zooid 0.13.0 → 0.14.0

package/src/daemon/webhook-routes.ts

@@ -0,0 +1,202 @@
+import type { Context, Hono } from 'hono'
+import type { MatchContext, TriggerConfig, WebhookTriggerConfig } from '@zooid/core'
+import { evaluateMatch, renderTemplate } from '@zooid/core'
+import { fireTrigger, type FireTriggerDeps } from './trigger-runner.js'
+import { verifySignature, verifyCustomSignature, type CustomVerifier } from './webhook-verify.js'
+import { DeliveryCache } from './delivery-cache.js'
+
+// GitHub's delivery times out at 10s; a 1MB cap leaves headroom to hash and
+// respond well inside that even on a slow box. Checked before hashing, per
+// [[ZOD082]] §Design 4 rule 5.
+const MAX_BODY = 1_000_000
+// `${output}` is a chat message body, not a blob store — cap it well under
+// Matrix's ~64KiB event-size ceiling once the surrounding `text:` is added.
+const MAX_OUTPUT_CHARS = 60_000
+const TRUNCATION_MARKER = '\n\n… (truncated)'
+// Comfortably past any provider's redelivery window.
+const DELIVERY_CACHE_TTL_MS = 24 * 60 * 60 * 1000
+
+const EVENT_HEADER_BY_PROVIDER: Partial<Record<WebhookTriggerConfig['provider'], string>> = {
+  github: 'x-github-event',
+}
+
+const DELIVERY_ID_HEADER_BY_PROVIDER: Partial<Record<WebhookTriggerConfig['provider'], string>> = {
+  github: 'x-github-delivery',
+  standard: 'webhook-id',
+}
+
+// Headers any supported provider might send, gathered once per request.
+const RELEVANT_HEADERS = [
+  'x-hub-signature-256',
+  'x-github-event',
+  'x-github-delivery',
+  'stripe-signature',
+  'x-slack-signature',
+  'x-slack-request-timestamp',
+  'webhook-signature',
+  'webhook-id',
+  'webhook-timestamp',
+] as const
+
+export interface WebhookDeps {
+  triggers: Record<string, TriggerConfig>
+  /**
+   * Verifier function per `provider: custom` trigger name, imported at
+   * daemon start by `loadCustomVerifiers`. A custom trigger with no entry
+   * here rejects every delivery — fail closed.
+   */
+  customVerifiers?: Record<string, CustomVerifier>
+  agentUserIds: Record<string, string>
+  resolveRoom: FireTriggerDeps['resolveRoom']
+  ensureBot: FireTriggerDeps['ensureBot']
+  sendMessage: FireTriggerDeps['sendMessage']
+}
+
+/**
+ * Gather the headers verification might need. Named providers read a fixed
+ * set; `provider: custom` gets every header, lower-cased, since only the
+ * operator's verifier knows which ones its service sends.
+ */
+function headersOf(
+  c: { req: { header: (name: string) => string | undefined; raw: Request } },
+  all: boolean,
+): Record<string, string | undefined> {
+  const out: Record<string, string | undefined> = {}
+  if (all) {
+    c.req.raw.headers.forEach((value, key) => {
+      out[key.toLowerCase()] = value
+    })
+    return out
+  }
+  for (const h of RELEVANT_HEADERS) out[h] = c.req.header(h)
+  return out
+}
+
+/** Headers as a dense record, for handing to an operator's verifier. */
+function definedHeaders(headers: Record<string, string | undefined>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(headers)) {
+    if (v !== undefined) out[k] = v
+  }
+  return out
+}
+
+function renderPayload(raw: string): string {
+  let pretty: string
+  try {
+    pretty = JSON.stringify(JSON.parse(raw), null, 2)
+  } catch {
+    pretty = raw
+  }
+  if (pretty.length <= MAX_OUTPUT_CHARS) return pretty
+  return pretty.slice(0, MAX_OUTPUT_CHARS) + TRUNCATION_MARKER
+}
+
+async function handleDelivery(
+  deps: WebhookDeps,
+  name: string,
+  trigger: TriggerConfig,
+  raw: string,
+  headers: Record<string, string | undefined>,
+  cache: DeliveryCache,
+  customDeliveryId: string | undefined,
+): Promise<void> {
+  try {
+    const webhook = trigger.webhook
+    if (!webhook) return
+
+    const idHeader = DELIVERY_ID_HEADER_BY_PROVIDER[webhook.provider]
+    // A custom verifier reports its own delivery id, since only it knows
+    // where the service puts one.
+    const deliveryId = customDeliveryId ?? (idHeader ? headers[idHeader] : undefined)
+    if (deliveryId !== undefined && cache.seen(`${name}:${deliveryId}`)) return
+
+    const eventHeader = EVENT_HEADER_BY_PROVIDER[webhook.provider]
+    const event = eventHeader ? headers[eventHeader] : undefined
+
+    let body: unknown
+    try {
+      body = JSON.parse(raw)
+    } catch {
+      body = undefined
+    }
+
+    const ctx: MatchContext = {
+      event,
+      body,
+      headers: definedHeaders(headers),
+      output: renderPayload(raw),
+    }
+
+    for (const message of trigger.messages) {
+      if (message.match !== undefined && !evaluateMatch(message.match, ctx)) continue
+
+      const agentUserId = deps.agentUserIds[message.mention]
+      if (!agentUserId) {
+        console.warn(`[webhook:${name}] unknown agent "${message.mention}" — skipping`)
+        continue
+      }
+
+      await fireTrigger({
+        name,
+        as: trigger.as,
+        message: { ...message, text: renderTemplate(message.text, ctx) },
+        agentUserId,
+        resolveRoom: deps.resolveRoom,
+        ensureBot: deps.ensureBot,
+        sendMessage: deps.sendMessage,
+      })
+    }
+  } catch (err) {
+    // Never throw: the response has already been sent, and one bad delivery
+    // must not take down the daemon.
+    console.warn(`[webhook:${name}] failed:`, (err as Error).message)
+  }
+}
+
+export const WEBHOOK_ROUTE_PREFIX = '/_zooid/webhooks'
+
+export function mountWebhookRoutes(app: Hono, deps: WebhookDeps): void {
+  const cache = new DeliveryCache(DELIVERY_CACHE_TTL_MS)
+
+  const receive = async (c: Context<any, '/:name'>) => {
+    const name = c.req.param('name')
+    const trigger = deps.triggers[name]
+
+    // Read the RAW body first. Parsing and re-serializing changes the bytes
+    // and breaks every signature — the classic webhook bug.
+    const raw = await c.req.text()
+    if (raw.length > MAX_BODY) return c.text('too large', 413)
+
+    // Unknown trigger and bad signature return the identical response, so
+    // the endpoint cannot be probed to discover which triggers exist.
+    if (!trigger?.webhook) return c.text('unauthorized', 401)
+    const webhook = trigger.webhook
+    const headers = headersOf(c, webhook.provider === 'custom')
+
+    let customDeliveryId: string | undefined
+    if (webhook.provider === 'custom') {
+      const v = await verifyCustomSignature(deps.customVerifiers?.[name], {
+        rawBody: raw,
+        headers: definedHeaders(headers),
+        secret: webhook.secret,
+      })
+      if (!v.ok) return c.text('unauthorized', 401)
+      customDeliveryId = v.deliveryId
+    } else {
+      const v = verifySignature(webhook.provider, {
+        rawBody: raw,
+        headers,
+        secret: webhook.secret,
+      })
+      if (!v.ok) return c.text('unauthorized', 401)
+    }
+
+    // Accepted. Everything below is fire-and-forget: GitHub times out at
+    // 10s and an agent turn does not fit in that.
+    void handleDelivery(deps, name, trigger, raw, headers, cache, customDeliveryId)
+    return c.text('accepted', 202)
+  }
+
+  app.post(`${WEBHOOK_ROUTE_PREFIX}/:name`, receive)
+}

package/src/daemon/webhook-verify.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest'
+import { createHmac } from 'node:crypto'
+import { verifySignature, verifyCustomSignature, type CustomVerifierInput } from './webhook-verify.js'
+
+const secret = 'shh'
+const body = '{"action":"closed","number":42}'
+
+const githubSig = (b = body, s = secret) =>
+  `sha256=${createHmac('sha256', s).update(b).digest('hex')}`
+
+describe('verifySignature — github', () => {
+  it('accepts a correct signature over the raw body', () => {
+    expect(
+      verifySignature('github', { rawBody: body, headers: { 'x-hub-signature-256': githubSig() }, secret }),
+    ).toEqual({ ok: true })
+  })
+
+  it('rejects a signature computed over different bytes', () => {
+    expect(
+      verifySignature('github', {
+        rawBody: '{"action":"opened","number":42}',
+        headers: { 'x-hub-signature-256': githubSig() },
+        secret,
+      }).ok,
+    ).toBe(false)
+  })
+
+  it('rejects a signature made with a different secret', () => {
+    expect(
+      verifySignature('github', {
+        rawBody: body,
+        headers: { 'x-hub-signature-256': githubSig(body, 'wrong') },
+        secret,
+      }).ok,
+    ).toBe(false)
+  })
+
+  it('rejects a missing signature header — fail closed', () => {
+    expect(verifySignature('github', { rawBody: body, headers: {}, secret }).ok).toBe(false)
+  })
+
+  it('rejects a malformed header without throwing', () => {
+    for (const h of ['', 'sha256=', 'garbage', 'sha256=zzzz', 'sha1=abcd']) {
+      expect(() =>
+        verifySignature('github', { rawBody: body, headers: { 'x-hub-signature-256': h }, secret }),
+      ).not.toThrow()
+      expect(
+        verifySignature('github', { rawBody: body, headers: { 'x-hub-signature-256': h }, secret }).ok,
+      ).toBe(false)
+    }
+  })
+
+  it('rejects a signature of the wrong length without throwing (timingSafeEqual throws on length mismatch)', () => {
+    expect(
+      verifySignature('github', {
+        rawBody: body,
+        headers: { 'x-hub-signature-256': 'sha256=abcd' },
+        secret,
+      }).ok,
+    ).toBe(false)
+  })
+})
+
+describe('verifyCustomSignature', () => {
+  const shopifyish = ({ rawBody, headers, secret: sec }: CustomVerifierInput) => {
+    const expected = createHmac('sha256', sec).update(rawBody).digest('base64')
+    return { ok: headers['x-shopify-hmac-sha256'] === expected, deliveryId: headers['x-delivery'] }
+  }
+  const input = (headers: Record<string, string>) => ({ rawBody: body, headers, secret })
+  const sigOf = (b = body, s = secret) => createHmac('sha256', s).update(b).digest('base64')
+
+  it('accepts what the operator function accepts, and passes back its delivery id', async () => {
+    expect(
+      await verifyCustomSignature(shopifyish, input({ 'x-shopify-hmac-sha256': sigOf(), 'x-delivery': 'd9' })),
+    ).toEqual({ ok: true, deliveryId: 'd9' })
+  })
+
+  it('rejects what the operator function rejects', async () => {
+    expect(
+      (await verifyCustomSignature(shopifyish, input({ 'x-shopify-hmac-sha256': sigOf(body, 'wrong') }))).ok,
+    ).toBe(false)
+  })
+
+  it('accepts a verifier that returns a bare boolean', async () => {
+    expect(await verifyCustomSignature(() => true, input({}))).toEqual({ ok: true })
+    expect(await verifyCustomSignature(() => false, input({}))).toEqual({ ok: false })
+  })
+
+  it('awaits an async verifier', async () => {
+    expect(await verifyCustomSignature(async () => ({ ok: true, deliveryId: 'a1' }), input({}))).toEqual({
+      ok: true,
+      deliveryId: 'a1',
+    })
+  })
+
+  it('fails closed when no verifier is loaded — never "no verifier, so accept"', async () => {
+    expect(await verifyCustomSignature(undefined, input({}))).toEqual({ ok: false })
+  })
+
+  it('fails closed when the verifier throws or rejects', async () => {
+    expect(
+      (
+        await verifyCustomSignature(() => {
+          throw new Error('boom')
+        }, input({}))
+      ).ok,
+    ).toBe(false)
+    expect((await verifyCustomSignature(async () => Promise.reject(new Error('boom')), input({}))).ok).toBe(
+      false,
+    )
+  })
+
+  it('fails closed on a junk return value, rather than coercing it to true', async () => {
+    for (const junk of ['yes', 1, {}, { ok: 'true' }, null, undefined]) {
+      expect((await verifyCustomSignature((() => junk) as never, input({}))).ok).toBe(false)
+    }
+  })
+})
+
+describe('verifySignature — providers with a timestamp', () => {
+  const slackSig = (ts: string, b = body, s = secret) =>
+    `v0=${createHmac('sha256', s).update(`v0:${ts}:${b}`).digest('hex')}`
+
+  it('accepts a fresh slack signature over v0:ts:body', () => {
+    const ts = String(Math.floor(Date.now() / 1000))
+    expect(
+      verifySignature('slack', {
+        rawBody: body,
+        headers: { 'x-slack-signature': slackSig(ts), 'x-slack-request-timestamp': ts },
+        secret,
+      }),
+    ).toEqual({ ok: true })
+  })
+
+  it('rejects a slack signature outside the freshness window — replay defence', () => {
+    const old = String(Math.floor(Date.now() / 1000) - 60 * 60)
+    expect(
+      verifySignature('slack', {
+        rawBody: body,
+        headers: { 'x-slack-signature': slackSig(old), 'x-slack-request-timestamp': old },
+        secret,
+      }).ok,
+    ).toBe(false)
+  })
+
+  it('rejects a slack request with no timestamp header', () => {
+    expect(
+      verifySignature('slack', {
+        rawBody: body,
+        headers: { 'x-slack-signature': slackSig('123') },
+        secret,
+      }).ok,
+    ).toBe(false)
+  })
+})

package/src/daemon/webhook-verify.ts

@@ -0,0 +1,155 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import type { WebhookTriggerConfig } from '@zooid/core'
+
+const FRESHNESS_S = 300
+
+/**
+ * What an operator's `verify:` module is called with. `headers` carries every
+ * request header, lower-cased — a named provider reads a fixed set, but a
+ * custom verifier is the only thing that knows which ones its service sends.
+ */
+export interface CustomVerifierInput {
+  rawBody: string
+  headers: Record<string, string>
+  secret: string
+}
+
+/**
+ * An operator-supplied verifier. Returns a bare boolean, or a result that
+ * also carries the provider's unique delivery id — the id is what replay
+ * dedupe keys on, and only the verifier knows where the service puts it.
+ * Throwing counts as rejection; nothing it does can turn into an accept.
+ */
+export type CustomVerifier = (
+  input: CustomVerifierInput,
+) =>
+  | boolean
+  | { ok: boolean; deliveryId?: string }
+  | Promise<boolean | { ok: boolean; deliveryId?: string }>
+
+/** Providers whose signing scheme is built in. `custom` is verified by the operator's own function. */
+export type NamedProvider = Exclude<WebhookTriggerConfig['provider'], 'custom'>
+
+export interface VerifyInput {
+  rawBody: string
+  headers: Record<string, string | undefined>
+  secret: string
+}
+
+export type VerifyResult = { ok: true } | { ok: false }
+
+// Length-check first: timingSafeEqual throws when buffers differ in length.
+function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a, 'utf8')
+  const bb = Buffer.from(b, 'utf8')
+  return ab.length === bb.length && timingSafeEqual(ab, bb)
+}
+
+function hmacHex(secret: string, baseString: string): string {
+  return createHmac('sha256', secret).update(baseString).digest('hex')
+}
+
+function verifyGithub(input: VerifyInput): VerifyResult {
+  const header = input.headers['x-hub-signature-256']
+  if (!header) return { ok: false }
+  const [scheme, sig] = header.split('=')
+  if (scheme !== 'sha256' || !sig) return { ok: false }
+  const expected = hmacHex(input.secret, input.rawBody)
+  return safeEqual(sig, expected) ? { ok: true } : { ok: false }
+}
+
+function verifyStripe(input: VerifyInput): VerifyResult {
+  const header = input.headers['stripe-signature']
+  if (!header) return { ok: false }
+  const parts = Object.fromEntries(
+    header
+      .split(',')
+      .map((p) => p.split('=', 2) as [string, string | undefined])
+      .filter(([, v]) => v !== undefined),
+  )
+  const ts = parts.t
+  const sig = parts.v1
+  if (!ts || !sig) return { ok: false }
+  if (!isFresh(ts)) return { ok: false }
+  const expected = hmacHex(input.secret, `${ts}.${input.rawBody}`)
+  return safeEqual(sig, expected) ? { ok: true } : { ok: false }
+}
+
+function verifySlack(input: VerifyInput): VerifyResult {
+  const header = input.headers['x-slack-signature']
+  const ts = input.headers['x-slack-request-timestamp']
+  if (!header || !ts) return { ok: false }
+  if (!header.startsWith('v0=')) return { ok: false }
+  const sig = header.slice('v0='.length)
+  if (!isFresh(ts)) return { ok: false }
+  const expected = hmacHex(input.secret, `v0:${ts}:${input.rawBody}`)
+  return safeEqual(sig, expected) ? { ok: true } : { ok: false }
+}
+
+function verifyStandard(input: VerifyInput): VerifyResult {
+  const header = input.headers['webhook-signature']
+  const id = input.headers['webhook-id']
+  const ts = input.headers['webhook-timestamp']
+  if (!header || !id || !ts) return { ok: false }
+  if (!isFresh(ts)) return { ok: false }
+  const candidate = header
+    .split(' ')
+    .map((p) => (p.startsWith('v1,') ? p.slice('v1,'.length) : undefined))
+    .find((v) => v !== undefined)
+  if (!candidate) return { ok: false }
+  const expected = createHmac('sha256', input.secret)
+    .update(`${id}.${ts}.${input.rawBody}`)
+    .digest('base64')
+  return safeEqual(candidate, expected) ? { ok: true } : { ok: false }
+}
+
+function isFresh(tsRaw: string): boolean {
+  const ts = Number(tsRaw)
+  if (!Number.isFinite(ts)) return false
+  const nowS = Date.now() / 1000
+  return Math.abs(nowS - ts) <= FRESHNESS_S
+}
+
+const VERIFIERS: Record<NamedProvider, (input: VerifyInput) => VerifyResult> = {
+  github: verifyGithub,
+  stripe: verifyStripe,
+  slack: verifySlack,
+  standard: verifyStandard,
+}
+
+/**
+ * Verify a webhook delivery's signature. Every failure path returns
+ * `{ ok: false }` — nothing throws, and no reason is returned to the
+ * caller, since the route must not explain *why* it rejected a request.
+ */
+export function verifySignature(provider: NamedProvider, input: VerifyInput): VerifyResult {
+  try {
+    return VERIFIERS[provider](input)
+  } catch {
+    return { ok: false }
+  }
+}
+
+/**
+ * Run an operator-supplied verifier for `provider: custom`. Fails closed on
+ * every abnormal path — no verifier loaded, a throw, a rejected promise, or
+ * a return value that is not a recognised shape. A verifier can only ever
+ * *grant* acceptance by explicitly returning true.
+ */
+export async function verifyCustomSignature(
+  verifier: CustomVerifier | undefined,
+  input: CustomVerifierInput,
+): Promise<{ ok: boolean; deliveryId?: string }> {
+  if (typeof verifier !== 'function') return { ok: false }
+  try {
+    const result = await verifier(input)
+    if (result === true) return { ok: true }
+    if (result === false || result === null || typeof result !== 'object') return { ok: false }
+    if (result.ok !== true) return { ok: false }
+    return typeof result.deliveryId === 'string'
+      ? { ok: true, deliveryId: result.deliveryId }
+      : { ok: true }
+  } catch {
+    return { ok: false }
+  }
+}

package/src/pi-extension-install.test.ts

@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { installPiExtension, resolvePiAgentDir } from './pi-extension-install.js'
+
+const dirs: string[] = []
+const scratch = () => { const dir = mkdtempSync(join(tmpdir(), 'zooid-pi-')); dirs.push(dir); return dir }
+afterEach(() => dirs.splice(0).forEach((dir) => rmSync(dir, { recursive: true, force: true })))
+
+describe('resolvePiAgentDir', () => {
+  it('resolves a relative PI_CODING_AGENT_DIR against each agent workdir', () => {
+    expect(
+      resolvePiAgentDir({
+        agentWorkdir: '/proj/agents/alice',
+        daemonHome: '/home/op',
+        env: { PI_CODING_AGENT_DIR: '.pi-agent' },
+      }),
+    ).toEqual({ dir: '/proj/agents/alice/.pi-agent', scope: 'project' })
+  })
+
+  it('honours an absolute override and falls back to the operator home', () => {
+    expect(
+      resolvePiAgentDir({
+        agentWorkdir: '/proj/agents/alice',
+        daemonHome: '/home/op',
+        env: { PI_CODING_AGENT_DIR: '/shared/pi' },
+      }),
+    ).toEqual({ dir: '/shared/pi', scope: 'project' })
+    expect(
+      resolvePiAgentDir({ agentWorkdir: '/proj/agents/alice', daemonHome: '/home/op', env: {} }),
+    ).toEqual({ dir: '/home/op/.pi/agent', scope: 'home' })
+  })
+})
+
+describe('installPiExtension', () => {
+  it('only installs into an existing Pi home and preserves other extensions', () => {
+    const home = scratch(); const source = join(scratch(), 'bundle.js')
+    writeFileSync(source, '// bundle')
+    const agentDir = join(home, '.pi', 'agent')
+    expect(installPiExtension({ agentDir, bundlePath: source })).toMatchObject({ status: 'skipped' })
+    expect(existsSync(join(home, '.pi'))).toBe(false)
+    const extensions = join(agentDir, 'extensions')
+    mkdirSync(extensions, { recursive: true }); writeFileSync(join(extensions, 'user.js'), '// user')
+    expect(installPiExtension({ agentDir, bundlePath: source })).toMatchObject({ status: 'installed' })
+    expect(readFileSync(join(extensions, 'zooid-tasks.js'), 'utf8')).toBe('// bundle')
+    expect(readFileSync(join(extensions, 'user.js'), 'utf8')).toBe('// user')
+    expect(installPiExtension({ agentDir, bundlePath: source })).toMatchObject({ status: 'unchanged' })
+  })
+
+  it('creates a project agent dir that does not exist yet', () => {
+    const workdir = scratch(); const source = join(scratch(), 'bundle.js')
+    writeFileSync(source, '// bundle')
+    const { dir } = resolvePiAgentDir({
+      agentWorkdir: workdir,
+      daemonHome: '/home/op',
+      env: { PI_CODING_AGENT_DIR: '.pi-agent' },
+    })
+    expect(installPiExtension({ agentDir: dir, bundlePath: source, createMissing: true })).toMatchObject({
+      status: 'installed',
+      target: join(workdir, '.pi-agent', 'extensions', 'zooid-tasks.js'),
+    })
+    expect(readFileSync(join(workdir, '.pi-agent', 'extensions', 'zooid-tasks.js'), 'utf8')).toBe('// bundle')
+  })
+})

package/src/pi-extension-install.ts

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+export interface InstallPiExtensionResult {
+  status: 'installed' | 'unchanged' | 'skipped'
+  reason?: string
+  target?: string
+}
+
+export interface PiAgentDir {
+  dir: string
+  /** `project` dirs are ours to create; `home` is the operator's ~/.pi. */
+  scope: 'project' | 'home'
+}
+
+/**
+ * Resolve pi's agent dir the way pi does: PI_CODING_AGENT_DIR when set,
+ * otherwise ~/.pi/agent.  `zooid init` writes that variable as a *relative*
+ * path on purpose (ZOD075) so one value is correct under both runtimes — it
+ * resolves against the agent's cwd, and `agents/<name>` locally and
+ * `/workspace` in a container are the same directory.  We always resolve
+ * against the host workdir, which is the host side of that same mount.
+ */
+export function resolvePiAgentDir(opts: {
+  agentWorkdir: string
+  daemonHome: string
+  env?: { PI_CODING_AGENT_DIR?: string | undefined }
+}): PiAgentDir {
+  const override = opts.env?.PI_CODING_AGENT_DIR
+  if (override) {
+    return {
+      dir: isAbsolute(override) ? override : resolve(opts.agentWorkdir, override),
+      scope: 'project',
+    }
+  }
+  return { dir: join(opts.daemonHome, '.pi', 'agent'), scope: 'home' }
+}
+
+/** Install our bundle without replacing an operator's existing Pi extensions. */
+export function installPiExtension(opts: {
+  agentDir: string
+  bundlePath: string
+  /** Project dirs belong to the workspace, so we may create them. ~/.pi is the
+   *  operator's: install into it only if they already use pi. */
+  createMissing?: boolean
+}): InstallPiExtensionResult {
+  if (!opts.createMissing && !existsSync(opts.agentDir)) {
+    return { status: 'skipped', reason: 'no Pi home' }
+  }
+  const target = join(opts.agentDir, 'extensions', 'zooid-tasks.js')
+  mkdirSync(dirname(target), { recursive: true })
+  const source = readFileSync(opts.bundlePath)
+  if (existsSync(target) && readFileSync(target).equals(source)) return { status: 'unchanged', target }
+  writeFileSync(target, source)
+  return { status: 'installed', target }
+}