@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
@@ -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 either a
4
- * `tool_execution_start`-shaped record (`toolName` + `args`) or a `tool_execution_end`-shaped one
5
- * (`toolName` + `result`, no `args`). For `edit`, the human-readable unified `patch` is only
6
- * present on the *end* event under `result.details.patch`, so it is pulled from there when args
7
- * carry no diff. `output` (tool stdout/result text) is only present on *end* events — `start`
8
- * events have no `result` yet, so `outputOf` yields `undefined` for them, which is correct.
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`, etc.
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 terminal
34
- * event on its own: since disposition is latched from a *prior* `agent_end` in the same session,
35
- * a lone `agent_end`/`agent_settled` call here always sees fresh (`"completed"`) state. Callers
36
- * observing a full turn lifecycle (e.g. `PiAgentSession`) MUST use `createPiEventMapper()` and
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
- /** Join `result.content` text blocks (Pi RPC `tool_execution_end` shape) into one string. */
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 either a
27
- * `tool_execution_start`-shaped record (`toolName` + `args`) or a `tool_execution_end`-shaped one
28
- * (`toolName` + `result`, no `args`). For `edit`, the human-readable unified `patch` is only
29
- * present on the *end* event under `result.details.patch`, so it is pulled from there when args
30
- * carry no diff. `output` (tool stdout/result text) is only present on *end* events — `start`
31
- * events have no `result` yet, so `outputOf` yields `undefined` for them, which is correct.
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`, etc.
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 terminal
294
- * event on its own: since disposition is latched from a *prior* `agent_end` in the same session,
295
- * a lone `agent_end`/`agent_settled` call here always sees fresh (`"completed"`) state. Callers
296
- * observing a full turn lifecycle (e.g. `PiAgentSession`) MUST use `createPiEventMapper()` and
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
@@ -1,9 +1,12 @@
1
1
  import type { Server as HttpServer } from "node:http";
2
+ import { LogTap } from "../logging/log-tap.js";
2
3
  import { type Logger } from "../logging/logger.js";
3
4
  import type { InstallSpawn } from "../extensions/sync-executor.js";
4
5
  export interface DaemonOptions {
5
- host: string;
6
- port: number;
6
+ /** Bind host. Defaults to the host of `config.daemon.listen` (`PI_STUDIO_LISTEN` → config → loopback). */
7
+ host?: string;
8
+ /** Bind port. Defaults to the port of `config.daemon.listen`. */
9
+ port?: number;
7
10
  /** Overrides `PI_STUDIO_HOME` (defaults to `~/.pi-studio`). */
8
11
  home?: string;
9
12
  /** Overrides the config path (defaults to `<home>/config.json`). */
@@ -15,6 +18,12 @@ export interface DaemonOptions {
15
18
  * `PI_STUDIO_LOG_LEVEL` (default `info`). Tests inject `silentLogger()`.
16
19
  */
17
20
  logger?: Logger;
21
+ /**
22
+ * Live log-stream tap (daemon log streaming). Defaults to a fresh `LogTap` attached to the
23
+ * logger the bootstrap builds itself; when `logger` is injected the caller must have passed the
24
+ * same tap to `createLogger({tap})` (an injected logger without it streams nothing).
25
+ */
26
+ logTap?: LogTap;
18
27
  /** Test-only injection for the preinstalled-extensions sync executor's process seam; production
19
28
  * always spawns the bundled `pi` (`defaultInstallSpawn`). */
20
29
  extensionsInstallSpawn?: InstallSpawn;
@@ -33,6 +42,13 @@ export interface DaemonHandle {
33
42
  home: string;
34
43
  provider: string;
35
44
  logger: Logger;
45
+ /** The address actually bound. */
46
+ listen: {
47
+ host: string;
48
+ port: number;
49
+ };
50
+ /** True when bound beyond loopback with no password configured (a warning was logged). */
51
+ exposedWithoutPassword: boolean;
36
52
  close(): Promise<void>;
37
53
  }
38
54
  /**
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Production daemon bootstrap — the REAL daemon: loads `PI_STUDIO_HOME/config.json`, resolves the
3
3
  * real provider (`pi` spawns `pi --mode rpc`), persists agents to disk, and registers the full RPC
4
- * surface (agents/sessions/timeline/permissions, projects/workspaces/open-project, git status/diff/
4
+ * surface (agents/sessions/timeline, projects/workspaces/open-project, git status/diff/
5
5
  * ops + GitHub PR + worktrees, file explorer + transfer, service proxy, terminals + binary frames,
6
6
  * schedules/chat/loops, providers). Mirrors `dev-bootstrap.ts` but is production-grade.
7
7
  *
@@ -14,6 +14,7 @@ import { readFile, stat } from "node:fs/promises";
14
14
  import { homedir } from "node:os";
15
15
  import { join } from "node:path";
16
16
  import nacl from "tweetnacl";
17
+ import { SERVER_VERSION } from "../version.js";
17
18
  import { createHttpServer } from "../http/http-server.js";
18
19
  import { createWebSocketServer } from "../ws/ws-server.js";
19
20
  import { HandlerRegistry, routeTextFrame, routeBinaryFrame } from "../ws/router.js";
@@ -24,6 +25,7 @@ import { createHostChecker } from "../http/host-allowlist.js";
24
25
  import { createPasswordAuth, resolvePasswordHash } from "../auth/password-auth.js";
25
26
  import { expandHome } from "../files/resolve-path.js";
26
27
  import { loadConfig } from "../config/daemon-config.js";
28
+ import { LogTap } from "../logging/log-tap.js";
27
29
  import { createDaemonLogger } from "../logging/logger.js";
28
30
  import { registerAgentUiHandlers } from "../agent/agent-ui/agent-ui-rpc.js";
29
31
  import { AgentUiService } from "../agent/agent-ui/agent-ui-service.js";
@@ -34,7 +36,6 @@ import { AgentService, getTimeline } from "../agent/agent-service.js";
34
36
  import { SessionOperationsService } from "../agent/session-operations.js";
35
37
  import { SlashCommandOperationsService } from "../agent/slash-command-operations.js";
36
38
  import { registerTimelineHandler } from "../agent/timeline-rpc.js";
37
- import { PermissionService } from "../agent/permissions.js";
38
39
  import { ProviderRegistry, resolveProviderClient } from "../agent/provider-registry.js";
39
40
  import { resolvePiAuthPaths } from "../agent/pi-home.js";
40
41
  import { createAgentTitleGenerator } from "../agent/structured-generation-runtime.js";
@@ -64,10 +65,16 @@ import { LoopService, } from "../orchestration/loop-service.js";
64
65
  import { registerOrchestrationHandlers } from "./orchestration-rpc.js";
65
66
  import { ExtensionsService } from "../extensions/extensions-service.js";
66
67
  import { registerExtensionsHandlers } from "../extensions/extensions-rpc.js";
68
+ import { registerDaemonLogsHandlers } from "../observability/daemon-logs-rpc.js";
69
+ import { DaemonLogsService } from "../observability/daemon-logs-service.js";
70
+ import { registerDaemonStatusHandlers } from "../observability/daemon-status-rpc.js";
71
+ import { DaemonStatusService } from "../observability/daemon-status-service.js";
67
72
  import { registerViewerSettingsHandlers } from "../viewers/viewer-settings-rpc.js";
68
73
  import { ResourceService } from "../resources/resource-service.js";
69
74
  import { registerSkillsHandlers } from "../resources/skills-rpc.js";
70
75
  import { SERVER_FEATURES, helloSchema, serverInfoPayloadSchema, statusSchema, } from "@av-pi-studio/protocol";
76
+ import { parseDaemonListen } from "./index.js";
77
+ import { isLoopbackHost, UNPROTECTED_BIND_WARNING } from "./loopback.js";
71
78
  import { connectRelay } from "./relay-transport.js";
72
79
  function resolveHome(opts) {
73
80
  return opts.home ?? process.env.PI_STUDIO_HOME ?? join(homedir(), ".pi-studio");
@@ -177,9 +184,21 @@ const lastAssistantText = (agentId) => {
177
184
  export function startDaemon(opts) {
178
185
  const home = resolveHome(opts);
179
186
  mkdirSync(home, { recursive: true });
180
- const logger = opts.logger ?? createDaemonLogger(home);
187
+ const logTap = opts.logTap ?? new LogTap();
188
+ const logger = opts.logger ?? createDaemonLogger(home, { tap: logTap });
181
189
  const configPath = opts.configPath ?? join(home, "config.json");
182
190
  const config = loadConfig(configPath, process.env);
191
+ let listen;
192
+ try {
193
+ const configured = parseDaemonListen(config.daemon.listen);
194
+ listen = { host: opts.host ?? configured.host, port: opts.port ?? configured.port };
195
+ }
196
+ catch (err) {
197
+ logger.error({ err: err.message }, "invalid listen address");
198
+ process.exitCode = 1;
199
+ opts.onFatalError?.(err);
200
+ throw err;
201
+ }
183
202
  const serverId = resolveServerId(home, opts.serverId);
184
203
  const daemonKeypairB64 = resolveDaemonKeypair(home);
185
204
  writePidLock(home);
@@ -225,6 +244,18 @@ export function startDaemon(opts) {
225
244
  resolveClient,
226
245
  logger,
227
246
  });
247
+ // ── Daemon status (features/daemon-status-rpc.md) — reads agents lazily through `manager`.
248
+ const daemonStatusService = new DaemonStatusService({
249
+ listAgents: () => manager.list(),
250
+ getActiveSessions,
251
+ send: (session, envelope) => session.send(envelope),
252
+ logger: logger.child({ component: "daemon-status" }),
253
+ });
254
+ // ── Daemon log streaming (features/daemon-log-streaming.md)
255
+ const daemonLogsService = new DaemonLogsService({
256
+ tap: logTap,
257
+ send: (session, envelope) => session.send(envelope),
258
+ });
228
259
  // ── Disk-persisted agent manager (recovers agents on boot) ───────────────────
229
260
  const manager = new AgentManager({
230
261
  home,
@@ -250,7 +281,7 @@ export function startDaemon(opts) {
250
281
  }
251
282
  });
252
283
  const registry = new HandlerRegistry(logger);
253
- // ── Core agent/session/timeline/permission handlers ──────────────────────────
284
+ // ── Core agent/session/timeline handlers ──────────────────────────
254
285
  const agentService = new AgentService({
255
286
  manager,
256
287
  resolveClient,
@@ -275,10 +306,10 @@ export function startDaemon(opts) {
275
306
  });
276
307
  slashCommandOps.registerHandlers(registry, getActiveSessions);
277
308
  registerTimelineHandler(registry, { manager, resolveClient });
278
- const permissionService = new PermissionService({ manager, broadcast });
279
- permissionService.registerHandlers(registry, getActiveSessions);
280
309
  registerAgentUiHandlers(registry, { service: agentUiService, logger });
281
310
  registerAgentTodosHandlers(registry, { service: agentTodosService });
311
+ registerDaemonStatusHandlers(registry, { service: daemonStatusService });
312
+ registerDaemonLogsHandlers(registry, { service: daemonLogsService });
282
313
  // ── Directory listing (agents) ────────────────────────────────────────────────
283
314
  registry.register("list_agents_request", (ctx) => ({
284
315
  type: "list_agents_response",
@@ -606,14 +637,18 @@ export function startDaemon(opts) {
606
637
  const wsHandle = createWebSocketServer(httpServer, {
607
638
  serverId,
608
639
  hostname: opts.host,
609
- version: "1.0.0",
640
+ version: SERVER_VERSION,
610
641
  auth,
611
642
  logger,
612
643
  hostCheck: (h) => hostChecker(h),
613
644
  onSession: (session) => {
614
645
  logger.info({ clientId: session.clientId, clientType: session.clientType }, "ws client connected");
615
646
  },
616
- onSessionClose: (session) => subscriptions.disposeSession(session),
647
+ onSessionClose: (session) => {
648
+ subscriptions.disposeSession(session);
649
+ daemonStatusService.disposeSession(session);
650
+ daemonLogsService.disposeSession(session);
651
+ },
617
652
  onMessage: (session, frame) => {
618
653
  if ("text" in frame) {
619
654
  void routeTextFrame(session, frame.text, registry);
@@ -646,8 +681,14 @@ export function startDaemon(opts) {
646
681
  let relayReply = null;
647
682
  let relayReplyBinary = null;
648
683
  const resetRelaySession = () => {
649
- if (relaySession)
684
+ if (relaySession) {
650
685
  relaySessions.delete(relaySession);
686
+ // Same per-session disposal a direct socket close runs (`onSessionClose` above): without
687
+ // it a replaced relay peer's subscriptions would leak until a failed send.
688
+ subscriptions.disposeSession(relaySession);
689
+ daemonStatusService.disposeSession(relaySession);
690
+ daemonLogsService.disposeSession(relaySession);
691
+ }
651
692
  relaySession = null;
652
693
  };
653
694
  relayHandle = connectRelay({
@@ -676,6 +717,8 @@ export function startDaemon(opts) {
676
717
  clientId: hello.data.clientId,
677
718
  clientType: hello.data.clientType,
678
719
  capabilities,
720
+ appVersion: hello.data.appVersion,
721
+ transport: "relay",
679
722
  // `Session.send()` calls `socket.send(jsonString)`; `Session.sendBinary()` calls
680
723
  // `socket.send(bytes)` — same method, discriminated by argument type here so both
681
724
  // funnel to the matching relay reply callback (text `e2ee_app` vs binary `e2ee_bin`).
@@ -699,7 +742,7 @@ export function startDaemon(opts) {
699
742
  status: "server_info",
700
743
  serverId,
701
744
  hostname: opts.host,
702
- version: "1.0.0",
745
+ version: SERVER_VERSION,
703
746
  // Same value the direct-WS handshake reports (`ws/ws-server.ts`): the DAEMON's home
704
747
  // dir, which a relay-remote client (different machine, possibly different OS) has no
705
748
  // other way to learn.
@@ -769,7 +812,7 @@ export function startDaemon(opts) {
769
812
  // process entry point, which passes `onFatalError` (see `daemon/main.ts`).
770
813
  httpServer.on("error", (err) => {
771
814
  if (err.code === "EADDRINUSE") {
772
- logger.error({ host: opts.host, port: opts.port }, "cannot bind — address already in use");
815
+ logger.error({ host: listen.host, port: listen.port }, "cannot bind — address already in use");
773
816
  }
774
817
  else {
775
818
  logger.error({ err: err.message }, "http server error");
@@ -777,8 +820,11 @@ export function startDaemon(opts) {
777
820
  process.exitCode = 1;
778
821
  void wsHandle.close().finally(() => opts.onFatalError?.(err));
779
822
  });
780
- httpServer.listen(opts.port, opts.host);
781
- logger.info({ host: opts.host, port: opts.port }, "http/ws server accepting connections");
823
+ httpServer.listen(listen.port, listen.host);
824
+ logger.info({ host: listen.host, port: listen.port }, "http/ws server accepting connections");
825
+ const exposedWithoutPassword = !isLoopbackHost(listen.host) && !passwordHash;
826
+ if (exposedWithoutPassword)
827
+ logger.warn({ host: listen.host, port: listen.port }, UNPROTECTED_BIND_WARNING);
782
828
  // Fire-and-forget: never delays daemon readiness, never blocks the return below. Mirrors the
783
829
  // agent-recovery block above, but deliberately kicked off AFTER listen() rather than before —
784
830
  // extensions sync is optional-and-loud, agent recovery is required-for-correctness.
@@ -791,10 +837,14 @@ export function startDaemon(opts) {
791
837
  home,
792
838
  provider: "pi",
793
839
  logger,
840
+ listen,
841
+ exposedWithoutPassword,
794
842
  close: async () => {
795
843
  logger.info("daemon shutting down");
796
844
  terminalManager.killAll();
797
845
  fileWatchService.close();
846
+ daemonStatusService.dispose();
847
+ daemonLogsService.dispose();
798
848
  relayHandle?.close();
799
849
  await wsHandle.close();
800
850
  await new Promise((resolve) => httpServer.close(() => resolve()));
@@ -1,5 +1,6 @@
1
1
  import type { Server as HttpServer } from "node:http";
2
2
  import { AgentManager } from "../agent/agent-manager.js";
3
+ import { LogTap } from "../logging/log-tap.js";
3
4
  import { type Logger } from "../logging/logger.js";
4
5
  export interface DevBootstrapOptions {
5
6
  host: string;
@@ -8,6 +9,12 @@ export interface DevBootstrapOptions {
8
9
  hostnames?: true | string[];
9
10
  /** Operational logger. Defaults to a stdout dev logger (`PI_STUDIO_LOG_LEVEL`, pretty on a TTY). */
10
11
  logger?: Logger;
12
+ /**
13
+ * Live log-stream tap (daemon log streaming). Defaults to a fresh `LogTap` attached to the
14
+ * logger the bootstrap builds itself; when `logger` is injected the caller must have passed the
15
+ * same tap to `createLogger({tap})` (an injected logger without it streams nothing).
16
+ */
17
+ logTap?: LogTap;
11
18
  /**
12
19
  * Delay (ms) before a mock turn auto-completes (`MockSessionOptions.turnDelayMs`). Defaults to
13
20
  * the mock provider's own default (5ms) — long enough for `interrupt` to win a race, too short