Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

20.1 KB
Raw Blame
import type { NativeExecutableSnapshot } from './nativeVersion.js'
/** Native launch writes from an engine's declared SQLite transaction or CLI API protocol.
 * Optional history readers never own these operations. Compatibility extraction first;
 * cancellation and uncertain-write corrections are tracked in the OpenCode control research note. */
import { execFile } from 'node:child_process'
import { promisify } from 'node:util'
import { LAUNCH_LOCATION_VARIABLES, nativeProcessEnvironment } from './nativeLocations.js'
import { builtinSqlite, runSqliteScript } from '../../lib/sqliteBuiltin.js'

export interface NativeSessionModel { providerID: string; modelID: string }
export type NativeModelResult = { ok: true } | { ok: false; code: string; detail: string; effect?: 'uncertain' }
export type NativeApiRun = (args: string[], options: { cwd?: string }) => Promise<{ stdout: string }>
export interface NativeModelAuthority { current?: () => boolean; executable?: NativeExecutableSnapshot; environment?: NodeJS.ProcessEnv }
export interface NativeModelRule {
  label: string; serviceMajor: number; id: RegExp; modelFlags: readonly string[]; modelEquals: string; variantSeparator: string
  errors: { sqliteMissing: string; sessionMissing: string; writeFailed: string; binaryMissing: string; switchFailed: string; unknownModel: string }
  sqlite: { args: readonly string[]; timeoutMs: number; statements: readonly string[] }
  api: { timeoutMs: number; retryDelayMs: number; list: readonly string[]; switch: readonly string[]; get: readonly string[];
    paramFlag: string; sessionParam: string; bodyFlag: string; missingSession: RegExp;
    fields: { data: string; model: string; id: string; alternativeId: string; provider: string; variant: string } }
}
const execFileAsync = promisify(execFile)
class NativeDispatchCancelled extends Error {}

export function createSessionModelControl(rule: NativeModelRule, binary: () => string | Promise<string>) {
  const ID_RE = rule.id
  const changed = (dispatched = false): NativeModelResult => ({ ok: false, code: 'AGENT_CHANGED',
    detail: `The harness changed or stopped during native model preparation.${dispatched ? ' The native model change may already have applied.' : ''}`,
    ...(dispatched ? { effect: 'uncertain' as const } : {}) })
  // An uncertain write cannot be forgotten just because its request returned. Keep
  // one receipt per conversation until a later read confirms it. At capacity, hold
  // new work instead of evicting a receipt and making a blind retry possible.
  type Pending = { model: NativeSessionModel; cwd?: string; store?: string; environment?: string; busy: boolean; dispatched: boolean; executable?: Promise<string> }
  const pending = new Map<string, Pending>()
  const capacity = 256
  /** A SQL string literal — the only way a value reaches the statement. */
  function lit(value: string): string {
    return `'${value.replace(/'/g, "''")}'`
  }

  /**
   * The `provider/model` an opencode argv names, split the way opencode splits it: the provider is
   * everything before the FIRST slash, the model is the rest (`vibe/minimax/minimax-m3` → `vibe` +
   * `minimax/minimax-m3`). Reads the LAST `-m`/`--model`, which is the one opencode honours.
   * Null when the argv names no model — then there is nothing to write and the engine decides.
   */
  function modelFromArgv(args: readonly string[]): NativeSessionModel | null {
    let id: string | null = null
    for (let i = 0; i < args.length; i++) {
      const arg = args[i]
      if (rule.modelFlags.includes(arg) && i + 1 < args.length) { id = args[i + 1]; i++ }
      else if (arg.startsWith(rule.modelEquals)) id = arg.slice(rule.modelEquals.length)
    }
    return id ? parseModelId(id) : null
  }

  /** A `provider/model` id split the way opencode splits it, or null when it names no provider. */
  function parseModelId(id: string): NativeSessionModel | null {
    const slash = id.indexOf('/')
    if (slash <= 0 || slash === id.length - 1) return null
    return { providerID: id.slice(0, slash), modelID: id.slice(slash + 1) }
  }

  /**
   * Rewrite `sessionId`'s model in `dbPath` so that resuming it opens on `model`.
   *
   * One transaction: both rows or neither. Writes through the `sqlite3` CLI when it is on PATH, else `node:sqlite`.
   * Refuses without writing when neither is there, when the id is not an opencode session id, or when the session
   * has no user message yet (the declared transaction guards it).
   */
  async function setSessionModel(
    dbPath: string,
    sessionId: string,
    model: NativeSessionModel,
    authority: NativeModelAuthority = {},
  ): Promise<NativeModelResult> {
    if (authority.current?.() === false) return changed()
    if (pending.has(sessionId)) return { ok: false, code: rule.errors.switchFailed, effect: 'uncertain',
      detail: 'Waiting to confirm the earlier native API model change. A changed or unavailable version cannot authorize a SQLite fallback.' }
    if (!ID_RE.test(sessionId)) {
      return { ok: false, code: rule.errors.sessionMissing, detail: `not an ${rule.label} session id: ${sessionId}` }
    }
    if (!model.providerID || !model.modelID) {
      return { ok: false, code: rule.errors.writeFailed, detail: 'refusing to write an empty provider or model id' }
    }
    const values: Record<string, string> = { session: lit(sessionId), provider: lit(model.providerID), model: lit(model.modelID) }
    const statements = rule.sqlite.statements.map((statement) =>
      statement.replace(/\{\{(session|provider|model)\}\}/g, (_token, key: string) => values[key]!))

    let stdout: string
    try {
      // The CLI first: the write waits up to `busy_timeout` (5s) for opencode's lock, and in a child process that
      // wait is not the daemon's. `-bail` stops at the first failing statement; the shell then exits with the
      // transaction still open, and SQLite rolls it back on close — so a failing second UPDATE leaves the first
      // unapplied. Bounded: a CLI that never answers used to hold this `agent_create` open for good, so 15s.
      ({ stdout } = await execFileAsync('sqlite3', [...rule.sqlite.args, dbPath, statements.join('\n')], { timeout: rule.sqlite.timeoutMs, killSignal: 'SIGKILL' }))
    } catch (err) {
      const error = err as NodeJS.ErrnoException & { stderr?: string }
      if (error?.code !== 'ENOENT') {
        const stderr = String(error?.stderr ?? '').trim()
        return { ok: false, code: rule.errors.writeFailed, detail: stderr || String(error?.message ?? err) }
      }
      // Windows ships no sqlite3 CLI: the same statements through node:sqlite when this Node has it. It runs on
      // this thread, so a lock opencode holds stalls it up to `busy_timeout`; that is only where no CLI exists.
      const Database = builtinSqlite()
      if (!Database) return { ok: false, code: rule.errors.sqliteMissing, detail: 'sqlite3 CLI not found on PATH' }
      try {
        stdout = runSqliteScript(Database, dbPath, statements).join('\n')
      } catch (builtinError) {
        return { ok: false, code: rule.errors.writeFailed, detail: String((builtinError as Error)?.message ?? builtinError) }
      }
    }
    const lines = stdout.trim().split('\n').map((line) => line.trim()).filter(Boolean)
    // Lines: the pragma's echo, then the two change counts.
    const messages = Number(lines[lines.length - 2])
    const sessions = Number(lines[lines.length - 1])
    if (!Number.isFinite(messages) || !Number.isFinite(sessions)) {
      return { ok: false, code: rule.errors.writeFailed, detail: `unexpected SQLite output: ${stdout.trim().slice(0, 200)}` }
    }
    if (messages === 0) {
      return {
        ok: false,
        code: rule.errors.sessionMissing,
        detail: `session ${sessionId} has no user message yet — nothing to rewrite; -m applies on launch`,
      }
    }
    console.log(
      `[${rule.label}] session model set to ${model.providerID}/${model.modelID} · ` +
      `${messages} message row, ${sessions} session row`,
    )
    return { ok: true }
  }

  const nativeRun = (authority: NativeModelAuthority, selection: { executable?: Promise<string>; snapshot?: NativeExecutableSnapshot }): NativeApiRun => {
    // Resolve once for this operation, before its first native command. Resolving
    // through a login shell can yield; cancellation must be checked afterwards.
    return async (args, options) => {
      selection.snapshot ??= authority.executable
      selection.executable ??= authority.executable ? Promise.resolve(authority.executable.command) : Promise.resolve().then(binary)
      const executable = await selection.executable
      if (authority.current?.() === false || selection.snapshot?.current() === false || authority.executable?.current() === false) throw new NativeDispatchCancelled('Native model operation was cancelled before dispatch')
      return new Promise((done, failed) => {
        const child = execFile(executable, args, { ...(authority.environment ? { env: nativeProcessEnvironment(authority.environment) } : {}), ...(options.cwd ? { cwd: options.cwd } : {}),
          timeout: rule.api.timeoutMs, killSignal: 'SIGKILL', maxBuffer: 1024 * 1024, encoding: 'utf8',
        }, (error, stdout, stderr) => { if (error) failed(Object.assign(error, { stdout, stderr })); else done({ stdout }) })
        child.stdin?.end()
      })
    }
  }

  /** What a failed `opencode api` call said: the body is on stdout, the HTTP status on stderr. */
  function apiFailure(err: unknown): { missing: boolean; text: string } {
    const error = err as NodeJS.ErrnoException & { stdout?: string; stderr?: string }
    if (error?.code === 'ENOENT') return { missing: true, text: String(error.message ?? err) }
    const text = [error?.stdout, error?.stderr].map((part) => String(part ?? '').trim()).filter(Boolean).join(' · ')
    return { missing: false, text: text || String(error?.message ?? err) }
  }

  /**
   * Put `sessionId` on `model` through the engine's declared native API.
   *
   * Talks to the background service (`opencode api` with no `--standalone`), which owns the store.
   * Proved on 2.0.18 that a session last opened by a `--standalone` pane is switched just the same,
   * and that the next pane reads it from the store whichever server it runs on. Never touches the DB.
   *
   * Measured on 2.0.18 that the service stores any id (`opencode/does-not-exist` reads back as set),
   * so with `checkCatalog` the model is looked for in `model.list` first — for a model of opencode's
   * own; a grid's provider is declared in its pane's own config, which the service never reads. A
   * lost reply does not prove the switch was not applied. Reconciliation retries
   * only the read: another write could overwrite a later choice made in the TUI.
   */
  async function switchSessionModel(
    sessionId: string,
    model: NativeSessionModel,
    options: { cwd?: string; store?: string; run?: NativeApiRun; checkCatalog?: boolean; retryDelayMs?: number } & NativeModelAuthority = {},
  ): Promise<NativeModelResult> {
    options = { ...options, ...(options.environment ? { environment: { ...options.environment } } : {}) }
    const current = () => options.current?.() !== false
    if (!current()) return changed()
    if (!ID_RE.test(sessionId)) {
      return { ok: false, code: rule.errors.sessionMissing, detail: `not an ${rule.label} session id: ${sessionId}` }
    }
    const requested = { ...model }
    const previous = pending.get(sessionId)
    // A receipt is evidence about one captured native store, not permission for
    // a later shell/profile to reinterpret an uncertain write at the same id.
    const environment = options.environment && JSON.stringify(LAUNCH_LOCATION_VARIABLES.map(key => options.environment![key] ?? null))
    const held = (detail: string): NativeModelResult => ({ ok: false, code: rule.errors.switchFailed, detail,
      ...(previous?.dispatched ? { effect: 'uncertain' as const } : {}) })
    if (previous?.busy) return held('Waiting for the native model operation already running for this conversation. No additional change was sent.')
    if (previous && (previous.cwd !== options.cwd || previous.store !== options.store || previous.environment !== environment)) {
      return held('Waiting to confirm the earlier native model change in its original store and folder. No additional change was sent.')
    }
    if (!previous && pending.size >= capacity) return held('Waiting for outstanding native model changes to be confirmed. No model change was sent.')
    const receipt: Pending = previous ?? { model: requested, cwd: options.cwd, store: options.store, environment, busy: false, dispatched: false }
    receipt.busy = true
    pending.set(sessionId, receipt)
    const run = options.run ?? nativeRun(options, receipt)
    let confirmed = false
    try {
      if (!previous) {
        if (options.checkCatalog) {
          const known = await listsModel(run, requested, receipt.cwd)
          if (!current()) return changed()
          if (known === null) return held(`Waiting for ${rule.label}'s model catalog before changing the session. No model change was sent.`)
          if (!known) return { ok: false, code: rule.errors.unknownModel, detail: `${rule.label} has no ${requested.providerID}/${requested.modelID} — \`${rule.label} models\` lists the ones it has` }
        }
        const param = `${rule.api.sessionParam}=${sessionId}`
        const { id, variant } = splitVariant(requested.modelID)
        const fields = rule.api.fields
        const body = JSON.stringify({ [fields.model]: { [fields.id]: id, [fields.provider]: requested.providerID, ...(variant ? { [fields.variant]: variant } : {}) } })
        receipt.dispatched = true
        try {
          await run([...rule.api.switch, rule.api.paramFlag, param, rule.api.bodyFlag, body], { cwd: receipt.cwd })
        } catch (err) {
          if (err instanceof NativeDispatchCancelled) { receipt.dispatched = false; return changed() }
          const failure = apiFailure(err)
          if (failure.missing || rule.api.missingSession.test(failure.text)) {
            receipt.dispatched = false
            return { ok: false, code: failure.missing ? rule.errors.binaryMissing : rule.errors.sessionMissing, detail: failure.text }
          }
          // Transport failure does not prove that the write failed. Only read next.
        }
      }
      if (!current()) return changed(receipt.dispatched)
      let result = await confirmModel(run, sessionId, receipt.model, receipt.cwd)
      if (!current()) return changed(receipt.dispatched)
      if (!result.ok) {
        await new Promise((resolve) => setTimeout(resolve, options.retryDelayMs ?? rule.api.retryDelayMs))
        if (!current()) return changed(receipt.dispatched)
        result = await confirmModel(run, sessionId, receipt.model, receipt.cwd)
      }
      if (!current()) return changed(receipt.dispatched)
      confirmed = result.ok
      if (confirmed && (requested.modelID !== receipt.model.modelID || requested.providerID !== receipt.model.providerID)) {
        return held('The earlier native model change is now confirmed. Retry the new choice to start a separate change; no additional change was sent.')
      }
      return result.ok ? result : { ...result, effect: 'uncertain' }
    } finally {
      receipt.busy = false
      if (!receipt.dispatched || confirmed) pending.delete(sessionId)
    }
  }

  /**
   * A v2 model id and the effort it names: `model#high` is opencode's own way (`opencode run -m
   * provider/model#variant`). v1 never splits it — its `-m` and its rewrite take the id as written.
   */
  function splitVariant(modelID: string): { id: string; variant?: string } {
    const at = modelID.lastIndexOf(rule.variantSeparator)
    return at > 0 && at < modelID.length - rule.variantSeparator.length ? { id: modelID.slice(0, at), variant: modelID.slice(at + rule.variantSeparator.length) } : { id: modelID }
  }

  /** Whether the service's `model.list` has [model]; null when the list could not be read. */
  async function listsModel(run: NativeApiRun, model: NativeSessionModel, cwd?: string): Promise<boolean | null> {
    try {
      const { stdout } = await run([...rule.api.list], { cwd })
      const parsed = JSON.parse(stdout) as Record<string, unknown> | unknown[]
      const fields = rule.api.fields
      const rows = (Array.isArray(parsed) ? parsed : parsed[fields.data]) as Array<Record<string, unknown>> | undefined
      if (!Array.isArray(rows)) return null
      if (rows.some(row => !row || typeof row !== 'object' || typeof row[fields.provider] !== 'string'
        || typeof (row[fields.id] ?? row[fields.alternativeId]) !== 'string')) return null
      const { id } = splitVariant(model.modelID)
      return rows.some((m) => m[fields.provider] === model.providerID && (m[fields.id] === id || m[fields.alternativeId] === id))
    } catch {
      return null
    }
  }

  /** Confirmation never repeats a mutation, including after an uncertain reply. */
  async function confirmModel(run: NativeApiRun, sessionId: string, model: NativeSessionModel, cwd?: string): Promise<NativeModelResult> {
    const options = { cwd }
    const param = `${rule.api.sessionParam}=${sessionId}`
    const { id, variant } = splitVariant(model.modelID)
    const fields = rule.api.fields
    // Read back: the service answers 204 for any model, known or not, so only the session itself can
    // say the switch landed.
    let stdout: string
    try {
      ({ stdout } = await run([...rule.api.get, rule.api.paramFlag, param], { cwd: options.cwd }))
    } catch (err) {
      return { ok: false, code: rule.errors.switchFailed, detail: `Waiting to confirm the native model change; it may already have applied. ${apiFailure(err).text}` }
    }
    let now: Record<string, unknown> | undefined
    try {
      const data = (JSON.parse(stdout) as Record<string, Record<string, unknown>>)[fields.data]
      if (!data || typeof data !== 'object' || Array.isArray(data) || data[fields.id] !== sessionId) {
        return { ok: false, code: rule.errors.switchFailed, detail: `Waiting for confirmation of session ${sessionId}; the native response did not identify that conversation.` }
      }
      const model = data[fields.model]
      now = model && typeof model === 'object' && !Array.isArray(model) ? model as Record<string, unknown> : undefined
    } catch {
      now = undefined
    }
    // (A variant asked for must read back too; none asked for, the service's own is fine.)
    if (now?.[fields.id] !== id || now?.[fields.provider] !== model.providerID || (variant && now?.[fields.variant] !== variant)) {
      const seen = now ? `${String(now[fields.provider])}/${String(now[fields.id])}${now[fields.variant] ? `#${String(now[fields.variant])}` : ''}` : stdout.trim().slice(0, 200)
      return { ok: false, code: rule.errors.switchFailed, detail: `session ${sessionId} is still on ${seen}` }
    }
    console.log(`[${rule.label}] session model switched to ${model.providerID}/${model.modelID} through the service`)
    return { ok: true }
  }

  /**
   * Put a resumed session on `model` the way the installed OpenCode needs, BEFORE its pane is
   * relaunched. A failure here is the caller's refusal: the live process has not been touched yet.
   *
   *  * v1 (or a version not read): the SQL rewrite above. A session with no user message yet is fine
   *    there — the relaunch's `-m` applies to it — so that one answer is success.
   *  * v2: the API. Every failure is a failure, `SESSION_NOT_FOUND` included: the relaunch carries no
   *    `-m`, so a switch that did not land is a pane on the old model with the move reported done.
   */
  async function applySessionModel(
    input: { major: number | null | undefined; dbPath: string; sessionId: string; model: NativeSessionModel; cwd?: string; checkCatalog?: boolean },
    deps: { run?: NativeApiRun; retryDelayMs?: number } & NativeModelAuthority = {},
  ): Promise<NativeModelResult> {
    if (deps.current?.() === false) return changed()
    if ((input.major ?? 0) >= rule.serviceMajor) {
      return switchSessionModel(input.sessionId, input.model, { ...deps, cwd: input.cwd, store: input.dbPath, checkCatalog: input.checkCatalog })
    }
    const written = await setSessionModel(input.dbPath, input.sessionId, input.model, deps)
    return !written.ok && written.code === rule.errors.sessionMissing ? { ok: true } : written
  }

  return { modelFromArgv, parseModelId, setSessionModel, switchSessionModel, applySessionModel }
}