@deepagents/experimental 7.5.0 → 7.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -30,9 +30,8 @@ for the public API and lifecycle mapping.
30
30
 
31
31
  ## `@deepagents/experimental/zukhruf`
32
32
 
33
- Zukhruf is an internal DSL for **declaring** an agent, plus a **runtime** that
34
- executes that declaration as a **durable background agent** — built on
35
- `@deepagents/context` primitives (`agent()`, `ContextEngine`, `AgentSandbox`,
33
+ Zukhruf provides a declaration API and a runtime for durable background agents,
34
+ built on `@deepagents/context` primitives (`agent()`, `ContextEngine`, `AgentSandbox`,
36
35
  fragments, the stream subsystem).
37
36
 
38
37
  ```ts
@@ -59,15 +58,25 @@ across workers and restarts that resume the same approval. A `toolApproval`
59
58
  map overrides `needsApproval` for the listed tools; unlisted tools keep their
60
59
  own rules. A callback controls every tool call, including tools added by the
61
60
  runtime. The runtime stores approvals and resumes turns after a decision.
62
- `defineAgent()` also accepts the AI SDK `stopWhen`, which ends the agent loop of
63
- a turn, for example `[hasToolCall('notify'), isStepCount(6)]`. Without it, a
64
- turn uses the default of `agent()` in `@deepagents/context`.
61
+
62
+ `defineAgent()` also accepts the AI SDK's `stopWhen`: one condition or an array
63
+ of conditions imported from `ai`. For example,
64
+ `[hasToolCall('notify'), isStepCount(6)]` stops after a step calls `notify` or
65
+ after six completed steps, whichever happens first. A step can execute several
66
+ tool calls before the condition is checked. The default is `isStepCount(200)`,
67
+ inherited from `agent()` in `@deepagents/context`.
65
68
 
66
69
  If the provider interrupts a response, the runtime retains partial output
67
70
  and marks the turn `failed` without automatically retrying it. Compaction
68
71
  keeps the input token and prompt cache measurements from the last successful
69
72
  step.
70
73
 
74
+ If a response ends midway through a tool's arguments, chat persistence records
75
+ that call as `output-error` with the message
76
+ `Tool input ended before the call was complete.` The incomplete call does not
77
+ execute or leave the conversation waiting for client input, so the next queued
78
+ user turn can proceed.
79
+
71
80
  The `AgentHost` returned by `AgentRuntime.initialize()` exposes enqueue, host
72
81
  mailbox delivery, observation, approval, denial, worker lifecycle, and
73
82
  model-facing collaboration for declared subagents. Its control plane, executor,
@@ -107,6 +116,13 @@ adapters without registering them with `resources`; those adapters remain
107
116
  caller-owned. Host and worker disposal always wait for active work. Only
108
117
  registered adapters are released by host disposal.
109
118
 
119
+ The runtime also owns each sandbox handle returned by the agent's `sandbox`
120
+ factory. It acquires a handle for a turn and disposes it when execution ends,
121
+ including on failure. Return a handle that can be disposed independently on
122
+ each call. A backend's disposal policy determines whether the underlying
123
+ sandbox is retained; a named Microsandbox microVM can outlive its turn's
124
+ client handle.
125
+
110
126
  Zukhruf discovers immediate `skills/<name>/SKILL.md` children from each
111
127
  configured sandbox once per conversation. It persists only the ordered catalog
112
128
  (`name`, `description`, and model-visible `path`) in chat metadata so later turns
package/dist/index.js CHANGED
@@ -3059,6 +3059,7 @@ var AgentTurnExecutor = class {
3059
3059
  #approvals;
3060
3060
  #multiAgent;
3061
3061
  #plugins;
3062
+ #sandboxes;
3062
3063
  #publishConversationStatus;
3063
3064
  constructor(options) {
3064
3065
  this.#store = options.store;
@@ -3068,6 +3069,7 @@ var AgentTurnExecutor = class {
3068
3069
  this.#approvals = options.approvals;
3069
3070
  this.#multiAgent = options.multiAgent;
3070
3071
  this.#plugins = options.plugins;
3072
+ this.#sandboxes = options.sandboxes;
3071
3073
  this.#publishConversationStatus = options.publishConversationStatus;
3072
3074
  }
3073
3075
  async execute(turn, context) {
@@ -3117,11 +3119,10 @@ var AgentTurnExecutor = class {
3117
3119
  }
3118
3120
  await this.#controlPlane.recordLatestTurn(turn, turn.streamId);
3119
3121
  await this.#prepareChain(turn, engine, communications);
3120
- const sandbox = await declaration.sandbox({
3122
+ const sandbox = await this.#sandboxes.acquire(declaration, {
3121
3123
  chatId: turn.chatId,
3122
3124
  userId: turn.userId
3123
3125
  });
3124
- await using _turnSandbox = sandbox.sandbox;
3125
3126
  const agentSkills = await this.#skillsFor(
3126
3127
  turn,
3127
3128
  declaration.name,
@@ -3627,6 +3628,36 @@ var ApprovalController = class _ApprovalController {
3627
3628
  }
3628
3629
  };
3629
3630
 
3631
+ // packages/experimental/src/zukhruf/runtime/conversation-sandboxes.ts
3632
+ var ConversationSandboxes = class {
3633
+ // One memoized acquisition for each declaration and conversation.
3634
+ #held = /* @__PURE__ */ new Map();
3635
+ acquire(declaration, context) {
3636
+ const key = JSON.stringify([
3637
+ declaration.name,
3638
+ context.chatId,
3639
+ context.userId
3640
+ ]);
3641
+ const held = this.#held.get(key);
3642
+ if (held !== void 0) return held();
3643
+ const acquiring = declaration.sandbox(context).catch((error) => {
3644
+ this.#held.delete(key);
3645
+ throw error;
3646
+ });
3647
+ this.#held.set(key, () => acquiring);
3648
+ return acquiring;
3649
+ }
3650
+ async [Symbol.asyncDispose]() {
3651
+ await using handles = new AsyncDisposableStack();
3652
+ const acquired = await Promise.allSettled(
3653
+ Array.from(this.#held.values(), (held) => held())
3654
+ );
3655
+ this.#held.clear();
3656
+ for (const result of acquired)
3657
+ if (result.status === "fulfilled") handles.use(result.value.sandbox);
3658
+ }
3659
+ };
3660
+
3630
3661
  // packages/experimental/src/zukhruf/runtime/conversation-status/projector.ts
3631
3662
  import { Latch } from "@zukhruf/async";
3632
3663
  import { Mutex } from "@zukhruf/mutex";
@@ -4761,6 +4792,7 @@ var RuntimeHost = class {
4761
4792
  subagents: (declaration.subagents ?? []).map(({ name }) => name)
4762
4793
  }))
4763
4794
  };
4795
+ const sandboxes = resources.use(new ConversationSandboxes());
4764
4796
  this.#executor = new AgentTurnExecutor({
4765
4797
  store: options.store,
4766
4798
  streams,
@@ -4769,6 +4801,7 @@ var RuntimeHost = class {
4769
4801
  approvals,
4770
4802
  multiAgent,
4771
4803
  plugins,
4804
+ sandboxes,
4772
4805
  publishConversationStatus: (conversation) => conversationStatus.publish(conversation)
4773
4806
  });
4774
4807
  this.#pluginHost = {
@@ -4781,9 +4814,9 @@ var RuntimeHost = class {
4781
4814
  listHistory: () => this.listHistory(),
4782
4815
  observe: (conversation) => this.observe(conversation),
4783
4816
  subscribeConversationStatus: (signal) => this.subscribeConversationStatus(signal),
4784
- // Attaches through the declaration directly: resolving the conversation
4785
- // through the control plane would create its root thread.
4786
- sandbox: (conversation) => this.#root.sandbox({
4817
+ // Borrows the root declaration's sandbox directly: resolving the
4818
+ // conversation through the control plane would create its root thread.
4819
+ sandbox: (conversation) => sandboxes.acquire(this.#root, {
4787
4820
  chatId: conversation.chatId,
4788
4821
  userId: conversation.userId
4789
4822
  })