@xingular/harness 0.1.7 → 1.0.0

package/src/sessions/conversation.test.ts

@@ -1,177 +0,0 @@
-// Whole replies, through everything the harness does for one: the compiled prompt, the plugins
-// it chose to load, the gate, the run's events. Pi is real and so are the extensions; only the
-// model is scripted, so no request leaves the machine.
-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 { listInbox } from '../memory/operations'
-import { wikiDir } from '../memory/store'
-import type { Plugin } from '../plugins/types'
-import { methods } from '../server/methods'
-import { fauxModel } from '../../tests/faux'
-import { rootWithProject, writeFile } from '../../tests/helpers'
-import type { RunEvent } from './contracts'
-
-const open: Harness[] = []
-afterEach(async () => {
-  for (const harness of open.splice(0)) await harness.close()
-})
-
-const EXTENSION = `import { Type } from 'typebox'
-export default function (pi) {
-  pi.registerTool({ name: 'kit_scan', label: 'Scan', description: 'Scan a folder.', parameters: Type.Object({ path: Type.String() }), async execute(id, input, signal, onUpdate, ctx) {
-    ctx.ui.notify('Scanning ' + input.path, 'info')
-    return { content: [{ type: 'text', text: 'scanned ' + input.path }], details: undefined }
-  } })
-}
-`
-
-async function setup() {
-  const root = rootWithProject()
-  const base = mkdtempSync(join(tmpdir(), 'conversation-'))
-  const harness = createHarness({ dataRoot: root, stateDir: join(base, 'state'), secrets: memorySecretStore(), maintainerFactory: async () => ({ prompt: async () => undefined, dispose: () => undefined, error: () => null }) })
-  open.push(harness)
-  harness.accounts.create('Main', 'apiKey')
-  const model = await fauxModel(harness)
-  const events: RunEvent[] = []
-  harness.runs.listen((event) => void events.push(event))
-  const table = methods(harness)
-  const call = <T>(method: string, params: Record<string, unknown> = {}) => table[method](params) as Promise<T>
-  const settled = (id: string) => events.some((event) => event.runId === id && (event.type === 'completed' || event.type === 'failed'))
-  const until = async (done: () => boolean) => {
-    for (let waited = 0; waited < 400 && !done(); waited += 1) await new Promise((resolve) => setTimeout(resolve, 25))
-  }
-  let count = 0
-  const start = async (extra: Record<string, unknown> = {}) => {
-    const id = `run-${(count += 1)}`
-    await harness.sessions.run({ run: { id, sessionId: 'a1' }, cwd: base, sessionDir: join(root, 'sessions', 'a1'), text: 'Go.', model: model.model, caller: { agentId: 'a1', agentName: 'Helper', actor: 'Chat' }, tools: { allow: ['read'] }, ...extra })
-    return id
-  }
-  const of = (id: string) => events.filter((event) => event.runId === id)
-  return { harness, root, base, model, call, start, until, settled, of }
-}
-
-describe('a whole reply, with a scripted model', () => {
-  it('dispatches a registered command with notes without making a provider request', async () => {
-    const { harness, model, start, until, settled, of } = await setup()
-    const account = harness.accounts.context(harness.accounts.resolve(null, null))
-    writeFile(join(account.configDir, 'extensions/command.ts'), `export default function(pi) { pi.registerCommand('hello', { description: 'Hello', handler: async (args, ctx) => ctx.ui.notify('hello ' + args) }) }`)
-    const id = await start({ text: '/hello original arguments', preamble: '[A note for the next request]' })
-    await until(() => settled(id))
-    expect(of(id).at(-1)?.type).toBe('completed')
-    expect(of(id).find((event) => event.type === 'extension.notice')?.payload).toMatchObject({ text: 'hello original arguments' })
-    expect(model.requests()).toBe(0)
-  })
-
-  it('asks before an extension tool that uses the name of an allowed native read', async () => {
-    const { harness, model, start, until, settled, of } = await setup()
-    const account = harness.accounts.context(harness.accounts.resolve(null, null))
-    writeFile(join(account.configDir, 'extensions/override.ts'), EXTENSION.replaceAll('kit_scan', 'read'))
-    model.script([model.calls(['read', { path: 'src' }]), model.says('Done.')])
-    const id = await start()
-    await until(() => of(id).some((event) => event.type === 'approval.requested') || settled(id))
-    const approval = of(id).find((event) => event.type === 'approval.requested')?.payload as { approvalId: string; target: string }
-    expect(approval?.target).toBe('read')
-    expect(of(id).some((event) => event.type === 'extension.notice')).toBe(false)
-    harness.runs.resolveApproval(id, approval.approvalId, 'denied')
-    await until(() => settled(id))
-    expect(model.lastToolResults().at(-1)).toContain('denied')
-    expect(of(id).some((event) => event.type === 'extension.notice')).toBe(false)
-  })
-
-  it("offers an installed plugin's tool only once the plugin is switched on and trusted, and asks before the tool runs", async () => {
-    const { harness, base, model, call, start, until, settled, of } = await setup()
-    writeFile(join(base, 'kit/package.json'), JSON.stringify({ name: 'review-kit', version: '1.0.0', description: 'Review helpers.' }))
-    writeFile(join(base, 'kit/extensions/scan.ts'), EXTENSION)
-    const plugin = (await call<Plugin[]>('plugins.install', { source: join(base, 'kit') })).find((candidate) => candidate.id === 'package:review-kit')!
-    const scan = () => model.script([model.calls(['kit_scan', { path: 'src' }]), model.says('Scanned.')])
-
-    // Installed, switched off, untrusted: the model names a tool the session does not have.
-    scan()
-    const first = await start()
-    await until(() => settled(first))
-    expect(of(first).some((event) => event.type === 'approval.requested')).toBe(false)
-    expect(model.lastToolResults().at(-1)).toMatch(/kit_scan/)
-    expect(model.lastToolResults().at(-1)).not.toContain('scanned src')
-
-    await call('plugins.attach', { id: plugin.id })
-    await call('plugins.trust', { hash: plugin.code!.hash })
-    scan()
-    const second = await start()
-    await until(() => of(second).some((event) => event.type === 'approval.requested') || settled(second))
-    const approval = of(second).find((event) => event.type === 'approval.requested')!.payload as { approvalId: string; target: string }
-    expect(approval.target).toBe('kit_scan')
-    // Nothing ran while the person was deciding.
-    expect(of(second).some((event) => event.type === 'extension.notice')).toBe(false)
-    harness.runs.resolveApproval(second, approval.approvalId, 'approved')
-    await until(() => settled(second))
-    expect(model.lastToolResults().at(-1)).toBe('scanned src')
-    // What the extension told the person arrived as a run event.
-    expect(of(second).find((event) => event.type === 'extension.notice')?.payload).toEqual({ kind: 'notify', level: 'info', text: 'Scanning src' })
-    expect(of(second).at(-1)?.type).toBe('completed')
-    // Having loaded once, the plugin's details say what its extension adds.
-    expect((await call<Plugin[]>('plugins.list')).find((candidate) => candidate.id === plugin.id)!.contributions[0].description).toBe('Adds tools kit_scan.')
-
-    // Denied, the tool does not run and the model is told.
-    scan()
-    const third = await start()
-    await until(() => of(third).some((event) => event.type === 'approval.requested') || settled(third))
-    harness.runs.resolveApproval(third, (of(third).find((event) => event.type === 'approval.requested')!.payload as { approvalId: string }).approvalId, 'denied')
-    await until(() => settled(third))
-    expect(model.lastToolResults().at(-1)).toMatch(/denied/)
-  })
-
-  it('lets the agent propose a plugin, which reaches the Inbox and nothing else', async () => {
-    const { root, model, start, until, settled, of } = await setup()
-    model.script([
-      model.calls(['plugin_propose', { name: 'Memory to Docs', description: 'Copies each saved memory to the team document.', extends: ['memory'] as never, files: [{ path: 'hooks.mjs', content: "export default function (harness) { harness.on('memory.saved', async () => {}) }\n" }] as never }]),
-      model.says('I proposed it; it is in your Inbox.')
-    ])
-    const id = await start()
-    await until(() => settled(id))
-    expect(model.lastToolResults().at(-1)).toContain('The plugin "memory-to-docs" is waiting in the Inbox')
-    expect(listInbox(wikiDir(root)).map((item) => item.title)).toEqual(['Proposed plugin "Memory to Docs"'])
-    expect(existsSync(join(root, 'plugins'))).toBe(false)
-    // Proposing is not something a person is asked to approve: it changes nothing until they accept.
-    expect(of(id).some((event) => event.type === 'approval.requested')).toBe(false)
-  })
-
-  it('has no plugin proposal tool in unattended work', async () => {
-    const { model, start, until, settled } = await setup()
-    model.script([model.calls(['plugin_propose', { name: 'x', description: 'y', files: [] as never }]), model.says('Done.')])
-    const id = await start({ automatic: true })
-    await until(() => settled(id))
-    expect(model.lastToolResults().at(-1)).not.toContain('waiting in the Inbox')
-  })
-
-  it('delivers a message sent during a tool call after that call, before the next request', async () => {
-    const { harness, model, call, start, until, settled, of } = await setup()
-    model.script([model.calls(['bash', { command: 'ls' }]), model.says('Noted.')])
-    const id = await start({ tools: { allow: ['read', 'bash'], gated: ['bash'] } })
-    await until(() => of(id).some((event) => event.type === 'approval.requested'))
-    const approval = of(id).find((event) => event.type === 'approval.requested')!.payload as { approvalId: string }
-    await call('runs.steer', { runId: id, text: 'Also check the logs.' })
-    harness.runs.resolveApproval(id, approval.approvalId, 'denied')
-    await until(() => settled(id))
-    const types = of(id).map((event) => event.type)
-    expect(of(id).find((event) => event.type === 'message.steered')?.payload).toEqual({ text: 'Also check the logs.' })
-    expect(types.indexOf('message.steered')).toBeGreaterThan(types.indexOf('approval.resolved'))
-    expect(model.requests()).toBe(2)
-    // The context update reaches the model as a user-role message too; the prompt and the steer come last.
-    expect(model.lastUserTexts().slice(-2)).toEqual(['Go.', 'Also check the logs.'])
-    expect(of(id).at(-1)?.type).toBe('completed')
-  })
-
-  it('refuses a message once the reply has ended, so the app sends it as a new reply', async () => {
-    const { call, model, start, until, settled, of } = await setup()
-    model.script([model.says('Done.')])
-    const id = await start()
-    await until(() => settled(id))
-    await expect(call('runs.steer', { runId: id, text: 'Too late.' })).rejects.toMatchObject({ code: 'run_not_active' })
-    expect(of(id).some((event) => event.type === 'message.steered')).toBe(false)
-  })
-})

package/src/sessions/extensionSession.test.ts

@@ -1,74 +0,0 @@
-// A real Pi session with a real extension, and no provider: nothing here makes a model request.
-import { mkdtempSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, expect, it } from 'vitest'
-
-import { memorySecretStore } from '../accounts/secrets'
-import { createHarness, type Harness } from '../harness'
-import { writeFile } from '../../tests/helpers'
-import type { ExtensionNotice } from './extensionUi'
-import type { QuestionInput } from './registry'
-import { piSessionFactory, type TurnParams } from './runner'
-
-const open: Harness[] = []
-afterEach(async () => {
-  for (const harness of open.splice(0)) await harness.close()
-})
-
-const EXTENSION = `import { Type } from 'typebox'
-export default function (pi) {
-  pi.registerTool({ name: 'kit_scan', label: 'Scan', description: 'Scan a folder.', parameters: Type.Object({ path: Type.String() }), async execute() { return { content: [{ type: 'text', text: 'scanned' }], details: undefined } } })
-  pi.registerCommand('hello', { description: 'Says hello', handler: async (args, ctx) => {
-    const sure = await ctx.ui.confirm('Say hello?', args)
-    ctx.ui.notify(sure ? 'hello ' + args : 'kept quiet', 'info')
-  } })
-  pi.on('session_start', async (_event, ctx) => { ctx.ui.setStatus('kit', 'ready in ' + ctx.mode) })
-}
-`
-
-it('binds an extension in a session without a terminal: its start hook runs, its tool is offered and asks, its command can ask and tell', async () => {
-  const base = mkdtempSync(join(tmpdir(), 'ext-session-'))
-  const harness = createHarness({ dataRoot: join(base, 'data'), stateDir: join(base, 'state'), secrets: memorySecretStore() })
-  open.push(harness)
-  harness.accounts.create('Main', 'apiKey')
-  const account = harness.accounts.context(harness.accounts.resolve(null, null))
-  writeFile(join(account.configDir, 'extensions/kit.ts'), EXTENSION)
-
-  const notices: ExtensionNotice[] = []
-  const asked: QuestionInput[] = []
-  const gated: string[] = []
-  const params: TurnParams = {
-    runId: 'r1',
-    cwd: base,
-    sessionDir: join(base, 'sessions'),
-    historyFile: null,
-    model: null,
-    text: '',
-    account,
-    system: '',
-    update: null,
-    plugins: { loading: () => harness.plugins.loading({ cwd: base, agentDir: account.configDir }), loaded: (extensions) => harness.plugins.loaded(extensions) }
-  }
-  const session = await piSessionFactory({
-    params,
-    allow: ['read'],
-    gate: { check: async () => null, ask: (names) => void gated.push(...names) },
-    tools: [],
-    runtime: () => harness.accounts.runtime(account),
-    extensions: { ask: async (input) => (asked.push(input), { selected: ['Yes'] }), notice: (notice) => void notices.push(notice) }
-  })
-  try {
-    expect(notices).toEqual([{ kind: 'status', key: 'kit', text: 'ready in rpc' }])
-    expect(gated).toEqual(['kit_scan'])
-    expect(session.getActiveToolNames?.()).toEqual(expect.arrayContaining(['read', 'kit_scan']))
-    expect(session.getActiveToolNames?.()).not.toContain('bash')
-
-    await session.prompt('/hello there')
-    expect(asked).toEqual([{ question: 'Say hello?\n\nthere', options: [{ label: 'Yes' }, { label: 'No' }], multiSelect: false, allowText: false }])
-    expect(notices.at(-1)).toEqual({ kind: 'notify', level: 'info', text: 'hello there' })
-    expect(Object.values(harness.plugins.registered())[0]).toMatchObject({ tools: ['kit_scan'], commands: ['hello'], hooks: ['session_start'] })
-  } finally {
-    session.dispose()
-  }
-})

package/src/sessions/extensionUi.test.ts

@@ -1,65 +0,0 @@
-import { describe, expect, it } from 'vitest'
-
-import { extensionUi, type ExtensionNotice } from './extensionUi'
-import type { QuestionAnswer, QuestionInput } from './registry'
-
-function host(answer: QuestionAnswer | Promise<QuestionAnswer>) {
-  const asked: QuestionInput[] = []
-  const notices: ExtensionNotice[] = []
-  const ui = extensionUi({ ask: async (input) => (asked.push(input), answer), notice: (notice) => void notices.push(notice) })
-  return { ui, asked, notices }
-}
-
-describe('what an extension can ask and show without a terminal', () => {
-  it('turns a choice, a yes or no, and typed text into questions', async () => {
-    const choice = host({ selected: ['Block'] })
-    expect(await choice.ui.select('Allow this command?', ['Allow', 'Block'])).toBe('Block')
-    expect(choice.asked[0]).toEqual({ question: 'Allow this command?', options: [{ label: 'Allow' }, { label: 'Block' }], multiSelect: false, allowText: false })
-
-    const yes = host({ selected: ['Yes'] })
-    expect(await yes.ui.confirm('Clear the session?', 'All messages will be lost.')).toBe(true)
-    expect(yes.asked[0]).toMatchObject({ question: 'Clear the session?\n\nAll messages will be lost.', options: [{ label: 'Yes' }, { label: 'No' }] })
-    expect(await host({ selected: ['No'] }).ui.confirm('Sure?', '')).toBe(false)
-    // No answer is a no, never a yes.
-    expect(await host({ selected: [] }).ui.confirm('Sure?', '')).toBe(false)
-
-    const typed = host({ selected: [], text: 'main' })
-    expect(await typed.ui.input('Branch', 'a name')).toBe('main')
-    expect(typed.asked[0]).toMatchObject({ question: 'Branch (a name)', options: [], allowText: true })
-    expect(await host({ selected: [] }).ui.input('Branch')).toBeUndefined()
-    expect(await host({ selected: [], text: 'edited' }).ui.editor('Edit', 'before')).toBe('edited')
-  })
-
-  it('gives up a dialog when the extension dismisses it or its time runs out', async () => {
-    const never = new Promise<QuestionAnswer>(() => undefined)
-    expect(await host(never).ui.confirm('Sure?', '', { timeout: 10 })).toBe(false)
-    const controller = new AbortController()
-    const pending = host(never).ui.select('Pick', ['a'], { signal: controller.signal })
-    controller.abort()
-    expect(await pending).toBeUndefined()
-  })
-
-  it('relays notifications, status lines and text widgets, and ignores what needs a terminal', async () => {
-    const { ui, notices } = host({ selected: [] })
-    ui.notify('Blocked', 'warning')
-    ui.setStatus('budget', '3 of 10 requests')
-    ui.setStatus('budget', undefined)
-    ui.setWidget('plan', ['One', 'Two'])
-    ui.setWidget('plan', (() => ({})) as never)
-    ui.setTitle('Review')
-    ui.setFooter(undefined)
-    ui.setWorkingMessage('thinking')
-    expect(notices).toEqual([
-      { kind: 'notify', level: 'warning', text: 'Blocked' },
-      { kind: 'status', key: 'budget', text: '3 of 10 requests' },
-      { kind: 'status', key: 'budget', text: '' },
-      { kind: 'widget', key: 'plan', text: 'One\nTwo' },
-      { kind: 'title', text: 'Review' }
-    ])
-    expect(await ui.custom((() => ({})) as never)).toBeUndefined()
-    expect(ui.getEditorText()).toBe('')
-    // Styling returns the text unchanged: there is nothing to colour.
-    expect((ui.theme as unknown as { fg(color: string, text: string): string }).fg('accent', 'plain')).toBe('plain')
-    expect(ui.setTheme('dark')).toMatchObject({ success: false })
-  })
-})

package/src/sessions/extensionUi.ts

@@ -1,102 +0,0 @@
-// What a Pi extension can show and ask in a session that has no terminal. Pi's own terminal
-// draws an extension's dialogs and status lines; here they become the run's question events and
-// notices, the same subset Pi's RPC mode supports. Anything that needs a real terminal (custom
-// components, key handlers, themes) does nothing, as it does there.
-import type { ExtensionUIContext } from '@earendil-works/pi-coding-agent'
-
-import type { QuestionAnswer, QuestionInput } from './registry'
-
-/** A status line, a notification, or an error from an extension. */
-export interface ExtensionNotice {
-  kind: 'notify' | 'status' | 'widget' | 'title' | 'error'
-  /** `notify` only. */
-  level?: 'info' | 'warning' | 'error'
-  /** The extension's own name for a status entry or a widget, so a later one replaces it. */
-  key?: string
-  /** The text. Empty clears a status entry or a widget. */
-  text: string
-  /** The file of the extension, for an error. */
-  extension?: string
-}
-
-export interface ExtensionHost {
-  ask(input: QuestionInput): Promise<QuestionAnswer>
-  notice(notice: ExtensionNotice): void
-}
-
-const MAX_TEXT = 4_000
-const clip = (text: string): string => (text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}…` : text)
-
-/** A dialog that Pi can dismiss on its own: by a signal, or after a time. */
-function dismissable<T>(answer: Promise<T>, fallback: T, options?: { signal?: AbortSignal; timeout?: number }): Promise<T> {
-  if (!options?.signal && !options?.timeout) return answer
-  return new Promise<T>((resolve) => {
-    let timer: ReturnType<typeof setTimeout> | undefined
-    const done = (value: T): void => {
-      if (timer) clearTimeout(timer)
-      resolve(value)
-    }
-    if (options.signal?.aborted) return done(fallback)
-    options.signal?.addEventListener('abort', () => done(fallback), { once: true })
-    if (options.timeout) timer = setTimeout(() => done(fallback), options.timeout)
-    void answer.then(done, () => done(fallback))
-  })
-}
-
-// Text styling has no meaning without a terminal: every style returns the text it was given.
-const plainTheme = new Proxy({}, { get: () => (...args: unknown[]) => String(args[args.length - 1] ?? '') })
-
-export function extensionUi(host: ExtensionHost): ExtensionUIContext {
-  const context = {
-    select: (title: string, options: string[], opts?: { signal?: AbortSignal; timeout?: number }) =>
-      dismissable(
-        host.ask({ question: clip(title), options: options.map((label) => ({ label })), multiSelect: false, allowText: false }).then((answer) => answer.selected[0]),
-        undefined,
-        opts
-      ),
-    confirm: (title: string, message: string, opts?: { signal?: AbortSignal; timeout?: number }) =>
-      dismissable(
-        host.ask({ question: clip(message ? `${title}\n\n${message}` : title), options: [{ label: 'Yes' }, { label: 'No' }], multiSelect: false, allowText: false }).then((answer) => answer.selected[0] === 'Yes'),
-        false,
-        opts
-      ),
-    input: (title: string, placeholder?: string, opts?: { signal?: AbortSignal; timeout?: number }) =>
-      dismissable(
-        host.ask({ question: clip(placeholder ? `${title} (${placeholder})` : title), options: [], multiSelect: false, allowText: true }).then((answer) => answer.text || undefined),
-        undefined,
-        opts
-      ),
-    editor: (title: string, prefill?: string) =>
-      host.ask({ question: clip(prefill ? `${title}\n\n${prefill}` : title), options: [], multiSelect: false, allowText: true }).then((answer) => answer.text || undefined),
-    notify: (message: string, level?: 'info' | 'warning' | 'error') => host.notice({ kind: 'notify', level: level ?? 'info', text: clip(message) }),
-    setStatus: (key: string, text: string | undefined) => host.notice({ kind: 'status', key, text: clip(text ?? '') }),
-    setWidget: (key: string, content: unknown) => {
-      // Only lines of text can be shown; a component needs a terminal.
-      if (content === undefined || Array.isArray(content)) host.notice({ kind: 'widget', key, text: clip(((content as string[] | undefined) ?? []).join('\n')) })
-    },
-    setTitle: (title: string) => host.notice({ kind: 'title', text: clip(title) }),
-    onTerminalInput: () => () => {},
-    setWorkingMessage: () => {},
-    setWorkingVisible: () => {},
-    setWorkingIndicator: () => {},
-    setHiddenThinkingLabel: () => {},
-    setFooter: () => {},
-    setHeader: () => {},
-    custom: async () => undefined,
-    pasteToEditor: () => {},
-    setEditorText: () => {},
-    getEditorText: () => '',
-    addAutocompleteProvider: () => {},
-    setEditorComponent: () => {},
-    getEditorComponent: () => undefined,
-    get theme() {
-      return plainTheme
-    },
-    getAllThemes: () => [],
-    getTheme: () => undefined,
-    setTheme: () => ({ success: false, error: 'There is no terminal to theme in this session.' }),
-    getToolsExpanded: () => false,
-    setToolsExpanded: () => {}
-  }
-  return context as unknown as ExtensionUIContext
-}

package/src/sessions/history.ts

@@ -1,51 +0,0 @@
-// Which native history a session opens. The prompt compiler compares against this file and Pi
-// opens it, so both always see the same conversation, including after a restart.
-import { readFileSync, realpathSync } from 'node:fs'
-import { isAbsolute, relative } from 'node:path'
-
-import { HarnessError } from '../core/errors'
-import { sessionFile } from '../prompt/compile'
-
-export interface HistorySelection {
-  sessionDir: string
-  /** A recorded history to continue, with the native session id it must still carry. */
-  resume?: { sessionFile?: string | null; nativeSessionId?: string | null } | null
-}
-
-const unavailable = (): HarnessError => new HarnessError('native_resume_unavailable', 'The saved conversation is unavailable; this reply cannot be continued.')
-
-/** The session file's own id, when the file is a native history inside `sessionDir`. */
-function nativeId(sessionDir: string, path: string): string {
-  const file = realpathSync(path)
-  const within = relative(realpathSync(sessionDir), file)
-  if (within.startsWith('..') || isAbsolute(within) || !file.endsWith('.jsonl')) throw new Error('Outside history')
-  const header = JSON.parse(readFileSync(file, 'utf8').split('\n', 1)[0]) as { type?: string; id?: string }
-  if (header.type !== 'session' || !header.id) throw new Error('Missing session identity')
-  return header.id
-}
-
-/**
- * The history to open: the recorded one for an explicit continuation, else the newest in the
- * session's folder, else none (a fresh history). An explicit continuation never falls back to
- * another session or a fresh history.
- */
-export function selectHistory(selection: HistorySelection): string | null {
-  const resume = selection.resume
-  if (resume?.sessionFile || resume?.nativeSessionId) {
-    try {
-      if (!resume.sessionFile || !resume.nativeSessionId) throw new Error('Missing history')
-      if (nativeId(selection.sessionDir, resume.sessionFile) !== resume.nativeSessionId) throw new Error('Different history')
-      return realpathSync(resume.sessionFile)
-    } catch {
-      throw unavailable()
-    }
-  }
-  const newest = sessionFile(selection.sessionDir)
-  if (!newest) return null
-  try {
-    nativeId(selection.sessionDir, newest)
-    return realpathSync(newest)
-  } catch {
-    throw unavailable()
-  }
-}

package/src/sessions/lineageJoin.ts

@@ -1,75 +0,0 @@
-import type { AgentBeforeSettleEvent, BoundaryResult, ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
-
-import { takeChars } from '../core/text'
-import { isActiveStatus } from './contracts'
-import { readEvents, runFamily } from './runStore'
-import type { InlineExtension } from '../plugins/firstParty'
-
-interface RunSummary {
-  id: string
-  status: string
-  goal: string | null
-  terminalReason: string | null
-}
-
-function directChildren(root: string, runId: string): RunSummary[] {
-  try {
-    return runFamily(root, runId).runs
-      .map(({ run }) => run)
-      .filter((run) => run.parentRunId === runId)
-      .map((run) => ({ id: run.id, status: run.status, goal: run.goal, terminalReason: run.terminalReason }))
-  } catch {
-    return []
-  }
-}
-
-function settled(root: string, runId: string): boolean {
-  return directChildren(root, runId).every((child) => !isActiveStatus(child.status))
-}
-
-function alreadyIncluded(event: AgentBeforeSettleEvent, runId: string): boolean {
-  return JSON.stringify(event.context.contextMessages).includes(runId)
-}
-
-function childReport(root: string, child: RunSummary): string {
-  const reply = readEvents(root, child.id)
-    .filter((event) => event.type === 'message.completed' && (event.payload as { role?: unknown }).role === 'assistant')
-    .at(-1)
-  const payload = reply?.payload as { text?: unknown } | undefined
-  const text = payload && typeof payload.text === 'string' ? takeChars(payload.text, 8000) : ''
-  const lines = [`Run ${child.id} · ${child.status}`, `Goal: ${child.goal?.trim() || '(not recorded)'}`]
-  if (text) lines.push(`Result:\n${text}`)
-  if (child.status !== 'completed' && child.terminalReason) lines.push(`Stopped because: ${child.terminalReason}`)
-  return lines.join('\n')
-}
-
-async function waitForChildren(root: string, runId: string, signal?: AbortSignal): Promise<boolean> {
-  while (!signal?.aborted) {
-    if (settled(root, runId)) return true
-    await new Promise<void>((resolve) => setTimeout(resolve, 250))
-  }
-  return false
-}
-
-function install(pi: ExtensionAPI, root: string, runId: string): void {
-  pi.on('agent_before_settle', async (event, context: ExtensionContext): Promise<BoundaryResult | undefined> => {
-    if (event.outcome !== 'completed' || settled(root, runId)) return undefined
-    const completed = await waitForChildren(root, runId, context.signal)
-    if (!completed || context.signal?.aborted) return undefined
-
-    const unreported = directChildren(root, runId).filter((child) => !alreadyIncluded(event, child.id))
-    if (!unreported.length) return undefined
-    const summary = takeChars(
-      `Independent run results. Include each result or failure in the reply; the user may open each run for its full history.\n\n${unreported.map((child) => childReport(root, child)).join('\n\n')}`,
-      32_000
-    )
-    return {
-      entries: [...event.entries, { type: 'custom_message', customType: 'run-lineage-results', content: summary, display: false }],
-      continue: true
-    }
-  })
-}
-
-export function runLineageJoin(root: string, runId: string): InlineExtension {
-  return { name: 'run-lineage-join', factory: (pi: ExtensionAPI) => install(pi, root, runId) }
-}

package/src/sessions/policy.ts

@@ -1,36 +0,0 @@
-// What the embedding application decides about a session's tool calls. The harness asks; it
-// never assumes: with no policy, every enabled tool may run and gated tools ask the user.
-import type { CallerContext } from '../memory/caller'
-import type { ApprovalFacts } from './approvals'
-import type { RunRecord } from './contracts'
-
-export interface ToolCall {
-  run: RunRecord
-  caller: CallerContext
-  tool: string
-  args: unknown
-}
-
-export interface ScopeDecision {
-  /** The run is unattended: nothing may ask a person, so what is not allowed is refused. */
-  automatic?: boolean
-  allowed: boolean
-  /** Not allowed as it stands, but a person may approve this one call. */
-  requiresApproval?: boolean
-  /** Per-tool remembered approvals never answer this call. */
-  humanOnly?: boolean
-  /** Whether the global always-approve switch may answer a human-only call. Defaults to false. */
-  allowGlobalApproval?: boolean
-  reason?: string | null
-}
-
-export interface ToolPolicy {
-  /** Whether the call is inside what this run may do. Asked before every tool call. */
-  scope?(call: ToolCall): Promise<ScopeDecision>
-  /** Whether the tool is still switched on. Asked before a call and again after an approval; throws to block. */
-  authorize?(call: ToolCall): Promise<void>
-  /** Facts about a pending approval that only the application knows. */
-  approval?(input: { run: RunRecord; target: string; operation?: { tool: string; args: unknown } }): Promise<ApprovalFacts>
-  /** The connected apps this session may reach, out of those its scope already allows. */
-  connections?(input: { sessionId: string; runId: string | null; caller: CallerContext; connectionIds: string[] }): Promise<string[]>
-}

package/src/sessions/pricing.ts

@@ -1,60 +0,0 @@
-// List-price cost of token usage, for when a provider reports tokens but no cost.
-import type { ModelRuntime } from '@earendil-works/pi-coding-agent'
-
-/** Dollars per million tokens. */
-export interface PriceRates {
-  input: number
-  output: number
-  cacheRead: number
-  cacheWrite: number
-  /** The highest tier whose threshold the request's whole input exceeds replaces the base rates. */
-  tiers?: Array<{ input: number; output: number; cacheRead: number; cacheWrite: number; inputTokensAbove: number }>
-}
-
-export interface PricedTokens {
-  inputTokens?: number
-  outputTokens?: number
-  cacheReadTokens?: number
-  cacheWriteTokens?: number
-}
-
-/** The cost of one request at `rates`. Same arithmetic as Pi's own `calculateCost`. */
-export function costAt(rates: PriceRates, usage: PricedTokens): number {
-  const input = usage.inputTokens ?? 0
-  const cacheRead = usage.cacheReadTokens ?? 0
-  const cacheWrite = usage.cacheWriteTokens ?? 0
-  const whole = input + cacheRead + cacheWrite
-  let applied: Omit<PriceRates, 'tiers'> = rates
-  let threshold = -1
-  for (const tier of rates.tiers ?? []) {
-    if (whole > tier.inputTokensAbove && tier.inputTokensAbove > threshold) {
-      applied = tier
-      threshold = tier.inputTokensAbove
-    }
-  }
-  return (applied.input * input + applied.output * (usage.outputTokens ?? 0) + applied.cacheRead * cacheRead + applied.cacheWrite * cacheWrite) / 1_000_000
-}
-
-type Catalogue = { getModel(provider: string, model: string): { cost?: PriceRates } | undefined }
-let catalogue: Promise<Catalogue> | null = null
-
-async function loadCatalogue(): Promise<Catalogue> {
-  const { ModelRuntime } = await import('@earendil-works/pi-coding-agent')
-  const none = { read: async () => undefined, list: async () => [], modify: async () => undefined, delete: async () => undefined }
-  return (await ModelRuntime.create({ credentials: none, modelsPath: null, refreshOnCreate: false })) as ModelRuntime as unknown as Catalogue
-}
-
-/**
- * The list rates Pi's catalogue has for a model, or null when it has none. A dated model id
- * (`…-20250929`) also matches its undated entry. Rates of zero are "unknown", not "free".
- */
-export async function modelRates(provider: string | undefined, model: string | undefined, lookup: Promise<Catalogue> = (catalogue ??= loadCatalogue())): Promise<PriceRates | null> {
-  if (!provider || !model) return null
-  const models = await lookup.catch(() => null)
-  if (!models) return null
-  for (const id of new Set([model, model.replace(/-\d{8}$/, '')])) {
-    const cost = models.getModel(provider, id)?.cost
-    if (cost && (cost.input > 0 || cost.output > 0)) return cost
-  }
-  return null
-}