@witqq/agent-sdk 0.4.0 → 0.5.0

package/README.md

@@ -225,6 +225,7 @@ for await (const event of agent.streamWithContext(messages)) {
 | `permission_response` | `toolName`, `decision` | Permission decision made |
 | `ask_user` | `request` | User input requested |
 | `ask_user_response` | `answer` | User response received |
+| `session_info` | `sessionId`, `transcriptPath?`, `backend` | CLI session metadata (streaming only) |
 | `usage_update` | `promptTokens`, `completionTokens`, `model?`, `backend?` | Token usage with metadata |
 | `heartbeat` | — | Keepalive signal during long operations |
 | `error` | `error`, `recoverable` | Error during execution |
@@ -283,6 +284,15 @@ agent.dispose(); // destroys the persistent session
 
 In persistent mode, if a session encounters an error, it is automatically cleared and recreated on the next call. The `sessionId` property exposes the CLI session ID for logging or external storage.
 
+### Interrupting Running Operations
+
+Call `interrupt()` to gracefully stop a running operation. For CLI backends, this calls the SDK's interrupt/abort method on the active session:
+
+```typescript
+// In another context (e.g., timeout handler)
+await agent.interrupt();
+```
+
 Default (`"per-call"`): each call creates and destroys a fresh session. Multi-message context is passed via prompt augmentation through `runWithContext()`/`streamWithContext()`.
 
 API-based backends (Vercel AI) ignore `sessionMode` — they are stateless by design.
@@ -300,6 +310,7 @@ const service = createCopilotService({
   workingDirectory: process.cwd(),
   githubToken: "ghp_...",        // optional, alternative to useLoggedInUser
   cliArgs: ["--allow-all"],      // extra CLI flags for the subprocess
+  env: { PATH: "/custom/bin" },  // custom env vars for subprocess
 });
 ```
 
@@ -328,11 +339,14 @@ const service = createClaudeService({
   cliPath: "/path/to/claude",    // optional custom CLI path
   workingDirectory: process.cwd(),
   maxTurns: 10,
+  env: { CLAUDE_CONFIG_DIR: "/custom/config" }, // custom env vars for subprocess
 });
 ```
 
 `supervisor.onAskUser` is not supported by the Claude backend; a warning is emitted if set.
 
+When `supervisor.onPermission` is set, the Claude backend automatically sets `permissionMode: "default"` so the CLI invokes the callback instead of using built-in rules.
+
 ### Vercel AI (OpenRouter / OpenAI-compatible)
 
 ```typescript

package/dist/backends/claude.cjs

@@ -132,6 +132,10 @@ var BaseAgent = class {
       this.abortController.abort();
     }
   }
+  /** Default interrupt — falls back to abort(). Backends may override with graceful shutdown. */
+  async interrupt() {
+    this.abort();
+  }
   getState() {
     return this.state;
   }
@@ -589,6 +593,7 @@ var ClaudeAgent = class extends BaseAgent {
   canUseTool;
   isPersistent;
   _sessionId;
+  activeQuery = null;
   constructor(config, options) {
     super(config);
     this.options = options;
@@ -604,10 +609,25 @@ var ClaudeAgent = class extends BaseAgent {
   get sessionId() {
     return this._sessionId;
   }
+  async interrupt() {
+    try {
+      if (this.activeQuery) {
+        await this.activeQuery.interrupt();
+      }
+    } catch {
+    } finally {
+      this.abort();
+    }
+  }
   /** Clear persistent session state after an error so next call starts fresh */
   clearPersistentSession() {
     this._sessionId = void 0;
   }
+  emitSessionInfo(sessionId) {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    const transcriptPath = home ? `${home}/.claude/projects/.session/sessions/${sessionId}/conversation.jsonl` : void 0;
+    return { type: "session_info", sessionId, transcriptPath, backend: "claude" };
+  }
   buildQueryOptions(signal) {
     const ac = new AbortController();
     signal.addEventListener("abort", () => ac.abort(), { once: true });
@@ -627,8 +647,15 @@ var ClaudeAgent = class extends BaseAgent {
     if (this.config.systemPrompt) {
       opts.systemPrompt = this.config.systemPrompt;
     }
-    if (this.options.oauthToken) {
-      opts.env = { ...process.env, CLAUDE_CODE_OAUTH_TOKEN: this.options.oauthToken };
+    if (this.options.oauthToken || this.options.env) {
+      opts.env = {
+        ...process.env,
+        ...this.options.env ?? {},
+        ...this.options.oauthToken ? { CLAUDE_CODE_OAUTH_TOKEN: this.options.oauthToken } : {}
+      };
+    }
+    if (opts.canUseTool && !opts.permissionMode) {
+      opts.permissionMode = "default";
     }
     return opts;
   }
@@ -653,6 +680,7 @@ var ClaudeAgent = class extends BaseAgent {
     const toolResultCapture = /* @__PURE__ */ new Map();
     opts = await this.buildMcpConfig(opts, toolResultCapture);
     const q = sdk.query({ prompt, options: opts });
+    this.activeQuery = q;
     const toolCalls = [];
     let output = null;
     let usage;
@@ -702,6 +730,8 @@ var ClaudeAgent = class extends BaseAgent {
       if (this.isPersistent) this.clearPersistentSession();
       if (signal.aborted) throw new AbortError();
       throw e;
+    } finally {
+      this.activeQuery = null;
     }
     return {
       output,
@@ -728,6 +758,7 @@ var ClaudeAgent = class extends BaseAgent {
       schema: jsonSchema
     };
     const q = sdk.query({ prompt, options: opts });
+    this.activeQuery = q;
     const toolCalls = [];
     let output = null;
     let structuredOutput;
@@ -769,6 +800,8 @@ var ClaudeAgent = class extends BaseAgent {
       if (this.isPersistent) this.clearPersistentSession();
       if (signal.aborted) throw new AbortError();
       throw e;
+    } finally {
+      this.activeQuery = null;
     }
     return {
       output,
@@ -790,6 +823,7 @@ var ClaudeAgent = class extends BaseAgent {
     let opts = this.buildQueryOptions(signal);
     opts = await this.buildMcpConfig(opts);
     const q = sdk.query({ prompt, options: opts });
+    this.activeQuery = q;
     const thinkingBlockIndices = /* @__PURE__ */ new Set();
     const toolCallTracker = new ClaudeToolCallTracker();
     try {
@@ -805,8 +839,11 @@ var ClaudeAgent = class extends BaseAgent {
         }
         if (msg.type === "result" && msg.subtype === "success") {
           const r = msg;
-          if (this.isPersistent && r.session_id) {
-            this._sessionId = r.session_id;
+          if (r.session_id) {
+            if (this.isPersistent) {
+              this._sessionId = r.session_id;
+            }
+            yield this.emitSessionInfo(r.session_id);
           }
           yield { type: "done", finalOutput: r.result };
         }
@@ -815,6 +852,8 @@ var ClaudeAgent = class extends BaseAgent {
       if (this.isPersistent) this.clearPersistentSession();
       if (signal.aborted) throw new AbortError();
       throw e;
+    } finally {
+      this.activeQuery = null;
     }
   }
   dispose() {