@link-assistant/agent 0.25.8 → 0.26.0

package/README.md

@@ -376,6 +376,30 @@ echo "hi" | agent --json-standard claude
 - **Event Types**: `init`, `message`, `tool_use`, `tool_result`, `result`
 - **Timestamps**: ISO 8601 strings
 - **Session ID**: `session_id` (snake_case)
+- **Model**: the `init` event reports the resolved model as `"model": "<provider>/<model>"`
+
+#### Model Routing Attestation
+
+Both standards emit exactly one `model_resolved` event per run, immediately after
+the model is resolved and before the first request reaches a provider:
+
+```json
+{
+  "type": "model_resolved",
+  "timestamp": "2026-08-11T00:12:31.320Z",
+  "requested": "formalai/formal-ai",
+  "selector": "formalai/formal-ai",
+  "providerID": "formalai",
+  "modelID": "formal-ai",
+  "source": "cli",
+  "matchesRequest": true
+}
+```
+
+Switch on `type` rather than matching the human-readable
+`using explicit provider/model` log message — the log message is prose and may be
+reworded, the event type is a contract. See
+[docs/model-resolved-event.md](../docs/model-resolved-event.md).
 
 ### Input Formats
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.25.8",
+  "version": "0.26.0",
   "description": "A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface. Bun-only runtime.",
   "main": "src/index.js",
   "type": "module",

package/src/cli/continuous-mode.js

@@ -303,8 +303,11 @@ export async function runContinuousServerMode(
       }
     }
 
-    // Create event handler for the selected JSON standard
-    const eventHandler = createEventHandler(jsonStandard, sessionID);
+    // Create event handler for the selected JSON standard.
+    // The resolved model rides along so the Claude `init` event reports it (#295).
+    const eventHandler = createEventHandler(jsonStandard, sessionID, {
+      model: `${providerID}/${modelID}`,
+    });
 
     // Track if we're currently processing a message
     let isProcessing = false;
@@ -526,8 +529,11 @@ export async function runContinuousDirectMode(
       sessionID = session.id;
     }
 
-    // Create event handler for the selected JSON standard
-    const eventHandler = createEventHandler(jsonStandard, sessionID);
+    // Create event handler for the selected JSON standard.
+    // The resolved model rides along so the Claude `init` event reports it (#295).
+    const eventHandler = createEventHandler(jsonStandard, sessionID, {
+      model: `${providerID}/${modelID}`,
+    });
 
     // Track if we're currently processing a message
     let isProcessing = false;

package/src/cli/model-config.js

@@ -10,10 +10,12 @@ import {
   DEFAULT_MODEL_ID,
   getDefaultModel,
   getDefaultModelParts,
+  getDefaultModelSource,
   getDefaultCompactionModel,
   getDefaultCompactionModels,
   getDefaultCompactionSafetyMarginPercent,
 } from './defaults.ts';
+import { outputModelResolved } from './model-resolution.ts';
 
 export class ModelResolutionError extends Error {
   constructor({ modelArgv, defaultModel }) {
@@ -96,6 +98,19 @@ export async function parseModelConfig(
     }
   }
 
+  // Attestation inputs (#295): record what was requested, and where it came
+  // from, before resolution can rewrite the effective model. `argv.model` is
+  // only treated as a request when it differs from the default, because yargs
+  // fills it with the default value even when no --model flag was passed.
+  const argvModelArg =
+    typeof argv.model === 'string' && argv.model !== defaultModel
+      ? argv.model
+      : null;
+  const requestedModel = cliModelArg ?? argvModelArg;
+  const modelSource = requestedModel
+    ? 'cli'
+    : getDefaultModelSource(defaultOptions);
+
   let providerID;
   let modelID;
 
@@ -257,6 +272,28 @@ export async function parseModelConfig(
     }
   }
 
+  // Machine-readable routing attestation (#295).
+  // Emitted last inside this function, which is still the earliest point where
+  // the effective model is final: --use-existing-claude-oauth above is the one
+  // path that can replace an already selected model, and the attestation must
+  // describe what actually runs. It is emitted before session creation and
+  // before any completion request, so a consumer can terminate the run before a
+  // request reaches a provider it did not ask for. Claude NDJSON streams must
+  // stay one line, so that standard forces compact output regardless of
+  // --compact-json.
+  const usesClaudeStandard =
+    argv['json-standard'] === 'claude' || argv.jsonStandard === 'claude';
+  outputModelResolved(
+    {
+      requested: requestedModel,
+      selector: modelArg,
+      providerID,
+      modelID,
+      source: modelSource,
+    },
+    usesClaudeStandard || argv['compact-json'] === true ? true : undefined
+  );
+
   return { providerID, modelID, compactionModel: compactionModelResult };
 }
 

package/src/cli/model-resolution.ts

@@ -0,0 +1,108 @@
+/**
+ * Machine-readable model routing attestation.
+ *
+ * The CLI already logs which provider/model it settled on, but that record is
+ * discriminated by a free-text `message` ("using explicit provider/model").
+ * A consumer that must *verify* routing — for example a supervisor that kills
+ * the run when the agent resolves anything other than the requested model —
+ * would have to match English prose, so an ordinary reword upstream silently
+ * disables a downstream safety check.
+ *
+ * `model_resolved` is the contract instead: one event per run, emitted on
+ * every resolution path (explicit `provider/model`, bare model id and default),
+ * before the first `step_start` and before any completion request.
+ *
+ * @see https://github.com/link-assistant/agent/issues/295
+ */
+
+import { output } from './output';
+
+/**
+ * Stable `type` of the routing attestation event.
+ *
+ * This string is a machine contract: consumers switch on it. Never reword it —
+ * a change here is a breaking change, unlike a change to any log message.
+ */
+export const MODEL_RESOLVED_EVENT_TYPE = 'model_resolved';
+
+/**
+ * Where the applied model selector came from.
+ * - `cli`: the `--model`/`-m` command line argument.
+ * - `config`: no CLI flag; an operator-configured default is in effect.
+ * - `default`: no CLI flag and no override; the built-in default model.
+ */
+export type ModelSource = 'cli' | 'config' | 'default';
+
+export interface ModelResolvedDetails {
+  /** Raw `--model` value, or `null` when no model was requested. */
+  requested: string | null;
+  /** Selector actually applied: `requested`, or the effective default. */
+  selector: string;
+  providerID: string;
+  modelID: string;
+  source: ModelSource;
+  /** ISO timestamp; injectable so tests stay deterministic. */
+  timestamp?: string;
+}
+
+export interface ModelResolvedEvent extends ModelResolvedDetails {
+  type: typeof MODEL_RESOLVED_EVENT_TYPE;
+  timestamp: string;
+  /**
+   * Whether the resolved provider/model satisfies `selector`. `false` means the
+   * run is about to talk to a model other than the one that was selected, even
+   * when the selector came from a default rather than from `--model`.
+   */
+  matchesRequest: boolean;
+  [key: string]: unknown;
+}
+
+/**
+ * Does `providerID`/`modelID` satisfy the selector the caller supplied?
+ *
+ * A selector with a `/` names both provider and model and must match both.
+ * A bare selector names only the model, so the resolved provider is free.
+ */
+export function selectorMatchesModel(
+  selector: string,
+  providerID: string,
+  modelID: string
+): boolean {
+  if (selector.includes('/')) {
+    return selector === `${providerID}/${modelID}`;
+  }
+  return selector === modelID;
+}
+
+/** Build the attestation event without emitting it (pure; used by tests). */
+export function buildModelResolvedEvent(
+  details: ModelResolvedDetails
+): ModelResolvedEvent {
+  const { requested, selector, providerID, modelID, source, timestamp } =
+    details;
+  return {
+    type: MODEL_RESOLVED_EVENT_TYPE,
+    timestamp: timestamp ?? new Date().toISOString(),
+    requested: requested ?? null,
+    selector,
+    providerID,
+    modelID,
+    source,
+    matchesRequest: selectorMatchesModel(selector, providerID, modelID),
+  };
+}
+
+/**
+ * Emit the attestation on stdout and return the emitted event.
+ *
+ * @param compact - Force single-line JSON (required for NDJSON streams such as
+ *   `--output-format stream-json`); defaults to the global compact setting.
+ */
+export function outputModelResolved(
+  details: ModelResolvedDetails,
+  compact?: boolean
+): ModelResolvedEvent {
+  const event = buildModelResolvedEvent(details);
+  output(event, compact);
+  return event;
+}

package/src/cli/output.ts

@@ -28,7 +28,9 @@ export type OutputType =
   | 'init'
   | 'message'
   | 'tool_result'
-  | 'input';
+  | 'input'
+  // Routing attestation emitted once per run, see cli/model-resolution.ts (#295)
+  | 'model_resolved';
 
 /**
  * Base interface for all output messages

package/src/config/defaults.ts

@@ -112,6 +112,25 @@ export function getDefaultModel(options: DefaultConfigOptions = {}): string {
   );
 }
 
+/**
+ * Report where the effective default model came from.
+ *
+ * `'config'` means an operator override is in effect (`defaultOptions.defaultModel`
+ * or `LINK_ASSISTANT_AGENT_DEFAULT_MODEL`); `'default'` means the built-in
+ * `DEFAULT_MODEL`. Used by the `model_resolved` attestation so a consumer can
+ * tell a configured fallback from the shipped one.
+ *
+ * @see https://github.com/link-assistant/agent/issues/295
+ */
+export function getDefaultModelSource(
+  options: DefaultConfigOptions = {}
+): 'config' | 'default' {
+  const env = options.env ?? process.env;
+  if (optionString(options.defaultModel)) return 'config';
+  if (envString(env, DEFAULT_MODEL_ENV)) return 'config';
+  return 'default';
+}
+
 export function getDefaultCompactionModel(
   options: DefaultConfigOptions = {}
 ): string {

package/src/index.js

@@ -486,8 +486,11 @@ async function runServerMode(
       }
     }
 
-    // Create event handler for the selected JSON standard
-    const eventHandler = createEventHandler(jsonStandard, sessionID);
+    // Create event handler for the selected JSON standard.
+    // The resolved model rides along so the Claude `init` event reports it (#295).
+    const eventHandler = createEventHandler(jsonStandard, sessionID, {
+      model: `${providerID}/${modelID}`,
+    });
 
     // Subscribe to all bus events and output in selected format
     const { unsub: eventUnsub, idlePromise: eventPromise } =
@@ -580,8 +583,11 @@ async function runDirectMode(
       sessionID = session.id;
     }
 
-    // Create event handler for the selected JSON standard
-    const eventHandler = createEventHandler(jsonStandard, sessionID);
+    // Create event handler for the selected JSON standard.
+    // The resolved model rides along so the Claude `init` event reports it (#295).
+    const eventHandler = createEventHandler(jsonStandard, sessionID, {
+      model: `${providerID}/${modelID}`,
+    });
 
     // Subscribe to all bus events and output in selected format
     const { unsub: eventUnsub, idlePromise: eventPromise } =

package/src/json-standard/index.ts

@@ -75,10 +75,14 @@ export function serializeOutput(
 
 /**
  * Convert OpenCode event to Claude event format
+ *
+ * @param model - Resolved `providerID/modelID`, reported on the `init` event so
+ *   Claude-standard consumers see which model the run settled on (#295)
  */
 export function convertOpenCodeToClaude(
   event: OpenCodeEvent,
-  startTime: number
+  startTime: number,
+  model?: string
 ): ClaudeEvent | null {
   const timestamp = new Date(event.timestamp).toISOString();
   const session_id = event.sessionID;
@@ -89,6 +93,7 @@ export function convertOpenCodeToClaude(
         type: 'init',
         timestamp,
         session_id,
+        ...(model ? { model } : {}),
       };
 
     case 'text':
@@ -157,9 +162,17 @@ export function convertOpenCodeToClaude(
 
 /**
  * Create an event output handler based on the selected standard
+ *
+ * @param options.model - Resolved `providerID/modelID` for the run; carried on
+ *   the Claude `init` event (#295)
  */
-export function createEventHandler(standard: JsonStandard, sessionID: string) {
+export function createEventHandler(
+  standard: JsonStandard,
+  sessionID: string,
+  options: { model?: string } = {}
+) {
   const startTime = Date.now();
+  const { model } = options;
 
   return {
     /**
@@ -169,7 +182,7 @@ export function createEventHandler(standard: JsonStandard, sessionID: string) {
       const outputStream =
         event.type === 'error' ? process.stderr : process.stdout;
       if (standard === 'claude') {
-        const claudeEvent = convertOpenCodeToClaude(event, startTime);
+        const claudeEvent = convertOpenCodeToClaude(event, startTime, model);
         if (claudeEvent) {
           outputStream.write(serializeOutput(claudeEvent, standard));
         }