@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 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 path = value.trim();
366
- if (path !== "/root" && !path.startsWith("/root/")) {
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 = path.slice(1).split("/");
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(path);
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 path !== "string" || parentChatId !== null && typeof parentChatId !== "string" || typeof declarationName !== "string" || lastTurnId !== void 0 && typeof lastTurnId !== "string") {
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(path);
449
+ parsedPath = AgentPath.parse(path2);
450
450
  } catch {
451
451
  return void 0;
452
452
  }
453
- if (parsedPath.toString() !== path) return void 0;
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 path = thread.path.resolve(target);
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 "${path}" does not exist in this tree`);
677
+ throw new Error(`agent path "${path2}" does not exist in this tree`);
678
678
  }
679
679
  async find(thread, target) {
680
- const path = thread.path.resolve(target);
680
+ const path2 = thread.path.resolve(target);
681
681
  return (await this.listTree(thread)).find(
682
- (candidate) => candidate.path.equals(path)
682
+ (candidate) => candidate.path.equals(path2)
683
683
  );
684
684
  }
685
685
  async createChild(options) {
686
- const path = options.parent.path.resolve(options.taskName);
687
- const pathString = path.toString();
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(path)
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, path) {
723
+ static #childChatId(userId, treeId, path2) {
724
724
  return uuidv5(
725
- `urn:deepagents:zukhruf:agent:${JSON.stringify([userId, treeId, path])}`,
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).set(
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
- constructor(conversation, store, streams) {
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(conversation, this.#store, this.#streams);
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(path) {
2664
+ constructor(path2) {
2562
2665
  super();
2563
- this.#database = new DatabaseSync(path, { timeout: BUSY_TIMEOUT_MS });
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
- createBashTool
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) => createBashTool({ sandbox: await createBackend(context), ...options });
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