@temporalio/agent-harness-codegen 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Temporal Technologies Inc. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @temporalio/agent-harness-codegen
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generate TypeScript application types from a Python or TypeScript harness agent's JSON Schema.
+The generator is a public npm package starting with the next npm release; it was previously
+repository-only tooling. No checkout or Bazel installation is needed to use the package.
+
+```bash
+npm install --save-dev --save-exact @temporalio/agent-harness-codegen@0.3.0
+# Export the schema using the SDK that defines your agent:
+uv run temporal-agent-harness schema my_agent.workflow:OpenAIHelloAgentWorkflow -o agent.schema.json
+# or: npx agent-harness-schema ./dist/agents.js#OpenAIHelloAgentTs -o agent.schema.json
+npx harness-codegen agent.schema.json -o Agent.ts
+```
+
+The version above tracks this development branch and becomes installable when released.
+Use the same release version as your other npm harness packages.
+
+The output has an interface per model the agent exposes (its `@agent.accepts` input and output
+models and its `agent.state(...)` types) and one mapping type naming them:
+
+```ts
+export interface TicTacToeAgent {
+  handlers: {
+    new_game: { input: NewGame; output: TextReply };
+    play: { input: PlayMove; output: TextReply };
+  };
+  states: {
+    board: Board;
+  };
+}
+```
+
+Handler inputs are typed as a sender writes them (a field with a default is optional); handler
+outputs and states as they arrive on the wire (every field present). Tool inputs and outputs are
+not typed.
+
+Options: `-o <file>` writes to a file instead of stdout; `--name <TypeName>` renames the mapping
+type, which defaults to the agent's workflow type name.
+
+`--json-schemas` also writes `<TypeName>Schemas`: each handler's input and output as JSON Schema,
+so you can check a message or a reply at runtime with any validator. Each schema is
+self-contained (a `$ref` plus just the `$defs` it reaches), and the constant is `as const` for
+tools that derive types from schemas. For example, with Ajv:
+
+```ts
+import Ajv from "ajv";
+import { TicTacToeAgentSchemas } from "./TicTacToeAgent";
+
+const validPlay = new Ajv().compile(TicTacToeAgentSchemas.play.input);
+if (!validPlay(move)) console.warn(validPlay.errors);
+```
+
+It is off by default, so the generated files examples commit stay as they are.
+
+## The event protocol
+
+With `--protocol`, it reads `temporal-agent-harness schema --protocol` instead and writes the
+event stream's types. The client package (`typescript/packages/client`) commits that output as
+its `src/protocol.ts`; `bazel run //typescript/packages/client/src:protocol_codegen_update` regenerates it.
+
+## Development
+
+```sh
+bazel test //typescript/packages/codegen/...   # one target per test file, e.g. //typescript/packages/codegen/test:generate_test
+```
+
+Without Bazel, from this directory:
+
+```sh
+pnpm install
+pnpm test   # compiles src/ and test/ (including compile-time type checks), then runs node --test
+```
+
+`test/golden/TicTacToeAgent.ts` is generated from the tic-tac-toe example's committed schema,
+`python/examples/tictactoe/TicTacToeAgent.schema.json`;
+`bazel run //typescript/packages/codegen/test/golden:golden_update` regenerates it.

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// harness-codegen <schema.json | -> [-o <out.ts>] [--name TypeName] [--json-schemas] [--protocol]
+import { readFileSync, writeFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { generateAgentTypes, generateProtocolTypes } from "./generate.js";
+const USAGE = `usage: harness-codegen <schema.json | -> [-o <out.ts>] [--name <TypeName>] [--json-schemas] [--protocol]
+
+Reads the document \`temporal-agent-harness schema module:Class\` prints (from a file, or
+stdin for -) and writes TypeScript types for the agent: one interface per model, and a
+mapping type naming each handler's input and output and each declared state. With
+--json-schemas, also writes each handler's input and output JSON Schema as a constant.
+
+With --protocol, reads \`temporal-agent-harness schema --protocol\` instead and writes the
+event stream's types.`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            output: { type: "string", short: "o" },
+            name: { type: "string" },
+            protocol: { type: "boolean" },
+            "json-schemas": { type: "boolean" },
+            help: { type: "boolean", short: "h" }
+        }
+    });
+    if (values.help || positionals.length !== 1) {
+        console.error(USAGE);
+        process.exit(values.help ? 0 : 2);
+    }
+    const input = positionals[0] === "-" ? readFileSync(0, "utf8") : readFileSync(positionals[0], "utf8");
+    const doc = JSON.parse(input);
+    const source = values.protocol
+        ? await generateProtocolTypes(doc)
+        : await generateAgentTypes(doc, {
+            typeName: values.name,
+            jsonSchemas: values["json-schemas"]
+        });
+    if (values.output === undefined)
+        process.stdout.write(source);
+    else
+        writeFileSync(values.output, source);
+}
+main().catch((error) => {
+    console.error(`harness-codegen: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});

package/dist/src/generate.d.ts

@@ -0,0 +1,38 @@
+import { type JSONSchema } from "json-schema-to-typescript";
+/** The document `temporal-agent-harness schema module:Class` prints. */
+export interface AgentSchemaDocument {
+    agent: string;
+    source: string;
+    /** Absent in documents from before init data existed; treated as `null`. */
+    init_data?: {
+        data: SchemaRef;
+        required: boolean;
+    } | null;
+    handlers: Record<string, {
+        description: string;
+        mid_turn: string;
+        input: SchemaRef;
+        output: SchemaRef;
+    }>;
+    states: Record<string, SchemaRef>;
+    $defs: Record<string, JSONSchema>;
+}
+/** The document `temporal-agent-harness schema --protocol` prints. */
+export interface ProtocolSchemaDocument {
+    event: SchemaRef;
+    stream_items: SchemaRef[];
+    $defs: Record<string, JSONSchema>;
+}
+interface SchemaRef {
+    $ref: string;
+}
+export interface GenerateOptions {
+    /** Name of the mapping type. Defaults to the agent's workflow type name. */
+    typeName?: string;
+    /** Also emit `<typeName>Schemas`: each handler's input and output as JSON Schema, for
+     *  validating them at runtime with any validator. */
+    jsonSchemas?: boolean;
+}
+export declare function generateAgentTypes(doc: AgentSchemaDocument, options?: GenerateOptions): Promise<string>;
+export declare function generateProtocolTypes(doc: ProtocolSchemaDocument): Promise<string>;
+export {};

package/dist/src/generate.js

@@ -0,0 +1,233 @@
+// TypeScript types from the documents `temporal-agent-harness schema` prints. For one agent:
+// an interface per model in its `$defs`, one mapping type naming its init data, every
+// handler's input and output and every declared state, and a same-named definition value that
+// `startSession` takes. For the event protocol (`--protocol`): an interface
+// per event payload and the envelope, plus the union of payloads and of their `type`s.
+import { compile } from "json-schema-to-typescript";
+const REF_PREFIX = "#/$defs/";
+const ROOT = "HarnessCodegenRoot";
+// Constraints json-schema-to-typescript drops, carried into the JSDoc instead.
+const CONSTRAINT_KEYWORDS = [
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "minLength",
+    "maxLength",
+    "pattern",
+    "minItems",
+    "maxItems"
+];
+// Keywords whose values are data rather than schemas, so they are copied as they are.
+const DATA_KEYWORDS = new Set(["default", "examples", "const", "enum"]);
+export async function generateAgentTypes(doc, options = {}) {
+    const names = typeNames(Object.keys(doc.$defs));
+    const typeName = options.typeName ?? safeName(doc.agent);
+    for (const name of options.jsonSchemas ? [typeName, `${typeName}Schemas`] : [typeName]) {
+        if ([...names.values()].includes(name)) {
+            throw new Error(`the generated name ${name} is also the name of one of the agent's models; ` +
+                "pass a different type name");
+        }
+    }
+    return [
+        `// GENERATED by @temporal-agent-harness/codegen from ${doc.source}. Do not edit.`,
+        "",
+        await compileModels(doc.$defs, names),
+        "",
+        mappingType(doc, typeName, names),
+        "",
+        definitionValue(doc, typeName),
+        ...(options.jsonSchemas ? ["", handlerSchemas(doc, typeName)] : []),
+        ""
+    ].join("\n");
+}
+/** Every handler's input and output as a self-contained JSON Schema: a `$ref` to its model,
+ *  with `$defs` holding just the models that one reaches. */
+function handlerSchemas(doc, typeName) {
+    const standalone = (ref) => {
+        const $defs = {};
+        const visit = (node) => {
+            if (Array.isArray(node))
+                return node.forEach(visit);
+            if (node === null || typeof node !== "object")
+                return;
+            for (const [key, value] of Object.entries(node)) {
+                if (key !== "$ref" || typeof value !== "string")
+                    visit(value);
+                else if (value.startsWith(REF_PREFIX) && !(value.slice(REF_PREFIX.length) in $defs)) {
+                    const name = value.slice(REF_PREFIX.length);
+                    $defs[name] = doc.$defs[name];
+                    visit($defs[name]);
+                }
+            }
+        };
+        visit(ref);
+        return { $ref: ref.$ref, $defs };
+    };
+    const schemas = Object.fromEntries(Object.entries(doc.handlers).map(([name, h]) => [name, { input: standalone(h.input), output: standalone(h.output) }]));
+    return [
+        `/** Each \`${doc.agent}\` handler's input and output as JSON Schema, to validate them with any`,
+        " *  JSON Schema validator. */",
+        `export const ${typeName}Schemas = ${JSON.stringify(schemas, null, 2)} as const;`
+    ].join("\n");
+}
+export async function generateProtocolTypes(doc) {
+    const names = typeNames(Object.keys(doc.$defs));
+    const resolve = refResolver(names);
+    const items = doc.stream_items.map(resolve);
+    return [
+        "// GENERATED by @temporal-agent-harness/codegen from the harness event protocol",
+        "// (`temporal-agent-harness schema --protocol`). Do not edit.",
+        "",
+        await compileModels(doc.$defs, names),
+        "",
+        `/** Every payload an \`${resolve(doc.event)}\` can carry, discriminated by \`type\`. */`,
+        `export type AgentStreamItem =\n${items.map((name) => `  | ${name}`).join("\n")};`,
+        "",
+        "/** The `type` of every event on the stream. */",
+        'export type AgentEventType = AgentStreamItem["type"];',
+        ""
+    ].join("\n");
+}
+async function compileModels($defs, names) {
+    const resolve = refResolver(names);
+    const defs = {};
+    for (const [key, schema] of Object.entries($defs)) {
+        defs[key] = { ...prepare(schema, resolve), title: names.get(key) };
+    }
+    const root = {
+        title: ROOT,
+        anyOf: Object.keys(defs).map((key) => ({ $ref: `${REF_PREFIX}${key}` })),
+        $defs: defs
+    };
+    const models = await compile(root, ROOT, {
+        bannerComment: "",
+        additionalProperties: false,
+        unknownAny: true,
+        strictIndexSignatures: true
+    });
+    return dropRoot(models).trim();
+}
+/** Shape a model's schema for json-schema-to-typescript, which would otherwise mint extra
+ *  named types: one per property-level title, and one per `$ref` that carries a sibling
+ *  keyword (pydantic puts a property's description next to its `$ref`). Titles are dropped
+ *  and each `$ref` becomes the referenced type's name, keeping the description. Constraints
+ *  are folded into the description. */
+function prepare(node, resolve) {
+    if (Array.isArray(node))
+        return node.map((item) => prepare(item, resolve));
+    if (node === null || typeof node !== "object")
+        return node;
+    if (typeof node.$ref === "string") {
+        const { description } = node;
+        return {
+            tsType: resolve(node),
+            ...(typeof description === "string" ? { description: fromSphinx(description) } : {})
+        };
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "title")
+            continue;
+        if (DATA_KEYWORDS.has(key))
+            out[key] = value;
+        else if (key === "properties" || key === "$defs" || key === "patternProperties")
+            out[key] = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, prepare(v, resolve)]));
+        else
+            out[key] = prepare(value, resolve);
+    }
+    if (typeof out.description === "string")
+        out.description = fromSphinx(out.description);
+    const tags = CONSTRAINT_KEYWORDS.filter((k) => k in out).map((k) => `@${k} ${String(out[k])}`);
+    if (tags.length > 0) {
+        const description = typeof out.description === "string" ? `${out.description}\n\n` : "";
+        out.description = description + tags.join("\n");
+    }
+    return out;
+}
+/** Python docstrings use reStructuredText roles; JSDoc renders Markdown. */
+function fromSphinx(text) {
+    return text
+        .replace(/:[a-z]+:`~?([^`]+)`/g, "`$1`")
+        .replace(/``([^`]+)``/g, "`$1`");
+}
+function refResolver(names) {
+    return (ref) => {
+        const key = ref.$ref.startsWith(REF_PREFIX) ? ref.$ref.slice(REF_PREFIX.length) : undefined;
+        const name = key === undefined ? undefined : names.get(key);
+        if (name === undefined)
+            throw new Error(`unresolvable $ref ${ref.$ref}`);
+        return name;
+    };
+}
+function mappingType(doc, typeName, names) {
+    const resolve = refResolver(names);
+    const handlers = Object.entries(doc.handlers).map(([name, h]) => `${jsdoc(h.description, "    ")}    ${name}: { input: ${resolve(h.input)}; output: ${resolve(h.output)} };`);
+    const states = Object.entries(doc.states).map(([id, ref]) => `    ${id}: ${resolve(ref)};`);
+    const block = (lines) => lines.length === 0 ? "Record<never, never>" : `{\n${lines.join("\n")}\n  }`;
+    const initData = doc.init_data
+        ? `{ data: ${resolve(doc.init_data.data)}; required: ${doc.init_data.required} }`
+        : "null";
+    return [
+        `/** The \`${doc.agent}\` agent's init data, handlers (message in, reply out) and observable`,
+        " *  state. */",
+        `export interface ${typeName} {`,
+        `  initData: ${initData};`,
+        `  handlers: ${block(handlers)};`,
+        `  states: ${block(states)};`,
+        "}"
+    ].join("\n");
+}
+/** The value `startSession` takes, named like the mapping type (a type and a value may share a
+ *  name). Its type carries the mapping type as a phantom `schema`, so the file needs no import. */
+function definitionValue(doc, typeName) {
+    const workflowType = JSON.stringify(doc.agent);
+    return [
+        `/** Pass to \`startSession\` to start a \`${doc.agent}\` session. */`,
+        `export const ${typeName}: { readonly workflowType: ${workflowType}; readonly schema?: ${typeName} } = {`,
+        `  workflowType: ${workflowType}`,
+        "};"
+    ].join("\n");
+}
+function jsdoc(text, indent) {
+    const lines = text.trim().replaceAll("*/", "*\\/").split("\n");
+    if (lines.length === 0 || lines[0] === "")
+        return "";
+    if (lines.length === 1)
+        return `${indent}/** ${lines[0]} */\n`;
+    return `${indent}/**\n${lines.map((l) => `${indent} * ${l}`.trimEnd()).join("\n")}\n${indent} */\n`;
+}
+/** The generated name for every `$defs` key, rejecting two keys that would share one. */
+function typeNames(keys) {
+    const names = new Map();
+    const owners = new Map();
+    for (const key of keys) {
+        const name = safeName(key);
+        const other = owners.get(name);
+        if (other !== undefined) {
+            throw new Error(`models ${other} and ${key} would both be generated as ${name}`);
+        }
+        owners.set(name, key);
+        names.set(key, name);
+    }
+    return names;
+}
+/** A TypeScript identifier for a schema name: `Echo-Input` → `EchoInput`. Already-safe
+ *  PascalCase names come back unchanged, which json-schema-to-typescript also leaves alone. */
+function safeName(raw) {
+    const name = raw
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join("");
+    if (!/^[A-Za-z]/.test(name))
+        throw new Error(`cannot derive a type name from ${raw}`);
+    return name;
+}
+function dropRoot(source) {
+    const start = source.indexOf(`export type ${ROOT} =`);
+    if (start === -1)
+        return source;
+    const end = source.indexOf(";\n", start);
+    return source.slice(0, start) + source.slice(end + 2);
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@temporalio/agent-harness-codegen",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Generate TypeScript types for a temporal-agent-harness agent from its `temporal-agent-harness schema` document.",
+  "bin": {
+    "harness-codegen": "dist/src/cli.js"
+  },
+  "dependencies": {
+    "json-schema-to-typescript": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "typescript": "^7.0.2"
+  },
+  "license": "MIT",
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/temporal-community/temporal-agent-harness.git",
+    "directory": "typescript/packages/codegen"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --outDir dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json --outDir dist && node --test dist/test/*.test.js"
+  }
 }