@comput/pi-intercom 0.1.3 → 0.2.1

package/src/runtime.ts

@@ -1,5 +1,7 @@
 import path from 'node:path';
-import { ConfigStore, coordinator, directory, fail, named, requireCoordinator, type Agent, type Config } from './config.js';
+import { randomUUID } from 'node:crypto';
+import { LocalObserver, LOG_LIMITS, observationError, type Observer, type EventType, type EventMetadata } from './observability.js';
+import { ConfigStore, coordinator, directory, fail, named, port, requireCoordinator, type Agent, type Config } from './config.js';
 import { listen, send, type Endpoint, type Envelope, type Kind } from './transport.js';
 
 export const UNSUPPORTED_CANCELLATION = 'Unsupported Pi host: stop_worker and close_worker are disabled. Pi 0.84.4 extension abort does not cancel retry backoff/continuations; graceful shutdown cannot guarantee no queued work restarts. No cancellation or shutdown was performed. See references/implementation-blocker.md. A verified supported host API is required (no version-only override).';
@@ -17,6 +19,7 @@ export interface RuntimeOptions {
   listen?: typeof listen;
   send?: typeof send;
   store?: (root: string) => ConfigStore;
+  observe?: (root: string, sessionId: string) => Observer;
 }
 export class Intercom {
   store!: ConfigStore;
@@ -25,6 +28,15 @@ export class Intercom {
   private generation = 0;
   private initialId = '';
   responsibility?: Agent;
+  private observer?: Observer;
+  private closing?: Promise<void>;
+  private captureObserver(): (event: EventType, metadata?: EventMetadata) => void {
+    const observer = this.observer;
+    return (event, metadata = {}) => {
+      try { observer?.record(event, metadata); } catch { /* Logging cannot affect communication. */ }
+    };
+  }
+  recordObservation(event: EventType, metadata: EventMetadata = {}): void { this.captureObserver()(event, metadata); }
   constructor(readonly host: Host, readonly options: RuntimeOptions) {}
   private id(): string {
     const id = this.host.sessionId();
@@ -40,26 +52,36 @@ export class Intercom {
     };
   }
   async start(): Promise<void> {
+    if (this.closing) await this.closing;
     if (this.active) fail('runtime already active');
     this.initialId = this.host.sessionId(); this.active = true;
     const generation = ++this.generation, assertValid = this.validity();
+    let record = this.captureObserver();
     try {
       const discovered = await ConfigStore.discover(this.host.cwd);
       assertValid();
       this.store = this.options.store?.(discovered?.root ?? this.host.cwd) ?? discovered ?? new ConfigStore(this.host.cwd);
+      try { this.observer = this.options.observe ? this.options.observe(this.store.root, this.initialId) : new LocalObserver(this.store.root, this.initialId); } catch { /* Logging is optional on failure. */ }
+      record = this.captureObserver();
+      record('runtime.starting');
       const previous = discovered ? await this.store.read() : undefined;
       assertValid();
       const own = previous?.agents.find(a => a.sessionId === this.id());
       const endpoint = await (this.options.listen ?? listen)(own?.port, m => { assertValid(); return this.receive(m); });
       try { assertValid(); } catch (error) { await endpoint.close(); throw error; }
       this.endpoint = endpoint;
-      if (!previous) await this.store.initialize(this.id(), this.endpoint.port, assertValid);
+      if (!previous) {
+        const initialized = await this.store.initialize(this.id(), this.endpoint.port, assertValid);
+        if (initialized) record('config.changed', { operation: 'initialize', outcome: 'written' });
+      }
       const config = await this.store.read();
       assertValid();
       const me = config.agents.find(a => a.sessionId === this.id());
       if (me?.coordinator) {
+        try { this.observer?.maintain?.(); } catch { /* No cleanup failure affects readiness. */ }
         await this.store.update(this.id(), c => { requireCoordinator(c, this.id()).port = this.endpoint!.port; }, assertValid);
         assertValid();
+        record('config.changed', { operation: 'port_update', outcome: 'written', port: this.endpoint.port });
         try { await this.reload(); } catch (e) { assertValid(); this.host.notify(`Name/responsibility synchronization failed: ${String(e)}`); }
         assertValid();
         this.host.notify(`Intercom Coordinator ready at 127.0.0.1:${this.endpoint.port}; waiting for user input.`);
@@ -77,13 +99,39 @@ export class Intercom {
         assertValid();
         this.host.notify(`Intercom worker ready at 127.0.0.1:${this.endpoint.port}; waiting for explicit work.`);
       }
-    } catch (e) { if (generation === this.generation) await this.close(); throw e; }
+      record('runtime.ready', { port: this.endpoint.port, role: me?.coordinator ? 'coordinator' : me ? 'worker' : 'anonymous', busy: this.host.busy(), outcome: 'ready' });
+    } catch (e) {
+      if (generation === this.generation) {
+        record('runtime.failed', { errorCode: observationError(e), outcome: 'failed' });
+        await this.close();
+      }
+      throw e;
+    }
   }
   async close(): Promise<void> {
+    if (this.closing) return this.closing;
+    this.recordObservation('runtime.closed');
+    const observer = this.observer; this.observer = undefined;
     this.active = false; this.generation++;
     const endpoint = this.endpoint; this.endpoint = undefined;
     this.responsibility = undefined;
-    if (endpoint) await endpoint.close();
+    const closing = (async () => {
+      try { if (endpoint) await endpoint.close(); }
+      finally {
+        if (observer) {
+          let timer: ReturnType<typeof setTimeout> | undefined;
+          try {
+            // Only shutdown waits, and only for this bounded deadline. Already-issued I/O cannot be cancelled.
+            await Promise.race([
+              Promise.resolve().then(() => observer.close()).catch(() => {}),
+              new Promise<void>(resolve => { timer = setTimeout(resolve, LOG_LIMITS.closeTimeoutMs); }),
+            ]);
+          } finally { if (timer) clearTimeout(timer); }
+        }
+      }
+    })();
+    this.closing = closing;
+    try { await closing; } finally { if (this.closing === closing) this.closing = undefined; }
   }
   async state(): Promise<{ id: string; config: Config; me?: Agent }> {
     const assertValid = this.validity();
@@ -91,7 +139,16 @@ export class Intercom {
     assertValid();
     return { id, config, me: config.agents.find(a => a.sessionId === id) };
   }
+  /** Persist an actual dashboard bind; saved discovery metadata, not a live-status assertion. */
+  async recordDashboardPort(boundPort: number): Promise<void> {
+    const record = this.captureObserver(), assertValid = this.validity();
+    const { id, config } = await this.state();
+    assertValid(); requireCoordinator(config, id); port(boundPort);
+    await this.store.update(id, c => { requireCoordinator(c, id).dashboardPort = boundPort; }, assertValid);
+    record('config.changed', { outcome: 'written' });
+  }
   async reload(): Promise<void> {
+    const record = this.captureObserver();
     const assertValid = this.validity();
     const { me } = await this.state();
     assertValid();
@@ -99,14 +156,24 @@ export class Intercom {
     this.responsibility = { ...me };
     await this.host.setName(me.name);
     assertValid();
+    record('config.reloaded', { role: me.coordinator ? 'coordinator' : 'worker' });
     this.host.notify(`Intercom responsibility loaded for ${me.name}; no work turn started.`);
   }
   async transmit(to: string, kind: Kind, payload: Record<string, unknown> = {}): Promise<void> {
+    const record = this.captureObserver();
     const assertValid = this.validity();
     const { id, config } = await this.state();
     assertValid();
-    const target = named(config, to);
-    await (this.options.send ?? send)(target.port, { version: 1, from: id, to: target.sessionId, kind, payload });
+    const target = named(config, to), correlationId = randomUUID();
+    const metadata = { peerSessionId: target.sessionId, peerName: target.name, correlationId, kind };
+    record('transport.send', { ...metadata, outcome: 'attempted' });
+    try {
+      await (this.options.send ?? send)(target.port, { version: 1, from: id, to: target.sessionId, kind, payload, correlationId });
+      record('transport.receipt', { ...metadata, outcome: 'http_receipt' });
+    } catch (error) {
+      record('transport.failed', { ...metadata, outcome: 'failed', errorCode: observationError(error) });
+      throw error;
+    }
   }
   async report(): Promise<void> {
     const assertValid = this.validity();
@@ -117,15 +184,35 @@ export class Intercom {
     await this.transmit(coordinator(config).name, 'status', { port: this.endpoint.port, busy: this.host.busy() });
   }
   async receive(message: Envelope): Promise<void> {
+    const record = this.captureObserver();
+    const metadata = { peerSessionId: message.from, correlationId: message.correlationId, kind: message.kind };
+    record('transport.received', metadata);
+    try { await this.handleReceive(message); }
+    catch (error) {
+      record('transport.rejected', { ...metadata, outcome: 'handler_failed', errorCode: observationError(error) });
+      throw error;
+    }
+  }
+  private async handleReceive(message: Envelope): Promise<void> {
+    const record = this.captureObserver();
     const assertValid = this.validity();
     const { id, config, me } = await this.state();
     assertValid();
     if (message.to !== id) fail('recipient session ID mismatch (stale endpoint)');
     const sender = config.agents.find(a => a.sessionId === message.from);
     const busy = this.host.busy();
+    const metadata = { peerSessionId: message.from, peerName: sender?.name, correlationId: message.correlationId, kind: message.kind, busy };
     const notify = (purpose: string, content: string) => {
       assertValid();
-      this.host.deliver(`[Intercom ${purpose} from ${sender?.name ?? 'unconfigured worker'} (${message.from})]\n${content}`, busy);
+      record('host.submission', { ...metadata, outcome: 'attempted' });
+      try {
+        this.host.deliver(`[Intercom ${purpose} from ${sender?.name ?? 'unconfigured worker'} (${message.from})]\n${content}`, busy);
+        // A synchronous return is not Pi queue acceptance or model completion.
+        record('host.submission', { ...metadata, outcome: 'returned' });
+      } catch (error) {
+        record('host.submission', { ...metadata, outcome: 'failed', errorCode: observationError(error) });
+        throw error;
+      }
     };
     if (message.kind === 'registration' || message.kind === 'status') {
       requireCoordinator(config, id);
@@ -133,12 +220,15 @@ export class Intercom {
       if (message.kind === 'registration') {
         const projectDirectory = await directory(this.store.root, message.payload.projectDirectory as string);
         // No pending map, placeholder or configuration mutation.
+        record('registration.received', { ...metadata, port: message.payload.port as number });
         notify('registration', JSON.stringify({ sessionId: message.from, port: message.payload.port, projectDirectory }) + '\nThis is connection information, not a work assignment. Configure explicitly, then reload separately.');
       } else {
         if (sender) await this.store.update(id, c => {
           const entry = c.agents.find(a => a.sessionId === message.from && !a.coordinator);
           if (entry) entry.port = message.payload.port as number;
         }, assertValid);
+        record('status.received', { ...metadata, busy: message.payload.busy as boolean, port: message.payload.port as number });
+        if (sender) record('config.changed', { operation: 'port_update', peerSessionId: message.from, port: message.payload.port as number, outcome: 'written' });
         notify('status', JSON.stringify({ sessionId: message.from, port: message.payload.port, busy: message.payload.busy, configured: !!sender }));
       }
       return;
@@ -166,12 +256,14 @@ export class Intercom {
     fail('unsupported control');
   }
   async tool(operation: string, args: Record<string, unknown>): Promise<unknown> {
+    const record = this.captureObserver();
     const assertValid = this.validity();
     const { id, config, me } = await this.state();
     assertValid();
     if (operation === 'list') {
       if (!me) fail('anonymous intercom_list permissions unresolved (TODO); no coordinator privileges');
-      return config;
+      const dashboardPort = coordinator(config).dashboardPort;
+      return { ...config, dashboardUrl: dashboardPort === undefined ? null : `http://127.0.0.1:${dashboardPort}/` };
     }
     if (operation === 'report_status') { await this.report(); return { accepted: true }; }
     if (operation === 'send') {
@@ -182,15 +274,17 @@ export class Intercom {
     if (operation === 'stop_worker' || operation === 'close_worker') fail(UNSUPPORTED_CANCELLATION);
     if (operation === 'configure_worker') {
       await this.store.configure(id, args as unknown as Omit<Agent, 'coordinator'>, assertValid);
+      record('config.changed', { operation: 'configure_worker', peerSessionId: args.sessionId as string, peerName: args.name as string, outcome: 'written' });
       return { written: true, reloaded: false };
     }
     if (operation === 'set_multiplexer') {
-      await this.store.update(id, c => { c.multiplexer = args.multiplexer as Config['multiplexer']; }, assertValid); return { written: true };
+      await this.store.update(id, c => { c.multiplexer = args.multiplexer as Config['multiplexer']; }, assertValid);
+      record('config.changed', { operation: 'set_multiplexer', outcome: 'written' }); return { written: true };
     }
     if (operation === 'create_worker') {
       const relative = await directory(this.store.root, (args.projectDirectory as string | undefined) ?? '.');
       assertValid();
-      return this.options.launch({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative) });
+      return this.launchObserved({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative) });
     }
     const target = named(config, args.to as string);
     if (target.coordinator) fail('operation requires a worker target');
@@ -201,13 +295,27 @@ export class Intercom {
     if (operation === 'resume_worker') {
       const relative = await directory(this.store.root, target.projectDirectory);
       assertValid();
-      return this.options.launch({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative), sessionId: target.sessionId });
+      return this.launchObserved({ multiplexer: config.multiplexer, cwd: path.resolve(this.store.root, relative), sessionId: target.sessionId });
     }
     if (operation === 'remove_worker') {
       // No live process claim: the caller must explicitly ensure closure first.
       await this.store.update(id, c => { c.agents = c.agents.filter(a => a.sessionId !== target.sessionId); }, assertValid);
+      record('config.changed', { operation: 'remove_worker', peerSessionId: target.sessionId, peerName: target.name, outcome: 'removed' });
       return { removed: true, processStopped: false, sessionDeleted: false };
     }
     fail(`unknown operation ${operation}`);
   }
+  private async launchObserved(request: LaunchRequest): Promise<unknown> {
+    const record = this.captureObserver();
+    const metadata: EventMetadata = { operation: request.sessionId ? 'resume_worker' : 'create_worker', peerSessionId: request.sessionId };
+    record('launch.result', { ...metadata, outcome: 'attempted' });
+    try {
+      const result = await this.options.launch(request);
+      record('launch.result', { ...metadata, outcome: 'returned' });
+      return result;
+    } catch (error) {
+      record('launch.result', { ...metadata, outcome: 'failed', errorCode: observationError(error) });
+      throw error;
+    }
+  }
 }

package/src/transport.ts

@@ -10,11 +10,14 @@ export interface Envelope {
   from: string;
   to: string;
   payload: Record<string, unknown>;
+  /** Optional diagnostics correlation only; never authentication or agent identity. */
+  correlationId?: string;
 }
 export function envelope(value: unknown): Envelope {
   const m = value as Envelope;
   if (!m || m.version !== 1 || !['message', 'registration', 'status', 'request_status', 'reload', 'stop', 'close'].includes(m.kind)) fail('invalid wire schema/version/kind');
   text(m.from, 'sender sessionId', 256); text(m.to, 'recipient sessionId', 256);
+  if (m.correlationId !== undefined && (typeof m.correlationId !== 'string' || !/^[a-zA-Z0-9-]{1,128}$/.test(m.correlationId))) fail('invalid correlation ID');
   if (!m.payload || Array.isArray(m.payload) || typeof m.payload !== 'object') fail('invalid payload');
   if (m.kind === 'message') text(m.payload.message, 'message', 48000);
   if (m.kind === 'registration' || m.kind === 'status') port(m.payload.port);