@xingular/harness 0.1.6 → 1.0.0

package/src/terminal/pluginControl.test.ts

@@ -1,146 +0,0 @@
-import { existsSync, mkdtempSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, describe, expect, it } from 'vitest'
-
-import { memorySecretStore } from '../accounts/secrets'
-import { createHarness, type Harness } from '../harness'
-import { runPluginsCli } from '../plugins/cli'
-import type { Plugin } from '../plugins/types'
-import { rootWithProject, writeFile } from '../../tests/helpers'
-import { SOCKET_ENV, TOKEN_ENV, socketCall, type SocketConnection } from './client'
-import { menuRows, rowActions, runPluginsMenu, type MenuUi } from './pluginMenu'
-
-const open: Harness[] = []
-afterEach(async () => {
-  for (const harness of open.splice(0)) await harness.close()
-})
-
-function kit(folder: string): void {
-  writeFile(join(folder, 'package.json'), JSON.stringify({ name: 'review-kit', description: 'Review helpers.', version: '1.0.0' }))
-  writeFile(join(folder, 'extensions/guard.ts'), 'export default function () {}\n')
-  writeFile(join(folder, 'skills/audit/SKILL.md'), '---\nname: audit\ndescription: Audit a change.\n---\nSteps.\n')
-}
-
-async function session() {
-  const root = rootWithProject()
-  const base = mkdtempSync(join(tmpdir(), 'control-'))
-  writeFile(join(root, 'registry/rules/tests.md'), '---\nname: Run tests\ndescription: Always test.\n---\nAlways run the tests.\n')
-  const harness = createHarness({ dataRoot: root, stateDir: join(base, 'state'), secrets: memorySecretStore(), piProgram: () => '/opt/pi/bin/pi', assets: { node: '/opt/node', cli: '/opt/harness/cli.js', piExtension: '/opt/harness/terminal-pi.js' } })
-  open.push(harness)
-  const account = harness.accounts.create('Main', 'apiKey').accounts[0]
-  harness.plugins.trust.adopt([])
-  kit(join(root, 'plugins/review-kit'))
-  const launch = await harness.terminals.prepare({ sessionId: 'term-1', accountId: account.id, projectId: 'p1', cwd: base, sessionFolder: join(root, 'sessions', 'p1', 'term-1') })
-  const connection: SocketConnection = { socket: String(launch.env[SOCKET_ENV]), token: String(launch.env[TOKEN_ENV]) }
-  return { harness, root, base, connection }
-}
-
-/** A person at the terminal, answering each dialog in turn from a script. */
-function person(answers: (string | boolean | undefined)[]) {
-  const shown: string[] = []
-  const said: string[] = []
-  const ui: MenuUi = {
-    select: async (title, options) => {
-      shown.push(`${title} → ${options.join(' | ')}`)
-      return answers.shift() as string | undefined
-    },
-    confirm: async (title, message) => {
-      shown.push(`${title} ${message}`)
-      return answers.shift() === true
-    },
-    notify: (message) => void said.push(message)
-  }
-  return { ui, shown, said }
-}
-
-describe('plugin control from a terminal session', () => {
-  it("lists for anyone in the session, and changes only for the session's own extension", async () => {
-    const { connection } = await session()
-    const listed = await socketCall<Plugin[]>(connection, 'plugins.list')
-    const plugin = listed.find((candidate) => candidate.id === 'package:review-kit')!
-    expect(plugin).toMatchObject({ trust: 'untrusted' })
-    // A command the model runs in the shell has the session token and nothing more.
-    await expect(socketCall(connection, 'plugins.trust', { hash: plugin.code!.hash })).rejects.toThrow('Only a person at this terminal can change plugins')
-    await expect(socketCall(connection, 'plugins.detach', { id: plugin.id })).rejects.toThrow('Only a person at this terminal')
-    await expect(socketCall(connection, 'plugins.trust', { hash: plugin.code!.hash }, 5_000, 'guessed')).rejects.toThrow('Only a person at this terminal')
-
-    // The extension claims the key as it loads. It is given out once.
-    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
-    await expect(socketCall(connection, 'control.claim')).rejects.toThrow('already claimed')
-    const trusted = await socketCall<Plugin[]>(connection, 'plugins.trust', { hash: plugin.code!.hash }, 5_000, key)
-    expect(trusted.find((candidate) => candidate.id === plugin.id)).toMatchObject({ trust: 'trusted' })
-    // Without "everywhere", a switch from a terminal is for the session's project.
-    const off = await socketCall<Plugin[]>(connection, 'plugins.detach', { id: plugin.id }, 5_000, key)
-    expect(off.find((candidate) => candidate.id === plugin.id)!.attachment).toEqual({ global: true, on: { agentIds: [], projectIds: [] }, off: { agentIds: [], projectIds: ['p1'] } })
-  })
-
-  it('walks a person through switching and trusting, and changes nothing they did not choose', async () => {
-    const { harness, connection } = await session()
-    const { key } = await socketCall<{ key: string }>(connection, 'control.claim')
-    const call = <T>(method: string, params?: Record<string, unknown>) => socketCall<T>(connection, method, params ?? {}, 5_000, key)
-    const rows = menuRows(await call<Plugin[]>('plugins.list'), 'p1')
-    expect(rows.map((row) => row.label)).toEqual(['● review-kit · code not trusted', '○ Run tests · instruction in Yours', '○ Budget guard · runs code', '○ Output trim · runs code'])
-    expect(rowActions(rows[0], 'p1')).toEqual(['Switch off for this project', 'Switch off everywhere', 'Trust its code', 'Back'])
-    expect(rowActions(rows[1], null)).toEqual(['Switch on everywhere', 'Back'])
-    // A part that ships with the harness needs no trust: it is the harness's own code.
-    expect(rowActions(rows[2], 'p1')).toEqual(['Switch on for this project', 'Switch on everywhere', 'Back'])
-
-    // Declining the trust question leaves the code untrusted; then they trust it, switch a rule on, and leave.
-    const { ui, shown, said } = person(['● review-kit · code not trusted', 'Trust its code', false, '● review-kit · code not trusted', 'Trust its code', true, '○ Run tests · instruction in Yours', 'Switch on for this project', 'Done'])
-    await runPluginsMenu(ui, call, 'p1')
-    expect(shown.find((line) => line.startsWith('Trust this code?'))).toContain('extensions/guard.ts')
-    expect(shown.find((line) => line.startsWith('Trust this code?'))).toContain('can do anything this app can')
-    expect(said).toEqual(['Saved. It applies when this session restarts.'])
-    const after = await call<Plugin[]>('plugins.list')
-    expect(after.find((plugin) => plugin.id === 'package:review-kit')).toMatchObject({ trust: 'trusted' })
-    expect(after.flatMap((plugin) => plugin.contributions).find((entry) => entry.id === 'yours/rules/tests')).toMatchObject({ state: 'on', scope: 'App' })
-    expect(harness.plugins.trust.list()).toHaveLength(1)
-
-    // Leaving at once changes nothing and says nothing.
-    const idle = person([undefined])
-    await runPluginsMenu(idle.ui, call, 'p1')
-    expect(idle.said).toEqual([])
-  })
-})
-
-describe('the plugins command', () => {
-  it('lists, installs, switches, trusts only on a yes, and removes, on its own data', async () => {
-    const base = mkdtempSync(join(tmpdir(), 'plugins-cli-'))
-    kit(join(base, 'kit'))
-    const lines: string[] = []
-    const run = (argv: string[], answer?: string) => runPluginsCli([...argv, '--data', join(base, 'data'), '--state', join(base, 'state')], { home: base, cwd: base, write: (text) => void lines.push(text), ...(answer === undefined ? {} : { ask: async () => answer }) })
-    const last = (): string => lines.at(-1) ?? ''
-
-    expect(await run(['list'])).toBe(0)
-    expect(last()).toMatch(/^memory\s+required\s+Memory$/m)
-    expect(await run(['install', join(base, 'kit')])).toBe(0)
-    expect(last()).toContain('Installed, switched off.')
-    expect(last()).toContain('trust its code with "plugins trust <id>"')
-    expect(await run(['list'])).toBe(0)
-    expect(last()).toMatch(/^package:review-kit\s+off, code not trusted\s+review-kit$/m)
-
-    expect(await run(['attach', 'package:review-kit'])).toBe(0)
-    expect(last()).toBe('package:review-kit is on everywhere. It applies from the next session start.\n')
-    // No terminal to ask on and no --yes: the files are shown and nothing is trusted.
-    expect(await run(['trust', 'package:review-kit'])).toBe(1)
-    expect(lines.at(-2)).toContain('extensions/guard.ts')
-    expect(last()).toBe('Read the files, then run this again with --yes to trust them.\n')
-    expect(await run(['trust', 'package:review-kit'], 'no')).toBe(1)
-    expect(last()).toBe('Not trusted.\n')
-    expect(await run(['trust', 'package:review-kit'], 'yes')).toBe(0)
-    expect(await run(['show', 'package:review-kit'])).toBe(0)
-    expect(last()).toContain('State: on')
-    expect(last()).toContain('Code (trusted)')
-    expect(last()).toContain('● skill audit (package:review-kit/skill/audit)')
-
-    expect(await run(['detach', 'memory'])).toBe(1)
-    expect(last()).toContain('Memory cannot be switched off.')
-    expect(await run(['untrust', 'package:review-kit'])).toBe(0)
-    expect(await run(['remove', 'package:review-kit'])).toBe(0)
-    expect(await run(['show', 'package:review-kit'])).toBe(1)
-    expect(await run(['nonsense'])).toBe(2)
-    // The folder that was installed in place is still the person's.
-    expect(existsSync(join(base, 'kit/package.json'))).toBe(true)
-  })
-})

package/src/terminal/pluginMenu.ts

@@ -1,112 +0,0 @@
-// The `/plugins` command of a terminal session, without Pi: what it lists, what it offers for
-// each row, and the conversation it has with the person. It asks through whatever interface it
-// is given (Pi's own dialogs in a terminal) and changes things through one function, so the
-// same flow is tested without a terminal.
-import type { Attachment } from '../plugins/attachments'
-import type { Contribution, Plugin } from '../plugins/types'
-
-export interface MenuUi {
-  select(title: string, options: string[]): Promise<string | undefined>
-  confirm(title: string, message: string): Promise<boolean>
-  notify(message: string, level?: 'info' | 'warning' | 'error'): void
-}
-
-/** `plugins.list`, `plugins.attach`, `plugins.detach`, `plugins.trust`, `plugins.untrust`. */
-export type MenuCall = <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T>
-
-export interface MenuRow {
-  /** The plugin's id, or one contribution's. */
-  id: string
-  label: string
-  on: boolean
-  /** The plugin it is, or belongs to. */
-  plugin: Plugin
-  /** Set when the row is the whole plugin. */
-  whole: boolean
-}
-
-const here = (attachment: Attachment, projectId: string | null): boolean => {
-  if (projectId && attachment.on.projectIds.includes(projectId)) return true
-  if (projectId && attachment.off.projectIds.includes(projectId)) return false
-  return attachment.global
-}
-
-const mark = (on: boolean): string => (on ? '●' : '○')
-
-/** What can be switched or trusted from here: each found or installed plugin, and each item of the rest that has a switch. */
-export function menuRows(plugins: readonly Plugin[], projectId: string | null): MenuRow[] {
-  const rows: MenuRow[] = []
-  for (const plugin of plugins) {
-    if (plugin.attachment) {
-      const on = here(plugin.attachment, projectId)
-      rows.push({ id: plugin.id, plugin, whole: true, on, label: `${mark(on)} ${plugin.title}${plugin.trust === 'untrusted' ? ' · code not trusted' : plugin.runsCode ? ' · runs code' : ''}` })
-      continue
-    }
-    if (plugin.trust !== 'none') rows.push({ id: plugin.id, plugin, whole: true, on: plugin.trust === 'trusted', label: `${mark(plugin.trust === 'trusted')} ${plugin.title} · ${plugin.trust === 'trusted' ? 'code trusted' : 'code not trusted'}` })
-    for (const entry of plugin.contributions) {
-      if (!entry.attachment) continue
-      rows.push({ id: entry.id, plugin, whole: false, on: entry.state === 'on', label: `${mark(entry.state === 'on')} ${entry.name} · ${kindWord(entry)} in ${plugin.title}` })
-    }
-  }
-  return rows
-}
-
-const kindWord = (entry: Contribution): string => (entry.kind === 'connection' ? 'connected app' : entry.kind === 'code' ? 'extension' : entry.kind)
-
-const SWITCH_OFF_PROJECT = 'Switch off for this project'
-const SWITCH_ON_PROJECT = 'Switch on for this project'
-const SWITCH_OFF_EVERYWHERE = 'Switch off everywhere'
-const SWITCH_ON_EVERYWHERE = 'Switch on everywhere'
-const TRUST = 'Trust its code'
-const UNTRUST = 'Stop trusting its code'
-const BACK = 'Back'
-const DONE = 'Done'
-
-/** What a person can do with one row. A whole plugin whose code waits for trust can be trusted here. */
-export function rowActions(row: MenuRow, projectId: string | null): string[] {
-  const switchable = row.whole ? row.plugin.attachment !== null : true
-  const actions: string[] = []
-  if (switchable) {
-    if (projectId) actions.push(row.on ? SWITCH_OFF_PROJECT : SWITCH_ON_PROJECT)
-    actions.push(row.on ? SWITCH_OFF_EVERYWHERE : SWITCH_ON_EVERYWHERE)
-  }
-  if (row.whole && row.plugin.code) actions.push(row.plugin.trust === 'untrusted' ? TRUST : UNTRUST)
-  return [...actions, BACK]
-}
-
-/**
- * Runs the command: list, pick a row, pick what to do, until the person is done. Nothing changes
- * without a choice made here, and trusting code asks once more with the files in view.
- */
-export async function runPluginsMenu(ui: MenuUi, call: MenuCall, projectId: string | null): Promise<void> {
-  let changed = false
-  for (;;) {
-    const rows = menuRows(await call<Plugin[]>('plugins.list'), projectId)
-    if (!rows.length) {
-      ui.notify('There is nothing to switch or trust here yet.', 'info')
-      return
-    }
-    const picked = await ui.select(`Plugins${changed ? ' (changes apply when this session restarts)' : ''}`, [...rows.map((row) => row.label), DONE])
-    const row = rows.find((candidate) => candidate.label === picked)
-    if (!row) break
-    const action = await ui.select(`${row.plugin.title}: ${row.plugin.description || 'No description.'}`, rowActions(row, projectId))
-    if (!action || action === BACK) continue
-    try {
-      if (action === TRUST || action === UNTRUST) {
-        const code = row.plugin.code!
-        if (action === TRUST) {
-          const sure = await ui.confirm('Trust this code?', `${code.files.join('\n')}\n\nFingerprint ${code.hash.slice(0, 12)}. It runs inside the session and can do anything this app can, including reading your files and credentials.`)
-          if (!sure) continue
-        }
-        await call(action === TRUST ? 'plugins.trust' : 'plugins.untrust', { hash: code.hash })
-      } else {
-        const on = action === SWITCH_ON_PROJECT || action === SWITCH_ON_EVERYWHERE
-        await call(on ? 'plugins.attach' : 'plugins.detach', { id: row.id, everywhere: action === SWITCH_ON_EVERYWHERE || action === SWITCH_OFF_EVERYWHERE })
-      }
-      changed = true
-    } catch (error) {
-      ui.notify(error instanceof Error ? error.message : String(error), 'error')
-    }
-  }
-  if (changed) ui.notify('Saved. It applies when this session restarts.', 'info')
-}

package/src/terminal/socket.test.ts

@@ -1,71 +0,0 @@
-import { chmodSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs'
-import { createConnection } from 'node:net'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { describe, expect, it } from 'vitest'
-
-import { SessionSocket, socketPath } from './socket'
-
-const handlers = { memory: () => '', apps: async () => null }
-
-/** Runs `body` as if on another operating system; `process.platform` is read at call time. */
-function onPlatform<T>(platform: NodeJS.Platform, body: () => T): T {
-  const original = Object.getOwnPropertyDescriptor(process, 'platform')!
-  Object.defineProperty(process, 'platform', { value: platform })
-  try {
-    return body()
-  } finally {
-    Object.defineProperty(process, 'platform', original)
-  }
-}
-
-describe('session socket path', () => {
-  it('keeps the socket file in the state folder on Unix', () => {
-    expect(onPlatform('darwin', () => socketPath('/tmp/state'))).toBe(join('/tmp/state', 'run', 'harness.sock'))
-  })
-
-  it('uses a named pipe on Windows, with a random name each time', () => {
-    const first = onPlatform('win32', () => socketPath('C:\\Users\\someone\\.xingular-harness\\state'))
-    const second = onPlatform('win32', () => socketPath('C:\\Users\\someone\\.xingular-harness\\state'))
-    expect(first).toMatch(/^\\\\\.\\pipe\\xingular-harness-[0-9a-f]{24}$/)
-    expect(second).not.toBe(first)
-  })
-})
-
-describe('session socket', () => {
-  it.skipIf(process.platform !== 'win32')('listens on a named pipe and answers a request on Windows', async () => {
-    const socket = new SessionSocket(socketPath('unused'), handlers)
-    await socket.listen()
-    try {
-      const reply = await new Promise<string>((resolve, reject) => {
-        const client = createConnection(socket.path)
-        let buffer = ''
-        client.on('connect', () => client.write('{"token":"nope","call":"wiki.read"}\n'))
-        client.on('data', (chunk) => (buffer += chunk.toString('utf8')))
-        client.on('end', () => resolve(buffer))
-        client.on('error', reject)
-      })
-      expect(JSON.parse(reply)).toMatchObject({ error: { code: 'unauthorized' } })
-    } finally {
-      await socket.close()
-    }
-  })
-
-  it('names the folder and the user when the operating system refuses to create the socket', async () => {
-    // Root can write anywhere, so the refusal cannot be produced there.
-    if (process.platform === 'win32' || process.getuid?.() === 0) return
-    const base = mkdtempSync(join(tmpdir(), 'sock-'))
-    const run = join(base, 'run')
-    mkdirSync(run)
-    chmodSync(run, 0o500)
-    try {
-      await expect(new SessionSocket(join(run, 'harness.sock'), handlers).listen()).rejects.toMatchObject({
-        code: 'session_socket_denied',
-        message: expect.stringMatching(/could not be created \((?:EACCES|EPERM)\)\. .*mode 500; this process runs as uid \d+\./)
-      })
-    } finally {
-      chmodSync(run, 0o700)
-      rmSync(base, { recursive: true, force: true })
-    }
-  })
-})

package/src/terminal/socket.ts

@@ -1,221 +0,0 @@
-// The session socket: how a process the harness did not start in-process (the `pi` command in
-// a terminal, with its extension and the `xagent-wiki` / `xagent-mcp` commands) reaches the
-// session it belongs to. Owner-only Unix socket (a named pipe on Windows), newline-delimited JSON,
-// one request per connection. Each terminal session holds a random token bound to its caller, its
-// connected-apps grant, and its controller; the token stops working when the terminal ends.
-import { createHash, randomBytes } from 'node:crypto'
-import { chmodSync, mkdirSync, rmSync, statSync } from 'node:fs'
-import { createServer, type Server, type Socket } from 'node:net'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-
-import { log } from '../core/bus'
-import { HarnessError, toErrorShape } from '../core/errors'
-import { newId } from '../core/fs'
-import type { BrokerSession } from '../mcp/service'
-import type { CallerContext } from '../memory/caller'
-
-/** What a token stands for. */
-export interface SocketGrant {
-  sessionId: string
-  /** Who memory, Wiki, and recall calls are made as. The run is filled in while a turn is live. */
-  caller: () => CallerContext
-  /** The session's connected-apps grant, when it has one. */
-  broker: BrokerSession | null
-  /** Telemetry from the native process, and what to do when it hangs up mid-request. */
-  terminal?: { accept(event: string, data: Record<string, unknown>): Promise<unknown>; disconnected(): void }
-}
-
-export interface SocketHandlers {
-  /** `wiki.*`, `memory.*`, `recall.*`. */
-  memory(caller: CallerContext, call: string, params: Record<string, unknown>): string
-  /** `mcp.list`, `mcp.call`, `mcp.revision`, `tools.list`, `tools.call`. */
-  apps(session: BrokerSession, call: string, params: Record<string, unknown>): Promise<unknown>
-  /**
-   * `plugins.*`. `control` is true only for the session's own extension, which holds a key the
-   * session's shell never sees; anything that changes what loads needs it.
-   */
-  plugins?(grant: SocketGrant, call: string, params: Record<string, unknown>, control: boolean): Promise<unknown>
-}
-
-const MAX_REQUEST_BYTES = 1024 * 1024
-/** macOS refuses a socket path longer than 103 bytes. */
-const MAX_SOCKET_PATH = 100
-
-/**
- * Windows has no socket files for Node's `net`: it listens on a named pipe, which lives in a
- * machine-wide namespace. A random name keeps another local process from guessing it and standing
- * in front of the session; the token still decides what a caller may do.
- */
-export function socketPath(stateDir: string): string {
-  if (process.platform === 'win32') return `\\\\.\\pipe\\xingular-harness-${randomBytes(12).toString('hex')}`
-  const path = join(stateDir, 'run', 'harness.sock')
-  if (Buffer.byteLength(path) <= MAX_SOCKET_PATH) return path
-  return join(tmpdir(), `xh-${createHash('sha256').update(path).digest('hex').slice(0, 16)}.sock`)
-}
-
-/** A named pipe has no folder, file mode, or owner to check or clean up. */
-const isPipePath = (path: string): boolean => path.startsWith('\\\\.\\pipe\\')
-
-/** Names the folder and the user when the operating system refuses the socket, so the cause shows. */
-function refusedBind(path: string, error: unknown): unknown {
-  const code = (error as { code?: unknown } | null)?.code
-  if (code !== 'EACCES' && code !== 'EPERM') return error
-  if (isPipePath(path)) {
-    return new HarnessError(
-      'session_socket_denied',
-      `The session pipe ${path} could not be created (${code}).`,
-      'Start the harness again from your own user session. If it keeps failing, report this code and the Windows version.'
-    )
-  }
-  let folder: string
-  try {
-    const stat = statSync(dirname(path))
-    folder = `${dirname(path)} is owned by uid ${stat.uid} with mode ${(stat.mode & 0o777).toString(8)}`
-  } catch {
-    folder = `${dirname(path)} could not be read`
-  }
-  const uid = process.getuid?.() ?? 'unknown'
-  return new HarnessError(
-    'session_socket_denied',
-    `The session socket ${path} could not be created (${code}). ${folder}; this process runs as uid ${uid}.`,
-    'Run the harness from your own terminal, as the user that owns its state folder, or choose a state folder you own with --state.'
-  )
-}
-
-export class SessionSocket {
-  private server: Server | null = null
-  private listening: Promise<void> | null = null
-  private readonly grants = new Map<string, SocketGrant>()
-  /**
-   * A second key per token, handed out once. The token is in the session's environment, where a
-   * command the model runs can read it; this key is claimed by the session's extension as it
-   * loads, before any model turn, and kept in its memory only.
-   */
-  private readonly controls = new Map<string, string>()
-  private readonly clients = new Set<Socket>()
-
-  constructor(
-    readonly path: string,
-    private readonly handlers: SocketHandlers
-  ) {}
-
-  issue(grant: SocketGrant): string {
-    const token = `${newId()}${newId()}`.replaceAll('-', '')
-    this.grants.set(token, grant)
-    return token
-  }
-
-  revoke(token: string): void {
-    this.grants.delete(token)
-    this.controls.delete(token)
-  }
-
-  revokeSession(sessionId: string): void {
-    for (const [token, grant] of this.grants) if (grant.sessionId === sessionId) this.revoke(token)
-  }
-
-  /** Runs one request line and returns the reply line's object. */
-  async handle(line: string, connection?: { waiting: (grant: SocketGrant | null) => void }): Promise<{ result: unknown } | { error: unknown }> {
-    try {
-      let request: Record<string, unknown>
-      try {
-        request = JSON.parse(line) as Record<string, unknown>
-      } catch {
-        throw new HarnessError('invalid_request', 'The request is not JSON.')
-      }
-      const token = typeof request.token === 'string' ? request.token : ''
-      const grant = this.grants.get(token)
-      if (!grant) throw new HarnessError('unauthorized', 'This session token is not valid. It ends when its terminal session ends.')
-      if (typeof request.event === 'string') {
-        if (!grant.terminal) throw new HarnessError('unknown_method', 'This session has no terminal controller.')
-        connection?.waiting(grant)
-        try {
-          return { result: (await grant.terminal.accept(request.event, (request.data ?? {}) as Record<string, unknown>)) ?? {} }
-        } finally {
-          connection?.waiting(null)
-        }
-      }
-      const call = typeof request.call === 'string' ? request.call : ''
-      const params = (request.params && typeof request.params === 'object' ? request.params : {}) as Record<string, unknown>
-      if (['wiki.', 'memory.', 'recall.'].some((prefix) => call.startsWith(prefix))) return { result: this.handlers.memory(grant.caller(), call, params) }
-      if (['mcp.', 'tools.'].some((prefix) => call.startsWith(prefix))) {
-        if (!grant.broker) throw new HarnessError('mcp_unauthorized', 'Connected apps are not available to this session.')
-        return { result: await this.handlers.apps(grant.broker, call, params) }
-      }
-      if (call === 'control.claim') {
-        if (this.controls.has(token)) throw new HarnessError('unauthorized', "This session's control key was already claimed.")
-        const key = `${newId()}${newId()}`.replaceAll('-', '')
-        this.controls.set(token, key)
-        return { result: { key } }
-      }
-      if (call.startsWith('plugins.') && this.handlers.plugins) {
-        const key = this.controls.get(token)
-        return { result: await this.handlers.plugins(grant, call, params, key !== undefined && request.control === key) }
-      }
-      throw new HarnessError('unknown_method', `Unknown call ${call}.`)
-    } catch (error) {
-      return { error: toErrorShape(error) }
-    }
-  }
-
-  private serve(client: Socket): void {
-    let buffer = ''
-    let waiting: SocketGrant | null = null
-    this.clients.add(client)
-    client.on('error', () => {})
-    client.once('close', () => {
-      this.clients.delete(client)
-      // A decision the native process was waiting on can no longer reach it.
-      waiting?.terminal?.disconnected()
-    })
-    client.on('data', (chunk) => {
-      buffer += chunk.toString('utf8')
-      if (Buffer.byteLength(buffer) > MAX_REQUEST_BYTES) {
-        client.destroy()
-        return
-      }
-      const newline = buffer.indexOf('\n')
-      if (newline < 0) return
-      client.pause()
-      void this.handle(buffer.slice(0, newline), { waiting: (grant) => void (waiting = grant) }).then((reply) => client.end(`${JSON.stringify(reply)}\n`))
-    })
-  }
-
-  /** Binds the socket once; later calls wait for the same bind. */
-  listen(): Promise<void> {
-    this.listening ??= new Promise<void>((resolve, reject) => {
-      if (!isPipePath(this.path)) {
-        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
-        rmSync(this.path, { force: true })
-      }
-      const server = createServer((client) => this.serve(client))
-      server.once('error', (error) => {
-        this.listening = null
-        reject(refusedBind(this.path, error))
-      })
-      server.listen(this.path, () => {
-        if (!isPipePath(this.path)) {
-          try {
-            chmodSync(this.path, 0o600)
-          } catch (error) {
-            log('session socket permissions', error instanceof Error ? error.message : String(error))
-          }
-        }
-        this.server = server
-        resolve()
-      })
-    })
-    return this.listening
-  }
-
-  async close(): Promise<void> {
-    this.grants.clear()
-    const server = this.server
-    this.server = null
-    this.listening = null
-    for (const client of this.clients) client.destroy()
-    if (server) await new Promise<void>((resolve) => server.close(() => resolve()))
-    if (!isPipePath(this.path)) rmSync(this.path, { force: true })
-  }
-}