@duetso/agent 0.1.20

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 (148) hide show
  1. package/LICENSE +189 -0
  2. package/README.md +315 -0
  3. package/dist/package.json +84 -0
  4. package/dist/src/cli.d.ts +23 -0
  5. package/dist/src/cli.d.ts.map +1 -0
  6. package/dist/src/cli.js +754 -0
  7. package/dist/src/cli.js.map +1 -0
  8. package/dist/src/core/serializer.d.ts +3 -0
  9. package/dist/src/core/serializer.d.ts.map +1 -0
  10. package/dist/src/core/serializer.js +22 -0
  11. package/dist/src/core/serializer.js.map +1 -0
  12. package/dist/src/core/structured-output.d.ts +13 -0
  13. package/dist/src/core/structured-output.d.ts.map +1 -0
  14. package/dist/src/core/structured-output.js +41 -0
  15. package/dist/src/core/structured-output.js.map +1 -0
  16. package/dist/src/guardrails/firewall.d.ts +7 -0
  17. package/dist/src/guardrails/firewall.d.ts.map +1 -0
  18. package/dist/src/guardrails/firewall.js +31 -0
  19. package/dist/src/guardrails/firewall.js.map +1 -0
  20. package/dist/src/guardrails/pattern.d.ts +13 -0
  21. package/dist/src/guardrails/pattern.d.ts.map +1 -0
  22. package/dist/src/guardrails/pattern.js +70 -0
  23. package/dist/src/guardrails/pattern.js.map +1 -0
  24. package/dist/src/guardrails/semantic.d.ts +14 -0
  25. package/dist/src/guardrails/semantic.d.ts.map +1 -0
  26. package/dist/src/guardrails/semantic.js +47 -0
  27. package/dist/src/guardrails/semantic.js.map +1 -0
  28. package/dist/src/index.d.ts +20 -0
  29. package/dist/src/index.d.ts.map +1 -0
  30. package/dist/src/index.js +20 -0
  31. package/dist/src/index.js.map +1 -0
  32. package/dist/src/lib/compact-json.d.ts +11 -0
  33. package/dist/src/lib/compact-json.d.ts.map +1 -0
  34. package/dist/src/lib/compact-json.js +36 -0
  35. package/dist/src/lib/compact-json.js.map +1 -0
  36. package/dist/src/lib/xml.d.ts +3 -0
  37. package/dist/src/lib/xml.d.ts.map +1 -0
  38. package/dist/src/lib/xml.js +9 -0
  39. package/dist/src/lib/xml.js.map +1 -0
  40. package/dist/src/memory/observation-groups.d.ts +15 -0
  41. package/dist/src/memory/observation-groups.d.ts.map +1 -0
  42. package/dist/src/memory/observation-groups.js +159 -0
  43. package/dist/src/memory/observation-groups.js.map +1 -0
  44. package/dist/src/memory/observational-prompts.d.ts +27 -0
  45. package/dist/src/memory/observational-prompts.d.ts.map +1 -0
  46. package/dist/src/memory/observational-prompts.js +237 -0
  47. package/dist/src/memory/observational-prompts.js.map +1 -0
  48. package/dist/src/memory/observational.d.ts +63 -0
  49. package/dist/src/memory/observational.d.ts.map +1 -0
  50. package/dist/src/memory/observational.js +605 -0
  51. package/dist/src/memory/observational.js.map +1 -0
  52. package/dist/src/memory/storage.d.ts +3 -0
  53. package/dist/src/memory/storage.d.ts.map +1 -0
  54. package/dist/src/memory/storage.js +127 -0
  55. package/dist/src/memory/storage.js.map +1 -0
  56. package/dist/src/memory/store.d.ts +13 -0
  57. package/dist/src/memory/store.d.ts.map +1 -0
  58. package/dist/src/memory/store.js +106 -0
  59. package/dist/src/memory/store.js.map +1 -0
  60. package/dist/src/model-resolution/duet-gateway.d.ts +35 -0
  61. package/dist/src/model-resolution/duet-gateway.d.ts.map +1 -0
  62. package/dist/src/model-resolution/duet-gateway.js +56 -0
  63. package/dist/src/model-resolution/duet-gateway.js.map +1 -0
  64. package/dist/src/model-resolution/index.d.ts +31 -0
  65. package/dist/src/model-resolution/index.d.ts.map +1 -0
  66. package/dist/src/model-resolution/index.js +129 -0
  67. package/dist/src/model-resolution/index.js.map +1 -0
  68. package/dist/src/session/session-manager.d.ts +45 -0
  69. package/dist/src/session/session-manager.d.ts.map +1 -0
  70. package/dist/src/session/session-manager.js +94 -0
  71. package/dist/src/session/session-manager.js.map +1 -0
  72. package/dist/src/session/session.d.ts +113 -0
  73. package/dist/src/session/session.d.ts.map +1 -0
  74. package/dist/src/session/session.js +308 -0
  75. package/dist/src/session/session.js.map +1 -0
  76. package/dist/src/tui/app.d.ts +60 -0
  77. package/dist/src/tui/app.d.ts.map +1 -0
  78. package/dist/src/tui/app.js +742 -0
  79. package/dist/src/tui/app.js.map +1 -0
  80. package/dist/src/turn-runner/agent-events.d.ts +5 -0
  81. package/dist/src/turn-runner/agent-events.d.ts.map +1 -0
  82. package/dist/src/turn-runner/agent-events.js +59 -0
  83. package/dist/src/turn-runner/agent-events.js.map +1 -0
  84. package/dist/src/turn-runner/prompts.d.ts +13 -0
  85. package/dist/src/turn-runner/prompts.d.ts.map +1 -0
  86. package/dist/src/turn-runner/prompts.js +79 -0
  87. package/dist/src/turn-runner/prompts.js.map +1 -0
  88. package/dist/src/turn-runner/shell-state-handle.d.ts +32 -0
  89. package/dist/src/turn-runner/shell-state-handle.d.ts.map +1 -0
  90. package/dist/src/turn-runner/shell-state-handle.js +168 -0
  91. package/dist/src/turn-runner/shell-state-handle.js.map +1 -0
  92. package/dist/src/turn-runner/skill-context.d.ts +26 -0
  93. package/dist/src/turn-runner/skill-context.d.ts.map +1 -0
  94. package/dist/src/turn-runner/skill-context.js +110 -0
  95. package/dist/src/turn-runner/skill-context.js.map +1 -0
  96. package/dist/src/turn-runner/skills.d.ts +35 -0
  97. package/dist/src/turn-runner/skills.d.ts.map +1 -0
  98. package/dist/src/turn-runner/skills.js +130 -0
  99. package/dist/src/turn-runner/skills.js.map +1 -0
  100. package/dist/src/turn-runner/state-machine-controller.d.ts +90 -0
  101. package/dist/src/turn-runner/state-machine-controller.d.ts.map +1 -0
  102. package/dist/src/turn-runner/state-machine-controller.js +289 -0
  103. package/dist/src/turn-runner/state-machine-controller.js.map +1 -0
  104. package/dist/src/turn-runner/state-machine-session.d.ts +27 -0
  105. package/dist/src/turn-runner/state-machine-session.d.ts.map +1 -0
  106. package/dist/src/turn-runner/state-machine-session.js +189 -0
  107. package/dist/src/turn-runner/state-machine-session.js.map +1 -0
  108. package/dist/src/turn-runner/tools.d.ts +193 -0
  109. package/dist/src/turn-runner/tools.d.ts.map +1 -0
  110. package/dist/src/turn-runner/tools.js +509 -0
  111. package/dist/src/turn-runner/tools.js.map +1 -0
  112. package/dist/src/turn-runner/turn-runner.d.ts +160 -0
  113. package/dist/src/turn-runner/turn-runner.d.ts.map +1 -0
  114. package/dist/src/turn-runner/turn-runner.js +907 -0
  115. package/dist/src/turn-runner/turn-runner.js.map +1 -0
  116. package/dist/src/turn-runner/turn-state.d.ts +6 -0
  117. package/dist/src/turn-runner/turn-state.d.ts.map +1 -0
  118. package/dist/src/turn-runner/turn-state.js +32 -0
  119. package/dist/src/turn-runner/turn-state.js.map +1 -0
  120. package/dist/src/turn-runner/usage-accounting.d.ts +7 -0
  121. package/dist/src/turn-runner/usage-accounting.d.ts.map +1 -0
  122. package/dist/src/turn-runner/usage-accounting.js +49 -0
  123. package/dist/src/turn-runner/usage-accounting.js.map +1 -0
  124. package/dist/src/types/agent.d.ts +15 -0
  125. package/dist/src/types/agent.d.ts.map +1 -0
  126. package/dist/src/types/agent.js +2 -0
  127. package/dist/src/types/agent.js.map +1 -0
  128. package/dist/src/types/config.d.ts +37 -0
  129. package/dist/src/types/config.d.ts.map +1 -0
  130. package/dist/src/types/config.js +2 -0
  131. package/dist/src/types/config.js.map +1 -0
  132. package/dist/src/types/guardrails.d.ts +34 -0
  133. package/dist/src/types/guardrails.d.ts.map +1 -0
  134. package/dist/src/types/guardrails.js +2 -0
  135. package/dist/src/types/guardrails.js.map +1 -0
  136. package/dist/src/types/memory.d.ts +151 -0
  137. package/dist/src/types/memory.d.ts.map +1 -0
  138. package/dist/src/types/memory.js +2 -0
  139. package/dist/src/types/memory.js.map +1 -0
  140. package/dist/src/types/protocol.d.ts +426 -0
  141. package/dist/src/types/protocol.d.ts.map +1 -0
  142. package/dist/src/types/protocol.js +2 -0
  143. package/dist/src/types/protocol.js.map +1 -0
  144. package/dist/src/types/state-machine.d.ts +344 -0
  145. package/dist/src/types/state-machine.d.ts.map +1 -0
  146. package/dist/src/types/state-machine.js +2 -0
  147. package/dist/src/types/state-machine.js.map +1 -0
  148. package/package.json +84 -0
@@ -0,0 +1,426 @@
1
+ import type { ImageContent, TextContent, ThinkingLevel } from "@earendil-works/pi-ai";
2
+ import type { AgentSession } from "./agent.js";
3
+ import type { ObservationalMemoryActivityEvent } from "./memory.js";
4
+ import type { StateMachineDefinition, StateMachineSession } from "./state-machine.js";
5
+ /**
6
+ * TurnRunner Protocol
7
+ *
8
+ * A JSON-friendly command/event protocol for operating duet turn runners.
9
+ * The transport is intentionally unspecified. A CLI, daemon, HTTP server, or
10
+ * parent process can all speak this protocol as long as they can send commands
11
+ * and consume streamed events.
12
+ *
13
+ * The protocol is not a comm layer. It is the control surface for the
14
+ * runner itself:
15
+ *
16
+ * - commands tell the runner what to do
17
+ * - turn events report work during the turn and end each turn
18
+ *
19
+ * ## Turn Model
20
+ *
21
+ * The runner is a stateful turn executor: `start` bootstraps the current
22
+ * `TurnState`, and each terminal event returns the next snapshot. The session
23
+ * is the persistence owner. It assigns session ids, hydrates stored snapshots
24
+ * before start, persists terminal snapshots, schedules wakeups, and can run an
25
+ * unbounded number of turn-runner turns for the same user session.
26
+ *
27
+ * A caller initializes a session by sending `start`. This is a setup command,
28
+ * not a turn: the runner loads memory and skills, emits `turn_started`
29
+ * with the initial empty `TurnState`, and returns. Skills, agent files, and
30
+ * skill collisions are exposed through `getSkills()`, `getResolvedAgentFiles()`,
31
+ * and `getSkillCollisions()` for callers (CLI/TUI) that want to render a
32
+ * setup summary; no agent work runs until the caller sends a follow-up.
33
+ *
34
+ * Once the session is set up, callers run turns by sending one of:
35
+ *
36
+ * - `prompt`: send a user prompt against the current state
37
+ * - `answer`: answer questions from the previous terminal `ask` event
38
+ * - `wake`: resume a sleeping session for one scheduled state-machine step
39
+ *
40
+ * Each turn emits any number of during-turn events (`step`, `todos`,
41
+ * `follow_up_queue`, `state_machine`, `log`). The turn ends with exactly one
42
+ * terminal event:
43
+ * `complete`, `ask`, `interrupted`, or `sleep`.
44
+ * Terminal events carry the turn runner-owned state needed to continue a later turn.
45
+ * `complete` means this turn-runner turn ended; it does not mean the session
46
+ * session is finished. A user can follow up with another prompt for the same
47
+ * session; the runner continues from its internally held `TurnState`. The
48
+ * agent session is always present because the agent owns the conversation
49
+ * history and, for state-machine mode, drives state transitions.
50
+ *
51
+ * ## Scenario 1: One-Shot Agent Task
52
+ *
53
+ * The user asks for a normal task, such as "summarize this file" or "fix this
54
+ * bug." The caller sends `start` (omitting `mode` or setting `mode: "auto"`)
55
+ * to set the session up; the runner emits `turn_started` with an empty
56
+ * `state.agent`. When the user types their first prompt, the caller sends a
57
+ * `prompt` command and the runner classifies it as agent mode and emits:
58
+ *
59
+ * 1. zero or more `step`, `todos`, `follow_up_queue`, or `log` events
60
+ * 2. `complete` with the final answer and updated `state.agent`
61
+ *
62
+ * This behaves like a normal agent runner. There is no state-machine UI because
63
+ * the session is not a long-running business process.
64
+ *
65
+ * ## Scenario 2: Auto-Selected State Machine
66
+ *
67
+ * The user asks for a task with a complex lifecycle, such as "prospect this
68
+ * customer until they book a meeting" or "implement this change, open a PR, and
69
+ * watch it until merge." With `mode: "auto"`, the first `prompt` after `start`
70
+ * routes through the runner, which chooses a state machine and populates
71
+ * `state.stateMachine` on the next emitted state.
72
+ *
73
+ * During the turn, the runner emits events that the UI can render directly:
74
+ *
75
+ * - `state_machine` shows the current state name
76
+ * - `step` shows textual progress, reasoning, tool calls, or system messages
77
+ * - `todos` shows current task progress
78
+ * - `follow_up_queue` shows prompts waiting for the current turn chain to finish
79
+ * - `log` shows diagnostic messages
80
+ *
81
+ * The UI can always render `state.agent` as the conversation transcript. When it
82
+ * also sees `state.stateMachine`, it can render a Kanban board for the state
83
+ * machine. Each `state_machine` event moves the visible session card to the
84
+ * current state column and updates the lifecycle status.
85
+ *
86
+ * ### Scenario 2a: User Follow-Up Interrupts The Turn
87
+ *
88
+ * While the state machine is running, the user can send a `prompt` command with
89
+ * `behavior: "steer"`. The runner should treat this as additional user
90
+ * context for the active pi session. For example, the user might say "I've
91
+ * already received this email" while the state machine is waiting for a reply.
92
+ * The runner agent can incorporate that message, update the state-machine
93
+ * state, and then continue the same state-machine session instead of abandoning it.
94
+ *
95
+ * A typical stream is:
96
+ *
97
+ * 1. `step` events while the agent incorporates the user's update
98
+ * 2. more `state_machine` events as the updated state machine continues
99
+ * 3. a terminal event (`complete`, `ask`, `sleep`, or `interrupted`) carrying
100
+ * the updated `state`
101
+ *
102
+ * ### Scenario 2b: Scheduled States Use Sleep
103
+ *
104
+ * A state machine might send an email and then wait for a reply, or pause until
105
+ * a specific timestamp. Recurring external checks should be modeled as poll
106
+ * states, not as user-owned infinite polling scripts. Absolute waits should be
107
+ * modeled as timer states. When scheduled work needs to wait, the runner emits
108
+ * a terminal `sleep` event with `wakeAt`.
109
+ *
110
+ * The layer above the runner persists the state, schedules a wakeup for `wakeAt`,
111
+ * and starts the runner again at that time. On each wake, the runner performs
112
+ * the scheduled poll attempt or completes the timer state. Once scheduled work
113
+ * finishes, the runner records it in the state-machine session and continues to
114
+ * the next state.
115
+ *
116
+ * If the user sends a prompt while the session is sleeping on a
117
+ * scheduled state, the session cancels the pending wake, runs that prompt
118
+ * as a normal turn-runner turn, and returns the session to `sleep` if the state
119
+ * machine is still waiting. The user should not see a stable `complete` state
120
+ * while the business process is actually waiting on something external.
121
+ *
122
+ * ### Scenario 2c: Interrupting State-Machine Work
123
+ *
124
+ * An interrupt stops active turn-runner work for the current turn. If a state-machine
125
+ * session is active, interruption also records an interrupted state-machine
126
+ * terminal marker. Scheduled wakeups are owned by the session and are cancelled
127
+ * there. A later user prompt starts a new turn from the interrupted state; the
128
+ * parent agent can choose the right continuation.
129
+ *
130
+ * ## Scenario 3: Explicit State Machine Definition
131
+ *
132
+ * A caller can pass a full `StateMachineDefinition` as `mode`. The definition
133
+ * is a set of possible states the runner may use, not a command to force every
134
+ * prompt into that state machine.
135
+ *
136
+ * If the user's prompt matches the definition, the runner runs that state
137
+ * machine directly and emits the same state-machine events as Scenario 2.
138
+ *
139
+ * If the user's prompt does not fit the provided definition, the runner should
140
+ * answer normally in agent mode. Conceptually, the selected state can be
141
+ * `undefined`: none of the possible states fit the user's request.
142
+ */
143
+ /**
144
+ * Top-level execution mode for a prompt.
145
+ *
146
+ * - "agent": handle the prompt as a normal one-shot/current-session agent session.
147
+ * - "auto": let the runner classify which mode the prompt needs. Auto sessions
148
+ * may create new state-machine definitions over time, even after a previous
149
+ * state machine reached a terminal state.
150
+ * - StateMachineDefinition: use this explicit set of possible states when it fits.
151
+ * Explicit-definition sessions are constrained to this definition; if none of its
152
+ * states fit, the selected state can be undefined and the runner can answer normally.
153
+ */
154
+ export type TurnMode = "agent" | "auto" | StateMachineDefinition;
155
+ export type TurnRunnerTerminalStatus = "completed" | "failed" | "cancelled";
156
+ export type TurnStateStatus = "running" | "waiting_for_human" | "sleeping" | "interrupted" | TurnRunnerTerminalStatus;
157
+ /** TurnRunner-owned state snapshot needed to continue a later turn. */
158
+ export interface TurnState {
159
+ /** Lifecycle of the current turn state, regardless of agent or state-machine mode. */
160
+ status: TurnStateStatus;
161
+ /**
162
+ * The mode originally used to start the session. This is required on resume so
163
+ * "auto" sessions can keep creating definitions while explicit-definition sessions
164
+ * stay constrained to their provided state set.
165
+ */
166
+ mode: TurnMode;
167
+ /**
168
+ * Effective runtime options for future turns. Persisted separately from agent
169
+ * transcripts so model, memory model, and thinking level survive resume even
170
+ * when process defaults change.
171
+ */
172
+ options?: TurnOptions;
173
+ /** The agent conversation is always present, including state-machine sessions. */
174
+ agent: AgentSession;
175
+ /** Present when this session is executing in state-machine mode. */
176
+ stateMachine?: StateMachineSession;
177
+ /**
178
+ * Current todo list written by the todo tool. Persisted with the turn state so
179
+ * resumed runners preserve the same work plan instead of starting with an
180
+ * empty tool-local list.
181
+ */
182
+ todos?: TurnTodo[];
183
+ /**
184
+ * User-visible follow-up prompts waiting to be delivered. The runner mirrors
185
+ * this into pi-agent follow-up queues when a parent agent is active.
186
+ */
187
+ followUpQueue?: string[];
188
+ /**
189
+ * Commands accepted by the runner but not yet executed because active work
190
+ * could not absorb them. These are replayed after resume in the original
191
+ * order when the runner can safely continue.
192
+ */
193
+ queuedCommands?: TurnCommand[];
194
+ }
195
+ /**
196
+ * How a follow-up prompt should be delivered while a pi session is active.
197
+ *
198
+ * - "steer": deliver as an interruption/steering message to the active pi agent.
199
+ * - "follow_up": queue until the active pi agent finishes its current turn.
200
+ */
201
+ export type TurnPromptBehavior = "steer" | "follow_up";
202
+ export interface TurnOptions {
203
+ /** Model override for the user-visible agent turn, in provider:modelId format. */
204
+ model?: string;
205
+ /**
206
+ * Model override for observational memory extraction and reflection, in
207
+ * provider:modelId format. When omitted, memory work uses the runner's
208
+ * configured `memoryModel`, then the default memory model.
209
+ */
210
+ memoryModel?: string;
211
+ thinkingLevel?: ThinkingLevel;
212
+ }
213
+ export interface TurnQuestionOption {
214
+ /** Display label shown to the user. */
215
+ label: string;
216
+ /** Optional extra context for the option. */
217
+ description?: string;
218
+ }
219
+ export interface TurnQuestion {
220
+ /** Question text shown to the user. */
221
+ question: string;
222
+ /** Optional section heading for grouped questions. */
223
+ header?: string;
224
+ /** Available answers. */
225
+ options: TurnQuestionOption[];
226
+ /** Whether multiple options can be selected. */
227
+ multiSelect?: boolean;
228
+ }
229
+ export type TurnTodoStatus = "pending" | "in_progress" | "completed" | "failed";
230
+ export interface TurnTodo {
231
+ /** Stable identifier used by todo edits to replace an existing work item. */
232
+ id: string;
233
+ /** Stable UI-facing label for the work item. */
234
+ content: string;
235
+ /** Current progress state for the work item. */
236
+ status: TurnTodoStatus;
237
+ }
238
+ export interface TurnTokenUsage {
239
+ inputTokens: number;
240
+ outputTokens: number;
241
+ cachedInputTokens?: number;
242
+ costUsd?: number;
243
+ }
244
+ export type TurnStep = {
245
+ type: "text_delta";
246
+ /** Partial assistant text streamed before the canonical `text` step arrives. */
247
+ delta: string;
248
+ } | {
249
+ type: "reasoning_delta";
250
+ /** Partial reasoning streamed before the canonical `reasoning` step arrives. */
251
+ delta: string;
252
+ } | {
253
+ type: "text";
254
+ text: string;
255
+ } | {
256
+ type: "reasoning";
257
+ text: string;
258
+ } | {
259
+ type: "tool_call";
260
+ toolName: string;
261
+ toolCallId: string;
262
+ status: "pending" | "running" | "completed" | "error";
263
+ /** Tool arguments as parsed by the model. Shape is tool-specific. */
264
+ input?: Record<string, any>;
265
+ /** Tool result content, present once the tool finishes (status "completed" or "error"). */
266
+ output?: (TextContent | ImageContent)[];
267
+ } | {
268
+ type: "system";
269
+ message: string;
270
+ };
271
+ /**
272
+ * Set up a new turn-runner session.
273
+ *
274
+ * `start` is a setup command, not a turn. The runner loads memory and skills,
275
+ * stores its initial `TurnState` (either fresh or the resumed one passed via
276
+ * `state`), and emits `turn_started`. No agent work runs. The caller sends
277
+ * `prompt` afterwards to actually run a turn. Skills, agent files, and skill
278
+ * collisions are exposed through dedicated runner methods so callers can
279
+ * render the setup summary without subscribing to a dedicated event.
280
+ *
281
+ * The CLI/TUI sends this on launch so the user sees the available skills
282
+ * before typing the first prompt.
283
+ */
284
+ export interface TurnStartCommand {
285
+ type: "start";
286
+ /** Routing mode for subsequent prompts. Omit to use the turn runner's configured default. */
287
+ mode?: TurnMode;
288
+ /**
289
+ * Existing state to resume. When provided, the runner emits `turn_started`
290
+ * with this state instead of creating a fresh one. Resumed sessions keep
291
+ * their persisted agent and state-machine history.
292
+ */
293
+ state?: TurnState;
294
+ /**
295
+ * Session-scoped runtime options. These are fixed when the runner starts so
296
+ * the parent pi-agent keeps a stable model, thinking level, and prompt cache
297
+ * shape across every pi-agent turn inside later duet-agent turns.
298
+ */
299
+ options?: TurnOptions;
300
+ }
301
+ /**
302
+ * Send a new user prompt against the runner's current state.
303
+ *
304
+ * Callers may send prompt commands even while a previous `turn()` call is
305
+ * active. The turn runner maps `behavior` onto the active pi agent when it can
306
+ * and otherwise queues the command behind active non-agent work. State is held
307
+ * inside the runner; it was bootstrapped at `start` and is updated from the
308
+ * runner's own terminal events.
309
+ */
310
+ export interface TurnPromptCommand {
311
+ type: "prompt";
312
+ message: string;
313
+ /**
314
+ * Delivery behavior for this user message. The runner decides whether the
315
+ * parent pi-agent or state-machine work is currently driving the public
316
+ * duet-agent turn; that driver determines whether this reaches pi immediately
317
+ * or waits for state-transition context.
318
+ */
319
+ behavior: TurnPromptBehavior;
320
+ }
321
+ /**
322
+ * Provide answers to a structured question emitted by the runner.
323
+ *
324
+ * Answers serialize into parent-agent prompt text and follow the same active
325
+ * turn behavior as prompts. State-agent answers also route through the parent,
326
+ * which can inspect state-machine history and select the appropriate state.
327
+ */
328
+ export interface TurnAnswerCommand {
329
+ type: "answer";
330
+ questions: TurnQuestion[];
331
+ answers: Record<string, string>;
332
+ /** Same delivery behavior as prompts after the answers are serialized. */
333
+ behavior: TurnPromptBehavior;
334
+ }
335
+ /** Wake the runner's sleeping state. If the state is not waiting on scheduled work, this is a no-op. */
336
+ export interface TurnWakeCommand {
337
+ type: "wake";
338
+ }
339
+ /**
340
+ * Replace the currently visible follow-up queue.
341
+ *
342
+ * This is an out-of-band edit command for UI clients. It mirrors the queue into
343
+ * the active pi agent when possible, but the protocol event is emitted from the
344
+ * runner-owned prompt list so clients can render and edit it directly.
345
+ */
346
+ export interface TurnEditFollowUpQueueCommand {
347
+ type: "edit_follow_up_queue";
348
+ /** Full replacement queue, in the order prompts should be delivered. */
349
+ prompts: string[];
350
+ }
351
+ /**
352
+ * Commands that drive a single turn-runner turn. `start` is excluded because
353
+ * setup is not a turn and is handled by `TurnRunner.start()` directly.
354
+ */
355
+ export type TurnCommand = TurnPromptCommand | TurnAnswerCommand | TurnWakeCommand;
356
+ /** Out-of-band control message that interrupts the currently running turn. */
357
+ export interface TurnInterruptCommand {
358
+ type: "interrupt";
359
+ }
360
+ export type TurnRunnerCommand = TurnStartCommand | TurnCommand | TurnInterruptCommand | TurnEditFollowUpQueueCommand;
361
+ /** A system-prompt file that was resolved on disk for the session. */
362
+ export interface TurnAgentFile {
363
+ /** Configured file name relative to the working directory, e.g. "AGENTS.md". */
364
+ name: string;
365
+ /** Absolute path on disk. */
366
+ path: string;
367
+ }
368
+ export interface TurnStartedEvent {
369
+ type: "turn_started";
370
+ /** Full turn state after applying config/options/auto routing. */
371
+ state: TurnState;
372
+ }
373
+ export interface TurnStepEvent {
374
+ type: "step";
375
+ step: TurnStep;
376
+ }
377
+ export interface TurnTodosEvent {
378
+ type: "todos";
379
+ todos: TurnTodo[];
380
+ }
381
+ export interface TurnFollowUpQueueEvent {
382
+ type: "follow_up_queue";
383
+ /** Prompts currently waiting to run as follow-ups after active work settles. */
384
+ prompts: string[];
385
+ }
386
+ export interface TurnStateMachineEvent {
387
+ type: "state_machine";
388
+ /** Display name of the current state. */
389
+ currentState: string;
390
+ }
391
+ export interface TurnMemoryEvent extends ObservationalMemoryActivityEvent {
392
+ type: "memory";
393
+ }
394
+ export interface TurnTerminalBaseEvent {
395
+ state: TurnState;
396
+ usage?: TurnTokenUsage;
397
+ }
398
+ export interface TurnAskEvent extends TurnTerminalBaseEvent {
399
+ type: "ask";
400
+ questions: TurnQuestion[];
401
+ }
402
+ export interface TurnCompletedEvent extends TurnTerminalBaseEvent {
403
+ type: "complete";
404
+ status: TurnRunnerTerminalStatus;
405
+ result?: string;
406
+ error?: string;
407
+ }
408
+ export interface TurnInterruptedEvent extends TurnTerminalBaseEvent {
409
+ type: "interrupted";
410
+ }
411
+ export interface TurnSleepEvent extends TurnTerminalBaseEvent {
412
+ type: "sleep";
413
+ /** Unix timestamp in milliseconds when the outer layer should wake the runner. */
414
+ wakeAt: number;
415
+ }
416
+ export interface TurnSystemEvent {
417
+ type: "system";
418
+ level: "debug" | "info" | "warn" | "error";
419
+ message: string;
420
+ }
421
+ /** Events emitted while the runner is still working on the current turn. */
422
+ export type TurnDuringEvent = TurnStepEvent | TurnTodosEvent | TurnFollowUpQueueEvent | TurnStateMachineEvent | TurnMemoryEvent | TurnSystemEvent;
423
+ /** Events that end the current turn. */
424
+ export type TurnTerminalEvent = TurnAskEvent | TurnCompletedEvent | TurnInterruptedEvent | TurnSleepEvent;
425
+ export type TurnEvent = TurnStartedEvent | TurnDuringEvent | TurnTerminalEvent;
426
+ //# sourceMappingURL=protocol.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/types/protocol.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=protocol.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/types/protocol.ts"],"names":[],"mappings":""}