@temporalio/agent-harness 0.2.0 → 0.3.0

package/skills/temporal-harness-typescript/references/advanced.md

@@ -0,0 +1,57 @@
+# Advanced TypeScript features
+
+Read the installed package's public types and the agent's generated schema for exact signatures.
+Prefer a small change to the working starter over copying internal runtime implementation.
+
+- **Observable state:** declare state on the agent, initialize it through its schema, and mutate
+  through the provided state reference. Mutations publish patches; changing an unrelated local
+  object does not publish observable state. Keep mutation callbacks synchronous.
+- **Approvals:** distinguish permission to run a tool from supplying a callback result. Preserve
+  the requesting agent and tool IDs, especially for subagents. See `api.md` for HTTP calls.
+- **Callbacks:** the tool implementation runs on the client; model execution waits for a result.
+  Use the application client's callback handlers or pending callback interface.
+- **Subagents:** expose typed handlers and compose through the harness subagent APIs. Follow
+  events using their agent identity rather than flattening the tree into the parent's transcript.
+- **Code Mode:** requires the optional Monty sandbox dependency on the worker. Expose an explicit
+  toolset; scripts run against those host functions. Filesystem mounts and durable activity
+  filesystems have separate declarations and worker registrations.
+- **Mid-turn handlers:** choose enqueue/accept/reject intentionally. Use `/api/messages` plus
+  `/api/attach` for clients that support messages joining an existing turn.
+
+For complete worked examples matching a release, use the repository's release-tagged Monty and
+OpenAI examples. A checkout is optional for normal application development. Do not assume Python
+and TypeScript model integrations or advanced feature signatures are interchangeable.
+
+## Add observable state to the starter
+
+Import `state` from `@temporalio/agent-harness`. Add a declaration to `defineAgent` and read its
+reference from the `create` context:
+
+```ts
+// Alongside handlers in defineAgent({...}):
+states: { counter: state(z.object({ messages: z.number().int().default(0) })) },
+
+// In create({ runner, state }), inside a handler:
+state.counter.mutate(draft => { draft.messages += 1; });
+```
+
+Read `state.counter.current` for the current value. Mutation callbacks must be synchronous.
+Regenerate the agent schema; client codegen then exposes the `counter` state.
+
+## Choose a tool boundary
+
+| Work | Public declaration | Registration |
+| --- | --- | --- |
+| Deterministic, fast computation | `tool({ ..., execute })` | Adapt through the model integration |
+| External I/O, database or provider calls | `activityTool({ ..., activityOptions })` | `new AgentHarnessPlugin({ tools: [toolActivity(declaration, implementation)] })` on the worker |
+| Browser/user environment | `tool({ ..., outputSchema })` without `execute` | Supply the result through the application client |
+
+Declarations come from `@temporalio/agent-harness`; `toolActivity` comes from
+`@temporalio/agent-harness-worker`. Keep implementations with Node/network imports out of the
+workflow bundle. Set timeouts and make side effects idempotent across retries. `inherentlySafe`
+is an explicit approval-policy decision. Use `injected<T>()` bindings for workflow-supplied
+values that should stay out of model input schemas.
+
+`subagentToolset` and `codeModeTool` are exported from the core package. Code Mode also needs
+`@pydantic/monty` on the worker. Inspect their installed declarations for lifecycle, mounting,
+and toolset options. Keep each child's registry, worker queue, and generated interface aligned.

package/skills/temporal-harness-typescript/references/api.md

@@ -0,0 +1,110 @@
+# Harness API and session lifecycle
+
+The shared Python server serves the same HTTP API and browser console for Python and TypeScript
+agents. Run a Temporal service, session-manager worker, API server, and your agent worker with
+the same connection and namespace. Worker task queues must match the registry.
+
+## Discover and start
+
+`GET /api/agents` lists registered workflow types, init-data schemas, and worker poller status.
+A poller indicates availability on a queue, not proof that it hosts a particular workflow type.
+`GET /api/sessions` lists sessions. Create one using the **workflow type**, not the registry key:
+
+```bash
+curl --fail-with-body http://localhost:8000/api/sessions \
+  -H 'Content-Type: application/json' \
+  -d '{"agent_workflow_type":"OpenAIHelloAgentTs"}'
+```
+
+The response's `workflow_id` is the session ID used by subsequent calls. An optional `session_id`
+lets an integration derive a stable ID from its own conversation identity; repeated creation
+with the same ID is idempotent. Supply `data` when the agent requires init data. Do not send it
+for an agent that takes none. The server checks presence and the agent validates its schema.
+Read `GET /api/agent-interface/{session_id}` for handlers and their input/output schemas.
+
+## Send and observe separately
+
+Use `POST /api/messages` for typed messages:
+
+```json
+{
+  "session_id": "the-workflow-id",
+  "message": {"type": "ask", "payload": {"text": "What's the weather in Paris?"}},
+  "request_id": "stable-id-for-this-one-delivery"
+}
+```
+
+An accepted message may open a turn, join a running turn, or be queued. Acceptance is not
+completion. Save the returned `message_id` and follow the event stream for its result. Reuse
+`request_id` only when retrying the same delivery; distinct user messages need distinct IDs.
+
+Attach with `GET /api/attach?session_id=...&from_offset=0` (URL-encode the ID). The response is
+SSE (`text/event-stream`). Events carry JSON data, including `resume_offset` when available.
+Save the last processed resume offset and pass it as `from_offset` on reconnect. Do not assume
+browser `Last-Event-ID` is the resume mechanism. Read the event's handler/message/agent identity:
+a session can contain queued messages, mid-turn handlers, and subagent events.
+
+Use the published `@temporalio/agent-harness-client`, React, or Svelte clients when possible;
+they implement stream/state handling. `POST /api/chat` is a convenience for a turn it opens;
+use message submission plus attach for general application clients and mid-turn handlers.
+
+## Human interaction
+
+`POST /api/approve` takes `session_id`, `tool_id`, `approved`, optional `reason`, and optional
+`remember`. An approval authorizes the pending tool; it does not provide a callback result.
+
+`POST /api/callback-result` takes `session_id`, `tool_id`, and `result` or `error`. A callback
+executes in the client environment. Preserve the identity of the agent requesting it; a UI may
+be answering a subagent's request. The client SDK handles routing across the agent tree.
+
+## State, status, and closing
+
+Apply a state snapshot before its subsequent patches, in stream order. Use the SDK's state
+implementation instead of treating every event as a complete state document.
+
+- `GET /api/status/{session_id}`: current turn, pending work, and agent status.
+- `GET /api/workflow-status/{workflow_id}`: execution status.
+- `POST /api/sessions/{session_id}/close`: signal the agent to wind down and settle pending interactions.
+
+Disconnecting an SSE stream does **not** close the agent. A network error is not evidence that
+its workflow has ended. Reconnect; only treat an explicit not-found/closed result as terminal.
+
+## Errors and schemas
+
+Check HTTP status before parsing a success response. Invalid init-data presence returns 422;
+other errors may contain `error`/`message` or FastAPI's `detail`. Do not retry a rejected payload
+unchanged. On a transport failure, retry a submission using its original request ID.
+
+The running server exposes `/openapi.json` and `/docs`, generated from its route declarations.
+To save the HTTP contract while the server is running:
+
+```bash
+curl --fail-with-body http://localhost:8000/openapi.json -o openapi.json
+```
+
+Generate an agent's schema from its declaration:
+
+```bash
+# Python
+temporal-agent-harness schema my_agent.workflow:OpenAIHelloAgentWorkflow -o agent.schema.json
+# TypeScript: compile first (agent-harness-schema is the same command)
+agent-harness schema ./dist/agents.js#OpenAIHelloAgentTs -o agent.schema.json
+# Either schema can generate a typed application client
+harness-codegen agent.schema.json -o Agent.ts
+```
+
+The code generator is distributed as `@temporalio/agent-harness-codegen`. Regenerate and commit
+client types after changing handlers, state, or init data. Never patch generated types manually.
+
+## Registry and deployment
+
+`agents.toml` declares a key, workflow type, task queue, label, description, and optional schema
+path relative to the TOML file. Keep the schema's agent name equal to `workflow_type`. The server
+never imports your agent implementation. The session manager caches its registry: replacing the
+registry file alone does not update an already-running manager's list. Restart with fresh local
+Temporal state only when the development sessions are disposable.
+
+The built-in local payload store is for processes sharing a host/filesystem. For a multi-host
+deployment, configure a shared offload store consistently across clients, workers, and server.
+Expose the API through your application's authentication boundary when deploying beyond local
+development. Embedding the FastAPI app lets you add your own middleware and routes.

package/skills/temporal-harness-typescript/references/authoring.md

@@ -0,0 +1,65 @@
+# TypeScript authoring
+
+Use `@temporalio/agent-harness` in workflow modules and `@temporalio/agent-harness-worker` on the
+Node worker. `npx agent-harness init ./my-agent` materializes a runnable OpenAI starter. The same
+starter is installed with this skill under `assets/starter/`; read `agents.ts.tmpl` and
+`worker.ts.tmpl` there for the complete wiring. Its exact Temporal SDK versions match the model
+plugin; keep those versions aligned. Harness package versions are separate from the underlying
+Temporal SDK versions. Compile ESM before starting.
+
+A minimal agent, with a safe inline tool and a model-free handler:
+
+```ts
+import { z } from "zod";
+import { TextMessage, TextReply, ToolApprovalPolicy, defineAgent, handler, tool } from "@temporalio/agent-harness";
+
+export const getWeather = tool({
+  name: "get_weather",
+  description: "Return sample weather for a city.",
+  inputSchema: z.object({ city: z.string() }),
+  outputSchema: z.string(),
+  inherentlySafe: true,
+  execute: async ({ city }) => `It's 72°F and sunny in ${city}.`,
+});
+
+export const HelloAgent = defineAgent({
+  name: "HelloAgent",
+  approvalPolicyDefault: ToolApprovalPolicy.allowInherentlySafe(),
+  handlers: {
+    ping: handler({ description: "Echo without a model call.", input: TextMessage, output: TextReply }),
+  },
+  create: ({ runner }) => ({
+    async ping({ text }) {
+      return { text };
+    },
+  }),
+});
+```
+
+The starter's `ask` handler adds the model turn: it passes `getWeather` through
+`asOpenAIAgentTool(runner, ...)` and awaits `runStreamed(runner, sdkAgent, input, ...)`.
+
+Public authoring imports come from `@temporalio/agent-harness`: `defineAgent`, `handler`, `tool`,
+`state`, `TextMessage`, `TextReply`, and `ToolApprovalPolicy`. Use Zod schemas for inputs and
+outputs. `defineAgent({ name, handlers, create })` returns the workflow export; `create` receives
+its runner, init data, and declared state references. Keep Node imports and external I/O in the
+worker or activities, not in the workflow module.
+
+Use `ToolApprovalPolicy.allowInherentlySafe()` for tools explicitly marked `inherentlySafe`.
+For OpenAI, import `asOpenAIAgentTool` and `runStreamed` from
+`@temporalio/agent-harness/ai-sdks/openai-agents-harness`. Consume the stream and await completion.
+Keep conversation history inside the agent instance. The worker's `OpenAIAgentsPlugin` comes from
+`@temporalio/agent-harness-worker/ai-sdks/openai-agents`, followed by `AgentHarnessPlugin`.
+Activity tool implementations are registered using `toolActivity` on the harness plugin.
+
+Point `workflowsPath` at the compiled agent module. Generate its schema with
+`agent-harness schema ./dist/agents.js#Export -o Agent.schema.json` (the `agent-harness-schema`
+binary is the same command). The registry's `workflow_type`
+must match `defineAgent`'s `name`, and its queue must match the worker. The schema CLI does not
+start Temporal. The shared Python server reads the schema without importing TypeScript code.
+
+The shared services come from the Python package: the starter's `npm run harness:dev` runs
+`temporal-agent-harness dev agents.toml` through `uvx`, beside Temporal and the Node worker.
+`npx agent-harness doctor --schema Agent.schema.json` checks the installed package, schema, API,
+and agent worker availability. For direct Temporal connection and local TOML validation, use the
+shared Python CLI's `doctor --registry agents.toml`. Both support `--json` and never reset services.

package/skills/temporal-harness-typescript/references/verification.md

@@ -0,0 +1,17 @@
+# Verification and troubleshooting
+
+Validate against the installed SDK version. Run the starter's schema command before launching
+services. A successful check includes discovering the agent, creating a session, sending a typed
+message, seeing a tool result and completed reply, and reconnecting to the same session.
+Use a scripted model for repeatable automated tests; do not claim a scripted response is a live
+provider test. Test approval/callback paths separately when your agent uses them.
+
+If the console loads but cannot start a session, check the session-manager worker. If a session
+exists but messages stall, check the agent worker, task queue, and namespace. If a model fails,
+check the worker's provider credentials and optional integration dependencies. If registration
+changes appear stale, inspect the session manager's cached registry before replacing local state.
+
+Keep the Temporal server, namespace, and task queues isolated for tests. Do not terminate unrelated
+sessions or reset a user's existing development server to make a test pass. Temporal workflow code
+must remain deterministic; move external I/O into activities. Replaying a completed activity uses
+its recorded result, but retryable activities with side effects still need idempotent design.