@claudebuddy/claudebuddy-agent-sdk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 0.5.0 — 2026-09-10
+
+- Apply tool permissions consistently to built-in, MCP, override and child tools;
+  isolate built-in mutable state by Agent session.
+- Preserve terminal errors, cancellation and usage in prompt results; share budgets
+  across goal rounds, subagents and compaction.
+- Forward cancellation to provider/MCP transports and retry waits. Preserve history
+  and clean up when consumers exit the query iterator early.
+- Stream incremental text/tool arguments from Anthropic and OpenAI-compatible APIs;
+  execute tool calls only after complete responses. Preserve mutation barriers in
+  tool scheduling and parallelize only explicitly safe adjacent reads.
+- Checkpoint conversation progress during execution and record replayable semantic
+  events. Resume unknown tool outcomes explicitly without automatically replaying
+  side effects.
+- Implement query-scoped background Bash/subagent execution with task output,
+  waiting, cancellation, bounded output and completion notifications. Join work
+  before final accounting and cancel it on interrupted runs.
+- Disable scheduler/remote-trigger placeholders in model tool schemas. Clarify that
+  the current LSP fallback performs lexical search, not semantic analysis.
+- Add 69 offline regression tests, including local HTTP/MCP transport coverage.
+
+### Migration notes
+
+- An explicit empty allowedTools list exposes no tools. Query overrides cannot widen
+  constructor allow/deny bounds. Default bypassPermissions remains unchanged.
+- Unsupported sandbox enforcement throws. Only one query/goal may own an Agent at
+  a time. Use separate Agents for concurrent conversations.
+- Pass agent.getToolState() to session-specific built-in helper functions. Global
+  helper defaults no longer configure Agent instances.
+- Check prompt().is_error and subtype before treating output as success.
+- Persistence now occurs during execution; set persistSession:false for host-owned
+  storage. Session storage remains single-writer, without exactly-once side effects.
+- Background work is scoped to its creating query; it is not a cross-query daemon.
+  See docs/background-tasks.md and docs/runtime-progress.md for limits.

package/README.md

@@ -1,12 +1,11 @@
-# Open Agent SDK (TypeScript)
+# ClaudeBuddy Agent SDK (TypeScript)
 
 [![npm version](https://img.shields.io/npm/v/@claudebuddy/claudebuddy-agent-sdk)](https://www.npmjs.com/package/@claudebuddy/claudebuddy-agent-sdk)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-Open-source Agent SDK that runs the full agent loop **in-process** — no subprocess or CLI required. Supports both **Anthropic** and **OpenAI-compatible** APIs. Deploy anywhere: cloud, serverless, Docker, CI/CD.
+claudebuddy Agent SDK that runs the full agent loop **in-process** — no subprocess or CLI required. Supports both **Anthropic** and **OpenAI-compatible** APIs. Deploy anywhere: cloud, serverless, Docker, CI/CD.
 
-Also available in **Go**: [open-agent-sdk-go](https://github.com/claudebuddy/claudebuddy-agent-sdk)
 
 ## Get started
 
@@ -486,6 +485,79 @@ Start the web UI:
 npx tsx examples/web/server.ts
 ```
 
+## Background tasks
+
+`Bash` and `Agent` support `run_in_background: true`, returning a `task_id` for
+`TaskOutput` and `TaskStop`. Tasks execute within the current query; the engine
+joins them before its final result and cancels them on interruption. See
+[background execution](docs/background-tasks.md) for output, cancellation and
+lifecycle details. Scheduler placeholders are currently excluded from model tools.
+
+## Streaming and recovery
+
+Set `includePartialMessages: true` to receive real text/tool argument deltas from
+Anthropic and OpenAI-compatible transports. The final `assistant` event contains the
+complete response. Tool calls execute only after completion; adjacent explicitly
+safe reads may run concurrently, preserving mutation barriers.
+
+With persistence enabled, progress is checkpointed during execution and semantic
+events can be replayed with `readSessionEvents(sessionId, afterId?)`. Unknown tool
+outcomes are marked on resume and are not automatically replayed. See
+[streaming, scheduling and recovery](docs/runtime-progress.md) for usage, failure
+semantics and the single-writer storage requirement.
+
+## Runtime reliability and compatibility
+
+Each `Agent` owns its conversation and built-in tool state. Only one query or goal
+may run on an Agent at a time; use separate Agents for concurrent conversations.
+Children intentionally share the parent session state, cancellation signal and
+execution budget, while inheriting its available tools and permission policy.
+`clear()` clears conversation and tool state, retaining connected MCP servers.
+Configure session-specific helpers with the Agent's state handle, for example
+`setQuestionHandler(handler, agent.getToolState())`. Helpers called without a state
+handle retain legacy standalone behavior and do not configure Agent instances.
+
+Tool allow/deny lists apply to built-in, MCP and replacement tools. Query overrides
+can narrow the constructor's lists; `allowedTools: []` exposes no tools. Denials win.
+
+| Permission mode | Execution policy |
+| --- | --- |
+| `bypassPermissions` (default) | Available tools are permitted; a supplied `canUseTool` callback may still deny. |
+| `plan` | Only tools declaring `isReadOnly() === true`; callbacks cannot permit mutations. |
+| `default`, `auto` | Read-only or explicitly allowed tools are preapproved; other tools require an allowing callback. `auto` currently uses this deterministic policy. |
+| `dontAsk` | Read-only or explicitly allowed tools only. |
+| `acceptEdits` | Also preapproves the built-in file and notebook edit/write tools; other mutations require an allowing callback. |
+
+A supplied callback is still consulted for preapproved tools. Tool metadata and
+custom tool implementations are trusted host code. These policies do not provide
+OS isolation: requesting sandbox enforcement throws an explicit unsupported error.
+Goal runs additionally expose their internal goal-reporting tool.
+
+`prompt()` returns `subtype`, `is_error`, `errors` and `total_cost_usd` alongside text
+and usage. Check `is_error` before treating text as a completed answer. Provider
+failures, cancellation, exhausted turns and budget limits remain observable.
+Invalid configuration and overlapping runs throw. Goal execution emits one final
+aggregate result and stops on provider failure, cancellation or a budget limit.
+
+`maxBudgetUsd` covers one ordinary query, or all rounds of one goal, including child
+agents and compaction summaries. Usage and costs accumulate in the same ledger.
+The limit checks whether another request may start; an in-flight request can exceed
+it. Cost is estimated from configured pricing and reported token usage.
+
+Cancellation propagates to Anthropic/OpenAI transports, retry waits, compaction,
+child agents and MCP requests. Custom tools/providers must cooperate with the
+supplied abort signal; cancellation cannot undo completed side effects. Breaking
+out of a query iterator preserves conversation history and releases its run lock.
+
+Run offline regression tests and compile the SDK:
+
+```bash
+npm run test:all
+```
+
+`npm run test:examples` executes the examples separately; these may use live model
+APIs and require credentials.
+
 ## Star History
 
 <a href="https://www.star-history.com/?repos=claudebuddy%2Fclaudebuddy-agent-sdk&type=timeline&legend=top-left">

package/dist/agent.d.ts

@@ -34,6 +34,9 @@ export declare class Agent {
     private abortCtrl;
     private currentEngine;
     private hookRegistry;
+    private sessionState;
+    private activeRun;
+    private closed;
     constructor(options?: AgentOptions);
     /**
      * Resolve API type from options, env, or model name heuristic.
@@ -54,38 +57,25 @@ export declare class Agent {
      * Async initialization: connect MCP servers, register agents, resume sessions.
      */
     private setup;
-    /**
-     * Run a query with streaming events.
-     */
+    /** Run one query, or an explicitly configured goal, with exclusive session ownership. */
     query(prompt: string | any[], overrides?: Partial<AgentOptions>): AsyncGenerator<SDKMessage, void>;
-    /**
-     * Convenience method: send a prompt and collect the final answer as a single object.
-     * Internally iterates through the streaming query and aggregates the outcome.
-     */
+    /** A controller and ledger outlive every round/child in this run. */
+    private withRun;
+    private queryOnce;
+    /** Collect text and retain the final status instead of hiding engine failures. */
     prompt(text: string, overrides?: Partial<AgentOptions>): Promise<QueryResult>;
-    /**
-     * Goal-driven autonomous loop.
-     *
-     * Runs the agent toward `goal` over up to `maxRounds` rounds. Unlike a single
-     * `query`, the agent keeps working ("give it a task and let it run until done")
-     * and only stops when:
-     *  - it calls the injected `update_goal` tool with goal_status="complete", or
-     *  - it reports goal_status="blocked", or
-     *  - `maxRounds` is exhausted (returns with a helpful error event), or
-     *  - it is aborted.
-     *
-     * The `update_goal` internal tool is injected into the tool pool and a
-     * goal-mode system prompt is appended, so the agent knows it should keep
-     * working autonomously and how to signal completion.
-     */
+    /** Goal rounds share cancellation, accounting and a run-local goal report. */
     runGoal(goal: string, overrides?: {
         maxGoalRounds?: number;
         turnsPerRound?: number;
     }): AsyncGenerator<SDKMessage, void>;
+    private runGoalInternal;
     /**
      * Get conversation messages.
      */
     getMessages(): Message[];
+    /** Pass this session handle to built-in state helpers such as setQuestionHandler. */
+    getToolState(): Map<string, unknown>;
     /**
      * Reset conversation history.
      */

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EAGV,OAAO,EACP,cAAc,EACf,MAAM,YAAY,CAAA;AAYnB,OAAO,EAAoC,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAarF,qBAAa,KAAK;IAChB,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,GAAG,CAAQ;IACnB,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,aAAa,CAA2B;IAChD,OAAO,CAAC,YAAY,CAAc;gBAEtB,OAAO,GAAE,YAAiB;IAkDtC;;OAEG;IACH,OAAO,CAAC,cAAc;IAgCtB,wEAAwE;IACxE,OAAO,CAAC,eAAe;IAevB;;;OAGG;IACH,OAAO,CAAC,OAAO;IAIf,6EAA6E;IAC7E,OAAO,CAAC,WAAW;IAInB,wDAAwD;IACxD,OAAO,CAAC,aAAa;IAerB;;OAEG;YACW,KAAK;IA2CnB;;OAEG;IACI,KAAK,CACV,MAAM,EAAE,MAAM,GAAG,GAAG,EAAE,EACtB,SAAS,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAChC,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC;IAuInC;;;OAGG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAChC,OAAO,CAAC,WAAW,CAAC;IA+BvB;;;;;;;;;;;;;;OAcG;IACI,OAAO,CACZ,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7D,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC;IAyFnC;;OAEG;IACH,WAAW,IAAI,OAAO,EAAE;IAIxB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;OAEG;IACG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C;;OAEG;IACG,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D;;OAEG;IACG,oBAAoB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3E;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7C;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB7B;AAMD,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,OAAO,GAAE,YAAiB,GAAG,KAAK,CAE7D;AAMD;;;GAGG;AACH,wBAAuB,KAAK,CAAC,MAAM,EAAE;IACnC,MAAM,EAAE,MAAM,GAAG,GAAG,EAAE,CAAA;IACtB,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB,GAAG,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC,CAOnC"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}