@botbotgo/agent-harness 0.0.10 → 0.0.11

package/README.md

@@ -83,6 +83,249 @@ There are two common ways to use the framework.
 
 Load a workspace from disk and run requests through the public API.
 
+#### SDK Surface
+
+The SDK is intentionally small:
+
+- `createAgentHarness(...)`: load a workspace and initialize the runtime
+- `run(...)`: start a new run or answer an approval request
+- `subscribe(...)`: observe runtime events for logging or UI updates
+- `getThread(...)`: fetch persisted thread state and messages
+- `stop(...)`: release runtime resources when your process is done
+
+#### Create A Harness From A Workspace Path
+
+This is the standard entry point. Pass the workspace root and let the harness load `AGENTS.md`, `config/`, resource sources, skills, tools, and agent bindings from disk.
+
+```ts
+import { createAgentHarness } from "@botbotgo/agent-harness";
+
+const harness = await createAgentHarness("/absolute/path/to/workspace");
+```
+
+If you omit the path, the SDK uses `process.cwd()`:
+
+```ts
+const harness = await createAgentHarness();
+```
+
+#### Create A Harness From A Prebuilt WorkspaceBundle
+
+If your application already compiled a workspace, or you want tighter control in tests, you can pass a `WorkspaceBundle` directly instead of a filesystem path.
+
+```ts
+import { createAgentHarness } from "@botbotgo/agent-harness";
+
+const harness = await createAgentHarness(workspaceBundle);
+```
+
+#### Run A Simple Request
+
+Use `run(...)` with an `agentId` and plain-text `input`. The return value includes:
+
+- `threadId`: stable conversation id
+- `runId`: the current execution id
+- `state`: final state such as `completed` or `waiting_for_approval`
+- `output`: final visible model output
+
+```ts
+import { createAgentHarness, run, stop } from "@botbotgo/agent-harness";
+
+const harness = await createAgentHarness("/absolute/path/to/workspace");
+
+try {
+  const result = await run(harness, {
+    agentId: "direct",
+    input: "Summarize what this workspace is for.",
+  });
+
+  console.log(result.threadId);
+  console.log(result.runId);
+  console.log(result.state);
+  console.log(result.output);
+} finally {
+  await stop(harness);
+}
+```
+
+#### Let The Harness Choose The Host Agent
+
+If your workspace defines runtime routing, use `agentId: "auto"` to let the harness choose between host agents such as `direct` and `orchestra`.
+
+```ts
+const result = await run(harness, {
+  agentId: "auto",
+  input: "Inspect this repository and explain how the release flow works.",
+});
+```
+
+Use this mode when your application should not hardcode the host agent choice.
+
+#### Stream Chunks And Runtime Events
+
+`run(...)` accepts listeners for streamed output and runtime activity. This is the main SDK path for CLIs, chat UIs, and debug logging.
+
+```ts
+const result = await run(harness, {
+  agentId: "orchestra",
+  input: "Inspect the workspace and explain the available agents.",
+  listeners: {
+    onChunk(chunk) {
+      process.stdout.write(chunk);
+    },
+    onEvent(event) {
+      console.log("event:", event.eventType, event.payload);
+    },
+    onStep(step) {
+      console.log("step:", step);
+    },
+    onToolResult(item) {
+      console.log("tool:", item.toolName, item.output);
+    },
+  },
+});
+```
+
+Listener usage by type:
+
+- `onChunk`: streamed user-visible response text
+- `onEvent`: raw runtime events
+- `onStep`: higher-level execution step messages
+- `onToolResult`: completed tool outputs
+- `onReasoning`: reasoning-channel text when available from the runtime
+
+#### Subscribe To Global Harness Events
+
+Use `subscribe(...)` when you want a process-wide event feed rather than per-run listeners.
+
+```ts
+import { subscribe } from "@botbotgo/agent-harness";
+
+const unsubscribe = subscribe(harness, (event) => {
+  console.log(event.threadId, event.runId, event.eventType);
+});
+
+// later
+unsubscribe();
+```
+
+This is useful when one process is handling multiple runs or updating a central UI.
+
+#### Continue An Existing Thread
+
+Pass an existing `threadId` to keep the conversation on the same persisted thread.
+
+```ts
+const first = await run(harness, {
+  agentId: "direct",
+  input: "Remember that the release branch is master.",
+});
+
+const second = await run(harness, {
+  agentId: "direct",
+  threadId: first.threadId,
+  input: "What did I just tell you about the release branch?",
+});
+```
+
+#### Read Back Thread State
+
+Use `getThread(...)` to fetch persisted thread data after a run completes.
+
+```ts
+import { getThread } from "@botbotgo/agent-harness";
+
+const thread = await getThread(harness, result.threadId);
+
+console.log(thread?.threadId);
+console.log(thread?.messages.at(-1)?.content);
+```
+
+Use this when your app needs to reopen a conversation, render history, or inspect the latest assistant message.
+
+#### Handle Approval Or Interrupt Flows
+
+Some runs can pause with `state: "waiting_for_approval"`. In that case, call `run(...)` again with the thread or approval decision payload instead of starting a new request.
+
+```ts
+const pending = await run(harness, {
+  agentId: "orchestra",
+  input: "Run the protected action if approval is required.",
+});
+
+if (pending.state === "waiting_for_approval" && pending.approvalId) {
+  const resumed = await run(harness, {
+    threadId: pending.threadId,
+    runId: pending.runId,
+    approvalId: pending.approvalId,
+    decision: "approve",
+  });
+
+  console.log(resumed.output);
+}
+```
+
+Use `decision: "edit"` plus `editedInput` when your application exposes approval-time parameter editing.
+
+#### Always Stop The Harness
+
+Call `stop(...)` before process exit so the runtime can close adapters and flush state cleanly.
+
+```ts
+await stop(harness);
+```
+
+For most applications, the safe pattern is `try/finally`.
+
+#### Complete SDK CLI Example
+
+The following example shows a small CLI-style integration that:
+
+- loads a workspace from disk
+- starts a first run with streaming output
+- continues the same thread
+- reads the saved thread state back
+- shuts the harness down cleanly
+
+```ts
+import { createAgentHarness, getThread, run, stop } from "@botbotgo/agent-harness";
+
+const workspaceRoot = "/absolute/path/to/workspace";
+const harness = await createAgentHarness(workspaceRoot);
+
+try {
+  const first = await run(harness, {
+    agentId: "auto",
+    input: "Explain what agents and tools are available in this workspace.",
+    listeners: {
+      onChunk(chunk) {
+        process.stdout.write(chunk);
+      },
+      onStep(step) {
+        console.log("\n[step]", step);
+      },
+    },
+  });
+
+  console.log("\nfirst run:", first.runId, first.state);
+
+  const second = await run(harness, {
+    agentId: "auto",
+    threadId: first.threadId,
+    input: "Now give me the shortest possible summary in 3 bullets.",
+  });
+
+  console.log("\nsecond run output:\n", second.output);
+
+  const thread = await getThread(harness, first.threadId);
+  console.log("\nthread message count:", thread?.messages.length ?? 0);
+} finally {
+  await stop(harness);
+}
+```
+
+For a real CLI entrypoint, wrap this in an async `main()` and feed the prompt from `process.argv`.
+
 ```ts
 import { createAgentHarness, getThread, run, subscribe, stop } from "@botbotgo/agent-harness";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "Agent Harness framework package",
   "type": "module",
   "packageManager": "npm@10.9.2",