@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 +22 -6
- package/dist/index.js +38 -5
- package/dist/index.js.map +3 -3
- package/dist/zukhruf/index.js +38 -5
- package/dist/zukhruf/index.js.map +3 -3
- package/dist/zukhruf/plugins/conversation-scheduling/index.js.map +2 -2
- package/dist/zukhruf/plugins/schedules/index.js.map +2 -2
- package/dist/zukhruf/runtime/agent-runtime.d.ts.map +1 -1
- package/dist/zukhruf/runtime/agent-turn-executor.d.ts +3 -0
- package/dist/zukhruf/runtime/agent-turn-executor.d.ts.map +1 -1
- package/dist/zukhruf/runtime/conversation-sandboxes.d.ts +16 -0
- package/dist/zukhruf/runtime/conversation-sandboxes.d.ts.map +1 -0
- package/package.json +9 -9
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
|
|
34
|
-
|
|
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
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
|
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
|
-
//
|
|
4785
|
-
// through the control plane would create its root thread.
|
|
4786
|
-
sandbox: (conversation) => this.#root
|
|
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
|
})
|