@xingular/harness 0.0.0-stage → 0.1.0

package/src/accounts/env.ts

@@ -0,0 +1,204 @@
+// Isolated launch environments. Every Pi session the harness starts gets its account's own
+// agent folder (`PI_CODING_AGENT_DIR`) under the state directory, and inherited credential
+// variables are removed. A launch that would fall back to `~/.pi` is refused.
+//
+// Settings, skills, prompts, and instructions are shared by every account: the account's agent
+// folder links those entries to `_shared/pi/`. Credentials, sessions, and history stay in the
+// account's own folder.
+import { chmodSync, lstatSync, mkdirSync, readlinkSync, renameSync, symlinkSync, unlinkSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, dirname, join, sep } from 'node:path'
+
+import { HarnessError } from '../core/errors'
+import type { Account } from './store'
+
+// Config-directory variables the harness always sets itself, including those of other tools so
+// a session can never inherit them.
+const DIR_VARS = ['CODEX_HOME', 'CLAUDE_CONFIG_DIR', 'PI_CODING_AGENT_DIR']
+
+/** Inherited variables that carry credentials; they would bypass the account's own sign-in. */
+export function isCredentialVar(name: string): boolean {
+  const upper = name.toUpperCase()
+  return DIR_VARS.includes(upper) || ['_API_KEY', '_AUTH_TOKEN', '_OAUTH_TOKEN', '_ACCESS_TOKEN'].some((suffix) => upper.endsWith(suffix))
+}
+
+/** Names of inherited variables to remove from a session's process. */
+export function inheritedCredentialVars(env: NodeJS.ProcessEnv = process.env): string[] {
+  const names = Object.keys(env).filter(isCredentialVar)
+  for (const name of DIR_VARS) if (!names.includes(name)) names.push(name)
+  return names
+}
+
+/**
+ * Makes this process safe to run Pi sessions in: credentials come only from an account's own
+ * store, so inherited credential variables are dropped, and Pi's fallback agent folder is an
+ * empty one under the state directory rather than `~/.pi`.
+ */
+export function isolateProcess(accountsDir: string, env: NodeJS.ProcessEnv = process.env): void {
+  for (const name of inheritedCredentialVars(env)) delete env[name]
+  const fallback = join(accountsDir, '.sidecar', 'pi')
+  mkdirSync(fallback, { recursive: true })
+  env.PI_CODING_AGENT_DIR = fallback
+}
+
+export const homeDir = (accountsDir: string, accountId: string): string => join(accountsDir, accountId, 'home')
+/** Pi's agent folder for this account. */
+export const configDir = (accountsDir: string, account: Pick<Account, 'id'>): string => join(homeDir(accountsDir, account.id), 'pi')
+/** The agent-folder entries every account shares. */
+export const sharedDir = (accountsDir: string): string => join(accountsDir, '_shared', 'pi')
+
+function makePrivate(path: string): void {
+  mkdirSync(path, { recursive: true })
+  chmodSync(path, 0o700)
+}
+
+// Entries every account shares, and whether each is a folder. Credentials (`auth.json`),
+// sessions, and history are never listed.
+const SHARED_ENTRIES: readonly (readonly [string, boolean])[] = [
+  ['settings.json', false],
+  ['models.json', false],
+  ['AGENTS.md', false],
+  ['SYSTEM.md', false],
+  ['skills', true],
+  ['prompts', true],
+  ['extensions', true],
+  ['themes', true],
+  // Where Pi keeps installed packages: one install serves every account.
+  ['npm', true],
+  ['git', true]
+]
+
+export interface NativeConfig {
+  provider: string
+  path: string
+  entries: { name: string; directory: boolean; present: boolean }[]
+}
+
+const present = (path: string): boolean => {
+  try {
+    lstatSync(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** What the accounts share, and which of it exists yet. Reads only; nothing is created. */
+export function nativeConfig(accountsDir: string): NativeConfig {
+  const shared = sharedDir(accountsDir)
+  return { provider: 'pi', path: shared, entries: SHARED_ENTRIES.map(([name, directory]) => ({ name, directory, present: present(join(shared, name)) })) }
+}
+
+/** The shared folder, created private if no account has linked it yet. */
+export function ensureSharedDir(accountsDir: string): string {
+  const shared = sharedDir(accountsDir)
+  makePrivate(shared)
+  return shared
+}
+
+const modified = (path: string): number => {
+  try {
+    return lstatSync(path).mtimeMs
+  } catch {
+    return -1
+  }
+}
+
+/** Moves a real file or folder aside so the shared link can take its place. */
+function backUp(path: string): void {
+  renameSync(path, join(dirname(path), `${basename(path)}.agentx-backup-${Math.floor(Date.now() / 1000)}`))
+}
+
+/**
+ * Links the account's shared entries to `_shared/pi/`. A real entry found in the account folder
+ * (from before sharing, or a tool that replaced the link while saving) becomes the shared copy
+ * when there is none or it is newer; otherwise it is kept as a backup.
+ */
+function linkShared(accountsDir: string, dir: string): void {
+  const shared = ensureSharedDir(accountsDir)
+  for (const [name, isDir] of SHARED_ENTRIES) {
+    const local = join(dir, name)
+    const target = join(shared, name)
+    let meta: ReturnType<typeof lstatSync> | null = null
+    try {
+      meta = lstatSync(local)
+    } catch {
+      meta = null
+    }
+    if (meta?.isSymbolicLink()) {
+      if (readlinkSync(local) === target) {
+        if (isDir) mkdirSync(target, { recursive: true })
+        continue
+      }
+      unlinkSync(local)
+    } else if (meta) {
+      if (!present(target)) renameSync(local, target)
+      else if (!isDir && modified(local) > modified(target)) {
+        backUp(target)
+        renameSync(local, target)
+      } else backUp(local)
+    }
+    if (isDir) mkdirSync(target, { recursive: true })
+    symlinkSync(target, local)
+  }
+}
+
+/** Creates the account's runtime folder and links the shared entries into it. */
+export function ensureHome(accountsDir: string, account: Pick<Account, 'id'>): string {
+  makePrivate(join(accountsDir, account.id))
+  makePrivate(homeDir(accountsDir, account.id))
+  const dir = configDir(accountsDir, account)
+  makePrivate(dir)
+  linkShared(accountsDir, dir)
+  return dir
+}
+
+const inside = (path: string, parent: string): boolean => path === parent || path.startsWith(parent.endsWith(sep) ? parent : `${parent}${sep}`)
+
+/**
+ * Refuses an agent folder that is (or is inside) a default tool folder, or that is not inside
+ * the harness's own accounts folder.
+ */
+export function assertIsolated(accountsDir: string, dir: string): void {
+  const defaults = ['.codex', '.claude', '.pi'].map((name) => join(homedir() || '/', name))
+  if (defaults.some((folder) => inside(dir, folder)) || !inside(dir, accountsDir)) {
+    throw new HarnessError('account_required', 'A session cannot start outside its isolated account folder.')
+  }
+}
+
+/** Variables to set, or remove (`null`), when launching a session for this account. */
+export function launchEnv(accountsDir: string, account: Pick<Account, 'id'>, inherited: NodeJS.ProcessEnv = process.env): Record<string, string | null> {
+  const dir = ensureHome(accountsDir, account)
+  assertIsolated(accountsDir, dir)
+  const env: Record<string, string | null> = {}
+  for (const name of inheritedCredentialVars(inherited)) env[name] = null
+  env.PI_CODING_AGENT_DIR = dir
+  return env
+}
+
+/** What a session needs to run for an account. */
+export interface AccountContext {
+  id: string
+  provider: 'pi'
+  label: string
+  /** Variables to set; `null` removes an inherited one. */
+  env: Record<string, string | null>
+  /** The account's own agent folder. */
+  configDir: string
+}
+
+export function accountContext(accountsDir: string, account: Account): AccountContext {
+  return { id: account.id, provider: 'pi', label: account.label, env: launchEnv(accountsDir, account), configDir: configDir(accountsDir, account) }
+}
+
+/** The process environment for a `pi` process launched on behalf of this account. */
+export function processEnv(account: AccountContext, inherited: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [name, value] of Object.entries(inherited)) if (value !== undefined) env[name] = value
+  for (const [name, value] of Object.entries(account.env)) {
+    if (value === null) delete env[name]
+    else env[name] = value
+  }
+  return env
+}
+

package/src/accounts/secrets.ts

@@ -0,0 +1,50 @@
+// Where credentials live. The harness never writes a secret to its own files: it asks the
+// store the embedding application provides (a Keychain, an encrypted vault), by key.
+import { chmodSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+import { atomicWrite, readJsonOr } from '../core/fs'
+
+export interface SecretStore {
+  get(key: string): Promise<string | null>
+  set(key: string, value: string): Promise<void>
+  delete(key: string): Promise<void>
+}
+
+/** `<account id>/<secret name>`: the key an account's secret is stored under. */
+export const secretKey = (accountId: string, name: string): string => `${accountId}/${name}`
+
+/** Secrets held only for the life of the process. For tests and throwaway runs. */
+export function memorySecretStore(initial: Record<string, string> = {}): SecretStore & { values: Map<string, string> } {
+  const values = new Map(Object.entries(initial))
+  return {
+    values,
+    get: async (key) => values.get(key) ?? null,
+    set: async (key, value) => void values.set(key, value),
+    delete: async (key) => void values.delete(key)
+  }
+}
+
+/**
+ * Secrets in one owner-only JSON file. For a host with no Keychain to offer; anything that can
+ * read the file can read every secret in it.
+ */
+export function fileSecretStore(path: string): SecretStore {
+  const read = (): Record<string, string> => readJsonOr<Record<string, string>>(path, {})
+  const write = (values: Record<string, string>): void => {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+    atomicWrite(path, `${JSON.stringify(values, null, 2)}\n`)
+    chmodSync(path, 0o600)
+  }
+  return {
+    get: async (key) => read()[key] ?? null,
+    set: async (key, value) => write({ ...read(), [key]: value }),
+    delete: async (key) => {
+      const values = read()
+      if (key in values) {
+        delete values[key]
+        write(values)
+      }
+    }
+  }
+}

package/src/accounts/store.ts

@@ -0,0 +1,338 @@
+// Accounts. One profile (settings, registry, memory) and any number of Pi accounts, each with
+// its own isolated agent folder, stored credentials, sign-in state, limits, health, and audit
+// trail.
+//
+// Device-local layout under `<state dir>/accounts/`:
+//   accounts.json        accounts, the default, pools (no secrets)
+//   <id>/state.json      health, plan, limits, last error (no secrets)
+//   <id>/home/pi/        Pi's own agent folder for this account
+//   _shared/pi/          settings, skills, prompts linked into every account's agent folder
+//   audit.jsonl          append-only account actions (secrets scrubbed)
+//
+// Switching is always manual. A pool only chooses an account when a session starts; a running
+// or resumed session keeps the account it started with.
+import { mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { HarnessError, invalid, notFound } from '../core/errors'
+import { appendLine, newId, now, readJsonOr, safeId, writeJson } from '../core/fs'
+import { charCount, compareText, lines, takeChars } from '../core/text'
+
+/** The only provider the harness runs. Records of other providers are kept in the file and ignored. */
+export const PROVIDER = 'pi'
+
+export interface Account {
+  id: string
+  provider: string
+  label: string
+  /** `subscription` (a provider's own sign-in) or `apiKey`. */
+  authKind: string
+  credentialStore?: string
+  createdAt: string
+}
+
+export interface Pool {
+  id: string
+  provider: string
+  label: string
+  accountIds: string[]
+}
+
+interface Registry {
+  accounts: Account[]
+  defaults: Record<string, string>
+  pools: Pool[]
+  migratedProviderKeys: boolean
+}
+
+export interface Limit {
+  id: string
+  label: string
+  usedPercent?: number | null
+  resetsAt?: string | null
+  windowMinutes?: number | null
+  /** `allowed`, `warning`, or `rejected` when the provider reports it. */
+  status?: string | null
+}
+
+export interface Issue {
+  /** `auth_expired`, `rate_limited`, `quota`, `network`, or `unknown`. */
+  category: string
+  message: string
+  at: string
+  resetsAt: string | null
+}
+
+export interface AccountState {
+  /** `ok`, `limited`, `auth_expired`, `signed_out`, `error`, or `unknown`. */
+  health: string
+  signedIn: boolean | null
+  authMethod: string | null
+  plan: string | null
+  identity: string | null
+  limits: Limit[]
+  lastError: Issue | null
+  lastCheckedAt: string | null
+  cliVersion: string | null
+  /** Features detected for this account, e.g. `models:12`, `provider:anthropic`. */
+  capabilities: string[]
+  /** Providers with a stored credential (names only). */
+  piProviders: string[]
+}
+
+export const emptyState = (): AccountState => ({ health: 'unknown', signedIn: null, authMethod: null, plan: null, identity: null, limits: [], lastError: null, lastCheckedAt: null, cliVersion: null, capabilities: [], piProviders: [] })
+
+export type AccountView = Account & { isDefault: boolean; state: AccountState }
+
+export interface AccountsOverview {
+  accounts: AccountView[]
+  pools: Pool[]
+  defaults: Record<string, string>
+}
+
+export interface AuditEntry {
+  at: string
+  accountId: string | null
+  action: string
+  detail: string
+}
+
+// ---- Files ------------------------------------------------------------------------------
+
+const registryPath = (dir: string): string => join(dir, 'accounts.json')
+const statePath = (dir: string, accountId: string): string => join(dir, safeId(accountId), 'state.json')
+
+export function loadRegistry(dir: string): Registry {
+  const stored = readJsonOr<Partial<Registry>>(registryPath(dir), {}) ?? {}
+  return { accounts: stored.accounts ?? [], defaults: stored.defaults ?? {}, pools: stored.pools ?? [], migratedProviderKeys: stored.migratedProviderKeys ?? false }
+}
+
+export function saveRegistry(dir: string, registry: Registry): void {
+  mkdirSync(dir, { recursive: true })
+  writeJson(registryPath(dir), registry)
+}
+
+export function loadState(dir: string, accountId: string): AccountState {
+  try {
+    return { ...emptyState(), ...(readJsonOr<Partial<AccountState>>(statePath(dir, accountId), {}) ?? {}) }
+  } catch {
+    return emptyState()
+  }
+}
+
+function saveState(dir: string, accountId: string, state: AccountState): void {
+  writeJson(statePath(dir, accountId), state)
+}
+
+/** Replaces anything that looks like a token so audit lines and stored errors never hold secrets. */
+export function scrub(text: string): string {
+  const words = text.split(' ').map((word) => {
+    const bytes = Buffer.byteLength(word)
+    const tokenLike = bytes >= 24 && (word.match(/[A-Za-z0-9]/g)?.length ?? 0) * 10 >= bytes * 8
+    return tokenLike || word.startsWith('sk-') || word.startsWith('sess-') ? '[redacted]' : word
+  })
+  return takeChars(words.join(' '), 500)
+}
+
+export function audit(dir: string, accountId: string | null, action: string, detail: string): void {
+  try {
+    mkdirSync(dir, { recursive: true })
+    appendLine(join(dir, 'audit.jsonl'), JSON.stringify({ at: now(), accountId, action, detail: scrub(detail) } satisfies AuditEntry))
+  } catch {
+    // An audit line that cannot be written never fails the action it describes.
+  }
+}
+
+/** The newest audit entries first, optionally for one account. */
+export function readAudit(dir: string, accountId?: string | null, limit = 100): AuditEntry[] {
+  let text = ''
+  try {
+    text = readFileSync(join(dir, 'audit.jsonl'), 'utf8')
+  } catch {
+    text = ''
+  }
+  const entries = lines(text).flatMap((line) => {
+    try {
+      const entry = JSON.parse(line) as AuditEntry
+      return entry && typeof entry.at === 'string' && typeof entry.action === 'string' && (!accountId || entry.accountId === accountId) ? [entry] : []
+    } catch {
+      return []
+    }
+  })
+  return entries.reverse().slice(0, Math.min(limit, 1000))
+}
+
+// ---- Health -----------------------------------------------------------------------------
+
+function inFuture(timestamp: string | null | undefined): boolean {
+  const time = timestamp ? Date.parse(timestamp) : Number.NaN
+  return !Number.isNaN(time) && time > Date.now()
+}
+
+// How long a limit error that came without a reset time keeps the account limited. Providers
+// report no limit windows, so nothing else would ever lift it.
+const UNTIMED_LIMIT_ERROR_SECS = 3600
+
+export const isLimitCategory = (category: string): boolean => category === 'rate_limited' || category === 'quota'
+
+/**
+ * Whether a `rate_limited` or `quota` error still counts. With a reset time it counts until
+ * then; without one it counts for a short while after it was recorded.
+ */
+export function limitErrorActive(issue: Issue): boolean {
+  if (issue.resetsAt) return inFuture(issue.resetsAt)
+  const at = Date.parse(issue.at)
+  return !Number.isNaN(at) && Math.trunc((Date.now() - at) / 1000) < UNTIMED_LIMIT_ERROR_SECS
+}
+
+export function deriveHealth(state: AccountState): string {
+  const limitedByWindow = state.limits.some((limit) => (limit.status === 'rejected' || (limit.usedPercent ?? 0) >= 100) && (!limit.resetsAt || inFuture(limit.resetsAt)))
+  const issue = state.lastError
+  if (issue?.category === 'auth_expired') return 'auth_expired'
+  if (issue && isLimitCategory(issue.category) && limitErrorActive(issue)) return 'limited'
+  if (state.signedIn === false) return 'signed_out'
+  if (limitedByWindow) return 'limited'
+  if (issue && !isLimitCategory(issue.category)) return 'error'
+  return state.signedIn === true ? 'ok' : 'unknown'
+}
+
+/** Read-modify-write on one account's state. Returns the previous health and the new state. */
+export function updateState(dir: string, accountId: string, change: (state: AccountState) => void): { previous: string; state: AccountState } {
+  const state = loadState(dir, accountId)
+  const previous = state.health
+  change(state)
+  state.health = deriveHealth(state)
+  saveState(dir, accountId, state)
+  return { previous, state }
+}
+
+// ---- Lookup and pinning -----------------------------------------------------------------
+
+export function find(dir: string, accountId: string): Account {
+  const account = loadRegistry(dir).accounts.find((entry) => entry.id === accountId)
+  if (!account) throw new HarnessError('account_required', "This session's account was removed.", 'Choose another account for it.')
+  return account
+}
+
+const usable = (state: AccountState): boolean => state.health === 'ok' || state.health === 'unknown'
+
+/**
+ * Chooses the account for a new session: the explicit account, else the pool's first usable
+ * account, else the default, else the first account. It never skips to another one silently.
+ */
+export function resolve(dir: string, accountId?: string | null, poolId?: string | null): Account {
+  const registry = loadRegistry(dir)
+  if (accountId) {
+    const account = find(dir, accountId)
+    if (account.provider !== PROVIDER) throw invalid('That account belongs to another provider.')
+    return account
+  }
+  if (poolId) {
+    const pool = registry.pools.find((entry) => entry.id === poolId)
+    if (!pool) throw notFound('Pool')
+    const members = pool.accountIds.flatMap((id) => registry.accounts.find((account) => account.id === id) ?? [])
+    const ready = members.find((account) => usable(loadState(dir, account.id)))
+    if (ready) return ready
+    const resets = members.flatMap((account) => {
+      const state = loadState(dir, account.id)
+      return [...state.limits.map((limit) => limit.resetsAt), state.lastError?.resetsAt].filter((reset): reset is string => Boolean(reset))
+    })
+    const earliest = resets.sort(compareText)[0]
+    throw new HarnessError('account_unavailable', `Every account in ${pool.label} is unavailable.`, earliest ? `The earliest reset is ${earliest}.` : 'Reauthenticate an account in Accounts.')
+  }
+  const account = registry.accounts.find((entry) => entry.id === registry.defaults[PROVIDER]) ?? registry.accounts.find((entry) => entry.provider === PROVIDER)
+  if (!account) throw new HarnessError('account_required', 'Add a Pi account first.', 'Open Accounts (⌘4) to sign in.')
+  return account
+}
+
+/** The default account, if any exists. */
+export function defaultAccount(dir: string): Account | null {
+  try {
+    return resolve(dir)
+  } catch {
+    return null
+  }
+}
+
+export function summaryAuthentication(dir: string): 'authenticated' | 'unauthenticated' | 'unknown' {
+  const states = loadRegistry(dir).accounts.filter((account) => account.provider === PROVIDER).map((account) => loadState(dir, account.id))
+  if (states.some((state) => state.signedIn === true)) return 'authenticated'
+  return states.some((state) => state.signedIn === false) ? 'unauthenticated' : 'unknown'
+}
+
+export function overview(dir: string): AccountsOverview {
+  const registry = loadRegistry(dir)
+  return {
+    accounts: registry.accounts.filter((account) => account.provider === PROVIDER).map((account) => ({ ...account, isDefault: registry.defaults[account.provider] === account.id, state: loadState(dir, account.id) })),
+    pools: registry.pools.filter((pool) => pool.provider === PROVIDER),
+    defaults: registry.defaults
+  }
+}
+
+// ---- Changes ----------------------------------------------------------------------------
+
+export function cleanLabel(label: string): string {
+  const cleaned = label.trim()
+  if (!cleaned || charCount(cleaned) > 60) throw invalid('Give the account a name of 1–60 characters.')
+  return cleaned
+}
+
+export function addAccount(dir: string, label: string, authKind: string): Account {
+  if (authKind !== 'subscription' && authKind !== 'apiKey') throw invalid('Unknown sign-in type.')
+  const account: Account = { id: newId(), provider: PROVIDER, label: cleanLabel(label), authKind, credentialStore: 'keyring', createdAt: now() }
+  const registry = loadRegistry(dir)
+  registry.defaults[PROVIDER] ??= account.id
+  registry.accounts.push(account)
+  saveRegistry(dir, registry)
+  return account
+}
+
+export function renameAccount(dir: string, accountId: string, label: string): void {
+  const cleaned = cleanLabel(label)
+  const registry = loadRegistry(dir)
+  const account = registry.accounts.find((entry) => entry.id === accountId)
+  if (!account) throw notFound('Account')
+  account.label = cleaned
+  saveRegistry(dir, registry)
+}
+
+export function setDefault(dir: string, accountId: string): Account {
+  const account = find(dir, accountId)
+  const registry = loadRegistry(dir)
+  registry.defaults[account.provider] = account.id
+  saveRegistry(dir, registry)
+  return account
+}
+
+/** Drops the account from the registry, its pools, and the default. Its folder and secrets are the caller's to remove. */
+export function forgetAccount(dir: string, account: Account): void {
+  const registry = loadRegistry(dir)
+  registry.accounts = registry.accounts.filter((entry) => entry.id !== account.id)
+  if (registry.defaults[account.provider] === account.id) {
+    const next = registry.accounts.find((entry) => entry.provider === account.provider)
+    if (next) registry.defaults[account.provider] = next.id
+    else delete registry.defaults[account.provider]
+  }
+  for (const pool of registry.pools) pool.accountIds = pool.accountIds.filter((id) => id !== account.id)
+  saveRegistry(dir, registry)
+}
+
+export function savePool(dir: string, pool: { id?: string; label: string; accountIds: string[] }): Pool {
+  const label = cleanLabel(pool.label)
+  const registry = loadRegistry(dir)
+  for (const id of pool.accountIds) {
+    const account = registry.accounts.find((entry) => entry.id === id)
+    if (!account) throw notFound('Account')
+    if (account.provider !== PROVIDER) throw invalid('A pool holds accounts of one provider.')
+  }
+  const next: Pool = { id: pool.id ? safeId(pool.id) : newId(), provider: PROVIDER, label, accountIds: [...pool.accountIds] }
+  registry.pools = [...registry.pools.filter((existing) => existing.id !== next.id), next]
+  saveRegistry(dir, registry)
+  return next
+}
+
+export function removePool(dir: string, poolId: string): void {
+  const registry = loadRegistry(dir)
+  registry.pools = registry.pools.filter((pool) => pool.id !== poolId)
+  saveRegistry(dir, registry)
+}

package/src/capabilities/api.ts

@@ -0,0 +1,75 @@
+// A generic view of what is available to a caller. The existing plugin, registry, and connector
+// stores remain the source of truth; this module gives hosts one capability-shaped contract.
+import { invalid } from '../core/errors'
+import type { Harness } from '../harness'
+import type { CallerContext } from '../memory/caller'
+import type { Launch } from '../prompt/compile'
+import * as pluginApi from '../plugins/api'
+import type { Plugin } from '../plugins/types'
+import type { Capability, CapabilityCatalogue, CapabilityScope, CapabilitySet } from './types'
+
+export interface ListParams extends CapabilityScope {}
+
+export interface InventoryParams extends CapabilityScope {
+  context?: CallerContext
+  launch?: Launch
+  tools?: string[]
+  connections?: boolean
+}
+
+const unique = (values: readonly string[]): string[] => [...new Set(values.filter((value) => value.length > 0))]
+
+function contributions(plugins: readonly Plugin[]): Capability[] {
+  return plugins.flatMap((plugin) => plugin.contributions.map((item) => ({
+    id: item.id,
+    pluginId: plugin.id,
+    kind: item.kind,
+    name: item.name,
+    description: item.description,
+    source: plugin.source,
+    state: item.state,
+    attachment: item.attachment
+  })))
+}
+
+export async function list(harness: Harness, params: ListParams = {}): Promise<CapabilityCatalogue> {
+  const plugins = await pluginApi.list(harness, params)
+  return { plugins, capabilities: contributions(plugins) }
+}
+
+/** The resolved callable set for one caller, based on the stores and caller-supplied tool list. */
+export async function resolve(harness: Harness, params: ListParams & { tools?: readonly string[] }): Promise<CapabilitySet> {
+  const caller = { agentId: params.agentId ?? null, projectId: params.projectId ?? null }
+  const catalogue = await list(harness, params)
+  const connectors = harness.apps.connections.forScope(caller).map((connection) => connection.id)
+  return {
+    version: 1,
+    tools: unique(params.tools ?? []),
+    connectors: unique(connectors),
+    contributions: catalogue.capabilities.filter((item) => item.state === 'on').map((item) => item.id)
+  }
+}
+
+export function toolIntersection(parent: CapabilitySet, assignee: CapabilitySet, taskTools: readonly string[] = []): CapabilitySet {
+  const permitted = new Set(taskTools.length ? taskTools : assignee.tools)
+  return {
+    version: 1,
+    tools: parent.tools.filter((tool) => assignee.tools.includes(tool) && permitted.has(tool)),
+    connectors: parent.connectors.filter((id) => assignee.connectors.includes(id)),
+    contributions: parent.contributions.filter((id) => assignee.contributions.includes(id))
+  }
+}
+
+export function inventory(harness: Harness, params: InventoryParams = {}) {
+  return pluginApi.inventoryFor(harness, params)
+}
+
+export async function attach(harness: Harness, params: pluginApi.AttachParams, on: boolean): Promise<CapabilityCatalogue> {
+  const plugins = await pluginApi.attach(harness, params, on)
+  return { plugins, capabilities: contributions(plugins) }
+}
+
+export async function switchCapability(harness: Harness, params: pluginApi.AttachParams, on: boolean): Promise<CapabilityCatalogue> {
+  if (!params.id.trim()) throw invalid('A capability id is required.')
+  return attach(harness, params, on)
+}