zooid 0.15.0 → 0.16.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AcpRuntime, ApprovalCorrelator, TapEvent, ZooidConfig, AcpAgentRegistry } from '@zooid/core';
+import { AcpRuntime, ApprovalCorrelator, TapEvent, SessionLifecycleEvent, ZooidConfig, AcpAgentRegistry } from '@zooid/core';
 import { SpawnRegistry } from '@zooid/context-mcp';
 
 interface BuildAcpRegistryOptions {
@@ -8,6 +8,7 @@ interface BuildAcpRegistryOptions {
     approvals?: ApprovalCorrelator;
     /** Observability tap forwarded to each AcpClient. */
     onTap?: (agentName: string, event: TapEvent) => void;
+    onLifecycle?: (agentName: string, event: SessionLifecycleEvent) => void;
     /**
      * Per-agent state root (`<dataRoot>/agents/`). When set, each AcpClient
      * persists its `(threadId → sessionId)` map under

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   buildAcpRegistry
-} from "./chunk-35IKQPC5.js";
+} from "./chunk-HE7DVDJA.js";
 export {
   buildAcpRegistry
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zooid",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "An open-source, self-hostable chat app for collaborating with AI agents alongside your team. Any model, any CLI.",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "zooid": {
-    "webVersion": "0.12.1"
+    "webVersion": "0.13.0"
   },
   "engines": {
     "node": ">=22"
@@ -43,14 +43,14 @@
     "tar": "^7.5.16",
     "web-push": "^3.6.7",
     "yaml": "^2.5.0",
-    "@zooid/acp-client": "^0.15.0",
-    "@zooid/core": "^0.15.0",
-    "@zooid/context-mcp": "^0.15.0",
-    "@zooid/runtime-docker": "^0.15.0",
-    "@zooid/pi-extension": "^0.13.2",
-    "@zooid/runtime-local": "^0.15.0",
-    "@zooid/transport-matrix": "^0.15.0",
-    "@zooid/transport-http": "^0.15.0"
+    "@zooid/context-mcp": "^0.16.1",
+    "@zooid/acp-client": "^0.16.1",
+    "@zooid/runtime-local": "^0.16.1",
+    "@zooid/core": "^0.16.1",
+    "@zooid/pi-extension": "^0.13.3",
+    "@zooid/runtime-docker": "^0.16.1",
+    "@zooid/transport-matrix": "^0.16.1",
+    "@zooid/transport-http": "^0.16.1"
   },
   "devDependencies": {
     "@agentclientprotocol/sdk": "^0.21.0",

package/src/build-registry.context.test.ts

@@ -28,6 +28,7 @@ const matrixCfg: ZooidConfig = {
       hooks: {},
       acp: { command: 'fake', args: [] },
       approval_timeout_ms: 0,
+        session_idle_timeout_ms: 600_000,
       matrix: {
         transport: 'mx',
         user_id: '@architect:hs',

package/src/build-registry.test.ts

@@ -15,6 +15,7 @@ function cfg(overrides: Partial<ZooidConfig> & Pick<ZooidConfig, 'runtime'>): Zo
         hooks: {},
         acp: { preset: 'claude' },
         approval_timeout_ms: 0,
+        session_idle_timeout_ms: 600_000,
         http: { transport: 'http-local' },
       },
     },

package/src/build-registry.ts

@@ -10,6 +10,7 @@ import {
   type ContextSpawnFactory,
   type MountConfig,
   type TapEvent,
+  type SessionLifecycleEvent,
   type ZooidConfig,
   type TransportContextProvider,
 } from '@zooid/core'
@@ -29,6 +30,7 @@ export interface BuildAcpRegistryOptions {
   approvals?: ApprovalCorrelator
   /** Observability tap forwarded to each AcpClient. */
   onTap?: (agentName: string, event: TapEvent) => void
+  onLifecycle?: (agentName: string, event: SessionLifecycleEvent) => void
   /**
    * Per-agent state root (`<dataRoot>/agents/`). When set, each AcpClient
    * persists its `(threadId → sessionId)` map under
@@ -314,6 +316,7 @@ export function buildAcpRegistry(
     cwd: cwdByAgent,
     approvals: opts.approvals,
     onTap: opts.onTap,
+    onLifecycle: opts.onLifecycle,
     agentsDir: opts.agentsDir,
     contextSpawns,
     onSessionEstablished: (agentName, sessionKey, sessionId) =>

package/src/build-registry.zod043.test.ts

@@ -25,6 +25,7 @@ function makeCfg(over: Partial<ZooidConfig> = {}): ZooidConfig {
         hooks: {},
         acp: { preset: 'claude' },
         approval_timeout_ms: 0,
+        session_idle_timeout_ms: 600_000,
         matrix: {
           transport: 'm1',
           user_id: '@alice:localhost',

package/src/build-registry.zod044.test.ts

@@ -24,6 +24,7 @@ function mkCfg(over: Partial<ZooidConfig['agents']['alice']> = {}): ZooidConfig
         hooks: {},
         acp: { preset: 'claude' },
         approval_timeout_ms: 0,
+        session_idle_timeout_ms: 600_000,
         matrix: {
           transport: 'm1',
           user_id: '@alice:localhost',

package/src/commands/dev.ts

@@ -208,6 +208,7 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
             // the web client without needing an invite.
             publicWorkforceSpace: true,
             onTap: (agentName, event) => captures[agentName]?.onTap(event),
+            onLifecycle: (agentName, event) => captures[agentName]?.onLifecycle(event),
             prepullLog: (line) => {
               t.output = line.replace(/^\[zooid\]\s+/, '').trim()
             },
@@ -251,6 +252,8 @@ export async function runDev(flags: DevFlags): Promise<DevHandle> {
           const app = webStatic({
             webRoot,
             homeserverUrl: homeserver,
+            // Same default as the daemon's space provisioning (start-daemon.ts).
+            workforceSpace: matrix.transport.space ?? 'dev',
             ...(ctx.daemon?.vapidPublicKey
               ? {
                   // Tuwunel runs in a container; `localhost` here would

package/src/commands/start.ts

@@ -3,6 +3,7 @@ import { resolve } from 'node:path'
 import type { CliFlags } from '@zooid/core'
 import { resolveDataLayout } from '../bootstrap/data-layout.js'
 import { startDaemon } from '../daemon/start-daemon.js'
+import { logLifecycle } from '../observability/lifecycle-log.js'
 
 export interface StartFlags extends CliFlags {
   printToken?: boolean
@@ -21,6 +22,7 @@ export async function runStart(flags: StartFlags): Promise<void> {
     cliFlags: flags,
     installSignalHandlers: true,
     agentsDir: layout.agentsDir,
+    onLifecycle: (agentName, event) => logLifecycle(agentName, event),
   })
   console.log(`zooid listening on http://localhost:${handle.port}`)
   for (const name of handle.agentNames) console.log(`  agent: ${name}`)

package/src/daemon/start-daemon.ts

@@ -13,6 +13,7 @@ import {
   mergeCliFlags,
   type CliFlags,
   type TapEvent,
+  type SessionLifecycleEvent,
 } from '@zooid/core'
 import { createApp } from '@zooid/transport-http'
 import {
@@ -49,6 +50,7 @@ export interface StartDaemonOpts {
   adminUserId?: string
   /** Observability tap forwarded to each AcpClient. */
   onTap?: (agentName: string, event: TapEvent) => void
+  onLifecycle?: (agentName: string, event: SessionLifecycleEvent) => void
   /**
    * Per-agent state root (`<dataRoot>/agents/`). Threaded into
    * `buildAcpRegistry` so each AcpClient persists `sessionId`s across
@@ -137,6 +139,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
   const registry = buildAcpRegistry(config, {
     approvals,
     onTap: opts.onTap,
+    onLifecycle: opts.onLifecycle,
     agentsDir: opts.agentsDir,
     contextSpawnRegistry,
     daemonSockPaths: contextSockets.paths,

package/src/observability/capture-agent.ts

@@ -1,4 +1,4 @@
-import type { TapEvent } from '@zooid/core'
+import type { TapEvent, SessionLifecycleEvent } from '@zooid/core'
 import type { LogPaths } from './paths.js'
 import { JsonlSink, shouldCaptureUpdate, type Verbosity } from './file-sink.js'
 
@@ -19,13 +19,28 @@ export interface WireAgentCaptureOpts {
 
 export interface AgentCapture {
   onTap: (event: TapEvent) => void
+  onLifecycle: (event: SessionLifecycleEvent) => void
+  readLifecycleCounters: () => LifecycleCounters
   close: () => Promise<void>
 }
 
+export interface LifecycleCounters {
+  closeAttempts: number
+  closeSuccesses: number
+  sessionsReclaimed: number
+  recoveries: Record<'cached' | 'resume' | 'load' | 'new', number>
+}
+
 export function wireAgentCapture(opts: WireAgentCaptureOpts): AgentCapture {
   const sink = new JsonlSink(opts.paths.agentTap(opts.agent))
   const now = opts.now ?? (() => new Date())
   const pending: Promise<unknown>[] = []
+  const counters: LifecycleCounters = {
+    closeAttempts: 0,
+    closeSuccesses: 0,
+    sessionsReclaimed: 0,
+    recoveries: { cached: 0, resume: 0, load: 0, new: 0 },
+  }
 
   const onTap = (event: TapEvent): void => {
     if (event.kind === 'session_update') {
@@ -50,6 +65,25 @@ export function wireAgentCapture(opts: WireAgentCaptureOpts): AgentCapture {
 
   return {
     onTap,
+    onLifecycle: (event) => {
+      if (event.reason && event.outcome !== 'unsupported') counters.closeAttempts++
+      if (event.reason && event.outcome === 'closed') {
+        counters.closeSuccesses++
+        counters.sessionsReclaimed++
+      }
+      if (event.outcome === 'recovered' && event.recoveryMethod) counters.recoveries[event.recoveryMethod]++
+      pending.push(sink.write({
+        ts: now().toISOString(),
+        agent: opts.agent,
+        kind: 'session_lifecycle',
+        session_key: event.sessionKey,
+        session_id: event.sessionId,
+        reason: event.reason,
+        outcome: event.outcome,
+        recovery_method: event.recoveryMethod,
+      }))
+    },
+    readLifecycleCounters: () => ({ ...counters, recoveries: { ...counters.recoveries } }),
     close: async () => {
       await Promise.all(pending)
       await sink.close()

package/src/observability/lifecycle-log.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { SessionLifecycleEvent } from '@zooid/core'
+import { formatLifecycleLine, logLifecycle } from './lifecycle-log.js'
+
+const base = { agentId: 'architect', sessionKey: '$root', sessionId: 's-1' }
+
+function sink() {
+  return { log: vi.fn(), error: vi.fn() }
+}
+
+describe('lifecycle log', () => {
+  it('formats closes with reason and outcome', () => {
+    expect(formatLifecycleLine('architect', { ...base, reason: 'idle', outcome: 'closed' })).toBe(
+      '[lifecycle] architect key=$root session=s-1 idle → closed',
+    )
+    expect(formatLifecycleLine('architect', { ...base, reason: 'clear', outcome: 'closed' })).toBe(
+      '[lifecycle] architect key=$root session=s-1 clear → closed',
+    )
+  })
+
+  it('formats recoveries with their method', () => {
+    expect(
+      formatLifecycleLine('architect', { ...base, outcome: 'recovered', recoveryMethod: 'resume' }),
+    ).toBe('[lifecycle] architect key=$root session=s-1 recovered (resume)')
+  })
+
+  it('skips cached hits, which fire on every prompt to a live session', () => {
+    expect(
+      formatLifecycleLine('architect', { ...base, outcome: 'recovered', recoveryMethod: 'cached' }),
+    ).toBeNull()
+  })
+
+  it('routes failed closes to stderr and the rest to stdout', () => {
+    const out = sink()
+    logLifecycle('architect', { ...base, reason: 'idle', outcome: 'failed' }, out)
+    logLifecycle('architect', { ...base, reason: 'idle', outcome: 'closed' }, out)
+    expect(out.error).toHaveBeenCalledWith('[lifecycle] architect key=$root session=s-1 idle → failed')
+    expect(out.log).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips unsupported, which the ACP client already warns about', () => {
+    const out = sink()
+    const event: SessionLifecycleEvent = { ...base, reason: 'idle', outcome: 'unsupported' }
+    logLifecycle('architect', event, out)
+    expect(out.log).not.toHaveBeenCalled()
+    expect(out.error).not.toHaveBeenCalled()
+  })
+})

package/src/observability/lifecycle-log.ts

@@ -0,0 +1,29 @@
+import type { SessionLifecycleEvent } from '@zooid/core'
+
+/**
+ * One grep-able line per ACP session lifecycle event, for `zooid start`'s
+ * stdout/stderr ([ZOD089]). Carries identities and outcomes only — never
+ * prompt or transcript content. Skipped: `unsupported` (the ACP client
+ * already warns once per agent) and `cached` recoveries, which fire on every
+ * prompt to a live session and would add a line per message.
+ */
+export function formatLifecycleLine(agentName: string, event: SessionLifecycleEvent): string | null {
+  if (event.outcome === 'unsupported') return null
+  if (event.recoveryMethod === 'cached') return null
+  const what =
+    event.outcome === 'recovered'
+      ? `recovered (${event.recoveryMethod ?? 'unknown'})`
+      : `${event.reason ?? 'close'} → ${event.outcome}`
+  return `[lifecycle] ${agentName} key=${event.sessionKey} session=${event.sessionId} ${what}`
+}
+
+export function logLifecycle(
+  agentName: string,
+  event: SessionLifecycleEvent,
+  out: Pick<Console, 'log' | 'error'> = console,
+): void {
+  const line = formatLifecycleLine(agentName, event)
+  if (!line) return
+  if (event.outcome === 'failed') out.error(line)
+  else out.log(line)
+}

package/src/observability/observability.integration.test.ts

@@ -16,6 +16,28 @@ describe('agent capture end-to-end', () => {
     rmSync(dataDir, { recursive: true, force: true })
   })
 
+  it('captures lifecycle identity and counts only successful reclamation', async () => {
+    const now = new Date('2026-05-06T10:00:00Z')
+    const paths = resolveLogPaths({ dataDir, now })
+    await ensureDayFolder(paths)
+    const cap = wireAgentCapture({ agent: 'docs', paths, verbosity: 'default', matrixContext: () => null, now: () => now })
+    cap.onLifecycle({ agentId: 'docs', sessionKey: 'root', sessionId: 's1', outcome: 'recovered', recoveryMethod: 'new' })
+    cap.onLifecycle({ agentId: 'docs', sessionKey: 'root', sessionId: 's1', reason: 'idle', outcome: 'closed' })
+    cap.onLifecycle({ agentId: 'docs', sessionKey: 'root', sessionId: 's1', outcome: 'recovered', recoveryMethod: 'resume' })
+    cap.onLifecycle({ agentId: 'docs', sessionKey: 'root', sessionId: 's1', reason: 'clear', outcome: 'failed' })
+    expect(cap.readLifecycleCounters()).toEqual({
+      closeAttempts: 2,
+      closeSuccesses: 1,
+      sessionsReclaimed: 1,
+      recoveries: { cached: 0, resume: 1, load: 0, new: 1 },
+    })
+    await cap.close()
+    const rows = (await readFile(paths.agentTap('docs'), 'utf8')).trim().split('\n').map((line) => JSON.parse(line))
+    expect(rows).toHaveLength(4)
+    expect(rows[1]).toMatchObject({ kind: 'session_lifecycle', session_key: 'root', session_id: 's1', reason: 'idle', outcome: 'closed' })
+    expect(rows[1]).not.toHaveProperty('prompt_text')
+  })
+
   it('writes one JSONL line per tap event with envelope + turn correlation', async () => {
     const now = new Date('2026-05-06T10:00:00Z')
     const paths = resolveLogPaths({ dataDir, now })

package/src/web/static.test.ts

@@ -64,6 +64,20 @@ describe('webStatic', () => {
     })
   })
 
+  it('serves workforce_space when configured, default or custom', async () => {
+    for (const space of ['dev', 'hq']) {
+      const app = webStatic({
+        webRoot: dir,
+        homeserverUrl: 'http://localhost:8448',
+        workforceSpace: space,
+      })
+      expect(await (await app.request('/config.json')).json()).toEqual({
+        homeserver_url: 'http://localhost:8448',
+        workforce_space: space,
+      })
+    }
+  })
+
   it('omits both when unconfigured, so the client falls back instead of half-subscribing', async () => {
     const app = webStatic({ webRoot: dir, homeserverUrl: 'http://localhost:8448' })
     expect(await (await app.request('/config.json')).json()).toEqual({

package/src/web/static.ts

@@ -5,6 +5,8 @@ import { Hono } from 'hono'
 export interface WebStaticOpts {
   webRoot: string
   homeserverUrl: string
+  /** Workforce space alias localpart, copied from `matrix.space`. */
+  workforceSpace?: string
   pushGatewayUrl?: string
   vapidPublicKey?: string
 }
@@ -33,6 +35,7 @@ export function webStatic(opts: WebStaticOpts): Hono {
   app.get('/config.json', (c) =>
     c.json({
       homeserver_url: opts.homeserverUrl,
+      ...(opts.workforceSpace ? { workforce_space: opts.workforceSpace } : {}),
       ...(opts.pushGatewayUrl ? { push_gateway_url: opts.pushGatewayUrl } : {}),
       ...(opts.vapidPublicKey ? { vapid_public_key: opts.vapidPublicKey } : {}),
     }),