@witqq/agent-sdk 0.1.0 → 0.2.0

package/README.md

@@ -10,11 +10,13 @@ npm install @witqq/agent-sdk zod
 
 ## Backends
 
-| Backend | Peer dependency | Type |
-|---|---|---|
-| `copilot` | `@github/copilot-sdk` | CLI subprocess |
-| `claude` | `@anthropic-ai/claude-agent-sdk` | CLI subprocess |
-| `vercel-ai` | `ai` + `@ai-sdk/openai-compatible` | API-based |
+`zod` is the only required peer dependency. Backend SDKs are **optional** — install only what you use:
+
+| Backend | Peer dependency | Required | Type |
+|---|---|---|---|
+| `copilot` | `@github/copilot-sdk` ^0.1.22 | optional | CLI subprocess |
+| `claude` | `@anthropic-ai/claude-agent-sdk` >=0.2.0 | optional | CLI subprocess |
+| `vercel-ai` | `ai` >=4.0.0 + `@ai-sdk/openai-compatible` >=2.0.0 | optional | API-based |
 
 Install only the backend you need:
 
@@ -194,21 +196,73 @@ for await (const event of agent.stream("Tell me a story")) {
 }
 ```
 
+### Streaming with Conversation History
+
+Use `streamWithContext` to stream with full conversation history:
+
+```typescript
+const messages = [
+  { role: "system" as const, content: "You are helpful." },
+  { role: "user" as const, content: "Hello" },
+  { role: "assistant" as const, content: "Hi! How can I help?" },
+  { role: "user" as const, content: "What is 2+2?" },
+];
+
+for await (const event of agent.streamWithContext(messages)) {
+  if (event.type === "text_delta") process.stdout.write(event.text);
+}
+```
+
 | Event | Fields | Description |
 |-------|--------|-------------|
 | `text_delta` | `text` | Incremental text output |
+| `thinking_delta` | `text` | Incremental reasoning/thinking text |
 | `thinking_start` | — | Model started reasoning |
 | `thinking_end` | — | Model finished reasoning |
-| `tool_call_start` | `toolName`, `args` | Tool invocation began |
-| `tool_call_end` | `toolName`, `result` | Tool invocation completed |
+| `tool_call_start` | `toolCallId`, `toolName`, `args` | Tool invocation began |
+| `tool_call_end` | `toolCallId`, `toolName`, `result` | Tool invocation completed |
 | `permission_request` | `request` | Permission check initiated |
 | `permission_response` | `toolName`, `decision` | Permission decision made |
 | `ask_user` | `request` | User input requested |
 | `ask_user_response` | `answer` | User response received |
-| `usage_update` | `promptTokens`, `completionTokens` | Token usage |
+| `usage_update` | `promptTokens`, `completionTokens`, `model?`, `backend?` | Token usage with metadata |
+| `heartbeat` | — | Keepalive signal during long operations |
 | `error` | `error`, `recoverable` | Error during execution |
 | `done` | `finalOutput`, `structuredOutput?` | Execution completed |
 
+## Usage Tracking
+
+Track token usage with the `onUsage` callback. Called after each `run()`/`runWithContext()`/`runStructured()` completion and during `stream()`/`streamWithContext()` when usage data arrives:
+
+```typescript
+const agent = service.createAgent({
+  systemPrompt: "You are a helpful assistant.",
+  onUsage: (usage) => {
+    console.log(`${usage.backend}/${usage.model}: ${usage.promptTokens}+${usage.completionTokens} tokens`);
+  },
+});
+```
+
+Usage data includes `promptTokens`, `completionTokens`, and optional `model` and `backend` fields. Callback errors are logged but not propagated (fire-and-forget).
+
+## Heartbeat
+
+Keep HTTP streams alive during long tool executions by emitting periodic heartbeat events:
+
+```typescript
+const agent = service.createAgent({
+  systemPrompt: "You are a helpful assistant.",
+  heartbeatInterval: 15000, // emit heartbeat every 15s during gaps
+});
+
+for await (const event of agent.stream("Run a long analysis")) {
+  if (event.type === "heartbeat") continue; // ignore keepalive
+  // handle other events...
+}
+```
+
+When `heartbeatInterval` is set, heartbeat events are emitted during streaming gaps (e.g., while a tool executes). No heartbeats are emitted when backend events flow continuously. The timer is cleaned up when the stream completes, errors, or is aborted.
+
 ## Backend-Specific Options
 
 ### Copilot
@@ -221,6 +275,23 @@ const service = createCopilotService({
   cliPath: "/path/to/copilot",   // optional custom CLI path
   workingDirectory: process.cwd(),
   githubToken: "ghp_...",        // optional, alternative to useLoggedInUser
+  cliArgs: ["--allow-all"],      // extra CLI flags for the subprocess
+});
+```
+
+**System requirements:** `@github/copilot-sdk` includes a native binary that requires glibc. Alpine Linux (musl) is not supported — use `node:20-bookworm-slim` or similar glibc-based images.
+
+**Headless defaults:** When `supervisor.onPermission` or `supervisor.onAskUser` are not provided, the Copilot backend auto-approves permission requests and auto-answers user questions to prevent the SDK from hanging in headless mode.
+
+**System prompt mode:** By default, `systemPrompt` is appended to the Copilot CLI's built-in prompt (`mode: "append"`). Set `systemMessageMode: "replace"` in `AgentConfig` to fully replace it (note: this removes built-in tool instructions).
+
+**Available tools filter:** Use `availableTools` in `AgentConfig` to restrict which Copilot built-in tools are available:
+
+```typescript
+const agent = service.createAgent({
+  systemPrompt: "Research assistant",
+  tools: [],
+  availableTools: ["web_search", "web_fetch"], // only these built-in tools
 });
 ```
 
@@ -297,6 +368,18 @@ import { createClaudeService } from "@witqq/agent-sdk/claude";
 import { createVercelAIService } from "@witqq/agent-sdk/vercel-ai";
 ```
 
+## Model Names
+
+`AgentConfig.model` accepts both full model IDs and short names:
+
+| Backend | Full ID example | Short name |
+|---|---|---|
+| Copilot | `gpt-4o` | (same) |
+| Claude | `claude-sonnet-4-5-20250514` | `sonnet` |
+| Vercel AI | `anthropic/claude-sonnet-4-5` | (provider-specific) |
+
+Use `service.listModels()` to get available model IDs for each backend.
+
 ## Build
 
 ```bash

package/dist/backends/claude.cjs

@@ -54,7 +54,9 @@ var BaseAgent = class {
     this.state = "running";
     try {
       const messages = [{ role: "user", content: prompt }];
-      return await this.executeRun(messages, options, ac.signal);
+      const result = await this.executeRun(messages, options, ac.signal);
+      this.enrichAndNotifyUsage(result);
+      return result;
     } finally {
       this.state = "idle";
       this.abortController = null;
@@ -66,7 +68,9 @@ var BaseAgent = class {
     const ac = this.createAbortController(options?.signal);
     this.state = "running";
     try {
-      return await this.executeRun(messages, options, ac.signal);
+      const result = await this.executeRun(messages, options, ac.signal);
+      this.enrichAndNotifyUsage(result);
+      return result;
     } finally {
       this.state = "idle";
       this.abortController = null;
@@ -79,12 +83,14 @@ var BaseAgent = class {
     this.state = "running";
     try {
       const messages = [{ role: "user", content: prompt }];
-      return await this.executeRunStructured(
+      const result = await this.executeRunStructured(
         messages,
         schema,
         options,
         ac.signal
       );
+      this.enrichAndNotifyUsage(result);
+      return result;
     } finally {
       this.state = "idle";
       this.abortController = null;
@@ -97,7 +103,21 @@ var BaseAgent = class {
     this.state = "streaming";
     try {
       const messages = [{ role: "user", content: prompt }];
-      yield* this.executeStream(messages, options, ac.signal);
+      const enriched = this.enrichStream(this.executeStream(messages, options, ac.signal));
+      yield* this.heartbeatStream(enriched);
+    } finally {
+      this.state = "idle";
+      this.abortController = null;
+    }
+  }
+  async *streamWithContext(messages, options) {
+    this.guardReentrancy();
+    this.guardDisposed();
+    const ac = this.createAbortController(options?.signal);
+    this.state = "streaming";
+    try {
+      const enriched = this.enrichStream(this.executeStream(messages, options, ac.signal));
+      yield* this.heartbeatStream(enriched);
     } finally {
       this.state = "idle";
       this.abortController = null;
@@ -119,6 +139,95 @@ var BaseAgent = class {
     this.abort();
     this.state = "disposed";
   }
+  // ─── Usage Enrichment ───────────────────────────────────────────
+  /** Enrich result usage with model/backend and fire onUsage callback */
+  enrichAndNotifyUsage(result) {
+    if (result.usage) {
+      result.usage = {
+        ...result.usage,
+        model: this.config.model,
+        backend: this.backendName
+      };
+      this.callOnUsage(result.usage);
+    }
+  }
+  /** Wrap a stream to enrich usage_update events and fire onUsage callback */
+  async *enrichStream(source) {
+    for await (const event of source) {
+      if (event.type === "usage_update") {
+        const usage = {
+          promptTokens: event.promptTokens,
+          completionTokens: event.completionTokens,
+          model: this.config.model,
+          backend: this.backendName
+        };
+        this.callOnUsage(usage);
+        yield { type: "usage_update", ...usage };
+      } else {
+        yield event;
+      }
+    }
+  }
+  /** Fire onUsage callback (fire-and-forget: errors logged, not propagated) */
+  callOnUsage(usage) {
+    if (!this.config.onUsage) return;
+    try {
+      this.config.onUsage(usage);
+    } catch (e) {
+      console.warn(
+        "[agent-sdk] onUsage callback error:",
+        e instanceof Error ? e.message : String(e)
+      );
+    }
+  }
+  // ─── Heartbeat ───────────────────────────────────────────────
+  /** Wrap a stream to emit heartbeat events at configured intervals.
+   *  When heartbeatInterval is not set, passes through directly. */
+  async *heartbeatStream(source) {
+    const interval = this.config.heartbeatInterval;
+    if (!interval || interval <= 0) {
+      yield* source;
+      return;
+    }
+    const iterator = source[Symbol.asyncIterator]();
+    let pendingEvent = null;
+    let heartbeatResolve = null;
+    const timer = setInterval(() => {
+      if (heartbeatResolve) {
+        const resolve = heartbeatResolve;
+        heartbeatResolve = null;
+        resolve();
+      }
+    }, interval);
+    try {
+      while (true) {
+        if (!pendingEvent) {
+          pendingEvent = iterator.next();
+        }
+        const heartbeatPromise = new Promise((resolve) => {
+          heartbeatResolve = resolve;
+        });
+        const eventDone = pendingEvent.then(
+          (r) => ({ kind: "event", result: r })
+        );
+        const heartbeatDone = heartbeatPromise.then(
+          () => ({ kind: "heartbeat" })
+        );
+        const winner = await Promise.race([eventDone, heartbeatDone]);
+        if (winner.kind === "heartbeat") {
+          yield { type: "heartbeat" };
+        } else {
+          pendingEvent = null;
+          heartbeatResolve = null;
+          if (winner.result.done) break;
+          yield winner.result.value;
+        }
+      }
+    } finally {
+      clearInterval(timer);
+      heartbeatResolve = null;
+    }
+  }
   // ─── Guards ───────────────────────────────────────────────────
   guardReentrancy() {
     if (this.state === "running" || this.state === "streaming") {
@@ -344,7 +453,31 @@ function aggregateUsage(modelUsage) {
   }
   return { promptTokens, completionTokens };
 }
-function mapSDKMessage(msg, thinkingBlockIndices) {
+var ClaudeToolCallTracker = class {
+  queues = /* @__PURE__ */ new Map();
+  trackStart(toolCallId, toolName) {
+    if (!this.queues.has(toolName)) {
+      this.queues.set(toolName, []);
+    }
+    this.queues.get(toolName).push(toolCallId);
+  }
+  /** Peek at the current tool call ID for a tool name (does not consume) */
+  peekToolCallId(toolName) {
+    const queue = this.queues.get(toolName);
+    if (!queue || queue.length === 0) return "";
+    return queue[0];
+  }
+  /** Consume and return the first tool call ID for a tool name */
+  consumeToolCallId(toolName) {
+    const queue = this.queues.get(toolName);
+    if (!queue || queue.length === 0) return "";
+    return queue.shift();
+  }
+  clear() {
+    this.queues.clear();
+  }
+};
+function mapSDKMessage(msg, thinkingBlockIndices, toolCallTracker) {
   switch (msg.type) {
     case "assistant": {
       const betaMessage = msg.message;
@@ -356,9 +489,15 @@ function mapSDKMessage(msg, thinkingBlockIndices) {
       }
       for (const block of betaMessage.content) {
         if (block.type === "tool_use") {
+          const toolCallId = String(block.id ?? "");
+          const toolName = block.name ?? "unknown";
+          if (toolCallTracker) {
+            toolCallTracker.trackStart(toolCallId, toolName);
+          }
           events.push({
             type: "tool_call_start",
-            toolName: block.name ?? "unknown",
+            toolCallId,
+            toolName,
             args: block.input ?? {}
           });
         }
@@ -375,9 +514,18 @@ function mapSDKMessage(msg, thinkingBlockIndices) {
     case "tool_use_summary": {
       const summary = msg.summary;
       const toolName = msg.tool_name ?? "unknown";
+      const precedingIds = msg.preceding_tool_use_ids;
+      let toolCallId = "";
+      if (precedingIds && precedingIds.length > 0) {
+        toolCallId = precedingIds[0];
+        if (toolCallTracker) toolCallTracker.consumeToolCallId(toolName);
+      } else if (toolCallTracker) {
+        toolCallId = toolCallTracker.consumeToolCallId(toolName);
+      }
       if (summary) {
         return {
           type: "tool_call_end",
+          toolCallId,
           toolName,
           result: summary
         };
@@ -404,7 +552,9 @@ function mapSDKMessage(msg, thinkingBlockIndices) {
     }
     case "tool_progress": {
       const toolName = msg.tool_name;
-      return toolName ? { type: "tool_call_start", toolName, args: {} } : null;
+      if (!toolName) return null;
+      const toolCallId = toolCallTracker?.peekToolCallId(toolName) ?? "";
+      return { type: "tool_call_start", toolCallId, toolName, args: {} };
     }
     case "result": {
       if (msg.subtype === "success") {
@@ -429,6 +579,7 @@ function mapSDKMessage(msg, thinkingBlockIndices) {
   }
 }
 var ClaudeAgent = class extends BaseAgent {
+  backendName = "claude";
   options;
   tools;
   canUseTool;
@@ -609,10 +760,11 @@ var ClaudeAgent = class extends BaseAgent {
     opts = await this.buildMcpConfig(opts);
     const q = sdk.query({ prompt, options: opts });
     const thinkingBlockIndices = /* @__PURE__ */ new Set();
+    const toolCallTracker = new ClaudeToolCallTracker();
     try {
       for await (const msg of q) {
         if (signal.aborted) throw new AbortError();
-        const event = mapSDKMessage(msg, thinkingBlockIndices);
+        const event = mapSDKMessage(msg, thinkingBlockIndices, toolCallTracker);
         if (event) {
           if (Array.isArray(event)) {
             for (const e of event) yield e;