@renzrollon/interlock 1.0.0

package/lib/host/qwen.mjs

@@ -0,0 +1,176 @@
+// The `qwen` host adapter (design D5).
+//
+// Qwen Code's non-interactive mode. One `qwen` process per spawn, prompt on
+// stdin, a JSON envelope on stdout.
+//
+// The contract, verified against the installed CLI (qwen-code 0.22.2) on
+// 2026-09-05:
+//
+//   -p, --prompt <text>       "Prompt. Appended to input on stdin (if any)."
+//                             The briefing travels on stdin (design D2), so `-`
+//                             is the placeholder the flag requires.
+//   -o, --output-format json  text | json | stream-json
+//   --json-schema <json>      accepted (absent from `--help`, accepted by the
+//                             parser — verified by a live argv probe)
+//   --yolo                    accepted, same as above; unattended tool approval
+//   -m, --model <MODEL>       the model flag, spelled `-m`, verified in `--help`
+//
+// `--yolo` is the reason this host declares `hooks: false` twice over: Qwen has
+// no equivalent of this repository's PreToolUse guards, AND its own approval
+// prompt is disabled because there is nobody to answer it. The runner banners
+// `HOOKS NOT IN FORCE (qwen)`, and the CLI's unit-suite shrink check stays the
+// deterministic backstop.
+//
+// Providers are configured in Qwen's own `settings.json`, so an unmapped slug is
+// not an error — it is a spawn that ran on the operator's default, which the
+// runner names in `MODEL ROUTING UNAVAILABLE (qwen)` rather than passing off as
+// the tier the planner asked for.
+
+import { assertWorkflowHost, execCapture, mapPipeline, parseAgentJson, runCli } from '../host.mjs'
+import { parseModelMap, resolveModel } from './model-map.mjs'
+
+/** Override the binary, for a wrapper or a fixture. */
+export const QWEN_COMMAND_ENV = 'INTERLOCK_QWEN_COMMAND'
+
+/** Optional per-spawn wall clock, in ms. 0 disables it. */
+export const QWEN_TIMEOUT_ENV = 'INTERLOCK_QWEN_TIMEOUT_MS'
+
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000
+
+/**
+ * The exact argv one spawn sends.
+ *
+ * @param {object} req
+ * @param {{model: string|null}} [opts]
+ * @returns {string[]}
+ */
+export function qwenArgs(req, { model } = {}) {
+  const request = req && typeof req === 'object' ? req : {}
+  const args = ['-p', '-', '--output-format', 'json']
+  if (request.schema) args.push('--json-schema', JSON.stringify(request.schema))
+  args.push('--yolo')
+  if (typeof model === 'string' && model) args.push('-m', model)
+  return args
+}
+
+/**
+ * The validated payload out of Qwen's JSON envelope.
+ *
+ * The envelope wraps the model's answer in a `response` field, which with
+ * `--json-schema` is the validated object. Older shapes put it at the top level.
+ * Both are read, and `parseAgentJson` recovers a payload that arrived as a
+ * string — the CLI validated it, so recovering it from its own quoting is not
+ * the same gamble the ACP adapter takes on free prose.
+ *
+ * @param {string} stdout
+ * @returns {{result: object|null, usage: object|null}}
+ */
+export function readQwenEnvelope(stdout) {
+  let envelope
+  try {
+    envelope = JSON.parse(typeof stdout === 'string' ? stdout : '')
+  } catch {
+    return { result: null, usage: null }
+  }
+  if (!envelope || typeof envelope !== 'object') return { result: null, usage: null }
+
+  const candidate = envelope.response !== undefined ? envelope.response : envelope
+  let result = null
+  if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) result = candidate
+  else if (typeof candidate === 'string') result = parseAgentJson(candidate)
+
+  const stats = envelope.stats && typeof envelope.stats === 'object' ? envelope.stats : null
+  const tokens = stats && stats.tokens && typeof stats.tokens === 'object' ? stats.tokens : null
+  const usage =
+    tokens && (Number.isFinite(tokens.output) || Number.isFinite(tokens.input))
+      ? {
+          inputTokens: Number.isFinite(tokens.input) ? tokens.input : undefined,
+          outputTokens: Number.isFinite(tokens.output) ? tokens.output : undefined
+        }
+      : null
+
+  return { result, usage }
+}
+
+/**
+ * Build a {@link import('../host.mjs').WorkflowHost} backed by `qwen -p`.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.command]  defaults to `$INTERLOCK_QWEN_COMMAND` or `qwen`
+ * @param {string} [opts.cwd]
+ * @param {object} [opts.env]
+ * @param {number} [opts.timeoutMs]
+ * @param {(event: object) => void} [opts.onEvent]
+ */
+export function createQwenHost({ command, cwd = process.cwd(), env = process.env, timeoutMs, onEvent } = {}) {
+  const source = env && typeof env === 'object' ? env : {}
+  const raw = (typeof command === 'string' && command.trim()) || source[QWEN_COMMAND_ENV] || 'qwen'
+  const argv = String(raw).trim().split(/\s+/)
+  const bin = argv[0]
+  const fixedArgs = argv.slice(1)
+  const budget = Number.isInteger(timeoutMs)
+    ? timeoutMs
+    : Number.parseInt(source[QWEN_TIMEOUT_ENV] || '', 10) || DEFAULT_TIMEOUT_MS
+  const modelMap = parseModelMap(source)
+
+  const host = {
+    command: [bin, ...fixedArgs].join(' '),
+
+    async spawn(req) {
+      const request = req && typeof req === 'object' ? req : {}
+      const label = typeof request.label === 'string' ? request.label : 'agent'
+      const started = Date.now()
+      const routed = resolveModel('qwen', request.model, modelMap, { modelSelect: 'map-only' })
+      if (typeof request.model === 'string' && request.model && onEvent) {
+        onEvent({
+          type: 'model-routing',
+          label,
+          requested: request.model,
+          applied: routed.applied,
+          value: routed.value,
+          via: routed.applied ? 'flag' : null,
+          reason: routed.reason
+        })
+      }
+
+      const { code, stdout, stderr, timedOut } = await execCapture(
+        bin,
+        [...fixedArgs, ...qwenArgs(request, { model: routed.value })],
+        {
+          cwd: typeof request.cwd === 'string' && request.cwd ? request.cwd : cwd,
+          env: source,
+          input: request.prompt,
+          timeoutMs: budget
+        }
+      )
+
+      if (code !== 0) {
+        if (onEvent) {
+          onEvent({
+            type: 'spawn-failed',
+            label,
+            code,
+            timedOut,
+            error: stderr.trim().slice(-500) || `qwen exited ${code}`
+          })
+        }
+        return null
+      }
+
+      const { result, usage } = readQwenEnvelope(stdout)
+      if (onEvent) {
+        onEvent({ type: 'spawn-done', label, ms: Date.now() - started, parsed: Boolean(result), usage })
+      }
+      if (!result) return null
+      return usage ? { ...result, usage } : result
+    },
+
+    mapPipeline,
+
+    runCli(argv2, opts = {}) {
+      return runCli(argv2, { cwd, env: source, ...opts })
+    }
+  }
+
+  return assertWorkflowHost(host, 'qwen host')
+}

package/lib/host/registry.mjs

@@ -0,0 +1,213 @@
+// The host registry (design D1).
+//
+// `bin/interlock-run` is an interpreter of the program `interlock run` emits. It
+// spawns what a step names and calls the argv a step names. The only thing that
+// differs between running that program over Claude Code, over an ACP agent, over
+// Codex or over Qwen is the transport — so a host is one file under this
+// directory implementing the three-function port in `../host.mjs`, plus a
+// declaration of what it cannot do.
+//
+// The declaration is the load-bearing half. Every adapter states the same seven
+// facts, and the run program reads them rather than branching on an id:
+//
+//   schemaEnforced  does the CLI itself validate the result against the schema
+//   modelSelect     'flag' | 'negotiated' | 'map-only' — how a slug becomes a model
+//   worktree        'driver' | 'runtime' — who creates a lane's worktree
+//   hooks           do this repository's PreToolUse guards fire on this host
+//   usage           does the CLI report token usage
+//   cacheAccounting does it decompose that usage into cache reads and writes
+//   billing         which account the run spends against
+//
+// `cacheAccounting` is separate from `usage` and not implied by it: the Workflow
+// runtime demonstrates the gap by exposing a single cumulative spend scalar with
+// no decomposition at all, and a run cannot banner a capability nobody declared.
+//
+// A capability that were merely implied by the adapter's code would be a
+// capability nothing could banner, and every one of these describes a way a run
+// is WEAKER than the default host. `test/spine/host-registry.test.mjs` asserts
+// each adapter declares every key, so a fifth adapter cannot arrive with a
+// silently absent one.
+//
+// The Workflow host is deliberately absent: it is reached through
+// `/interlock:ship`, it owns its own worktrees (`worktree: 'runtime'`), and the
+// runner refuses its id (design D10).
+
+import { createAcpHost, isClaudeCodeBinary, parseAcpCommand, ACP_COMMAND_ENV } from './acp.mjs'
+import { createClaudeHost } from './claude-cli.mjs'
+import { createCodexHost } from './codex.mjs'
+import { createQwenHost } from './qwen.mjs'
+
+/** Every fact an adapter must declare. Order is the order a banner reads them. */
+export const CAPABILITY_KEYS = Object.freeze([
+  'schemaEnforced',
+  'modelSelect',
+  'worktree',
+  'hooks',
+  'usage',
+  'cacheAccounting',
+  'billing'
+])
+
+/** The allowed value of each declared capability. */
+export const CAPABILITY_VALUES = Object.freeze({
+  schemaEnforced: Object.freeze([true, false]),
+  modelSelect: Object.freeze(['flag', 'negotiated', 'map-only']),
+  worktree: Object.freeze(['driver', 'runtime']),
+  hooks: Object.freeze([true, false]),
+  usage: Object.freeze([true, false]),
+  cacheAccounting: Object.freeze([true, false]),
+  billing: Object.freeze(['claude-subscription-programmatic', 'chatgpt-plan-or-api', 'local'])
+})
+
+/**
+ * The Workflow host's id. Not an adapter — the runner refuses it, and `run
+ * start` treats a run without declared capabilities as this one (design D10).
+ * What that assumption CONTAINS is stated once, in `lib/run.mjs`, because the
+ * run program is the only party that reads it.
+ */
+export const WORKFLOW_HOST_ID = 'workflow'
+
+export const HOSTS = Object.freeze({
+  claude: {
+    id: 'claude',
+    create: opts => createClaudeHost(opts),
+    capabilities: Object.freeze({
+      schemaEnforced: true,
+      modelSelect: 'flag',
+      worktree: 'driver',
+      hooks: true,
+      usage: true,
+      // The vendor envelope carries `cache_read_input_tokens` and a
+      // `cache_creation` block split by lifetime tier; `readClaudeEnvelope`
+      // keeps both.
+      cacheAccounting: true,
+      billing: 'claude-subscription-programmatic'
+    })
+  },
+  acp: {
+    id: 'acp',
+    create: opts => createAcpHost(opts),
+    // Declared for the general case — an arbitrary agent behind
+    // `INTERLOCK_ACP_COMMAND`. The adapter refines `hooks` and `billing` at
+    // creation when that command turns out to be the Claude binary, because a
+    // run that IS spending a Claude subscription must say so (design D8).
+    capabilities: Object.freeze({
+      schemaEnforced: false,
+      modelSelect: 'negotiated',
+      worktree: 'driver',
+      hooks: false,
+      usage: false,
+      // No usage envelope to decompose. Refined at creation only where `usage`
+      // is, and it is not — an arbitrary ACP agent reports neither.
+      cacheAccounting: false,
+      billing: 'local'
+    })
+  },
+  codex: {
+    id: 'codex',
+    create: opts => createCodexHost(opts),
+    capabilities: Object.freeze({
+      schemaEnforced: true,
+      modelSelect: 'map-only',
+      worktree: 'driver',
+      hooks: false,
+      usage: true,
+      // Token usage without a cache decomposition — exactly the gap this
+      // capability exists to make declarable rather than inferrable.
+      cacheAccounting: false,
+      billing: 'chatgpt-plan-or-api'
+    })
+  },
+  qwen: {
+    id: 'qwen',
+    create: opts => createQwenHost(opts),
+    capabilities: Object.freeze({
+      schemaEnforced: true,
+      modelSelect: 'map-only',
+      worktree: 'driver',
+      hooks: false,
+      usage: false,
+      cacheAccounting: false,
+      billing: 'local'
+    })
+  }
+})
+
+/** Every adapter id the runner accepts, for a message that names them. */
+export const HOST_IDS = Object.freeze(Object.keys(HOSTS))
+
+/**
+ * Create the adapter an id names.
+ *
+ * Throws on an unknown id and on the Workflow host, both before any step runs:
+ * a run that started and then discovered it had no host would already have
+ * written a manifest and a trajectory for a run that never happened.
+ *
+ * @param {string} id
+ * @param {object} [opts] passed through to the adapter's factory
+ * @returns {import('../host.mjs').WorkflowHost & {capabilities: object}}
+ */
+export function createHost(id, opts = {}) {
+  const wanted = typeof id === 'string' ? id.trim() : ''
+  if (wanted === WORKFLOW_HOST_ID) {
+    throw new Error(
+      'the Workflow runtime is reached through /interlock:ship, not the runner — ' +
+        `known runner hosts: ${HOST_IDS.join(', ')}`
+    )
+  }
+  const entry = HOSTS[wanted]
+  if (!entry) {
+    throw new Error(`unknown host "${wanted || '(none)'}" — known hosts: ${HOST_IDS.join(', ')}`)
+  }
+  const host = entry.create(opts)
+  return Object.assign(host, {
+    id: entry.id,
+    capabilities: effectiveCapabilities(entry, host)
+  })
+}
+
+/**
+ * The declared capabilities, refined by anything the created host observed
+ * about itself.
+ *
+ * Only ACP refines today, and only downward-to-honest: a `claude` binary behind
+ * `INTERLOCK_ACP_COMMAND` means the run does have this repository's hooks and is
+ * spending a Claude subscription, and declaring otherwise would suppress the two
+ * banners that matter most on that path.
+ *
+ * @param {{capabilities: object}} entry
+ * @param {object} host
+ * @returns {object}
+ */
+function effectiveCapabilities(entry, host) {
+  const declared = { ...entry.capabilities }
+  const observed = host && typeof host.capabilities === 'object' && host.capabilities ? host.capabilities : {}
+  for (const key of CAPABILITY_KEYS) {
+    if (observed[key] !== undefined) declared[key] = observed[key]
+  }
+  return declared
+}
+
+/**
+ * Whether a host id, as configured, drives the Claude binary — directly or
+ * through ACP. The `SUBSCRIPTION PATH` banner's condition (design D8).
+ *
+ * @param {string} id
+ * @param {Record<string, string|undefined>} [env]
+ * @param {string} [acpCommand] an explicit --acp-command, which beats the env
+ * @returns {boolean}
+ */
+export function drivesClaudeBinary(id, env = {}, acpCommand) {
+  if (id === 'claude') return true
+  if (id !== 'acp') return false
+  const raw = typeof acpCommand === 'string' && acpCommand.trim()
+    ? acpCommand
+    : (env && env[ACP_COMMAND_ENV]) || ''
+  try {
+    return isClaudeCodeBinary(parseAcpCommand(raw).command)
+  } catch {
+    // An unusable command is not a Claude run; the adapter's own creation error
+    // is what the operator will see.
+    return false
+  }
+}