zooid 0.9.0 → 0.9.1

package/src/commands/init.ts

@@ -21,9 +21,9 @@ export interface InitOptions {
   preset: 'claude' | 'codex' | 'opencode'
   /** Required for claude/codex; ignored for opencode. */
   auth?: 'subscription' | 'api-key'
-  /** Required for claude/codex; required for opencode (paired with `provider`). */
+  /** Optional model pin. Omitted by default — the harness uses its own default. */
   model?: string
-  /** Required for opencode. */
+  /** opencode provider id; defaults to `opencode-go` in the wizard. */
   provider?: string
   /** Required on api-key path; required for opencode. */
   apiKey?: string
@@ -68,7 +68,6 @@ export async function runInit(opts: InitOptions): Promise<void> {
   const writes: WriteSpec[] = []
 
   if (opts.preset === 'claude' || opts.preset === 'codex') {
-    if (!opts.model) throw new Error(`--model is required for preset ${opts.preset}`)
     if (!opts.auth) throw new Error('--auth (subscription|api-key) is required for claude/codex')
     const meta = findSimplePreset(opts.preset)!
 
@@ -101,7 +100,6 @@ export async function runInit(opts: InitOptions): Promise<void> {
     const isCustom = opts.provider === 'custom'
     const providerMeta = isCustom ? undefined : findOpencodeProvider(opts.provider)
     if (!isCustom && !providerMeta) throw new Error(`unknown opencode provider: ${opts.provider}`)
-    if (!isCustom && !opts.model) throw new Error('--model is required (paired with --provider)')
     if (!isCustom && !opts.apiKey) throw new Error('--api-key is required for opencode')
 
     writes.push({ path: 'zooid.yaml', content: generateZooidYaml({ preset: 'opencode' }) })

package/src/daemon/pull-wiring.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { shouldBindHttpListener } from './pull-wiring.js'
+
+describe('shouldBindHttpListener', () => {
+  it('binds in appservice (push) mode — homeserver pushes to the daemon', () => {
+    expect(shouldBindHttpListener('appservice')).toBe(true)
+  })
+  it('does NOT bind in client (pull) mode — daemon polls outbound /sync', () => {
+    expect(shouldBindHttpListener('client')).toBe(false)
+  })
+  it('defaults to binding when mode is undefined', () => {
+    expect(shouldBindHttpListener(undefined)).toBe(true)
+  })
+})

package/src/daemon/pull-wiring.ts

@@ -0,0 +1,4 @@
+/** Push (`appservice`) binds an inbound listener; pull (`client`) does not. */
+export function shouldBindHttpListener(mode: 'appservice' | 'client' | undefined): boolean {
+  return mode !== 'client'
+}

package/src/daemon/start-daemon-pull.integration.test.ts

@@ -0,0 +1,95 @@
+import { mkdtempSync, rmSync, writeFileSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { startDaemon } from './start-daemon.js'
+
+let dir: string
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'zooid-pull-'))
+})
+afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+// Permissive stub: bootstrap CS calls all succeed with a benign body; the
+// /sync endpoint returns one page (carrying next_batch `s-1`) then idles. The
+// idle page is *paced* (~150ms) to mimic the long-poll — SyncLoop.run() has no
+// inter-tick delay, so an instant stub would busy-loop. This proves the daemon
+// selects + drives the pull loop; event→runTurn dispatch is covered in ZOD064.
+function pullFetchStub() {
+  let synced = false
+  return vi.fn(async (input: string | URL) => {
+    const url = new URL(typeof input === 'string' ? input : input.toString())
+    if (url.pathname === '/_matrix/client/v3/sync') {
+      if (synced) {
+        await delay(150)
+        return new Response(JSON.stringify({ next_batch: 's-idle', rooms: { join: {} } }), {
+          status: 200,
+        })
+      }
+      synced = true
+      return new Response(JSON.stringify({ next_batch: 's-1', rooms: { join: {} } }), {
+        status: 200,
+      })
+    }
+    if (url.pathname.endsWith('/account/whoami')) {
+      return new Response(JSON.stringify({ user_id: '@laptop:zoon.eco' }), { status: 200 })
+    }
+    // createRoom / register / join / send / state — benign shapes.
+    if (url.pathname.endsWith('/createRoom')) {
+      return new Response(JSON.stringify({ room_id: '!stub:zoon.eco' }), { status: 200 })
+    }
+    return new Response('{}', { status: 200 })
+  }) as unknown as typeof globalThis.fetch
+}
+
+describe('startDaemon — matrix client (pull) mode', () => {
+  it('binds no HTTP listener, runs the sync loop, persists a cursor, stops cleanly', async () => {
+    const yamlPath = join(dir, 'zooid.yaml')
+    writeFileSync(
+      yamlPath,
+      [
+        'runtime: local',
+        'workstation: laptop',
+        'transports:',
+        '  matrix:',
+        '    homeserver: https://zoon.eco',
+        '    mode: client',
+        '    as_token: test-as-token',
+        '    hs_token: test-hs-token',
+        'agents:',
+        '  docs:',
+        '    workdir: .',
+        '    acp: { preset: claude }',
+        '    matrix:',
+        '      transport: matrix',
+        "      rooms: ['#general']",
+      ].join('\n'),
+    )
+
+    const agentsDir = join(dir, 'data', 'agents')
+    const handle = await startDaemon({
+      configPath: yamlPath,
+      installSignalHandlers: false,
+      agentsDir,
+      fetch: pullFetchStub(),
+    })
+
+    // (a) No inbound listener in pull mode.
+    expect(handle.port).toBe(0)
+    expect(handle.agentNames).toEqual(['docs'])
+
+    // (c) Cursor persisted for the agent after a sync page is consumed, beside
+    //     sessions.json under <agentsDir>/<agentName>/. run() ticks async.
+    const sincePath = join(agentsDir, 'docs', 'sync-since')
+    await vi.waitFor(() => expect(existsSync(sincePath)).toBe(true), {
+      timeout: 3000,
+      interval: 50,
+    })
+
+    // (b) Clean, idempotent shutdown stops the loop (no hanging long-poll).
+    await handle.stop()
+    await handle.stop()
+  })
+})

package/src/daemon/start-daemon.ts

@@ -24,6 +24,7 @@ import {
   startWorkforcePublisher,
   type AgentBinding,
   type PublisherHandle,
+  type SyncLoop,
 } from '@zooid/transport-matrix'
 import {
   SpawnRegistry,
@@ -32,6 +33,8 @@ import {
 } from '@zooid/context-mcp'
 import { buildAcpRegistry } from '../build-registry.js'
 import { prepullImages } from '../prepull-images.js'
+import { makeSyncCursorStore } from './sync-cursors.js'
+import { shouldBindHttpListener } from './pull-wiring.js'
 
 export interface StartDaemonOpts {
   configPath?: string
@@ -66,6 +69,11 @@ export interface StartDaemonOpts {
    * task instead of leaving the user staring at an unmoving spinner.
    */
   prepullLog?: (line: string) => void
+  /**
+   * Override the global fetch used by the daemon's MatrixClient. Test seam for
+   * driving pull mode against canned /sync responses without a homeserver.
+   */
+  fetch?: typeof globalThis.fetch
 }
 
 export interface DaemonHandle {
@@ -149,6 +157,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
   )
 
   let server: ServerType | null = null
+  let syncLoops: SyncLoop[] | undefined
   let stopped = false
   let resolveStopped!: () => void
   const whenStopped = new Promise<void>((r) => {
@@ -159,9 +168,17 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
   let port: number
 
   if (matrix) {
+    const mode = matrix.transport.mode ?? 'appservice'
+    // Pull (client) mode persists a per-agent `since` cursor for offline resume,
+    // so it needs a data dir. Push mode doesn't.
+    if (mode === 'client' && !opts.agentsDir) {
+      throw new Error('matrix client (pull) mode requires a data dir for since-cursor persistence')
+    }
+    const cursors = opts.agentsDir ? makeSyncCursorStore(opts.agentsDir) : undefined
     const client = new MatrixClient({
       homeserver: matrix.transport.homeserver,
       asToken: matrix.transport.as_token,
+      ...(opts.fetch ? { fetch: opts.fetch } : {}),
     })
     const mediaClient = new MediaClient({
       homeserver: matrix.transport.homeserver,
@@ -191,6 +208,9 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
       matrix.transport.user_namespace.split(':').slice(1).join(':').replace(/\\?\)?$/, '') ||
       new URL(matrix.transport.homeserver).hostname
     const asUserId = `@${matrix.transport.sender_localpart}:${serverName}`
+    // Pull mode's loadSince/saveSince are keyed by MXID; the cursor store is
+    // keyed by agent name. Translate via the bindings we just built.
+    const nameByUserId = new Map(bindings.map((b) => [b.userId, b.name]))
     const transport = createMatrixTransport({
       agents: registry,
       approvals,
@@ -200,13 +220,27 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
       adminUserId: opts.adminUserId,
       botUserId: asUserId,
       media: mediaClient,
+      mode,
+      loadSince: (uid) => {
+        const name = nameByUserId.get(uid)
+        return name && cursors ? cursors.loadSince(name) : null
+      },
+      saveSince: (uid, since) => {
+        const name = nameByUserId.get(uid)
+        if (name && cursors) cursors.saveSince(name, since)
+      },
     })
-    const requestedPort = matrix.transport.port ?? 9000
-    // Bind 0.0.0.0 explicitly — @hono/node-server defaults to IPv6-only on
-    // macOS, which Docker's NAT bridge can't reach when Tuwunel pushes AS
-    // events back to host.docker.internal:<port>.
-    server = serve({ fetch: transport.app.fetch, port: requestedPort, hostname: '0.0.0.0' })
-    port = await listenAsync(server)
+    if (shouldBindHttpListener(mode)) {
+      const requestedPort = matrix.transport.port ?? 9000
+      // Bind 0.0.0.0 explicitly — @hono/node-server defaults to IPv6-only on
+      // macOS, which Docker's NAT bridge can't reach when Tuwunel pushes AS
+      // events back to host.docker.internal:<port>.
+      server = serve({ fetch: transport.app.fetch, port: requestedPort, hostname: '0.0.0.0' })
+      port = await listenAsync(server)
+    } else {
+      // Pull (client) mode runs outbound /sync loops; no inbound listener.
+      port = 0
+    }
     const spaceLocalpart = matrix.transport.space ?? 'dev'
     const adminUserIds = opts.adminUserId ? [opts.adminUserId] : []
     let spaceRoomId: string | undefined
@@ -233,6 +267,14 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
     // m.space.child while joining it.
     await transport.bootstrap({ spaceRoomId, asUserId, adminUserIds })
 
+    // Pull mode: start the outbound /sync loops after bootstrap so the rooms
+    // each agent syncs already exist. Loops long-poll until stop().
+    syncLoops = transport.syncLoops
+    if (syncLoops?.length) {
+      for (const loop of syncLoops) void loop.run()
+      console.log(`[matrix] pull mode: ${syncLoops.length} sync loop(s) running`)
+    }
+
     if (spaceRoomId) {
       try {
         const generalRoomId = await ensureDefaultChannel({
@@ -272,6 +314,11 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
   const stop = async (): Promise<void> => {
     if (stopped) return whenStopped
     stopped = true
+    try {
+      if (syncLoops) for (const loop of syncLoops) loop.stop()
+    } catch {
+      // swallow
+    }
     try {
       if (server) await closeAsync(server)
     } catch {

package/src/daemon/sync-cursors.test.ts

@@ -0,0 +1,38 @@
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { makeSyncCursorStore } from './sync-cursors.js'
+
+let agentsDir: string
+beforeEach(() => {
+  agentsDir = mkdtempSync(join(tmpdir(), 'zooid-agents-'))
+})
+afterEach(() => rmSync(agentsDir, { recursive: true, force: true }))
+
+describe('makeSyncCursorStore', () => {
+  it('returns null before any save (cold start)', () => {
+    const store = makeSyncCursorStore(agentsDir)
+    expect(store.loadSince('docs')).toBeNull()
+  })
+
+  it('round-trips a since cursor per agent name', () => {
+    const store = makeSyncCursorStore(agentsDir)
+    store.saveSince('docs', 's42')
+    store.saveSince('triage', 's7')
+    expect(store.loadSince('docs')).toBe('s42')
+    expect(store.loadSince('triage')).toBe('s7')
+  })
+
+  it('persists across store instances (simulates daemon restart)', () => {
+    makeSyncCursorStore(agentsDir).saveSince('docs', 's99')
+    expect(makeSyncCursorStore(agentsDir).loadSince('docs')).toBe('s99')
+  })
+
+  it('writes sync-since beside sessions.json under <agentsDir>/<agentName>/', () => {
+    makeSyncCursorStore(agentsDir).saveSince('docs', 's1')
+    const path = join(agentsDir, 'docs', 'sync-since')
+    expect(existsSync(path)).toBe(true)
+    expect(readFileSync(path, 'utf8')).toBe('s1')
+  })
+})

package/src/daemon/sync-cursors.ts

@@ -0,0 +1,31 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface SyncCursorStore {
+  loadSince(agentName: string): string | null
+  saveSince(agentName: string, since: string): void
+}
+
+/**
+ * File-backed `since` cursor store: `<agentsDir>/<agentName>/sync-since`, next
+ * to the `(threadId → sessionId)` `sessions.json` buildAcpRegistry writes. Same
+ * per-agent durable-state root, so an agent's restart-surviving state lives in
+ * one folder. Agent names are validated kebab-case keys (ZOD063 isValidAgentKey),
+ * so they're safe path segments — no hashing needed.
+ */
+export function makeSyncCursorStore(agentsDir: string): SyncCursorStore {
+  const fileFor = (agentName: string): string => join(agentsDir, agentName, 'sync-since')
+  return {
+    loadSince(agentName) {
+      try {
+        return readFileSync(fileFor(agentName), 'utf8').trim() || null
+      } catch {
+        return null
+      }
+    },
+    saveSince(agentName, since) {
+      mkdirSync(join(agentsDir, agentName), { recursive: true })
+      writeFileSync(fileFor(agentName), since, 'utf8')
+    },
+  }
+}

package/src/web/resolve.test.ts

@@ -16,7 +16,7 @@ afterEach(() => {
 function makeSibling(rootDir: string): { cliRoot: string; webDist: string } {
   const cliRoot = join(rootDir, 'zooid', 'packages', 'cli')
   mkdirSync(cliRoot, { recursive: true })
-  const webPkg = join(rootDir, 'zoon', 'packages', 'web')
+  const webPkg = join(rootDir, 'zooid-clients', 'packages', 'web')
   const webDist = join(webPkg, 'dist')
   mkdirSync(webDist, { recursive: true })
   writeFileSync(join(webPkg, 'package.json'), '{"name":"@zooid/web"}')
@@ -69,7 +69,7 @@ describe('ensureWebRoot', () => {
 describe('webSourcePackage', () => {
   it('returns the source package dir when sibling zooid-clients/packages/web exists', () => {
     const { cliRoot } = makeSibling(root)
-    expect(webSourcePackage(cliRoot)).toBe(join(root, 'zoon', 'packages', 'web'))
+    expect(webSourcePackage(cliRoot)).toBe(join(root, 'zooid-clients', 'packages', 'web'))
   })
 
   it('returns null outside the monorepo', () => {

package/src/web/resolve.ts

@@ -35,9 +35,9 @@ export async function ensureWebRoot(opts: EnsureWebRootOptions): Promise<string>
 
 // Returns the path to the in-tree @zooid/web package (zooid-clients/packages/web) if the
 // CLI is running from the monorepo source. Returns null when running from an
-// installed package (no sibling zoon/ tree).
+// installed package (no sibling zooid-clients/ tree).
 export function webSourcePackage(cliRoot: string): string | null {
   const workspaceRoot = dirname(dirname(dirname(cliRoot)))
-  const candidate = join(workspaceRoot, 'zoon', 'packages', 'web')
+  const candidate = join(workspaceRoot, 'zooid-clients', 'packages', 'web')
   return existsSync(join(candidate, 'package.json')) ? candidate : null
 }