@stigmer/sdk 2.0.1 → 3.0.0

package/README.md

@@ -182,11 +182,66 @@ interface StigmerConfig {
   getAccessToken?: () => string | null | Promise<string | null>;  // Dynamic token provider
   onUnauthenticated?: () => void;     // Called once on UNAUTHENTICATED (code 16)
   transport?: "grpc-web" | "connect"; // Default: "grpc-web"
+  executionTarget?: "local" | "cloud"; // Default execution target — see "Local Execution"
 }
 ```
 
 Exactly one of `apiKey` or `getAccessToken` must be provided.
 
+## Local Execution
+
+Agent and workflow execution runs in the cloud by default — the Stigmer server provisions a sandbox with a runner. To run execution on the client (a desktop app, CLI, or self-hosted deployment), set the execution target.
+
+### Selecting the target
+
+```typescript
+// App-level default for every session and workflow execution
+const stigmer = new Stigmer({
+  baseUrl: "https://api.stigmer.ai",
+  getAccessToken: () => authStore.getToken(),
+  executionTarget: "local", // "local" | "cloud"; omit to let the server decide
+});
+
+// A per-call executionTarget takes precedence over the app-level default
+const session = await stigmer.session.create({
+  name: "review",
+  org: "my-org",
+  agentInstanceId: "inst-abc",
+  executionTarget: "cloud",
+});
+```
+
+`workflowExecution.create()` accepts the same per-call `executionTarget`.
+
+### `RunnerAdapter`
+
+For local execution, the client owns the runner lifecycle. `@stigmer/sdk` exports the `RunnerAdapter` type so non-React hosts (Node scripts, custom frameworks) can implement it:
+
+```typescript
+import type { RunnerAdapter } from "@stigmer/sdk";
+
+const adapter: RunnerAdapter = {
+  onSessionOpened: async (sessionId) => { /* start a worker for this session */ },
+  onSessionClosed: async (sessionId) => { /* stop it */ },
+  onWorkflowExecutionCreated: async (executionId) => { /* start a worker */ },
+  onWorkflowExecutionTerminated: async (executionId) => { /* stop it */ },
+};
+```
+
+If your runner backend already exposes `addSession` / `removeSession` / `addWorkflowExecution` / `removeWorkflowExecution` (a `RunnerWorkerHost`) — the in-process `createStigmerRunnerManager`, the desktop's embedded-runner context, or your own API — skip the hand-wiring and let `createRunnerAdapter` build the adapter:
+
+```typescript
+import { createRunnerAdapter } from "@stigmer/sdk";
+
+const adapter = createRunnerAdapter(myRunnerHost);
+```
+
+A Session has no terminal phase, so its worker is tied to whether the session is **open**: attach on `onSessionOpened`, detach on `onSessionClosed` (and keep both idempotent — `onSessionOpened` may fire again on re-open). A Workflow Execution runs to a terminal phase, so its worker is tied to create/terminate.
+
+The SDK does not invoke these methods on its own in a non-React host — you wire the adapter to your own open/close and create/terminate code paths. In React apps, `@stigmer/react` does this wiring automatically: pass `executionTarget` and `runnerAdapter` to `StigmerProvider` and the SDK hooks invoke the adapter at the right lifecycle points.
+
+See the [`@stigmer/react` local execution docs](../react/README.md#local-execution) and the [runner embedding guide](https://stigmer.ai/docs/guides/runners/embedding) for the full desktop (local) and web (cloud) walkthrough.
+
 ## Code Generation
 
 The resource clients in `src/gen/` are generated from protobuf service schemas. To regenerate after proto changes:

package/__tests__/runner-adapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runner-adapter.test.d.ts.map

package/__tests__/runner-adapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-adapter.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/runner-adapter.test.ts"],"names":[],"mappings":""}

package/__tests__/runner-adapter.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect, vi } from "vitest";
+import { createRunnerAdapter, } from "../runner-adapter";
+function createMockHost() {
+    return {
+        addSession: vi.fn().mockResolvedValue(undefined),
+        removeSession: vi.fn().mockResolvedValue(undefined),
+        addWorkflowExecution: vi.fn().mockResolvedValue(undefined),
+        removeWorkflowExecution: vi.fn().mockResolvedValue(undefined),
+    };
+}
+describe("createRunnerAdapter", () => {
+    it("returns an adapter with all four lifecycle methods", () => {
+        const adapter = createRunnerAdapter(createMockHost());
+        expect(adapter.onSessionOpened).toBeInstanceOf(Function);
+        expect(adapter.onSessionClosed).toBeInstanceOf(Function);
+        expect(adapter.onWorkflowExecutionCreated).toBeInstanceOf(Function);
+        expect(adapter.onWorkflowExecutionTerminated).toBeInstanceOf(Function);
+    });
+    it("maps onSessionOpened to host.addSession with the session id", async () => {
+        const host = createMockHost();
+        const adapter = createRunnerAdapter(host);
+        await adapter.onSessionOpened("ses-123");
+        expect(host.addSession).toHaveBeenCalledTimes(1);
+        expect(host.addSession).toHaveBeenCalledWith("ses-123");
+        // The asymmetric mapping is the footgun this factory exists to prevent:
+        // closing/removing must not fire on open.
+        expect(host.removeSession).not.toHaveBeenCalled();
+    });
+    it("maps onSessionClosed to host.removeSession with the session id", async () => {
+        const host = createMockHost();
+        const adapter = createRunnerAdapter(host);
+        await adapter.onSessionClosed("ses-123");
+        expect(host.removeSession).toHaveBeenCalledTimes(1);
+        expect(host.removeSession).toHaveBeenCalledWith("ses-123");
+        expect(host.addSession).not.toHaveBeenCalled();
+    });
+    it("maps onWorkflowExecutionCreated to host.addWorkflowExecution with the execution id", async () => {
+        const host = createMockHost();
+        const adapter = createRunnerAdapter(host);
+        await adapter.onWorkflowExecutionCreated("wfexec-456");
+        expect(host.addWorkflowExecution).toHaveBeenCalledTimes(1);
+        expect(host.addWorkflowExecution).toHaveBeenCalledWith("wfexec-456");
+        expect(host.removeWorkflowExecution).not.toHaveBeenCalled();
+    });
+    it("maps onWorkflowExecutionTerminated to host.removeWorkflowExecution with the execution id", async () => {
+        const host = createMockHost();
+        const adapter = createRunnerAdapter(host);
+        await adapter.onWorkflowExecutionTerminated("wfexec-456");
+        expect(host.removeWorkflowExecution).toHaveBeenCalledTimes(1);
+        expect(host.removeWorkflowExecution).toHaveBeenCalledWith("wfexec-456");
+        expect(host.addWorkflowExecution).not.toHaveBeenCalled();
+    });
+    it("resolves to undefined regardless of the host's return value", async () => {
+        // The host's add methods return a task queue string; the adapter contract
+        // is Promise<void>, so the value must be swallowed.
+        const host = createMockHost();
+        host.addSession.mockResolvedValue("session:ses-123");
+        host.addWorkflowExecution.mockResolvedValue("wfexec:wfexec-456");
+        const adapter = createRunnerAdapter(host);
+        await expect(adapter.onSessionOpened("ses-123")).resolves.toBeUndefined();
+        await expect(adapter.onWorkflowExecutionCreated("wfexec-456")).resolves.toBeUndefined();
+    });
+    it("awaits the host: it does not resolve before the host settles", async () => {
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const host = createMockHost();
+        host.addSession.mockReturnValue(gate);
+        const adapter = createRunnerAdapter(host);
+        let settled = false;
+        const pending = adapter.onSessionOpened("ses-123").then(() => {
+            settled = true;
+        });
+        await Promise.resolve();
+        expect(settled).toBe(false);
+        release();
+        await pending;
+        expect(settled).toBe(true);
+    });
+    it("propagates a host rejection", async () => {
+        const host = createMockHost();
+        host.removeSession.mockRejectedValue(new Error("worker teardown failed"));
+        const adapter = createRunnerAdapter(host);
+        await expect(adapter.onSessionClosed("ses-123")).rejects.toThrow("worker teardown failed");
+    });
+});
+//# sourceMappingURL=runner-adapter.test.js.map

package/__tests__/runner-adapter.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-adapter.test.js","sourceRoot":"","sources":["../../src/__tests__/runner-adapter.test.ts"],"names":[],"mappings":"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"}

package/execution/__tests__/tool-view.fixtures.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-view.fixtures.test.d.ts.map

package/execution/__tests__/tool-view.fixtures.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-view.fixtures.test.d.ts","sourceRoot":"","sources":["../../../src/execution/__tests__/tool-view.fixtures.test.ts"],"names":[],"mappings":""}

package/execution/__tests__/tool-view.fixtures.test.js

@@ -0,0 +1,102 @@
+// Validates the tool-view layer against the shared cross-language contract in
+// test/fixtures/tool-view/. The Go CLI runs the same fixtures, so the two
+// surfaces cannot drift in classification or result interpretation.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ToolKind, resolveToolKindByName, normalizeToolResult } from "../tool-view";
+const here = dirname(fileURLToPath(import.meta.url));
+// sdk/typescript/src/execution/__tests__ -> repo root is five levels up.
+const fixtureDir = resolve(here, "../../../../../test/fixtures/tool-view");
+function loadFixture(name) {
+    return JSON.parse(readFileSync(resolve(fixtureDir, name), "utf8"));
+}
+describe("classification fixtures", () => {
+    const { cases } = loadFixture("classification.json");
+    it("loads the fixture", () => {
+        expect(cases.length).toBeGreaterThan(0);
+    });
+    for (const c of cases) {
+        const expected = ToolKind[c.toolKind.replace(/^TOOL_KIND_/, "")];
+        it(`classifies ${c.name || "(empty)"}${c.mcpServerSlug ? ` @${c.mcpServerSlug}` : ""}`, () => {
+            expect(resolveToolKindByName(c.name, c.mcpServerSlug)).toBe(expected);
+        });
+    }
+});
+describe("result-view fixtures", () => {
+    const { cases } = loadFixture("result-views.json");
+    it("loads the fixture", () => {
+        expect(cases.length).toBeGreaterThan(0);
+    });
+    for (const c of cases) {
+        it(`normalizes ${c.name} -> ${c.expected.type}`, () => {
+            const status = c.status === "TOOL_CALL_FAILED"
+                ? ToolCallStatus.TOOL_CALL_FAILED
+                : ToolCallStatus.TOOL_CALL_COMPLETED;
+            const toolCall = create(ToolCallSchema, {
+                id: c.name,
+                name: c.toolName,
+                mcpServerSlug: c.mcpServerSlug,
+                result: c.result,
+                error: c.error ?? "",
+                status,
+                args: c.args,
+            });
+            const view = normalizeToolResult(toolCall);
+            expect(view.type).toBe(c.expected.type);
+            // Only deterministic facts are part of the shared contract.
+            if (c.expected.path !== undefined && view.type === "diff") {
+                expect(view.path).toBe(c.expected.path);
+            }
+            if (c.expected.path !== undefined && view.type === "file") {
+                expect(view.path).toBe(c.expected.path);
+            }
+            if (c.expected.exitCode !== undefined && view.type === "terminal") {
+                expect(view.exitCode).toBe(c.expected.exitCode);
+            }
+            if (c.expected.count !== undefined && view.type === "search") {
+                expect(view.count).toBe(c.expected.count);
+            }
+            if (c.expected.count !== undefined && view.type === "list") {
+                expect(view.count).toBe(c.expected.count);
+            }
+            if (c.expected.mcpServerSlug !== undefined && view.type === "contentBlocks") {
+                expect(view.mcpServerSlug).toBe(c.expected.mcpServerSlug);
+            }
+            if (c.expected.linesAdded !== undefined && view.type === "diff") {
+                expect(view.linesAdded).toBe(c.expected.linesAdded);
+            }
+            if (c.expected.linesRemoved !== undefined && view.type === "diff") {
+                expect(view.linesRemoved).toBe(c.expected.linesRemoved);
+            }
+        });
+    }
+});
+describe("resolveToolKind wire field precedence", () => {
+    it("prefers the wire tool_kind over the name fallback", () => {
+        const toolCall = create(ToolCallSchema, {
+            name: "some_unknown_name",
+            toolKind: ToolKind.SHELL,
+        });
+        // resolveToolKind is exercised indirectly via normalizeToolResult routing.
+        const view = normalizeToolResult(create(ToolCallSchema, {
+            name: "some_unknown_name",
+            toolKind: ToolKind.SHELL,
+            result: "done\n[Command succeeded]",
+            status: ToolCallStatus.TOOL_CALL_COMPLETED,
+        }));
+        expect(view.type).toBe("terminal");
+        expect(toolCall.toolKind).toBe(ToolKind.SHELL);
+    });
+    it("degrades unknown results to json or text", () => {
+        const jsonView = normalizeToolResult(create(ToolCallSchema, { name: "mystery", result: '{"a":1}', status: ToolCallStatus.TOOL_CALL_COMPLETED }));
+        expect(jsonView.type).toBe("json");
+        const textView = normalizeToolResult(create(ToolCallSchema, { name: "mystery", result: "plain", status: ToolCallStatus.TOOL_CALL_COMPLETED }));
+        expect(textView.type).toBe("text");
+    });
+});
+//# sourceMappingURL=tool-view.fixtures.test.js.map

package/execution/__tests__/tool-view.fixtures.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-view.fixtures.test.js","sourceRoot":"","sources":["../../../src/execution/__tests__/tool-view.fixtures.test.ts"],"names":[],"mappings":"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"}

package/execution/tool-view.d.ts

@@ -0,0 +1,88 @@
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+export { ToolKind };
+/** A single match in a search/grep result. */
+export interface ToolSearchMatch {
+    /** File path the match was found in, when the result format provides it. */
+    readonly file?: string;
+    /** 1-based line number, when available. */
+    readonly line?: number;
+    /** The matched text. */
+    readonly text: string;
+}
+/** An MCP content block (the `content: [...]` array MCP servers return). */
+export interface ToolContentBlock {
+    /** Block type, e.g. "text". */
+    readonly type: string;
+    /** Text payload, when the block is textual. */
+    readonly text?: string;
+}
+/**
+ * A typed projection of a tool call's result, discriminated by `type`.
+ *
+ * Presentation layers switch on `type` and never re-parse the raw string. The
+ * `json` and `text` variants are the guaranteed graceful-degradation fallbacks:
+ * any unrecognized or truncated payload lands there, so this is never worse than
+ * showing the raw result.
+ */
+export type ToolResultView = {
+    readonly type: "diff";
+    readonly path: string;
+    readonly oldText?: string;
+    readonly newText?: string;
+    readonly linesAdded?: number;
+    readonly linesRemoved?: number;
+    readonly unifiedDiff?: string;
+} | {
+    readonly type: "file";
+    readonly path: string;
+    readonly content: string;
+    readonly language?: string;
+    readonly truncated: boolean;
+} | {
+    readonly type: "terminal";
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode?: number;
+} | {
+    readonly type: "search";
+    readonly matches: readonly ToolSearchMatch[];
+    readonly count: number;
+} | {
+    readonly type: "list";
+    readonly entries: readonly string[];
+    readonly count: number;
+} | {
+    readonly type: "contentBlocks";
+    readonly blocks: readonly ToolContentBlock[];
+    readonly mcpServerSlug: string;
+} | {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "json";
+    readonly value: unknown;
+} | {
+    readonly type: "error";
+    readonly message: string;
+} | {
+    readonly type: "empty";
+};
+/**
+ * Resolves the harness-agnostic kind of a tool call.
+ *
+ * Prefers the wire `tool_kind` set by the runner; falls back to a name lookup
+ * for legacy executions where it is UNSPECIFIED. An unknown name with a
+ * non-empty mcpServerSlug is an MCP tool.
+ */
+export declare function resolveToolKind(toolCall: Pick<ToolCall, "name" | "mcpServerSlug" | "toolKind">): ToolKind;
+/** Name-based classification used as the legacy fallback for resolveToolKind. */
+export declare function resolveToolKindByName(name: string, mcpServerSlug?: string): ToolKind;
+/**
+ * Normalizes a tool call into a typed ToolResultView for rendering.
+ *
+ * A FAILED tool with an error always yields an `error` view. Otherwise the kind
+ * drives interpretation, and anything unrecognized degrades to `json`/`text`.
+ */
+export declare function normalizeToolResult(toolCall: ToolCall): ToolResultView;
+//# sourceMappingURL=tool-view.d.ts.map

package/execution/tool-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-view.d.ts","sourceRoot":"","sources":["../../src/execution/tool-view.ts"],"names":[],"mappings":"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"}