@av-pi-studio/server 0.0.114 → 0.0.116

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 (58) hide show
  1. package/README.md +8 -8
  2. package/dist/agent/agent-service.d.ts +5 -0
  3. package/dist/agent/agent-service.js +12 -0
  4. package/dist/agent/index.d.ts +0 -1
  5. package/dist/agent/index.js +0 -1
  6. package/dist/agent/mcp-server.d.ts +3 -13
  7. package/dist/agent/mcp-server.js +2 -10
  8. package/dist/agent/provider-contract.d.ts +0 -7
  9. package/dist/agent/providers/mock/mock-provider.d.ts +16 -3
  10. package/dist/agent/providers/mock/mock-provider.js +80 -8
  11. package/dist/agent/providers/mock/stream-script.d.ts +28 -0
  12. package/dist/agent/providers/mock/stream-script.js +57 -0
  13. package/dist/agent/providers/mock/tool-script.d.ts +28 -0
  14. package/dist/agent/providers/mock/tool-script.js +72 -0
  15. package/dist/agent/providers/pi/agent.js +15 -7
  16. package/dist/agent/providers/pi/event-mapper.d.ts +15 -12
  17. package/dist/agent/providers/pi/event-mapper.js +33 -15
  18. package/dist/agent/providers/pi/tool-output-coalescer.d.ts +58 -0
  19. package/dist/agent/providers/pi/tool-output-coalescer.js +121 -0
  20. package/dist/daemon/bootstrap.d.ts +18 -2
  21. package/dist/daemon/bootstrap.js +63 -13
  22. package/dist/daemon/dev-bootstrap.d.ts +7 -0
  23. package/dist/daemon/dev-bootstrap.js +34 -5
  24. package/dist/daemon/dev-main.js +5 -2
  25. package/dist/daemon/loopback.d.ts +4 -0
  26. package/dist/daemon/loopback.js +12 -0
  27. package/dist/daemon/main.js +4 -10
  28. package/dist/extensions/curated-packs.d.ts +0 -1
  29. package/dist/extensions/curated-packs.js +1 -6
  30. package/dist/extensions/sync-executor.js +1 -1
  31. package/dist/logging/index.d.ts +1 -0
  32. package/dist/logging/index.js +1 -0
  33. package/dist/logging/log-tap.d.ts +33 -0
  34. package/dist/logging/log-tap.js +233 -0
  35. package/dist/logging/logger.d.ts +6 -0
  36. package/dist/logging/logger.js +4 -0
  37. package/dist/observability/daemon-logs-rpc.d.ts +12 -0
  38. package/dist/observability/daemon-logs-rpc.js +17 -0
  39. package/dist/observability/daemon-logs-service.d.ts +67 -0
  40. package/dist/observability/daemon-logs-service.js +165 -0
  41. package/dist/observability/daemon-status-rpc.d.ts +12 -0
  42. package/dist/observability/daemon-status-rpc.js +21 -0
  43. package/dist/observability/daemon-status-service.d.ts +85 -0
  44. package/dist/observability/daemon-status-service.js +154 -0
  45. package/dist/test-support/auth-gated-rpc.d.ts +18 -0
  46. package/dist/test-support/auth-gated-rpc.js +80 -0
  47. package/dist/test-support/daemon-test-client.d.ts +43 -0
  48. package/dist/test-support/daemon-test-client.js +91 -0
  49. package/dist/test-support/external-fixtures-scenario.d.ts +30 -0
  50. package/dist/test-support/external-fixtures-scenario.js +223 -0
  51. package/dist/version.d.ts +2 -0
  52. package/dist/version.js +7 -0
  53. package/dist/ws/session.d.ts +11 -0
  54. package/dist/ws/session.js +11 -0
  55. package/dist/ws/ws-server.js +2 -0
  56. package/package.json +3 -3
  57. package/dist/agent/permissions.d.ts +0 -71
  58. package/dist/agent/permissions.js +0 -132
package/README.md CHANGED
@@ -97,7 +97,7 @@ node packages/server/dist/daemon/main.js
97
97
  On startup the daemon prints its identity and readiness:
98
98
 
99
99
  ```
100
- pi-studio daemon listening on http://0.0.0.0:6767
100
+ pi-studio daemon listening on http://127.0.0.1:6767
101
101
  serverId: 3f2a…
102
102
  home: /home/you/.pi-studio
103
103
  provider: pi
@@ -107,7 +107,8 @@ pi-studio daemon listening on http://0.0.0.0:6767
107
107
 
108
108
  By default the daemon:
109
109
 
110
- - listens on **`0.0.0.0:6767`** (override with `PI_STUDIO_LISTEN`) — reachable over the LAN
110
+ - listens on **`127.0.0.1:6767`** (loopback only). Override with `PI_STUDIO_LISTEN` or `config.json` `daemon.listen` (env wins); for LAN access use `0.0.0.0:6767` **together with `PI_STUDIO_PASSWORD`** — an unprotected non-loopback bind logs a warning
111
+ - (**Upgrade note:** earlier builds bound `0.0.0.0` by default. To keep LAN access set `PI_STUDIO_LISTEN=0.0.0.0:6767` or `daemon.listen`, together with `PI_STUDIO_PASSWORD`.)
111
112
  - stores all state under **`$PI_STUDIO_HOME`** (default **`~/.pi-studio`**)
112
113
  - writes logs to **`$PI_STUDIO_HOME/logs/`**
113
114
  - uses the **`pi`** provider
@@ -129,7 +130,7 @@ curl http://127.0.0.1:6767/api/health
129
130
  `src/daemon/dev-main.ts` is a development entry that wires only a **minimal handler subset**
130
131
  (`dev-bootstrap.ts`: agent list/archive/delete, workspaces/projects listing, providers, file
131
132
  read/diff, schedule listing — no terminals, git ops, worktrees, chat, loops, or relay), the mock
132
- provider, and in-memory state, and binds `0.0.0.0` with developer-friendly defaults. From the root:
133
+ provider, and in-memory state, and binds `127.0.0.1:6767` (override with `PI_STUDIO_LISTEN`; non-loopback logs a no-auth warning) with developer-friendly defaults. From the root:
133
134
 
134
135
  ```bash
135
136
  npm run dev:daemon
@@ -171,7 +172,7 @@ All optional.
171
172
  | Variable | Default | Purpose |
172
173
  |----------|---------|---------|
173
174
  | `PI_STUDIO_HOME` | `~/.pi-studio` | State + config + logs directory |
174
- | `PI_STUDIO_LISTEN` | `0.0.0.0:6767` | Daemon listen address (`host:port`) |
175
+ | `PI_STUDIO_LISTEN` | `127.0.0.1:6767` | Daemon listen address (`host:port`); falls back to `config.json` `daemon.listen`, then the default |
175
176
  | `PI_STUDIO_PASSWORD` | _(unset)_ | Require this password for connections (bcrypt-checked) |
176
177
  | `PI_STUDIO_HOSTNAMES` | `localhost,*.localhost` | Allowed `Host` header values (comma-separated, or `true` to allow all) |
177
178
  | `PI_STUDIO_SERVER_ID` | _(persisted/generated)_ | Stable server identity |
@@ -185,7 +186,7 @@ All optional.
185
186
  | `PI_STUDIO_SERVICE_PROXY_ENABLED` | _(unset)_ | Enable the service proxy (`1`/`true`/`yes`/`on`) |
186
187
  | `PI_STUDIO_APP_BASE_URL` | `https://app.molagent.ai` | Pairing link origin (`daemon pair`) — set to your own web-client URL for self-hosted/local pairing |
187
188
 
188
- > Literal IP addresses always pass the Host allowlist, so binding `0.0.0.0` and connecting via the
189
+ > Literal IP addresses always pass the Host allowlist, so binding `0.0.0.0` (opt-in) and connecting via the
189
190
  > server's IP needs no extra config. To reach the daemon by **hostname**, add it to
190
191
  > `PI_STUDIO_HOSTNAMES`.
191
192
 
@@ -266,7 +267,7 @@ All communication rides a **single WebSocket connection** per client.
266
267
  - `rpc_error` — a correlated error response (carries the originating `requestId`).
267
268
 
268
269
  A non-`hello` first frame closes the socket. RPC names follow a dotted convention —
269
- `domain.provider.operation.direction` (e.g. `agent.permission.respond.request`); legacy flat names
270
+ `domain.provider.operation.direction` (e.g. `checkout.github.set_auto_merge.request`); legacy flat names
270
271
  are accepted via aliases but never generated.
271
272
 
272
273
  ### Binary frames — terminal + file transfer
@@ -370,13 +371,12 @@ src/
370
371
  dev-bootstrap.ts Dev handler wiring (local testing only).
371
372
  orchestration-rpc.ts
372
373
 
373
- agent/ Agent lifecycle, provider registry, timeline, permissions.
374
+ agent/ Agent lifecycle, provider registry, timeline.
374
375
  agent-manager.ts Single source of truth for agent state + FSM + persistence + broadcast.
375
376
  agent-service.ts RPC handler wiring for agent operations.
376
377
  provider-contract.ts AgentClient / AgentSession interfaces (the ONLY provider surface).
377
378
  provider-registry.ts Register/resolve AgentClient by provider id.
378
379
  timeline-store.ts Append/page/cursor the agent event log.
379
- permissions.ts Park + resolve tool-call permission requests.
380
380
  providers/pi/ Real Pi provider (spawn, JSONL transport, event mapper).
381
381
  providers/mock/ In-process synthetic provider.
382
382
 
@@ -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",
@@ -12,7 +12,6 @@ export * from "./agent-service.js";
12
12
  export * from "./timeline-rpc.js";
13
13
  export * from "./session-operations.js";
14
14
  export * from "./slash-command-operations.js";
15
- export * from "./permissions.js";
16
15
  export * from "./structured-generation.js";
17
16
  export * from "./mcp-server.js";
18
17
  //# sourceMappingURL=index.d.ts.map
@@ -13,7 +13,6 @@ export * from "./agent-service.js";
13
13
  export * from "./timeline-rpc.js";
14
14
  export * from "./session-operations.js";
15
15
  export * from "./slash-command-operations.js";
16
- export * from "./permissions.js";
17
16
  export * from "./structured-generation.js";
18
17
  export * from "./mcp-server.js";
19
18
  //# sourceMappingURL=index.js.map
@@ -15,7 +15,6 @@ import type { AgentUiPendingRequest, AgentUiResponse } from "@av-pi-studio/proto
15
15
  * `appendSystemPrompt`, so no agent is ever handed a `--mcp-config`.
16
16
  * Sprint-010/task-001 built this registry and deferred the transport as "a bootstrap step"; that
17
17
  * step was never taken. Consequence: every tool here is dormant — including
18
- * `list_pending_permissions`/`respond_to_permission` (sprint-010) and
19
18
  * `list_pending_ui_requests`/`respond_to_ui_request` (sprint-066/task-005) — and the
20
19
  * agent-to-agent orchestration in `features/subagents.md` has never run.
21
20
  *
@@ -41,7 +40,7 @@ export interface McpToolContext {
41
40
  callerAgentId?: string;
42
41
  }
43
42
  export type McpToolHandler<A> = (args: A, ctx: McpToolContext) => Promise<McpToolResult> | McpToolResult;
44
- /** Backend the orchestration tools route to (AgentManager / permission / provider services). */
43
+ /** Backend the orchestration tools route to (AgentManager / provider services). */
45
44
  export interface McpBackend {
46
45
  /** Create an async child agent. Returns its id. */
47
46
  createAgent(input: {
@@ -74,18 +73,9 @@ export interface McpBackend {
74
73
  cancelAgent?(agentId: string): Promise<void>;
75
74
  killAgent?(agentId: string): Promise<void>;
76
75
  archiveAgent(agentId: string): Promise<void>;
77
- listPendingPermissions(agentId?: string): Array<{
78
- requestId: string;
79
- agentId: string;
80
- toolName?: string;
81
- }>;
82
- respondToPermission(requestId: string, response: unknown): {
83
- resolved: boolean;
84
- };
85
76
  /** Extension UI (features/extension-ui-rpc.md § MCP mirror) — closes the deadlock where an
86
- * orchestrating agent can't answer a child's extension questionnaire. Mirrors the permission
87
- * pair's shape; its own error vocabulary ("unknown_ui_request"/"unsupported") is intentionally
88
- * distinct — see the tool registration below for why. */
77
+ * orchestrating agent can't answer a child's extension questionnaire. Its error vocabulary
78
+ * ("unknown_ui_request"/"unsupported") is documented at the tool registration below. */
89
79
  listPendingUiRequests(agentId?: string): AgentUiPendingRequest[];
90
80
  respondToUiRequest(requestId: string, response: AgentUiResponse): {
91
81
  resolved: boolean;
@@ -17,7 +17,6 @@ import { PARENT_AGENT_ID_LABEL } from "./agent-manager.js";
17
17
  * `appendSystemPrompt`, so no agent is ever handed a `--mcp-config`.
18
18
  * Sprint-010/task-001 built this registry and deferred the transport as "a bootstrap step"; that
19
19
  * step was never taken. Consequence: every tool here is dormant — including
20
- * `list_pending_permissions`/`respond_to_permission` (sprint-010) and
21
20
  * `list_pending_ui_requests`/`respond_to_ui_request` (sprint-066/task-005) — and the
22
21
  * agent-to-agent orchestration in `features/subagents.md` has never run.
23
22
  *
@@ -160,16 +159,9 @@ export class McpServer {
160
159
  await b.archiveAgent(args.agentId);
161
160
  return { ok: true };
162
161
  });
163
- // Permissions.
164
- this.registerTool("list_pending_permissions", z.object({ agentId: z.string().optional() }), (args) => ({ ok: true, permissions: b.listPendingPermissions(args.agentId) }));
165
- this.registerTool("respond_to_permission", z.object({ requestId: z.string(), response: z.unknown() }), (args) => {
166
- const result = b.respondToPermission(args.requestId, args.response);
167
- return result.resolved ? { ok: true } : { ok: false, error: "unknown_permission" };
168
- });
169
162
  // Extension UI (features/extension-ui-rpc.md § MCP mirror). Error vocabulary intentionally
170
- // differs from `respond_to_permission`'s `unknown_permission`/the WS side's `not_found`: a
171
- // `resolved:false` with no `error` (never happens for this backend) and an `unsupported`
172
- // result are distinct outcomes a caller must not conflate with "unknown" — collapsing a live
163
+ // differs from the WS side's `not_found`: a `resolved:false` with no `error` (never happens for
164
+ // this backend) and an `unsupported` result are distinct outcomes a caller must not conflate with "unknown" — collapsing a live
173
165
  // dialog on a provider without `respondToUi` into `unknown_ui_request` would report it as
174
166
  // gone when it is actually still answerable over WS by a human.
175
167
  this.registerTool("list_pending_ui_requests", z.object({ agentId: z.string().optional() }), (args) => ({ ok: true, requests: b.listPendingUiRequests(args.agentId) }));
@@ -121,11 +121,6 @@ export interface ProviderRuntimeInfo {
121
121
  modeId?: string;
122
122
  extra?: Record<string, unknown>;
123
123
  }
124
- export interface PendingPermission {
125
- requestId: string;
126
- toolName?: string;
127
- detail?: unknown;
128
- }
129
124
  /**
130
125
  * One agent's todo list as a provider reports it: already sorted by id and capped to the protocol
131
126
  * limits (`capAgentTodos`), so `truncated` has to travel with the tasks. The service adds the
@@ -213,8 +208,6 @@ export interface AgentSession {
213
208
  getAvailableModes(): AgentModeDefinition[];
214
209
  getCurrentMode(): string | null;
215
210
  setMode(id: string): Promise<void>;
216
- getPendingPermissions(): PendingPermission[];
217
- respondToPermission(requestId: string, response: unknown): Promise<void>;
218
211
  describePersistence(): PersistenceHandle | null;
219
212
  interrupt(): Promise<void>;
220
213
  close(): Promise<void>;
@@ -1,11 +1,14 @@
1
1
  import type { AgentCapabilityFlags, AgentSessionConfig, AgentStreamEvent, AgentTodo } from "@av-pi-studio/protocol";
2
- import type { AgentClient, AgentCommandDefinition, AgentCompactResult, AgentModeDefinition, AgentModelDefinition, AgentSession, AgentTodoList, CreateSessionOptions, LaunchContext, PendingPermission, PersistenceHandle, ProviderRuntimeInfo, ProviderUiRequest, ProviderUiResponse, Unsubscribe } from "../../provider-contract.js";
2
+ import type { AgentClient, AgentCommandDefinition, AgentCompactResult, AgentModeDefinition, AgentModelDefinition, AgentSession, AgentTodoList, CreateSessionOptions, LaunchContext, PersistenceHandle, ProviderRuntimeInfo, ProviderUiRequest, ProviderUiResponse, Unsubscribe } from "../../provider-contract.js";
3
3
  /**
4
4
  * In-process `mock` provider (features/agent-providers.md § Provider entry — dev/test only). It
5
5
  * implements the `AgentClient`/`AgentSession` contracts in memory and emits a scripted turn. Never
6
6
  * user-selectable in production paths.
7
7
  */
8
8
  export declare const MOCK_CAPABILITIES: AgentCapabilityFlags;
9
+ /** `fork` entry id that makes the mock rebind its persistence handle (sprint-083/task-002), so the
10
+ * real `agent_timeline_reset` broadcast path is reachable without a Pi session file. */
11
+ export declare const MOCK_REBIND_ENTRY_ID = "mock-rebind";
9
12
  export interface MockSessionOptions {
10
13
  /** Delay before a started turn completes (ms). Small but non-zero so `interrupt` can win. */
11
14
  turnDelayMs?: number;
@@ -67,6 +70,14 @@ export declare class MockAgentSession implements AgentSession {
67
70
  * instead of the normal echoed turn. Mirrors `startUiScriptTurn`'s shape: resolves immediately
68
71
  * with the turn id, the emission and the echo happen after `turnDelayMs`. */
69
72
  private startTodoScriptTurn;
73
+ /** `#tool ...` prompt (sprint-058/task-004): after `turnDelayMs`, emit the scripted tool-call
74
+ * lifecycle (start, 3 partials, end) synchronously — no timers between tool events — then the
75
+ * usual echo and `turn_completed`. `help` emits the recipe list and no tool events. */
76
+ private startToolScriptTurn;
77
+ /** `#stream ...` prompt (sprint-083/task-002): after `turnDelayMs`, emit the event kinds the
78
+ * normal mock turn never produces (`reasoning`, `turn_failed`, `error`) through the same
79
+ * `emit` path, ending on a terminal turn event. `help` emits the recipe list as assistant text. */
80
+ private startStreamScriptTurn;
70
81
  /** Builds the raw (uncapped) task list for every recipe except `help`, which `startTodoScriptTurn`
71
82
  * handles itself. `advance` reads `currentTodos` — the only recipe whose result depends on
72
83
  * session state — everything else is a pure `todo-script.ts` builder. */
@@ -94,8 +105,6 @@ export declare class MockAgentSession implements AgentSession {
94
105
  * silent clamping so the dev daemon exercises the same effective-level semantics. */
95
106
  setThinkingOption(id: string): Promise<void>;
96
107
  listThinkingLevels(): Promise<string[]>;
97
- getPendingPermissions(): PendingPermission[];
98
- respondToPermission(): Promise<void>;
99
108
  onUiRequest(cb: (req: ProviderUiRequest) => void): Unsubscribe;
100
109
  respondToUi(providerRequestId: string, response: ProviderUiResponse): void;
101
110
  /** Test-only: push a scripted UI request to every subscriber, with sensible defaults for any
@@ -124,6 +133,10 @@ export declare class MockAgentSession implements AgentSession {
124
133
  switchSession(): Promise<{
125
134
  cancelled: boolean;
126
135
  }>;
136
+ /** Fork generation: `fork(MOCK_REBIND_ENTRY_ID)` bumps it, which changes the native handle
137
+ * `describePersistence` reports — the condition under which `handleFork` resets the timeline and
138
+ * broadcasts `agent_timeline_reset`. Every other entry id leaves the handle alone (inert stub). */
139
+ private forkGeneration;
127
140
  fork(entryId: string): Promise<{
128
141
  text: string;
129
142
  cancelled: boolean;
@@ -1,6 +1,8 @@
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 { getStreamScriptHelpText, parseStreamScript, streamScriptEvents, } from "./stream-script.js";
5
+ import { getToolScriptHelpText, parseToolScript, toolScriptEvents, } from "./tool-script.js";
4
6
  import { getUiScriptHelpText, parseUiScript } from "./ui-script.js";
5
7
  /**
6
8
  * In-process `mock` provider (features/agent-providers.md § Provider entry — dev/test only). It
@@ -26,6 +28,9 @@ export const MOCK_CAPABILITIES = {
26
28
  * that produced the data has closed, so clearing on close would defeat the whole point of this
27
29
  * map. Bounded by distinct mock session ids created in the process. */
28
30
  const mockTodosByHandle = new Map();
31
+ /** `fork` entry id that makes the mock rebind its persistence handle (sprint-083/task-002), so the
32
+ * real `agent_timeline_reset` broadcast path is reachable without a Pi session file. */
33
+ export const MOCK_REBIND_ENTRY_ID = "mock-rebind";
29
34
  const MOCK_MODES = [
30
35
  { id: "default", label: "Default" },
31
36
  { id: "plan", label: "Plan" },
@@ -75,7 +80,11 @@ export class MockAgentSession {
75
80
  this.compactDelayMs = options.compactDelayMs ?? MOCK_COMPACT_DELAY_MS;
76
81
  }
77
82
  emit(event) {
78
- this.history.push(event);
83
+ // Ephemeral partial tool snapshots reach subscribers but never the replay buffer — the mirror
84
+ // of the Pi coalescer's history rule (tool-output-streaming.md tenet 2), so a post-restart
85
+ // hydration contains no partials.
86
+ if (!(event.kind === "tool_call" && event.partial))
87
+ this.history.push(event);
79
88
  for (const cb of this.subscribers)
80
89
  cb(event);
81
90
  }
@@ -94,6 +103,12 @@ export class MockAgentSession {
94
103
  const todoRecipe = parseTodoScript(prompt);
95
104
  if (todoRecipe !== null)
96
105
  return this.startTodoScriptTurn(todoRecipe);
106
+ const toolRecipe = parseToolScript(prompt);
107
+ if (toolRecipe !== null)
108
+ return this.startToolScriptTurn(toolRecipe);
109
+ const streamRecipe = parseStreamScript(prompt);
110
+ if (streamRecipe !== null)
111
+ return this.startStreamScriptTurn(streamRecipe);
97
112
  const turnId = randomUUID();
98
113
  this.activeTurn = turnId;
99
114
  this.emit({ kind: "turn_started", turnId });
@@ -164,6 +179,58 @@ export class MockAgentSession {
164
179
  }, this.turnDelayMs);
165
180
  return Promise.resolve({ turnId });
166
181
  }
182
+ /** `#tool ...` prompt (sprint-058/task-004): after `turnDelayMs`, emit the scripted tool-call
183
+ * lifecycle (start, 3 partials, end) synchronously — no timers between tool events — then the
184
+ * usual echo and `turn_completed`. `help` emits the recipe list and no tool events. */
185
+ startToolScriptTurn(recipe) {
186
+ const turnId = randomUUID();
187
+ this.activeTurn = turnId;
188
+ this.emit({ kind: "turn_started", turnId });
189
+ setTimeout(() => {
190
+ if (this.activeTurn !== turnId)
191
+ return;
192
+ let text;
193
+ if (recipe === "help") {
194
+ text = getToolScriptHelpText();
195
+ }
196
+ else {
197
+ for (const event of toolScriptEvents(recipe, randomUUID()))
198
+ this.emit(event);
199
+ text = `echo: #tool ${recipe}`;
200
+ }
201
+ this.emit({ kind: "assistant_message", messageId: randomUUID(), text, final: true });
202
+ this.emit({ kind: "turn_completed", turnId });
203
+ this.activeTurn = null;
204
+ }, this.turnDelayMs);
205
+ return Promise.resolve({ turnId });
206
+ }
207
+ /** `#stream ...` prompt (sprint-083/task-002): after `turnDelayMs`, emit the event kinds the
208
+ * normal mock turn never produces (`reasoning`, `turn_failed`, `error`) through the same
209
+ * `emit` path, ending on a terminal turn event. `help` emits the recipe list as assistant text. */
210
+ startStreamScriptTurn(recipe) {
211
+ const turnId = randomUUID();
212
+ this.activeTurn = turnId;
213
+ this.emit({ kind: "turn_started", turnId });
214
+ setTimeout(() => {
215
+ if (this.activeTurn !== turnId)
216
+ return;
217
+ if (recipe === "help") {
218
+ this.emit({
219
+ kind: "assistant_message",
220
+ messageId: randomUUID(),
221
+ text: getStreamScriptHelpText(),
222
+ final: true,
223
+ });
224
+ this.emit({ kind: "turn_completed", turnId });
225
+ }
226
+ else {
227
+ for (const event of streamScriptEvents(recipe, turnId, randomUUID()))
228
+ this.emit(event);
229
+ }
230
+ this.activeTurn = null;
231
+ }, this.turnDelayMs);
232
+ return Promise.resolve({ turnId });
233
+ }
167
234
  /** Builds the raw (uncapped) task list for every recipe except `help`, which `startTodoScriptTurn`
168
235
  * handles itself. `advance` reads `currentTodos` — the only recipe whose result depends on
169
236
  * session state — everything else is a pure `todo-script.ts` builder. */
@@ -305,12 +372,6 @@ export class MockAgentSession {
305
372
  listThinkingLevels() {
306
373
  return Promise.resolve([...MOCK_THINKING_LEVELS]);
307
374
  }
308
- getPendingPermissions() {
309
- return [];
310
- }
311
- respondToPermission() {
312
- return Promise.resolve();
313
- }
314
375
  onUiRequest(cb) {
315
376
  this.uiSubscribers.add(cb);
316
377
  return () => this.uiSubscribers.delete(cb);
@@ -362,7 +423,12 @@ export class MockAgentSession {
362
423
  return capped;
363
424
  }
364
425
  describePersistence() {
365
- return { provider: this.provider, sessionId: this.id, nativeHandle: `mock:${this.id}` };
426
+ const generation = this.forkGeneration > 0 ? `:fork-${this.forkGeneration}` : "";
427
+ return {
428
+ provider: this.provider,
429
+ sessionId: this.id,
430
+ nativeHandle: `mock:${this.id}${generation}`,
431
+ };
366
432
  }
367
433
  // Slash-command operations (sprint-037) + command discovery (sprint-040): deterministic,
368
434
  // dependency-free implementations for tests. `exportHtml` is deliberately omitted so callers
@@ -405,7 +471,13 @@ export class MockAgentSession {
405
471
  switchSession() {
406
472
  return Promise.resolve({ cancelled: false });
407
473
  }
474
+ /** Fork generation: `fork(MOCK_REBIND_ENTRY_ID)` bumps it, which changes the native handle
475
+ * `describePersistence` reports — the condition under which `handleFork` resets the timeline and
476
+ * broadcasts `agent_timeline_reset`. Every other entry id leaves the handle alone (inert stub). */
477
+ forkGeneration = 0;
408
478
  fork(entryId) {
479
+ if (entryId === MOCK_REBIND_ENTRY_ID)
480
+ this.forkGeneration += 1;
409
481
  return Promise.resolve({ text: `mock forked text for ${entryId}`, cancelled: false });
410
482
  }
411
483
  getForkMessages() {
@@ -0,0 +1,28 @@
1
+ import type { AgentStreamEvent } from "@av-pi-studio/protocol";
2
+ /**
3
+ * Scripted stream-event trigger for the mock provider (sprint-083/task-002). The normal mock turn
4
+ * only ever emits `turn_started` / `assistant_message` / `turn_completed`; typing a `#stream ...`
5
+ * prompt makes the mock emit the event kinds it otherwise never produces, so the whole wire family
6
+ * is exercisable (and fixturable) with no Pi and no credentials. Mirrors `#ui` / `#todo` / `#tool`:
7
+ * a pure, cheap-prefix-checked parser, a `help` recipe, and recognised-but-unknown input falling
8
+ * back to help rather than an ordinary echo.
9
+ *
10
+ * Grammar (also echoed verbatim by `#stream help`):
11
+ *
12
+ * #stream reasoning a `reasoning` block, then the usual echo and `turn_completed`
13
+ * #stream fail `turn_failed` instead of `turn_completed` (agent status becomes `error`)
14
+ * #stream error an `error` event, then `turn_failed`
15
+ * #stream help this list
16
+ *
17
+ * A bare `#stream` shows help.
18
+ */
19
+ export declare const STREAM_SCRIPT_RECIPES: readonly ["reasoning", "fail", "error", "help"];
20
+ export type StreamScriptRecipe = (typeof STREAM_SCRIPT_RECIPES)[number];
21
+ export declare function getStreamScriptHelpText(): string;
22
+ /** Parses a `#stream ...` prompt into the recipe it names. Returns `null` when `prompt` is not a
23
+ * script. A bare `#stream` or an unrecognised recipe returns `"help"`. */
24
+ export declare function parseStreamScript(prompt: string): StreamScriptRecipe | null;
25
+ /** The events a non-`help` recipe emits after `turn_started`, in emission order. Every recipe ends
26
+ * on a terminal turn event so `AgentSession.run` resolves. */
27
+ export declare function streamScriptEvents(recipe: Exclude<StreamScriptRecipe, "help">, turnId: string, messageId: string): AgentStreamEvent[];
28
+ //# sourceMappingURL=stream-script.d.ts.map
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Scripted stream-event trigger for the mock provider (sprint-083/task-002). The normal mock turn
3
+ * only ever emits `turn_started` / `assistant_message` / `turn_completed`; typing a `#stream ...`
4
+ * prompt makes the mock emit the event kinds it otherwise never produces, so the whole wire family
5
+ * is exercisable (and fixturable) with no Pi and no credentials. Mirrors `#ui` / `#todo` / `#tool`:
6
+ * a pure, cheap-prefix-checked parser, a `help` recipe, and recognised-but-unknown input falling
7
+ * back to help rather than an ordinary echo.
8
+ *
9
+ * Grammar (also echoed verbatim by `#stream help`):
10
+ *
11
+ * #stream reasoning a `reasoning` block, then the usual echo and `turn_completed`
12
+ * #stream fail `turn_failed` instead of `turn_completed` (agent status becomes `error`)
13
+ * #stream error an `error` event, then `turn_failed`
14
+ * #stream help this list
15
+ *
16
+ * A bare `#stream` shows help.
17
+ */
18
+ export const STREAM_SCRIPT_RECIPES = ["reasoning", "fail", "error", "help"];
19
+ const RECIPE_SET = new Set(STREAM_SCRIPT_RECIPES);
20
+ const HELP_TEXT = `#stream script recipes:
21
+ #stream reasoning a reasoning block, then the echo and turn_completed
22
+ #stream fail turn_failed instead of turn_completed (agent status becomes error)
23
+ #stream error an error event, then turn_failed
24
+ #stream help this list`;
25
+ export function getStreamScriptHelpText() {
26
+ return HELP_TEXT;
27
+ }
28
+ /** Parses a `#stream ...` prompt into the recipe it names. Returns `null` when `prompt` is not a
29
+ * script. A bare `#stream` or an unrecognised recipe returns `"help"`. */
30
+ export function parseStreamScript(prompt) {
31
+ const trimmed = prompt.trim();
32
+ if (!/^#stream(\s|$)/i.test(trimmed))
33
+ return null;
34
+ const rest = trimmed.slice("#stream".length).trim();
35
+ return RECIPE_SET.has(rest) ? rest : "help";
36
+ }
37
+ /** The events a non-`help` recipe emits after `turn_started`, in emission order. Every recipe ends
38
+ * on a terminal turn event so `AgentSession.run` resolves. */
39
+ export function streamScriptEvents(recipe, turnId, messageId) {
40
+ switch (recipe) {
41
+ case "reasoning":
42
+ return [
43
+ { kind: "reasoning", text: "mock reasoning" },
44
+ { kind: "reasoning", final: true },
45
+ { kind: "assistant_message", messageId, text: "echo: #stream reasoning", final: true },
46
+ { kind: "turn_completed", turnId },
47
+ ];
48
+ case "fail":
49
+ return [{ kind: "turn_failed", turnId, error: "mock turn failure" }];
50
+ case "error":
51
+ return [
52
+ { kind: "error", message: "mock stream error" },
53
+ { kind: "turn_failed", turnId, error: "mock stream error" },
54
+ ];
55
+ }
56
+ }
57
+ //# sourceMappingURL=stream-script.js.map
@@ -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
  }
@@ -312,13 +326,6 @@ class PiAgentSession {
312
326
  this.mode = id;
313
327
  return Promise.resolve();
314
328
  }
315
- getPendingPermissions() {
316
- return [];
317
- }
318
- respondToPermission(requestId, response) {
319
- this.transport.notify("respond_to_permission", { requestId, response });
320
- return Promise.resolve();
321
- }
322
329
  onUiRequest(cb) {
323
330
  this.uiSubscribers.add(cb);
324
331
  return () => this.uiSubscribers.delete(cb);
@@ -505,6 +512,7 @@ class PiAgentSession {
505
512
  }));
506
513
  }
507
514
  close() {
515
+ this.partialOutput.cancelAll();
508
516
  this.subscribers.clear();
509
517
  return this.transport.close();
510
518
  }