@temporalio/agent-harness 0.0.0-stage → 0.2.0

package/dist/src/harness/code-mode/okf.js

@@ -0,0 +1,315 @@
+// Open Knowledge Format (OKF v0.2) as workflow-safe models and text.
+// Parsing YAML and walking a bundle need a YAML library and a filesystem, so both stay in
+// worker activities. Rendering a concept runs in the workflow, with a small block-style emitter
+// instead of a Node YAML package.
+import { z } from "zod";
+export const OKF_VERSION = "0.2";
+export const RESERVED_NAMES = new Set(["index.md", "log.md"]);
+/** The most a walk reads, so a huge bundle can't stall the activity or the console. */
+export const MAX_OKF_CONCEPTS = 1_000;
+export const MAX_OKF_FILE_BYTES = 256_000;
+export const MAX_OKF_TOTAL_BYTES = 8_000_000;
+/** Without links only frontmatter is needed, so a walk reads each file's head first. */
+export const OKF_HEAD_BYTES = 8_192;
+export const UNCLOSED_FRONTMATTER = "frontmatter is never closed with a `---` line";
+const TrustTier = z.enum(["unverified", "machine-confirmed", "human-reviewed"]);
+export const OKFConcept = z
+    .object({
+    id: z.string(),
+    path: z.string(),
+    type: z.string(),
+    title: z.string(),
+    description: z.string().default(""),
+    tags: z.array(z.string()).default([]),
+    status: z.string().default("stable"),
+    trust_tier: TrustTier.default("unverified"),
+    stale: z.boolean().default(false),
+    size: z.number(),
+    problem: z.string().nullable().default(null),
+})
+    .meta({ title: "OKFConcept" });
+export const OKFLink = z
+    .object({
+    source: z.string(),
+    target: z.string(),
+    dangling: z.boolean().default(false),
+})
+    .meta({ title: "OKFLink" });
+export const OKFLinks = z
+    .object({
+    id: z.string(),
+    links_to: z.array(OKFLink),
+    cited_by: z.array(OKFLink),
+})
+    .meta({ title: "OKFLinks" });
+export const OKFGraph = z
+    .object({
+    concepts: z.array(OKFConcept),
+    links: z.array(OKFLink).default([]),
+    truncated: z.boolean().default(false),
+    walked_at: z.number(),
+})
+    .meta({ title: "OKFGraph" });
+/** `(frontmatter, body, problem)`. `frontmatter` is null when there is none. */
+export function splitFrontmatter(text) {
+    const lines = splitKeep(text);
+    if (!lines.length || stripLine(lines[0]) !== "---")
+        return [null, text, "no frontmatter: the file doesn't start with a `---` line"];
+    for (let i = 1; i < lines.length; i++) {
+        if (stripLine(lines[i]) === "---")
+            return [lines.slice(1, i).join(""), lines.slice(i + 1).join(""), null];
+    }
+    return [null, text, UNCLOSED_FRONTMATTER];
+}
+const FENCE = /^\s{0,3}(```|~~~)/;
+const SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+const SPACE = /\s/;
+const TARGET_END = /[)\s>]/;
+/**
+ * The targets of the `](target "title")` links in `line`, exactly as
+ * `/\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g` finds them, in one pass: that regex retries at
+ * every `](`, which is quadratic in a long line of them.
+ */
+function linkTargetsIn(line) {
+    const found = [];
+    const skipSpace = (at) => {
+        while (at < line.length && SPACE.test(line[at]))
+            at++;
+        return at;
+    };
+    for (let open = line.indexOf("]("); open >= 0;) {
+        let at = skipSpace(open + 2);
+        const angle = line[at] === "<";
+        if (angle)
+            at++;
+        let start = at;
+        while (at < line.length && !TARGET_END.test(line[at]))
+            at++;
+        // A `<` with nothing after it is the target itself.
+        if (at === start && angle)
+            start--;
+        let end = -1;
+        if (at > start) {
+            const afterTarget = line[at] === ">" ? at + 1 : at;
+            const titleAt = skipSpace(afterTarget);
+            if (titleAt > afterTarget && line[titleAt] === '"') {
+                const close = line.indexOf('"', titleAt + 1);
+                if (close >= 0) {
+                    const paren = skipSpace(close + 1);
+                    if (line[paren] === ")")
+                        end = paren + 1;
+                }
+            }
+            if (end < 0) {
+                const paren = skipSpace(afterTarget);
+                if (line[paren] === ")")
+                    end = paren + 1;
+            }
+        }
+        if (end >= 0)
+            found.push(line.slice(start, at));
+        // After a failed `](`, every later one whose target starts inside this target ends where it
+        // did and fails too; the next to try is the one that ends just before that end.
+        open = line.indexOf("](", end >= 0 ? end : Math.max(open + 1, at - 2));
+    }
+    return found;
+}
+/**
+ * Concept ids `body` links to, in order, without repeats. Relative targets resolve against
+ * `conceptPath`; a target starting with `/` is relative to the bundle root. Links inside
+ * fenced code blocks, and links to the concept itself, are left out.
+ */
+export function linkTargets(body, conceptPath) {
+    const found = [];
+    const here = parentPosix(conceptPath);
+    let fence = null;
+    for (const line of body.split(/\r\n|\n|\r/)) {
+        const opened = FENCE.exec(line);
+        if (opened) {
+            const marker = opened[1];
+            fence = fence === marker ? null : (fence ?? marker);
+            continue;
+        }
+        if (fence)
+            continue;
+        for (const raw of linkTargetsIn(line)) {
+            const target = resolveLink(decodePercent(raw), here);
+            if (target !== null && !found.includes(target))
+                found.push(target);
+        }
+    }
+    const selfId = conceptPath.endsWith(".md") ? conceptPath.slice(0, -3) : conceptPath;
+    return found.filter((id) => id !== selfId);
+}
+/**
+ * A concept's full text: `frontmatter` as YAML between `---` lines, then `body`.
+ * Records `generated` unless it is already present, and stamps a `verified` entry that has no `at`.
+ */
+export function renderConcept(frontmatter, body, generated) {
+    const stamp = generated.at.toISOString().replace(/\.\d{3}Z$/, "Z");
+    const fields = { ...frontmatter };
+    if (!Object.hasOwn(fields, "generated"))
+        fields.generated = { by: generated.by, at: stamp };
+    const verified = fields.verified;
+    if (isPlainObject(verified))
+        fields.verified = stampVerified(verified, stamp);
+    else if (Array.isArray(verified))
+        fields.verified = verified.map((entry) => isPlainObject(entry) ? stampVerified(entry, stamp) : entry);
+    const text = body.replace(/^\n+/, "");
+    const block = dumpMap(fields, 0);
+    return `---\n${block}\n---\n\n${text}${text.endsWith("\n") ? "" : "\n"}`;
+}
+function stampVerified(entry, stamp) {
+    return { ...entry, at: Object.hasOwn(entry, "at") ? entry.at : stamp };
+}
+function splitKeep(text) {
+    const lines = [];
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch !== "\n" && ch !== "\r")
+            continue;
+        const end = ch === "\r" && text[i + 1] === "\n" ? i + 2 : i + 1;
+        lines.push(text.slice(start, end));
+        start = end;
+        i = end - 1;
+    }
+    if (start < text.length || text.length === 0)
+        lines.push(text.slice(start));
+    if (text.length === 0)
+        return [];
+    return lines;
+}
+const stripLine = (line) => line.replace(/[\r\n]+$/, "").trim();
+function parentPosix(path) {
+    const i = path.lastIndexOf("/");
+    return i === -1 ? "." : path.slice(0, i);
+}
+function decodePercent(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function resolveLink(target, here) {
+    const hash = target.indexOf("#");
+    const bare = hash === -1 ? target : target.slice(0, hash);
+    if (!bare || SCHEME.test(bare) || !bare.endsWith(".md"))
+        return null;
+    const joined = bare.startsWith("/")
+        ? bare.replace(/^\/+/, "")
+        : here === "."
+            ? bare
+            : `${here}/${bare}`;
+    const normal = posixNorm(joined);
+    if (normal === "." || normal === "" || normal === ".." || normal.startsWith("../"))
+        return null;
+    const name = normal.slice(normal.lastIndexOf("/") + 1);
+    if (RESERVED_NAMES.has(name))
+        return null;
+    return normal.slice(0, -3);
+}
+function posixNorm(path) {
+    const parts = [];
+    let up = 0;
+    for (const part of path.split("/")) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            if (parts.length)
+                parts.pop();
+            else
+                up++;
+        }
+        else
+            parts.push(part);
+    }
+    if (!parts.length)
+        return up ? `..${"/..".repeat(up - 1)}` : ".";
+    return `${up ? "../".repeat(up) : ""}${parts.join("/")}`;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Quoted when YAML 1.1 would otherwise retype the string (a date, a bool, a number).
+const BOOL_OR_NULL = /^(?:~|null|Null|NULL|y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF)$/;
+const NUMBER = /^[+-]?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}(?:[Tt ]|$)/;
+function needsQuote(value) {
+    if (value === "" || value !== value.trim())
+        return true;
+    if (/[\n\r\t#{}[\],&*!|>'"%@`]/.test(value))
+        return true;
+    if (/: /.test(value) || /^[-?:]/.test(value))
+        return true;
+    return BOOL_OR_NULL.test(value) || NUMBER.test(value) || TIMESTAMP.test(value);
+}
+function emitString(value) {
+    if (!needsQuote(value))
+        return value;
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function dumpScalar(value) {
+    if (value === null || value === undefined)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : "null";
+    if (typeof value === "string")
+        return emitString(value);
+    return emitString(String(value));
+}
+function dumpMap(obj, indent) {
+    const pad = " ".repeat(indent);
+    const lines = [];
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === undefined)
+            continue;
+        const name = emitString(key);
+        if (Array.isArray(value)) {
+            lines.push(value.length ? `${pad}${name}:\n${dumpList(value, indent)}` : `${pad}${name}: []`);
+        }
+        else if (isPlainObject(value)) {
+            const inner = dumpMap(value, indent + 2);
+            lines.push(inner ? `${pad}${name}:\n${inner}` : `${pad}${name}: {}`);
+        }
+        else
+            lines.push(`${pad}${name}: ${dumpScalar(value)}`);
+    }
+    return lines.join("\n");
+}
+function dumpList(items, indent) {
+    const pad = " ".repeat(indent);
+    const lines = [];
+    for (const item of items) {
+        if (isPlainObject(item)) {
+            const entries = Object.entries(item).filter(([, value]) => value !== undefined);
+            if (!entries.length) {
+                lines.push(`${pad}- {}`);
+                continue;
+            }
+            const [firstKey, firstValue] = entries[0];
+            lines.push(`${pad}- ${emitString(firstKey)}:${inlineOrBreak(firstValue, indent + 2)}`);
+            for (const [key, value] of entries.slice(1))
+                lines.push(`${" ".repeat(indent + 2)}${emitString(key)}:${inlineOrBreak(value, indent + 4)}`);
+        }
+        else if (Array.isArray(item)) {
+            lines.push(item.length ? `${pad}-\n${dumpList(item, indent + 2)}` : `${pad}- []`);
+        }
+        else
+            lines.push(`${pad}- ${dumpScalar(item)}`);
+    }
+    return lines.join("\n");
+}
+function inlineOrBreak(value, indent) {
+    if (Array.isArray(value))
+        return value.length ? `\n${dumpList(value, indent - 2)}` : " []";
+    if (isPlainObject(value)) {
+        const inner = dumpMap(value, indent);
+        return inner ? `\n${inner}` : " {}";
+    }
+    return ` ${dumpScalar(value)}`;
+}

package/dist/src/harness/code-mode/stubs.d.ts

@@ -0,0 +1,13 @@
+import type { AnyHarnessTool } from "../agent-workflow/types.ts";
+import { pyRepr } from "../py-repr.ts";
+export { pyRepr };
+export interface TypeCheckStubs {
+    source: string;
+    type_names: string[];
+}
+export declare class CodeModeStubError extends Error {
+    name: string;
+}
+export type Schema = Record<string, unknown>;
+export declare function renderTypeCheckStubs(tools: readonly AnyHarnessTool[]): TypeCheckStubs;
+export declare function renderHostInterface(tools: readonly AnyHarnessTool[]): string;

package/dist/src/harness/code-mode/stubs.js

@@ -0,0 +1,203 @@
+// The host functions as the model reads them, and as Python stubs Monty type-checks scripts
+// against.
+import { pyRepr } from "../py-repr.js";
+export { pyRepr };
+import { toJsonSchema } from "../agent-protocol/index.js";
+// ---------------------------------------------------------------------------------------------
+// Python stubs from JSON Schema
+// ---------------------------------------------------------------------------------------------
+export class CodeModeStubError extends Error {
+    name = "CodeModeStubError";
+}
+const SEPARATOR = /[_\-\s(). ]/;
+const WORD = /\w/;
+/**
+ * `s` in PascalCase without non-word characters: what
+ * `s.replace(/(^|[_\-\s(). ]+)(\w)/g, upper).replace(/\W/g, "")` makes, in one pass (that regex
+ * retries inside every run of separators, which is quadratic).
+ */
+function pascal(s) {
+    let out = "";
+    let i = 0;
+    if (s.length > 0 && WORD.test(s[0]))
+        out += s[i++].toUpperCase();
+    while (i < s.length) {
+        let run = i;
+        while (run < s.length && SEPARATOR.test(s[run]))
+            run++;
+        if (run === i) {
+            out += s[i++];
+        }
+        else if (run < s.length && WORD.test(s[run])) {
+            out += s[run].toUpperCase();
+            i = run + 1;
+        }
+        else {
+            // No word follows the run: the regex backs off to the run's last `_` after its first
+            // character, which is a word character too, and replaces the span with it.
+            let underscore = run - 1;
+            while (underscore > i && s[underscore] !== "_")
+                underscore--;
+            if (underscore > i) {
+                out += "_";
+                i = underscore + 1;
+            }
+            else {
+                out += s.slice(i, run);
+                i = run;
+            }
+        }
+    }
+    return out.replace(/\W/g, "");
+}
+const pyLiteral = (v) => typeof v === "string"
+    ? JSON.stringify(v)
+    : v === true
+        ? "True"
+        : v === false
+            ? "False"
+            : v === null
+                ? "None"
+                : String(v);
+class StubBuilder {
+    #classes = [];
+    #byKey = new Map();
+    #used = new Set();
+    #imports = new Set();
+    build(tools, withDoc) {
+        const funcs = tools.map((t) => this.#renderTool(t, withDoc));
+        if (this.#classes.length)
+            this.#imports.add("TypedDict");
+        const header = ["from __future__ import annotations"];
+        if (this.#imports.size)
+            header.push(`from typing import ${[...this.#imports].sort().join(", ")}`);
+        const sections = [header.join("\n")];
+        if (this.#classes.length) {
+            sections.push(this.#classes
+                .map((c) => `class ${c.name}(TypedDict):\n${c.fields.length ? c.fields.join("\n") : "    pass"}`)
+                .join("\n\n"));
+        }
+        if (funcs.length)
+            sections.push(funcs.join("\n\n"));
+        return `${sections.join("\n\n\n")}\n`;
+    }
+    typeNames() {
+        return this.#classes.map((c) => c.name);
+    }
+    #renderTool(tool, withDoc) {
+        if (tool.outputSchema === undefined) {
+            throw new CodeModeStubError(`tool '${tool.name}' has no output schema; Code Mode requires a typed result so scripts can be checked against it.`);
+        }
+        const input = tool.parameters;
+        const required = new Set(input.required ?? []);
+        const props = Object.entries(input.properties ?? {});
+        const params = [
+            ...props
+                .filter(([n]) => required.has(n))
+                .map(([n, s]) => `${n}: ${this.#type(s, input, `${tool.name}(${n})`)}`),
+            ...props
+                .filter(([n]) => !required.has(n))
+                .map(([n, s]) => `${n}: ${this.#type(s, input, `${tool.name}(${n})`)} = ...`),
+        ];
+        const outSchema = toJsonSchema(tool.outputSchema, "output");
+        const signature = `async def ${tool.name}(${params.join(", ")}) -> ${this.#type(outSchema, outSchema, `${tool.name} return`)}`;
+        const text = tool.description.trim().replaceAll('"""', '\\"\\"\\"');
+        if (!withDoc || !text)
+            return `${signature}: ...`;
+        const doc = text
+            .split("\n")
+            .map((line) => `    ${line}`.trimEnd())
+            .join("\n");
+        return `${signature}:\n    """\n${doc}\n    """`;
+    }
+    #type(schema, root, ctx) {
+        if (typeof schema.$ref === "string") {
+            const key = schema.$ref.replace(/^#\/(\$defs|definitions)\//, "");
+            const target = (root.$defs ?? root.definitions)?.[key];
+            if (target === undefined)
+                throw new CodeModeStubError(`${ctx}: unresolvable $ref ${schema.$ref}`);
+            return this.#type({ title: key, ...target }, root, ctx);
+        }
+        const union = (schema.anyOf ?? schema.oneOf);
+        if (union)
+            return [...new Set(union.map((s) => this.#type(s, root, ctx)))].join(" | ");
+        if (schema.const !== undefined) {
+            this.#imports.add("Literal");
+            return `Literal[${pyLiteral(schema.const)}]`;
+        }
+        if (Array.isArray(schema.enum)) {
+            this.#imports.add("Literal");
+            return `Literal[${schema.enum.map(pyLiteral).join(", ")}]`;
+        }
+        const type = schema.type;
+        if (Array.isArray(type))
+            return type.map((t) => this.#type({ ...schema, type: t }, root, ctx)).join(" | ");
+        switch (type) {
+            case "string":
+                return "str";
+            case "integer":
+                return "int";
+            case "number":
+                return "float";
+            case "boolean":
+                return "bool";
+            case "null":
+                return "None";
+            case "array": {
+                if (typeof schema.items !== "object" || schema.items === null) {
+                    throw new CodeModeStubError(`${ctx}: array without an element type; give its items a schema for static validation.`);
+                }
+                return `list[${this.#type(schema.items, root, ctx)}]`;
+            }
+            case "object": {
+                if (schema.properties !== undefined)
+                    return this.#typedDict(schema, root, ctx);
+                const extra = schema.additionalProperties;
+                if (typeof extra === "object" && extra !== null)
+                    return `dict[str, ${this.#type(extra, root, ctx)}]`;
+                this.#imports.add("Any");
+                return "dict[str, Any]";
+            }
+            case undefined:
+                this.#imports.add("Any");
+                return "Any";
+            default:
+                throw new CodeModeStubError(`${ctx}: cannot represent JSON Schema type ${JSON.stringify(type)} in Code Mode stubs.`);
+        }
+    }
+    #typedDict(schema, root, ctx) {
+        // A model's input and output schemas differ only in these, and render to the same TypedDict.
+        const { $schema: _s, additionalProperties: _a, ...shape } = schema;
+        const key = JSON.stringify(shape);
+        const known = this.#byKey.get(key);
+        if (known !== undefined)
+            return known;
+        let name = typeof schema.title === "string"
+            ? pascal(schema.title)
+            : pascal(ctx.replace(/ return$/, "_result"));
+        for (let i = 2; this.#used.has(name); i++)
+            name = `${name.replace(/_\d+$/, "")}_${i}`;
+        this.#used.add(name);
+        this.#byKey.set(key, name);
+        const entry = { name, fields: [] };
+        this.#classes.push(entry);
+        const required = new Set(schema.required ?? []);
+        for (const [field, fieldSchema] of Object.entries(schema.properties)) {
+            let rendered = this.#type(fieldSchema, root, `${name}.${field}`);
+            if (!required.has(field)) {
+                this.#imports.add("NotRequired");
+                rendered = `NotRequired[${rendered}]`;
+            }
+            entry.fields.push(`    ${field}: ${rendered}`);
+        }
+        return name;
+    }
+}
+export function renderTypeCheckStubs(tools) {
+    const builder = new StubBuilder();
+    const source = builder.build(tools, false);
+    return { source, type_names: builder.typeNames() };
+}
+export function renderHostInterface(tools) {
+    return new StubBuilder().build(tools, true);
+}

package/dist/src/harness/code-mode/texts.d.ts

@@ -0,0 +1,4 @@
+export declare const CONTRACT = "Run a Python `script` in a sandbox and return its output. Accomplish tasks by WRITING CODE that calls the host functions listed below \u2014 using variables, loops, conditionals, comprehensions and arithmetic to combine many calls in one go \u2014 instead of calling tools one at a time.\n\n{sandbox} The host functions and the types below are ALREADY IN SCOPE \u2014 never import them (there is no module to import them from). Calling a `TypedDict` type builds a plain dict, as in Python. The host functions are ASYNC \u2014 you MUST `await` them \u2014 so structure every script like this:\n\n    import asyncio\n    async def main():\n        ...                 # await host functions here\n        return <final value>\n    asyncio.run(main())\n\nThe value of the script's LAST EXPRESSION becomes the result (along with anything you `print`). Run INDEPENDENT host calls CONCURRENTLY with `asyncio.gather(...)`; only await sequentially when a later call needs an earlier call's result. Host results come back as plain dicts/lists/scalars \u2014 index into them with normal Python (e.g. `results[0][\"field\"]`). A host function that fails RAISES at its `await`: catch it with `try`/`except Exception` to handle the failure, or let it propagate to end the script with an error.\n\nYour script is STATICALLY TYPE-CHECKED against the host-function signatures below BEFORE it runs: a wrong argument type, or reading a result key that doesn't exist, comes back as an error to fix rather than a result. The signatures and result shapes below are exact \u2014 only the listed keys exist.\n\nHost functions available:\n\n{interface}\n{filesystem}{guide}";
+export declare const FILESYSTEM_STUB = "import os as _os\nimport typing as _typing\ndef open(file: str | _os.PathLike[str], mode: str = \"r\", encoding: str | None = None) -> _typing.IO[_typing.Any]: ...\nclass FileNotFoundError(OSError): ...\nclass FileExistsError(OSError): ...\nclass IsADirectoryError(OSError): ...\nclass NotADirectoryError(OSError): ...\nclass PermissionError(OSError): ...";
+export declare const NO_FILESYSTEM = "The sandbox has no filesystem, no network, and no imports except `asyncio` and the host functions below.";
+export declare const WITH_FILESYSTEM = "The sandbox has no network, and no imports except `asyncio`, `pathlib` and the host functions below. It has the filesystem listed under Filesystem below: read and write it with `open()` and `pathlib.Path`. File operations are synchronous (never `await` them) and work on whole files; read lines with `f.read().splitlines()`, not `for line in f`. A failed file operation raises an `OSError` subclass (`FileNotFoundError`, `FileExistsError`, `IsADirectoryError`, `NotADirectoryError`, `PermissionError`) whose message names the path; it has no `errno`.";

package/dist/src/harness/code-mode/texts.js

@@ -0,0 +1,6 @@
+// GENERATED from contract/code_mode/ by //typescript/packages/core/src/harness/code-mode:contract_texts (harness_texts).
+// Do not edit: change the text files and run `bazel run //typescript/packages/core/src/harness/code-mode:contract_texts_update`.
+export const CONTRACT = "Run a Python `script` in a sandbox and return its output. Accomplish tasks by WRITING CODE that calls the host functions listed below — using variables, loops, conditionals, comprehensions and arithmetic to combine many calls in one go — instead of calling tools one at a time.\n\n{sandbox} The host functions and the types below are ALREADY IN SCOPE — never import them (there is no module to import them from). Calling a `TypedDict` type builds a plain dict, as in Python. The host functions are ASYNC — you MUST `await` them — so structure every script like this:\n\n    import asyncio\n    async def main():\n        ...                 # await host functions here\n        return <final value>\n    asyncio.run(main())\n\nThe value of the script's LAST EXPRESSION becomes the result (along with anything you `print`). Run INDEPENDENT host calls CONCURRENTLY with `asyncio.gather(...)`; only await sequentially when a later call needs an earlier call's result. Host results come back as plain dicts/lists/scalars — index into them with normal Python (e.g. `results[0][\"field\"]`). A host function that fails RAISES at its `await`: catch it with `try`/`except Exception` to handle the failure, or let it propagate to end the script with an error.\n\nYour script is STATICALLY TYPE-CHECKED against the host-function signatures below BEFORE it runs: a wrong argument type, or reading a result key that doesn't exist, comes back as an error to fix rather than a result. The signatures and result shapes below are exact — only the listed keys exist.\n\nHost functions available:\n\n{interface}\n{filesystem}{guide}";
+export const FILESYSTEM_STUB = "import os as _os\nimport typing as _typing\ndef open(file: str | _os.PathLike[str], mode: str = \"r\", encoding: str | None = None) -> _typing.IO[_typing.Any]: ...\nclass FileNotFoundError(OSError): ...\nclass FileExistsError(OSError): ...\nclass IsADirectoryError(OSError): ...\nclass NotADirectoryError(OSError): ...\nclass PermissionError(OSError): ...";
+export const NO_FILESYSTEM = "The sandbox has no filesystem, no network, and no imports except `asyncio` and the host functions below.";
+export const WITH_FILESYSTEM = "The sandbox has no network, and no imports except `asyncio`, `pathlib` and the host functions below. It has the filesystem listed under Filesystem below: read and write it with `open()` and `pathlib.Path`. File operations are synchronous (never `await` them) and work on whole files; read lines with `f.read().splitlines()`, not `for line in f`. A failed file operation raises an `OSError` subclass (`FileNotFoundError`, `FileExistsError`, `IsADirectoryError`, `NotADirectoryError`, `PermissionError`) whose message names the path; it has no `errno`.";

package/dist/src/harness/code-mode/tool.d.ts

@@ -0,0 +1,37 @@
+import { type AnyHarnessTool, type HarnessTool } from "../agent.ts";
+import { type TypeCheckStubs } from "./stubs.ts";
+import { type Mount } from "./vfs.ts";
+/** The model-facing listing of the mounts. */
+export declare function renderFilesystem(mounts: readonly Mount[]): string;
+export interface CodeModeOptions {
+    name: string;
+    /** Applies to the run-code tool only; each host call re-enters the gate under its own tool. */
+    inherentlySafe?: boolean;
+    autoApprovalCriteria?: string;
+    /** Values for the tools' injected parameters, supplied to every host call. */
+    injections?: Record<string, unknown>;
+    /** Bounds one sandbox step's activity (compile-to-first-batch or resume-to-next-batch). */
+    stepTimeout?: string | number;
+    /**
+     * Extra contract text appended for the model (Python's OKF guide). Empty leaves the
+     * description unchanged.
+     */
+    guide?: string;
+    /**
+     * The sandbox's virtual filesystem, as mounts at distinct, non-nested paths. Each
+     * file operation a script makes is carried out as fs_* tool calls through the runner, so it is
+     * subject to the approval policy and publishes tool lifecycle events. Build the mounts' backends
+     * in `create`, so each workflow has its own.
+     */
+    mounts?: readonly Mount[];
+}
+export type CodeModeTool = HarnessTool<{
+    script: string;
+}, string> & {
+    /** The type-check stubs scripts are checked against. */
+    readonly codeModeStubs: TypeCheckStubs;
+    readonly stepTimeout: string | number;
+};
+export declare function codeModeTool(tools: readonly AnyHarnessTool[], options: CodeModeOptions): CodeModeTool;
+/** Type-check a `script` against a Code Mode tool's host functions without running it. */
+export declare function codeModeTypeCheck(codeTool: CodeModeTool, script: string): Promise<string | null>;

package/dist/src/harness/code-mode/tool.js

@@ -0,0 +1,79 @@
+// Code Mode: expose a set of harness tools to a model as ONE tool that runs a model-written Python
+// script in Monty, the Python harness's sandbox, where the tools are async host functions.
+// Independent host calls awaited together run concurrently as durable tool calls, and every host
+// call goes through its own tool's approval gate and lifecycle. The script runs to completion in
+// a `CodeModeDriver` (driver.ts). What the model is told is contract/code_mode/'s text
+// (texts.ts).
+import { proxyActivities } from "@temporalio/workflow";
+import { z } from "zod";
+import { tool as harnessTool } from "../agent.js";
+import { currentToolCall } from "../agent-workflow.js";
+import { CodeModeDriver, DEFAULT_STEP_TIMEOUT, STEP_RETRY, } from "./driver.js";
+import { renderHostInterface, renderTypeCheckStubs } from "./stubs.js";
+import { CONTRACT, FILESYSTEM_STUB, NO_FILESYSTEM, WITH_FILESYSTEM } from "./texts.js";
+import { validateMounts } from "./vfs.js";
+/** The model-facing listing of the mounts. */
+export function renderFilesystem(mounts) {
+    if (!mounts.length)
+        return "";
+    const lines = mounts.map((m) => `- \`${m.path}\` (${m.readOnly ? "read-only" : "writable"})${m.description ? `: ${m.description}` : ""}`);
+    return `\nFilesystem:\n\n${lines.join("\n")}\n`;
+}
+function validateTools(tools) {
+    const byName = new Map();
+    for (const tool of tools) {
+        if (byName.has(tool.name))
+            throw new TypeError(`duplicate host-function name '${tool.name}' in this codeModeTool.`);
+        byName.set(tool.name, tool);
+    }
+    return byName;
+}
+export function codeModeTool(tools, options) {
+    const mounts = validateMounts(options.mounts ?? []);
+    if (tools.length === 0 && mounts.length === 0)
+        throw new TypeError("codeModeTool requires at least one tool or mount.");
+    const toolsByName = validateTools(tools);
+    const stepTimeout = options.stepTimeout ?? DEFAULT_STEP_TIMEOUT;
+    // Generated once at construction: an unrenderable type throws now, not at script time.
+    const rendered = renderTypeCheckStubs(tools);
+    const stubs = mounts.length
+        ? { ...rendered, source: `${rendered.source}\n${FILESYSTEM_STUB}\n` }
+        : rendered;
+    const fill = {
+        sandbox: mounts.length ? WITH_FILESYSTEM : NO_FILESYSTEM,
+        interface: tools.length ? renderHostInterface(tools) : "(none)",
+        filesystem: renderFilesystem(mounts),
+        guide: options.guide ?? "",
+    };
+    // One pass, so a placeholder inside a filled-in value is left as it is.
+    const description = CONTRACT.replace(/\{(sandbox|interface|filesystem|guide)\}/g, (_, key) => fill[key]);
+    const injections = options.injections ?? {};
+    const tool = harnessTool({
+        name: options.name,
+        description,
+        inputSchema: z.object({ script: z.string() }),
+        outputSchema: z.string(),
+        inherentlySafe: options.inherentlySafe ?? true,
+        ...(options.autoApprovalCriteria ? { autoApprovalCriteria: options.autoApprovalCriteria } : {}),
+        execute: async ({ script }) => {
+            const { runner } = currentToolCall(`codeModeTool '${options.name}'`);
+            const driver = new CodeModeDriver(runner, toolsByName, {
+                injections,
+                stubs,
+                mounts,
+                stepTimeout,
+            });
+            return driver.runScript(script);
+        },
+    });
+    // Read back by codeModeTypeCheck, so a script can be checked against these exact stubs.
+    return Object.assign(tool, { codeModeStubs: stubs, stepTimeout });
+}
+/** Type-check a `script` against a Code Mode tool's host functions without running it. */
+export async function codeModeTypeCheck(codeTool, script) {
+    const { code_type_check } = proxyActivities({
+        startToCloseTimeout: codeTool.stepTimeout,
+        retry: STEP_RETRY,
+    });
+    return (await code_type_check(script, codeTool.codeModeStubs)) || null;
+}