@aidriftline/driftline 0.1.15 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidriftline/driftline",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Finds OpenAI, Anthropic and Google model IDs in your code and warns before they are retired. CLI, GitHub Action and MCP server.",
   "mcpName": "io.github.AI-Driftline/driftline",
   "type": "module",

package/src/cli.js

@@ -8,6 +8,7 @@
 //   driftline mcp                      MCP server on stdio for coding agents (Claude Code, Cursor, ...)
 //   driftline --help | --version
 import { loadBestRegistry } from "./registry.js";
+import { migrationFor } from "./migration.js";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
@@ -80,7 +81,7 @@ if (cmd === "-h" || cmd === "--help" || cmd === "help") {
     const pick = (f) => ({
       id: f.id, file: f.file, line: f.line, status: f.status, docOnly: !!f.doc,
       provider: f.entry?.provider, retires: f.entry?.retires, qualifier: f.entry?.qualifier,
-      replacement: f.entry?.replacement, routes: !!f.entry?.routes, aliasOf: f.entry?.aliasOf,
+      replacement: f.entry?.replacement, migration: migrationFor(f.entry) || undefined, routes: !!f.entry?.routes, aliasOf: f.entry?.aliasOf,
     });
     console.log(JSON.stringify({ findings: result.findings.map(pick), drift: result.drift || [] }, null, 2));
   } else console.log(result.markdown);

package/src/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // GitHub Action entry point.
 import { replacementText, replacementChange, loadBestRegistry } from "./registry.js";
+import { migrationFor } from "./migration.js";
 import { resolve } from "node:path";
 import { statSync } from "node:fs";
 import { randomUUID } from "node:crypto";
@@ -53,6 +54,8 @@ async function main() {
   for (const f of toAnnotate.slice(0, MAX_ANNOTATIONS)) {
     const level = f.status === "deprecated" || f.doc ? "notice" : "warning";
     const chg = replacementChange(f.entry);
+    const mig = f.entry.routes ? null : migrationFor(f.entry);
+    const more = mig && !mig.drop_in && mig.change !== "settings" ? ` Not just a rename: ${mig.note}` : mig?.change === "choose" ? ` ${mig.note}` : "";
     const repl = f.entry?.replacement && !f.entry.routes ? ` Replacement: ${replacementText(f.entry)}.${chg ? ` (Changed by the provider on ${chg.on}; before it was ${chg.was}.)` : ""}` : "";
     const text = f.entry.routes && f.entry.replacement
       ? (f.days <= 0
@@ -61,7 +64,8 @@ async function main() {
       : f.entry.qualifier === "earliest" && f.days <= 0
       ? `${f.id} is past its earliest shutdown date (${f.entry.retires}) and may stop working at any time.`
       : `${f.id} ${STATUS_TEXT[f.status]} (${f.entry.retires}).`;
-    annotate(level, text + repl, f.file, f.line);
+    const routedMore = f.entry.routes && migrationFor(f.entry)?.change === "params" ? ` Before then, apply the request changes the provider lists: ${migrationFor(f.entry).note}` : "";
+    annotate(level, text + repl + more + routedMore, f.file, f.line);
   }
 
   // The report contains model answers; stop GitHub from reading any "::command::" lines inside it.

package/src/mcp.js

@@ -7,6 +7,7 @@ import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { loadBestRegistry, classify, normalizeId, replacementChange } from "./registry.js";
+import { migrationFor } from "./migration.js";
 import { scanDirectory } from "./scan.js";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
@@ -21,15 +22,17 @@ function advice(c, today = new Date()) {
   if (!m) return "Not in Driftline's registry: no retirement is announced for it on the OpenAI, Anthropic or Google deprecation pages (or it is not a model ID).";
   const who = WHO[m.provider] || m.provider;
   const chg = replacementChange(m, today);
+  const mig = migrationFor(m);
+  const migText = mig && !mig.drop_in && mig.change !== "settings" ? ` More than a rename: ${mig.note}` : mig?.change === "choose" ? ` ${mig.note}` : "";
   const repl = m.replacement ? ` Replacement: ${m.replacement}${m.replacement_note ? ` (${m.replacement_note})` : ""}.${chg ? ` ${who} changed this recommendation on ${chg.on}; before it was ${chg.was}.` : ""}` : "";
   if (m.qualifier === "not-before") return `Active. ${who} says it will not be retired before ${m.retires}.`;
   if (m.routes) return c.days <= 0
-    ? `Since ${m.retires}, ${who} answers requests for it with ${m.replacement}. No error, but answers come from a different model.`
-    : `From ${m.retires} (in ${c.days} days), ${who} will answer requests for it with ${m.replacement}.`;
+    ? `Since ${m.retires}, ${who} answers requests for it with ${m.replacement}. No error, but answers come from a different model.${migText}`
+    : `From ${m.retires} (in ${c.days} days), ${who} will answer requests for it with ${m.replacement}.${migText}`;
   if (m.qualifier === "earliest") return c.days <= 0
-    ? `${who} listed ${m.retires} as the earliest shutdown date; it can stop working at any time now.${repl}`
-    : `${who} may shut it down from ${m.retires} (in ${c.days} days).${repl}`;
-  return c.days <= 0 ? `Retired on ${m.retires}. Calls to it fail.${repl}` : `Retires on ${m.retires} (in ${c.days} days). Calls fail after that.${repl}`;
+    ? `${who} listed ${m.retires} as the earliest shutdown date; it can stop working at any time now.${repl}${migText}`
+    : `${who} may shut it down from ${m.retires} (in ${c.days} days).${repl}${migText}`;
+  return c.days <= 0 ? `Retired on ${m.retires}. Calls to it fail.${repl}${migText}` : `Retires on ${m.retires} (in ${c.days} days). Calls fail after that.${repl}${migText}`;
 }
 
 function describe(rawId, reg, today) {
@@ -43,6 +46,7 @@ function describe(rawId, reg, today) {
       replacement: m.replacement || null, ...(m.replacement_note ? { replacement_note: m.replacement_note } : {}),
       ...(m.previous_replacement ? { previous_replacement: m.previous_replacement, replacement_changed: m.replacement_changed } : {}), routes: !!m.routes, ...(m.aliasOf ? { alias_of: m.aliasOf } : {}), page: page(m.aliasOf || m.id),
     } : {}),
+    ...(m && migrationFor(m) ? { migration: migrationFor(m) } : {}),
     advice: advice(c, today),
   };
 }
@@ -60,6 +64,7 @@ const MODEL_RESULT = {
     replacement: { type: ["string", "null"] },
     previous_replacement: { type: "string", description: "The replacement the provider recommended before it changed its advice" },
     replacement_changed: { type: "string", description: "YYYY-MM-DD: when the change was seen on the provider's page" },
+    migration: { type: "object", description: "Whether moving to the replacement is just a new model name (drop_in true) or needs more: change = rename | settings | params | api | re-embed | choose, with a note and the provider's guide", properties: { change: { type: "string" }, drop_in: { type: "boolean" }, note: { type: "string" }, guide: { type: ["string", "null"] } } },
     replacement_note: { type: "string", description: "Extra instruction the provider gives with the replacement (e.g. a setting or API to use). Without it, switching the model name alone is not enough" },
     routes: { type: "boolean", description: "true: after the date the provider answers with the replacement model instead of failing" },
     alias_of: { type: "string" }, page: { type: "string", description: "aidriftline.com page with the source for this date" },

package/src/migration.js

@@ -0,0 +1,101 @@
+// Is the replacement a drop-in, or does moving to it need more than a new model name?
+// Rules per model family, written from the providers' own migration docs (checked 13 Nov 2026).
+// Anything no rule matches is a plain rename, which is how Driftline has always presented it.
+//
+// migrationFor(entry) → { change, drop_in, note, guide }
+//   change: "rename"   the model name is the only change
+//           "settings" also set a parameter the provider names (e.g. reasoning.mode: pro)
+//           "params"   some request parameters are removed or renamed
+//           "api"      a different API, method or endpoint
+//           "re-embed" stored embeddings have to be recomputed
+//           "choose"   the provider names more than one replacement; which one depends on how you use it
+
+const OPENAI = "https://developers.openai.com/api/docs/guides/";
+const GOOGLE = "https://ai.google.dev/gemini-api/docs/";
+
+// Claude family version from an ID: claude-sonnet-4-5-20250929 → 4.5, claude-3-haiku-20240307 → 3, claude-opus-4-8 → 4.8
+function claudeVersion(id) {
+  const m = String(id || "").match(/^claude-(?:(?:opus|sonnet|haiku|fable|mythos)-)?(\d+)(?:[-.](\d))?(?:-|$)/);
+  return m ? Number(m[1]) + (m[2] ? Number(m[2]) / 10 : 0) : null;
+}
+const geminiMajor = (id) => { const m = String(id || "").match(/^gemini-(\d+)/); return m ? Number(m[1]) : null; };
+
+const RULES = [
+  {
+    when: (e) => e.provider === "openai" && (/^(davinci-002|babbage-002|gpt-3\.5-turbo-instruct)/.test(e.id) || /-completions$/.test(e.id)),
+    change: "api",
+    note: "The old Completions endpoint (a plain prompt) doesn't serve the replacement: move the call to the Responses API or Chat Completions (messages).",
+    guide: OPENAI + "migrate-to-responses",
+  },
+  {
+    when: (e) => e.provider === "openai" && /^(tts-1|gpt-4o-mini-tts)/.test(e.id),
+    change: "api",
+    note: "OpenAI calls this a change of API workflow: the replacement isn't a model for /v1/audio/speech and runs through the Realtime API.",
+    guide: OPENAI + "text-to-speech",
+  },
+  {
+    when: (e) => e.provider === "openai" && /realtime-preview/.test(e.id),
+    change: "api",
+    note: "The preview models ran on the Realtime beta (header OpenAI-Beta: realtime=v1), which OpenAI shut down; the replacement needs the current Realtime API.",
+    guide: OPENAI + "realtime",
+  },
+  {
+    when: (e) => e.provider === "openai" && /^(whisper-1|gpt-4o(-mini)?-transcribe)/.test(e.id),
+    change: "choose",
+    note: "OpenAI names two replacements: gpt-transcribe for recorded files, gpt-live-transcribe for live audio. Word timestamps, subtitles and translation work differently, so check those if you use them.",
+    guide: OPENAI + "transcription",
+  },
+  {
+    when: (e) => e.provider === "openai" && e.kind === "image" && /-sunburst$/.test(e.replacement || ""),
+    change: "rename",
+    note: "Same Images API. OpenAI offers two: …-sunburst for editing precision, …-flare for fast everyday generation.",
+    guide: OPENAI + "image-generation",
+  },
+  {
+    when: (e) => e.kind === "embedding",
+    change: "re-embed",
+    note: "Embeddings from different models can't be compared: re-embed your stored data with the new model, and query with that same model. The vector size may differ too.",
+    guide: (e) => e.provider === "google" ? GOOGLE + "embeddings" : OPENAI + "embeddings",
+  },
+  {
+    when: (e) => e.provider === "google" && /^imagen-/.test(e.id),
+    change: "api",
+    note: "Use generate_content instead of generate_images; images come back as content parts, not an image response object.",
+    guide: GOOGLE + "imagen",
+  },
+  {
+    when: (e) => e.provider === "google" && /^veo-/.test(e.id),
+    change: "api",
+    note: "Gemini Omni Flash uses the Interactions API (interactions.create), not Veo's video-generation call. Google also offers Veo itself on Gemini Enterprise Agent Platform.",
+    guide: GOOGLE + "video",
+  },
+  {
+    when: (e) => e.provider === "google" && (!e.kind || e.kind === "text") && geminiMajor(e.id) === 2 && geminiMajor(e.replacement) >= 3,
+    change: "params",
+    note: "Gemini 3 changes the request: remove temperature, top_p, top_k, candidate_count and prefilled model turns, replace thinking_budget with thinking_level, and check function calling.",
+    guide: (e) => GOOGLE + (/^gemini-3\.8/.test(e.replacement) ? "whats-new-gemini-3.8" : "whats-new-gemini-3.6"),
+  },
+  {
+    when: (e) => e.provider === "anthropic" && claudeVersion(e.id) !== null && claudeVersion(e.id) < 4.7 && claudeVersion(e.replacement) >= 4.7,
+    change: "params",
+    note: "Claude 4.7 and later accept only the default temperature, top_p and top_k: if your code sets them, remove them.",
+    guide: "https://platform.claude.com/docs/en/api/migration-2026-10-21",
+  },
+];
+
+export function migrationFor(entry) {
+  if (!entry?.replacement) return null;
+  // A provider's own instruction next to the replacement (registry replacement_note) comes first.
+  const setting = entry.replacement_note
+    ? { change: "settings", drop_in: false, note: `Also set ${entry.replacement_note}.`, guide: /reasoning\.mode/.test(entry.replacement_note) ? OPENAI + "reasoning" : null }
+    : null;
+  const rule = RULES.find((r) => r.when(entry));
+  if (!rule) return setting || { change: "rename", drop_in: true, note: "", guide: null };
+  const found = { change: rule.change, drop_in: rule.change === "rename", note: rule.note, guide: typeof rule.guide === "function" ? rule.guide(entry) : rule.guide };
+  return setting ? { ...found, change: found.change === "rename" ? "settings" : found.change, drop_in: false, note: `${setting.note} ${found.note}` } : found;
+}
+
+// Short label for tables: "Rename" or what else is needed.
+export const MIGRATION_LABEL = {
+  rename: "Rename", settings: "Rename + setting", params: "Parameter changes", api: "API change", "re-embed": "Re-embed data", choose: "Pick one of two",
+};

package/src/providers.js

@@ -63,7 +63,7 @@ async function postOnce(fetchImpl, url, headers, body) {
   return json;
 }
 
-export async function complete({ model, prompt, system, env = process.env, fetchImpl = fetch }) {
+export async function complete({ model, prompt, system, reasoningMode = null, env = process.env, fetchImpl = fetch }) {
   const provider = providerOf(model);
   const key = keyFor(provider, env);
   if (!key) throw new Error(missingKeyMessage(provider));
@@ -71,7 +71,7 @@ export async function complete({ model, prompt, system, env = process.env, fetch
   if (provider === "openai") {
     const data = await postJson(fetchImpl, "https://api.openai.com/v1/responses",
       { authorization: `Bearer ${key}` },
-      { model, input: prompt, ...(system ? { instructions: system } : {}) });
+      { model, input: prompt, ...(system ? { instructions: system } : {}), ...(reasoningMode ? { reasoning: { mode: reasoningMode } } : {}) });
     const text = typeof data.output_text === "string" ? data.output_text : (data.output || [])
       .flatMap((o) => o.content || [])
       .filter((c) => c.type === "output_text" || typeof c.text === "string")

package/src/report.js

@@ -1,4 +1,5 @@
 import { replacementChange } from "./registry.js";
+import { migrationFor, MIGRATION_LABEL } from "./migration.js";
 
 const STATUS_LABEL = {
   retired: "🔴 Retired",
@@ -65,16 +66,30 @@ export function renderReport({ findings, drift, registry, notices = [], answers
     lines.push(n
       ? `**${n} reference${n === 1 ? "" : "s"} to retired or retiring models** across ${byModel.size} model ID${byModel.size === 1 ? "" : "s"} found.`
       : `Found ${byModel.size} model ID${byModel.size === 1 ? "" : "s"}. None are scheduled for retirement.`);
-    lines.push("", "| Model | Status | Retirement | Replacement | Where |", "|---|---|---|---|---|");
+    lines.push("", "| Model | Status | Retirement | Replacement | Change needed | Where |", "|---|---|---|---|---|---|");
+    const migNotes = new Map(); // note → { n, ids, guide } for the list under the table
     const order = ["retired", "at-risk", "deprecated", "active", "unknown"];
     const all = [...byModel.values()].sort((a, b) => order.indexOf(a.status) - order.indexOf(b.status));
     const rows = all.slice(0, MAX_ROWS); // flagged models sort first, so only unknown/active rows get cut
     for (const r of rows) {
+      const mig = migrationFor(r.entry);
+      let changeCell = "";
+      if (mig) {
+        if (mig.note && !(mig.change === "settings" && r.entry.replacement_note && mig.note === `Also set ${r.entry.replacement_note}.`)) {
+          if (!migNotes.has(mig.note)) migNotes.set(mig.note, { n: migNotes.size + 1, ids: [], guide: mig.guide });
+          migNotes.get(mig.note).ids.push(r.id);
+          changeCell = `${mig.drop_in ? "✅" : "⚠️"} ${MIGRATION_LABEL[mig.change]} [${migNotes.get(mig.note).n}]`;
+        } else changeCell = `${mig.drop_in ? "✅" : "⚠️"} ${MIGRATION_LABEL[mig.change]}`;
+      }
       const places = r.places.slice(0, 3).join(", ") + (r.places.length > 3 ? ` +${r.places.length - 3} more` : "");
       const docsOnly = r.places.length && byModel.get(r.id).docs === r.places.length ? " · docs only" : "";
-      lines.push(`| ${code(r.id)}${r.entry?.aliasOf ? " · alias of " + code(r.entry.aliasOf) : ""}${r.entry?.kind && r.entry.kind !== "text" ? " · " + r.entry.kind : ""} | ${label(r)}${docsOnly} | ${esc(when(r))} | ${r.entry?.replacement ? code(r.entry.replacement) + (r.entry.replacement_note ? " (" + esc(r.entry.replacement_note) + ")" : "") + changed(r.entry, today) : ""} | ${places} |`);
+      lines.push(`| ${code(r.id)}${r.entry?.aliasOf ? " · alias of " + code(r.entry.aliasOf) : ""}${r.entry?.kind && r.entry.kind !== "text" ? " · " + r.entry.kind : ""} | ${label(r)}${docsOnly} | ${esc(when(r))} | ${r.entry?.replacement ? code(r.entry.replacement) + (r.entry.replacement_note ? " (" + esc(r.entry.replacement_note) + ")" : "") + changed(r.entry, today) : ""} | ${changeCell} | ${places} |`);
     }
     if (all.length > rows.length) lines.push("", `_${all.length - rows.length} more model ID(s) with no retirement listed are not shown._`);
+    if (migNotes.size) {
+      lines.push("", "**More than a rename:**", "");
+      for (const [note, m] of migNotes) lines.push(`${m.n}. ${m.ids.map(code).join(", ")}: ${esc(note)}${m.guide ? ` ([provider guide](${m.guide}))` : ""}`);
+    }
   }
 
   if (drift?.length) {

package/src/run.js

@@ -7,6 +7,7 @@ import { complete, providerOf, keyFor, missingKeyMessage } from "./providers.js"
 import { compare, extractJson } from "./compare.js";
 import { checkLicense } from "./license.js";
 import { renderReport } from "./report.js";
+import { migrationFor } from "./migration.js";
 
 const MAX_PROMPTS = 20;
 const oneLine = (s) => String(s).replace(/[\r\n]+/g, " ");
@@ -95,9 +96,14 @@ async function runDrift({ prompts, findings, registry, env, fetchImpl, today, wa
       // The provider's replacement comes with an extra instruction (e.g. "reasoning.mode: pro") that this test
       // doesn't apply: say so on every row, so nobody reads a plain-mode answer as the replacement's best.
       const chg = !p.compare_to && replacementChange(status.entry, today);
+      // The provider says the replacement runs in a mode (e.g. reasoning.mode: pro): test it that way, as the customer would run it.
+      const proMode = !p.compare_to && /reasoning\.mode: pro/.test(status.entry?.replacement_note || "") && providerOf(to) === "openai" ? "pro" : null;
+      const mig = !p.compare_to ? migrationFor(status.entry) : null;
       const caveat = [
-        !p.compare_to && status.entry?.replacement_note
+        proMode ? "Replacement tested with reasoning.mode: pro, as the provider recommends." : "",
+        !p.compare_to && !proMode && status.entry?.replacement_note
           ? `Tested without "${status.entry.replacement_note}", which the provider says the replacement needs; answers after a correct switch may differ.` : "",
+        mig && !mig.drop_in && mig.change !== "settings" ? `Beyond the model name: ${mig.note}` : "",
         chg ? `The provider changed this replacement on ${chg.on} (before: ${chg.was}); drift results from earlier runs compared against ${chg.was}.` : "",
       ].filter(Boolean).join(" ");
       const push = (row) => out.push(caveat ? { ...row, note: [row.note, caveat].filter(Boolean).join(" ") } : row);
@@ -112,7 +118,7 @@ async function runDrift({ prompts, findings, registry, env, fetchImpl, today, wa
       }
       log(oneLine(`Drift test ${p.id}: ${from} → ${to}`));
       try {
-        const after = await complete({ model: to, prompt: p.prompt, system: p.system, env, fetchImpl });
+        const after = await complete({ model: to, prompt: p.prompt, system: p.system, reasoningMode: proMode, env, fetchImpl });
         if (status.status === "retired") {
           if (!after.trim()) {
             push({ id: p.id, from, to, after, before: "(current model already retired)", result: "broken", note: "Replacement returned an empty answer" });