@xingular/harness 0.1.7 → 1.1.1

package/src/sessions/sessions.ts

@@ -1,339 +0,0 @@
-// Starting a session turn: the account, the run record, the compiled prompt, the tools and
-// their gate, then Pi. Everything before Pi answers is synchronous with the caller; the reply
-// itself streams as run events.
-import { existsSync, mkdirSync } from 'node:fs'
-import { join } from 'node:path'
-
-import type { Accounts } from '../accounts/accounts'
-import { log } from '../core/bus'
-import type { HarnessEnv } from '../core/env'
-import { HarnessError, invalid } from '../core/errors'
-import { capabilitySet as parseCapabilitySet, freezeRun } from '../capabilities/runSnapshot'
-import type { CapabilitySet } from '../capabilities/types'
-import { now, writeJson } from '../core/fs'
-import { takeChars } from '../core/text'
-import type { CallerContext } from '../memory/caller'
-import type { DispatchEnv } from '../memory/dispatch'
-import type { Plugins } from '../plugins/plugins'
-import { sessionLaunch, type Launch } from '../prompt/compile'
-import * as attachments from '../plugins/attachments'
-import { FIRST_PARTY_PLUGINS, firstPartyExtensions, type InlineExtension } from '../plugins/firstParty'
-import * as registry from '../skills/registry'
-import { ASK_USER, askUserTool } from '../tools/askUser'
-import { PLUGIN_PROPOSE, pluginProposeTool } from '../tools/pluginPropose'
-import { SPAWN_SUBAGENT, SUBAGENT_RELATION, spawnSubagentTool, subagentDepth, type SubagentOptions } from '../tools/spawnSubagent'
-import { WIKI_TOOL_NAMES } from '../tools/definitions'
-import { memoryTools } from '../tools/memoryTools'
-import type { ToolProvider, ToolSession, ToolSpec } from '../tools/types'
-import type { RunRecord } from './contracts'
-import { selectHistory } from './history'
-import { runLineageJoin } from './lineageJoin'
-import type { ToolPolicy } from './policy'
-import type { ActiveRun, RunRegistry } from './registry'
-import { piSessionFactory, runTurn, summarize, type Effort, type PiSessionLike, type SessionFactory, type ToolGate, type TurnParams } from './runner'
-import { loadRun, runDir, saveRun, updateRun } from './runStore'
-
-/** The fields of a run record the caller decides; the harness fills in the rest. */
-export type RunFields = Pick<RunRecord, 'id' | 'sessionId'> & Partial<Pick<RunRecord, 'mode' | 'harness' | 'sessionType' | 'projectId' | 'agentId' | 'trigger' | 'goal' | 'attachmentCount' | 'resumedFromRunId' | 'parentRunId' | 'relation' | 'worktreeId' | 'handoffId'>>
-
-export interface SessionRunInput {
-  run: RunFields
-  /** The account this session is pinned to. A new session may name a pool, or neither for the default. */
-  accountId?: string | null
-  poolId?: string | null
-  model?: string | null
-  effort?: Effort | null
-  cwd: string
-  /** Where this session's native history lives. */
-  sessionDir: string
-  /** Continue exactly this recorded history; never another one. */
-  resume?: { sessionFile?: string | null; nativeSessionId?: string | null } | null
-  text: string
-  images?: { mediaType: string; data: string }[]
-  /** Reject a resolved model that cannot inspect image content. */
-  requiresImageInput?: boolean
-  preamble?: string | null
-  /** Unattended: no project extensions, no context files, nothing may ask a person. */
-  automatic?: boolean
-  /** Who the session works as, for memory and the prompt. */
-  caller: CallerContext
-  /** What the application adds to the prompt, and which tools it describes. */
-  launch?: Launch
-  /** The tools switched on, in the order the model sees them, and those that ask before each call. */
-  tools: { allow: string[]; gated?: string[] }
-  /** Give the session the connected-apps broker. */
-  connections?: boolean | { readOnly?: boolean }
-  /** Optional narrower set for a child run; the harness intersects it with current availability. */
-  capabilities?: CapabilitySet
-  /** Hops from the user to this session (0 when the user started it). */
-  depth?: number
-  /** Offer `spawn_subagent`: the model may start child runs of this caller, up to this depth. */
-  subagents?: SubagentOptions | null
-  /** Ask the application's tool providers for tools (the default). False runs with the harness's own tools only. */
-  providers?: boolean
-}
-
-/** The connected-apps broker, as a session sees it. */
-export interface SessionBroker {
-  toolNames: readonly string[]
-  tools(session: ToolSession, options: { readOnly: boolean }): ToolSpec[]
-}
-
-export interface SessionsOptions {
-  env: DispatchEnv
-  accounts: Accounts
-  runs: RunRegistry
-  policy: ToolPolicy
-  broker?: SessionBroker | null
-  /** Chooses what a session loads. Without it Pi discovers extensions and skills on its own. */
-  plugins?: Plugins
-  /** Resolves the caller's capability set from the harness's stores. */
-  resolveCapabilities?: (caller: CallerContext, tools: readonly string[], cwd: string) => Promise<CapabilitySet>
-  factory?: SessionFactory
-}
-
-/** The harness's own plugins a person switched on for this caller, with the numbers they set. */
-function firstPartyFor(root: string, contributions: readonly string[]): InlineExtension[] {
-  const choices = attachments.load(root)
-  const allowed = new Set(contributions)
-  return firstPartyExtensions((id) => FIRST_PARTY_PLUGINS.find((plugin) => plugin.id === id)?.code?.some((code) => allowed.has(`${id}/code/${code.name}`)) ?? false, choices.settings)
-}
-
-export class Sessions {
-  private readonly providers: ToolProvider[] = []
-  private readonly factory: SessionFactory
-
-  constructor(private readonly options: SessionsOptions) {
-    this.factory = options.factory ?? piSessionFactory
-  }
-
-  private get env(): HarnessEnv {
-    return this.options.env
-  }
-
-  /** Adds tools an application provides. Providers are asked in the order they were added. */
-  provide(provider: ToolProvider): void {
-    this.providers.push(provider)
-  }
-
-  private gate(run: ActiveRun, caller: CallerContext, gated: Set<string>): ToolGate {
-    const { policy } = this.options
-    return {
-      ask: (names) => {
-        for (const name of names) gated.add(name)
-      },
-      check: async (tool, args) => {
-        const call = { run: loadRun(this.env.root, run.runId), caller, tool, args }
-        const scope = (await policy.scope?.(call)) ?? { allowed: true }
-        if (!scope.allowed && (scope.automatic || !scope.requiresApproval)) return scope.reason ?? 'Outside the approved work scope.'
-        try {
-          await policy.authorize?.(call)
-        } catch (error) {
-          return error instanceof Error ? error.message : 'Tool unavailable in the app settings.'
-        }
-        if (scope.allowed && !scope.humanOnly && (scope.automatic || !gated.has(tool))) return null
-        // A call outside the scope is approved one at a time; a gated tool may be remembered, unless only a person may decide it.
-        const decision = await run.requestApproval({
-          target: tool,
-          action: summarize(args),
-          operation: { tool, args: (args && typeof args === 'object' ? args : {}) as Record<string, unknown> },
-          rememberable: scope.allowed && !scope.humanOnly,
-          standing: scope.humanOnly ? (scope.allowGlobalApproval ? 'switch' : 'none') : undefined
-        })
-        if (decision !== 'approved') return 'The user denied this action. Ask how they would like to proceed.'
-        try {
-          await policy.authorize?.(call)
-        } catch (error) {
-          return error instanceof Error ? error.message : 'Tool was disabled while waiting.'
-        }
-        return null
-      }
-    }
-  }
-
-  /** `spawn_subagent` for a run: each child is this caller again, one hop deeper, with no more tools than the parent. */
-  private subagentTool(input: SessionRunInput, runId: string, accountId: string, parent: CapabilitySet): ToolSpec {
-    const parentTools = parent.tools.filter((name) => name !== SPAWN_SUBAGENT)
-    return spawnSubagentTool({
-      root: this.env.root,
-      parentRunId: runId,
-      parentSessionId: input.run.sessionId,
-      parentTools,
-      sessionDir: input.sessionDir,
-      start: (child) => this.run({
-        ...input,
-        run: { ...input.run, id: child.runId, sessionId: child.sessionId, parentRunId: runId, relation: SUBAGENT_RELATION, goal: takeChars(child.brief, 4000), resumedFromRunId: null, handoffId: null },
-        accountId,
-        poolId: null,
-        sessionDir: child.sessionDir,
-        resume: null,
-        text: child.brief,
-        images: undefined,
-        requiresImageInput: false,
-        preamble: null,
-        caller: { ...input.caller, runId: undefined, sessionId: child.sessionId },
-        tools: { allow: [...child.tools, SPAWN_SUBAGENT], gated: (input.tools.gated ?? []).filter((name) => child.tools.includes(name)) },
-        // Never wider than the parent's frozen set; the session intersects it with what is available now.
-        capabilities: { ...parent, tools: [...parent.tools.filter((name) => child.tools.includes(name)), SPAWN_SUBAGENT] },
-        depth: (input.depth ?? 0) + 1
-      })
-    })
-  }
-
-  /**
-   * Starts one turn. Returns once the Pi session is open; the reply arrives as run events. A
-   * session that cannot be opened ends its run as failed and returns no native session id.
-   */
-  async run(input: SessionRunInput): Promise<{ runId: string; nativeSessionId: string | null }> {
-    const { root } = this.env
-    if (!input?.run?.id || !input.run.sessionId || typeof input.text !== 'string') throw invalid('A session turn needs a run id, a session, and text.')
-    const historyFile = selectHistory({ sessionDir: input.sessionDir, resume: input.resume })
-    const account = this.options.accounts.resolve(input.accountId, input.poolId)
-    const context = this.options.accounts.context(account)
-    const runId = input.run.id
-    const caller: CallerContext = { ...input.caller, maintenanceJobIds: input.caller.maintenanceJobIds?.slice(), runId, sessionId: input.caller.sessionId ?? input.run.sessionId }
-    const broker = input.connections ? this.options.broker : null
-    const depth = input.depth ?? 0
-    const canSpawn = Boolean(input.subagents) && depth < subagentDepth(input.subagents ?? undefined)
-    const requestedTools = [...new Set([
-      ...input.tools.allow.filter((name) => name !== SPAWN_SUBAGENT),
-      ASK_USER,
-      ...(input.automatic ? [] : [PLUGIN_PROPOSE]),
-      ...WIKI_TOOL_NAMES,
-      ...(broker?.toolNames ?? []),
-      ...(canSpawn ? [SPAWN_SUBAGENT] : [])
-    ])]
-    const available = this.options.resolveCapabilities
-      ? await this.options.resolveCapabilities(caller, requestedTools, input.cwd)
-      : { version: 1 as const, tools: requestedTools, connectors: [], contributions: [] }
-    const requested = input.capabilities ? parseCapabilitySet(input.capabilities) : available
-    const capabilities: CapabilitySet = {
-      version: 1,
-      tools: available.tools.filter((tool) => requested.tools.includes(tool)),
-      connectors: available.connectors.filter((id) => requested.connectors.includes(id)),
-      contributions: available.contributions.filter((id) => requested.contributions.includes(id))
-    }
-    freezeRun(root, runId, caller, capabilities)
-
-    saveRun(root, {
-      resumedFromRunId: input.run.resumedFromRunId ?? null,
-      parentRunId: input.run.parentRunId ?? null,
-      relation: input.run.relation ?? null,
-      terminalReason: null,
-      id: runId,
-      projectId: input.run.projectId ?? caller.projectId ?? null,
-      mode: input.run.mode ?? 'chat',
-      harness: input.run.harness ?? 'pi',
-      sessionType: input.run.sessionType ?? 'structured',
-      sessionId: input.run.sessionId,
-      nativeSessionId: null,
-      workingDirectory: input.cwd,
-      worktreeId: input.run.worktreeId ?? null,
-      goal: input.run.goal ?? takeChars(input.text, 4000),
-      attachmentCount: input.run.attachmentCount ?? 0,
-      startedAt: now(),
-      endedAt: null,
-      status: 'queued',
-      exitCode: null,
-      handoffId: input.run.handoffId ?? null,
-      accountId: account.id,
-      agentId: input.run.agentId ?? caller.agentId ?? null,
-      trigger: input.run.trigger ?? null
-    })
-
-    // What the session is, kept with the run so later consolidation knows which memory it had.
-    try {
-      writeJson(join(runDir(root, runId), 'caller.json'), caller)
-    } catch {
-      // Consolidation falls back to what the run record says.
-    }
-
-    const fail = (error: unknown, code = 'provider_unavailable'): void => {
-      const message = error instanceof Error ? error.message : String(error)
-      updateRun(root, runId, (record) => Object.assign(record, { status: 'failed', endedAt: now(), terminalReason: message }))
-      log(`session ${runId} did not start: ${message}`, code)
-    }
-
-    let system: string
-    let update: TurnParams['update']
-    try {
-      if (!existsSync(input.sessionDir)) mkdirSync(input.sessionDir, { recursive: true })
-      const launch = input.launch ?? {}
-      const effectiveLaunch = {
-        ...launch,
-        tools: capabilities.tools,
-        connectionTools: (launch.connectionTools ?? []).filter((name) => capabilities.tools.includes(name)),
-        toolGroups: launch.toolGroups?.map((group) => ({ ...group, tools: group.tools.filter((name) => capabilities.tools.includes(name)) })).filter((group) => group.tools.length > 0)
-      }
-      ;({ system, update } = sessionLaunch(this.env, caller, effectiveLaunch, historyFile, capabilities.contributions))
-    } catch (error) {
-      fail(error)
-      throw error
-    }
-
-    const run = this.options.runs.start(input.run.sessionId, runId)
-    if (run.finished) return { runId, nativeSessionId: null }
-    // What every session has, after the tools the caller switched on and in a fixed order.
-    const allow = capabilities.tools
-    const session: ToolSession = { run, caller, allow, depth, cwd: input.cwd, capabilities }
-    const { plugins } = this.options
-
-    let pi: PiSessionLike
-    try {
-      const tools: ToolSpec[] = [
-        ...(broker ? broker.tools(session, { readOnly: typeof input.connections === 'object' && input.connections.readOnly === true }) : []),
-        ...memoryTools(this.options.env, caller, capabilities.contributions),
-        askUserTool(run),
-        pluginProposeTool(this.options.env, caller),
-        ...(allow.includes(SPAWN_SUBAGENT) ? [this.subagentTool(input, runId, account.id, capabilities)] : [])
-      ]
-      if (input.providers !== false) for (const provider of this.providers) tools.push(...(await provider(session)))
-      const params: TurnParams = {
-        runId,
-        cwd: input.cwd,
-        sessionDir: input.sessionDir,
-        historyFile,
-        model: input.model ?? null,
-        effort: input.effort ?? null,
-        text: input.text,
-        images: input.images,
-        requiresImageInput: input.requiresImageInput,
-        preamble: input.preamble ?? null,
-        automatic: input.automatic,
-        account: context,
-        resources: registry.resources(root, caller.projectId ?? null, caller.agentId ?? null, capabilities.contributions),
-        inline: [...firstPartyFor(root, capabilities.contributions), runLineageJoin(root, runId)],
-        ...(plugins ? { plugins: { loading: () => plugins.loading({ cwd: input.cwd, agentDir: context.configDir, install: true, caller: { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null }, contributions: capabilities.contributions }), loaded: (extensions) => plugins.loaded(extensions) } } : {}),
-        system,
-        update
-      }
-      pi = await this.factory({
-        params,
-        allow,
-        gate: this.gate(run, caller, new Set((input.tools.gated ?? []).filter((name) => capabilities.tools.includes(name)))),
-        tools,
-        runtime: () => this.options.accounts.runtime(context),
-        // An unattended run loads no extension, so it has nobody to relay for.
-        ...(input.automatic ? {} : { extensions: { ask: (question) => run.requestAnswer(question), notice: (notice) => run.emit('extension.notice', notice) } })
-      })
-      if ((input.requiresImageInput || input.images?.length) && !pi.model?.input.includes('image')) {
-        pi.dispose()
-        throw new HarnessError('image_input_unsupported', 'Choose a model that supports images, or remove the image attachments and send again.')
-      }
-      if (input.resume?.nativeSessionId && pi.sessionId !== input.resume.nativeSessionId) {
-        pi.dispose()
-        run.finish('failed', { code: 'native_resume_unavailable', message: 'The saved conversation could not be restored.' })
-        throw new HarnessError('native_resume_unavailable', 'The saved conversation could not be restored.')
-      }
-      updateRun(root, runId, (record) => void (record.nativeSessionId = pi.sessionId))
-      void runTurn(run, pi, params)
-      return { runId, nativeSessionId: pi.sessionId }
-    } catch (error) {
-      if (error instanceof HarnessError && error.code === 'native_resume_unavailable') throw error
-      const message = error instanceof Error ? error.message : String(error)
-      log('session failed to start', message)
-      run.finish('failed', { code: error instanceof HarnessError ? error.code : 'provider_unavailable', message })
-      return { runId, nativeSessionId: null }
-    }
-  }
-}

package/src/skills/registry.test.ts

@@ -1,104 +0,0 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { expect, test } from 'vitest'
-
-import { writeJson } from '../core/fs'
-import { isDir, isFile } from '../memory/store'
-import { enabledFor, importSkills, itemBody, list, removeLinkedSkills, resources } from './registry'
-
-const temp = () => mkdtempSync(join(tmpdir(), 'harness-registry-'))
-
-test('lists items and resolves enablement', () => {
-  const root = temp()
-  mkdirSync(join(root, 'registry/rules'), { recursive: true })
-  mkdirSync(join(root, 'registry/skills/release-notes'), { recursive: true })
-  writeFileSync(join(root, 'registry/rules/tests.md'), '---\nname: Run tests\n---\n\nAlways run the test suite before finishing.\n')
-  writeFileSync(join(root, 'registry/skills/release-notes/SKILL.md'), '# Release notes\n\nWrite release notes from commits.\n')
-  const items = list(root)
-  expect(items.map((item) => item.id)).toEqual(['rules/tests', 'skills/release-notes'])
-  expect(items[0].name).toBe('Run tests')
-  expect(items[1].description).toBe('Write release notes from commits.')
-
-  writeJson(join(root, 'config/registry-enabled.json'), { p1: ['rules/tests'], global: ['skills/release-notes'] })
-  const ids = (project: string | null) => enabledFor(root, project).map((item) => item.id)
-  expect(ids('p1')).toEqual(['rules/tests', 'skills/release-notes'])
-  expect(ids(null)).toEqual(['skills/release-notes'])
-  expect(itemBody(items[0]).trim()).toBe('Always run the test suite before finishing.')
-  expect(resources(root, null).skillPaths[0].endsWith('registry/skills/release-notes/SKILL.md')).toBe(true)
-})
-
-test('removes the links an earlier version made and keeps the user\'s own skills', () => {
-  const root = temp()
-  mkdirSync(join(root, 'registry/skills/release-notes'), { recursive: true })
-  writeFileSync(join(root, 'registry/skills/release-notes/SKILL.md'), '# Release notes\n')
-  writeFileSync(join(root, 'registry/skills/triage.md'), '# Triage\n')
-  const skills = join(root, 'shared/skills')
-  mkdirSync(join(skills, 'mine'), { recursive: true })
-  mkdirSync(join(skills, 'agentx-handmade'), { recursive: true })
-  writeFileSync(join(skills, 'agentx-handmade/SKILL.md'), "user's")
-  symlinkSync(join(root, 'registry/skills/release-notes'), join(skills, 'agentx-release-notes'))
-  mkdirSync(join(skills, 'agentx-triage'))
-  symlinkSync(join(root, 'registry/skills/triage.md'), join(skills, 'agentx-triage/SKILL.md'))
-
-  removeLinkedSkills(skills)
-  expect(existsSync(join(skills, 'agentx-release-notes')) || existsSync(join(skills, 'agentx-triage'))).toBe(false)
-  expect(isDir(join(skills, 'mine')) && isFile(join(skills, 'agentx-handmade/SKILL.md'))).toBe(true)
-  expect(isFile(join(root, 'registry/skills/release-notes/SKILL.md')) && isFile(join(root, 'registry/skills/triage.md'))).toBe(true)
-  removeLinkedSkills(join(root, 'no-such-folder'))
-})
-
-test('imports complete skill folders without replacing registry items', () => {
-  const root = temp()
-  const state = importSkills(root, [{
-    name: 'Source Review',
-    files: [
-      { path: 'SKILL.md', content: '# Source review\n', encoding: 'utf8' },
-      { path: 'references/checklist.md', content: 'Check the source first.\n', encoding: 'utf8' },
-      { path: 'assets/icon.bin', content: Buffer.from([0, 1, 255]).toString('base64'), encoding: 'base64' }
-    ]
-  }])
-
-  expect(state.items.map((item) => item.id)).toContain('skills/source-review')
-  expect(readFileSync(join(root, 'registry/skills/source-review/references/checklist.md'), 'utf8')).toBe('Check the source first.\n')
-  expect(readFileSync(join(root, 'registry/skills/source-review/assets/icon.bin'))).toEqual(Buffer.from([0, 1, 255]))
-  expect(() => importSkills(root, [{ name: 'Source Review', files: [{ path: 'SKILL.md', content: 'replacement', encoding: 'utf8' }] }])).toThrow('already exists')
-  expect(readFileSync(join(root, 'registry/skills/source-review/SKILL.md'), 'utf8')).toBe('# Source review\n')
-})
-
-test('rejects unsafe or incomplete skill folders without writing partial files', () => {
-  const root = temp()
-  expect(() => importSkills(root, [{
-    name: 'Unsafe',
-    files: [
-      { path: 'SKILL.md', content: 'valid', encoding: 'utf8' },
-      { path: '../escape.md', content: 'no', encoding: 'utf8' }
-    ]
-  }])).toThrow('path outside')
-  expect(() => importSkills(root, [{ name: 'Missing root skill', files: [{ path: 'references/SKILL.md', content: 'no', encoding: 'utf8' }] }])).toThrow('must include SKILL.md')
-  expect(list(root)).toEqual([])
-})
-
-test('does not replace an unindexed folder at the imported skill path', () => {
-  const root = temp()
-  const orphan = join(root, 'registry/skills/orphan')
-  mkdirSync(orphan, { recursive: true })
-  writeFileSync(join(orphan, 'notes.txt'), 'keep')
-
-  expect(() => importSkills(root, [{ name: 'orphan', files: [{ path: 'SKILL.md', content: 'replacement', encoding: 'utf8' }] }])).toThrow('already exists')
-  expect(readFileSync(join(orphan, 'notes.txt'), 'utf8')).toBe('keep')
-  expect(existsSync(join(orphan, 'SKILL.md'))).toBe(false)
-})
-
-test('rejects portable path collisions before writing a skill folder', () => {
-  const root = temp()
-  expect(() => importSkills(root, [{
-    name: 'Case collision',
-    files: [
-      { path: 'SKILL.md', content: 'valid', encoding: 'utf8' },
-      { path: 'assets/Icon.png', content: 'one', encoding: 'utf8' },
-      { path: 'assets/icon.png', content: 'two', encoding: 'utf8' }
-    ]
-  }])).toThrow('duplicate file path')
-  expect(list(root)).toEqual([])
-})