@xingular/harness 0.0.0-stage → 0.1.0

package/src/terminal/terminals.ts

@@ -0,0 +1,429 @@
+// Terminal sessions: a person working with the `pi` command in a terminal that the embedding
+// application draws. The harness prepares the launch (isolated account, compiled instructions,
+// skills, the session socket), then follows the process through its extension. It never owns
+// the terminal: the application spawns the process from the spec returned here and reports when
+// it exits.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import type { Accounts } from '../accounts/accounts'
+import { configDir, launchEnv } from '../accounts/env'
+import type { Account } from '../accounts/store'
+import type { Bus } from '../core/bus'
+import { log } from '../core/bus'
+import type { HarnessEnv } from '../core/env'
+import { HarnessError, invalid } from '../core/errors'
+import { newId, now } from '../core/fs'
+import { findBinary, searchPath } from '../core/path'
+import type { BrokerSession, ConnectedApps } from '../mcp/service'
+import type { CallerContext } from '../memory/caller'
+import { dispatch } from '../memory/dispatch'
+import type { AttachParams, PluginScope } from '../plugins/api'
+import type { Plugins } from '../plugins/plugins'
+import type { Plugin } from '../plugins/types'
+import { compile, copyToRun, memoryDelta, record, render, saveForSession, type Launch } from '../prompt/compile'
+import type { RunRecord } from '../sessions/contracts'
+import { isActiveStatus } from '../sessions/contracts'
+import type { ToolPolicy } from '../sessions/policy'
+import type { ActiveRun, RunRegistry } from '../sessions/registry'
+import { findRun, loadRun, saveRun, updateRun } from '../sessions/runStore'
+import { resources } from '../skills/registry'
+import type { ToolSpec } from '../tools/types'
+import { APPS_COMMAND, WIKI_COMMAND } from './cli'
+import { SOCKET_ENV, TOKEN_ENV } from './client'
+import { TerminalController, type PolicyReply } from './controller'
+import { SessionSocket, socketPath } from './socket'
+
+/** The files a terminal session needs on disk, outside this process. */
+export interface TerminalAssets {
+  /** The Node binary that runs the commands. */
+  node: string
+  /** The built `xingular-harness` command (`dist/cli.js`). */
+  cli: string
+  /** The built Pi extension (`dist/terminal-pi.js`). */
+  piExtension: string
+}
+
+/** Where the package's own build puts them. An application that bundles the harness passes its own. */
+export function defaultAssets(): TerminalAssets {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const dist = [here, join(here, '..', '..', 'dist'), join(here, '..', 'dist')].find((folder) => existsSync(join(folder, 'terminal-pi.js'))) ?? here
+  return { node: process.execPath, cli: join(dist, 'cli.js'), piExtension: join(dist, 'terminal-pi.js') }
+}
+
+export interface TerminalPrepareInput {
+  sessionId: string
+  /** The account the session is pinned to. Omitted only for a session that has none yet; it then takes the default and keeps it. */
+  accountId?: string | null
+  projectId?: string | null
+  cwd: string
+  /** The session's own folder. Its compiled instructions and native history are kept under it. */
+  sessionFolder: string
+  nativeSessionId?: string | null
+  model?: string | null
+  readOnly?: boolean
+  /** What the application adds to the instructions, and which of its tools it describes. */
+  launch?: Launch
+  /** Give the session the connected-apps broker. Defaults to yes. */
+  connections?: boolean
+  /** Fields copied onto each run this session records. */
+  run?: Partial<Pick<RunRecord, 'mode' | 'worktreeId'>>
+}
+
+export interface TerminalLaunch {
+  program: string
+  args: string[]
+  /** Variables to set; `null` removes an inherited one. */
+  env: Record<string, string | null>
+  accountId: string
+  nativeSessionId: string | null
+}
+
+interface Live {
+  input: TerminalPrepareInput
+  account: Account
+  controller: TerminalController
+  token: string
+  broker: BrokerSession | null
+  caller: CallerContext
+}
+
+export interface TerminalsOptions {
+  env: HarnessEnv
+  stateDir: string
+  accounts: Accounts
+  runs: RunRegistry
+  apps: ConnectedApps
+  policy: ToolPolicy
+  bus: Bus
+  /** Chooses what a terminal loads. Without it Pi discovers extensions and skills on its own. */
+  plugins?: Plugins
+  /** Lists plugins and applies a person's choices, for the session's `/plugins` command. */
+  pluginControl?: PluginControl
+  assets?: TerminalAssets
+  /** The `pi` executable. Defaults to the one on the search path. */
+  program?: () => string | null
+}
+
+/** What `/plugins` in a terminal can do. Each takes the session's folder, account and project. */
+export interface PluginControl {
+  list(scope: PluginScope): Promise<Plugin[]>
+  attach(params: AttachParams, on: boolean): Promise<Plugin[]>
+  trust(scope: PluginScope & { hash: string }): Promise<Plugin[]>
+  untrust(scope: PluginScope & { hash: string }): Promise<Plugin[]>
+}
+
+const READ_ONLY_TOOLS = new Set(['read', 'grep', 'find', 'ls'])
+
+export class Terminals {
+  private readonly sessions = new Map<string, Live>()
+  private readonly socket: SessionSocket
+  private readonly assets: TerminalAssets
+
+  constructor(private readonly options: TerminalsOptions) {
+    this.assets = options.assets ?? defaultAssets()
+    this.socket = new SessionSocket(socketPath(options.stateDir), {
+      memory: (caller, call, params) => dispatch(options.env, caller, call, params),
+      apps: (session, call, params) => this.appsCall(session, call, params),
+      plugins: (grant, call, params, control) => this.pluginsCall(grant.sessionId, call, params, control)
+    })
+  }
+
+  /** The commands a terminal session finds on PATH. Rewritten only when they change. */
+  private ensureCommands(): string {
+    const bin = join(this.options.stateDir, 'run', 'bin')
+    mkdirSync(bin, { recursive: true })
+    const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`
+    for (const [name, mode] of [[WIKI_COMMAND, 'wiki'], [APPS_COMMAND, 'mcp']] as const) {
+      const wrapper = join(bin, name)
+      const text = `#!/bin/sh\nexec ${quote(this.assets.node)} ${quote(this.assets.cli)} ${mode} "$@"\n`
+      let current: string | null = null
+      try {
+        current = readFileSync(wrapper, 'utf8')
+      } catch {
+        current = null
+      }
+      if (current !== text) {
+        writeFileSync(wrapper, text)
+        chmodSync(wrapper, 0o755)
+      }
+    }
+    return bin
+  }
+
+  private tools(session: BrokerSession): ToolSpec[] {
+    return this.options.apps.brokerTools(session)
+  }
+
+  private async appsCall(session: BrokerSession, call: string, params: Record<string, unknown>): Promise<unknown> {
+    const { apps } = this.options
+    switch (call) {
+      case 'mcp.list':
+        return apps.list(session)
+      case 'mcp.call':
+        return apps.invoke(session, String(params.name ?? ''), (params.args && typeof params.args === 'object' ? params.args : {}) as Record<string, unknown>)
+      case 'mcp.revision':
+        return apps.revision(session)
+      case 'tools.list': {
+        const { Type } = await import('typebox')
+        return { tools: this.tools(session).map((tool) => ({ name: tool.name, label: tool.label, description: tool.description, parameters: tool.parameters(Type) })) }
+      }
+      case 'tools.call': {
+        const tool = this.tools(session).find((candidate) => candidate.name === params.name)
+        if (!tool) throw new HarnessError('unknown_method', `Unknown tool ${String(params.name)}.`)
+        const result = await tool.execute((params.input && typeof params.input === 'object' ? params.input : {}) as Record<string, unknown>)
+        return { text: typeof result === 'string' ? result : result.text }
+      }
+      default:
+        throw new HarnessError('unknown_method', `Unknown call ${call}.`)
+    }
+  }
+
+  /**
+   * `/plugins` in a terminal. Listing is open to the session. A change is taken only from the
+   * session's own extension, which asks the person in the terminal first: the model can reach
+   * this socket from a shell command, and must not be able to trust code or switch it on.
+   */
+  private async pluginsCall(sessionId: string, call: string, params: Record<string, unknown>, control: boolean): Promise<unknown> {
+    const api = this.options.pluginControl
+    const live = this.sessions.get(sessionId)
+    if (!api || !live) throw new HarnessError('unknown_method', `Unknown call ${call}.`)
+    const projectId = live.input.projectId ?? null
+    const scope = { cwd: live.input.cwd, accountId: live.account.id, projectId }
+    if (call === 'plugins.list') return api.list(scope)
+    if (call === 'plugins.session') return { projectId }
+    if (!control) throw new HarnessError('unauthorized', 'Only a person at this terminal can change plugins. Type /plugins.')
+    const text = (name: string): string => {
+      if (typeof params[name] !== 'string' || !params[name]) throw invalid(`${name} is required.`)
+      return params[name] as string
+    }
+    switch (call) {
+      case 'plugins.attach':
+      case 'plugins.detach':
+        return api.attach({ ...scope, id: text('id'), scope: params.everywhere === true || !projectId ? {} : { projectId } }, call === 'plugins.attach')
+      case 'plugins.trust':
+        return api.trust({ ...scope, hash: text('hash') })
+      case 'plugins.untrust':
+        return api.untrust({ ...scope, hash: text('hash') })
+      default:
+        throw new HarnessError('unknown_method', `Unknown call ${call}.`)
+    }
+  }
+
+  private live(sessionId: string): Live {
+    const live = this.sessions.get(sessionId)
+    if (!live) throw new HarnessError('terminal_not_ready', 'The terminal controller is unavailable. Reopen this session.')
+    return live
+  }
+
+  private historyDir(input: TerminalPrepareInput): string {
+    return join(input.sessionFolder, 'pi')
+  }
+
+  private runRecord(live: Live, runId: string, text: string | null): RunRecord {
+    const { input } = live
+    return {
+      resumedFromRunId: null,
+      parentRunId: null,
+      relation: null,
+      terminalReason: null,
+      agentId: null,
+      trigger: null,
+      id: runId,
+      projectId: input.projectId ?? null,
+      mode: input.run?.mode ?? 'code',
+      harness: 'pi',
+      sessionType: 'terminal',
+      sessionId: input.sessionId,
+      nativeSessionId: live.controller.nativeSessionId,
+      workingDirectory: input.cwd,
+      worktreeId: input.run?.worktreeId ?? null,
+      goal: text,
+      attachmentCount: 0,
+      startedAt: now(),
+      endedAt: null,
+      status: 'queued',
+      exitCode: null,
+      handoffId: null,
+      accountId: live.account.id
+    }
+  }
+
+  /** The run a native turn reports into: the one reserved by `send`, or a new one for what the person typed. */
+  private begin(live: Live, reservedRunId: string | null, text: string): ActiveRun {
+    const { root } = this.options.env
+    const { sessionId } = live.input
+    if (this.options.runs.activeForSession(sessionId)) throw new HarnessError('session_busy', 'A native turn already owns this session.')
+    let runId = reservedRunId
+    if (runId) {
+      const reserved = loadRun(root, runId)
+      if (reserved.sessionId !== sessionId || reserved.status !== 'queued') throw invalid('Delivery does not own this queued run.')
+    } else {
+      runId = newId()
+      saveRun(root, this.runRecord(live, runId, text || null))
+      copyToRun(root, live.input.sessionFolder, runId)
+    }
+    return this.options.runs.start(sessionId, runId)
+  }
+
+  private async decide(live: Live, run: ActiveRun, tool: string, args: unknown): Promise<PolicyReply> {
+    const record = loadRun(this.options.env.root, run.runId)
+    if (!isActiveStatus(record.status)) throw invalid('The run is no longer active.')
+    const call = { run: record, caller: { ...live.caller, runId: run.runId }, tool, args }
+    const { policy } = this.options
+    if (policy.scope) {
+      const scope = await policy.scope(call)
+      if (!scope.allowed && !scope.requiresApproval) return { allowed: false, reason: scope.reason ?? 'Outside what this session may do.' }
+      try {
+        await policy.authorize?.(call)
+      } catch (error) {
+        return { allowed: false, reason: error instanceof Error ? error.message : 'Tool unavailable in the settings.' }
+      }
+      return { allowed: scope.allowed, requiresApproval: !!scope.requiresApproval, reason: scope.reason ?? null }
+    }
+    // With no application policy: reads run, a read-only session refuses the rest, and anything else asks.
+    const name = tool.toLowerCase()
+    if (READ_ONLY_TOOLS.has(name) || this.options.apps.toolNames.includes(name as never)) return { allowed: true }
+    if (live.input.readOnly) return { allowed: false, reason: 'This session is read-only.' }
+    return { allowed: false, requiresApproval: true, reason: 'This native action requires approval.' }
+  }
+
+  /**
+   * Prepares a `pi` terminal session and returns what to spawn. The caller must report the
+   * process's end with `dispose`, also when it never starts.
+   */
+  async prepare(input: TerminalPrepareInput): Promise<TerminalLaunch> {
+    const { env, accounts, apps, bus } = this.options
+    const { root } = env
+    if (!input?.sessionId || !input.cwd || !input.sessionFolder) throw invalid('A terminal session needs an id, a working folder, and its own folder.')
+    await this.dispose(input.sessionId)
+    const program = this.options.program ? this.options.program() : findBinary('pi')
+    if (!program) throw new HarnessError('harness_unavailable', 'The Pi CLI was not found on PATH.')
+    // A pinned account is used as it is; it is never exchanged for another one.
+    const account = input.accountId ? accounts.find(input.accountId) : accounts.resolve(null, null)
+    const launch = launchEnv(accounts.dir, account)
+    const loading = (await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, account), install: true, caller: { projectId: input.projectId ?? null } })) ?? null
+    await this.socket.listen()
+    await accounts.terminalBegin(account)
+
+    const sessionId = input.sessionId
+    const caller: CallerContext = { sessionId, projectId: input.projectId ?? null, actor: 'Code', surface: 'cli' }
+    let token: string | null = null
+    try {
+      const broker = input.connections === false ? null : apps.grant({ sessionId, runId: null, caller, readOnly: !!input.readOnly, depth: 0 })
+      // The session keeps these instructions; each of its runs records a copy, and a memory
+      // block that changes later is sent along as a note.
+      const pack = compile(env, caller, { input: '', ...input.launch })
+      record(root, caller, pack)
+      mkdirSync(this.historyDir(input), { recursive: true })
+      saveForSession(input.sessionFolder, pack)
+
+      const live: Live = {
+        input,
+        account,
+        broker,
+        caller,
+        token: '',
+        controller: new TerminalController({
+          sessionId,
+          nativeSessionId: input.nativeSessionId ?? null,
+          begin: ({ reservedRunId, text }) => this.begin(live, reservedRunId, text),
+          policy: (run, tool, args) => this.decide(live, run, tool, args),
+          native: (nativeSessionId) => bus.emit({ type: 'terminal.native', sessionId, nativeSessionId }),
+          telemetry: (event) => bus.emit({ type: 'terminal.telemetry', sessionId, event })
+        })
+      }
+      token = this.socket.issue({
+        sessionId,
+        caller: () => ({ ...caller, runId: live.controller.activeRun?.runId ?? null }),
+        broker,
+        terminal: { accept: (event, data) => live.controller.accept(event, data), disconnected: () => live.controller.disconnected() }
+      })
+      live.token = token
+      this.sessions.set(sessionId, live)
+
+      const args = ['--append-system-prompt', render(env, pack)]
+      if (input.model) args.push('--model', input.model)
+      if (loading) {
+        // Pi's own discovery is off: the terminal loads what the harness found and nothing else.
+        args.push('--no-extensions', '--no-skills', '--no-prompt-templates', '--no-themes')
+        const enabled = resources(root, input.projectId ?? null)
+        for (const path of [...loading.extensionPaths, ...loading.builtins]) args.push('--extension', path)
+        for (const path of [...enabled.skillPaths, ...loading.skillPaths]) args.push('--skill', path)
+        for (const path of [...enabled.promptPaths, ...loading.promptPaths]) args.push('--prompt-template', path)
+        for (const path of loading.themePaths) args.push('--theme', path)
+      }
+      // Last, so its gate sees a tool call as every other extension left it.
+      args.push('--extension', this.assets.piExtension, '--session-dir', this.historyDir(input))
+      if (input.nativeSessionId) args.push('--session', input.nativeSessionId)
+      return {
+        program,
+        args,
+        env: { ...launch, PATH: `${this.ensureCommands()}:${searchPath()}`, [SOCKET_ENV]: this.socket.path, [TOKEN_ENV]: token },
+        accountId: account.id,
+        nativeSessionId: input.nativeSessionId ?? null
+      }
+    } catch (error) {
+      if (token) this.socket.revoke(token)
+      this.sessions.delete(sessionId)
+      apps.revokeSession(sessionId)
+      await accounts.terminalEnd(account).catch(() => undefined)
+      throw error
+    }
+  }
+
+  /** Hands the terminal an instruction as a new run. Resolves once the native session has taken it. */
+  async send(input: { sessionId: string; runId?: string | null; text: string }): Promise<{ runId: string }> {
+    const { env } = this.options
+    const { root } = env
+    if (!input.text?.trim()) throw invalid('Message is empty.')
+    const live = this.live(input.sessionId)
+    if (this.options.runs.activeForSession(input.sessionId) || live.controller.state().active) throw new HarnessError('session_busy', 'This session is still working.')
+    const runId = input.runId || newId()
+    if (findRun(root, runId)) throw invalid('This run already exists.')
+    saveRun(root, this.runRecord(live, runId, input.text))
+    const note = memoryDelta(env, live.input.sessionFolder, { ...live.caller, runId })
+    copyToRun(root, live.input.sessionFolder, runId)
+    try {
+      await live.controller.send(runId, note ? `${note}\n\n${input.text}` : input.text)
+    } catch (error) {
+      updateRun(root, runId, (run) => {
+        if (!isActiveStatus(run.status)) return
+        run.status = 'failed'
+        run.endedAt = now()
+      })
+      throw error
+    }
+    return { runId }
+  }
+
+  /** What the person typed into the terminal. */
+  input(sessionId: string, data: string): void {
+    this.sessions.get(sessionId)?.controller.onInput(data)
+  }
+
+  state(sessionId: string): { ready: boolean; dirty: boolean; active: boolean } {
+    return this.live(sessionId).controller.state()
+  }
+
+  has(sessionId: string): boolean {
+    return this.sessions.has(sessionId)
+  }
+
+  /** The terminal process ended (or never started): its turn, tokens, and written credentials go with it. */
+  async dispose(sessionId: string): Promise<void> {
+    const live = this.sessions.get(sessionId)
+    if (!live) return
+    this.sessions.delete(sessionId)
+    live.controller.dispose()
+    this.socket.revoke(live.token)
+    this.options.apps.revokeSession(sessionId)
+    await this.options.accounts.terminalEnd(live.account).catch((error) => log('terminal credentials', error instanceof Error ? error.message : String(error)))
+  }
+
+  async close(): Promise<void> {
+    await Promise.allSettled([...this.sessions.keys()].map((sessionId) => this.dispose(sessionId)))
+    await this.socket.close()
+  }
+}

package/src/tools/askUser.ts

@@ -0,0 +1,45 @@
+// Asking the person a question and waiting for the answer: part of every session.
+import type { ActiveRun, QuestionAnswer } from '../sessions/registry'
+import type { ToolSpec } from './types'
+
+export const ASK_USER = 'ask_user'
+const MAX_OPTIONS = 6
+
+const text = (value: unknown): string => (typeof value === 'string' ? value.trim() : '')
+
+/** The answer as the model reads it. */
+export function describeAnswer(answer: QuestionAnswer): string {
+  const parts: string[] = []
+  if (answer.selected.length) parts.push(`The user chose: ${answer.selected.join(', ')}.`)
+  if (answer.text) parts.push(answer.selected.length ? `They added: ${answer.text}` : `The user answered: ${answer.text}`)
+  return parts.join(' ') || 'The user did not answer.'
+}
+
+export function askUserTool(run: ActiveRun): ToolSpec {
+  return {
+    name: ASK_USER,
+    label: 'Ask the user',
+    description:
+      'Ask the user a question and wait for the answer. Offer up to 6 short options when the choices are clear; ' +
+      'set multiSelect when several can apply. The user can also type their own answer. Use it when you need a decision, not for small talk.',
+    parameters: (Type) =>
+      Type.Object({
+        question: Type.String({ description: 'The question, in one sentence' }),
+        options: Type.Optional(
+          Type.Array(Type.Object({ label: Type.String({ description: 'A short choice' }), description: Type.Optional(Type.String({ description: 'One line about what it means' })) }), { maxItems: MAX_OPTIONS })
+        ),
+        multiSelect: Type.Optional(Type.Boolean()),
+        allowText: Type.Optional(Type.Boolean({ description: 'Let the user type their own answer (default true)' }))
+      }),
+    execute: async (input) => {
+      const question = text(input.question)
+      if (!question) return 'The question is empty.'
+      const options = (Array.isArray(input.options) ? input.options : [])
+        .map((option) => ({ label: text((option as { label?: unknown }).label), description: text((option as { description?: unknown }).description) }))
+        .filter((option) => option.label)
+        .slice(0, MAX_OPTIONS)
+        .map((option) => (option.description ? option : { label: option.label }))
+      return describeAnswer(await run.requestAnswer({ question, options, multiSelect: options.length > 1 && input.multiSelect === true, allowText: options.length === 0 || input.allowText !== false }))
+    }
+  }
+}

package/src/tools/definitions.ts

@@ -0,0 +1,187 @@
+// The memory and Wiki tools a session gets, defined once. An SDK session gets them as Pi tools;
+// a terminal session gets them from the `agentx-wiki` command or the bundled MCP server. All of
+// them reach the same calls.
+
+export type WikiCall =
+  | 'memory.append' | 'memory.replace' | 'memory.rethink'
+  | 'recall.search' | 'recall.read'
+  | 'wiki.entrypoint' | 'wiki.search' | 'wiki.read' | 'wiki.list' | 'wiki.skill' | 'wiki.memory' | 'wiki.propose'
+
+/** A JSON Schema object, kept loose so TypeBox, MCP, and the CLI can all use it. */
+export type JsonSchema = { type: string; properties?: Record<string, unknown>; required?: string[]; [key: string]: unknown }
+
+export interface WikiToolDefinition {
+  name: string
+  call: WikiCall
+  label: string
+  description: string
+  parameters: JsonSchema
+  /** The compiled prompt is injected at launch; the tool exists for sessions that need it again. */
+  bootstrap?: boolean
+}
+
+/** The kinds of entry a model names. A fact was called `memory` before; that word is still accepted. */
+export const WIKI_ENTRY_KINDS = ['page', 'fact', 'block', 'skill', 'rule', 'prompt'] as const
+export const WIKI_PAGE_TYPES = ['project', 'person', 'concept', 'decision', 'summary', 'question', 'reference'] as const
+export const WIKI_MEMORY_KINDS = ['preference', 'fact', 'decision', 'feedback'] as const
+export const WIKI_LINK_TYPES = ['references', 'depends_on', 'supersedes', 'contradicts', 'produced_by', 'uses'] as const
+
+const text = (description: string) => ({ type: 'string', description })
+const block = text('The block\'s label as shown in your memory blocks: user, persona, notes, project/<slug>, or a shared block\'s label')
+
+/** Core memory: the blocks that are always in the caller's context. */
+export const MEMORY_TOOLS: WikiToolDefinition[] = [
+  {
+    name: 'memory_append',
+    call: 'memory.append',
+    label: 'Add to memory',
+    description:
+      'Add a line or short passage to the end of one of your memory blocks. Use it when you learn something worth keeping across conversations: about the user, about how you work, or about a project. The change is saved at once and the user can undo it.',
+    parameters: { type: 'object', properties: { block, text: text('What to add') }, required: ['block', 'text'] }
+  },
+  {
+    name: 'memory_replace',
+    call: 'memory.replace',
+    label: 'Correct memory',
+    description: 'Replace one exact passage in a memory block, to correct or remove something that is no longer true. Copy the old passage exactly; pass an empty new passage to delete it.',
+    parameters: { type: 'object', properties: { block, old: text('The exact passage to replace'), new: text('What replaces it') }, required: ['block', 'old', 'new'] }
+  },
+  {
+    name: 'memory_rethink',
+    call: 'memory.rethink',
+    label: 'Rewrite memory',
+    description: 'Rewrite a whole memory block, to condense it when it is close to its limit or has grown repetitive. Keep everything that is still true and useful.',
+    parameters: { type: 'object', properties: { block, body: text('The complete new content of the block') }, required: ['block', 'body'] }
+  }
+]
+
+/** History: what was said and done in earlier conversations and runs. */
+export const RECALL_TOOLS: WikiToolDefinition[] = [
+  {
+    name: 'history_search',
+    call: 'recall.search',
+    label: 'Search history',
+    description:
+      'Search what was said and done before: your earlier conversations (including a chat the user cleared), tool use, and Harness runs. Any word may match; the best matches come first. An agent searches its own conversations unless scope is "all" or a project is given. A Harness session searches Harness runs in its own project.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: text('Words to look for'),
+        scope: { type: 'string', enum: ['mine', 'all'], description: 'mine (default): your own conversations. all: every conversation and Harness run.' },
+        project: text('Only Harness runs in this project (its name or slug)'),
+        since: text('Only from this date on, as YYYY-MM-DD'),
+        limit: { type: 'integer', minimum: 1, maximum: 30 }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'history_read',
+    call: 'recall.read',
+    label: 'Read a run',
+    description: 'Read one earlier run in order: the request, the replies, and the tools used. Pass a run id from history_search.',
+    parameters: { type: 'object', properties: { run: text('Run id') }, required: ['run'] }
+  }
+]
+
+export const WIKI_TOOLS: WikiToolDefinition[] = [
+  ...MEMORY_TOOLS,
+  ...RECALL_TOOLS,
+  {
+    name: 'wiki_entrypoint',
+    call: 'wiki.entrypoint',
+    label: 'Context pack',
+    description: 'Your {product} context pack again: memory blocks, rules, the skills index, the project map, and tool guidance. It is already in your instructions at the start; call this to see its current state.',
+    parameters: { type: 'object', properties: {} },
+    bootstrap: true
+  },
+  {
+    name: 'wiki_search',
+    call: 'wiki.search',
+    label: 'Search Wiki',
+    description:
+      'Search everything written down in {product}: the Library, every project namespace, facts, skills, rules, and prompts. Results from the current project rank higher. Each hit has a path and an [id@revision] citation.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: text('What to look for'),
+        kinds: { type: 'array', items: { type: 'string', enum: [...WIKI_ENTRY_KINDS] }, description: 'Only these kinds of entries' },
+        namespace: text('Only this namespace, such as /library or /projects/<name>'),
+        limit: { type: 'integer', minimum: 1, maximum: 50 }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'wiki_read',
+    call: 'wiki.read',
+    label: 'Read Wiki entry',
+    description: 'Read one Wiki page, fact, skill, rule, or prompt in full, with its sources, links, and backlinks. Pass an id (arch, skills/review) or a Wiki path (/projects/agent-x/arch).',
+    parameters: { type: 'object', properties: { id: text('Entry id or Wiki path'), revision: text('Optional pinned revision selected for this reply'), offset: { type: 'integer', minimum: 0, description: 'Character offset when reading a pinned revision; use nextOffset to continue.' } }, required: ['id'] }
+  },
+  {
+    name: 'wiki_list',
+    call: 'wiki.list',
+    label: 'List Wiki',
+    description: 'List Wiki namespaces and pages (optionally in one namespace), or all facts, skills, rules, or prompts.',
+    parameters: {
+      type: 'object',
+      properties: { namespace: text('A namespace such as /library or /projects/<name>'), kind: { type: 'string', enum: [...WIKI_ENTRY_KINDS] } }
+    }
+  },
+  {
+    name: 'skill_load',
+    call: 'wiki.skill',
+    label: 'Load skill',
+    description: "Load a skill's instructions by name, or list every skill (and which are active) when no name is given. Follow a skill's steps when the task matches it.",
+    parameters: { type: 'object', properties: { name: text('Skill name or id, such as review or skills/review') } }
+  },
+  {
+    name: 'memory_facts',
+    call: 'wiki.memory',
+    label: 'Recall facts',
+    description: 'Recall facts: short statements, preferences, decisions, and feedback. Without a query it returns the facts that apply to the current project.',
+    parameters: { type: 'object', properties: { query: text('What to recall'), namespace: text('/ or a project namespace') } }
+  },
+  {
+    name: 'wiki_propose',
+    call: 'wiki.propose',
+    label: 'Propose Wiki update',
+    description:
+      'Record durable knowledge. kind "fact" for a short fact, preference, decision, or piece of feedback, "page" to update an existing page or add one about an entity or concept (not about one run), or "skill"/"rule"/"prompt" to suggest a change to those. ' +
+      'Cite evidence in sourceRefs: {"kind":"run","ref":"current","excerpt":"…"} with a passage copied exactly from this conversation or run (what the user wrote, or what you already said), a source id, or a URL. ' +
+      'A run reference without an excerpt found in the run is not evidence. Cited pages and facts apply right away (with undo); uncited or low-confidence ones, and every skill, rule, or prompt change, wait in the Wiki Inbox for the user. Never include secrets.',
+    parameters: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: [...WIKI_ENTRY_KINDS] },
+        title: text('Title (or the skill/rule/prompt name)'),
+        body: text('Markdown body. For a fact, a few lines.'),
+        id: text('Existing id to update'),
+        type: text(`Page type (${WIKI_PAGE_TYPES.join(', ')}) or what sort of fact (${WIKI_MEMORY_KINDS.join(', ')})`),
+        namespace: text('Where it belongs: /library, /projects/<name>, or / for a fact that applies everywhere. Defaults to the current project.'),
+        confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+        description: text('One line for a skill, rule, or prompt'),
+        supersedes: text('Id of a fact this one replaces'),
+        volatile: { type: 'boolean', description: 'For a fact: true when it describes current state that will change (an open issue list, who is on call)' },
+        reason: text('Why this change is needed (skills, rules, prompts)'),
+        sourceRefs: {
+          type: 'array',
+          items: { type: 'object', properties: { kind: { type: 'string', enum: ['run', 'source', 'url'] }, ref: { type: 'string' }, excerpt: { type: 'string', description: 'For a run or source: a passage copied exactly from it' } }, required: ['kind'] }
+        },
+        links: {
+          type: 'array',
+          items: { type: 'object', properties: { toId: { type: 'string' }, type: { type: 'string', enum: [...WIKI_LINK_TYPES] } }, required: ['toId', 'type'] }
+        }
+      },
+      required: ['kind', 'title', 'body']
+    }
+  }
+]
+
+/** Tools agents get when the context pack is already in their instructions. */
+/** A tool's description with the application's name in it. */
+export const describeTool = (tool: WikiToolDefinition, productName: string): string => tool.description.replaceAll('{product}', productName)
+
+export const WIKI_AGENT_TOOLS = WIKI_TOOLS.filter((tool) => !tool.bootstrap)
+export const WIKI_TOOL_NAMES = WIKI_AGENT_TOOLS.map((tool) => tool.name)