@temporalio/agent-harness-react 0.1.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

@@ -0,0 +1,46 @@
+# @temporalio/agent-harness-react
+
+A React binding for `@temporalio/agent-harness-client`: `useAgentSession`, a hook that follows one
+harness agent session. React 18.2 or later.
+
+```tsx
+import { useAgentSession } from "@temporalio/agent-harness-react";
+import type { TicTacToeAgent } from "./client_sdk/TicTacToeAgent"; // from harness-codegen
+
+function Board({ sessionId }: { sessionId: string }) {
+  const agent = useAgentSession<TicTacToeAgent>({ sessionId });
+  const board = agent.states.board;
+  if (!board) return null;
+  return board.cells.map((cell, i) => (
+    <button key={i} onClick={() => agent.sendMessage("play", { cell: i + 1 })}>{cell ?? ""}</button>
+  ));
+}
+```
+
+- **Mounting opens the connection.** The first mounted component using a session opens its
+  stream; it closes once the last one unmounts. StrictMode's extra unmount and remount in
+  development does not reconnect.
+- **Renders follow the stream.** The hook reads the session through `useSyncExternalStore`, and
+  the core writes once per flush, so a burst of frames is one render.
+- **A changed `sessionId` moves the connection.** Pass it as a prop or state like any other value.
+- **One connection per session.** Put a `<HarnessProvider>` above your components and every
+  `useAgentSession` below it with the same session id shares one connection and one state.
+  Without one, each component gets its own.
+- **The first component to open a session decides its options** (`callbackTools`, transport and
+  so on). Later components, and later renders, share what it set up, so passing a new
+  `callbackTools` object each render is fine but does not replace the handlers.
+- **The whole tree.** `messages`, `states` and `agentStatus` are the root agent's; `agents` and
+  `agent(id)` reach every subagent, and a `subagent` part's `messageId` names the child message
+  it ran. `pendingApprovals` and `pendingCallbacks` collect waiting tool calls from all of them.
+- **Server rendering** shows the empty session and opens no connection; the client connects once
+  it hydrates.
+
+## Development
+
+This package links `../client` and resolves it through that package's build:
+
+```sh
+(cd ../client && npm ci && npm run build)
+npm ci
+npm run check && npm test && npm run build
+```

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { HarnessProvider, SessionStore, useAgentSession, type AgentSession } from "./session.js";
+export { ReactSessionState, type SessionSnapshot } from "./state.js";
+export * from "@temporalio/agent-harness-client";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { HarnessProvider, SessionStore, useAgentSession } from "./session.js";
+export { ReactSessionState } from "./state.js";
+export * from "@temporalio/agent-harness-client";

package/dist/session.d.ts

@@ -0,0 +1,74 @@
+import { type ReactNode } from "react";
+import { AgentSessionCore, type AgentSchema, type AgentSessionOptions, type AgentSseFrame, type AgentView, type ConnectionStatus, type HandlerInput, type HandlerName, type HarnessMessage, type SubmitMessageResponse, type ToolApprovalDecision, type UntypedAgent, type WaitingToolCall } from "@temporalio/agent-harness-client";
+import { ReactSessionState } from "./state.js";
+/** One session's core and state, shared by every component that follows it. */
+declare class SessionEntry<A extends AgentSchema> {
+    #private;
+    readonly state: ReactSessionState<A>;
+    readonly core: AgentSessionCore<A>;
+    constructor(options: AgentSessionOptions<A>);
+    acquire(): void;
+    release(): void;
+}
+/**
+ * Sessions by id, so that components following the same session share one connection and one
+ * state. Put one in context with `<HarnessProvider>`; a component using `useAgentSession`
+ * outside any provider gets a store of its own.
+ *
+ * The first component to follow an id decides that session's options (`callbackTools`,
+ * transport and so on); later ones, and later renders, share what it set up.
+ */
+export declare class SessionStore {
+    #private;
+    entry<A extends AgentSchema>(options: AgentSessionOptions<A>): SessionEntry<A>;
+}
+/** Share sessions below this component: every `useAgentSession` in its subtree for the same
+ *  session id uses one connection. */
+export declare function HarnessProvider({ store, children }: {
+    store?: SessionStore;
+    children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<SessionStore | null>>;
+/** What `useAgentSession` returns: the session's fields as of this render, and its actions. */
+export interface AgentSession<A extends AgentSchema = UntypedAgent> {
+    readonly sessionId: string;
+    readonly connection: ConnectionStatus;
+    /** The last connection or action failure, until `clearError()`. */
+    readonly error: Error | undefined;
+    /** The root agent's messages. */
+    readonly messages: readonly HarnessMessage<A>[];
+    /** The root agent's observable state, by state id; each is undefined until its snapshot. */
+    readonly states: Readonly<Partial<A["states"]>>;
+    /** Whether the root agent has a turn open. */
+    readonly agentStatus: "idle" | "busy";
+    /** Messages sent from here that the server has not admitted yet, and failed sends. */
+    readonly pending: readonly HarnessMessage<A>[];
+    /** Every agent in the session's tree — the root and its subagents at any depth — by id. */
+    readonly agents: Readonly<Record<string, AgentView>>;
+    /** The agent the session was opened for, once the stream has named it. */
+    readonly rootAgentId: string | null;
+    /** Every frame received, from every agent. */
+    readonly frames: readonly AgentSseFrame[];
+    /** Gated tool calls waiting on a person, anywhere in the tree. */
+    readonly pendingApprovals: readonly WaitingToolCall[];
+    /** Callback tool calls waiting on a client, anywhere in the tree, other than the ones the
+     *  session's `callbackTools` answer. */
+    readonly pendingCallbacks: readonly WaitingToolCall[];
+    /** Any agent in the tree by id — a subagent part's `subagentId`, say — typed as `B` when its
+     *  generated type is given. */
+    agent<B extends AgentSchema = UntypedAgent>(agentId: string): AgentView<B> | undefined;
+    sendMessage<H extends HandlerName<A>>(handler: H, payload: HandlerInput<A, H>): Promise<SubmitMessageResponse | null>;
+    respondToApproval(toolId: string, decision: ToolApprovalDecision): Promise<boolean>;
+    provideToolOutput(toolId: string, result: unknown): Promise<boolean>;
+    provideToolError(toolId: string, error: string): Promise<boolean>;
+    /** Stop the agent: it finishes its turn loop and auto-denies anything pending. */
+    closeSession(): Promise<boolean>;
+    /** Drop a failed send from `pending`. */
+    dismiss(localId: string): void;
+    clearError(): void;
+}
+/**
+ * Follow one agent session. Re-renders when anything in it changes; a changed `sessionId`
+ * moves the connection to the new session.
+ */
+export declare function useAgentSession<A extends AgentSchema = UntypedAgent>(options: AgentSessionOptions<A>): AgentSession<A>;
+export {};

package/dist/session.js

@@ -0,0 +1,113 @@
+// useAgentSession: one agent session as React state. Call it in a component, render its fields,
+// and call its actions. The connection is open exactly while a component using the session is
+// mounted: the first to mount opens it, and it closes once the last one unmounts.
+import { createContext, createElement, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { AgentSessionCore, rootView, waitingCalls } from "@temporalio/agent-harness-client";
+import { ReactSessionState } from "./state.js";
+/** One session's core and state, shared by every component that follows it. */
+class SessionEntry {
+    state = new ReactSessionState();
+    core;
+    #readers = 0;
+    #stopScheduled = false;
+    constructor(options) {
+        this.core = new AgentSessionCore(options, this.state);
+    }
+    acquire() {
+        if (this.#readers++ > 0)
+            return;
+        /* A release that has not taken effect yet is cancelled rather than followed by a restart:
+           StrictMode unmounts and remounts every component once in development, and that should
+           not cost a reconnect. */
+        if (this.#stopScheduled)
+            this.#stopScheduled = false;
+        else
+            this.core.start();
+    }
+    release() {
+        if (--this.#readers > 0)
+            return;
+        this.#stopScheduled = true;
+        queueMicrotask(() => {
+            if (!this.#stopScheduled)
+                return;
+            this.#stopScheduled = false;
+            this.core.stop();
+        });
+    }
+}
+/**
+ * Sessions by id, so that components following the same session share one connection and one
+ * state. Put one in context with `<HarnessProvider>`; a component using `useAgentSession`
+ * outside any provider gets a store of its own.
+ *
+ * The first component to follow an id decides that session's options (`callbackTools`,
+ * transport and so on); later ones, and later renders, share what it set up.
+ */
+export class SessionStore {
+    #entries = new Map();
+    entry(options) {
+        let entry = this.#entries.get(options.sessionId);
+        if (!entry) {
+            entry = new SessionEntry(options);
+            this.#entries.set(options.sessionId, entry);
+        }
+        return entry;
+    }
+}
+const StoreContext = createContext(null);
+/** Share sessions below this component: every `useAgentSession` in its subtree for the same
+ *  session id uses one connection. */
+export function HarnessProvider({ store, children }) {
+    const [value] = useState(() => store ?? new SessionStore());
+    return createElement(StoreContext.Provider, { value }, children);
+}
+/**
+ * Follow one agent session. Re-renders when anything in it changes; a changed `sessionId`
+ * moves the connection to the new session.
+ */
+export function useAgentSession(options) {
+    const context = useContext(StoreContext);
+    const [own] = useState(() => new SessionStore());
+    const entry = (context ?? own).entry(options);
+    useEffect(() => {
+        entry.acquire();
+        return () => entry.release();
+    }, [entry]);
+    /* The server snapshot is the same empty state: effects never run there, so nothing connects. */
+    const snapshot = useSyncExternalStore(entry.state.subscribe, entry.state.getSnapshot, entry.state.getSnapshot);
+    return useMemo(() => sessionView(entry, snapshot), [entry, snapshot]);
+}
+function sessionView(entry, snapshot) {
+    const { core } = entry;
+    const root = rootView(snapshot);
+    /* Walking every part of every agent is only worth doing for a render that reads the result. */
+    let waiting;
+    const waitingNow = () => (waiting ??= waitingCalls(snapshot.agents, (name) => core.handlesCallback(name)));
+    return {
+        sessionId: core.sessionId,
+        connection: snapshot.connection,
+        error: snapshot.error,
+        messages: root.messages,
+        states: root.states,
+        agentStatus: root.agentStatus,
+        pending: snapshot.pending,
+        agents: snapshot.agents,
+        rootAgentId: snapshot.rootAgentId,
+        frames: snapshot.frames,
+        get pendingApprovals() {
+            return waitingNow().approvals;
+        },
+        get pendingCallbacks() {
+            return waitingNow().callbacks;
+        },
+        agent: (agentId) => snapshot.agents[agentId],
+        sendMessage: (handler, payload) => core.sendMessage(handler, payload),
+        respondToApproval: (toolId, decision) => core.respondToApproval(toolId, decision),
+        provideToolOutput: (toolId, result) => core.provideToolOutput(toolId, result),
+        provideToolError: (toolId, error) => core.provideToolError(toolId, error),
+        closeSession: () => core.closeSession(),
+        dismiss: (localId) => core.dismiss(localId),
+        clearError: () => core.clearError()
+    };
+}

package/dist/state.d.ts

@@ -0,0 +1,28 @@
+import { type AgentSchema, type AgentSseFrame, type AgentUpdate, type AgentView, type ConnectionStatus, type HarnessMessage, type SessionState, type UntypedAgent } from "@temporalio/agent-harness-client";
+export interface SessionSnapshot<A extends AgentSchema = UntypedAgent> {
+    readonly connection: ConnectionStatus;
+    readonly error: Error | undefined;
+    readonly rootAgentId: string | null;
+    readonly agents: Readonly<Record<string, AgentView>>;
+    readonly pending: readonly HarnessMessage<A>[];
+    readonly frames: readonly AgentSseFrame[];
+}
+export declare class ReactSessionState<A extends AgentSchema = UntypedAgent> implements SessionState<A> {
+    #private;
+    readonly subscribe: (listener: () => void) => (() => void);
+    readonly getSnapshot: () => SessionSnapshot<A>;
+    get connection(): ConnectionStatus;
+    set connection(connection: ConnectionStatus);
+    get error(): Error | undefined;
+    set error(error: Error | undefined);
+    get rootAgentId(): string | null;
+    set rootAgentId(rootAgentId: string | null);
+    get agents(): Readonly<Record<string, AgentView>>;
+    set agents(agents: Readonly<Record<string, AgentView>>);
+    get pending(): readonly HarnessMessage<A>[];
+    set pending(pending: readonly HarnessMessage<A>[]);
+    get frames(): readonly AgentSseFrame[];
+    set frames(frames: readonly AgentSseFrame[]);
+    updateAgents(updates: ReadonlyArray<readonly [string, AgentUpdate]>): void;
+    appendFrames(frames: readonly AgentSseFrame[]): void;
+}

package/dist/state.js

@@ -0,0 +1,73 @@
+// The SessionState the core writes into, as an immutable snapshot for `useSyncExternalStore`.
+// Every write replaces the snapshot, so its identity changes exactly when something did; the
+// core never mutates what it has handed over, so the fields inside can be shared as they are.
+import { applyAgentUpdate } from "@temporalio/agent-harness-client";
+export class ReactSessionState {
+    #snapshot = {
+        connection: "stopped",
+        error: undefined,
+        rootAgentId: null,
+        agents: {},
+        pending: [],
+        frames: []
+    };
+    #listeners = new Set();
+    /* Arrow properties: `useSyncExternalStore` resubscribes whenever these change identity. */
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    };
+    getSnapshot = () => this.#snapshot;
+    get connection() {
+        return this.#snapshot.connection;
+    }
+    set connection(connection) {
+        this.#set("connection", connection);
+    }
+    get error() {
+        return this.#snapshot.error;
+    }
+    set error(error) {
+        this.#set("error", error);
+    }
+    get rootAgentId() {
+        return this.#snapshot.rootAgentId;
+    }
+    set rootAgentId(rootAgentId) {
+        this.#set("rootAgentId", rootAgentId);
+    }
+    get agents() {
+        return this.#snapshot.agents;
+    }
+    set agents(agents) {
+        this.#set("agents", agents);
+    }
+    get pending() {
+        return this.#snapshot.pending;
+    }
+    set pending(pending) {
+        this.#set("pending", pending);
+    }
+    get frames() {
+        return this.#snapshot.frames;
+    }
+    set frames(frames) {
+        this.#set("frames", frames);
+    }
+    updateAgents(updates) {
+        const next = { ...this.#snapshot.agents };
+        for (const [id, update] of updates)
+            next[id] = applyAgentUpdate(next[id], id, update);
+        this.#set("agents", next);
+    }
+    appendFrames(frames) {
+        this.#set("frames", this.#snapshot.frames.concat(frames));
+    }
+    #set(key, value) {
+        if (this.#snapshot[key] === value)
+            return;
+        this.#snapshot = { ...this.#snapshot, [key]: value };
+        for (const listener of this.#listeners)
+            listener();
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@temporalio/agent-harness-react",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "React binding for @temporalio/agent-harness-client: a useAgentSession hook over a temporal-agent-harness agent's event stream.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@temporalio/agent-harness-client": "^0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^22.20.4",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "happy-dom": "^20.14.5",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
+  }
+}