@av-pi-studio/server 0.0.114 → 0.0.115
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/dist/agent/agent-service.d.ts +5 -0
- package/dist/agent/agent-service.js +12 -0
- package/dist/agent/providers/mock/mock-provider.d.ts +4 -0
- package/dist/agent/providers/mock/mock-provider.js +34 -1
- package/dist/agent/providers/mock/tool-script.d.ts +28 -0
- package/dist/agent/providers/mock/tool-script.js +72 -0
- package/dist/agent/providers/pi/agent.js +15 -0
- package/dist/agent/providers/pi/event-mapper.d.ts +15 -12
- package/dist/agent/providers/pi/event-mapper.js +33 -15
- package/dist/agent/providers/pi/tool-output-coalescer.d.ts +58 -0
- package/dist/agent/providers/pi/tool-output-coalescer.js +121 -0
- package/package.json +3 -3
|
@@ -42,6 +42,11 @@ export declare function resetTimeline(agentId: string, rows: import("./timeline-
|
|
|
42
42
|
* Record `event` on `agentId`'s timeline and broadcast it as an `agent_stream` frame carrying the
|
|
43
43
|
* daemon-owned seq/timestamp. The one append-and-broadcast path for stream events: `runTurn`'s
|
|
44
44
|
* subscription and any operation that subscribes outside a turn (today: compaction) both use it.
|
|
45
|
+
*
|
|
46
|
+
* Two kinds are EPHEMERAL (live-stream-only, see timeline-streaming.md § Timeline model): a partial
|
|
47
|
+
* `tool_call` (a superseded in-flight output snapshot) and `queue_update` (a snapshot of the
|
|
48
|
+
* pending steer/follow-up queues). They are broadcast with a daemon-owned `timestamp` but NO `seq`,
|
|
49
|
+
* and are never appended to the timeline, so they never appear in fetched history.
|
|
45
50
|
*/
|
|
46
51
|
export declare function appendStreamEvent(agentId: string, event: AgentStreamEvent, broadcast: (sessions: Iterable<Session>, message: unknown) => void, sessions: Iterable<Session>): void;
|
|
47
52
|
/**
|
|
@@ -43,8 +43,20 @@ export function resetTimeline(agentId, rows) {
|
|
|
43
43
|
* Record `event` on `agentId`'s timeline and broadcast it as an `agent_stream` frame carrying the
|
|
44
44
|
* daemon-owned seq/timestamp. The one append-and-broadcast path for stream events: `runTurn`'s
|
|
45
45
|
* subscription and any operation that subscribes outside a turn (today: compaction) both use it.
|
|
46
|
+
*
|
|
47
|
+
* Two kinds are EPHEMERAL (live-stream-only, see timeline-streaming.md § Timeline model): a partial
|
|
48
|
+
* `tool_call` (a superseded in-flight output snapshot) and `queue_update` (a snapshot of the
|
|
49
|
+
* pending steer/follow-up queues). They are broadcast with a daemon-owned `timestamp` but NO `seq`,
|
|
50
|
+
* and are never appended to the timeline, so they never appear in fetched history.
|
|
46
51
|
*/
|
|
47
52
|
export function appendStreamEvent(agentId, event, broadcast, sessions) {
|
|
53
|
+
if ((event.kind === "tool_call" && event.partial) || event.kind === "queue_update") {
|
|
54
|
+
broadcast(sessions, {
|
|
55
|
+
type: "session",
|
|
56
|
+
message: { type: "agent_stream", agentId, timestamp: new Date().toISOString(), event },
|
|
57
|
+
});
|
|
58
|
+
return;
|
|
59
|
+
}
|
|
48
60
|
const row = getOrCreateTimeline(agentId).append(event);
|
|
49
61
|
broadcast(sessions, {
|
|
50
62
|
type: "session",
|
|
@@ -67,6 +67,10 @@ export declare class MockAgentSession implements AgentSession {
|
|
|
67
67
|
* instead of the normal echoed turn. Mirrors `startUiScriptTurn`'s shape: resolves immediately
|
|
68
68
|
* with the turn id, the emission and the echo happen after `turnDelayMs`. */
|
|
69
69
|
private startTodoScriptTurn;
|
|
70
|
+
/** `#tool ...` prompt (sprint-058/task-004): after `turnDelayMs`, emit the scripted tool-call
|
|
71
|
+
* lifecycle (start, 3 partials, end) synchronously — no timers between tool events — then the
|
|
72
|
+
* usual echo and `turn_completed`. `help` emits the recipe list and no tool events. */
|
|
73
|
+
private startToolScriptTurn;
|
|
70
74
|
/** Builds the raw (uncapped) task list for every recipe except `help`, which `startTodoScriptTurn`
|
|
71
75
|
* handles itself. `advance` reads `currentTodos` — the only recipe whose result depends on
|
|
72
76
|
* session state — everything else is a pure `todo-script.ts` builder. */
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto";
|
|
2
2
|
import { capAgentTodos } from "../../agent-todos/todo-limits.js";
|
|
3
3
|
import { advanceTodos, blockedTodos, clearTodos, doneTodos, getTodoScriptHelpText, hugeTodos, literalTodos, manyTodos, parseTodoScript, planTodos, } from "./todo-script.js";
|
|
4
|
+
import { getToolScriptHelpText, parseToolScript, toolScriptEvents, } from "./tool-script.js";
|
|
4
5
|
import { getUiScriptHelpText, parseUiScript } from "./ui-script.js";
|
|
5
6
|
/**
|
|
6
7
|
* In-process `mock` provider (features/agent-providers.md § Provider entry — dev/test only). It
|
|
@@ -75,7 +76,11 @@ export class MockAgentSession {
|
|
|
75
76
|
this.compactDelayMs = options.compactDelayMs ?? MOCK_COMPACT_DELAY_MS;
|
|
76
77
|
}
|
|
77
78
|
emit(event) {
|
|
78
|
-
|
|
79
|
+
// Ephemeral partial tool snapshots reach subscribers but never the replay buffer — the mirror
|
|
80
|
+
// of the Pi coalescer's history rule (tool-output-streaming.md tenet 2), so a post-restart
|
|
81
|
+
// hydration contains no partials.
|
|
82
|
+
if (!(event.kind === "tool_call" && event.partial))
|
|
83
|
+
this.history.push(event);
|
|
79
84
|
for (const cb of this.subscribers)
|
|
80
85
|
cb(event);
|
|
81
86
|
}
|
|
@@ -94,6 +99,9 @@ export class MockAgentSession {
|
|
|
94
99
|
const todoRecipe = parseTodoScript(prompt);
|
|
95
100
|
if (todoRecipe !== null)
|
|
96
101
|
return this.startTodoScriptTurn(todoRecipe);
|
|
102
|
+
const toolRecipe = parseToolScript(prompt);
|
|
103
|
+
if (toolRecipe !== null)
|
|
104
|
+
return this.startToolScriptTurn(toolRecipe);
|
|
97
105
|
const turnId = randomUUID();
|
|
98
106
|
this.activeTurn = turnId;
|
|
99
107
|
this.emit({ kind: "turn_started", turnId });
|
|
@@ -164,6 +172,31 @@ export class MockAgentSession {
|
|
|
164
172
|
}, this.turnDelayMs);
|
|
165
173
|
return Promise.resolve({ turnId });
|
|
166
174
|
}
|
|
175
|
+
/** `#tool ...` prompt (sprint-058/task-004): after `turnDelayMs`, emit the scripted tool-call
|
|
176
|
+
* lifecycle (start, 3 partials, end) synchronously — no timers between tool events — then the
|
|
177
|
+
* usual echo and `turn_completed`. `help` emits the recipe list and no tool events. */
|
|
178
|
+
startToolScriptTurn(recipe) {
|
|
179
|
+
const turnId = randomUUID();
|
|
180
|
+
this.activeTurn = turnId;
|
|
181
|
+
this.emit({ kind: "turn_started", turnId });
|
|
182
|
+
setTimeout(() => {
|
|
183
|
+
if (this.activeTurn !== turnId)
|
|
184
|
+
return;
|
|
185
|
+
let text;
|
|
186
|
+
if (recipe === "help") {
|
|
187
|
+
text = getToolScriptHelpText();
|
|
188
|
+
}
|
|
189
|
+
else {
|
|
190
|
+
for (const event of toolScriptEvents(recipe, randomUUID()))
|
|
191
|
+
this.emit(event);
|
|
192
|
+
text = `echo: #tool ${recipe}`;
|
|
193
|
+
}
|
|
194
|
+
this.emit({ kind: "assistant_message", messageId: randomUUID(), text, final: true });
|
|
195
|
+
this.emit({ kind: "turn_completed", turnId });
|
|
196
|
+
this.activeTurn = null;
|
|
197
|
+
}, this.turnDelayMs);
|
|
198
|
+
return Promise.resolve({ turnId });
|
|
199
|
+
}
|
|
167
200
|
/** Builds the raw (uncapped) task list for every recipe except `help`, which `startTodoScriptTurn`
|
|
168
201
|
* handles itself. `advance` reads `currentTodos` — the only recipe whose result depends on
|
|
169
202
|
* session state — everything else is a pure `todo-script.ts` builder. */
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import type { AgentStreamEvent } from "@av-pi-studio/protocol";
|
|
2
|
+
/**
|
|
3
|
+
* Scripted tool-call trigger for the mock provider (sprint-058/task-004). Typing a `#tool ...`
|
|
4
|
+
* prompt makes the mock run a shell tool call that streams ephemeral `partial: true` snapshots, so
|
|
5
|
+
* the whole live-tool-output path (broadcast without `seq`, no timeline append, no history replay,
|
|
6
|
+
* client live tail) is exercisable with no Pi and no credentials. Mirrors `#ui` / `#todo`
|
|
7
|
+
* (`ui-script.ts`, `todo-script.ts`): a pure, cheap-prefix-checked parser, a `help` recipe, and
|
|
8
|
+
* recognised-but-unknown input falling back to help rather than an ordinary echo.
|
|
9
|
+
*
|
|
10
|
+
* Grammar (also echoed verbatim by `#tool help`):
|
|
11
|
+
*
|
|
12
|
+
* #tool shell start row, 3 growing partial snapshots, completed row with the full output
|
|
13
|
+
* #tool empty same, but the completed row carries an EMPTY output (terminal-authority edge)
|
|
14
|
+
* #tool help this list
|
|
15
|
+
*
|
|
16
|
+
* A bare `#tool` runs the `shell` recipe; an unrecognised recipe shows help.
|
|
17
|
+
*/
|
|
18
|
+
export declare const TOOL_SCRIPT_RECIPES: readonly ["shell", "empty", "help"];
|
|
19
|
+
export type ToolScriptRecipe = (typeof TOOL_SCRIPT_RECIPES)[number];
|
|
20
|
+
export declare function getToolScriptHelpText(): string;
|
|
21
|
+
/** Parses a `#tool ...` prompt into the recipe it names. Returns `null` when `prompt` is not a
|
|
22
|
+
* script. A bare `#tool` is the `shell` recipe; an unrecognised recipe returns `"help"`. */
|
|
23
|
+
export declare function parseToolScript(prompt: string): ToolScriptRecipe | null;
|
|
24
|
+
/** The `tool_call` events for a non-`help` recipe, in emission order: start row, 3 partial
|
|
25
|
+
* snapshots whose output ACCUMULATES (each contains all prior text, like bash's replace-semantics
|
|
26
|
+
* snapshots), then the terminal row. */
|
|
27
|
+
export declare function toolScriptEvents(recipe: Exclude<ToolScriptRecipe, "help">, callId: string): AgentStreamEvent[];
|
|
28
|
+
//# sourceMappingURL=tool-script.d.ts.map
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Scripted tool-call trigger for the mock provider (sprint-058/task-004). Typing a `#tool ...`
|
|
3
|
+
* prompt makes the mock run a shell tool call that streams ephemeral `partial: true` snapshots, so
|
|
4
|
+
* the whole live-tool-output path (broadcast without `seq`, no timeline append, no history replay,
|
|
5
|
+
* client live tail) is exercisable with no Pi and no credentials. Mirrors `#ui` / `#todo`
|
|
6
|
+
* (`ui-script.ts`, `todo-script.ts`): a pure, cheap-prefix-checked parser, a `help` recipe, and
|
|
7
|
+
* recognised-but-unknown input falling back to help rather than an ordinary echo.
|
|
8
|
+
*
|
|
9
|
+
* Grammar (also echoed verbatim by `#tool help`):
|
|
10
|
+
*
|
|
11
|
+
* #tool shell start row, 3 growing partial snapshots, completed row with the full output
|
|
12
|
+
* #tool empty same, but the completed row carries an EMPTY output (terminal-authority edge)
|
|
13
|
+
* #tool help this list
|
|
14
|
+
*
|
|
15
|
+
* A bare `#tool` runs the `shell` recipe; an unrecognised recipe shows help.
|
|
16
|
+
*/
|
|
17
|
+
export const TOOL_SCRIPT_RECIPES = ["shell", "empty", "help"];
|
|
18
|
+
const RECIPE_SET = new Set(TOOL_SCRIPT_RECIPES);
|
|
19
|
+
const HELP_TEXT = `#tool script recipes:
|
|
20
|
+
#tool shell a shell tool call streaming 3 growing output snapshots, then completing
|
|
21
|
+
#tool empty the same, but the completed call carries an empty final output
|
|
22
|
+
#tool help this list`;
|
|
23
|
+
export function getToolScriptHelpText() {
|
|
24
|
+
return HELP_TEXT;
|
|
25
|
+
}
|
|
26
|
+
/** Parses a `#tool ...` prompt into the recipe it names. Returns `null` when `prompt` is not a
|
|
27
|
+
* script. A bare `#tool` is the `shell` recipe; an unrecognised recipe returns `"help"`. */
|
|
28
|
+
export function parseToolScript(prompt) {
|
|
29
|
+
const trimmed = prompt.trim();
|
|
30
|
+
if (!/^#tool(\s|$)/i.test(trimmed))
|
|
31
|
+
return null;
|
|
32
|
+
const rest = trimmed.slice("#tool".length).trim();
|
|
33
|
+
if (rest === "")
|
|
34
|
+
return "shell";
|
|
35
|
+
return RECIPE_SET.has(rest) ? rest : "help";
|
|
36
|
+
}
|
|
37
|
+
const SHELL_COMMAND = "npm test";
|
|
38
|
+
const OUTPUT_LINES = ["> running suite A", "> running suite B", "> running suite C"];
|
|
39
|
+
/** The `tool_call` events for a non-`help` recipe, in emission order: start row, 3 partial
|
|
40
|
+
* snapshots whose output ACCUMULATES (each contains all prior text, like bash's replace-semantics
|
|
41
|
+
* snapshots), then the terminal row. */
|
|
42
|
+
export function toolScriptEvents(recipe, callId) {
|
|
43
|
+
const events = [
|
|
44
|
+
{
|
|
45
|
+
kind: "tool_call",
|
|
46
|
+
callId,
|
|
47
|
+
status: "running",
|
|
48
|
+
tool: { kind: "shell", command: SHELL_COMMAND },
|
|
49
|
+
},
|
|
50
|
+
];
|
|
51
|
+
for (let i = 1; i <= OUTPUT_LINES.length; i++) {
|
|
52
|
+
events.push({
|
|
53
|
+
kind: "tool_call",
|
|
54
|
+
callId,
|
|
55
|
+
status: "running",
|
|
56
|
+
partial: true,
|
|
57
|
+
tool: { kind: "shell", command: SHELL_COMMAND, output: OUTPUT_LINES.slice(0, i).join("\n") },
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
events.push({
|
|
61
|
+
kind: "tool_call",
|
|
62
|
+
callId,
|
|
63
|
+
status: "completed",
|
|
64
|
+
tool: {
|
|
65
|
+
kind: "shell",
|
|
66
|
+
command: SHELL_COMMAND,
|
|
67
|
+
output: recipe === "empty" ? "" : `${OUTPUT_LINES.join("\n")}\nall passed`,
|
|
68
|
+
},
|
|
69
|
+
});
|
|
70
|
+
return events;
|
|
71
|
+
}
|
|
72
|
+
//# sourceMappingURL=tool-script.js.map
|
|
@@ -6,6 +6,7 @@ import { createProcessTransport, defaultPiCommand, resolveBinaryOnPath, } from "
|
|
|
6
6
|
import { hydrateTimelineFromSessionFile, readTodosFromSessionFile } from "./session-hydration.js";
|
|
7
7
|
import { deriveThinkingLevels } from "./thinking-levels.js";
|
|
8
8
|
import { toAgentTodos, todoDetailsFromFrame } from "./todos.js";
|
|
9
|
+
import { createToolOutputCoalescer } from "./tool-output-coalescer.js";
|
|
9
10
|
/**
|
|
10
11
|
* Pi provider adapter (features/agent-providers.md § Pi lifecycle / § Models·modes·features /
|
|
11
12
|
* § Import & resume). Spawns `pi --mode rpc` (or a configured `command`), maps RPC events to
|
|
@@ -118,6 +119,10 @@ class PiAgentSession {
|
|
|
118
119
|
todoSubscribers = new Set();
|
|
119
120
|
history = [];
|
|
120
121
|
eventMapper = createPiEventMapper();
|
|
122
|
+
/** Owns ephemeral `partial: true` tool output: throttled, tail-capped, kept out of `history`. */
|
|
123
|
+
partialOutput = createToolOutputCoalescer({
|
|
124
|
+
deliver: (event) => this.fanOut(event),
|
|
125
|
+
});
|
|
121
126
|
modes = [];
|
|
122
127
|
mode;
|
|
123
128
|
model;
|
|
@@ -156,7 +161,16 @@ class PiAgentSession {
|
|
|
156
161
|
});
|
|
157
162
|
}
|
|
158
163
|
emit(event) {
|
|
164
|
+
// Partials are live-stream-only (features/tool-output-streaming.md): the coalescer delivers
|
|
165
|
+
// them to subscribers itself, so they never reach `history` and its replay. Every other event
|
|
166
|
+
// keeps the record-then-fan-out path; the coalescer has already cancelled any partial
|
|
167
|
+
// flush it supersedes (a call's terminal, a turn terminal), so no partial outruns it.
|
|
168
|
+
if (this.partialOutput.accept(event))
|
|
169
|
+
return;
|
|
159
170
|
this.history.push(event);
|
|
171
|
+
this.fanOut(event);
|
|
172
|
+
}
|
|
173
|
+
fanOut(event) {
|
|
160
174
|
for (const cb of this.subscribers)
|
|
161
175
|
cb(event);
|
|
162
176
|
}
|
|
@@ -505,6 +519,7 @@ class PiAgentSession {
|
|
|
505
519
|
}));
|
|
506
520
|
}
|
|
507
521
|
close() {
|
|
522
|
+
this.partialOutput.cancelAll();
|
|
508
523
|
this.subscribers.clear();
|
|
509
524
|
return this.transport.close();
|
|
510
525
|
}
|
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
import type { AgentStreamEvent, ToolCallDetail } from "@av-pi-studio/protocol";
|
|
2
2
|
/**
|
|
3
|
-
* Map a Pi tool-call payload to a normalized `ToolCallDetail`. Accepts
|
|
4
|
-
* `tool_execution_start`-shaped record (`toolName` + `args`)
|
|
5
|
-
* (`toolName` + `
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
3
|
+
* Map a Pi tool-call payload to a normalized `ToolCallDetail`. Accepts a
|
|
4
|
+
* `tool_execution_start`-shaped record (`toolName` + `args`), a `tool_execution_update`-shaped one
|
|
5
|
+
* (`toolName` + `args` + `partialResult`) or a `tool_execution_end`-shaped one (`toolName` +
|
|
6
|
+
* `result`, no `args`). For `edit`, the human-readable unified `patch` is only present on the
|
|
7
|
+
* *end* event under `result.details.patch`, so it is pulled from there when args carry no diff.
|
|
8
|
+
* `output` (tool stdout/result text) follows the event: absent on `start` events (no `result` or
|
|
9
|
+
* `partialResult` yet, so `outputOf` yields `undefined` — correct), the output *so far* on
|
|
10
|
+
* `update` events (`partialResult`), and the final output on `end` events (`result`).
|
|
9
11
|
*/
|
|
10
12
|
export declare function mapToolCall(raw: unknown): ToolCallDetail;
|
|
11
13
|
export interface PiEventMapper {
|
|
@@ -16,7 +18,8 @@ export interface PiEventMapper {
|
|
|
16
18
|
* Stateful Pi event mapper (features/agent-sessions.md § Stream events).
|
|
17
19
|
*
|
|
18
20
|
* Real Pi RPC events (docs/rpc.md): `agent_start`/`agent_end`, `turn_start`/`turn_end`,
|
|
19
|
-
* `message_update` (carrying an `assistantMessageEvent` delta), `tool_execution_start|end`,
|
|
21
|
+
* `message_update` (carrying an `assistantMessageEvent` delta), `tool_execution_start|update|end`,
|
|
22
|
+
* etc.
|
|
20
23
|
*
|
|
21
24
|
* Pi's session run loop emits ONE `agent_end` **per low-level run** — a retryable error,
|
|
22
25
|
* overflow-compaction, or a queued steering/follow-up message all loop into another run before
|
|
@@ -30,11 +33,11 @@ export declare function createPiEventMapper(): PiEventMapper;
|
|
|
30
33
|
/**
|
|
31
34
|
* Stateless convenience wrapper — maps a single event through a **fresh** mapper instance. Fine
|
|
32
35
|
* for one-off/unit assertions of turn-agnostic events (`agent_start`, `message_update`,
|
|
33
|
-
* `tool_execution_start|end`, `queue_update`, unknown types). It cannot report a turn's
|
|
34
|
-
* event on its own: since disposition is latched from a *prior* `agent_end` in the same
|
|
35
|
-
* a lone `agent_end`/`agent_settled` call here always sees fresh (`"completed"`) state.
|
|
36
|
-
* observing a full turn lifecycle (e.g. `PiAgentSession`) MUST use `createPiEventMapper()`
|
|
37
|
-
* reuse one instance for the session's lifetime.
|
|
36
|
+
* `tool_execution_start|update|end`, `queue_update`, unknown types). It cannot report a turn's
|
|
37
|
+
* terminal event on its own: since disposition is latched from a *prior* `agent_end` in the same
|
|
38
|
+
* session, a lone `agent_end`/`agent_settled` call here always sees fresh (`"completed"`) state.
|
|
39
|
+
* Callers observing a full turn lifecycle (e.g. `PiAgentSession`) MUST use `createPiEventMapper()`
|
|
40
|
+
* and reuse one instance for the session's lifetime.
|
|
38
41
|
*/
|
|
39
42
|
export declare function mapPiEvent(raw: unknown): AgentStreamEvent | null;
|
|
40
43
|
//# sourceMappingURL=event-mapper.d.ts.map
|
|
@@ -11,9 +11,14 @@ function str(value) {
|
|
|
11
11
|
return typeof value === "string" ? value : undefined;
|
|
12
12
|
}
|
|
13
13
|
const COMPACTION_REASONS = ["manual", "threshold", "overflow"];
|
|
14
|
-
/**
|
|
14
|
+
/**
|
|
15
|
+
* Join a tool payload's content text blocks into one string. Pi reports a tool's text under two
|
|
16
|
+
* keys depending on the event: `result.content` on `tool_execution_end`, and
|
|
17
|
+
* `partialResult.content` on `tool_execution_update` (update events carry no `result`; Pi
|
|
18
|
+
* `docs/json.md` § tool events). One reader for both — `result` wins when present.
|
|
19
|
+
*/
|
|
15
20
|
function outputOf(tool) {
|
|
16
|
-
const content = asRecord(tool.result).content;
|
|
21
|
+
const content = asRecord(tool.result).content ?? asRecord(tool.partialResult).content;
|
|
17
22
|
if (!Array.isArray(content))
|
|
18
23
|
return undefined;
|
|
19
24
|
const text = content
|
|
@@ -23,12 +28,14 @@ function outputOf(tool) {
|
|
|
23
28
|
return text || undefined;
|
|
24
29
|
}
|
|
25
30
|
/**
|
|
26
|
-
* Map a Pi tool-call payload to a normalized `ToolCallDetail`. Accepts
|
|
27
|
-
* `tool_execution_start`-shaped record (`toolName` + `args`)
|
|
28
|
-
* (`toolName` + `
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
31
|
+
* Map a Pi tool-call payload to a normalized `ToolCallDetail`. Accepts a
|
|
32
|
+
* `tool_execution_start`-shaped record (`toolName` + `args`), a `tool_execution_update`-shaped one
|
|
33
|
+
* (`toolName` + `args` + `partialResult`) or a `tool_execution_end`-shaped one (`toolName` +
|
|
34
|
+
* `result`, no `args`). For `edit`, the human-readable unified `patch` is only present on the
|
|
35
|
+
* *end* event under `result.details.patch`, so it is pulled from there when args carry no diff.
|
|
36
|
+
* `output` (tool stdout/result text) follows the event: absent on `start` events (no `result` or
|
|
37
|
+
* `partialResult` yet, so `outputOf` yields `undefined` — correct), the output *so far* on
|
|
38
|
+
* `update` events (`partialResult`), and the final output on `end` events (`result`).
|
|
32
39
|
*/
|
|
33
40
|
export function mapToolCall(raw) {
|
|
34
41
|
const tool = asRecord(raw);
|
|
@@ -83,7 +90,8 @@ export function mapToolCall(raw) {
|
|
|
83
90
|
* Stateful Pi event mapper (features/agent-sessions.md § Stream events).
|
|
84
91
|
*
|
|
85
92
|
* Real Pi RPC events (docs/rpc.md): `agent_start`/`agent_end`, `turn_start`/`turn_end`,
|
|
86
|
-
* `message_update` (carrying an `assistantMessageEvent` delta), `tool_execution_start|end`,
|
|
93
|
+
* `message_update` (carrying an `assistantMessageEvent` delta), `tool_execution_start|update|end`,
|
|
94
|
+
* etc.
|
|
87
95
|
*
|
|
88
96
|
* Pi's session run loop emits ONE `agent_end` **per low-level run** — a retryable error,
|
|
89
97
|
* overflow-compaction, or a queued steering/follow-up message all loop into another run before
|
|
@@ -198,6 +206,17 @@ export function createPiEventMapper() {
|
|
|
198
206
|
tool: mapToolCall(event),
|
|
199
207
|
status: "running",
|
|
200
208
|
};
|
|
209
|
+
// In-flight output snapshot. Ephemeral (`partial: true`): the mapper stays stateless and
|
|
210
|
+
// forwards exactly the text Pi sent — never concatenating successive updates; rate control
|
|
211
|
+
// and ordering against the terminal event live in `PiAgentSession` (tool-output-coalescer).
|
|
212
|
+
case "tool_execution_update":
|
|
213
|
+
return {
|
|
214
|
+
kind: "tool_call",
|
|
215
|
+
callId: str(event.toolCallId),
|
|
216
|
+
tool: mapToolCall(event),
|
|
217
|
+
status: "running",
|
|
218
|
+
partial: true,
|
|
219
|
+
};
|
|
201
220
|
case "tool_execution_end":
|
|
202
221
|
return {
|
|
203
222
|
kind: "tool_call",
|
|
@@ -277,7 +296,6 @@ export function createPiEventMapper() {
|
|
|
277
296
|
case "turn_end":
|
|
278
297
|
case "message_start":
|
|
279
298
|
case "message_end":
|
|
280
|
-
case "tool_execution_update":
|
|
281
299
|
case "auto_retry_start":
|
|
282
300
|
case "auto_retry_end":
|
|
283
301
|
return null;
|
|
@@ -290,11 +308,11 @@ export function createPiEventMapper() {
|
|
|
290
308
|
/**
|
|
291
309
|
* Stateless convenience wrapper — maps a single event through a **fresh** mapper instance. Fine
|
|
292
310
|
* for one-off/unit assertions of turn-agnostic events (`agent_start`, `message_update`,
|
|
293
|
-
* `tool_execution_start|end`, `queue_update`, unknown types). It cannot report a turn's
|
|
294
|
-
* event on its own: since disposition is latched from a *prior* `agent_end` in the same
|
|
295
|
-
* a lone `agent_end`/`agent_settled` call here always sees fresh (`"completed"`) state.
|
|
296
|
-
* observing a full turn lifecycle (e.g. `PiAgentSession`) MUST use `createPiEventMapper()`
|
|
297
|
-
* reuse one instance for the session's lifetime.
|
|
311
|
+
* `tool_execution_start|update|end`, `queue_update`, unknown types). It cannot report a turn's
|
|
312
|
+
* terminal event on its own: since disposition is latched from a *prior* `agent_end` in the same
|
|
313
|
+
* session, a lone `agent_end`/`agent_settled` call here always sees fresh (`"completed"`) state.
|
|
314
|
+
* Callers observing a full turn lifecycle (e.g. `PiAgentSession`) MUST use `createPiEventMapper()`
|
|
315
|
+
* and reuse one instance for the session's lifetime.
|
|
298
316
|
*/
|
|
299
317
|
export function mapPiEvent(raw) {
|
|
300
318
|
return createPiEventMapper().map(raw);
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { AgentStreamEvent } from "@av-pi-studio/protocol";
|
|
2
|
+
/**
|
|
3
|
+
* Per-`callId` rate and size control for ephemeral partial tool output
|
|
4
|
+
* (features/tool-output-streaming.md § Server — per-callId coalescer).
|
|
5
|
+
*
|
|
6
|
+
* `PiAgentSession` routes every mapped event through `accept`. A `partial: true` `tool_call` is
|
|
7
|
+
* owned by the coalescer from then on: it is delivered to subscribers (never recorded in the
|
|
8
|
+
* session's replay history) on a leading + trailing edge at most every `PARTIAL_MIN_INTERVAL_MS`
|
|
9
|
+
* per call, latest snapshot winning, with its output tail-capped. Any other event is handed back
|
|
10
|
+
* unchanged for the caller's normal record-and-fan-out path, after the coalescer has dropped the
|
|
11
|
+
* state it supersedes:
|
|
12
|
+
*
|
|
13
|
+
* - a non-partial `tool_call` (start, `"started"`, `completed`/`error`) cancels that call's
|
|
14
|
+
* pending flush and snapshot — a trailing flush firing after the terminal would regress the
|
|
15
|
+
* card from `completed` back to `running`;
|
|
16
|
+
* - a turn terminal (`turn_completed`/`turn_failed`/`turn_canceled`) cancels every pending flush,
|
|
17
|
+
* so nothing escapes after a turn ends or is aborted (`cancelAll` covers session close).
|
|
18
|
+
*
|
|
19
|
+
* Dropping intermediate snapshots is lossless for snapshot-style tools (bash sends accumulated
|
|
20
|
+
* output); a delta-style tool would show its latest chunk — a documented degradation, not
|
|
21
|
+
* reconciled here.
|
|
22
|
+
*
|
|
23
|
+
* The cap is measured in UTF-8 bytes (`Buffer.byteLength`) — the unit that bounds the wire frame —
|
|
24
|
+
* and cut on a code-point boundary. Only partial snapshots are capped; a terminal event's output
|
|
25
|
+
* is authoritative and passes through untouched.
|
|
26
|
+
*
|
|
27
|
+
* Clock and timers are injectable so tests assert timing without real waiting; the defaults read
|
|
28
|
+
* the globals at call time so fake timers installed later are honoured.
|
|
29
|
+
*/
|
|
30
|
+
/** Minimum spacing between emitted partials of one call (≤5 broadcasts/s per tool call). */
|
|
31
|
+
export declare const PARTIAL_MIN_INTERVAL_MS = 200;
|
|
32
|
+
/** Largest tail (UTF-8 bytes) of a snapshot put on the wire; bounds relay frame size. */
|
|
33
|
+
export declare const PARTIAL_OUTPUT_CAP_BYTES = 65536;
|
|
34
|
+
/** Cancels a callback scheduled through {@link ToolOutputCoalescerOptions.schedule}. */
|
|
35
|
+
export type CancelTimer = () => void;
|
|
36
|
+
export interface ToolOutputCoalescerOptions {
|
|
37
|
+
/** Receives each partial that survives throttling, tail-capped: synchronously on the leading
|
|
38
|
+
* edge, from a timer on the trailing edge. */
|
|
39
|
+
deliver: (event: AgentStreamEvent) => void;
|
|
40
|
+
/** Epoch milliseconds; defaults to `Date.now`. */
|
|
41
|
+
now?: () => number;
|
|
42
|
+
/** Runs `callback` after `delayMs` and returns its canceller; defaults to an unref'd
|
|
43
|
+
* `setTimeout`. */
|
|
44
|
+
schedule?: (callback: () => void, delayMs: number) => CancelTimer;
|
|
45
|
+
}
|
|
46
|
+
export interface ToolOutputCoalescer {
|
|
47
|
+
/**
|
|
48
|
+
* Route one mapped event. Returns `true` when `event` is a partial the coalescer took over
|
|
49
|
+
* (delivered now or later through `deliver`; the caller must neither record nor emit it) and
|
|
50
|
+
* `false` for every other event, which the caller records and emits as usual — superseded
|
|
51
|
+
* pending partials have already been cancelled.
|
|
52
|
+
*/
|
|
53
|
+
accept(event: AgentStreamEvent): boolean;
|
|
54
|
+
/** Cancel every pending flush and forget all per-call state (turn terminal, session close). */
|
|
55
|
+
cancelAll(): void;
|
|
56
|
+
}
|
|
57
|
+
export declare function createToolOutputCoalescer(options: ToolOutputCoalescerOptions): ToolOutputCoalescer;
|
|
58
|
+
//# sourceMappingURL=tool-output-coalescer.d.ts.map
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-`callId` rate and size control for ephemeral partial tool output
|
|
3
|
+
* (features/tool-output-streaming.md § Server — per-callId coalescer).
|
|
4
|
+
*
|
|
5
|
+
* `PiAgentSession` routes every mapped event through `accept`. A `partial: true` `tool_call` is
|
|
6
|
+
* owned by the coalescer from then on: it is delivered to subscribers (never recorded in the
|
|
7
|
+
* session's replay history) on a leading + trailing edge at most every `PARTIAL_MIN_INTERVAL_MS`
|
|
8
|
+
* per call, latest snapshot winning, with its output tail-capped. Any other event is handed back
|
|
9
|
+
* unchanged for the caller's normal record-and-fan-out path, after the coalescer has dropped the
|
|
10
|
+
* state it supersedes:
|
|
11
|
+
*
|
|
12
|
+
* - a non-partial `tool_call` (start, `"started"`, `completed`/`error`) cancels that call's
|
|
13
|
+
* pending flush and snapshot — a trailing flush firing after the terminal would regress the
|
|
14
|
+
* card from `completed` back to `running`;
|
|
15
|
+
* - a turn terminal (`turn_completed`/`turn_failed`/`turn_canceled`) cancels every pending flush,
|
|
16
|
+
* so nothing escapes after a turn ends or is aborted (`cancelAll` covers session close).
|
|
17
|
+
*
|
|
18
|
+
* Dropping intermediate snapshots is lossless for snapshot-style tools (bash sends accumulated
|
|
19
|
+
* output); a delta-style tool would show its latest chunk — a documented degradation, not
|
|
20
|
+
* reconciled here.
|
|
21
|
+
*
|
|
22
|
+
* The cap is measured in UTF-8 bytes (`Buffer.byteLength`) — the unit that bounds the wire frame —
|
|
23
|
+
* and cut on a code-point boundary. Only partial snapshots are capped; a terminal event's output
|
|
24
|
+
* is authoritative and passes through untouched.
|
|
25
|
+
*
|
|
26
|
+
* Clock and timers are injectable so tests assert timing without real waiting; the defaults read
|
|
27
|
+
* the globals at call time so fake timers installed later are honoured.
|
|
28
|
+
*/
|
|
29
|
+
/** Minimum spacing between emitted partials of one call (≤5 broadcasts/s per tool call). */
|
|
30
|
+
export const PARTIAL_MIN_INTERVAL_MS = 200;
|
|
31
|
+
/** Largest tail (UTF-8 bytes) of a snapshot put on the wire; bounds relay frame size. */
|
|
32
|
+
export const PARTIAL_OUTPUT_CAP_BYTES = 65536;
|
|
33
|
+
/** One shared bucket for events without a `callId`; partial and terminal must agree on the key. */
|
|
34
|
+
function callKey(event) {
|
|
35
|
+
return event.callId ?? "";
|
|
36
|
+
}
|
|
37
|
+
/** The last `maxBytes` UTF-8 bytes of `text`, starting on a code-point boundary. */
|
|
38
|
+
function tailWithinBytes(text, maxBytes) {
|
|
39
|
+
// UTF-8 spends at most 3 bytes per UTF-16 code unit, so a short string cannot exceed the cap.
|
|
40
|
+
if (text.length * 3 <= maxBytes || Buffer.byteLength(text, "utf8") <= maxBytes)
|
|
41
|
+
return text;
|
|
42
|
+
const bytes = Buffer.from(text, "utf8");
|
|
43
|
+
let start = bytes.length - maxBytes;
|
|
44
|
+
// Skip UTF-8 continuation bytes (0b10xxxxxx) so the cut never splits a character.
|
|
45
|
+
while (start < bytes.length && (bytes.readUInt8(start) & 0xc0) === 0x80)
|
|
46
|
+
start++;
|
|
47
|
+
return bytes.toString("utf8", start);
|
|
48
|
+
}
|
|
49
|
+
function withTailCap(event) {
|
|
50
|
+
const output = event.tool.output;
|
|
51
|
+
if (output === undefined)
|
|
52
|
+
return event;
|
|
53
|
+
const tail = tailWithinBytes(output, PARTIAL_OUTPUT_CAP_BYTES);
|
|
54
|
+
return tail === output ? event : { ...event, tool: { ...event.tool, output: tail } };
|
|
55
|
+
}
|
|
56
|
+
function scheduleTimeout(callback, delayMs) {
|
|
57
|
+
const handle = setTimeout(callback, delayMs);
|
|
58
|
+
// A pending flush must never keep the daemon alive.
|
|
59
|
+
handle.unref();
|
|
60
|
+
return () => clearTimeout(handle);
|
|
61
|
+
}
|
|
62
|
+
export function createToolOutputCoalescer(options) {
|
|
63
|
+
const { deliver } = options;
|
|
64
|
+
const now = options.now ?? (() => Date.now());
|
|
65
|
+
const schedule = options.schedule ?? scheduleTimeout;
|
|
66
|
+
const calls = new Map();
|
|
67
|
+
const flush = (state) => {
|
|
68
|
+
const event = state.pending;
|
|
69
|
+
state.pending = undefined;
|
|
70
|
+
state.cancelFlush = undefined;
|
|
71
|
+
if (!event)
|
|
72
|
+
return;
|
|
73
|
+
state.lastEmit = now();
|
|
74
|
+
deliver(withTailCap(event));
|
|
75
|
+
};
|
|
76
|
+
const offerPartial = (event) => {
|
|
77
|
+
const key = callKey(event);
|
|
78
|
+
const at = now();
|
|
79
|
+
const state = calls.get(key);
|
|
80
|
+
if (state && at - state.lastEmit < PARTIAL_MIN_INTERVAL_MS) {
|
|
81
|
+
// Too soon: the latest snapshot supersedes any pending one; one flush per call is enough.
|
|
82
|
+
state.pending = event;
|
|
83
|
+
state.cancelFlush ??= schedule(() => flush(state), state.lastEmit + PARTIAL_MIN_INTERVAL_MS - at);
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
// Leading edge. A flush may still be pending if its timer is running late — this snapshot is
|
|
87
|
+
// newer than the pending one, so retire the flush instead of letting it deliver a stale one.
|
|
88
|
+
state?.cancelFlush?.();
|
|
89
|
+
calls.set(key, { lastEmit: at });
|
|
90
|
+
deliver(withTailCap(event));
|
|
91
|
+
};
|
|
92
|
+
const cancelAll = () => {
|
|
93
|
+
for (const state of calls.values())
|
|
94
|
+
state.cancelFlush?.();
|
|
95
|
+
calls.clear();
|
|
96
|
+
};
|
|
97
|
+
return {
|
|
98
|
+
accept(event) {
|
|
99
|
+
if (event.kind === "tool_call") {
|
|
100
|
+
if (event.partial) {
|
|
101
|
+
offerPartial(event);
|
|
102
|
+
return true;
|
|
103
|
+
}
|
|
104
|
+
// Start, `"started"` or terminal: this call's partials are over — nothing pending may
|
|
105
|
+
// outlive the event about to be emitted.
|
|
106
|
+
const key = callKey(event);
|
|
107
|
+
calls.get(key)?.cancelFlush?.();
|
|
108
|
+
calls.delete(key);
|
|
109
|
+
return false;
|
|
110
|
+
}
|
|
111
|
+
if (event.kind === "turn_completed" ||
|
|
112
|
+
event.kind === "turn_failed" ||
|
|
113
|
+
event.kind === "turn_canceled") {
|
|
114
|
+
cancelAll();
|
|
115
|
+
}
|
|
116
|
+
return false;
|
|
117
|
+
},
|
|
118
|
+
cancelAll,
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
//# sourceMappingURL=tool-output-coalescer.js.map
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@av-pi-studio/server",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.115",
|
|
4
4
|
"bin": {
|
|
5
5
|
"pi-studio-daemon": "dist/daemon/main.js"
|
|
6
6
|
},
|
|
@@ -24,8 +24,8 @@
|
|
|
24
24
|
"clean": "rm -rf dist *.tsbuildinfo"
|
|
25
25
|
},
|
|
26
26
|
"dependencies": {
|
|
27
|
-
"@av-pi-studio/protocol": "^0.0.
|
|
28
|
-
"@av-pi-studio/relay": "^0.0.
|
|
27
|
+
"@av-pi-studio/protocol": "^0.0.115",
|
|
28
|
+
"@av-pi-studio/relay": "^0.0.115",
|
|
29
29
|
"@earendil-works/pi-coding-agent": "^1.4.0",
|
|
30
30
|
"@xterm/addon-serialize": "^0.14.0",
|
|
31
31
|
"@xterm/headless": "^6.0.0",
|