@zooid/pi-extension 0.13.1

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@zooid/pi-extension",
+  "version": "0.13.1",
+  "description": "Native Pi extension exposing Zooid context and task tools.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./bundle": "./dist/zooid-tasks.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@zooid/context-mcp": "^0.14.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/extension.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest'
+import createExtension from './extension.js'
+
+function harness(reply: unknown = { ok: true, result: { messages: [] } }) {
+  const tools: Array<any> = []
+  const handlers: Record<string, Function> = {}
+  let active: string[] = []
+  const pi = {
+    registerTool: (tool: any) => {
+      tools.push(tool)
+      active.push(tool.name)
+    },
+    on: (event: string, handler: Function) => {
+      handlers[event] = handler
+    },
+    getActiveTools: () => active,
+    setActiveTools: (names: string[]) => {
+      active = names
+    },
+    getAllTools: () => tools.map((t) => ({ name: t.name })),
+  }
+  const calls: Array<any> = []
+  createExtension(pi as any, {
+    resolve: async (request) => {
+      calls.push(request)
+      return reply as any
+    },
+  })
+  return { tools, calls, handlers, activeTools: () => active }
+}
+const ctx = (sessionId = 'session-a') => ({ sessionManager: { getSessionId: () => sessionId } })
+
+describe('Pi Zooid extension', () => {
+  it('registers the renamed surface plus the two new tools', () => {
+    const { tools } = harness()
+    expect(tools.map((t) => t.name).sort()).toEqual([
+      'zooid_complete_task', 'zooid_get_history', 'zooid_get_members',
+      'zooid_get_recent_threads', 'zooid_get_room_info', 'zooid_get_rooms',
+      'zooid_get_thread_history', 'zooid_send_message', 'zooid_start_task_threads',
+    ])
+  })
+
+  it('carries the wake contract in promptGuidelines', () => {
+    const { tools } = harness()
+    const start = tools.find((t) => t.name === 'zooid_start_task_threads')
+    expect(start.promptGuidelines.join(' ')).toMatch(/zooid_start_task_threads/)
+    expect(start.promptGuidelines.join(' ')).toMatch(/end your turn/i)
+  })
+
+  it('uses the session from ctx for every call and defaults task notifications', async () => {
+    const { tools, calls } = harness({ ok: true, result: { results: [] } })
+    await tools.find((tool) => tool.name === 'zooid_start_task_threads').execute(
+      'call', { tasks: [{ agent: 'reviewer', prompt: 'review this' }] }, undefined, undefined, ctx('alpha'),
+    )
+    await tools.find((tool) => tool.name === 'zooid_complete_task').execute(
+      'call', { summary: 'done' }, undefined, undefined, ctx('beta'),
+    )
+    expect(calls).toEqual([
+      { acpSessionId: 'alpha', method: 'startTasks', params: { tasks: [{ agent: 'reviewer', prompt: 'review this' }], notify: 'caller' } },
+      { acpSessionId: 'beta', method: 'completeTask', params: { summary: 'done' } },
+    ])
+  })
+
+  it('maps read tools to the daemon methods and clamps pagination', async () => {
+    const { tools, calls } = harness()
+    await tools.find((tool) => tool.name === 'zooid_get_history').execute('c', { limit: 5000 }, undefined, undefined, ctx())
+    await tools.find((tool) => tool.name === 'zooid_get_thread_history').execute('c', { thread_id: '$root', before: 'cursor' }, undefined, undefined, ctx())
+    expect(calls).toEqual([
+      { acpSessionId: 'session-a', method: 'getRoomHistory', params: { limit: 200 } },
+      { acpSessionId: 'session-a', method: 'getThreadHistory', params: { threadId: '$root', limit: 50, before: 'cursor' } },
+    ])
+  })
+
+  it('zooid_send_message forwards room, thread_id and text', async () => {
+    const { tools, calls } = harness({ ok: true, result: { event_id: '$e' } })
+    await tools.find((tool) => tool.name === 'zooid_send_message').execute(
+      'c', { room: '!a:localhost', thread_id: '$t', text: 'noted' }, undefined, undefined, ctx(),
+    )
+    expect(calls).toEqual([
+      { acpSessionId: 'session-a', method: 'sendMessage', params: { room: '!a:localhost', thread_id: '$t', text: 'noted' } },
+    ])
+  })
+
+  it('zooid_get_rooms maps to getRooms with no params', async () => {
+    const { tools, calls } = harness({ ok: true, result: { rooms: [] } })
+    await tools.find((tool) => tool.name === 'zooid_get_rooms').execute('c', {}, undefined, undefined, ctx())
+    expect(calls).toEqual([{ acpSessionId: 'session-a', method: 'getRooms', params: {} }])
+  })
+
+  it('returns readable errors for unbound sessions and invalid completion summaries', async () => {
+    const { tools } = harness({ ok: false, error: 'unknown session: orphan' })
+    const unbound = await tools.find((tool) => tool.name === 'zooid_get_members').execute('c', {}, undefined, undefined, ctx('orphan'))
+    const invalid = await tools.find((tool) => tool.name === 'zooid_complete_task').execute('c', { summary: '  ' }, undefined, undefined, ctx())
+    expect(unbound).toMatchObject({ isError: true })
+    expect(unbound.content[0].text).toMatch(/not bound/i)
+    expect(invalid).toMatchObject({ isError: true })
+  })
+
+  it('disables complete_task for a non-assignee on session_start', async () => {
+    const { handlers, activeTools } = harness({
+      ok: true, result: { is_task_assignee: false, can_start_task_threads: true },
+    })
+    await handlers.session_start?.({ reason: 'startup' }, ctx('alpha'))
+    expect(activeTools()).toContain('zooid_start_task_threads')
+    expect(activeTools()).not.toContain('zooid_complete_task')
+  })
+
+  it('disables start_task_threads for an assignee on session_start', async () => {
+    const { handlers, activeTools } = harness({
+      ok: true, result: { is_task_assignee: true, can_start_task_threads: false },
+    })
+    await handlers.session_start?.({ reason: 'startup' }, ctx('beta'))
+    expect(activeTools()).toContain('zooid_complete_task')
+    expect(activeTools()).not.toContain('zooid_start_task_threads')
+  })
+
+  it('leaves the surface untouched when the role query fails', async () => {
+    const { handlers, tools, activeTools } = harness({ ok: false, error: 'binding not owned by caller' })
+    await handlers.session_start?.({ reason: 'startup' }, ctx('gamma'))
+    // Fail open: a daemon hiccup must not strip an assignee's ability to finish.
+    expect(activeTools().length === 0 || activeTools().length === tools.length).toBe(true)
+  })
+})

package/src/extension.ts

@@ -0,0 +1,188 @@
+import { callDaemon, type DaemonRequest } from '@zooid/context-mcp'
+
+interface ToolResult {
+  content: Array<{ type: 'text'; text: string }>
+  details?: Record<string, unknown>
+  isError?: boolean
+}
+interface ExtensionContext {
+  sessionManager?: { getSessionId?: () => string | undefined }
+}
+interface RegisteredTool {
+  name: string
+  label: string
+  description: string
+  parameters: unknown
+  /**
+   * Flat bullets appended to the system prompt while this tool is active —
+   * pi has no per-tool "Use this tool when…" slot, so anything that must
+   * name the tool explicitly (the wake contract) goes here.
+   */
+  promptGuidelines?: string[]
+  execute(
+    toolCallId: string,
+    params: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+    onUpdate: ((partial: unknown) => void) | undefined,
+    ctx: ExtensionContext,
+  ): Promise<ToolResult>
+}
+interface ExtensionAPI {
+  registerTool(tool: RegisteredTool): void
+  /** Registered during load or after startup, including from a session_start handler. */
+  on(event: string, handler: (evt: unknown, ctx: ExtensionContext) => void | Promise<void>): void
+  getActiveTools(): string[]
+  setActiveTools(names: string[]): void
+  getAllTools(): Array<{ name: string }>
+}
+
+type DaemonReply = { ok: true; result: unknown } | { ok: false; error: string }
+interface Deps {
+  resolve?: (request: DaemonRequest) => Promise<DaemonReply>
+}
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 200
+const pageParameters = {
+  type: 'object',
+  properties: {
+    limit: { type: 'integer', minimum: 1 },
+    before: { type: 'string' },
+  },
+} as const
+const noParameters = { type: 'object', properties: {} } as const
+
+function error(text: string): ToolResult {
+  return { content: [{ type: 'text', text }], isError: true }
+}
+
+/** Pi's extension entry point. Pi only passes `pi`; deps is a test seam. */
+export default function createExtension(pi: ExtensionAPI, deps: Deps = {}): void {
+  const resolve =
+    deps.resolve ??
+    (async (request: DaemonRequest): Promise<DaemonReply> => {
+      const sockPath = process.env.ZOOID_DAEMON_SOCK
+      if (!sockPath) throw new Error('ZOOID_DAEMON_SOCK is not set')
+      try {
+        return { ok: true, result: await callDaemon(sockPath, request) }
+      } catch (cause) {
+        return { ok: false, error: cause instanceof Error ? cause.message : String(cause) }
+      }
+    })
+
+  const call = async (
+    method: DaemonRequest['method'],
+    params: Record<string, unknown>,
+    ctx: ExtensionContext,
+  ): Promise<ToolResult> => {
+    const acpSessionId = ctx.sessionManager?.getSessionId?.()
+    if (!acpSessionId) return error('zooid: this Pi session has no id; cannot address a Zooid session.')
+    try {
+      const reply = await resolve({ acpSessionId, method, params })
+      if (!reply.ok) {
+        return error(
+          `zooid: this Pi session (${acpSessionId}) is not bound to a Zooid session — ${reply.error}.`,
+        )
+      }
+      return { content: [{ type: 'text', text: JSON.stringify(reply.result) }] }
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause)
+      return error(`zooid: could not reach the Zooid daemon (${message}).`)
+    }
+  }
+  const page = (params: Record<string, unknown>) => ({
+    limit: Math.min(Number(params.limit) || DEFAULT_LIMIT, MAX_LIMIT),
+    ...(typeof params.before === 'string' ? { before: params.before } : {}),
+  })
+  const registerRead = (
+    name: string,
+    label: string,
+    description: string,
+    method: DaemonRequest['method'],
+    parameters: unknown = pageParameters,
+    map: (params: Record<string, unknown>) => Record<string, unknown> = page,
+  ) => pi.registerTool({ name, label, description, parameters, execute: (_id, params, _signal, _update, ctx) => call(method, map(params), ctx) })
+
+  registerRead('zooid_get_history', 'Read room history', 'Read every message in the current room chronologically. Supports limit and before pagination.', 'getRoomHistory')
+  registerRead('zooid_get_recent_threads', 'Read recent threads', 'Scan the current room for top-level messages and thread roots, newest first.', 'getRecentThreads')
+  registerRead('zooid_get_thread_history', 'Read thread', 'Read a thread root and all its replies in chronological order.', 'getThreadHistory', {
+    ...pageParameters,
+    properties: { ...pageParameters.properties, thread_id: { type: 'string' } },
+    required: ['thread_id'],
+  }, (params) => ({ threadId: params.thread_id, ...page(params) }))
+  registerRead('zooid_get_members', 'List room members', 'List the humans and agents in the current room.', 'getChannelMembers', noParameters, () => ({}))
+  registerRead('zooid_get_room_info', 'Get room information', 'Describe the current room: id, display name, and transport kind.', 'getRoomInfo', noParameters, () => ({}))
+  registerRead('zooid_get_rooms', 'List rooms', 'List the rooms this agent is a member of. Valid targets for zooid_send_message.', 'getRooms', noParameters, () => ({}))
+
+  pi.registerTool({
+    name: 'zooid_send_message',
+    label: 'Send Zooid message',
+    description: 'Post a message into a room or thread this agent is bound to. Fire-and-forget: no assignee, no completion tracking, no notify. Use zooid_start_task_threads instead when the intent is delegation.',
+    parameters: {
+      type: 'object',
+      properties: {
+        room: { type: 'string' },
+        thread_id: { type: 'string' },
+        text: { type: 'string' },
+      },
+      required: ['room', 'text'],
+    },
+    async execute(_id, params, _signal, _update, ctx) {
+      return call('sendMessage', { room: params.room, thread_id: params.thread_id, text: params.text }, ctx)
+    },
+  })
+
+  pi.registerTool({
+    name: 'zooid_start_task_threads',
+    label: 'Start Zooid task threads',
+    description: 'Assign concurrent work to other agents in this room. Each task opens a separate thread. A delegated task cannot start tasks of its own. The return payload states how the result comes back — read `delivery` before deciding what to do next.',
+    promptGuidelines: [
+      'After calling zooid_start_task_threads, read the `delivery` field of its result and end your turn now when it tells you to — do not poll the task thread while waiting for a result.',
+    ],
+    parameters: {
+      type: 'object',
+      properties: {
+        tasks: { type: 'array', minItems: 1, items: { type: 'object', properties: { agent: { type: 'string' }, prompt: { type: 'string' } }, required: ['agent', 'prompt'] } },
+        notify: { enum: ['caller', 'none'] },
+      },
+      required: ['tasks'],
+    },
+    async execute(_id, params, _signal, _update, ctx) {
+      return call('startTasks', { tasks: params.tasks, notify: params.notify ?? 'caller' }, ctx)
+    },
+  })
+  pi.registerTool({
+    name: 'zooid_complete_task',
+    label: 'Complete Zooid task',
+    description: 'Record an explicit result for the delegated task you were assigned.',
+    parameters: { type: 'object', properties: { summary: { type: 'string', minLength: 1 } }, required: ['summary'] },
+    async execute(_id, params, _signal, _update, ctx) {
+      if (typeof params.summary !== 'string' || !params.summary.trim()) return error('zooid: summary must not be empty.')
+      return call('completeTask', { summary: params.summary }, ctx)
+    },
+  })
+
+  // Role-conditional gating ([[ZOD084]]). Fail open on any error — the read
+  // tools and zooid_start_task_threads/zooid_complete_task are already
+  // registered above, so the failure mode of gating is removing a
+  // capability rather than declining to add one. A daemon hiccup must not
+  // strip an assignee's ability to finish its task.
+  pi.on('session_start', async (_evt, ctx) => {
+    const acpSessionId = ctx.sessionManager?.getSessionId?.()
+    if (!acpSessionId) return
+    let reply: DaemonReply
+    try {
+      reply = await resolve({ acpSessionId, method: 'describeRole', params: {} })
+    } catch {
+      return
+    }
+    if (!reply.ok) return
+    const role = reply.result as { is_task_assignee: boolean; can_start_task_threads: boolean }
+    const next = new Set(pi.getAllTools().map((t) => t.name))
+    if (role.is_task_assignee) next.add('zooid_complete_task')
+    else next.delete('zooid_complete_task')
+    if (role.can_start_task_threads) next.add('zooid_start_task_threads')
+    else next.delete('zooid_start_task_threads')
+    pi.setActiveTools([...next])
+  })
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+import { createRequire } from 'node:module'
+
+/** Location of the self-contained extension installed by the Zooid daemon. */
+export function resolvePiExtensionBundle(): string {
+  return createRequire(import.meta.url).resolve('@zooid/pi-extension/bundle')
+}