@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.
@@ -10,6 +10,10 @@ export interface SandboxContext {
10
10
  chatId: string;
11
11
  userId: string;
12
12
  }
13
+ export type ZukhrufSandbox = AgentSandbox & {
14
+ /** Absolute directory containing this conversation's files and skills. Omit to disable discovery. */
15
+ readonly workingDirectory?: string;
16
+ };
13
17
  export interface AgentDeclaration {
14
18
  /**
15
19
  * Stable declaration identity persisted in conversation metadata.
@@ -18,7 +22,7 @@ export interface AgentDeclaration {
18
22
  */
19
23
  name: string;
20
24
  model: AgentModel;
21
- sandbox: (context: SandboxContext) => Promise<AgentSandbox>;
25
+ sandbox: (context: SandboxContext) => Promise<ZukhrufSandbox>;
22
26
  instructions: ContextFragment[];
23
27
  tools?: ZukhrufToolSet;
24
28
  subagents?: AgentDeclaration[];
@@ -1 +1 @@
1
- {"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/zukhruf/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAEvC,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5D,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,SAAS,CAAC,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAED,wBAAgB,WAAW,CACzB,WAAW,EAAE,gBAAgB,GAC5B,uBAAuB,CAUzB"}
1
+ {"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/zukhruf/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAEvC,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,eAAe,EAChB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG;IAC1C,qGAAqG;IACrG,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC9D,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,SAAS,CAAC,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAED,wBAAgB,WAAW,CACzB,WAAW,EAAE,gBAAgB,GAC5B,uBAAuB,CAUzB"}
@@ -21,17 +21,17 @@ var AgentPath = class _AgentPath {
21
21
  return new _AgentPath("/root");
22
22
  }
23
23
  static parse(value) {
24
- const path = value.trim();
25
- if (path !== "/root" && !path.startsWith("/root/")) {
24
+ const path2 = value.trim();
25
+ if (path2 !== "/root" && !path2.startsWith("/root/")) {
26
26
  throw new Error(`agent path "${value}" must start at /root`);
27
27
  }
28
- const segments = path.slice(1).split("/");
28
+ const segments = path2.slice(1).split("/");
29
29
  if (segments.some(
30
30
  (segment) => segment.length === 0 || segment !== segment.trim() || segment === "." || segment === ".."
31
31
  )) {
32
32
  throw new Error(`agent path "${value}" contains an invalid segment`);
33
33
  }
34
- return new _AgentPath(path);
34
+ return new _AgentPath(path2);
35
35
  }
36
36
  /** Relative targets name descendants; absolute targets keep their canonical path. */
37
37
  resolve(target) {
@@ -99,17 +99,17 @@ var AgentThread = class _AgentThread {
99
99
  if (typeof treeId !== "string" || !_AgentThread.#isRecord(zukhruf)) {
100
100
  return void 0;
101
101
  }
102
- const { path, parentChatId, declarationName, lastTurnId } = zukhruf;
103
- if (typeof path !== "string" || parentChatId !== null && typeof parentChatId !== "string" || typeof declarationName !== "string" || lastTurnId !== void 0 && typeof lastTurnId !== "string") {
102
+ const { path: path2, parentChatId, declarationName, lastTurnId } = zukhruf;
103
+ if (typeof path2 !== "string" || parentChatId !== null && typeof parentChatId !== "string" || typeof declarationName !== "string" || lastTurnId !== void 0 && typeof lastTurnId !== "string") {
104
104
  return void 0;
105
105
  }
106
106
  let parsedPath;
107
107
  try {
108
- parsedPath = AgentPath.parse(path);
108
+ parsedPath = AgentPath.parse(path2);
109
109
  } catch {
110
110
  return void 0;
111
111
  }
112
- if (parsedPath.toString() !== path) return void 0;
112
+ if (parsedPath.toString() !== path2) return void 0;
113
113
  try {
114
114
  return new _AgentThread({
115
115
  conversation,
@@ -330,20 +330,20 @@ var AgentDirectory = class _AgentDirectory {
330
330
  );
331
331
  }
332
332
  async resolve(thread, target) {
333
- const path = thread.path.resolve(target);
333
+ const path2 = thread.path.resolve(target);
334
334
  const match = await this.find(thread, target);
335
335
  if (match) return match;
336
- throw new Error(`agent path "${path}" does not exist in this tree`);
336
+ throw new Error(`agent path "${path2}" does not exist in this tree`);
337
337
  }
338
338
  async find(thread, target) {
339
- const path = thread.path.resolve(target);
339
+ const path2 = thread.path.resolve(target);
340
340
  return (await this.listTree(thread)).find(
341
- (candidate) => candidate.path.equals(path)
341
+ (candidate) => candidate.path.equals(path2)
342
342
  );
343
343
  }
344
344
  async createChild(options) {
345
- const path = options.parent.path.resolve(options.taskName);
346
- const pathString = path.toString();
345
+ const path2 = options.parent.path.resolve(options.taskName);
346
+ const pathString = path2.toString();
347
347
  const conversation = {
348
348
  chatId: _AgentDirectory.#childChatId(
349
349
  options.parent.conversation.userId,
@@ -353,7 +353,7 @@ var AgentDirectory = class _AgentDirectory {
353
353
  userId: options.parent.conversation.userId
354
354
  };
355
355
  const occupied = (await this.listTree(options.parent)).find(
356
- (thread) => thread.path.equals(path)
356
+ (thread) => thread.path.equals(path2)
357
357
  );
358
358
  if (occupied && occupied.conversation.chatId !== conversation.chatId) {
359
359
  throw new Error(`agent path "${pathString}" already exists`);
@@ -361,7 +361,7 @@ var AgentDirectory = class _AgentDirectory {
361
361
  const child = new AgentThread({
362
362
  conversation,
363
363
  treeId: options.parent.treeId,
364
- path,
364
+ path: path2,
365
365
  parentChatId: options.parent.conversation.chatId,
366
366
  declarationName: options.declarationName
367
367
  });
@@ -379,9 +379,9 @@ var AgentDirectory = class _AgentDirectory {
379
379
  }
380
380
  return stored;
381
381
  }
382
- static #childChatId(userId, treeId, path) {
382
+ static #childChatId(userId, treeId, path2) {
383
383
  return uuidv5(
384
- `urn:deepagents:zukhruf:agent:${JSON.stringify([userId, treeId, path])}`,
384
+ `urn:deepagents:zukhruf:agent:${JSON.stringify([userId, treeId, path2])}`,
385
385
  uuidv5.URL
386
386
  );
387
387
  }
@@ -1522,6 +1522,59 @@ function configureTool(collaborationTool, config) {
1522
1522
  };
1523
1523
  }
1524
1524
 
1525
+ // packages/experimental/src/zukhruf/runtime/agent-skills.ts
1526
+ import path from "node:path";
1527
+ import {
1528
+ parseFrontmatter,
1529
+ skills
1530
+ } from "@deepagents/context";
1531
+ var EMPTY_SKILLS = { available: [], fragments: [] };
1532
+ async function discoverAgentSkills(sandbox, signal) {
1533
+ if (sandbox.workingDirectory === void 0) return EMPTY_SKILLS;
1534
+ const skillsDirectory = path.posix.join(sandbox.workingDirectory, "skills");
1535
+ const quotedSkillsDirectory = shellQuote(skillsDirectory);
1536
+ const result = await sandbox.sandbox.executeCommand(
1537
+ `if [ -d ${quotedSkillsDirectory} ]; then find ${quotedSkillsDirectory} -mindepth 1 -maxdepth 1 -type d -print; fi`,
1538
+ { signal }
1539
+ );
1540
+ if (result.exitCode !== 0) {
1541
+ throw new Error(
1542
+ `AgentRuntime: failed to discover sandbox skills: ${result.stderr.trim() || `exit ${result.exitCode}`}`
1543
+ );
1544
+ }
1545
+ const skillDirectories = result.stdout.split("\n").filter(Boolean).filter((directory) => !path.posix.basename(directory).startsWith(".")).toSorted();
1546
+ if (skillDirectories.length === 0) return EMPTY_SKILLS;
1547
+ const discovered = await Promise.all(
1548
+ skillDirectories.map((directory) => loadSkill(sandbox, directory))
1549
+ );
1550
+ return createAgentSkills(discovered);
1551
+ }
1552
+ function createAgentSkills(available) {
1553
+ if (available.length === 0) return EMPTY_SKILLS;
1554
+ const snapshot = [...available];
1555
+ return { available: snapshot, fragments: [skills(snapshot)] };
1556
+ }
1557
+ async function loadSkill(sandbox, directory) {
1558
+ const directoryName = path.posix.basename(directory);
1559
+ const skillMd = await sandbox.sandbox.readFile(
1560
+ path.posix.join(directory, "SKILL.md")
1561
+ );
1562
+ const { frontmatter } = parseFrontmatter(skillMd);
1563
+ if (frontmatter.name !== directoryName) {
1564
+ throw new Error(
1565
+ `AgentRuntime: skill "${frontmatter.name}" must use matching directory "${directoryName}"`
1566
+ );
1567
+ }
1568
+ return {
1569
+ name: frontmatter.name,
1570
+ description: frontmatter.description,
1571
+ path: path.posix.join("skills", directoryName, "SKILL.md")
1572
+ };
1573
+ }
1574
+ function shellQuote(value) {
1575
+ return `'${value.replaceAll("'", "'\\''")}'`;
1576
+ }
1577
+
1525
1578
  // packages/experimental/src/zukhruf/runtime/agent-turn-executor.ts
1526
1579
  var AgentTurnExecutor = class {
1527
1580
  #store;
@@ -1576,10 +1629,7 @@ var AgentTurnExecutor = class {
1576
1629
  if (await this.#projectSkippedTerminalTurn(turn)) return;
1577
1630
  const { declaration, thread } = await this.#controlPlane.resolve(turn);
1578
1631
  const usageHint = thread.path.isRoot ? this.#multiAgentV2.rootAgentUsageHintText : this.#multiAgentV2.subagentUsageHintText;
1579
- const engine = this.#engineFor(turn).set(
1580
- ...declaration.instructions,
1581
- ...usageHint === void 0 ? [] : [role(usageHint)]
1582
- );
1632
+ const engine = this.#engineFor(turn);
1583
1633
  if (turn.kind === "ask" || turn.kind === "mailbox") {
1584
1634
  const head = (await engine.getMessages()).at(-1);
1585
1635
  if (this.#approvals.isPaused(head)) {
@@ -1603,6 +1653,12 @@ var AgentTurnExecutor = class {
1603
1653
  chatId: turn.chatId,
1604
1654
  userId: turn.userId
1605
1655
  });
1656
+ const agentSkills = await this.#skillsFor(turn, sandbox, signal);
1657
+ engine.set(
1658
+ ...declaration.instructions,
1659
+ ...agentSkills.fragments,
1660
+ ...usageHint === void 0 ? [] : [role(usageHint)]
1661
+ );
1606
1662
  if (await this.#projectSkippedTerminalTurn(turn)) return;
1607
1663
  if (!await this.#streams.claim(turn.streamId)) {
1608
1664
  await this.#projectSkippedTerminalTurn(turn);
@@ -1715,6 +1771,29 @@ var AgentTurnExecutor = class {
1715
1771
  (communication) => this.#mailboxInputMessage(communication)
1716
1772
  );
1717
1773
  }
1774
+ async #skillsFor(turn, sandbox, signal) {
1775
+ const chat2 = await this.#store.getChat(turn.chatId);
1776
+ const existing = readSkills(chat2?.metadata);
1777
+ if (existing !== void 0) return createAgentSkills(existing);
1778
+ if (sandbox.workingDirectory === void 0) return createAgentSkills([]);
1779
+ const discovered = await discoverAgentSkills(sandbox, signal);
1780
+ let available = discovered.available;
1781
+ await this.#store.updateChat(turn.chatId, ({ metadata }) => {
1782
+ const persisted = readSkills(metadata);
1783
+ if (persisted !== void 0) {
1784
+ available = persisted;
1785
+ return void 0;
1786
+ }
1787
+ const zukhruf = isRecord2(metadata?.zukhruf) ? metadata.zukhruf : {};
1788
+ return {
1789
+ metadata: {
1790
+ ...metadata,
1791
+ zukhruf: { ...zukhruf, skills: available }
1792
+ }
1793
+ };
1794
+ });
1795
+ return available === discovered.available ? discovered : createAgentSkills(available);
1796
+ }
1718
1797
  #engineFor({ chatId, userId }) {
1719
1798
  return new ContextEngine2({ store: this.#store, chatId, userId });
1720
1799
  }
@@ -1743,6 +1822,22 @@ Payload:
1743
1822
  ${communication.content}`;
1744
1823
  }
1745
1824
  };
1825
+ function readSkills(metadata) {
1826
+ const zukhruf = metadata?.zukhruf;
1827
+ if (!isRecord2(zukhruf) || !Object.hasOwn(zukhruf, "skills")) {
1828
+ return void 0;
1829
+ }
1830
+ if (!Array.isArray(zukhruf.skills) || !zukhruf.skills.every(isSkill)) {
1831
+ throw new Error("AgentRuntime: stored skill catalog is invalid");
1832
+ }
1833
+ return zukhruf.skills;
1834
+ }
1835
+ function isSkill(value) {
1836
+ return isRecord2(value) && typeof value.name === "string" && typeof value.description === "string" && typeof value.path === "string";
1837
+ }
1838
+ function isRecord2(value) {
1839
+ return typeof value === "object" && value !== null && !Array.isArray(value);
1840
+ }
1746
1841
 
1747
1842
  // packages/experimental/src/zukhruf/runtime/approval-controller.ts
1748
1843
  import {
@@ -1988,7 +2083,8 @@ var AgentObservation = class {
1988
2083
  #conversation;
1989
2084
  #store;
1990
2085
  #streams;
1991
- constructor(conversation, store, streams) {
2086
+ #queue;
2087
+ constructor(conversation, store, streams, queue) {
1992
2088
  this.engine = new ContextEngine4({
1993
2089
  store,
1994
2090
  chatId: conversation.chatId,
@@ -1997,6 +2093,7 @@ var AgentObservation = class {
1997
2093
  this.#conversation = conversation;
1998
2094
  this.#store = store;
1999
2095
  this.#streams = streams;
2096
+ this.#queue = queue;
2000
2097
  }
2001
2098
  async resume() {
2002
2099
  const id = await this.#headStreamId();
@@ -2016,8 +2113,9 @@ var AgentObservation = class {
2016
2113
  if (!id) return;
2017
2114
  AgentTurnId.assertOwner(this.#conversation, id);
2018
2115
  const status = await this.#streams.store.getStreamStatus(id);
2019
- if (status === "queued" || status === "running") {
2116
+ if (status === "queued" || status === "running" || status === "cancelled") {
2020
2117
  await this.#streams.cancel(id);
2118
+ await this.#queue.cancel(id);
2021
2119
  }
2022
2120
  }
2023
2121
  async #headStreamId() {
@@ -2098,7 +2196,12 @@ var AgentRuntime = class {
2098
2196
  return this.#approvals.deny(conversation, input);
2099
2197
  }
2100
2198
  observe(conversation) {
2101
- return new AgentObservation(conversation, this.#store, this.#streams);
2199
+ return new AgentObservation(
2200
+ conversation,
2201
+ this.#store,
2202
+ this.#streams,
2203
+ this.#queue
2204
+ );
2102
2205
  }
2103
2206
  work(options) {
2104
2207
  return this.#queue.consume(this.#executor.execute.bind(this.#executor), {
@@ -2217,9 +2320,9 @@ var BUSY_TIMEOUT_MS = 5e3;
2217
2320
  var SqliteMailboxStore = class extends MailboxStore {
2218
2321
  #database;
2219
2322
  #closed = false;
2220
- constructor(path) {
2323
+ constructor(path2) {
2221
2324
  super();
2222
- this.#database = new DatabaseSync(path, { timeout: BUSY_TIMEOUT_MS });
2325
+ this.#database = new DatabaseSync(path2, { timeout: BUSY_TIMEOUT_MS });
2223
2326
  this.#database.exec(DDL);
2224
2327
  }
2225
2328
  async beginTurn(recipient, turnId) {
@@ -2736,11 +2839,20 @@ async function renderTurn(stream) {
2736
2839
  }
2737
2840
 
2738
2841
  // packages/experimental/src/zukhruf/sandbox/define.ts
2739
- import {
2740
- createBashTool
2741
- } from "@deepagents/context";
2842
+ import { createBashTool } from "@deepagents/context";
2843
+ var DEFAULT_WORKING_DIRECTORY = "/workspace";
2742
2844
  function defineSandbox(createBackend, options) {
2743
- return async (context) => createBashTool({ sandbox: await createBackend(context), ...options });
2845
+ return async (context) => {
2846
+ const workingDirectory = options?.destination ?? DEFAULT_WORKING_DIRECTORY;
2847
+ return Object.assign(
2848
+ await createBashTool({
2849
+ sandbox: await createBackend(context),
2850
+ ...options,
2851
+ destination: workingDirectory
2852
+ }),
2853
+ { workingDirectory }
2854
+ );
2855
+ };
2744
2856
  }
2745
2857
 
2746
2858
  // packages/experimental/src/zukhruf/tool.ts