@devosurf/tesser-sdk 0.1.0-alpha.0

package/src/internal/manifest.ts

@@ -0,0 +1,398 @@
+// Static manifest extraction (ADR-0010 / 0012): the build reads an automation's or
+// connector's requirements WITHOUT executing handlers. Module evaluation is allowed;
+// `run` functions are never called. Powers deploy-halt, connect links, codegen, and CI.
+
+import type { AutomationDef, ConnectionMap, RetryPolicy, SecretMap } from "../automation.js";
+import type { HarnessDef } from "../harnesses.js";
+import type { ModelDef, ModelSettingsV1, OperatorDef } from "../operators.js";
+import type {
+  ActionsTree,
+  AnyAction,
+  ConnectorInstance,
+  ProviderFacts,
+  TriggersDecl,
+} from "../connector/index.js";
+import { isAction, isConnector } from "../connector/index.js";
+import type {
+  ConnectorTrigger,
+  EventTrigger,
+  ScheduleTrigger,
+  Trigger,
+  WebhookTrigger,
+} from "../triggers.js";
+import { encodeJournal, type JsonValue } from "./codec.js";
+import { actionAtPath, isRetrySafe } from "./client.js";
+
+export type TriggerManifest =
+  | { kind: "schedule"; cron: string; tz?: string }
+  | { kind: "webhook"; respond: "async" | "sync"; hasInputSchema: boolean }
+  | { kind: "event"; event: string }
+  | {
+      kind: "connector";
+      connector: string;
+      trigger: string;
+      params: JsonValue;
+      /** The `connections` key this trigger binds to (resolved here, ADR-0013). */
+      connection: string;
+      /** Author cadence override for poll triggers (clamped to the connector floor). */
+      every?: string;
+    };
+
+export interface AutomationManifest {
+  id: string;
+  trigger: TriggerManifest;
+  connections: Record<string, { connector: string; scope: "workspace" | "per_user" }>;
+  secrets: Record<string, { describe?: string }>;
+  models: Record<string, { connection: string; connector: string; alias: string; settings?: ModelSettingsV1 }>;
+  operators: Record<
+    string,
+    {
+      model: string;
+      instructions: string;
+      tools: Array<{ path: string; connection: string; action: string; safety: "read" | "write" }>;
+      maxTurns: number;
+    }
+  >;
+  harnesses: Record<
+    string,
+    {
+      connection: string;
+      connector: string;
+      sandbox: string;
+      permissions: string;
+      timeout?: string;
+      maxOutputBytes?: number;
+    }
+  >;
+  budget?: { models?: { tokens: number; outputTokens: number }; harnesses?: { invocations: number; wallClock?: string } };
+  retry?: RetryPolicy;
+  concurrency?: { limit: number; hasKey: boolean; onConflict: "queue" | "drop" };
+  hasInputSchema: boolean;
+  hasOutputSchema: boolean;
+}
+
+export class ManifestError extends TypeError {
+  constructor(
+    readonly automationId: string,
+    message: string,
+  ) {
+    super(`automation "${automationId}": ${message}`);
+    this.name = "ManifestError";
+  }
+}
+
+// `any` maps on purpose: Ctx is contravariant in `run`, so a concretely-typed def is not
+// assignable to AutomationDef<…, ConnectionMap, SecretMap>.
+export function extractAutomationManifest(
+  def: AutomationDef<any, any, any, any, any, any, any>,
+): AutomationManifest {
+  const connections: AutomationManifest["connections"] = {};
+  const connMap = (def.connections ?? {}) as ConnectionMap;
+  for (const [key, conn] of Object.entries(connMap)) {
+    connections[key] = { connector: conn.id, scope: conn.scope ?? "workspace" };
+  }
+  const secrets: AutomationManifest["secrets"] = {};
+  const secretMap = (def.secrets ?? {}) as SecretMap;
+  for (const [key, sec] of Object.entries(secretMap)) {
+    secrets[key] = sec.describe !== undefined ? { describe: sec.describe } : {};
+  }
+
+  let trigger: TriggerManifest;
+  const t = def.trigger as Trigger<unknown>;
+  switch (t.kind) {
+    case "schedule": {
+      const st = t as ScheduleTrigger;
+      trigger = { kind: "schedule", cron: st.cron, ...(st.tz !== undefined ? { tz: st.tz } : {}) };
+      break;
+    }
+    case "webhook": {
+      const wt = t as WebhookTrigger<unknown>;
+      trigger = { kind: "webhook", respond: wt.respond, hasInputSchema: wt.input !== undefined };
+      break;
+    }
+    case "event": {
+      const et = t as EventTrigger<unknown>;
+      trigger = { kind: "event", event: et.event.name };
+      break;
+    }
+    case "connector": {
+      const ct = t as ConnectorTrigger<unknown>;
+      // Connection binding (ADR-0013): explicit key, else auto-bind when exactly one
+      // connections entry uses this connector.
+      let key = ct.connectionKey;
+      if (key !== undefined) {
+        const bound = connections[key];
+        if (!bound) {
+          throw new ManifestError(def.id, `trigger names connection "${key}" but connections has no such entry`);
+        }
+        if (bound.connector !== ct.connectorId) {
+          throw new ManifestError(
+            def.id,
+            `trigger connection "${key}" is a ${bound.connector} connection, but the trigger belongs to ${ct.connectorId}`,
+          );
+        }
+      } else {
+        const candidates = Object.entries(connections).filter(([, c]) => c.connector === ct.connectorId);
+        if (candidates.length === 0) {
+          throw new ManifestError(
+            def.id,
+            `trigger ${ct.connectorId}.triggers.${ct.triggerId} requires a ${ct.connectorId} entry in connections`,
+          );
+        }
+        if (candidates.length > 1) {
+          throw new ManifestError(
+            def.id,
+            `trigger ${ct.connectorId}.triggers.${ct.triggerId} is ambiguous — name it: { connection: "<key>" } (candidates: ${candidates.map(([k]) => k).join(", ")})`,
+          );
+        }
+        key = (candidates[0] as [string, unknown])[0];
+      }
+      let params: JsonValue;
+      try {
+        params = encodeJournal(ct.params);
+      } catch (err) {
+        throw new ManifestError(def.id, `trigger params must be plain data: ${(err as Error).message}`);
+      }
+      trigger = {
+        kind: "connector",
+        connector: ct.connectorId,
+        trigger: ct.triggerId,
+        params,
+        connection: key,
+        ...(ct.every !== undefined ? { every: ct.every } : {}),
+      };
+      break;
+    }
+    default:
+      throw new ManifestError(def.id, `unknown trigger kind "${(t as { kind: string }).kind}"`);
+  }
+
+  const models: AutomationManifest["models"] = {};
+  const modelMap = (def.models ?? {}) as Record<string, ModelDef>;
+  for (const [key, m] of Object.entries(modelMap)) {
+    const conn = connections[m.connection];
+    if (!conn) {
+      throw new ManifestError(def.id, `models.${key} names connection "${m.connection}" but connections has no such entry`);
+    }
+    const connector = connMap[m.connection] as ConnectorInstance<any, any> | undefined;
+    if (!connector?.__connector.modelProvider) {
+      throw new ManifestError(def.id, `models.${key} uses connection "${m.connection}" but ${conn.connector} is not model-capable`);
+    }
+    models[key] = {
+      connection: m.connection,
+      connector: conn.connector,
+      alias: m.alias,
+      ...(m.settings !== undefined ? { settings: m.settings } : {}),
+    };
+  }
+
+  const operators: AutomationManifest["operators"] = {};
+  const operatorMap = (def.operators ?? {}) as Record<string, OperatorDef>;
+  for (const [key, op] of Object.entries(operatorMap)) {
+    if (!models[op.model]) {
+      throw new ManifestError(def.id, `operators.${key} references unknown model "${op.model}"`);
+    }
+    const tools: AutomationManifest["operators"][string]["tools"] = [];
+    for (const tool of op.tools) {
+      const [connKey, ...actionPath] = tool.split(".");
+      const conn = connections[connKey!];
+      if (!conn) {
+        throw new ManifestError(def.id, `operators.${key} tool "${tool}" names undeclared connection "${connKey}"`);
+      }
+      const connector = connMap[connKey!] as ConnectorInstance<any, any> | undefined;
+      const action = connector ? actionAtPath(connector, actionPath) : undefined;
+      if (!action) {
+        throw new ManifestError(def.id, `operators.${key} tool "${tool}" is not a declared Action`);
+      }
+      tools.push({ path: tool, connection: connKey!, action: actionPath.join("."), safety: action.safety });
+    }
+    operators[key] = { model: op.model, instructions: op.instructions, tools, maxTurns: op.maxTurns };
+  }
+  if (Object.keys(operators).length > 0 && !def.budget?.models) {
+    throw new ManifestError(def.id, `budget.models is required when operators are declared`);
+  }
+
+  const harnesses: AutomationManifest["harnesses"] = {};
+  const harnessMap = (def.harnesses ?? {}) as Record<string, HarnessDef>;
+  for (const [key, h] of Object.entries(harnessMap)) {
+    const conn = connections[h.connection];
+    if (!conn) {
+      throw new ManifestError(def.id, `harnesses.${key} names connection "${h.connection}" but connections has no such entry`);
+    }
+    const connector = connMap[h.connection] as ConnectorInstance<any, any> | undefined;
+    if (!connector?.__connector.harnessProvider) {
+      throw new ManifestError(def.id, `harnesses.${key} uses connection "${h.connection}" but ${conn.connector} is not harness-capable`);
+    }
+    harnesses[key] = {
+      connection: h.connection,
+      connector: conn.connector,
+      sandbox: h.sandbox,
+      permissions: h.permissions,
+      ...(h.timeout !== undefined ? { timeout: h.timeout } : {}),
+      ...(h.maxOutputBytes !== undefined ? { maxOutputBytes: h.maxOutputBytes } : {}),
+    };
+  }
+
+  return {
+    id: def.id,
+    trigger,
+    connections,
+    secrets,
+    models,
+    operators,
+    harnesses,
+    ...(def.budget !== undefined ? { budget: def.budget } : {}),
+    ...(def.retry !== undefined ? { retry: def.retry } : {}),
+    ...(def.concurrency !== undefined
+      ? {
+          concurrency: {
+            limit: def.concurrency.limit,
+            hasKey: typeof def.concurrency.key === "function",
+            onConflict: def.concurrency.onConflict ?? "queue",
+          },
+        }
+      : {}),
+    hasInputSchema: def.input !== undefined,
+    hasOutputSchema: def.output !== undefined,
+  };
+}
+
+// ---- Connector manifests (codegen + Catalog assembly, ADR-0012) ----
+
+export interface ConnectorManifest {
+  id: string;
+  describe?: string;
+  provider?: string;
+  providerFacts?: ProviderFacts;
+  baseUrl?: string;
+  auth: Record<
+    string,
+    | { kind: "oauth2"; provider?: string; scopes: string[]; flow: string; describe?: string }
+    | { kind: "apiKey"; in: string; name: string; prefix?: string; describe?: string }
+    | { kind: "basic"; describe?: string }
+    | { kind: "custom"; fields: string[]; describe?: string }
+  >;
+  idempotencyHeader?: string;
+  actions: Array<{ path: string; describe?: string; safety: "read" | "write"; retrySafe: boolean }>;
+  modelProvider?: { aliases?: Record<string, string> };
+  harnessProvider?: { adapter: string };
+  triggers: Array<{
+    id: string;
+    strategy: "poll" | "webhook";
+    describe?: string;
+    registerMode?: "auto" | "manual";
+    intervalDefault?: string;
+    intervalFloor?: string;
+    event?: string;
+  }>;
+  webhookVerify?: string;
+}
+
+export function extractConnectorManifest(
+  connector: ConnectorInstance<ActionsTree, TriggersDecl>,
+): ConnectorManifest {
+  if (!isConnector(connector)) throw new TypeError("extractConnectorManifest: not a connector");
+  const spec = connector.__connector;
+
+  const authMap = ("kind" in spec.auth ? { default: spec.auth } : spec.auth) as Record<
+    string,
+    import("../connector/index.js").AuthDecl
+  >;
+  const auth: ConnectorManifest["auth"] = {};
+  for (const [mode, decl] of Object.entries(authMap)) {
+    switch (decl.kind) {
+      case "oauth2":
+        auth[mode] = {
+          kind: "oauth2",
+          scopes: [...decl.scopes],
+          flow: decl.flow,
+          ...(decl.provider !== undefined ? { provider: decl.provider } : {}),
+          ...(decl.describe !== undefined ? { describe: decl.describe } : {}),
+        };
+        break;
+      case "apiKey":
+        auth[mode] = {
+          kind: "apiKey",
+          in: decl.in,
+          name: decl.name,
+          ...(decl.prefix !== undefined ? { prefix: decl.prefix } : {}),
+          ...(decl.describe !== undefined ? { describe: decl.describe } : {}),
+        };
+        break;
+      case "basic":
+        auth[mode] = { kind: "basic", ...(decl.describe !== undefined ? { describe: decl.describe } : {}) };
+        break;
+      case "custom":
+        auth[mode] = {
+          kind: "custom",
+          fields: [...(decl.fields ?? [])],
+          ...(decl.describe !== undefined ? { describe: decl.describe } : {}),
+        };
+        break;
+    }
+  }
+
+  const actions: ConnectorManifest["actions"] = [];
+  const hasIdem = spec.idempotencyHeader !== undefined;
+  (function walk(tree: ActionsTree, path: string[]) {
+    for (const [key, child] of Object.entries(tree)) {
+      const p = [...path, key];
+      if (isAction(child)) {
+        const a = child as AnyAction;
+        actions.push({
+          path: p.join("."),
+          safety: a.safety,
+          retrySafe: isRetrySafe(a, hasIdem),
+          ...(a.describe !== undefined ? { describe: a.describe } : {}),
+        });
+      } else {
+        walk(child as ActionsTree, p);
+      }
+    }
+  })(spec.actions ?? {}, []);
+
+  const triggers: ConnectorManifest["triggers"] = [];
+  for (const [id, decl] of Object.entries(spec.triggers ?? {})) {
+    if (decl.__trigger === "webhook") {
+      triggers.push({
+        id,
+        strategy: "webhook",
+        registerMode: decl.register.mode,
+        event: decl.event,
+        ...(decl.describe !== undefined ? { describe: decl.describe } : {}),
+      });
+    } else {
+      triggers.push({
+        id,
+        strategy: "poll",
+        ...(decl.interval?.default !== undefined ? { intervalDefault: decl.interval.default } : {}),
+        ...(decl.interval?.floor !== undefined ? { intervalFloor: decl.interval.floor } : {}),
+        ...(decl.describe !== undefined ? { describe: decl.describe } : {}),
+      });
+    }
+  }
+
+  return {
+    id: spec.id,
+    auth,
+    actions,
+    ...(spec.modelProvider !== undefined
+      ? {
+          modelProvider: {
+            ...(spec.modelProvider.aliases !== undefined ? { aliases: spec.modelProvider.aliases } : {}),
+          },
+        }
+      : {}),
+    ...(spec.harnessProvider !== undefined ? { harnessProvider: { adapter: spec.harnessProvider.adapter } } : {}),
+    triggers,
+    ...(spec.describe !== undefined ? { describe: spec.describe } : {}),
+    ...(typeof spec.provider === "string"
+      ? { provider: spec.provider }
+      : spec.provider !== undefined
+        ? { provider: spec.provider.id, providerFacts: spec.provider }
+        : {}),
+    ...(spec.baseUrl !== undefined ? { baseUrl: spec.baseUrl } : {}),
+    ...(spec.idempotencyHeader !== undefined ? { idempotencyHeader: spec.idempotencyHeader } : {}),
+    ...(spec.webhook !== undefined ? { webhookVerify: spec.webhook.verify.kind } : {}),
+  };
+}

package/src/internal/operators.ts

@@ -0,0 +1,287 @@
+import { TerminalError } from "../errors.js";
+import type { AutomationDef, Ctx, Schema, Serializable } from "../automation.js";
+import type { ActionsTree, AnyAction, ConnectorInstance, TriggersDecl } from "../connector/index.js";
+import type {
+  ModelDef,
+  ModelMessage,
+  ModelToolCall,
+  ModelToolDescriptor,
+  NormalizedModelRequest,
+  NormalizedModelResponse,
+  OperatorDef,
+  Operators,
+} from "../operators.js";
+import { encodeJournal, decodeJournal, type JsonValue } from "./codec.js";
+import { actionAtPath } from "./client.js";
+import { validateSchema } from "./standard-schema.js";
+
+export interface ModelCallInfo {
+  automationId: string;
+  operatorKey: string;
+  modelKey: string;
+  model: ModelDef;
+  request: NormalizedModelRequest;
+}
+
+export type ModelCaller = (info: ModelCallInfo) => Promise<NormalizedModelResponse>;
+
+interface ToolRuntime {
+  descriptor: ModelToolDescriptor;
+  connectionKey: string;
+  actionPath: string[];
+  action: AnyAction;
+}
+
+interface ApprovalPayload {
+  approved: boolean;
+  reason?: string;
+}
+
+const approvalSchema: Schema<ApprovalPayload> = {
+  "~standard": {
+    version: 1,
+    vendor: "tesser",
+    validate(value) {
+      if (typeof value === "object" && value !== null && typeof (value as { approved?: unknown }).approved === "boolean") {
+        const v = value as { approved: boolean; reason?: unknown };
+        return {
+          value: {
+            approved: v.approved,
+            ...(typeof v.reason === "string" ? { reason: v.reason } : {}),
+          },
+        };
+      }
+      return { issues: [{ message: "expected { approved: boolean }" }] };
+    },
+  },
+};
+
+export function buildOperators(
+  def: AutomationDef<any, any, any, any, any, any, any>,
+  ctx: Ctx<any, any, any>,
+  callModel: ModelCaller,
+): Operators<any> {
+  const usage = { tokens: 0, outputTokens: 0 };
+  const out: Record<string, (input: unknown) => Promise<unknown>> = {};
+  for (const [operatorKey, op] of Object.entries(def.operators ?? {})) {
+    out[operatorKey] = (input: unknown) =>
+      executeOperator({ def, ctx, operatorKey, op: op as OperatorDef, input, usage, callModel });
+  }
+  return Object.freeze(out);
+}
+
+async function executeOperator(opts: {
+  def: AutomationDef<any, any, any, any, any, any, any>;
+  ctx: Ctx<any, any, any>;
+  operatorKey: string;
+  op: OperatorDef;
+  input: unknown;
+  usage: { tokens: number; outputTokens: number };
+  callModel: ModelCaller;
+}): Promise<unknown> {
+  const { def, ctx, operatorKey, op } = opts;
+  const modelKey = op.model;
+  const model = def.models?.[modelKey];
+  if (!model) throw new TerminalError(`operator.${operatorKey}: unknown model "${modelKey}"`);
+
+  const validatedInput = await validateSchema(op.input, opts.input, `operator.${operatorKey} input`);
+  const serialInput = toSerializable(validatedInput, `operator.${operatorKey} input`);
+  const tools = await resolveTools(def, op, operatorKey);
+  const messages: ModelMessage[] = [{ role: "user", content: JSON.stringify(serialInput) }];
+  const outputJsonSchema = await schemaJson(op.output);
+  let tainted = true; // trigger payload / Operator input is coarse-tainted in v1.
+
+  for (let turn = 1; turn <= op.maxTurns; turn++) {
+    assertBudget(def, model, opts.usage, operatorKey);
+    const request: NormalizedModelRequest = {
+      operatorKey,
+      modelKey,
+      alias: model.alias,
+      instructions: op.instructions,
+      input: serialInput,
+      messages,
+      tools: tools.map((t) => t.descriptor),
+      ...(model.settings !== undefined ? { settings: model.settings } : {}),
+      ...(outputJsonSchema !== undefined ? { outputJsonSchema } : {}),
+    };
+    const response = (await ctx.step(`operator.${operatorKey}.model.${turn}`, async () =>
+      toSerializable(
+        await opts.callModel({ automationId: def.id, operatorKey, modelKey, model, request }),
+        `operator.${operatorKey} model response`,
+      ),
+    )) as unknown as NormalizedModelResponse;
+    validateModelResponse(response, operatorKey, turn);
+    addUsage(opts.usage, response);
+    assertBudget(def, model, opts.usage, operatorKey);
+
+    const toolCalls = response.toolCalls ?? [];
+    if (toolCalls.length > 0) {
+      messages.push({ role: "assistant", content: response.content ?? `requested ${toolCalls.length} tool call(s)` });
+      let index = 0;
+      for (const call of toolCalls) {
+        index++;
+        const tool = toolForCall(tools, call);
+        if (!tool) {
+          throw new TerminalError(`operator.${operatorKey}: model requested undeclared tool "${call.name}"`);
+        }
+        if (tool.action.safety === "write") {
+          const approval = await ctx.waitForSignal(`operator.${operatorKey}.approval`, {
+            schema: approvalSchema,
+            timeout: "1h",
+          });
+          if (approval === null) {
+            throw new TerminalError(`operator.${operatorKey}: approval timed out for write tool ${tool.descriptor.path}`);
+          }
+          if (!approval.approved) {
+            throw new TerminalError(`operator.${operatorKey}: approval denied for write tool ${tool.descriptor.path}`);
+          }
+        }
+        const toolResult = await ctx.step(`operator.${operatorKey}.tool.${turn}.${index}.${tool.descriptor.path}`, async () => {
+          const fn = actionFunction(ctx.connections as Record<string, unknown>, tool.connectionKey, tool.actionPath);
+          return toSerializable(await fn(call.input), `operator.${operatorKey} tool ${tool.descriptor.path} output`);
+        });
+        if (tool.action.safety === "read") tainted = true;
+        messages.push({
+          role: "tool",
+          toolCallId: call.id,
+          content: minimizeToolOutput(toolResult, { tainted }),
+        });
+      }
+      continue;
+    }
+
+    const rawOutput = response.output !== undefined ? response.output : parseJson(response.content, operatorKey, turn);
+    return validateSchema(op.output, rawOutput, `operator.${operatorKey} output`);
+  }
+  throw new TerminalError(`operator.${operatorKey}: exceeded maxTurns (${op.maxTurns})`);
+}
+
+async function resolveTools(
+  def: AutomationDef<any, any, any, any, any, any, any>,
+  op: OperatorDef,
+  operatorKey: string,
+): Promise<ToolRuntime[]> {
+  const out: ToolRuntime[] = [];
+  const connections = (def.connections ?? {}) as Record<string, ConnectorInstance<ActionsTree, TriggersDecl>>;
+  for (const toolPath of op.tools) {
+    const [connectionKey, ...actionPath] = toolPath.split(".");
+    const connector = connections[connectionKey!];
+    if (!connector) throw new TerminalError(`operator.${operatorKey}: undeclared tool connection "${connectionKey}"`);
+    const action = actionAtPath(connector, actionPath);
+    if (!action) throw new TerminalError(`operator.${operatorKey}: tool "${toolPath}" is not a declared Action`);
+    const inputSchema = await schemaJson(action.input as Schema<unknown>);
+    out.push({
+      connectionKey: connectionKey!,
+      actionPath,
+      action,
+      descriptor: {
+        name: toolName(toolPath),
+        path: toolPath,
+        ...(action.describe !== undefined ? { description: action.describe } : {}),
+        ...(inputSchema !== undefined ? { inputSchema } : {}),
+      },
+    });
+  }
+  return out;
+}
+
+function toolForCall(tools: ToolRuntime[], call: ModelToolCall): ToolRuntime | undefined {
+  return tools.find((t) => call.name === t.descriptor.name || call.name === t.descriptor.path);
+}
+
+export function toolName(path: string): string {
+  return path.replace(/[^A-Za-z0-9_-]/g, "__");
+}
+
+function actionFunction(
+  connections: Record<string, unknown>,
+  connectionKey: string,
+  actionPath: string[],
+): (input: unknown) => Promise<unknown> {
+  let node = connections[connectionKey];
+  for (const seg of actionPath) node = (node as Record<string, unknown> | undefined)?.[seg];
+  if (typeof node !== "function") {
+    throw new TerminalError(`operator tool ${connectionKey}.${actionPath.join(".")} is not callable`);
+  }
+  return node as (input: unknown) => Promise<unknown>;
+}
+
+function validateModelResponse(response: NormalizedModelResponse, operatorKey: string, turn: number): void {
+  if (typeof response !== "object" || response === null) {
+    throw new TerminalError(`operator.${operatorKey} turn ${turn}: model adapter returned a non-object response`);
+  }
+  if (!response.usage || typeof response.usage.inputTokens !== "number" || typeof response.usage.outputTokens !== "number") {
+    throw new TerminalError(`operator.${operatorKey} turn ${turn}: model response missing usage tokens`);
+  }
+}
+
+function addUsage(usage: { tokens: number; outputTokens: number }, response: NormalizedModelResponse): void {
+  usage.tokens += response.usage.inputTokens + response.usage.outputTokens + (response.usage.reasoningTokens ?? 0);
+  usage.outputTokens += response.usage.outputTokens;
+}
+
+function assertBudget(
+  def: AutomationDef<any, any, any, any, any, any, any>,
+  model: ModelDef,
+  usage: { tokens: number; outputTokens: number },
+  operatorKey: string,
+): void {
+  const budget = def.budget?.models;
+  if (!budget) throw new TerminalError(`operator.${operatorKey}: budget.models is required`);
+  if (usage.tokens >= budget.tokens) {
+    throw new TerminalError(`operator.${operatorKey}: model token budget exceeded (${usage.tokens}/${budget.tokens})`);
+  }
+  if (usage.outputTokens >= budget.outputTokens) {
+    throw new TerminalError(
+      `operator.${operatorKey}: model output-token budget exceeded (${usage.outputTokens}/${budget.outputTokens})`,
+    );
+  }
+  const maxOut = model.settings?.maxOutputTokens;
+  if (maxOut !== undefined && maxOut > budget.outputTokens - usage.outputTokens) {
+    throw new TerminalError(`operator.${operatorKey}: model maxOutputTokens exceeds remaining output-token budget`);
+  }
+}
+
+function parseJson(content: string | undefined, operatorKey: string, turn: number): unknown {
+  if (!content) throw new TerminalError(`operator.${operatorKey} turn ${turn}: model returned no output`);
+  const trimmed = content.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+  try {
+    return JSON.parse(trimmed);
+  } catch (cause) {
+    throw new TerminalError(`operator.${operatorKey} turn ${turn}: model output was not JSON`, { cause });
+  }
+}
+
+function toSerializable(value: unknown, what: string): Serializable {
+  try {
+    return decodeJournal(encodeJournal(value)) as Serializable;
+  } catch (cause) {
+    throw new TerminalError(`${what} is not serializable`, { cause });
+  }
+}
+
+function minimizeToolOutput(value: Serializable, opts: { tainted: boolean }): string {
+  const raw = JSON.stringify({ tainted: opts.tainted, value: encodeJournal(value) });
+  return raw.length <= 4000 ? raw : raw.slice(0, 3997) + "...";
+}
+
+async function schemaJson(schema: Schema<unknown>): Promise<Serializable | undefined> {
+  const std = (schema as { "~standard"?: { vendor?: string } })["~standard"];
+  try {
+    let json: unknown;
+    const direct = schema as unknown as { toJSONSchema?: () => unknown };
+    if (typeof direct.toJSONSchema === "function") json = direct.toJSONSchema();
+    else if (std?.vendor === "zod") {
+      const zod = (await import("zod")) as unknown as {
+        toJSONSchema?: (s: unknown, opts?: unknown) => unknown;
+        z?: { toJSONSchema?: (s: unknown, opts?: unknown) => unknown };
+      };
+      const convert = zod.toJSONSchema ?? zod.z?.toJSONSchema;
+      if (convert) json = convert(schema, { unrepresentable: "any" });
+    }
+    if (json === undefined) return undefined;
+    return decodeJournal(encodeJournal(json as JsonValue)) as Serializable;
+  } catch {
+    return undefined;
+  }
+}