code-mode - GitLite

KO | EN

gitlite — search

#html #security #php #proxy #gemini #ruby #api #agent #ai-agent #artificial-intelligence

code-mode

(★ 9)

A runtime-agnostic code-mode library for executing typed agent-authored code against host-provided tools over a bidirectional channel.

파일 탐색기

ZIP 다운로드

- - publish.yml
- benchmark-host-node-memory.mjs
- write-runner-source.mjs
- - abort.test.ts
  - abort.ts
  - agent-contract.test.ts
  - client.test.ts
  - client.ts
  - json.ts
  - runtime.test.ts
  - runtime.ts
  - telemetry.ts
  - transpile.ts
  - types.test.ts
  - types.ts
- - index.ts
  - runtime.test.ts
- - index.ts
  - node24.test.ts
  - node24.ts
- - index.test.ts
  - index.ts
  - source.ts
- - index.ts
- - index.ts
  - schema.ts
- index.ts
- package.test.ts
.gitignore
AGENTS.md
package-lock.json
package.json
playground.ts
README.md
tsconfig.build.json
tsconfig.json
VISION.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Run agent-authored TypeScript ESM against host-controlled tools on a pluggable,
long-lived JavaScript runtime.

Code mode owns the complete program contract: whether per-execution input
exists, its type when declared, tool declarations, ordered typed results,
checking, TypeScript erasure, host-side schema validation, tool routing,
telemetry, and its internal wire protocol. Runtime drivers own where programs
execute, how modules resolve, how the runner is booted, and how strongly
execution can be isolated or cancelled.

## Install

```sh
npm install @torkbot/code-mode
```

The library requires Node.js 24 or newer on the host. Agent programs can run in
any environment with a conforming runtime driver.

## Quick start

```ts
import {
  createClient,
  createProgramContract,
  defineTool,
} from "@torkbot/code-mode";
import { createHostNodeRuntime } from "@torkbot/code-mode/host-node";

const contract = createProgramContract({
  inputSchema: WeatherRequested,
  tools: [
    defineTool(
      "getWeather",
      {
        description: "Get weather for a location.",
        inputSchema: WeatherInput,
        outputSchema: WeatherReport,
      },
      async ({ signal }, input) => {
        signal.throwIfAborted();
        return weatherService.get(input.location, { signal });
      },
    ),
  ],
});

const runtime = await createHostNodeRuntime(
  {
    nodePath: process.execPath,
    cwd: process.cwd(),
  },
  AbortSignal.timeout(5_000),
);

try {
  const client = createClient({ runtime, contract });
  const source = `
export default async function ({ input, codemode, console, result }: AgentProgramScope) {
  console.info("Loading weather for", input.location);
  const weather = await codemode.getWeather({ location: input.location });
  result.appendText(JSON.stringify(weather));
}
`.trimStart();

const validation = await client.validate(
    source,
    AbortSignal.timeout(5_000),
  );
  if (validation.kind === "invalid") {
    throw new Error(validation.report);
  }

const outcome = await client.run(source, {
    input: {
      type: "weather.requested",
      location: "London",
    },
    signal: AbortSignal.timeout(30_000),
    onTelemetry(event) {
      if (event.kind === "program-output") {
        process[event.stream].write(event.text);
      }
    },
  });
  if (outcome.kind === "success") {
    deliverToolResult(outcome.content);
  }
} finally {
  await runtime[Symbol.asyncDispose]();
}
```

`createHostNodeRuntime()` starts one Node.js process and returns after its runner
is ready. Every subsequent `client.run()` is an execution request on that live
connection. Dispose the runtime when its owner is done with it.

## Program contract

A program contract has one of two explicit forms:

```ts
const inputless = createProgramContract({
  tools,
});

const inputBearing = createProgramContract({
  inputSchema: EventInput,
  tools,
});
```

`inputSchema` is not an optional value with a fallback. Its presence selects an
input-bearing contract; its absence selects an inputless contract. Accordingly,
`client.run(source, { signal })` is the complete inputless execution call, while
an input-bearing client requires
`client.run(source, { input: schemaInput, signal })`.

A submitted program is a real ECMAScript module. It may use static imports and
must have a callable default export assignable to its generated contract. An
input-bearing contract generates:

```ts
interface AgentProgramScope {
  readonly input: {
    readonly type: "weather.requested";
    readonly location: string;
  };
  readonly codemode: Tools;
  readonly console: CodeModeConsole;
  readonly result: CodeModeResult;
}

type AgentProgram = (scope: AgentProgramScope) => unknown;
```

An inputless contract instead generates:

```ts
interface AgentProgramScope {
  readonly codemode: Tools;
  readonly console: CodeModeConsole;
  readonly result: CodeModeResult;
}
```

The runner evaluates a fresh root module for every execution. It calls the
default export with `{ input, codemode, console, result }` for an input-bearing
execution and `{ codemode, console, result }` for an inputless execution, awaits
it, and ignores its fulfilled value. Declared `input` is the host-validated,
transformed value for that execution. There is no continuity between root
modules; a runtime may still use its platform's normal cache for imported
dependencies.

Every execution receives a result writer:

```ts
interface CodeModeResult {
  appendImage(image: {
    readonly data: string;
    readonly mimeType: string;
  }): void;
  appendText(text: string): void;
}
```

Calls append semantic content in call order. `appendImage()` accepts base64
image bytes and their media type. Arguments are validated and copied when
appended, so later mutation cannot change the result. A fulfilled program
returns the complete buffer:

```ts
type ProgramContent =
  | { readonly type: "text"; readonly text: string }
  | {
      readonly type: "image";
      readonly data: string;
      readonly mimeType: string;
    };
```

A program that appends nothing succeeds with `content: []`. If evaluation or
the default export fails, its buffered content is discarded. Result content is
therefore terminal and transactional; it is not a live telemetry stream.

Only the `console` passed in `AgentProgramScope` is captured as diagnostic
output. Calls to an ambient global console or an imported console are outside
the runtime contract. Console calls never append semantic result content. The
captured console has this minimum surface:

```ts
interface CodeModeConsole {
  debug(...values: unknown[]): void;
  error(...values: unknown[]): void;
  info(...values: unknown[]): void;
  log(...values: unknown[]): void;
  warn(...values: unknown[]): void;
}
```

Runtimes format console arguments. Code mode only promises text chunks and
their provenance:

```ts
type ProgramOutput = {
  readonly stream: "stdout" | "stderr";
  readonly text: string;
};
```

The consumer is expected to interpret text. There is no structured-value,
circular-reference, or console-formatting contract.

`validate()` checks the submitted module itself. `run()` uses Amaro's strip-only
transform to erase TypeScript in place, with no parser-owned wrapper and no
prepended source. Runtime stacks therefore retain submitted line and column
coordinates.

## Schemas, tools, and checking

A declared program input schema and every tool input/output schema implement
both `StandardSchemaV1` and `StandardJSONSchemaV1`:

```ts
type CodeModeSchema<Input, Output> =
  & StandardSchemaV1<Input, Output>
  & StandardJSONSchemaV1<Input, Output>;
```

Standard Schema validates and transforms values on the host. Standard JSON
Schema generates exact agent-facing declarations. Transforming schemas have
six distinct type positions:

| Boundary | Type |
| --- | --- |
| Host supplies program input | `SchemaInput<ProgramInputSchema>` |
| Program receives validated input | `SchemaOutput<ProgramInputSchema>` |
| Program supplies tool input | `SchemaInput<InputSchema>` |
| Handler receives validated input | `SchemaOutput<InputSchema>` |
| Handler returns an output candidate | `SchemaInput<OutputSchema>` |
| Program receives validated output | `SchemaOutput<OutputSchema>` |

Tool names must be unique JavaScript identifiers. `then` and the inherited
`Object` property names are reserved. Descriptions must be non-empty because
they become user-facing JSDoc in generated declarations.

The declaration printer supports closed objects, arrays, strings, numbers,
integers, booleans, and null. String schemas may use `const` to emit a string
literal type. Object schemas must explicitly set `additionalProperties: false`.

`anyOf` and `oneOf` support one deliberately narrow form: at least two closed
object branches must share a required string-`const` property, and each branch
must give that property a distinct value. The result is emitted as a
discriminated TypeScript union. The distinct required values also make the
branches mutually exclusive, so a TypeScript union preserves `oneOf` semantics.
Other composition shapes and unsupported schema keywords fail instead of being
represented loosely.

`contract.typeDefinitions` contains the complete program declaration surface:
the input declaration when one exists, tools, console, and default-export
contract. Program input declarations use the schema's output JSON Schema
because that is the value supplied after host validation.
`Runtime.loadTypeDefinitionFiles()` supplies checker-only declarations for the
execution environment. Those files are mounted in an in-memory TypeScript
project and are never sent as part of an execution request.

This remains honest for contracts built dynamically. Host TypeScript may know a
ledger-built schema only as `CodeModeSchema<unknown, unknown>`, while its
concrete output JSON Schema still generates a strong discriminated union for
the submitted program.

`validate()` has no runtime side effects. `run()` does not implicitly typecheck.
For an input-bearing contract, it validates and transforms program input before
submitting an execution; invalid or non-JSON transformed input never reaches
the runtime. Inputless contracts perform no input validation and submit no
input field. Tool inputs and outputs are also validated on the host. Non-JSON
tool values fail that program without closing the shared runtime.

## Outcomes, cancellation, and telemetry

```ts
type RunOutcome =
  | {
      readonly kind: "success";
      readonly content: ProgramContent[];
    }
  | {
      readonly kind: "program-failed";
      readonly error: TelemetryError;
    };
```

Module evaluation errors, a non-callable default export, thrown or rejected
programs, invalid dynamically supplied result content, unknown tools, handler
failures, and tool schema failures resolve as `program-failed`. The default
export's fulfilled value never affects the outcome. Transport failures and
execution cancellation reject the promise.
For an input-bearing contract, invalid host-supplied program input also rejects:
it is an embedder failure, not a failure caused by the submitted program. Its
`execution-failed` telemetry has `program-input-validation` details with a
bounded schema report.

An execution signal governs only that execution and its active tool handlers.
It does not close the runtime or cancel other multiplexed executions.

Telemetry reports:

- `program-output` with `stream` and `text`;
- tool call start, completion, and failure;
- terminal execution completion or infrastructure failure.

The terminal `execution-completed` event carries a clone of the same outcome,
including successful content. Telemetry callbacks are observational. Their
throws and rejected promises do not alter program execution.

## Runtime lifecycle

The public runtime used by a client is already connected:

```ts
interface Runtime extends AsyncDisposable {
  readonly description: string;
  readonly finished: Promise<RuntimeFinished>;

loadTypeDefinitionFiles(
    signal: AbortSignal,
  ): Promise<readonly TypeDefinitionFile[]>;

execute(request: RuntimeExecuteRequest): Promise<RunOutcome>;

[Symbol.asyncDispose](): Promise<void>;
}
```

`RuntimeExecuteRequest` has input-bearing and inputless forms. The former
requires a host-validated, JSON-compatible `input`; the latter forbids the
property. The wire message and runner scope preserve that distinction rather
than representing absence as `undefined`, `null`, or `{}`.

`description` is opaque environment context an embedder may present to an
agent. `finished` always resolves when the runtime becomes unusable: `closed`
for an orderly end, or `failed` with the underlying error. Async disposal closes
the connection and waits for driver-owned resources to stop.

Scheduling belongs to the driver. Clients always receive promises; a driver may
serialize them. The built-in Host Node driver is fully multiplexed.

## Authoring a runtime driver

Driver authors use `@torkbot/code-mode/runtime`:

```ts
interface RuntimeDriver<Options> {
  readonly description: string;

loadTypeDefinitionFiles(
    signal: AbortSignal,
  ): Promise<readonly TypeDefinitionFile[]>;

connect(
    options: Options,
    request: {
      readonly runnerSource: string;
      readonly signal: AbortSignal;
    },
  ): Promise<RuntimeConnection>;
}

interface RuntimeConnection extends AsyncDisposable {
  readonly channel: {
    readonly readable: ReadableStream<Uint8Array>;
    readonly writable: WritableStream<Uint8Array>;
  };
  readonly finished: Promise<RuntimeFinished>;
  [Symbol.asyncDispose](): Promise<void>;
}
```

Expose a user-facing factory by closing over the driver:

```ts
import { createRuntimeFactory } from "@torkbot/code-mode/runtime";

const driver: RuntimeDriver<MyOptions> = {
  description: "My runtime",
  loadTypeDefinitionFiles,
  connect,
};

export const createMyRuntime = createRuntimeFactory(driver);
```

The factory owns the version-matched runner, readiness handshake, internal
execution IDs, wire protocol, and failed-boot cleanup. Its signal governs boot
through readiness and then detaches. The caller that creates the runtime owns
its later lifetime.

`connect()` boots the execution environment, wires one runner to the returned
byte channel, and returns the connection. The driver can use any process,
isolate, VM, worker, socket, provider API, or in-memory transport. Agent source,
tool calls, output, outcomes, cancellation, and opaque correlation are carried
by execution requests after boot; they are not driver options.

The byte framing and messages are internal to this package. Drivers transport
bytes; they do not reproduce or interpret the protocol.

### Bootstrapping the runner

Platforms that can preinstall the package use the normal ESM export:

```ts
import { startRunner } from "@torkbot/code-mode/runner";

await startRunner({
  channel,
  schedule: (execute) => execute(),
  importModule: ({ source, signal }) => importFreshRoot(source, signal),
  createConsole: (emit) => createPlatformConsole(emit),
});
```

Some runtimes cannot preinstall npm modules. Every `connect()` request therefore
also receives `runnerSource`: self-contained ESM source exporting the same
`startRunner()` implementation. A driver can evaluate or upload that source and
append only its platform glue. The equivalent artifact is exported from
`@torkbot/code-mode/runner/source` for driver tooling and inspection, but normal
runtime users never plumb it.

`schedule()` wraps the complete module-evaluation and default-export invocation.
Call its callback immediately to multiplex, or queue callbacks to serialize a
runtime. `importModule()` must evaluate each request as a fresh root ESM module
and use the target's native static-import resolution. Its signal provides
logical cancellation; runtimes with stronger interruption primitives can apply
them there. `createConsole()` must call `emit` with text plus `stdout` or
`stderr`.

### Authoring a Node.js 24 driver

Node.js 24 driver authors can reuse code-mode's version-matched declarations
and guest execution semantics without adopting the built-in Host Node process
lifecycle:

```ts
import {
  assertNode24Version,
  createNode24BootstrapSource,
  loadNode24TypeDefinitionFiles,
} from "@torkbot/code-mode/node-runtime";

const driver: RuntimeDriver<MyNodeOptions> = {
  description: "My Node.js 24 runtime",
  loadTypeDefinitionFiles: loadNode24TypeDefinitionFiles,
  async connect(options, { runnerSource, signal }) {
    const version = await readRuntimeNodeVersion(options, signal);
    assertNode24Version(version, "My Node runtime");

const bootstrapSource = createNode24BootstrapSource({
      runnerSource,
      channelFileDescriptor: 3,
    });
    return launchRuntimeNode(options, bootstrapSource, signal);
  },
};
```

The generated self-contained ESM attaches to the supplied full-duplex file
descriptor, multiplexes executions, evaluates fresh root modules with native
Node resolution from `process.cwd()`, and constructs the captured console with
`node:console`. The driver still owns how the source reaches Node, how the file
descriptor is connected, ambient stdio, boot cancellation, and process
lifecycle. This keeps Host Node, Sandbox Node, and other Node substrates aligned
without importing each other's launch mechanics.

## Built-in Host Node driver

```ts
import { createHostNodeRuntime } from "@torkbot/code-mode/host-node";

const runtime = await createHostNodeRuntime(
  { nodePath: process.execPath, cwd: process.cwd() },
  bootSignal,
);
```

The driver requires Node.js 24. It starts one long-lived child process per
runtime, connects its runner over fd 3, and multiplexes executions. Programs use
native Node ESM resolution rooted at `cwd`, including ordinary ESM/CJS package
interop. The child constructs the captured console with `node:console`; its
ambient stdout, stderr, and global console are not program-output channels.

Host Node is not a sandbox. Use it for trusted programs and conformance tests.
Sandbox vendors and `@torkbot/code-mode-sandbox` should implement their own
driver while reusing the standard factory and the Node runtime authoring
surface where applicable.

Node retains each unique root module record in its module map until the runtime
process is disposed. Imported dependencies may also remain cached. Code mode
does not pretend to evict native module records or add process recycling policy;
runtime owners should choose a lifecycle appropriate to their workload. To
observe the retained-memory profile locally:

```sh
npm run benchmark:host-node-memory
```

The benchmark reports samples and does not impose a universal pass/fail limit.

## Runtime conformance

Every driver should run the exported black-box suite:

```ts
import { testRuntime } from "@torkbot/code-mode/testing";

testRuntime({
  name: "my runtime",
  createRuntime(signal) {
    return createMyRuntime(requiredOptions, signal);
  },
});
```

The suite creates and disposes arbitrary runtime instances. It exercises both
the public `Runtime` interface and the public client journey, including ordered
text/image results, rollback, result validation, and diagnostic separation,
without observing a driver, connection, process, or wire message.

## Breaking migration

The complete program contract replaces the tool-only primitive:

- replace `Toolbox` with `ProgramContract` and let the constructor infer its
  input form;
- replace `createToolbox(tools)` with `createProgramContract({ tools })`;
- add `inputSchema` only for a genuinely input-bearing program contract;
- replace `ToolSchema` with `CodeModeSchema`;
- pass `contract`, not `toolbox`, to `createClient()`;
- for input-bearing contracts, supply required `input` to `client.run()` and
  read required `input` in `AgentProgramScope`;
- for inputless contracts, do not pass `input`; it is absent from
  `AgentProgramScope`;
- append semantic output with `result.appendText()` and `result.appendImage()`;
- consume required `content` on successful `RunOutcome` values, including the
  empty array for programs that append nothing;
- runtime authors must preserve whether `RuntimeExecuteRequest.input` is present
  when invoking the default export, without wrapping or rewriting submitted
  source.