@yolk-sdk/codemode 0.1.0-canary.100

package/src/catalog.ts

@@ -0,0 +1,305 @@
+import { Predicate } from 'effect'
+import {
+  renderDeclarations,
+  renderToolOutputType,
+  renderToolSample,
+  toCodemodeIdentifier
+} from '@earendil-works/pi-codemode/declarations'
+import { toolDiscovery } from '@yolk-sdk/agent/protocol'
+import type { NestedTool } from '@yolk-sdk/agent/tools'
+import type { CodeModeJsonSchema } from './executor.ts'
+
+/** How a nested tool reaches scripts: `all` tools are also direct model tools; `listed` and
+ * `search` are the two discovery modes of `codemode`-only tools.
+ */
+export type CodeModeToolExposure = 'all' | 'listed' | 'search'
+
+/** One nested tool as scripts see it. */
+export type CodeModeCatalogTool = {
+  /** Raw tool name; scripts may call `tools["<name>"](args)`. */
+  readonly name: string
+  /** Identifier for `tools.<identifier>(args)` (invalid identifier characters become `_`). */
+  readonly identifier: string
+  /**
+   * How scripts call this tool, used to prefix its rejections: `tools.<identifier>`, or
+   * `tools["<name>"]` when an earlier tool already has the identifier (see `codeModeCallLabels`;
+   * when the name is taken too, the tool is unreachable and the label only names it).
+   */
+  readonly callLabel: string
+  /** The tool's `ToolModule.id`. */
+  readonly namespace: string
+  /** The module's `ToolModule.description`, when set. */
+  readonly namespaceDescription?: string
+  readonly description: string
+  readonly inputSchema: CodeModeJsonSchema
+  /** The declared output schema, or `{ type: 'string' }` for text results. */
+  readonly outputSchema: CodeModeJsonSchema
+  /** True when the tool declares an output schema (calls resolve to `structuredContent`). */
+  readonly structured: boolean
+  readonly exposure: CodeModeToolExposure
+}
+
+const textOutputSchema: CodeModeJsonSchema = { type: 'string' }
+
+/**
+ * The call label of each tool name, in order, as pi binds `tools`: each tool takes
+ * `tools[<identifier>]` unless an earlier tool holds that key (first tool wins), then
+ * `tools[<name>]` if still free. The label is `tools.<identifier>` for the tool that holds its
+ * identifier, otherwise `tools["<name>"]`. The executor guard and the host rejection prefix share
+ * it, so both name a call the same way.
+ */
+export const codeModeCallLabels = (names: ReadonlyArray<string>): ReadonlyArray<string> => {
+  const bound = new Set<string>()
+
+  return names.map(name => {
+    const identifier = toCodemodeIdentifier(name)
+    const ownsIdentifier = !bound.has(identifier)
+
+    bound.add(identifier)
+    bound.add(name)
+
+    return ownsIdentifier ? `tools.${identifier}` : `tools[${JSON.stringify(name)}]`
+  })
+}
+
+/** Catalog of nested tools in resolution order. */
+export const codeModeCatalog = (
+  tools: ReadonlyArray<NestedTool>
+): ReadonlyArray<CodeModeCatalogTool> => {
+  const labels = codeModeCallLabels(tools.map(({ def }) => def.name))
+
+  return tools.map(({ def, moduleId, moduleDescription }, index) => {
+    const tool: CodeModeCatalogTool = {
+      name: def.name,
+      identifier: toCodemodeIdentifier(def.name),
+      callLabel: labels[index] ?? `tools[${JSON.stringify(def.name)}]`,
+      namespace: moduleId,
+      description: def.description,
+      inputSchema: def.parameters,
+      outputSchema: def.outputSchema ?? textOutputSchema,
+      structured: def.outputSchema !== undefined,
+      exposure: toolDiscovery(def) ?? 'all'
+    }
+
+    return moduleDescription === undefined
+      ? tool
+      : { ...tool, namespaceDescription: moduleDescription }
+  })
+}
+
+/** Default inline budget of the nested tool listing, in estimated tokens. */
+export const defaultCodeModeInlineBudget = 3000
+
+/** Estimated tokens of a text: four characters per token, rounded up. */
+export const estimateCodeModeTokens = (text: string): number => Math.ceil(text.length / 4)
+
+const maxShortTypeChars = 60
+
+const shortType = (schema: CodeModeJsonSchema): string => {
+  const rendered = renderToolOutputType(schema)
+
+  if (rendered.length <= maxShortTypeChars) return rendered
+
+  if (!Predicate.isBoolean(schema)) {
+    if (schema.type === 'array') return 'Array<unknown>'
+
+    if (schema.type === 'object') return 'object'
+  }
+
+  return 'unknown'
+}
+
+// Declarations only read names, descriptions, and schemas; `execute` is never called.
+const declarationTool = (tool: CodeModeCatalogTool) => ({
+  name: tool.name,
+  description: tool.description,
+  inputSchema: tool.inputSchema,
+  outputSchema: tool.outputSchema,
+  execute: () => undefined
+})
+
+const directToolLine = (tool: CodeModeCatalogTool) =>
+  `- \`tools.${tool.identifier}(args)\` takes the arguments of the \`${tool.name}\` tool and resolves to \`${shortType(tool.outputSchema)}\`.`
+
+const declarationMembers = (tools: ReadonlyArray<CodeModeCatalogTool>) =>
+  renderDeclarations({ tools: tools.map(declarationTool) })
+
+type Candidate = {
+  readonly tool: CodeModeCatalogTool
+  readonly index: number
+  readonly cost: number
+}
+
+const candidateCost = (tool: CodeModeCatalogTool) =>
+  estimateCodeModeTokens(declarationMembers([tool]))
+
+const groupByNamespace = <A extends { readonly tool: CodeModeCatalogTool }>(
+  items: ReadonlyArray<A>
+): ReadonlyMap<string, ReadonlyArray<A>> => {
+  const groups = new Map<string, Array<A>>()
+
+  for (const item of items) {
+    const group = groups.get(item.tool.namespace)
+
+    if (group === undefined) {
+      groups.set(item.tool.namespace, [item])
+    } else {
+      group.push(item)
+    }
+  }
+
+  return groups
+}
+
+export type CodeModeListing = {
+  /** Tools placed in the description, in catalog order: every `all` tool, and the `listed` tools
+   * that fit the budget.
+   */
+  readonly listed: ReadonlyArray<CodeModeCatalogTool>
+  /** Namespaces (catalog order) with callable tools the description does not list. */
+  readonly unlistedNamespaces: ReadonlyArray<string>
+}
+
+/**
+ * Chooses the tools the description lists. `all` tools are always placed, outside the budget
+ * (the model already has their declarations). `listed` tools fill `budget` estimated tokens fairly
+ * across namespaces: each round, every namespace still in play places its cheapest remaining tool;
+ * a namespace whose next tool does not fit drops out. `search` tools are never candidates.
+ */
+export const selectCodeModeListing = (
+  catalog: ReadonlyArray<CodeModeCatalogTool>,
+  budget: number
+): CodeModeListing => {
+  const candidates = catalog.flatMap((tool, index): ReadonlyArray<Candidate> =>
+    tool.exposure === 'listed' ? [{ tool, index, cost: candidateCost(tool) }] : []
+  )
+
+  const queues = new Map(
+    [...groupByNamespace(candidates)].map(([namespace, group]) => [
+      namespace,
+      [...group].sort((left, right) => left.cost - right.cost || left.index - right.index)
+    ])
+  )
+
+  const placed = new Set(catalog.flatMap((tool, index) => (tool.exposure === 'all' ? [index] : [])))
+
+  const inPlay = new Set(queues.keys())
+  let remaining = budget
+
+  while (inPlay.size > 0) {
+    for (const [namespace, queue] of queues) {
+      if (!inPlay.has(namespace)) continue
+
+      const next = queue.shift()
+
+      if (next === undefined || next.cost > remaining) {
+        inPlay.delete(namespace)
+        continue
+      }
+
+      placed.add(next.index)
+      remaining -= next.cost
+    }
+  }
+
+  const unlisted = new Set(
+    catalog.flatMap((tool, index) => (placed.has(index) ? [] : [tool.namespace]))
+  )
+
+  return {
+    listed: catalog.filter((_, index) => placed.has(index)),
+    unlistedNamespaces: [...new Set(catalog.map(tool => tool.namespace))].filter(namespace =>
+      unlisted.has(namespace)
+    )
+  }
+}
+
+const intro = [
+  'Run a JavaScript script that calls tools and returns only what matters.',
+  '`code` is the body of an async function: top-level `await` and `return` work. Write plain JavaScript; simple TypeScript annotations are stripped. There is no Node.js, network, filesystem, `require`, `fetch`, or timers.',
+  'Call tools as `await tools.<id>(args)`. Arguments must be plain JSON (no `NaN`, `undefined` array items, `Map`, or functions). A call resolves to the declared result type and rejects with an Error whose message starts with `tools.<id>:` when the tool fails. Calls still running when the script ends are cancelled, so await every call (use `Promise.all` for parallel calls).',
+  'Only the script output and its return value come back to you: filter and aggregate inside the script and return a small JSON value.'
+].join('\n')
+
+const globalLines = (store: boolean) => [
+  '- `text(value)` and `console.log(...values)`: append text to the output.',
+  '- `image(dataUrl)`: append a base64 image (a `data:` URL or `{ type: "image", data, mimeType }`).',
+  '- `exit()`: end the script successfully.',
+  '- `ALL_TOOLS`: `{ name, description }` of every callable tool.',
+  '- `await searchTools(query, { limit?, namespace? })`: find tools by topic; resolves to `Array<{ name: string; description: string }>` (default limit 8).',
+  '- `await describeTool(name)`: the description and TypeScript declaration of a tool, or `undefined`.',
+  '- `await describeNamespace(name)`: `{ name, description?, tools: Array<{ name, description }> }` for a namespace, or `undefined`.',
+  ...(store
+    ? [
+        '- `store(key, value)` and `load(key)`: keep small JSON values for later scripts; writes are saved only when the script succeeds.'
+      ]
+    : [])
+]
+
+const namespaceSection = (namespace: string, tools: ReadonlyArray<CodeModeCatalogTool>) => {
+  const declared = tools.filter(tool => tool.exposure !== 'all')
+  const direct = tools.filter(tool => tool.exposure === 'all')
+
+  const description = tools.find(
+    tool => tool.namespaceDescription !== undefined
+  )?.namespaceDescription
+
+  return [
+    `### ${namespace}`,
+    ...(description === undefined ? [] : [description]),
+    ...(declared.length > 0 ? ['```ts', declarationMembers(declared), '```'] : []),
+    ...direct.map(directToolLine)
+  ].join('\n')
+}
+
+// Fixed text: never derived from `search` tools or from which tools did not fit the budget.
+const unlistedToolsLine =
+  'More tools may be callable than are listed here: find them with `await searchTools(query, { namespace? })` and read one with `await describeTool(name)` or `await describeNamespace(name)` before calling it.'
+
+export type CodeModeDescriptionInput = {
+  readonly tools: ReadonlyArray<NestedTool>
+  readonly inlineBudget?: number
+  /** Mention `store()`/`load()` persistence. */
+  readonly store?: boolean
+}
+
+/**
+ * The code mode tool description: intro, globals one per line, then nested tools grouped by
+ * namespace, then one fixed line pointing to `searchTools`/`describeTool`/`describeNamespace`.
+ * `all` tools get one line each outside the budget; `listed` tools are declared within the inline
+ * budget; `search` tools never contribute, so adding or removing them (even whole namespaces of
+ * them) leaves the text byte-identical.
+ */
+export const renderCodeModeDescription = (input: CodeModeDescriptionInput): string => {
+  const catalog = codeModeCatalog(input.tools)
+
+  const listing = selectCodeModeListing(catalog, input.inlineBudget ?? defaultCodeModeInlineBudget)
+
+  const sections = [...groupByNamespace(listing.listed.map(tool => ({ tool })))].map(
+    ([namespace, items]) =>
+      namespaceSection(
+        namespace,
+        items.map(item => item.tool)
+      )
+  )
+
+  return [
+    intro,
+    ['Globals:', ...globalLines(input.store === true)].join('\n'),
+    sections.length === 0
+      ? 'Nested tools: none are listed here.'
+      : ['## Nested tools by namespace', ...sections].join('\n\n'),
+    unlistedToolsLine
+  ].join('\n\n')
+}
+
+/** `describeTool` text: the description and TypeScript declaration of one tool. */
+export const describeCodeModeTool = (tool: CodeModeCatalogTool): string =>
+  renderToolSample(declarationTool(tool))
+
+/** Finds a tool by identifier or raw name. */
+export const findCodeModeTool = (
+  catalog: ReadonlyArray<CodeModeCatalogTool>,
+  name: string
+): CodeModeCatalogTool | undefined =>
+  catalog.find(tool => tool.identifier === name) ?? catalog.find(tool => tool.name === name)

package/src/classifier-tool.ts

@@ -0,0 +1,227 @@
+import { Effect, Predicate, Semaphore } from 'effect'
+import * as Schema from 'effect/Schema'
+import {
+  ClassificationResult,
+  ClassifierQuestions,
+  ClassifierState,
+  type ClassificationError,
+  type ClassificationRequest,
+  type ClassificationUsage,
+  type ClassifierModel
+} from '@yolk-sdk/agent/classification'
+import {
+  AgentInputUsage,
+  AgentOutputUsage,
+  AgentUsage,
+  ToolResult,
+  type ToolCall
+} from '@yolk-sdk/agent/protocol'
+import {
+  makeTool,
+  modelVisibleToolError,
+  modelVisibleToolErrorStructuredContent,
+  type ModelVisibleToolErrorReason,
+  type ToolRegistration
+} from '@yolk-sdk/agent/tools'
+
+/** Default name of the classifier tool. */
+export const classifierToolName = 'classify'
+
+/** Default cap of concurrent classifications per script. */
+export const defaultClassifierToolMaxConcurrency = 100
+
+/** Default cap of concurrent classifications per process, across scripts and registrations. */
+export const defaultClassifierProcessMaxConcurrency = 200
+
+/** A concurrency cap shared by every classifier tool registration that uses it. */
+export type ClassifierConcurrencyLimiter = {
+  /** Maximum concurrent classifications. */
+  readonly max: number
+  /** Runs `effect` holding one permit. Waiting is interruptible and never leaks a permit; the
+   * permit is released when `effect` ends, however it ends.
+   */
+  readonly withPermit: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+}
+
+const permitCount = (max: number) => Math.max(1, Math.floor(max))
+
+/** A classifier concurrency limiter allowing `max` (at least 1) classifications at once. */
+export const makeClassifierConcurrencyLimiter = (max: number): ClassifierConcurrencyLimiter => {
+  const permits = permitCount(max)
+  const semaphore = Semaphore.makeUnsafe(permits)
+
+  return { max: permits, withPermit: effect => semaphore.withPermits(1)(effect) }
+}
+
+/** The process-wide limiter every classifier tool uses unless given `processLimiter`. Default
+ * 200 concurrent classifications (200 concurrent AI Gateway classifications finished in about
+ * 1.2 s without rate-limit errors in a live probe).
+ */
+export const defaultClassifierProcessLimiter = makeClassifierConcurrencyLimiter(
+  defaultClassifierProcessMaxConcurrency
+)
+
+type ClassifierModelService = (typeof ClassifierModel)['Service']
+
+type Classify = ClassifierModelService['classify']
+
+export type MakeClassifierToolOptions = {
+  /** `ClassifierModel`'s `classify`, or the service value itself. */
+  readonly classify: Classify | ClassifierModelService
+  /** Default `classify`. */
+  readonly name?: string
+  /** Concurrent classifications per script (keyed by the parent tool call id of the nested call
+   * id `<parentToolCallId>/<seq>`, or the call id itself); default 100.
+   */
+  readonly maxConcurrency?: number
+  /** Limiter shared across scripts and registrations; default `defaultClassifierProcessLimiter`
+   * (200 per process). `false` disables the process cap (the per-script cap still applies).
+   */
+  readonly processLimiter?: ClassifierConcurrencyLimiter | false
+  readonly description?: string
+}
+
+/** The classifier tool's input: one state and its named questions. Provider options stay
+ * host-owned and are never taken from scripts.
+ */
+export const ClassifierToolParams = Schema.Struct({
+  state: ClassifierState,
+  questions: ClassifierQuestions
+})
+
+const defaultDescription = (maxConcurrency: number) =>
+  [
+    'Classify one item with a classifier model: answer named typed questions about one `state` (a string, JSON object, or JSON array) with probabilities.',
+    'Question types: `boolean` (`probability` of true), `choice` (one of the `criteria` keys, with `probabilities`), and `score` (an ordinal level from the `criteria` list, lowest first).',
+    `Call it once per item; at most ${maxConcurrency} classifications of one script run at once and further calls queue.`
+  ].join(' ')
+
+/** Token usage of a classification as agent usage. `costUsd` has no agent usage field; it stays
+ * in the result's `structuredContent.usage`, so nested-call records carry token usage only.
+ */
+const agentUsage = (usage: ClassificationUsage): AgentUsage =>
+  AgentUsage.make({
+    input: AgentInputUsage.make({ total: usage.inputTokens }),
+    output: AgentOutputUsage.make({ total: usage.outputTokens })
+  })
+
+const errorReason = (error: ClassificationError): ModelVisibleToolErrorReason =>
+  Predicate.isTagged(error, 'ClassificationRequestInvalid') ? 'invalid_input' : 'unavailable'
+
+const billedUsage = (error: ClassificationError) =>
+  Predicate.isTagged(error, 'ClassificationResponseInvalid') ? error.usage : undefined
+
+/** The parent tool call id of a nested call id `<parentToolCallId>/<seq>`, else the id itself. */
+const scriptKey = (call: ToolCall) => {
+  const separator = call.id.lastIndexOf('/')
+
+  return separator > 0 ? call.id.slice(0, separator) : call.id
+}
+
+type ResultFields = {
+  toolCallId: string
+  content: string
+  isError?: boolean
+  structuredContent: unknown
+  usage?: AgentUsage
+}
+
+const withUsage = (fields: ResultFields, usage: ClassificationUsage | undefined) => {
+  if (usage !== undefined) {
+    fields.usage = agentUsage(usage)
+  }
+
+  return ToolResult.make(fields)
+}
+
+const successResult = (call: ToolCall, result: ClassificationResult) =>
+  withUsage(
+    { toolCallId: call.id, content: JSON.stringify(result.answers), structuredContent: result },
+    result.usage
+  )
+
+const errorResult = (call: ToolCall, name: string, error: ClassificationError) =>
+  withUsage(
+    {
+      toolCallId: call.id,
+      content: error.message,
+      isError: true,
+      structuredContent: modelVisibleToolErrorStructuredContent(
+        modelVisibleToolError({ tool: name, reason: errorReason(error), message: error.message })
+      )
+    },
+    billedUsage(error)
+  )
+
+/**
+ * A code-mode-only (`callableBy: 'codemode'`, `discovery: 'listed'`) read tool that classifies one
+ * item per call with a classifier model. Its content is the compact JSON of the answers, its
+ * `structuredContent` the full `ClassificationResult` (which nested calls resolve to), and its
+ * token usage is reported on `ToolResult.usage`. Classifier errors become model-visible error
+ * results; usage billed before a response error is kept.
+ *
+ * Each call takes a per-script permit (`maxConcurrency`) and then a process permit
+ * (`processLimiter`), so one script's queue never holds process permits it cannot use.
+ */
+export const makeClassifierTool = <Context>(
+  options: MakeClassifierToolOptions
+): ToolRegistration<Context> => {
+  const name = options.name ?? classifierToolName
+
+  const maxConcurrency = permitCount(options.maxConcurrency ?? defaultClassifierToolMaxConcurrency)
+
+  const processLimiter =
+    options.processLimiter === undefined ? defaultClassifierProcessLimiter : options.processLimiter
+
+  const withProcessPermit = <A, E>(effect: Effect.Effect<A, E>) =>
+    processLimiter === false ? effect : processLimiter.withPermit(effect)
+
+  const classify = Predicate.isFunction(options.classify)
+    ? options.classify
+    : options.classify.classify
+
+  // One semaphore per script (parent tool call), removed when its last classification ends.
+  const scripts = new Map<string, { readonly semaphore: Semaphore.Semaphore; users: number }>()
+
+  const withScriptPermit = <A, E>(call: ToolCall, effect: Effect.Effect<A, E>) =>
+    Effect.acquireUseRelease(
+      Effect.sync(() => {
+        const key = scriptKey(call)
+
+        const entry = scripts.get(key) ?? {
+          semaphore: Semaphore.makeUnsafe(maxConcurrency),
+          users: 0
+        }
+
+        entry.users++
+        scripts.set(key, entry)
+
+        return { key, entry }
+      }),
+      ({ entry }) => entry.semaphore.withPermits(1)(withProcessPermit(effect)),
+      ({ key, entry }) =>
+        Effect.sync(() => {
+          entry.users--
+
+          if (entry.users === 0 && scripts.get(key) === entry) scripts.delete(key)
+        })
+    )
+
+  return makeTool<Context, typeof ClassifierToolParams>({
+    name,
+    description: options.description ?? defaultDescription(maxConcurrency),
+    parameters: ClassifierToolParams,
+    output: ClassificationResult,
+    access: 'read',
+    callableBy: 'codemode',
+    discovery: 'listed',
+    execute: ({ call, params }) => {
+      const request: ClassificationRequest = { state: params.state, questions: params.questions }
+
+      return withScriptPermit(call, classify(request)).pipe(
+        Effect.map(result => successResult(call, result)),
+        Effect.catch(error => Effect.succeed(errorResult(call, name, error)))
+      )
+    }
+  })
+}

package/src/executor.ts

@@ -0,0 +1,122 @@
+import type * as Schema from 'effect/Schema'
+import type { ToolJsonSchema } from '@yolk-sdk/agent/protocol'
+
+/** A JSON Schema document. Only shapes declarations; values are never validated against it. */
+export type CodeModeJsonSchema = ToolJsonSchema
+
+/** Store contents: small JSON values by key. */
+export type CodeModeStore = Readonly<Record<string, Schema.Json>>
+
+export type CodeModeToolContext = {
+  /** Aborted when the script ends (unawaited calls), times out, or the execution is aborted. */
+  readonly signal: AbortSignal
+}
+
+/**
+ * A function a script can call. Tools are called as `tools.<identifier>(args)` and
+ * `tools["<name>"](args)`; the identifier replaces characters that are not valid in a JavaScript
+ * identifier with `_`. Arguments and results make a JSON round trip; a rejection surfaces in the
+ * script as an `Error` with the same message (`makeCodeModeTool` rejects with
+ * `<call label>: <message>`, the label being `tools.<identifier>` or `tools["<name>"]`).
+ *
+ * `args` is the JSON value of the script's first argument (`undefined` when there is none), read
+ * once the way `JSON.stringify` reads it (getters and `toJSON` run once); the checked value is the
+ * one sent. Executors reject, inside the script and without calling `execute`, values that JSON
+ * would silently change instead of coercing them: non-finite numbers, invalid `Date`s,
+ * `undefined`/function/symbol array items and holes, function/symbol/bigint values, cycles, and
+ * non-plain objects without `toJSON` (`Map`, `Set`, `RegExp`, `Error`, class instances), including
+ * inside `toJSON` results. `undefined`-valued object keys count as absent, as JSON drops them; a
+ * valid `Date` passes as its ISO string. An argument too large or deep to check completely is
+ * rejected, never sent unchecked (the pi executor: more than 100000 values or 64 levels). A
+ * rejection names the call the way scripts reach it, as `makeCodeModeTool` does: the first tool
+ * with an identifier is `tools.<identifier>`, a later one `tools["<name>"]`.
+ */
+export type CodeModeExecutorTool = {
+  readonly name: string
+  readonly description?: string
+  readonly inputSchema?: CodeModeJsonSchema
+  readonly outputSchema?: CodeModeJsonSchema
+  /** Diagnostic call label for rejection messages: `tools.<identifier>`, or `tools["<name>"]`
+   * when an earlier tool holds the identifier (a tool whose name is taken too is unreachable and
+   * the label only names it). `makeCodeModeTool` sets it; executors fall back to pi's binding rule.
+   */
+  readonly callLabel?: string
+  readonly execute: (args: unknown, context: CodeModeToolContext) => Promise<unknown>
+}
+
+/**
+ * A top-level function (`name`) or namespace member (`namespace.member`) for scripts. Globals are
+ * host helpers: they are not tools and are not recorded as nested calls.
+ */
+export type CodeModeExecutorGlobal = Omit<CodeModeExecutorTool, 'callLabel'> & {
+  /** `execute` receives every call argument as an array instead of the first one. */
+  readonly spread?: boolean
+  /** TypeScript parameter list and return type for declarations. */
+  readonly signature?: string
+}
+
+/** One item of script output, in the order the script produced it. `data` is base64. */
+export type CodeModeOutputItem =
+  | { readonly type: 'text'; readonly text: string }
+  | { readonly type: 'image'; readonly data: string; readonly mimeType: string }
+
+/**
+ * - `script`: the script threw, failed to parse, or its TypeScript could not be stripped.
+ * - `timeout`: the deadline expired.
+ * - `aborted`: the caller's signal fired.
+ * - `sandbox`: the engine failed outside the script's control.
+ */
+export type CodeModeErrorKind = 'script' | 'timeout' | 'aborted' | 'sandbox'
+
+export type CodeModeError = {
+  readonly kind: CodeModeErrorKind
+  readonly message: string
+  readonly stack?: string
+}
+
+/** Keys a successful script changed with `store()`; `delete` lists keys stored as `undefined`. */
+export type CodeModeStoreWrites = {
+  readonly set: CodeModeStore
+  readonly delete: ReadonlyArray<string>
+}
+
+export type CodeModeExecutionResult = {
+  readonly ok: boolean
+  /** The script's return value (JSON); absent when it returned nothing. */
+  readonly value?: unknown
+  readonly error?: CodeModeError
+  /** Kept for failed executions too, up to the failure. */
+  readonly output: ReadonlyArray<CodeModeOutputItem>
+  /** Only successful executions report writes. */
+  readonly storeWrites?: CodeModeStoreWrites
+}
+
+export type CodeModeExecuteOptions = {
+  readonly tools: ReadonlyArray<CodeModeExecutorTool>
+  readonly globals: ReadonlyArray<CodeModeExecutorGlobal>
+  /** Overall deadline, including time spent in tools and waiting for a free execution slot. */
+  readonly timeoutMs: number
+  /** Heap cap of the script's VM. */
+  readonly memoryLimitBytes: number
+  /** Values the script reads with `load(key)`. */
+  readonly store: CodeModeStore
+  readonly signal: AbortSignal
+}
+
+/**
+ * Runs one script. `code` is the body of an async function (top-level `await` and `return`) and
+ * may carry TypeScript annotations: executors strip them or report a `script` error. The promise
+ * resolves for every script outcome, including failures, timeouts, and aborts; a rejection is
+ * treated as a `sandbox` failure. Running tool calls must be cancelled through their signal when
+ * the script ends. Tool arguments follow the JSON rules of `CodeModeExecutorTool`: pass their JSON
+ * value and reject what JSON would silently change.
+ *
+ * `@yolk-sdk/codemode/node` provides `makePiCodeModeExecutor`; hosts on other runtimes supply their
+ * own engine behind this interface.
+ */
+export type CodeModeExecutor = {
+  readonly execute: (
+    code: string,
+    options: CodeModeExecuteOptions
+  ) => Promise<CodeModeExecutionResult>
+}