@temporalio/agent-harness-svelte 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,40 @@
+# @temporalio/agent-harness-svelte
+
+A Svelte 5 binding for `@temporalio/agent-harness-client`: `AgentSession`, a reactive handle on one
+harness agent session.
+
+```svelte
+<script lang="ts">
+  import { AgentSession } from "@temporalio/agent-harness-svelte";
+  import type { TicTacToeAgent } from "./client_sdk/TicTacToeAgent"; // from harness-codegen
+
+  let { sessionId } = $props();
+  const agent = new AgentSession<TicTacToeAgent>({ get sessionId() { return sessionId; } });
+  const board = $derived(agent.states.board);
+</script>
+
+{#if board}
+  {#each board.cells as cell, i (i)}
+    <button onclick={() => agent.sendMessage("play", { cell: i + 1 })}>{cell ?? ""}</button>
+  {/each}
+{/if}
+```
+
+- **Reading opens the connection.** The first effect or markup to read any field opens the
+  session's stream; it closes once nothing reads it, so unmounting the last view releases it.
+- **Getter options follow changes.** A `get sessionId()` switches the session when its value does.
+- **One connection per session.** Call `createHarnessContext()` in a parent component and every
+  `AgentSession` below it with the same session id shares one connection and one state.
+- **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.
+
+## 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 { AgentSession, SessionStore, createHarnessContext, type AgentSessionOptions } from "./session.svelte.js";
+export { SvelteSessionState } from "./state.svelte.js";
+export * from "@temporalio/agent-harness-client";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { AgentSession, SessionStore, createHarnessContext } from "./session.svelte.js";
+export { SvelteSessionState } from "./state.svelte.js";
+export * from "@temporalio/agent-harness-client";

package/dist/session.svelte.d.ts

@@ -0,0 +1,69 @@
+import { AgentSessionCore, type AgentSchema, type AgentSessionOptions as CoreOptions, 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 { SvelteSessionState } from "./state.svelte.js";
+export interface AgentSessionOptions<A extends AgentSchema> extends Omit<CoreOptions<A>, "sessionId"> {
+    /** The session to follow. Pass a getter (`get sessionId() { return id; }`) to switch
+     *  sessions when `id` changes. */
+    readonly sessionId: string;
+}
+/** One session's core and state, shared by every AgentSession that follows it. */
+declare class SessionEntry<A extends AgentSchema> {
+    #private;
+    readonly state: SvelteSessionState<A>;
+    readonly core: AgentSessionCore<A>;
+    constructor(options: CoreOptions<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 `createHarnessContext()`; an AgentSession constructed outside
+ * any such context gets its own.
+ *
+ * The first AgentSession to follow an id decides that session's options (`callbackTools`,
+ * transport and so on); later ones share what it set up.
+ */
+export declare class SessionStore {
+    #private;
+    entry<A extends AgentSchema>(options: CoreOptions<A>): SessionEntry<A>;
+}
+/** Share sessions below this component: every AgentSession constructed in its subtree for the
+ *  same session id uses one connection. Call it during component initialisation. */
+export declare function createHarnessContext(store?: SessionStore): SessionStore;
+export declare class AgentSession<A extends AgentSchema = UntypedAgent> {
+    #private;
+    constructor(options: AgentSessionOptions<A>, store?: SessionStore);
+    get sessionId(): string;
+    get connection(): ConnectionStatus;
+    get error(): Error | undefined;
+    /** The root agent's messages. */
+    get messages(): readonly HarnessMessage<A>[];
+    /** The root agent's observable state, by state id; each is undefined until its snapshot. */
+    get states(): Readonly<Partial<A["states"]>>;
+    /** Whether the root agent has a turn open. */
+    get agentStatus(): "idle" | "busy";
+    /** Messages sent from here that the server has not admitted yet, and failed sends. */
+    get pending(): readonly HarnessMessage<A>[];
+    /** Every agent in the session's tree — the root and its subagents at any depth — by id. */
+    get agents(): Readonly<Record<string, AgentView>>;
+    get rootAgentId(): string | null;
+    /** Every frame received, from every agent. */
+    get frames(): readonly AgentSseFrame[];
+    /** Gated tool calls waiting on a person, anywhere in the tree. */
+    get pendingApprovals(): readonly WaitingToolCall[];
+    /** Callback tool calls waiting on a client, anywhere in the tree, other than the ones the
+     *  session's `callbackTools` answer. */
+    get 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;
+}
+export {};

package/dist/session.svelte.js

@@ -0,0 +1,161 @@
+// AgentSession: a reactive handle on one agent session. Construct it in a component, read its
+// fields in markup or effects, and call its actions. The connection is open exactly while
+// something reads it: the first effect to read any field opens it, and it closes when the last
+// such effect is torn down, so unmounting the last view of a session releases its stream.
+import { getContext, hasContext, setContext } from "svelte";
+import { createSubscriber } from "svelte/reactivity";
+import { AgentSessionCore, rootView, waitingCalls } from "@temporalio/agent-harness-client";
+import { SvelteSessionState } from "./state.svelte.js";
+/** One session's core and state, shared by every AgentSession that follows it. */
+class SessionEntry {
+    state = new SvelteSessionState();
+    core;
+    #readers = 0;
+    constructor(options) {
+        this.core = new AgentSessionCore(options, this.state);
+    }
+    acquire() {
+        if (this.#readers++ === 0)
+            this.core.start();
+    }
+    release() {
+        if (--this.#readers === 0)
+            this.core.stop();
+    }
+}
+/**
+ * Sessions by id, so that components following the same session share one connection and one
+ * state. Put one in context with `createHarnessContext()`; an AgentSession constructed outside
+ * any such context gets its own.
+ *
+ * The first AgentSession to follow an id decides that session's options (`callbackTools`,
+ * transport and so on); later ones 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 STORE = Symbol("temporal-agent-harness sessions");
+/** Share sessions below this component: every AgentSession constructed in its subtree for the
+ *  same session id uses one connection. Call it during component initialisation. */
+export function createHarnessContext(store = new SessionStore()) {
+    return setContext(STORE, store);
+}
+function contextStore() {
+    // Outside component initialisation there is no context to read, and asking throws.
+    try {
+        return hasContext(STORE) ? getContext(STORE) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export class AgentSession {
+    #options;
+    #store;
+    #entry = $derived.by(() => this.#resolve());
+    #subscribe;
+    #waiting = $derived.by(() => waitingCalls(this.#state().agents, (toolName) => this.#entry.core.handlesCallback(toolName)));
+    constructor(options, store) {
+        this.#options = options;
+        this.#store = store ?? contextStore() ?? new SessionStore();
+        this.#subscribe = createSubscriber(() => 
+        // Hold the session for as long as anything reads it. The inner effect follows
+        // `sessionId`, so switching sessions moves the hold from the old one to the new one.
+        $effect.root(() => {
+            $effect(() => {
+                const entry = this.#entry;
+                entry.acquire();
+                return () => entry.release();
+            });
+        }));
+    }
+    get sessionId() {
+        return this.#options.sessionId;
+    }
+    get connection() {
+        return this.#state().connection;
+    }
+    get error() {
+        return this.#state().error;
+    }
+    /** The root agent's messages. */
+    get messages() {
+        return rootView(this.#state()).messages;
+    }
+    /** The root agent's observable state, by state id; each is undefined until its snapshot. */
+    get states() {
+        return rootView(this.#state()).states;
+    }
+    /** Whether the root agent has a turn open. */
+    get agentStatus() {
+        return rootView(this.#state()).agentStatus;
+    }
+    /** Messages sent from here that the server has not admitted yet, and failed sends. */
+    get pending() {
+        return this.#state().pending;
+    }
+    /** Every agent in the session's tree — the root and its subagents at any depth — by id. */
+    get agents() {
+        return this.#state().agents;
+    }
+    get rootAgentId() {
+        return this.#state().rootAgentId;
+    }
+    /** Every frame received, from every agent. */
+    get frames() {
+        return this.#state().frames;
+    }
+    /** Gated tool calls waiting on a person, anywhere in the tree. */
+    get pendingApprovals() {
+        return this.#waiting.approvals;
+    }
+    /** Callback tool calls waiting on a client, anywhere in the tree, other than the ones the
+     *  session's `callbackTools` answer. */
+    get pendingCallbacks() {
+        return this.#waiting.callbacks;
+    }
+    /** Any agent in the tree by id — a subagent part's `subagentId`, say — typed as `B` when its
+     *  generated type is given. */
+    agent(agentId) {
+        return this.#state().agents[agentId];
+    }
+    sendMessage(handler, payload) {
+        return this.#entry.core.sendMessage(handler, payload);
+    }
+    respondToApproval(toolId, decision) {
+        return this.#entry.core.respondToApproval(toolId, decision);
+    }
+    provideToolOutput(toolId, result) {
+        return this.#entry.core.provideToolOutput(toolId, result);
+    }
+    provideToolError(toolId, error) {
+        return this.#entry.core.provideToolError(toolId, error);
+    }
+    /** Stop the agent: it finishes its turn loop and auto-denies anything pending. */
+    closeSession() {
+        return this.#entry.core.closeSession();
+    }
+    /** Drop a failed send from `pending`. */
+    dismiss(localId) {
+        this.#entry.core.dismiss(localId);
+    }
+    clearError() {
+        this.#entry.core.clearError();
+    }
+    #state() {
+        this.#subscribe();
+        return this.#entry.state;
+    }
+    #resolve() {
+        const { sessionId, ...rest } = this.#options;
+        return this.#store.entry({ ...rest, sessionId });
+    }
+}

package/dist/state.svelte.d.ts

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

package/dist/state.svelte.js

@@ -0,0 +1,21 @@
+// The SessionState the core writes into, as Svelte state. `$state.raw` rather than deep
+// `$state`: the core always hands over whole new objects, so deep proxies would buy nothing and
+// make replaying a long session expensive.
+import { applyAgentUpdate } from "@temporalio/agent-harness-client";
+export class SvelteSessionState {
+    connection = $state("stopped");
+    error = $state.raw(undefined);
+    rootAgentId = $state(null);
+    agents = $state.raw({});
+    pending = $state.raw([]);
+    frames = $state.raw([]);
+    updateAgents(updates) {
+        const next = { ...this.agents };
+        for (const [id, update] of updates)
+            next[id] = applyAgentUpdate(next[id], id, update);
+        this.agents = next;
+    }
+    appendFrames(frames) {
+        this.frames = this.frames.concat(frames);
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@temporalio/agent-harness-svelte",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Svelte 5 binding for @temporalio/agent-harness-client: a reactive AgentSession over a temporal-agent-harness agent's event stream.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "svelte-package",
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "svelte": "^5.7.0"
+  },
+  "dependencies": {
+    "@temporalio/agent-harness-client": "^0.1.0"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.3.0",
+    "@types/node": "^22.20.4",
+    "happy-dom": "^20.14.5",
+    "svelte": "^5.57.1",
+    "svelte-check": "^4.7.6",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1"
+  }
+}