@deepagents/experimental 4.3.0 → 6.0.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.
Files changed (70) hide show
  1. package/README.md +24 -9
  2. package/dist/index.js +2613 -167
  3. package/dist/index.js.map +4 -4
  4. package/dist/zukhruf/agent.d.ts +15 -9
  5. package/dist/zukhruf/agent.d.ts.map +1 -1
  6. package/dist/zukhruf/collaboration/agent-tool-context.d.ts +6 -0
  7. package/dist/zukhruf/collaboration/agent-tool-context.d.ts.map +1 -0
  8. package/dist/zukhruf/collaboration/collaboration-tools.d.ts +4 -0
  9. package/dist/zukhruf/collaboration/collaboration-tools.d.ts.map +1 -0
  10. package/dist/zukhruf/collaboration/interrupt-agent.d.ts +234 -0
  11. package/dist/zukhruf/collaboration/interrupt-agent.d.ts.map +1 -0
  12. package/dist/zukhruf/collaboration/list-agents.d.ts +234 -0
  13. package/dist/zukhruf/collaboration/list-agents.d.ts.map +1 -0
  14. package/dist/zukhruf/collaboration/message-tools.d.ts +452 -0
  15. package/dist/zukhruf/collaboration/message-tools.d.ts.map +1 -0
  16. package/dist/zukhruf/collaboration/spawn-agent.d.ts +313 -0
  17. package/dist/zukhruf/collaboration/spawn-agent.d.ts.map +1 -0
  18. package/dist/zukhruf/collaboration/wait-agent.d.ts +253 -0
  19. package/dist/zukhruf/collaboration/wait-agent.d.ts.map +1 -0
  20. package/dist/zukhruf/control-plane/agent-control-plane.d.ts +80 -0
  21. package/dist/zukhruf/control-plane/agent-control-plane.d.ts.map +1 -0
  22. package/dist/zukhruf/control-plane/agent-declaration-registry.d.ts +9 -0
  23. package/dist/zukhruf/control-plane/agent-declaration-registry.d.ts.map +1 -0
  24. package/dist/zukhruf/control-plane/agent-directory.d.ts +22 -0
  25. package/dist/zukhruf/control-plane/agent-directory.d.ts.map +1 -0
  26. package/dist/zukhruf/control-plane/agent-history-forker.d.ts +10 -0
  27. package/dist/zukhruf/control-plane/agent-history-forker.d.ts.map +1 -0
  28. package/dist/zukhruf/control-plane/agent-path.d.ts +15 -0
  29. package/dist/zukhruf/control-plane/agent-path.d.ts.map +1 -0
  30. package/dist/zukhruf/control-plane/agent-status-projector.d.ts +50 -0
  31. package/dist/zukhruf/control-plane/agent-status-projector.d.ts.map +1 -0
  32. package/dist/zukhruf/control-plane/agent-thread.d.ts +31 -0
  33. package/dist/zukhruf/control-plane/agent-thread.d.ts.map +1 -0
  34. package/dist/zukhruf/control-plane/agent-turn-id.d.ts +12 -0
  35. package/dist/zukhruf/control-plane/agent-turn-id.d.ts.map +1 -0
  36. package/dist/zukhruf/control-plane/fork-turns.d.ts +4 -0
  37. package/dist/zukhruf/control-plane/fork-turns.d.ts.map +1 -0
  38. package/dist/zukhruf/index.d.ts +15 -11
  39. package/dist/zukhruf/index.d.ts.map +1 -1
  40. package/dist/zukhruf/index.js +2613 -167
  41. package/dist/zukhruf/index.js.map +4 -4
  42. package/dist/zukhruf/mailbox/coordinator.d.ts +26 -0
  43. package/dist/zukhruf/mailbox/coordinator.d.ts.map +1 -0
  44. package/dist/zukhruf/mailbox/sqlite.store.d.ts +16 -0
  45. package/dist/zukhruf/mailbox/sqlite.store.d.ts.map +1 -0
  46. package/dist/zukhruf/mailbox/store.d.ts +20 -0
  47. package/dist/zukhruf/mailbox/store.d.ts.map +1 -0
  48. package/dist/zukhruf/mailbox/types.d.ts +35 -0
  49. package/dist/zukhruf/mailbox/types.d.ts.map +1 -0
  50. package/dist/zukhruf/multi-agent-v2-config.d.ts +32 -0
  51. package/dist/zukhruf/multi-agent-v2-config.d.ts.map +1 -0
  52. package/dist/zukhruf/queue/pg-boss.turn-queue.d.ts +17 -4
  53. package/dist/zukhruf/queue/pg-boss.turn-queue.d.ts.map +1 -1
  54. package/dist/zukhruf/queue/turn-queue.d.ts +49 -6
  55. package/dist/zukhruf/queue/turn-queue.d.ts.map +1 -1
  56. package/dist/zukhruf/render-turn.d.ts +9 -0
  57. package/dist/zukhruf/render-turn.d.ts.map +1 -0
  58. package/dist/zukhruf/runtime/agent-runtime.d.ts +64 -0
  59. package/dist/zukhruf/runtime/agent-runtime.d.ts.map +1 -0
  60. package/dist/zukhruf/runtime/agent-turn-executor.d.ts +21 -0
  61. package/dist/zukhruf/runtime/agent-turn-executor.d.ts.map +1 -0
  62. package/dist/zukhruf/runtime/approval-controller.d.ts +45 -0
  63. package/dist/zukhruf/runtime/approval-controller.d.ts.map +1 -0
  64. package/dist/zukhruf/runtime/approval-job-id.d.ts +3 -0
  65. package/dist/zukhruf/runtime/approval-job-id.d.ts.map +1 -0
  66. package/dist/zukhruf/tool.d.ts +18 -6
  67. package/dist/zukhruf/tool.d.ts.map +1 -1
  68. package/package.json +11 -10
  69. package/dist/zukhruf/runtime.d.ts +0 -67
  70. package/dist/zukhruf/runtime.d.ts.map +0 -1
@@ -0,0 +1,16 @@
1
+ import { type MailboxEndTurnResult, type MailboxEnqueueResult, MailboxStore } from './store.ts';
2
+ import { type ConversationId, type InterAgentCommunication } from './types.ts';
3
+ /** SQLite-backed mailbox for durable cross-process delivery. */
4
+ export declare class SqliteMailboxStore extends MailboxStore implements Disposable {
5
+ #private;
6
+ constructor(path: string);
7
+ beginTurn(recipient: ConversationId, turnId: string): Promise<void>;
8
+ enqueue(communication: InterAgentCommunication): Promise<MailboxEnqueueResult>;
9
+ endTurn(recipient: ConversationId, turnId: string): Promise<MailboxEndTurnResult>;
10
+ hasPending(recipient: ConversationId): Promise<boolean>;
11
+ drain(recipient: ConversationId): Promise<InterAgentCommunication[]>;
12
+ drainLeadingQueueOnly(recipient: ConversationId): Promise<InterAgentCommunication[]>;
13
+ close(): void;
14
+ [Symbol.dispose](): void;
15
+ }
16
+ //# sourceMappingURL=sqlite.store.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sqlite.store.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/mailbox/sqlite.store.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAE7B,MAAM,YAAY,CAAC;AAuCpB,gEAAgE;AAChE,qBAAa,kBAAmB,SAAQ,YAAa,YAAW,UAAU;;gBAI5D,IAAI,EAAE,MAAM;IAMT,SAAS,CACtB,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAgBD,OAAO,CACpB,aAAa,EAAE,uBAAuB,GACrC,OAAO,CAAC,oBAAoB,CAAC;IA0BjB,OAAO,CACpB,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,oBAAoB,CAAC;IAiBjB,UAAU,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IA0CvD,KAAK,CAClB,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAItB,qBAAqB,CAClC,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAyErC,KAAK,IAAI,IAAI;IAMb,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAGzB"}
@@ -0,0 +1,20 @@
1
+ import type { ConversationId, InterAgentCommunication } from './types.ts';
2
+ export interface MailboxEnqueueResult {
3
+ recipientActive: boolean;
4
+ }
5
+ export interface MailboxEndTurnResult {
6
+ hasPending: boolean;
7
+ turnEnded: boolean;
8
+ }
9
+ /** Durable pending-mail storage. This is deliberately not an execution queue. */
10
+ export declare abstract class MailboxStore {
11
+ abstract beginTurn(recipient: ConversationId, turnId: string): Promise<void>;
12
+ abstract enqueue(communication: InterAgentCommunication): Promise<MailboxEnqueueResult>;
13
+ abstract endTurn(recipient: ConversationId, turnId: string): Promise<MailboxEndTurnResult>;
14
+ abstract hasPending(recipient: ConversationId): Promise<boolean>;
15
+ /** Consumes the contiguous queue-only prefix, stopping before the first trigger. */
16
+ abstract drainLeadingQueueOnly(recipient: ConversationId): Promise<InterAgentCommunication[]>;
17
+ /** Draining is consumption: removes and returns all pending mail in FIFO order. */
18
+ abstract drain(recipient: ConversationId): Promise<InterAgentCommunication[]>;
19
+ }
20
+ //# sourceMappingURL=store.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/mailbox/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1E,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,iFAAiF;AACjF,8BAAsB,YAAY;IAChC,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE5E,QAAQ,CAAC,OAAO,CACd,aAAa,EAAE,uBAAuB,GACrC,OAAO,CAAC,oBAAoB,CAAC;IAEhC,QAAQ,CAAC,OAAO,CACd,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,oBAAoB,CAAC;IAEhC,QAAQ,CAAC,UAAU,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAEhE,oFAAoF;IACpF,QAAQ,CAAC,qBAAqB,CAC5B,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAErC,mFAAmF;IACnF,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC;CAC9E"}
@@ -0,0 +1,35 @@
1
+ /** Durable thread identity; AgentPath is its model-facing address. */
2
+ export interface ConversationId {
3
+ chatId: string;
4
+ userId: string;
5
+ }
6
+ export declare const MessageDeliveryMode: {
7
+ readonly QueueOnly: "queue-only";
8
+ readonly TriggerTurn: "trigger-turn";
9
+ };
10
+ export type MessageDeliveryMode = (typeof MessageDeliveryMode)[keyof typeof MessageDeliveryMode];
11
+ export declare const InterAgentCommunicationType: {
12
+ readonly Message: "MESSAGE";
13
+ readonly NewTask: "NEW_TASK";
14
+ readonly FinalAnswer: "FINAL_ANSWER";
15
+ };
16
+ export type InterAgentCommunicationType = (typeof InterAgentCommunicationType)[keyof typeof InterAgentCommunicationType];
17
+ /** A model-visible message sent from one independent agent thread to another. */
18
+ export interface InterAgentCommunication {
19
+ id: string;
20
+ type: InterAgentCommunicationType;
21
+ author: ConversationId;
22
+ recipient: ConversationId;
23
+ otherRecipients: ConversationId[];
24
+ content: string;
25
+ metadata?: Record<string, unknown>;
26
+ triggerTurn: boolean;
27
+ }
28
+ export type NewInterAgentCommunication = Omit<InterAgentCommunication, 'id' | 'otherRecipients' | 'triggerTurn' | 'type'> & {
29
+ id?: string;
30
+ otherRecipients?: ConversationId[];
31
+ type?: InterAgentCommunicationType;
32
+ };
33
+ export declare function createInterAgentCommunication(communication: NewInterAgentCommunication): InterAgentCommunication;
34
+ export declare function assertCommunication(communication: InterAgentCommunication): void;
35
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/mailbox/types.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAC7B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE,eAAO,MAAM,2BAA2B;;;;CAI9B,CAAC;AAEX,MAAM,MAAM,2BAA2B,GACrC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,OAAO,2BAA2B,CAAC,CAAC;AAEjF,iFAAiF;AACjF,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,2BAA2B,CAAC;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,cAAc,CAAC;IAC1B,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAC3C,uBAAuB,EACvB,IAAI,GAAG,iBAAiB,GAAG,aAAa,GAAG,MAAM,CAClD,GAAG;IACF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,IAAI,CAAC,EAAE,2BAA2B,CAAC;CACpC,CAAC;AAEF,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,0BAA0B,GACxC,uBAAuB,CAUzB;AAED,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,uBAAuB,GACrC,IAAI,CAiBN"}
@@ -0,0 +1,32 @@
1
+ /** Host-level controls matching Codex MultiAgentV2 configuration. */
2
+ export interface MultiAgentV2HostConfig {
3
+ minWaitTimeoutMs?: number;
4
+ defaultWaitTimeoutMs?: number;
5
+ maxWaitTimeoutMs?: number;
6
+ /** Additional guidance appended to the spawn_agent tool description. */
7
+ usageHintText?: string;
8
+ /** Complete root guidance override. An empty string disables the hint. */
9
+ rootAgentUsageHintText?: string;
10
+ /** Complete child guidance override. An empty string disables the hint. */
11
+ subagentUsageHintText?: string;
12
+ /** Native OpenAI Responses namespace for the six collaboration tools. */
13
+ toolNamespace?: string;
14
+ /**
15
+ * Keeps collaboration tools on the direct model surface instead of a nested
16
+ * code-mode executor. Defaults to true. Zukhruf currently rejects false
17
+ * because it has no nested code-mode executor in which to expose the tools.
18
+ */
19
+ nonCodeModeOnly?: boolean;
20
+ }
21
+ export interface ResolvedMultiAgentV2HostConfig {
22
+ minWaitTimeoutMs: number;
23
+ defaultWaitTimeoutMs: number;
24
+ maxWaitTimeoutMs: number;
25
+ usageHintText?: string;
26
+ rootAgentUsageHintText?: string;
27
+ subagentUsageHintText?: string;
28
+ toolNamespace?: string;
29
+ nonCodeModeOnly: boolean;
30
+ }
31
+ export declare function resolveMultiAgentV2HostConfig(input?: MultiAgentV2HostConfig): ResolvedMultiAgentV2HostConfig;
32
+ //# sourceMappingURL=multi-agent-v2-config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"multi-agent-v2-config.d.ts","sourceRoot":"","sources":["../../src/zukhruf/multi-agent-v2-config.ts"],"names":[],"mappings":"AAqBA,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,2EAA2E;IAC3E,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,8BAA8B;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,GAAE,sBAA2B,GACjC,8BAA8B,CA2EhC"}
@@ -1,7 +1,9 @@
1
1
  import type { PgBoss } from 'pg-boss';
2
- import { type ConsumeContext, type ConsumeOptions, TurnQueue, type TurnRef } from './turn-queue.ts';
2
+ import { type ConsumeContext, type ConsumeOptions, type TurnActivity, type TurnPushResult, TurnQueue, type TurnRef } from './turn-queue.ts';
3
3
  export interface PgBossTurnQueueOptions {
4
4
  queue?: string;
5
+ /** Required for custom DB adapters; must match the PgBoss schema. */
6
+ schema?: string;
5
7
  /** Hard cap on one turn attempt; the job fails past this. */
6
8
  expireInSeconds?: number;
7
9
  /** Dead-worker detection window; must be >= 10 (pg-boss constraint). */
@@ -12,8 +14,11 @@ export interface PgBossTurnQueueOptions {
12
14
  * TurnQueue on pg-boss.
13
15
  *
14
16
  * - `key_strict_fifo` policy with `singletonKey = chatId` gives the per-chat
15
- * serialization contract structurally: one active turn per chat, strict
16
- * push order, cross-chat concurrency.
17
+ * serialization contract structurally: one active turn per chat and strict
18
+ * push order.
19
+ * - `group.id = chatId` with global `groupConcurrency: 1` excludes an active
20
+ * chat before pg-boss selects the next job, so its queued successor cannot
21
+ * block ready turns from other chats.
17
22
  * - `retryLimit: 0` — a crashed turn is never silently re-run (its bash
18
23
  * already executed). It dead-letters instead.
19
24
  * - A failed job blocks its chat's key until acknowledged; the dead-letter
@@ -27,6 +32,11 @@ export interface PgBossTurnQueueOptions {
27
32
  * (`retentionSeconds`, which governs still-`created` jobs, can't be 0; its
28
33
  * default 14d is never approached because a queued turn only waits behind one
29
34
  * running turn.)
35
+ * - Interrupting an active turn aborts the adapter-local handler but leaves its
36
+ * pg-boss row `active` until that handler exits. Cancelling the row itself
37
+ * would surrender the strict-FIFO key early and let the successor overlap.
38
+ * Cross-process handler abort comes from the runtime's durable stream
39
+ * cancellation; this queue remains the scheduler-ordering authority.
30
40
  *
31
41
  * The `PgBoss` instance is borrowed: the caller `start()`s and `stop()`s it.
32
42
  */
@@ -36,7 +46,10 @@ export declare class PgBossTurnQueue extends TurnQueue {
36
46
  get queue(): string;
37
47
  get deadLetterQueue(): string;
38
48
  initialize(): Promise<void>;
39
- push(turn: TurnRef): Promise<void>;
49
+ push(turn: TurnRef): Promise<TurnPushResult>;
50
+ getTurnActivity(conversation: Pick<TurnRef, 'chatId' | 'userId'>): Promise<TurnActivity>;
51
+ getCurrentTurn(conversation: Pick<TurnRef, 'chatId' | 'userId'>): Promise<TurnRef | undefined>;
52
+ cancel(streamId: string): Promise<void>;
40
53
  consume(handler: (turn: TurnRef, context: ConsumeContext) => Promise<void>, options: ConsumeOptions): Promise<AsyncDisposable>;
41
54
  resumeParked(chatId: string): Promise<void>;
42
55
  }
@@ -1 +1 @@
1
- {"version":3,"file":"pg-boss.turn-queue.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/queue/pg-boss.turn-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,MAAM,EAAE,MAAM,SAAS,CAAC;AAGvD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,SAAS,EACT,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,eAAgB,SAAQ,SAAS;;gBAOhC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B;IAS9D,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,eAAe,IAAI,MAAM,CAE5B;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB3B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBlC,OAAO,CACX,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,EAClE,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,CAAC;IAyDrB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAYlD"}
1
+ {"version":3,"file":"pg-boss.turn-queue.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/queue/pg-boss.turn-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,MAAM,EAAE,MAAM,SAAS,CAAC;AAIvD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,SAAS,EACT,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,eAAgB,SAAQ,SAAS;;gBAchC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B;IAmC9D,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,eAAe,IAAI,MAAM,CAE5B;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA6C3B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IA2BnC,eAAe,CAC5B,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAC,GAC/C,OAAO,CAAC,YAAY,CAAC;IAiBT,cAAc,CAC3B,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAC,GAC/C,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAehB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BhD,OAAO,CACX,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,EAClE,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,CAAC;IAgFrB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA6GlD"}
@@ -14,12 +14,35 @@ export type TurnRef = {
14
14
  input: string;
15
15
  } | {
16
16
  /**
17
- * Re-execution of an existing (reopened) stream after a tool approval
18
- * or denial. Carries no payload: the chain was already updated in
19
- * place by `approve()`/`deny()`.
17
+ * Recovery-only re-execution of an existing stream. Normal approval
18
+ * responses resume directly inside their approval job.
20
19
  */
21
20
  kind: 'continuation';
21
+ recovery?: 'handoff' | 'idempotent';
22
+ } | {
23
+ kind: 'approval';
24
+ toolCallId: string;
25
+ approvalId: string;
26
+ decision: {
27
+ approved: true;
28
+ } | {
29
+ approved: false;
30
+ reason?: string;
31
+ };
32
+ } | {
33
+ /**
34
+ * A mailbox wake-up. The communication payload remains in MailboxStore;
35
+ * TurnQueue carries only the execution request and addressing.
36
+ */
37
+ kind: 'mailbox';
22
38
  });
39
+ export interface TurnPushResult {
40
+ jobId: string;
41
+ inserted: boolean;
42
+ }
43
+ export type ApprovalTurnRef = Extract<TurnRef, {
44
+ kind: 'approval';
45
+ }>;
23
46
  export interface ConsumeContext {
24
47
  signal: AbortSignal;
25
48
  /**
@@ -39,31 +62,51 @@ export interface ConsumeOptions {
39
62
  */
40
63
  onOrphaned: (turn: TurnRef, error: string) => Promise<void>;
41
64
  }
65
+ export type TurnActivity = 'idle' | 'queued' | 'running';
42
66
  /**
43
67
  * Durable holding pen for pending turns.
44
68
  *
45
69
  * Contract every implementation must honor:
46
70
  * - `push` is durable: a pushed turn survives process death until consumed.
47
- * - Delivery is AT-LEAST-ONCE: a pushed turn is delivered until settled, and
71
+ * - Delivery is AT-LEAST-ONCE: a pushed non-approval turn is delivered until settled, and
48
72
  * duplicate pushes of the same `streamId` may each be delivered. Consumers
49
73
  * MUST be idempotent on `streamId` (the zukhruf runtime skips turns whose
50
74
  * stream row is terminal — a check that, unlike queue-side dedup, never
51
75
  * expires with job retention).
76
+ * - Approval pushes use their persisted approval id as a deterministic job
77
+ * identity. The first decision inserts; later decisions for that approval
78
+ * report the existing job instead of adding a row.
52
79
  * - Per chat, at most ONE handler invocation is active at a time, and turns
53
80
  * run in the order they were pushed (strict FIFO per `chatId`) — this
54
81
  * covers duplicates too: they can never run concurrently or out of order.
55
82
  * - Turns from different chats may run concurrently.
83
+ * - `getTurnActivity` distinguishes queued from active scheduler work for
84
+ * status inspection; adapters must not silently fall back to stale history.
85
+ * - `getCurrentTurn` returns the active turn, or otherwise the oldest eligible
86
+ * queued turn, for exact interruption. `cancel` removes queued copies of that
87
+ * exact stream and signals an adapter-local active handler, but an active turn
88
+ * retains FIFO ownership until its handler exits. Cross-process handler abort
89
+ * is the runtime stream-control layer's responsibility.
56
90
  * - A handler that throws (or a worker that dies mid-turn) does not retry:
57
91
  * the turn surfaces once through `onOrphaned`, then the chat unblocks.
92
+ * - Mailbox payloads NEVER live here. A `{kind: 'mailbox'}` item is only a
93
+ * durable wake request; the target MailboxStore remains the pending-input
94
+ * authority.
58
95
  * - A parked turn (`context.park()`) is not delivered again until
59
96
  * `resumeParked(chatId)`; revived turns keep their original FIFO order,
60
- * and a `'continuation'` turn pushed for the chat outranks them.
97
+ * and approval/recovery turns pushed for the chat outrank them.
61
98
  *
62
99
  * On platforms with native per-conversation serialization (e.g. Durable
63
100
  * Objects) this port is absorbed by the host rather than implemented.
64
101
  */
65
102
  export declare abstract class TurnQueue {
66
- abstract push(turn: TurnRef): Promise<void>;
103
+ abstract push(turn: TurnRef): Promise<TurnPushResult>;
104
+ /** Whether this conversation currently has queued or active scheduler work. */
105
+ abstract getTurnActivity(conversation: Pick<TurnRef, 'chatId' | 'userId'>): Promise<TurnActivity>;
106
+ /** Active turn, or the oldest eligible queued turn, for a conversation. */
107
+ abstract getCurrentTurn(conversation: Pick<TurnRef, 'chatId' | 'userId'>): Promise<TurnRef | undefined>;
108
+ /** Cancel queued copies and request local active cancellation by stream id. */
109
+ abstract cancel(streamId: string): Promise<void>;
67
110
  abstract consume(handler: (turn: TurnRef, context: ConsumeContext) => Promise<void>, options: ConsumeOptions): Promise<AsyncDisposable>;
68
111
  abstract resumeParked(chatId: string): Promise<void>;
69
112
  }
@@ -1 +1 @@
1
- {"version":3,"file":"turn-queue.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/queue/turn-queue.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,CACA;IACE,IAAI,EAAE,KAAK,CAAC;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE;;;;OAIG;IACH,IAAI,EAAE,cAAc,CAAC;CACtB,CACJ,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,SAAS;IAC7B,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAE3C,QAAQ,CAAC,OAAO,CACd,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,EAClE,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,CAAC;IAE3B,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CACrD"}
1
+ {"version":3,"file":"turn-queue.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/queue/turn-queue.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,CACA;IACE,IAAI,EAAE,KAAK,CAAC;IACZ;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE;;;OAGG;IACH,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;CACrC,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,QAAQ,EAAE,KAAK,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrE,GACD;IACE;;;OAGG;IACH,IAAI,EAAE,SAAS,CAAC;CACjB,CACJ,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC;AAErE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8BAAsB,SAAS;IAC7B,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAErD,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,CACtB,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAC,GAC/C,OAAO,CAAC,YAAY,CAAC;IAExB,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CACrB,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,GAAG,QAAQ,CAAC,GAC/C,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC;IAE/B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhD,QAAQ,CAAC,OAAO,CACd,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,EAClE,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,CAAC;IAE3B,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CACrD"}
@@ -0,0 +1,9 @@
1
+ import type { UIMessageChunk } from 'ai';
2
+ /**
3
+ * Render one turn stream as a conversation: assistant text streams raw, each
4
+ * tool call becomes a single dim line, and failures become a single red line.
5
+ * Reasoning shows up only as one dim ellipsis so silence never looks like a
6
+ * hang. Everything else in the chunk vocabulary is deliberately dropped.
7
+ */
8
+ export declare function renderTurn(stream: ReadableStream<UIMessageChunk>): Promise<void>;
9
+ //# sourceMappingURL=render-turn.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"render-turn.d.ts","sourceRoot":"","sources":["../../src/zukhruf/render-turn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AA6BzC;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,CAAC,cAAc,CAAC,GACrC,OAAO,CAAC,IAAI,CAAC,CAgDf"}
@@ -0,0 +1,64 @@
1
+ import { ContextEngine, type ContextStore, type StreamManager } from '@deepagents/context';
2
+ import type { AgentDeclaration } from '../agent.ts';
3
+ import { type TurnInput } from '../control-plane/agent-control-plane.ts';
4
+ import type { MailboxStore } from '../mailbox/store.ts';
5
+ import type { ConversationId, InterAgentCommunication, MessageDeliveryMode } from '../mailbox/types.ts';
6
+ import { type MultiAgentV2HostConfig } from '../multi-agent-v2-config.ts';
7
+ import type { TurnQueue } from '../queue/turn-queue.ts';
8
+ export interface AgentRuntimeOptions {
9
+ store: ContextStore;
10
+ /** Borrowed stream subsystem; the caller owns its store, change source, and lifecycle. */
11
+ streams: StreamManager;
12
+ queue: TurnQueue;
13
+ /** Durable pending inter-agent input. Distinct from the TurnQueue scheduler. */
14
+ mailboxStore: MailboxStore;
15
+ /** Codex MultiAgentV2-compatible host guidance and tool configuration. */
16
+ multiAgentV2?: MultiAgentV2HostConfig;
17
+ }
18
+ export interface AgentRuntimeWorkOptions {
19
+ concurrency?: number;
20
+ }
21
+ /** Reconnect and cancellation view over one durable conversation. */
22
+ export declare class AgentObservation {
23
+ #private;
24
+ readonly engine: ContextEngine;
25
+ constructor(conversation: ConversationId, store: ContextStore, streams: StreamManager);
26
+ resume(): Promise<ReadableStream<import("@deepagents/context").StreamPart> | null>;
27
+ cancel(streamId?: string): Promise<void>;
28
+ }
29
+ /** Thin host-facing composition and lifecycle façade for a Zukhruf agent tree. */
30
+ export declare class AgentRuntime {
31
+ #private;
32
+ constructor(root: AgentDeclaration, options: AgentRuntimeOptions);
33
+ enqueue(conversation: ConversationId, turn: TurnInput): Promise<{
34
+ id: string;
35
+ stream: ReadableStream<import("@deepagents/context").StreamPart>;
36
+ }>;
37
+ deliver(communication: InterAgentCommunication, mode: MessageDeliveryMode): Promise<void>;
38
+ approve(conversation: ConversationId, input: {
39
+ toolCallId: string;
40
+ }): Promise<{
41
+ id: string;
42
+ jobId: string;
43
+ status: "already-applied";
44
+ } | {
45
+ id: string;
46
+ jobId: string;
47
+ status: "queued" | "already-queued";
48
+ }>;
49
+ deny(conversation: ConversationId, input: {
50
+ toolCallId: string;
51
+ reason?: string;
52
+ }): Promise<{
53
+ id: string;
54
+ jobId: string;
55
+ status: "already-applied";
56
+ } | {
57
+ id: string;
58
+ jobId: string;
59
+ status: "queued" | "already-queued";
60
+ }>;
61
+ observe(conversation: ConversationId): AgentObservation;
62
+ work(options?: AgentRuntimeWorkOptions): Promise<AsyncDisposable>;
63
+ }
64
+ //# sourceMappingURL=agent-runtime.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-runtime.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/runtime/agent-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAEL,KAAK,SAAS,EACf,MAAM,yCAAyC,CAAC;AAOjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EACV,cAAc,EACd,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,wBAAwB,CAAC;AAIjE,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,0FAA0F;IAC1F,OAAO,EAAE,aAAa,CAAC;IACvB,KAAK,EAAE,SAAS,CAAC;IACjB,gFAAgF;IAChF,YAAY,EAAE,YAAY,CAAC;IAC3B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,sBAAsB,CAAC;CACvC;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qEAAqE;AACrE,qBAAa,gBAAgB;;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;gBAM7B,YAAY,EAAE,cAAc,EAC5B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,aAAa;IAYlB,MAAM;IAQN,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAoB/C;AAED,kFAAkF;AAClF,qBAAa,YAAY;;gBAUX,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,mBAAmB;IAmD1D,OAAO,CAAC,YAAY,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS;;;;IAKrD,OAAO,CACX,aAAa,EAAE,uBAAuB,EACtC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,IAAI,CAAC;IAKhB,OAAO,CAAC,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE;;;;;;;;;IAInE,IAAI,CACF,YAAY,EAAE,cAAc,EAC5B,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;IAKhD,OAAO,CAAC,YAAY,EAAE,cAAc,GAAG,gBAAgB;IAIvD,IAAI,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,eAAe,CAAC;CAsFlE"}
@@ -0,0 +1,21 @@
1
+ import { type ContextStore, type StreamManager } from '@deepagents/context';
2
+ import type { AgentControlPlane } from '../control-plane/agent-control-plane.ts';
3
+ import type { MailboxCoordinator } from '../mailbox/coordinator.ts';
4
+ import type { ResolvedMultiAgentV2HostConfig } from '../multi-agent-v2-config.ts';
5
+ import type { ConsumeContext, TurnRef } from '../queue/turn-queue.ts';
6
+ import type { ApprovalController } from './approval-controller.ts';
7
+ export interface AgentTurnExecutorOptions {
8
+ store: ContextStore;
9
+ streams: StreamManager;
10
+ controlPlane: AgentControlPlane;
11
+ mailbox: MailboxCoordinator;
12
+ approvals: ApprovalController;
13
+ multiAgentV2: ResolvedMultiAgentV2HostConfig;
14
+ }
15
+ /** Executes one queued turn without owning host lifecycle or agent routing. */
16
+ export declare class AgentTurnExecutor {
17
+ #private;
18
+ constructor(options: AgentTurnExecutorOptions);
19
+ execute(turn: TurnRef, context: ConsumeContext): Promise<void>;
20
+ }
21
+ //# sourceMappingURL=agent-turn-executor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-turn-executor.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/runtime/agent-turn-executor.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,aAAa,EAMnB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAKpE,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;IACvB,YAAY,EAAE,iBAAiB,CAAC;IAChC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,SAAS,EAAE,kBAAkB,CAAC;IAC9B,YAAY,EAAE,8BAA8B,CAAC;CAC9C;AAMD,+EAA+E;AAC/E,qBAAa,iBAAiB;;gBAShB,OAAO,EAAE,wBAAwB;IAUvC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CA0PrE"}
@@ -0,0 +1,45 @@
1
+ import { type UIMessage } from 'ai';
2
+ import { type ContextStore } from '@deepagents/context';
3
+ import type { ConversationId } from '../mailbox/types.ts';
4
+ import type { ApprovalTurnRef, TurnQueue, TurnRef } from '../queue/turn-queue.ts';
5
+ import type { ZukhrufToolSet } from '../tool.ts';
6
+ export interface ApprovalControllerOptions {
7
+ store: ContextStore;
8
+ queue: TurnQueue;
9
+ }
10
+ /** Durable approval-response and continuation state machine. */
11
+ export declare class ApprovalController {
12
+ #private;
13
+ constructor(options: ApprovalControllerOptions);
14
+ isPaused(message: UIMessage | undefined): boolean;
15
+ approve(conversation: ConversationId, input: {
16
+ toolCallId: string;
17
+ }): Promise<{
18
+ id: string;
19
+ jobId: string;
20
+ status: "already-applied";
21
+ } | {
22
+ id: string;
23
+ jobId: string;
24
+ status: "queued" | "already-queued";
25
+ }>;
26
+ deny(conversation: ConversationId, input: {
27
+ toolCallId: string;
28
+ reason?: string;
29
+ }): Promise<{
30
+ id: string;
31
+ jobId: string;
32
+ status: "already-applied";
33
+ } | {
34
+ id: string;
35
+ jobId: string;
36
+ status: "queued" | "already-queued";
37
+ }>;
38
+ settleDeniedApprovals(conversation: ConversationId, streamId: string): Promise<void>;
39
+ settleFailedApprovals(conversation: ConversationId, streamId: string, error: string): Promise<void>;
40
+ reconcileTerminalContinuation(conversation: ConversationId, streamId: string, status: 'completed' | 'failed' | 'cancelled', error?: string | null): Promise<void>;
41
+ retryIdempotentContinuation(conversation: ConversationId, streamId: string, tools: ZukhrufToolSet): Promise<boolean>;
42
+ applyDecision(turn: ApprovalTurnRef): Promise<boolean>;
43
+ recoverUnstartedContinuation(turn: TurnRef, streamId: string): Promise<boolean>;
44
+ }
45
+ //# sourceMappingURL=approval-controller.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"approval-controller.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/runtime/approval-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EAGf,MAAM,IAAI,CAAC;AAEZ,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EACV,eAAe,EACf,SAAS,EACT,OAAO,EACR,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,SAAS,CAAC;CAClB;AAID,gEAAgE;AAChE,qBAAa,kBAAkB;;gBAUjB,OAAO,EAAE,yBAAyB;IAK9C,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO;IAOjD,OAAO,CAAC,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE;;;;;;;;;IAMnE,IAAI,CACF,YAAY,EAAE,cAAc,EAC5B,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;IAQ1C,qBAAqB,CACzB,YAAY,EAAE,cAAc,EAC5B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAiCV,qBAAqB,CACzB,YAAY,EAAE,cAAc,EAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC;IAmCV,6BAA6B,CACjC,YAAY,EAAE,cAAc,EAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,EAC5C,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GACpB,OAAO,CAAC,IAAI,CAAC;IAaV,2BAA2B,CAC/B,YAAY,EAAE,cAAc,EAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,OAAO,CAAC;IA6Bb,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBtD,4BAA4B,CAChC,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC;CA2GpB"}
@@ -0,0 +1,3 @@
1
+ import type { ConversationId } from '../mailbox/types.ts';
2
+ export declare function approvalJobId(conversation: ConversationId, approvalId: string): string;
3
+ //# sourceMappingURL=approval-job-id.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"approval-job-id.d.ts","sourceRoot":"","sources":["../../../src/zukhruf/runtime/approval-job-id.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,wBAAgB,aAAa,CAC3B,YAAY,EAAE,cAAc,EAC5B,UAAU,EAAE,MAAM,GACjB,MAAM,CAER"}
@@ -1,7 +1,19 @@
1
- /**
2
- * Declaration-layer tool definition: a pure passthrough of the AI SDK's
3
- * `tool()` (full generics, zero side effects). Set `needsApproval: true` to
4
- * pause the turn on this tool's call until `runtime.approve()`/`deny()`.
5
- */
6
- export { tool as defineTool } from 'ai';
1
+ import { type Tool, type ToolExecuteFunction, type ToolSet } from 'ai';
2
+ export type ToolRecovery = 'idempotent';
3
+ export type ZukhrufTool<INPUT, OUTPUT, CONTEXT extends Record<string, unknown>> = Tool<INPUT, OUTPUT, CONTEXT> & {
4
+ /** Allows one automatic replay after a worker crash. */
5
+ recovery?: ToolRecovery;
6
+ };
7
+ export type ZukhrufToolSet = ToolSet & Record<string, {
8
+ recovery?: ToolRecovery;
9
+ }>;
10
+ export declare function defineTool<INPUT, OUTPUT, CONTEXT extends Record<string, unknown>>(definition: ZukhrufTool<INPUT, OUTPUT, CONTEXT> & {
11
+ execute: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
12
+ }): ZukhrufTool<INPUT, OUTPUT, CONTEXT> & {
13
+ execute: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
14
+ };
15
+ export declare function defineTool<INPUT, OUTPUT, CONTEXT extends Record<string, unknown>>(definition: ZukhrufTool<INPUT, OUTPUT, CONTEXT>): ZukhrufTool<INPUT, OUTPUT, CONTEXT>;
16
+ export declare function defineTool<INPUT, CONTEXT extends Record<string, unknown>>(definition: ZukhrufTool<INPUT, never, CONTEXT>): ZukhrufTool<INPUT, never, CONTEXT>;
17
+ export declare function defineTool<OUTPUT, CONTEXT extends Record<string, unknown>>(definition: ZukhrufTool<never, OUTPUT, CONTEXT>): ZukhrufTool<never, OUTPUT, CONTEXT>;
18
+ export declare function defineTool<CONTEXT extends Record<string, unknown>>(definition: ZukhrufTool<never, never, CONTEXT>): ZukhrufTool<never, never, CONTEXT>;
7
19
  //# sourceMappingURL=tool.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/zukhruf/tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,IAAI,CAAC"}
1
+ {"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/zukhruf/tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,mBAAmB,EAAE,KAAK,OAAO,EAAQ,MAAM,IAAI,CAAC;AAE7E,MAAM,MAAM,YAAY,GAAG,YAAY,CAAC;AAExC,MAAM,MAAM,WAAW,CACrB,KAAK,EACL,MAAM,EACN,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACrC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG;IACjC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,OAAO,GAClC,MAAM,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;AAE9C,wBAAgB,UAAU,CACxB,KAAK,EACL,MAAM,EACN,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEvC,UAAU,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG;IAChD,OAAO,EAAE,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;CACtD,GACA,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG;IACvC,OAAO,EAAE,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;CACtD,CAAC;AACF,wBAAgB,UAAU,CACxB,KAAK,EACL,MAAM,EACN,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEvC,UAAU,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,GAC9C,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACvC,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvE,UAAU,EAAE,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,GAC7C,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AACtC,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,UAAU,EAAE,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,GAC9C,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACvC,wBAAgB,UAAU,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChE,UAAU,EAAE,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,GAC7C,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deepagents/experimental",
3
- "version": "4.3.0",
3
+ "version": "6.0.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -35,6 +35,7 @@
35
35
  },
36
36
  "files": [
37
37
  "dist",
38
+ "!dist/spec/**",
38
39
  "!**/*.tsbuildinfo",
39
40
  "!**/*.test.*"
40
41
  ],
@@ -42,17 +43,17 @@
42
43
  "access": "public"
43
44
  },
44
45
  "dependencies": {
45
- "@deepagents/context": "4.3.0",
46
- "ai": "^6.0.218",
47
- "just-bash": "^3.0.1",
48
- "pg-boss": "^12.24.1",
46
+ "@deepagents/context": "6.0.0",
47
+ "ai": "^7.0.30",
48
+ "just-bash": "^3.1.0",
49
+ "pg-boss": "^12.26.1",
49
50
  "tiny-tfidf": "^1.0.0",
50
- "uuid": "^13.0.2"
51
+ "uuid": "^14.0.1",
52
+ "zod": "^4.4.3"
51
53
  },
52
54
  "devDependencies": {
53
- "@ai-sdk/provider": "^3.0.13",
54
- "@electric-sql/pglite": "^0.5.3",
55
- "just-bash": "^3.0.1",
56
- "zod": "^3.25.76 || ^4.0.0"
55
+ "@ai-sdk/provider": "^4.0.3",
56
+ "@electric-sql/pglite": "^0.5.4",
57
+ "just-bash": "^3.1.0"
57
58
  }
58
59
  }
@@ -1,67 +0,0 @@
1
- import { ContextEngine, type ContextStore, type StreamStore } from '@deepagents/context';
2
- import type { AgentDeclaration } from './agent.ts';
3
- import type { TurnQueue } from './queue/turn-queue.ts';
4
- export interface RuntimeOptions {
5
- store: ContextStore;
6
- streamStore: StreamStore;
7
- queue: TurnQueue;
8
- }
9
- export interface ConversationId {
10
- chatId: string;
11
- userId: string;
12
- }
13
- export interface WorkOptions {
14
- concurrency?: number;
15
- }
16
- export interface TurnInput {
17
- /**
18
- * The ask's identity, supplied by the caller: any unique string (a client's
19
- * message id, or `crypto.randomUUID()` when the caller has no natural key).
20
- * It doubles as the stream id and the assistant message id. Enqueueing the
21
- * same id again reattaches to the existing turn instead of running it
22
- * twice; the first call's `input` wins.
23
- */
24
- id: string;
25
- input: string;
26
- }
27
- /**
28
- * Executes an AgentDeclaration as a background agent, split into three roles:
29
- *
30
- * - `enqueue` — durably queue a turn (the queue carries the user message
31
- * until execution); executes nothing. Safe from any short-lived process.
32
- * - `work` — start a worker that consumes queued turns; each turn runs
33
- * start-to-finish in this process, serialized per chat by the TurnQueue.
34
- * - `observe` — reconnect/cancel from anywhere; never spins a sandbox.
35
- *
36
- * Plus the approval verbs: a turn pauses when the model calls a
37
- * `needsApproval` tool (the pause is pure data — a dangling tool part on the
38
- * chain head + a terminal stream); `approve`/`deny` resolve it and re-run the
39
- * turn as a continuation. Turns enqueued while a chat awaits approval QUEUE
40
- * BEHIND it (parked, revived in order after the continuation).
41
- */
42
- export declare function createRuntime(declaration: AgentDeclaration, options: RuntimeOptions): {
43
- enqueue({ chatId, userId }: ConversationId, turn: TurnInput): Promise<{
44
- id: string;
45
- stream: ReadableStream<import("@deepagents/context").StreamPart>;
46
- }>;
47
- approve(conversation: ConversationId, input: {
48
- toolCallId: string;
49
- }): Promise<{
50
- id: string;
51
- stream: ReadableStream<import("@deepagents/context").StreamPart>;
52
- }>;
53
- deny(conversation: ConversationId, input: {
54
- toolCallId: string;
55
- reason?: string;
56
- }): Promise<{
57
- id: string;
58
- stream: ReadableStream<import("@deepagents/context").StreamPart>;
59
- }>;
60
- observe({ chatId, userId }: ConversationId): {
61
- engine: ContextEngine;
62
- resume(): Promise<ReadableStream<import("@deepagents/context").StreamPart> | null>;
63
- cancel(streamId?: string): Promise<void>;
64
- };
65
- work(options?: WorkOptions): Promise<AsyncDisposable>;
66
- };
67
- //# sourceMappingURL=runtime.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/zukhruf/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,aAAa,EACb,KAAK,YAAY,EAGjB,KAAK,WAAW,EAKjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAkB,SAAS,EAAW,MAAM,uBAAuB,CAAC;AAEhF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,gBAAgB,EAC7B,OAAO,EAAE,cAAc;gCAmHa,cAAc,QAAQ,SAAS;;;;0BAsBrC,cAAc,SAAS;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE;;;;uBAOzD,cAAc,SACrB;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;;gCAQpB,cAAc;;;0BAgBd,MAAM;;mBAWb,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;EAc9D"}