@deepagents/experimental 6.0.0 → 6.1.0
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 +8 -0
- package/dist/index.js +143 -31
- package/dist/index.js.map +4 -4
- package/dist/zukhruf/agent.d.ts +5 -1
- package/dist/zukhruf/agent.d.ts.map +1 -1
- package/dist/zukhruf/index.js +143 -31
- package/dist/zukhruf/index.js.map +4 -4
- package/dist/zukhruf/runtime/agent-runtime.d.ts +1 -1
- package/dist/zukhruf/runtime/agent-runtime.d.ts.map +1 -1
- package/dist/zukhruf/runtime/agent-skills.d.ts +9 -0
- package/dist/zukhruf/runtime/agent-skills.d.ts.map +1 -0
- package/dist/zukhruf/runtime/agent-turn-executor.d.ts.map +1 -1
- package/dist/zukhruf/sandbox/define.d.ts +4 -3
- package/dist/zukhruf/sandbox/define.d.ts.map +1 -1
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -40,6 +40,14 @@ and injected collaboration-tool implementations are internal wiring. See
|
|
|
40
40
|
[`TODO.md`](./src/zukhruf/TODO.md) for the convergence plan, and
|
|
41
41
|
[`BUGS.md`](./src/zukhruf/BUGS.md) for known residue.
|
|
42
42
|
|
|
43
|
+
Zukhruf discovers immediate `skills/<name>/SKILL.md` children from each
|
|
44
|
+
configured sandbox once per conversation. It persists only the ordered catalog
|
|
45
|
+
(`name`, `description`, and model-visible `path`) in chat metadata so later turns
|
|
46
|
+
and process restarts reconstruct the same prompt fragment without rediscovery.
|
|
47
|
+
Skill bodies, scripts, references, and assets remain in the sandbox. Providers
|
|
48
|
+
may preinstall or mount them, or opt into the existing `uploadDirectory` support
|
|
49
|
+
when creating the sandbox.
|
|
50
|
+
|
|
43
51
|
Runnable end-to-end showcases live in
|
|
44
52
|
[`demo/zukhruf-simple`](../../demo/zukhruf-simple) (the smallest complete
|
|
45
53
|
deployable unit),
|
package/dist/index.js
CHANGED
|
@@ -362,17 +362,17 @@ var AgentPath = class _AgentPath {
|
|
|
362
362
|
return new _AgentPath("/root");
|
|
363
363
|
}
|
|
364
364
|
static parse(value) {
|
|
365
|
-
const
|
|
366
|
-
if (
|
|
365
|
+
const path2 = value.trim();
|
|
366
|
+
if (path2 !== "/root" && !path2.startsWith("/root/")) {
|
|
367
367
|
throw new Error(`agent path "${value}" must start at /root`);
|
|
368
368
|
}
|
|
369
|
-
const segments =
|
|
369
|
+
const segments = path2.slice(1).split("/");
|
|
370
370
|
if (segments.some(
|
|
371
371
|
(segment) => segment.length === 0 || segment !== segment.trim() || segment === "." || segment === ".."
|
|
372
372
|
)) {
|
|
373
373
|
throw new Error(`agent path "${value}" contains an invalid segment`);
|
|
374
374
|
}
|
|
375
|
-
return new _AgentPath(
|
|
375
|
+
return new _AgentPath(path2);
|
|
376
376
|
}
|
|
377
377
|
/** Relative targets name descendants; absolute targets keep their canonical path. */
|
|
378
378
|
resolve(target) {
|
|
@@ -440,17 +440,17 @@ var AgentThread = class _AgentThread {
|
|
|
440
440
|
if (typeof treeId !== "string" || !_AgentThread.#isRecord(zukhruf)) {
|
|
441
441
|
return void 0;
|
|
442
442
|
}
|
|
443
|
-
const { path, parentChatId, declarationName, lastTurnId } = zukhruf;
|
|
444
|
-
if (typeof
|
|
443
|
+
const { path: path2, parentChatId, declarationName, lastTurnId } = zukhruf;
|
|
444
|
+
if (typeof path2 !== "string" || parentChatId !== null && typeof parentChatId !== "string" || typeof declarationName !== "string" || lastTurnId !== void 0 && typeof lastTurnId !== "string") {
|
|
445
445
|
return void 0;
|
|
446
446
|
}
|
|
447
447
|
let parsedPath;
|
|
448
448
|
try {
|
|
449
|
-
parsedPath = AgentPath.parse(
|
|
449
|
+
parsedPath = AgentPath.parse(path2);
|
|
450
450
|
} catch {
|
|
451
451
|
return void 0;
|
|
452
452
|
}
|
|
453
|
-
if (parsedPath.toString() !==
|
|
453
|
+
if (parsedPath.toString() !== path2) return void 0;
|
|
454
454
|
try {
|
|
455
455
|
return new _AgentThread({
|
|
456
456
|
conversation,
|
|
@@ -671,20 +671,20 @@ var AgentDirectory = class _AgentDirectory {
|
|
|
671
671
|
);
|
|
672
672
|
}
|
|
673
673
|
async resolve(thread, target) {
|
|
674
|
-
const
|
|
674
|
+
const path2 = thread.path.resolve(target);
|
|
675
675
|
const match = await this.find(thread, target);
|
|
676
676
|
if (match) return match;
|
|
677
|
-
throw new Error(`agent path "${
|
|
677
|
+
throw new Error(`agent path "${path2}" does not exist in this tree`);
|
|
678
678
|
}
|
|
679
679
|
async find(thread, target) {
|
|
680
|
-
const
|
|
680
|
+
const path2 = thread.path.resolve(target);
|
|
681
681
|
return (await this.listTree(thread)).find(
|
|
682
|
-
(candidate) => candidate.path.equals(
|
|
682
|
+
(candidate) => candidate.path.equals(path2)
|
|
683
683
|
);
|
|
684
684
|
}
|
|
685
685
|
async createChild(options) {
|
|
686
|
-
const
|
|
687
|
-
const pathString =
|
|
686
|
+
const path2 = options.parent.path.resolve(options.taskName);
|
|
687
|
+
const pathString = path2.toString();
|
|
688
688
|
const conversation = {
|
|
689
689
|
chatId: _AgentDirectory.#childChatId(
|
|
690
690
|
options.parent.conversation.userId,
|
|
@@ -694,7 +694,7 @@ var AgentDirectory = class _AgentDirectory {
|
|
|
694
694
|
userId: options.parent.conversation.userId
|
|
695
695
|
};
|
|
696
696
|
const occupied = (await this.listTree(options.parent)).find(
|
|
697
|
-
(thread) => thread.path.equals(
|
|
697
|
+
(thread) => thread.path.equals(path2)
|
|
698
698
|
);
|
|
699
699
|
if (occupied && occupied.conversation.chatId !== conversation.chatId) {
|
|
700
700
|
throw new Error(`agent path "${pathString}" already exists`);
|
|
@@ -702,7 +702,7 @@ var AgentDirectory = class _AgentDirectory {
|
|
|
702
702
|
const child = new AgentThread({
|
|
703
703
|
conversation,
|
|
704
704
|
treeId: options.parent.treeId,
|
|
705
|
-
path,
|
|
705
|
+
path: path2,
|
|
706
706
|
parentChatId: options.parent.conversation.chatId,
|
|
707
707
|
declarationName: options.declarationName
|
|
708
708
|
});
|
|
@@ -720,9 +720,9 @@ var AgentDirectory = class _AgentDirectory {
|
|
|
720
720
|
}
|
|
721
721
|
return stored;
|
|
722
722
|
}
|
|
723
|
-
static #childChatId(userId, treeId,
|
|
723
|
+
static #childChatId(userId, treeId, path2) {
|
|
724
724
|
return uuidv5(
|
|
725
|
-
`urn:deepagents:zukhruf:agent:${JSON.stringify([userId, treeId,
|
|
725
|
+
`urn:deepagents:zukhruf:agent:${JSON.stringify([userId, treeId, path2])}`,
|
|
726
726
|
uuidv5.URL
|
|
727
727
|
);
|
|
728
728
|
}
|
|
@@ -1863,6 +1863,59 @@ function configureTool(collaborationTool, config) {
|
|
|
1863
1863
|
};
|
|
1864
1864
|
}
|
|
1865
1865
|
|
|
1866
|
+
// packages/experimental/src/zukhruf/runtime/agent-skills.ts
|
|
1867
|
+
import path from "node:path";
|
|
1868
|
+
import {
|
|
1869
|
+
parseFrontmatter,
|
|
1870
|
+
skills
|
|
1871
|
+
} from "@deepagents/context";
|
|
1872
|
+
var EMPTY_SKILLS = { available: [], fragments: [] };
|
|
1873
|
+
async function discoverAgentSkills(sandbox, signal) {
|
|
1874
|
+
if (sandbox.workingDirectory === void 0) return EMPTY_SKILLS;
|
|
1875
|
+
const skillsDirectory = path.posix.join(sandbox.workingDirectory, "skills");
|
|
1876
|
+
const quotedSkillsDirectory = shellQuote(skillsDirectory);
|
|
1877
|
+
const result = await sandbox.sandbox.executeCommand(
|
|
1878
|
+
`if [ -d ${quotedSkillsDirectory} ]; then find ${quotedSkillsDirectory} -mindepth 1 -maxdepth 1 -type d -print; fi`,
|
|
1879
|
+
{ signal }
|
|
1880
|
+
);
|
|
1881
|
+
if (result.exitCode !== 0) {
|
|
1882
|
+
throw new Error(
|
|
1883
|
+
`AgentRuntime: failed to discover sandbox skills: ${result.stderr.trim() || `exit ${result.exitCode}`}`
|
|
1884
|
+
);
|
|
1885
|
+
}
|
|
1886
|
+
const skillDirectories = result.stdout.split("\n").filter(Boolean).filter((directory) => !path.posix.basename(directory).startsWith(".")).toSorted();
|
|
1887
|
+
if (skillDirectories.length === 0) return EMPTY_SKILLS;
|
|
1888
|
+
const discovered = await Promise.all(
|
|
1889
|
+
skillDirectories.map((directory) => loadSkill(sandbox, directory))
|
|
1890
|
+
);
|
|
1891
|
+
return createAgentSkills(discovered);
|
|
1892
|
+
}
|
|
1893
|
+
function createAgentSkills(available) {
|
|
1894
|
+
if (available.length === 0) return EMPTY_SKILLS;
|
|
1895
|
+
const snapshot = [...available];
|
|
1896
|
+
return { available: snapshot, fragments: [skills(snapshot)] };
|
|
1897
|
+
}
|
|
1898
|
+
async function loadSkill(sandbox, directory) {
|
|
1899
|
+
const directoryName = path.posix.basename(directory);
|
|
1900
|
+
const skillMd = await sandbox.sandbox.readFile(
|
|
1901
|
+
path.posix.join(directory, "SKILL.md")
|
|
1902
|
+
);
|
|
1903
|
+
const { frontmatter } = parseFrontmatter(skillMd);
|
|
1904
|
+
if (frontmatter.name !== directoryName) {
|
|
1905
|
+
throw new Error(
|
|
1906
|
+
`AgentRuntime: skill "${frontmatter.name}" must use matching directory "${directoryName}"`
|
|
1907
|
+
);
|
|
1908
|
+
}
|
|
1909
|
+
return {
|
|
1910
|
+
name: frontmatter.name,
|
|
1911
|
+
description: frontmatter.description,
|
|
1912
|
+
path: path.posix.join("skills", directoryName, "SKILL.md")
|
|
1913
|
+
};
|
|
1914
|
+
}
|
|
1915
|
+
function shellQuote(value) {
|
|
1916
|
+
return `'${value.replaceAll("'", "'\\''")}'`;
|
|
1917
|
+
}
|
|
1918
|
+
|
|
1866
1919
|
// packages/experimental/src/zukhruf/runtime/agent-turn-executor.ts
|
|
1867
1920
|
var AgentTurnExecutor = class {
|
|
1868
1921
|
#store;
|
|
@@ -1917,10 +1970,7 @@ var AgentTurnExecutor = class {
|
|
|
1917
1970
|
if (await this.#projectSkippedTerminalTurn(turn)) return;
|
|
1918
1971
|
const { declaration, thread } = await this.#controlPlane.resolve(turn);
|
|
1919
1972
|
const usageHint = thread.path.isRoot ? this.#multiAgentV2.rootAgentUsageHintText : this.#multiAgentV2.subagentUsageHintText;
|
|
1920
|
-
const engine = this.#engineFor(turn)
|
|
1921
|
-
...declaration.instructions,
|
|
1922
|
-
...usageHint === void 0 ? [] : [role(usageHint)]
|
|
1923
|
-
);
|
|
1973
|
+
const engine = this.#engineFor(turn);
|
|
1924
1974
|
if (turn.kind === "ask" || turn.kind === "mailbox") {
|
|
1925
1975
|
const head = (await engine.getMessages()).at(-1);
|
|
1926
1976
|
if (this.#approvals.isPaused(head)) {
|
|
@@ -1944,6 +1994,12 @@ var AgentTurnExecutor = class {
|
|
|
1944
1994
|
chatId: turn.chatId,
|
|
1945
1995
|
userId: turn.userId
|
|
1946
1996
|
});
|
|
1997
|
+
const agentSkills = await this.#skillsFor(turn, sandbox, signal);
|
|
1998
|
+
engine.set(
|
|
1999
|
+
...declaration.instructions,
|
|
2000
|
+
...agentSkills.fragments,
|
|
2001
|
+
...usageHint === void 0 ? [] : [role(usageHint)]
|
|
2002
|
+
);
|
|
1947
2003
|
if (await this.#projectSkippedTerminalTurn(turn)) return;
|
|
1948
2004
|
if (!await this.#streams.claim(turn.streamId)) {
|
|
1949
2005
|
await this.#projectSkippedTerminalTurn(turn);
|
|
@@ -2056,6 +2112,29 @@ var AgentTurnExecutor = class {
|
|
|
2056
2112
|
(communication) => this.#mailboxInputMessage(communication)
|
|
2057
2113
|
);
|
|
2058
2114
|
}
|
|
2115
|
+
async #skillsFor(turn, sandbox, signal) {
|
|
2116
|
+
const chat2 = await this.#store.getChat(turn.chatId);
|
|
2117
|
+
const existing = readSkills(chat2?.metadata);
|
|
2118
|
+
if (existing !== void 0) return createAgentSkills(existing);
|
|
2119
|
+
if (sandbox.workingDirectory === void 0) return createAgentSkills([]);
|
|
2120
|
+
const discovered = await discoverAgentSkills(sandbox, signal);
|
|
2121
|
+
let available = discovered.available;
|
|
2122
|
+
await this.#store.updateChat(turn.chatId, ({ metadata }) => {
|
|
2123
|
+
const persisted = readSkills(metadata);
|
|
2124
|
+
if (persisted !== void 0) {
|
|
2125
|
+
available = persisted;
|
|
2126
|
+
return void 0;
|
|
2127
|
+
}
|
|
2128
|
+
const zukhruf = isRecord2(metadata?.zukhruf) ? metadata.zukhruf : {};
|
|
2129
|
+
return {
|
|
2130
|
+
metadata: {
|
|
2131
|
+
...metadata,
|
|
2132
|
+
zukhruf: { ...zukhruf, skills: available }
|
|
2133
|
+
}
|
|
2134
|
+
};
|
|
2135
|
+
});
|
|
2136
|
+
return available === discovered.available ? discovered : createAgentSkills(available);
|
|
2137
|
+
}
|
|
2059
2138
|
#engineFor({ chatId, userId }) {
|
|
2060
2139
|
return new ContextEngine2({ store: this.#store, chatId, userId });
|
|
2061
2140
|
}
|
|
@@ -2084,6 +2163,22 @@ Payload:
|
|
|
2084
2163
|
${communication.content}`;
|
|
2085
2164
|
}
|
|
2086
2165
|
};
|
|
2166
|
+
function readSkills(metadata) {
|
|
2167
|
+
const zukhruf = metadata?.zukhruf;
|
|
2168
|
+
if (!isRecord2(zukhruf) || !Object.hasOwn(zukhruf, "skills")) {
|
|
2169
|
+
return void 0;
|
|
2170
|
+
}
|
|
2171
|
+
if (!Array.isArray(zukhruf.skills) || !zukhruf.skills.every(isSkill)) {
|
|
2172
|
+
throw new Error("AgentRuntime: stored skill catalog is invalid");
|
|
2173
|
+
}
|
|
2174
|
+
return zukhruf.skills;
|
|
2175
|
+
}
|
|
2176
|
+
function isSkill(value) {
|
|
2177
|
+
return isRecord2(value) && typeof value.name === "string" && typeof value.description === "string" && typeof value.path === "string";
|
|
2178
|
+
}
|
|
2179
|
+
function isRecord2(value) {
|
|
2180
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
2181
|
+
}
|
|
2087
2182
|
|
|
2088
2183
|
// packages/experimental/src/zukhruf/runtime/approval-controller.ts
|
|
2089
2184
|
import {
|
|
@@ -2329,7 +2424,8 @@ var AgentObservation = class {
|
|
|
2329
2424
|
#conversation;
|
|
2330
2425
|
#store;
|
|
2331
2426
|
#streams;
|
|
2332
|
-
|
|
2427
|
+
#queue;
|
|
2428
|
+
constructor(conversation, store, streams, queue) {
|
|
2333
2429
|
this.engine = new ContextEngine4({
|
|
2334
2430
|
store,
|
|
2335
2431
|
chatId: conversation.chatId,
|
|
@@ -2338,6 +2434,7 @@ var AgentObservation = class {
|
|
|
2338
2434
|
this.#conversation = conversation;
|
|
2339
2435
|
this.#store = store;
|
|
2340
2436
|
this.#streams = streams;
|
|
2437
|
+
this.#queue = queue;
|
|
2341
2438
|
}
|
|
2342
2439
|
async resume() {
|
|
2343
2440
|
const id = await this.#headStreamId();
|
|
@@ -2357,8 +2454,9 @@ var AgentObservation = class {
|
|
|
2357
2454
|
if (!id) return;
|
|
2358
2455
|
AgentTurnId.assertOwner(this.#conversation, id);
|
|
2359
2456
|
const status = await this.#streams.store.getStreamStatus(id);
|
|
2360
|
-
if (status === "queued" || status === "running") {
|
|
2457
|
+
if (status === "queued" || status === "running" || status === "cancelled") {
|
|
2361
2458
|
await this.#streams.cancel(id);
|
|
2459
|
+
await this.#queue.cancel(id);
|
|
2362
2460
|
}
|
|
2363
2461
|
}
|
|
2364
2462
|
async #headStreamId() {
|
|
@@ -2439,7 +2537,12 @@ var AgentRuntime = class {
|
|
|
2439
2537
|
return this.#approvals.deny(conversation, input);
|
|
2440
2538
|
}
|
|
2441
2539
|
observe(conversation) {
|
|
2442
|
-
return new AgentObservation(
|
|
2540
|
+
return new AgentObservation(
|
|
2541
|
+
conversation,
|
|
2542
|
+
this.#store,
|
|
2543
|
+
this.#streams,
|
|
2544
|
+
this.#queue
|
|
2545
|
+
);
|
|
2443
2546
|
}
|
|
2444
2547
|
work(options) {
|
|
2445
2548
|
return this.#queue.consume(this.#executor.execute.bind(this.#executor), {
|
|
@@ -2558,9 +2661,9 @@ var BUSY_TIMEOUT_MS = 5e3;
|
|
|
2558
2661
|
var SqliteMailboxStore = class extends MailboxStore {
|
|
2559
2662
|
#database;
|
|
2560
2663
|
#closed = false;
|
|
2561
|
-
constructor(
|
|
2664
|
+
constructor(path2) {
|
|
2562
2665
|
super();
|
|
2563
|
-
this.#database = new DatabaseSync(
|
|
2666
|
+
this.#database = new DatabaseSync(path2, { timeout: BUSY_TIMEOUT_MS });
|
|
2564
2667
|
this.#database.exec(DDL);
|
|
2565
2668
|
}
|
|
2566
2669
|
async beginTurn(recipient, turnId) {
|
|
@@ -3077,11 +3180,20 @@ async function renderTurn(stream) {
|
|
|
3077
3180
|
}
|
|
3078
3181
|
|
|
3079
3182
|
// packages/experimental/src/zukhruf/sandbox/define.ts
|
|
3080
|
-
import {
|
|
3081
|
-
|
|
3082
|
-
} from "@deepagents/context";
|
|
3183
|
+
import { createBashTool } from "@deepagents/context";
|
|
3184
|
+
var DEFAULT_WORKING_DIRECTORY = "/workspace";
|
|
3083
3185
|
function defineSandbox(createBackend, options) {
|
|
3084
|
-
return async (context) =>
|
|
3186
|
+
return async (context) => {
|
|
3187
|
+
const workingDirectory = options?.destination ?? DEFAULT_WORKING_DIRECTORY;
|
|
3188
|
+
return Object.assign(
|
|
3189
|
+
await createBashTool({
|
|
3190
|
+
sandbox: await createBackend(context),
|
|
3191
|
+
...options,
|
|
3192
|
+
destination: workingDirectory
|
|
3193
|
+
}),
|
|
3194
|
+
{ workingDirectory }
|
|
3195
|
+
);
|
|
3196
|
+
};
|
|
3085
3197
|
}
|
|
3086
3198
|
|
|
3087
3199
|
// packages/experimental/src/zukhruf/tool.ts
|