@temporalio/agent-harness 0.2.0 → 0.3.0

package/dist/src/harness/agent-workflow.js

@@ -6,9 +6,10 @@
 // Ambient context (Python's contextvars) is AsyncLocalStorage: the participant's message id is
 // set once per handler task, and the in-flight tool call (runner, tool id, injections) is set by
 // `runTool` for exactly one invocation. Both are read only inside this package.
-import { ApplicationFailure, AsyncLocalStorage, CancellationScope, ParentClosePolicy, allHandlersFinished, condition, defineQuery, defineSignal, defineUpdate, getExternalWorkflowHandle, isCancellation, log, proxyActivities, setHandler, startChild, uuid4, ActivityFailure, } from "@temporalio/workflow";
+import { ApplicationFailure, AsyncLocalStorage, CancellationScope, ParentClosePolicy, allHandlersFinished, condition, defineQuery, defineSignal, defineUpdate, getExternalWorkflowHandle, log, proxyActivities, setHandler, startChild, uuid4, ActivityFailure, } from "@temporalio/workflow";
+import { msToNumber } from "@temporalio/common/lib/time.js";
 import { WorkflowStream } from "@temporalio/workflow-streams/workflow";
-import { AGENT_ID_LENGTH, AGENT_INTERFACE_QUERY, AGENT_STATUS_QUERY, APPROVAL_SHORT_ID_LENGTH, AgentMessageSchema, AutoApprovalCriteria, ApprovalVerdict, WIRE_VERDICT, CLOSE_SIGNAL, CallbackResultSchema, DEFAULT_SUBAGENT_HEARTBEAT_TIMEOUT, DEFAULT_SUBAGENT_START_TO_CLOSE_TIMEOUT, MessageDisposition, MidTurn, PROVIDE_CALLBACK_RESULT_UPDATE, SEND_AGENT_MESSAGE_UPDATE, TOOL_APPROVAL_UPDATE, TURN_EVENTS_TOPIC, ToolApprovalDecisionSchema, ToolApprovalPolicy, toJsonSchema, validate, } from "./agent-protocol/index.js";
+import { AGENT_ID_LENGTH, AGENT_INTERFACE_QUERY, AGENT_STATUS_QUERY, APPROVAL_SHORT_ID_LENGTH, AgentMessageSchema, AutoApprovalCriteria, ApprovalVerdict, WIRE_VERDICT, CLOSE_SIGNAL, CallbackResultSchema, CloseReason, DEFAULT_SUBAGENT_HEARTBEAT_TIMEOUT, DEFAULT_SUBAGENT_START_TO_CLOSE_TIMEOUT, MessageDisposition, MidTurn, PROVIDE_CALLBACK_RESULT_UPDATE, SEND_AGENT_MESSAGE_UPDATE, TOOL_APPROVAL_UPDATE, TURN_EVENTS_TOPIC, ToolApprovalDecisionSchema, ToolApprovalPolicy, toJsonSchema, validate, } from "./agent-protocol/index.js";
 import { StateRef } from "./state/index.js";
 import { CallbackToolError, ToolApprovalDenied, assertAutoModeHasEvaluator, assertPortableJson, errorMessage, errorText, isOwnCancellation, } from "./agent-workflow/errors.js";
 export { CallbackToolError, ToolApprovalDenied, errorText, };
@@ -53,7 +54,10 @@ export class AgentWorkflowRunner {
     #events;
     #handlers;
     #evaluator;
+    // Milliseconds idle before the runner closes the agent; null never closes on idle.
+    #closeAfterIdleMs;
     #closed = false;
+    #closeReason = null;
     #currentTurn = 0;
     #currentTurnId = null;
     #participants = 0;
@@ -74,6 +78,15 @@ export class AgentWorkflowRunner {
                 options.autoApprovalCriteriaDefault ??
                 AutoApprovalCriteria.empty();
         this.agentId = config.agent_id ?? shortHex(AGENT_ID_LENGTH);
+        const closeAfterIdleMs = config.close_after_idle !== null
+            ? config.close_after_idle * 1000
+            : options.closeAfterIdleDefault === undefined
+                ? 0
+                : msToNumber(options.closeAfterIdleDefault);
+        if (closeAfterIdleMs < 0)
+            throw new TypeError("closeAfterIdleDefault must not be negative; use 0 or omit it for never");
+        // 0 is "never", kept as null from here on so there is one spelling.
+        this.#closeAfterIdleMs = closeAfterIdleMs > 0 ? closeAfterIdleMs : null;
         this.stream = new WorkflowStream();
         this.#events = this.stream.topic(TURN_EVENTS_TOPIC);
         // Before any handler is installed: a buffered first message is dispatched by setHandler, and
@@ -95,9 +108,7 @@ export class AgentWorkflowRunner {
         });
         setHandler(agentStatusQuery, () => this.status);
         setHandler(agentInterfaceQuery, () => this.#agentInterface());
-        setHandler(closeSignal, () => {
-            this.#closed = true;
-        });
+        setHandler(closeSignal, () => this.#close(CloseReason.REQUESTED));
     }
     // -- public surface -------------------------------------------------------------------------
     get closed() {
@@ -178,6 +189,7 @@ export class AgentWorkflowRunner {
             })),
             approval_policy: this.#policy,
             has_auto_approval_evaluator: this.#evaluator !== undefined,
+            close_reason: this.#closeReason,
         };
     }
     /** Publish a payload on the current turn, attributed to the ambient message. */
@@ -203,40 +215,64 @@ export class AgentWorkflowRunner {
     }
     // -- the turn loop --------------------------------------------------------------------------
     async run(impls) {
-        try {
-            while (!this.#closed) {
-                await condition(() => this.#canOpenTurn ||
-                    this.#joining.length > 0 ||
-                    this.#closed);
-                if (this.#closed)
-                    break;
-                for (let joined = this.#joining.shift(); joined; joined = this.#joining.shift()) {
-                    void this.#runParticipant(impls, joined, true);
-                }
-                if (this.#canOpenTurn) {
-                    const admitted = this.#pendingTurns.shift();
-                    this.#currentTurn += 1;
-                    this.#currentTurnId = admitted.turn_id;
-                    this.#participants = 1;
-                    this.pub(admitted.turn_id, admitted.turn_number, { type: "turn_started" }, null);
-                    void this.#runParticipant(impls, admitted, false);
-                }
+        while (!this.#closed) {
+            await this.#waitForWork();
+            if (this.#closed)
+                break;
+            for (let joined = this.#joining.shift(); joined; joined = this.#joining.shift()) {
+                void this.#runParticipant(impls, joined, true);
             }
-            await condition(() => this.#participants === 0);
-        }
-        catch (e) {
-            if (isCancellation(e)) {
-                await CancellationScope.nonCancellable(async () => {
-                    this.stream.detachPollers();
-                    await condition(allHandlersFinished);
-                });
+            if (this.#canOpenTurn) {
+                const admitted = this.#pendingTurns.shift();
+                this.#currentTurn += 1;
+                this.#currentTurnId = admitted.turn_id;
+                this.#participants = 1;
+                this.pub(admitted.turn_id, admitted.turn_number, { type: "turn_started" }, null);
+                void this.#runParticipant(impls, admitted, false);
             }
-            throw e;
         }
-        // Parked polls are handed the last events (turn_end included) before the run completes.
+        await condition(() => this.#participants === 0);
+        if (this.#closeReason !== null)
+            this.pub("", 0, { type: "agent_closed", reason: this.#closeReason }, null);
+    }
+    /**
+     * @internal The last step of a run, after teardown: parked stream polls are handed the last
+     * events, then every handler finishes. Not before teardown, which may publish too, and whose
+     * whole duration the stream must stay readable for: a poll arriving once pollers are detached
+     * is refused.
+     */
+    async finish() {
         this.stream.detachPollers();
         await condition(allHandlersFinished);
     }
+    /**
+     * Wait until there is something for the turn loop to do, or the agent closes. With
+     * `close_after_idle` set this is also the idle clock: while the agent is idle the wait carries
+     * that timeout, and running out closes the agent; while a turn runs the wait also wakes when the
+     * agent goes idle, so the loop comes back here and starts the clock afresh.
+     */
+    async #waitForWork() {
+        const hasWork = () => this.#canOpenTurn || this.#joining.length > 0 || this.#closed;
+        if (this.#closeAfterIdleMs === null) {
+            await condition(hasWork);
+        }
+        else if (!this.#idle) {
+            await condition(() => hasWork() || this.#idle);
+        }
+        else if (!(await condition(hasWork, this.#closeAfterIdleMs)) && this.#idle) {
+            // The idle check covers a message admitted in the same workflow task as the timer firing.
+            this.#close(CloseReason.IDLE_TIMEOUT_EXPIRED);
+        }
+    }
+    /** Stop admitting messages and let the turn loop exit. The first reason sticks. */
+    #close(reason) {
+        this.#closeReason ??= reason;
+        this.#closed = true;
+    }
+    /** No turn running, nothing queued, no join waiting to be dispatched. */
+    get #idle() {
+        return !this.#hasPendingWork && this.#joining.length === 0;
+    }
     // -- the stream -----------------------------------------------------------------------------
     // WorkflowStream keeps its log private; the runner reads its head offset from it. Revisit if the
     // SDK exposes one.
@@ -301,6 +337,15 @@ export class AgentWorkflowRunner {
     }
     // -- send_agent_message ---------------------------------------------------------------------
     #validateSendAgentMessage(raw) {
+        // A closed agent's loop has exited, so an admitted message would never run.
+        if (this.#closeReason !== null) {
+            throw ApplicationFailure.create({
+                type: "AgentClosed",
+                nonRetryable: true,
+                message: `The agent is closed (${this.#closeReason}) and accepts no more messages.`,
+                details: [{ reason: this.#closeReason }],
+            });
+        }
         const message = AgentMessageSchema.parse(raw);
         assertPortableJson(message.payload, `Payload for function '${message.type}'`);
         const handler = Object.hasOwn(this.#handlers, message.type)
@@ -672,13 +717,17 @@ export class AgentWorkflowRunner {
         }, entry.message_id);
     }
     // -- subagents ------------------------------------------------------------------------------
-    /** Start a child agent; returns its short, tree-unique handle (also its agent_id). */
+    /**
+     * Start a child agent; returns its short, tree-unique handle (also its agent_id). The child never
+     * closes on idle: `close_after_idle` is always pushed down as 0, overriding both `config` and the
+     * child's own default.
+     */
     async startSubagent(agentKey, workflowType, taskQueue, { config = {}, data } = {}) {
         let handle = `${this.agentId}-${shortHex(AGENT_ID_LENGTH)}`;
         while (this.#subagents.has(handle))
             handle = `${this.agentId}-${shortHex(AGENT_ID_LENGTH)}`;
         const workflowId = `${agentKey}-subagent-${uuid4()}`;
-        const childConfig = { ...config, agent_id: handle };
+        const childConfig = { ...config, agent_id: handle, close_after_idle: 0 };
         await startChild(workflowType, {
             args: data === undefined ? [childConfig] : [childConfig, data],
             workflowId,
@@ -761,6 +810,17 @@ export class AgentWorkflowRunner {
                     (cause.type === "SubagentTurnError" || cause.type === "SubagentNoReply")) {
                     this.#publishReplyReceived(inst, msgType, acceptedTurnFromError(cause), "error");
                 }
+                if (cause instanceof ApplicationFailure && cause.type === "AgentClosed") {
+                    // Something other than this parent closed or ended the child, so the handle is dead.
+                    this.#forgetClosedSubagent(inst);
+                    throw ApplicationFailure.create({
+                        type: "AgentClosed",
+                        nonRetryable: true,
+                        message: `Subagent '${handle}' has closed and accepts no more messages. Start a new one with start_${inst.agent_key}.`,
+                        details: [{ subagent_id: handle }],
+                        cause,
+                    });
+                }
                 throw e;
             }
             inst.last_consumed_offset = result.consumed_offset;
@@ -771,6 +831,17 @@ export class AgentWorkflowRunner {
             inst.serving += 1;
         }
     }
+    /** Drop a subagent something else closed or ended; only the first send to find it publishes. */
+    #forgetClosedSubagent(inst) {
+        if (!this.#subagents.delete(inst.handle))
+            return;
+        this.publish({
+            type: "subagent_stopped",
+            subagent_id: inst.handle,
+            agent_key: inst.agent_key,
+            workflow_id: inst.workflow_id,
+        });
+    }
     #publishReplyReceived(inst, handler, subagentTurn, outcome) {
         this.publish({
             type: "subagent_reply_received",

package/dist/src/harness/agent.d.ts

@@ -1,4 +1,5 @@
 import { type ActivityOptions } from "@temporalio/workflow";
+import type { Duration } from "@temporalio/common";
 import { z } from "zod";
 import { MidTurn, ToolApprovalPolicy, type AgentConfig, type InferInput, type InferOutput, type JsonValue, type Schema, type AutoApprovalCriteria, type AutoModeEvaluator, type TurnStreamContext } from "./agent-protocol/index.ts";
 import { AgentWorkflowRunner, type HandlerDecl, type HandlerImpl } from "./agent-workflow.ts";
@@ -124,6 +125,12 @@ export interface AgentDefinition<H extends Record<string, HandlerDecl> = Record<
     approvalPolicyDefault: ToolApprovalPolicy;
     autoApprovalCriteriaDefault?: AutoApprovalCriteria;
     autoModeEvaluator?: AutoModeEvaluator;
+    /**
+     * Close the agent once it has been idle (no turn running, nothing queued) this long, publishing
+     * `agent_closed` with reason `idle_timeout_expired`. Omitted or 0 never closes on idle. A
+     * caller's `AgentConfig.close_after_idle` (seconds; 0 for never) overrides it.
+     */
+    closeAfterIdleDefault?: Duration;
     create(ctx: AgentContext<S, D>): AgentImpl<H>;
 }
 export type AgentWorkflow<Def extends AgentDefinition = AgentDefinition> = ((config?: unknown, data?: unknown) => Promise<void>) & {

package/dist/src/harness/agent.js

@@ -235,6 +235,7 @@ export function defineAgent(definition) {
             approvalPolicyDefault: definition.approvalPolicyDefault,
             autoApprovalCriteriaDefault: definition.autoApprovalCriteriaDefault,
             autoModeEvaluator: definition.autoModeEvaluator,
+            closeAfterIdleDefault: definition.closeAfterIdleDefault,
             states: definition.states,
             data,
         });
@@ -254,11 +255,16 @@ export function defineAgent(definition) {
             await runner.run(impl);
         }
         catch (e) {
-            if (isCancellation(e) && impl.teardown)
-                await CancellationScope.nonCancellable(impl.teardown);
+            if (isCancellation(e)) {
+                await CancellationScope.nonCancellable(async () => {
+                    await impl.teardown?.();
+                    await runner.finish();
+                });
+            }
             throw e;
         }
         await impl.teardown?.();
+        await runner.finish();
     };
     Object.defineProperty(workflow, "name", { value: definition.name });
     return Object.assign(workflow, { definition });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/agent-harness",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "description": "Temporal-native agent harness for TypeScript: the workflow-safe authoring API for durable agents.",
@@ -49,14 +49,16 @@
     "./ai-sdks/openai-agents-harness": {
       "types": "./dist/src/ai-sdks/openai-agents-harness.d.ts",
       "default": "./dist/src/ai-sdks/openai-agents-harness.js"
-    }
+    },
+    "./skill": "./skills/temporal-harness-typescript/SKILL.md"
   },
   "files": [
-    "dist/src"
+    "dist/src",
+    "skills"
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@temporalio/agent-harness-client": "^0.2.0",
+    "@temporalio/agent-harness-client": "^0.3.0",
     "@temporalio/common": "^1.24.0",
     "@temporalio/workflow": "^1.24.0",
     "@temporalio/workflow-streams": "^1.24.0",

package/skills/temporal-harness-typescript/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: temporal-harness-typescript
+description: Build, run, test, and integrate TypeScript agents using the Temporal Agent Harness SDK and shared harness API. Use for agent authoring, tools, approvals, state, session clients, or startup troubleshooting in applications using this SDK.
+---
+
+# Temporal Agent Harness for TypeScript
+
+Build against the installed package's public API. Read its version before choosing imports and
+integration dependencies. These resources ship with the SDK; no repository checkout is required.
+Preserve the application's chosen model provider and framework. The bundled OpenAI starter is an
+example, not a requirement to replace an existing integration.
+
+## Choose the task
+
+- New agent or worker: read [authoring](references/authoring.md), then the bundled starter,
+  which is installed next to this file and is the complete worked example for this release:
+  [assets/starter/agents.ts.tmpl](assets/starter/agents.ts.tmpl) (agent, handlers, tool) and
+  [assets/starter/worker.ts.tmpl](assets/starter/worker.ts.tmpl) (worker and plugins). Adapt it rather
+  than re-deriving the wiring. The package's `init` command materializes it as a new project.
+- Connect an application, stream replies, handle approvals, or generate client types: read
+  [the shared API guide](references/api.md).
+- State, Code Mode, callback tools, or subagents: read [advanced features](references/advanced.md).
+- Validate behavior or troubleshoot startup: read [verification](references/verification.md).
+
+Inside the harness repository checkout itself, use the `temporal-harness-repo` skill in its
+`.agents/skills/` instead: there, Bazel and `just` replace these commands and registries are generated.
+
+Load only the references relevant to the task. Use schemas and public types to discover the
+agent's interface before searching implementation files. The project may also have its own
+instructions; these resources describe SDK usage, not permission to change deployment settings.
+
+## Runtime boundaries
+
+An agent runs as a Temporal workflow on your TypeScript worker. The console, HTTP API, and
+session-manager worker currently come from the Python package. All services must connect to the
+same Temporal namespace; worker queues must match `agents.toml`. Provider API keys belong on the
+agent worker. Model integration plugins precede `AgentHarnessPlugin`.
+
+Keep external I/O out of workflow code. Register activity tool bodies on the worker, regenerate
+schemas after changing declarations, and verify a complete session using installed packages.
+Verify with the starter's `ping` handler first: it needs no model call or provider key.
+Do not import from repository-only `examples` or tests in an application.

package/skills/temporal-harness-typescript/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Temporal Harness TypeScript"
+  short_description: "Build durable TypeScript agents and harness API clients"
+  default_prompt: "Use $temporal-harness-typescript to build and verify this harness application."

package/skills/temporal-harness-typescript/assets/starter/README.md.tmpl

@@ -0,0 +1,95 @@
+# Your TypeScript harness agent
+
+This project was generated by `agent-harness init` from @temporalio/agent-harness
+__HARNESS_VERSION__. You need Node 22.18+, npm, uv, the Temporal CLI, and an OpenAI API key for
+the `ask` handler. The weather tool returns sample data.
+
+## 1. Install the generated project
+
+Project creation is already complete. Run the following from this directory:
+
+```bash
+npm install
+```
+
+`agents.ts` defines your agent, `worker.ts` runs it, and `agents.toml` registers it with the
+console. `package.json` pins the harness, compatible Temporal/model SDK versions, and the Python
+package that provides the shared services.
+
+## 2. Configure it and install the skill
+
+```bash
+cp env.example .env.local
+npm run schema
+npm run harness:skill                      # Codex reads .agents/skills
+npx agent-harness skills install --for claude  # Claude Code reads .claude/skills
+```
+
+`.env.local` is where `OPENAI_API_KEY` goes once you try `ask`; never commit it. `schema`
+compiles the agent and writes `agent.schema.json`. `harness:skill` copies this SDK release's skill, with
+authoring, API, advanced-feature, and verification references, into the directory your coding
+agent reads. Run it for each tool you use. For another tool, run `npx agent-harness skills path`
+to locate the bundled resources, or use `npx agent-harness skills install --dest <directory>`.
+
+## 3. Start the three services
+
+Run each command in its own terminal, all from this project directory:
+
+**Terminal 1 — Temporal service** (skip if your configured Temporal service is already running):
+
+```bash
+temporal server start-dev
+```
+
+**Terminal 2 — shared session manager, API, and harness console:**
+
+```bash
+npm run harness:dev
+```
+
+**Terminal 3 — your TypeScript agent worker:**
+
+```bash
+npm start
+```
+
+**The API, console, and session manager come from the Python package.** `harness:dev` runs them
+with `uvx` in one process; no Python project of your own is needed, and the console is prebuilt.
+Your agent worker runs in Node. The Python version is pinned in `package.json`.
+
+Defaults are `localhost:7233` and namespace `default`. For another Temporal service, export the
+same `TEMPORAL_*` connection settings in each service terminal. `.env.local` loads only into the
+Node worker. Leave `TASK_QUEUE_PREFIX` unset for this starter. Keep all three processes running.
+
+## 4. Verify, then develop with your coding agent
+
+1. Open the **harness console at <http://localhost:8000>**. Create a session for
+   **OpenAI Hello (TypeScript)**.
+2. Send `ping` a text message. Expect the same text back without a model request or an API key.
+3. Set `OPENAI_API_KEY` in `.env.local`, restart the worker, then send `ask`
+   **“What's the weather in Paris?”**. Expect a streamed reply and a completed `get_weather`
+   tool trace with sample weather data. This step calls OpenAI.
+4. Reload the page and confirm the session reconnects.
+5. Check startup and worker availability:
+
+   ```bash
+   npm run harness:doctor
+   ```
+
+Temporal's own workflow UI is at <http://localhost:8233>; it is separate from the harness console.
+
+With the services running, open the project in your coding agent. Reload its session if it was
+already running, then ask it to use the skill:
+
+| Tool | Prompt |
+| --- | --- |
+| Codex | `Use $temporal-harness-typescript to help me build this agent. Explain the starter, then verify it with ping before making model calls.` |
+| Claude Code | `/temporal-harness-typescript Explain the starter, then verify it with ping before making model calls.` |
+
+Edit `agents.ts` to change your agent and `worker.ts` for worker configuration. After changes,
+stop the worker, run `npm run schema`, and restart `npm start`. Use a new session for changed
+workflow behavior. Commit `agent.schema.json` and `package-lock.json`.
+
+After upgrading the SDK, rerun the `skills install` commands to update unchanged skill files.
+Local edits produce a conflict and are preserved. Application-client guidance is in the installed
+skill's `references/api.md`.

package/skills/temporal-harness-typescript/assets/starter/agents.toml.tmpl

@@ -0,0 +1,7 @@
+[[agents]]
+key = "openai-hello-ts"
+workflow_type = "OpenAIHelloAgentTs"
+task_queue = "openai-hello-ts"
+label = "OpenAI Hello (TypeScript)"
+description = "Chat with a TypeScript agent and try its sample weather tool."
+schema = "agent.schema.json"

package/skills/temporal-harness-typescript/assets/starter/agents.ts.tmpl

@@ -0,0 +1,61 @@
+import { Agent, type AgentInputItem } from "@openai/agents-core";
+import { z } from "zod";
+import {
+  TextMessage,
+  TextReply,
+  ToolApprovalPolicy,
+  defineAgent,
+  handler,
+  tool,
+} from "@temporalio/agent-harness";
+import {
+  asOpenAIAgentTool,
+  runStreamed,
+} from "@temporalio/agent-harness/ai-sdks/openai-agents-harness";
+
+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 OpenAIHelloAgentTs = defineAgent({
+  name: "OpenAIHelloAgentTs",
+  approvalPolicyDefault: ToolApprovalPolicy.allowInherentlySafe(),
+  handlers: {
+    ping: handler({ description: "Check the worker without a model call.", input: TextMessage, output: TextReply }),
+    ask: handler({
+      description: "Chat with the assistant. Ask about the weather to try its tool.",
+      input: TextMessage,
+      output: TextReply,
+    }),
+  },
+  create: ({ runner }) => {
+    let conversation: AgentInputItem[] = [];
+    return {
+      async ping({ text }) { return { text }; },
+      async ask({ text }) {
+        const sdkAgent = new Agent({
+          name: "Hello",
+          instructions: "Answer briefly. For weather questions, call get_weather and explain that it returns sample data.",
+          model: "gpt-5.1",
+          tools: [asOpenAIAgentTool(runner, getWeather)],
+        });
+        const input: AgentInputItem[] = [...conversation, { role: "user", content: text }];
+        const result = await runStreamed(runner, sdkAgent, input, {
+          defaultModelParams: {
+            startToCloseTimeout: "2 minutes",
+            heartbeatTimeout: "30 seconds",
+          },
+        });
+        for await (const _event of result) void _event;
+        await result.completed;
+        conversation = result.history;
+        return { text: String(result.finalOutput) };
+      },
+    };
+  },
+});

package/skills/temporal-harness-typescript/assets/starter/env.example.tmpl

@@ -0,0 +1,3 @@
+# Uncomment and set your key before trying `ask`; `ping` works without one.
+# OPENAI_API_KEY=sk-...
+# Export the same TEMPORAL_* settings in every service terminal when using a profile.

package/skills/temporal-harness-typescript/assets/starter/gitignore.tmpl

@@ -0,0 +1,6 @@
+.env.local
+.venv/
+__pycache__/
+*.egg-info/
+node_modules/
+dist/

package/skills/temporal-harness-typescript/assets/starter/package.json.tmpl

@@ -0,0 +1,35 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "schema": "npm run build && agent-harness schema ./dist/agents.js#OpenAIHelloAgentTs -o agent.schema.json",
+    "harness:dev": "uvx --from 'temporal-agent-harness[ui]==0.9.0' temporal-agent-harness dev agents.toml",
+    "start": "node --env-file-if-exists=.env.local dist/worker.js",
+    "harness:skill": "agent-harness skills install",
+    "harness:doctor": "agent-harness doctor --schema agent.schema.json"
+  },
+  "dependencies": {
+    "@temporalio/agent-harness": "__HARNESS_VERSION__",
+    "@temporalio/agent-harness-worker": "__HARNESS_VERSION__",
+    "@temporalio/agent-harness-client": "__HARNESS_VERSION__",
+    "@temporalio/activity": "1.24.0",
+    "@temporalio/client": "1.24.0",
+    "@temporalio/common": "1.24.0",
+    "@temporalio/envconfig": "1.24.0",
+    "@temporalio/plugin": "1.24.0",
+    "@temporalio/worker": "1.24.0",
+    "@temporalio/workflow": "1.24.0",
+    "@temporalio/workflow-streams": "1.24.0",
+    "@temporalio/openai-agents": "1.24.0",
+    "@openai/agents-core": "0.14.3",
+    "@openai/agents-openai": "0.14.3",
+    "openai": "6.46.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "@types/node": "22.20.4"
+  }
+}

package/skills/temporal-harness-typescript/assets/starter/tsconfig.json.tmpl

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "rootDir": ".",
+    "outDir": "dist"
+  },
+  "include": ["agents.ts", "worker.ts"]
+}

package/skills/temporal-harness-typescript/assets/starter/worker.ts.tmpl

@@ -0,0 +1,24 @@
+import { fileURLToPath } from "node:url";
+import { loadClientConnectConfig } from "@temporalio/envconfig";
+import { NativeConnection, Worker } from "@temporalio/worker";
+import { AgentHarnessPlugin } from "@temporalio/agent-harness-worker";
+import { OpenAIAgentsPlugin } from "@temporalio/agent-harness-worker/ai-sdks/openai-agents";
+
+// `ping` needs no model, so the worker starts without a key; only `ask` fails without one.
+if (!process.env.OPENAI_API_KEY)
+  console.warn("OPENAI_API_KEY is not set: `ping` works, `ask` will fail until it is (see env.example)");
+
+const { connectionOptions, namespace } = loadClientConnectConfig();
+const connection = await NativeConnection.connect(connectionOptions);
+try {
+  const worker = await Worker.create({
+    connection,
+    namespace: namespace ?? "default",
+    taskQueue: "openai-hello-ts",
+    workflowsPath: fileURLToPath(new URL("./agents.js", import.meta.url)),
+    plugins: [new OpenAIAgentsPlugin(), new AgentHarnessPlugin()],
+  });
+  await worker.run();
+} finally {
+  await connection.close();
+}