@comput/pi-intercom 0.1.3 → 0.2.1

package/src/dashboard.ts

@@ -0,0 +1,158 @@
+import { createServer } from 'node:http';
+import { constants } from 'node:fs';
+import { lstat, open, opendir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateConfig, type Config } from './config.js';
+import { LOG_DIRECTORY, LOG_FILE_PATTERN, sanitizeObservation, type Observation } from './observability.js';
+
+const CONFIG_BYTES = 1024 * 1024, TAIL_BYTES = 128 * 1024, TOTAL_BYTES = 2 * 1024 * 1024;
+const MAX_FILES = 32, MAX_ENTRIES = 512, MAX_EVENTS = 500, MAX_AGENTS = 256;
+export interface DashboardSnapshot {
+  version: 1;
+  generatedAt: string;
+  staleAfterMs: number;
+  config: Pick<Config, 'multiplexer' | 'agents'> | null;
+  events: Observation[];
+  truncated: boolean;
+  errors: string[];
+}
+
+// Only fixed, extension-owned paths are read. Reject symlink/junction components
+// rather than allowing a local log/config link to expose an unrelated file.
+async function confined(root: string, relative: string): Promise<string> {
+  const base = await realpath(root);
+  let current = base;
+  for (const segment of relative.split(/[\\/]/)) {
+    if (!segment || segment === '.' || segment === '..') throw new Error('invalid path');
+    current = path.join(current, segment);
+    if ((await lstat(current)).isSymbolicLink()) throw new Error('linked path');
+    if (path.relative(current, await realpath(current)) !== '') throw new Error('redirected path');
+  }
+  return current;
+}
+
+async function boundedRead(file: string, limit: number, tail = false): Promise<{ text: string; truncated: boolean; bytes: number }> {
+  if (!(await lstat(file)).isFile()) throw new Error('not a file');
+  const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw new Error('not a file');
+    if (!tail && stat.size > limit) throw new Error('file too large');
+    const size = Math.min(stat.size, limit), start = tail ? Math.max(0, stat.size - size) : 0;
+    const buffer = Buffer.alloc(size);
+    const { bytesRead } = await handle.read(buffer, 0, size, start);
+    let text = buffer.subarray(0, bytesRead).toString('utf8');
+    // Drop potentially partial UTF-8/JSON at both tail boundaries. Writers append
+    // complete newline-terminated records; incomplete records are not evidence.
+    if (tail) {
+      if (start > 0) text = text.slice(text.indexOf('\n') + 1);
+      text = text.slice(0, text.lastIndexOf('\n') + 1);
+    }
+    return { text, truncated: stat.size > limit, bytes: bytesRead };
+  } finally { await handle.close(); }
+}
+
+export async function readDashboardSnapshot(root: string): Promise<DashboardSnapshot> {
+  const result: DashboardSnapshot = { version: 1, generatedAt: new Date().toISOString(), staleAfterMs: 60000, config: null, events: [], truncated: false, errors: [] };
+  try {
+    const file = await confined(root, '.pi-intercom/config.json');
+    const config = validateConfig(JSON.parse((await boundedRead(file, CONFIG_BYTES)).text));
+    result.truncated ||= config.agents.length > MAX_AGENTS;
+    result.config = { multiplexer: config.multiplexer, agents: config.agents.slice(0, MAX_AGENTS).map(a => ({
+      sessionId: a.sessionId, name: a.name, coordinator: a.coordinator, description: a.description,
+      projectDirectory: a.projectDirectory, port: a.port,
+      ...(a.dashboardPort === undefined ? {} : { dashboardPort: a.dashboardPort }),
+    })) };
+  } catch { result.errors.push('config_unavailable'); }
+  try {
+    const directory = await confined(root, LOG_DIRECTORY);
+    const files: { name: string; modified: number }[] = [];
+    const entries = await opendir(directory);
+    let scanned = 0;
+    for await (const entry of entries) {
+      if (++scanned > MAX_ENTRIES) { result.truncated = true; break; }
+      if (!entry.isFile() || !LOG_FILE_PATTERN.test(entry.name)) continue;
+      try {
+        const file = await confined(root, `${LOG_DIRECTORY}/${entry.name}`);
+        files.push({ name: entry.name, modified: (await lstat(file)).mtimeMs });
+      } catch { /* Rotations can remove a file while scanning. */ }
+    }
+    files.sort((a, b) => b.modified - a.modified || a.name.localeCompare(b.name));
+    result.truncated ||= files.length > MAX_FILES;
+    let budget = TOTAL_BYTES;
+    for (const file of files.slice(0, MAX_FILES)) {
+      if (budget <= 0) { result.truncated = true; break; }
+      try {
+        const resolved = await confined(root, `${LOG_DIRECTORY}/${file.name}`);
+        const read = await boundedRead(resolved, Math.min(TAIL_BYTES, budget), true);
+        budget -= read.bytes;
+        result.truncated ||= read.truncated;
+        for (const line of read.text.split('\n')) {
+          if (!line) continue;
+          try {
+            const event = sanitizeObservation(JSON.parse(line));
+            if (event) result.events.push(event);
+          } catch { /* Ignore malformed/partial/foreign records, never expose raw data. */ }
+        }
+      } catch { if (!result.errors.includes('log_read_failed')) result.errors.push('log_read_failed'); }
+    }
+    result.events.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    if (result.events.length > MAX_EVENTS) { result.events = result.events.slice(-MAX_EVENTS); result.truncated = true; }
+  } catch { result.errors.push('logs_unavailable'); }
+  return result;
+}
+
+export interface Dashboard { url: string; port: number; close(): Promise<void> }
+export async function startDashboard(root: string, options: { assetDirectory?: string } = {}): Promise<Dashboard> {
+  const assets = options.assetDirectory ?? fileURLToPath(new URL('../dashboard/', import.meta.url));
+  const routes: Record<string, [string, string]> = {
+    '/': ['index.html', 'text/html; charset=utf-8'],
+    '/app.js': ['app.js', 'text/javascript; charset=utf-8'],
+    '/style.css': ['style.css', 'text/css; charset=utf-8'],
+  };
+  let port = 0, active = 0, closing = false;
+  let pending: Promise<DashboardSnapshot> | undefined;
+  const server = createServer(async (request, response) => {
+    response.setHeader('Cache-Control', 'no-store');
+    response.setHeader('X-Content-Type-Options', 'nosniff');
+    response.setHeader('Content-Security-Policy', "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; base-uri 'none'; frame-ancestors 'none'");
+    response.setHeader('Referrer-Policy', 'no-referrer');
+    const end = (code: number, body: string, type = 'text/plain; charset=utf-8') => {
+      response.writeHead(code, { 'Content-Type': type }); response.end(body);
+    };
+    const hosts = [`127.0.0.1:${port}`, `localhost:${port}`];
+    if (!hosts.includes(request.headers.host ?? '') ||
+      (request.headers.origin !== undefined && !hosts.some(host => request.headers.origin === `http://${host}`)) ||
+      request.headers['sec-fetch-site'] === 'cross-site') return end(403, 'Forbidden');
+    if (request.method !== 'GET') { response.setHeader('Allow', 'GET'); return end(405, 'GET only'); }
+    if (closing || active >= 8) return end(503, 'Unavailable');
+    active++;
+    try {
+      if (request.url === '/api/snapshot') {
+        pending ??= readDashboardSnapshot(root).finally(() => { pending = undefined; });
+        return end(200, JSON.stringify(await pending), 'application/json; charset=utf-8');
+      }
+      const route = Object.hasOwn(routes, request.url ?? '') ? routes[request.url!] : undefined;
+      if (!route) return end(404, 'Not found');
+      const file = await confined(assets, route[0]);
+      return end(200, (await boundedRead(file, 256 * 1024)).text, route[1]);
+    } catch { return end(503, 'Unavailable'); }
+    finally { active--; }
+  });
+  server.requestTimeout = 5000; server.headersTimeout = 5000; server.keepAliveTimeout = 1000;
+  server.maxConnections = 16;
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => { server.off('error', reject); resolve(); });
+  });
+  port = (server.address() as { port: number }).port;
+  let closed: Promise<void> | undefined;
+  return { port, url: `http://127.0.0.1:${port}/`, close() {
+    closing = true;
+    return closed ??= new Promise<void>((resolve, reject) => {
+      server.close(error => error ? reject(error) : resolve());
+      server.closeAllConnections();
+    });
+  } };
+}

package/src/index.ts

@@ -5,6 +5,7 @@ import { getAgentDir, SessionManager, SettingsManager, truncateHead, withFileMut
 import { ConfigStore } from './config.js';
 import { Intercom, UNSUPPORTED_CANCELLATION } from './runtime.js';
 import { launchers } from './launcher.js';
+import { startDashboard, type Dashboard } from './dashboard.js';
 
 const to = Type.Object({ to: Type.String({ minLength: 1, maxLength: 128 }) });
 const tools: [string, string, TSchema][] = [
@@ -42,11 +43,15 @@ class PiConfigStore extends ConfigStore {
 export default function intercomExtension(pi: ExtensionAPI): void {
   let runtime: Intercom | undefined;
   let context: ExtensionContext | undefined;
+  let dashboard: Dashboard | undefined;
+  let generation = 0;
   const launcher = launchers({
     extension: fileURLToPath(import.meta.url),
     sessionExists: async (cwd, id) => (await SessionManager.list(cwd, resumeSessionDirectory(cwd))).some(s => s.id === id),
   });
   pi.on('session_start', async (_event, ctx) => {
+    const started = ++generation;
+    await dashboard?.close(); dashboard = undefined;
     await runtime?.close(); context = ctx;
     if (process.platform !== 'win32' || ctx.mode !== 'tui') throw new Error('PiIntercom V1 requires Windows interactive Pi. No resources started.');
     if (!ctx.isProjectTrusted()) throw new Error('PiIntercom requires project trust before honoring shared project configuration.');
@@ -54,14 +59,49 @@ export default function intercomExtension(pi: ExtensionAPI): void {
       cwd: ctx.cwd,
       sessionId: () => context!.sessionManager.getSessionId(),
       busy: () => !context!.isIdle(),
-      deliver: (content, busy) => pi.sendUserMessage(content, busy ? { deliverAs: 'steer' } : undefined),
+      // Always supply the supported busy mode: the arrival snapshot can become
+      // stale before Pi checks it. Pi still starts a normal turn when idle.
+      deliver: content => pi.sendUserMessage(content, { deliverAs: 'steer' }),
       setName: async name => { if (pi.getSessionName() !== name) pi.setSessionName(name); await launcher.syncName(name); },
       notify: text => ctx.ui.notify(text, 'info'),
     }, { launch: launcher.launch, store: root => new PiConfigStore(root) });
-    try { await runtime.start(); }
-    catch (e) { runtime = undefined; ctx.ui.notify(String(e), 'error'); }
+    const current = runtime;
+    try { await current.start(); }
+    catch (e) { if (runtime === current) runtime = undefined; ctx.ui.notify(String(e), 'error'); return; }
+    if (started !== generation) return;
+    let server: Dashboard | undefined;
+    let savingPort = false;
+    try {
+      if ((await current.state()).me?.coordinator) {
+        server = await startDashboard(current.store.root);
+        if (started !== generation) { await server.close(); return; }
+        savingPort = true;
+        await current.recordDashboardPort(server.port);
+        if (started !== generation) { await server.close(); return; }
+        dashboard = server;
+        ctx.ui.notify(`Intercom read-only dashboard: ${server.url} (saved URL is last-known, not live availability)`, 'info');
+      }
+    } catch {
+      await server?.close().catch(() => {});
+      if (started !== generation) return;
+      ctx.ui.notify(savingPort
+        ? 'Intercom dashboard port could not be saved; the new dashboard was closed. Any saved URL is last-known only. Messaging remains available.'
+        : 'Intercom dashboard unavailable; communication remains independent.', 'error');
+    }
+  });
+  pi.on('session_shutdown', async () => {
+    generation++;
+    await dashboard?.close(); dashboard = undefined;
+    await runtime?.close(); runtime = undefined; context = undefined;
+  });
+  pi.on('agent_start', async (_event, ctx) => {
+    context = ctx;
+    runtime?.recordObservation('host.activity', { busy: !ctx.isIdle(), outcome: 'started' });
+  });
+  pi.on('agent_settled', async (_event, ctx) => {
+    context = ctx;
+    runtime?.recordObservation('host.activity', { busy: !ctx.isIdle(), outcome: 'settled' });
   });
-  pi.on('session_shutdown', async () => { await runtime?.close(); runtime = undefined; context = undefined; });
   pi.on('before_agent_start', async (event, ctx) => {
     context = ctx;
     if (!runtime) return;

package/src/observability.ts

@@ -0,0 +1,169 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { appendFile, lstat, mkdir, opendir, rename, stat, unlink } from 'node:fs/promises';
+
+export const LOG_DIRECTORY = '.pi-intercom/logs';
+export const LOG_FILE_PATTERN = /^writer-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl(?:\.[12]|\.closed)?$/;
+export const LOG_LIMITS = { fileBytes: 1024 * 1024, filesPerInstance: 3, queueEntries: 256, entryBytes: 4096, retentionMs: 7 * 24 * 60 * 60 * 1000, directoryBytes: 32 * 1024 * 1024, scanEntries: 4096, closeTimeoutMs: 250 } as const;
+export const EVENT_TYPES = ['runtime.starting', 'runtime.ready', 'runtime.closed', 'runtime.failed', 'config.changed', 'config.reloaded', 'transport.send', 'transport.receipt', 'transport.failed', 'transport.received', 'transport.rejected', 'registration.received', 'status.received', 'launch.result', 'host.submission', 'host.activity', 'host.ui_prompt'] as const;
+export type EventType = typeof EVENT_TYPES[number];
+const OUTCOMES = ['attempted', 'returned', 'failed', 'http_receipt', 'handler_failed', 'started', 'settled', 'snapshot', 'ended', 'written', 'removed', 'ready'] as const;
+const ERROR_CODES = ['operation_failed', 'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EADDRINUSE', 'EACCES', 'EPERM', 'ENOENT', 'ENOSPC'] as const;
+const KINDS = ['message', 'registration', 'status', 'request_status', 'reload', 'stop', 'close'] as const;
+const OPERATIONS = ['configure_worker', 'set_multiplexer', 'remove_worker', 'create_worker', 'resume_worker', 'port_update', 'initialize'] as const;
+export interface EventMetadata {
+  peerSessionId?: string;
+  peerName?: string;
+  correlationId?: string;
+  kind?: typeof KINDS[number];
+  busy?: boolean;
+  port?: number;
+  role?: 'coordinator' | 'worker' | 'anonymous';
+  outcome?: typeof OUTCOMES[number];
+  errorCode?: typeof ERROR_CODES[number];
+  operation?: typeof OPERATIONS[number];
+}
+export interface Observation extends EventMetadata {
+  version: 1;
+  timestamp: string;
+  /** Log-file writer identity only: never a transport or agent identity. */
+  writerId: string;
+  sessionId: string;
+  event: EventType;
+}
+export interface Observer { record(event: EventType, metadata?: EventMetadata): void; close(): Promise<void>; maintain?(): void }
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function safeText(value: unknown, max: number): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= max && !/[\x00-\x1f\x7f]/.test(value);
+}
+function includes<T extends string>(list: readonly T[], value: unknown): value is T { return typeof value === 'string' && list.includes(value as T); }
+/** Project only explicitly allowed metadata, including when reading untrusted on-disk logs. */
+export function sanitizeObservation(value: unknown): Observation | undefined {
+  if (!value || typeof value !== 'object') return;
+  const v = value as Record<string, unknown>;
+  if (v.version !== 1 || !includes(EVENT_TYPES, v.event) || !safeText(v.sessionId, 256) || typeof v.writerId !== 'string' || !uuid.test(v.writerId)) return;
+  if (typeof v.timestamp !== 'string' || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(v.timestamp) || !Number.isFinite(Date.parse(v.timestamp))) return;
+  const result: Observation = { version: 1, timestamp: v.timestamp, writerId: v.writerId, sessionId: v.sessionId, event: v.event };
+  if (safeText(v.peerSessionId, 256)) result.peerSessionId = v.peerSessionId;
+  if (safeText(v.peerName, 128)) result.peerName = v.peerName;
+  if (safeText(v.correlationId, 128) && /^[a-zA-Z0-9-]+$/.test(v.correlationId)) result.correlationId = v.correlationId;
+  if (includes(KINDS, v.kind)) result.kind = v.kind;
+  if (typeof v.busy === 'boolean') result.busy = v.busy;
+  if (Number.isInteger(v.port) && Number(v.port) >= 1 && Number(v.port) <= 65535) result.port = Number(v.port);
+  if (includes(['coordinator', 'worker', 'anonymous'], v.role)) result.role = v.role;
+  if (includes(OUTCOMES, v.outcome)) result.outcome = v.outcome;
+  if (includes(ERROR_CODES, v.errorCode)) result.errorCode = v.errorCode;
+  if (includes(OPERATIONS, v.operation)) result.operation = v.operation;
+  return result;
+}
+/** Never inspect error.message/stack, response bodies, paths, or arbitrary error codes. */
+export function observationError(error: unknown): EventMetadata['errorCode'] {
+  try {
+    const code = error && typeof error === 'object' ? (error as { code?: unknown }).code : undefined;
+    return includes(ERROR_CODES, code) ? code : 'operation_failed';
+  } catch { return 'operation_failed'; }
+}
+export class LocalObserver implements Observer {
+  readonly writerId = randomUUID();
+  readonly directory: string;
+  readonly file: string;
+  private queue: string[] = [];
+  private pending?: Promise<void>;
+  private initialized = false;
+  private bytes = 0;
+  private closed = false;
+  private disabled = false;
+  private maintenance = false;
+  private timer?: ReturnType<typeof setInterval>;
+  dropped = 0;
+  constructor(root: string, readonly sessionId: string, private readonly limits: { fileBytes?: number; queueEntries?: number } = {}) {
+    this.directory = path.join(root, LOG_DIRECTORY);
+    this.file = path.join(this.directory, `writer-${this.writerId}.jsonl`);
+  }
+  record(event: EventType, metadata: EventMetadata = {}): void {
+    try {
+      if (this.closed || this.disabled) return;
+      const observation = sanitizeObservation({ ...metadata, version: 1, timestamp: new Date().toISOString(), writerId: this.writerId, sessionId: this.sessionId, event });
+      if (!observation) return;
+      const line = JSON.stringify(observation) + '\n';
+      const capacity = Math.max(1, Math.min(LOG_LIMITS.queueEntries, this.limits.queueEntries ?? LOG_LIMITS.queueEntries));
+      if (Buffer.byteLength(line) > LOG_LIMITS.entryBytes || this.queue.length >= capacity) { this.dropped++; return; }
+      this.queue.push(line);
+      this.schedule();
+    } catch { /* Observability must never throw into communication. */ }
+  }
+  private schedule(): void {
+    if (this.pending || this.disabled) return;
+    this.pending = Promise.resolve().then(() => this.drain()).catch(() => {
+      // Disable this writer after an I/O failure; no retry queue and no communication failure.
+      this.disabled = true; this.dropped += this.queue.length; this.queue = [];
+    }).finally(() => {
+      this.pending = undefined;
+      if (this.queue.length && !this.disabled) this.schedule();
+    });
+  }
+  /** Runtime calls only on the coordinator. No process probes or activity inference. */
+  maintain(): void {
+    if (this.closed || this.disabled || this.timer) return;
+    const request = () => { this.maintenance = true; this.schedule(); };
+    this.timer = setInterval(request, 60_000); this.timer.unref(); request();
+  }
+  protected append(file: string, line: string): Promise<void> { return appendFile(file, line, { encoding: 'utf8', mode: 0o600 }); }
+  private async prune(): Promise<void> {
+    const files: { file: string; base: string; mtime: number; bytes: number }[] = [];
+    const closed = new Set<string>();
+    let scanned = 0;
+    for await (const entry of await opendir(this.directory)) {
+      if (++scanned > LOG_LIMITS.scanEntries) break;
+      if (!entry.isFile() || !LOG_FILE_PATTERN.test(entry.name)) continue;
+      const file = path.join(this.directory, entry.name);
+      const base = file.replace(/\.(?:closed|[12])$/, '');
+      if (file.endsWith('.closed')) closed.add(base);
+      const info = await stat(file).catch(() => undefined);
+      if (info) files.push({ file, base, mtime: info.mtimeMs, bytes: info.size });
+    }
+    let total = files.reduce((sum, file) => sum + file.bytes, 0);
+    const groups = [...closed].map(base => {
+      const members = files.filter(file => file.base === base);
+      return { members, newest: Math.max(...members.map(file => file.mtime)) };
+    }).sort((a, b) => a.newest - b.newest);
+    for (const group of groups) {
+      // Only gracefully closed writer groups are eligible. Active/crashed writers stay untouched.
+      if (Date.now() - group.newest > LOG_LIMITS.retentionMs || total > LOG_LIMITS.directoryBytes) {
+        // Remove the closed marker last, retaining eligibility if an earlier unlink fails.
+        for (const file of group.members.sort((a, b) => Number(a.file.endsWith('.closed')) - Number(b.file.endsWith('.closed')))) {
+          try { await unlink(file.file); total -= file.bytes; } catch { break; }
+        }
+      }
+    }
+  }
+  private async drain(): Promise<void> {
+    if (!this.initialized) {
+      const parent = path.dirname(this.directory);
+      await mkdir(parent, { recursive: true, mode: 0o700 });
+      if ((await lstat(parent)).isSymbolicLink()) throw new Error('log parent must not be a symlink');
+      await mkdir(this.directory, { recursive: true, mode: 0o700 });
+      if ((await lstat(this.directory)).isSymbolicLink()) throw new Error('log directory must not be a symlink');
+      this.initialized = true;
+    }
+    if (this.maintenance) { this.maintenance = false; await this.prune().catch(() => {}); }
+    const maxBytes = Math.max(LOG_LIMITS.entryBytes, Math.min(LOG_LIMITS.fileBytes, this.limits.fileBytes ?? LOG_LIMITS.fileBytes));
+    while (this.queue.length) {
+      const line = this.queue.shift()!, size = Buffer.byteLength(line);
+      if (this.bytes + size > maxBytes) {
+        await unlink(`${this.file}.2`).catch(e => { if (e.code !== 'ENOENT') throw e; });
+        await rename(`${this.file}.1`, `${this.file}.2`).catch(e => { if (e.code !== 'ENOENT') throw e; });
+        await rename(this.file, `${this.file}.1`).catch(e => { if (e.code !== 'ENOENT') throw e; });
+        this.bytes = 0;
+      }
+      await this.append(this.file, line); this.bytes += size;
+    }
+  }
+  async close(): Promise<void> {
+    if (this.timer) { clearInterval(this.timer); this.timer = undefined; }
+    this.closed = true;
+    while (this.pending) await this.pending;
+    // An atomic suffix change is the sole inactive-writer signal. Crashes leave no such signal.
+    if (this.initialized && !this.disabled) await rename(this.file, `${this.file}.closed`).catch(() => {});
+  }
+}