@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.
- package/LICENSE +189 -0
- package/README.md +315 -0
- package/dist/package.json +84 -0
- package/dist/src/cli.d.ts +23 -0
- package/dist/src/cli.d.ts.map +1 -0
- package/dist/src/cli.js +754 -0
- package/dist/src/cli.js.map +1 -0
- package/dist/src/core/serializer.d.ts +3 -0
- package/dist/src/core/serializer.d.ts.map +1 -0
- package/dist/src/core/serializer.js +22 -0
- package/dist/src/core/serializer.js.map +1 -0
- package/dist/src/core/structured-output.d.ts +13 -0
- package/dist/src/core/structured-output.d.ts.map +1 -0
- package/dist/src/core/structured-output.js +41 -0
- package/dist/src/core/structured-output.js.map +1 -0
- package/dist/src/guardrails/firewall.d.ts +7 -0
- package/dist/src/guardrails/firewall.d.ts.map +1 -0
- package/dist/src/guardrails/firewall.js +31 -0
- package/dist/src/guardrails/firewall.js.map +1 -0
- package/dist/src/guardrails/pattern.d.ts +13 -0
- package/dist/src/guardrails/pattern.d.ts.map +1 -0
- package/dist/src/guardrails/pattern.js +70 -0
- package/dist/src/guardrails/pattern.js.map +1 -0
- package/dist/src/guardrails/semantic.d.ts +14 -0
- package/dist/src/guardrails/semantic.d.ts.map +1 -0
- package/dist/src/guardrails/semantic.js +47 -0
- package/dist/src/guardrails/semantic.js.map +1 -0
- package/dist/src/index.d.ts +20 -0
- package/dist/src/index.d.ts.map +1 -0
- package/dist/src/index.js +20 -0
- package/dist/src/index.js.map +1 -0
- package/dist/src/lib/compact-json.d.ts +11 -0
- package/dist/src/lib/compact-json.d.ts.map +1 -0
- package/dist/src/lib/compact-json.js +36 -0
- package/dist/src/lib/compact-json.js.map +1 -0
- package/dist/src/lib/xml.d.ts +3 -0
- package/dist/src/lib/xml.d.ts.map +1 -0
- package/dist/src/lib/xml.js +9 -0
- package/dist/src/lib/xml.js.map +1 -0
- package/dist/src/memory/observation-groups.d.ts +15 -0
- package/dist/src/memory/observation-groups.d.ts.map +1 -0
- package/dist/src/memory/observation-groups.js +159 -0
- package/dist/src/memory/observation-groups.js.map +1 -0
- package/dist/src/memory/observational-prompts.d.ts +27 -0
- package/dist/src/memory/observational-prompts.d.ts.map +1 -0
- package/dist/src/memory/observational-prompts.js +237 -0
- package/dist/src/memory/observational-prompts.js.map +1 -0
- package/dist/src/memory/observational.d.ts +63 -0
- package/dist/src/memory/observational.d.ts.map +1 -0
- package/dist/src/memory/observational.js +605 -0
- package/dist/src/memory/observational.js.map +1 -0
- package/dist/src/memory/storage.d.ts +3 -0
- package/dist/src/memory/storage.d.ts.map +1 -0
- package/dist/src/memory/storage.js +127 -0
- package/dist/src/memory/storage.js.map +1 -0
- package/dist/src/memory/store.d.ts +13 -0
- package/dist/src/memory/store.d.ts.map +1 -0
- package/dist/src/memory/store.js +106 -0
- package/dist/src/memory/store.js.map +1 -0
- package/dist/src/model-resolution/duet-gateway.d.ts +35 -0
- package/dist/src/model-resolution/duet-gateway.d.ts.map +1 -0
- package/dist/src/model-resolution/duet-gateway.js +56 -0
- package/dist/src/model-resolution/duet-gateway.js.map +1 -0
- package/dist/src/model-resolution/index.d.ts +31 -0
- package/dist/src/model-resolution/index.d.ts.map +1 -0
- package/dist/src/model-resolution/index.js +129 -0
- package/dist/src/model-resolution/index.js.map +1 -0
- package/dist/src/session/session-manager.d.ts +45 -0
- package/dist/src/session/session-manager.d.ts.map +1 -0
- package/dist/src/session/session-manager.js +94 -0
- package/dist/src/session/session-manager.js.map +1 -0
- package/dist/src/session/session.d.ts +113 -0
- package/dist/src/session/session.d.ts.map +1 -0
- package/dist/src/session/session.js +308 -0
- package/dist/src/session/session.js.map +1 -0
- package/dist/src/tui/app.d.ts +60 -0
- package/dist/src/tui/app.d.ts.map +1 -0
- package/dist/src/tui/app.js +742 -0
- package/dist/src/tui/app.js.map +1 -0
- package/dist/src/turn-runner/agent-events.d.ts +5 -0
- package/dist/src/turn-runner/agent-events.d.ts.map +1 -0
- package/dist/src/turn-runner/agent-events.js +59 -0
- package/dist/src/turn-runner/agent-events.js.map +1 -0
- package/dist/src/turn-runner/prompts.d.ts +13 -0
- package/dist/src/turn-runner/prompts.d.ts.map +1 -0
- package/dist/src/turn-runner/prompts.js +79 -0
- package/dist/src/turn-runner/prompts.js.map +1 -0
- package/dist/src/turn-runner/shell-state-handle.d.ts +32 -0
- package/dist/src/turn-runner/shell-state-handle.d.ts.map +1 -0
- package/dist/src/turn-runner/shell-state-handle.js +168 -0
- package/dist/src/turn-runner/shell-state-handle.js.map +1 -0
- package/dist/src/turn-runner/skill-context.d.ts +26 -0
- package/dist/src/turn-runner/skill-context.d.ts.map +1 -0
- package/dist/src/turn-runner/skill-context.js +110 -0
- package/dist/src/turn-runner/skill-context.js.map +1 -0
- package/dist/src/turn-runner/skills.d.ts +35 -0
- package/dist/src/turn-runner/skills.d.ts.map +1 -0
- package/dist/src/turn-runner/skills.js +130 -0
- package/dist/src/turn-runner/skills.js.map +1 -0
- package/dist/src/turn-runner/state-machine-controller.d.ts +90 -0
- package/dist/src/turn-runner/state-machine-controller.d.ts.map +1 -0
- package/dist/src/turn-runner/state-machine-controller.js +289 -0
- package/dist/src/turn-runner/state-machine-controller.js.map +1 -0
- package/dist/src/turn-runner/state-machine-session.d.ts +27 -0
- package/dist/src/turn-runner/state-machine-session.d.ts.map +1 -0
- package/dist/src/turn-runner/state-machine-session.js +189 -0
- package/dist/src/turn-runner/state-machine-session.js.map +1 -0
- package/dist/src/turn-runner/tools.d.ts +193 -0
- package/dist/src/turn-runner/tools.d.ts.map +1 -0
- package/dist/src/turn-runner/tools.js +509 -0
- package/dist/src/turn-runner/tools.js.map +1 -0
- package/dist/src/turn-runner/turn-runner.d.ts +160 -0
- package/dist/src/turn-runner/turn-runner.d.ts.map +1 -0
- package/dist/src/turn-runner/turn-runner.js +907 -0
- package/dist/src/turn-runner/turn-runner.js.map +1 -0
- package/dist/src/turn-runner/turn-state.d.ts +6 -0
- package/dist/src/turn-runner/turn-state.d.ts.map +1 -0
- package/dist/src/turn-runner/turn-state.js +32 -0
- package/dist/src/turn-runner/turn-state.js.map +1 -0
- package/dist/src/turn-runner/usage-accounting.d.ts +7 -0
- package/dist/src/turn-runner/usage-accounting.d.ts.map +1 -0
- package/dist/src/turn-runner/usage-accounting.js +49 -0
- package/dist/src/turn-runner/usage-accounting.js.map +1 -0
- package/dist/src/types/agent.d.ts +15 -0
- package/dist/src/types/agent.d.ts.map +1 -0
- package/dist/src/types/agent.js +2 -0
- package/dist/src/types/agent.js.map +1 -0
- package/dist/src/types/config.d.ts +37 -0
- package/dist/src/types/config.d.ts.map +1 -0
- package/dist/src/types/config.js +2 -0
- package/dist/src/types/config.js.map +1 -0
- package/dist/src/types/guardrails.d.ts +34 -0
- package/dist/src/types/guardrails.d.ts.map +1 -0
- package/dist/src/types/guardrails.js +2 -0
- package/dist/src/types/guardrails.js.map +1 -0
- package/dist/src/types/memory.d.ts +151 -0
- package/dist/src/types/memory.d.ts.map +1 -0
- package/dist/src/types/memory.js +2 -0
- package/dist/src/types/memory.js.map +1 -0
- package/dist/src/types/protocol.d.ts +426 -0
- package/dist/src/types/protocol.d.ts.map +1 -0
- package/dist/src/types/protocol.js +2 -0
- package/dist/src/types/protocol.js.map +1 -0
- package/dist/src/types/state-machine.d.ts +344 -0
- package/dist/src/types/state-machine.d.ts.map +1 -0
- package/dist/src/types/state-machine.js +2 -0
- package/dist/src/types/state-machine.js.map +1 -0
- 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 @@
|
|
|
1
|
+
{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../src/types/protocol.ts"],"names":[],"mappings":""}
|