@deepseek-insight/dsi 0.8.4 → 0.9.0

package/.agents/skills/glass-url/scripts/_args.mjs

@@ -0,0 +1,49 @@
+/**
+ * _args.mjs — pure helpers for glass-url.mjs (ADR-0045 Amendment 5, D9 + D10).
+ *
+ * Lives beside _connect.mjs so vitest can pin them without touching CDP
+ * (the driver connects at import; these never do). Exports are a contract:
+ * change them in the same edit that changes glass-url.mjs.
+ */
+
+/**
+ * Title normalization: fold apostrophes, case, and punctuation runs.
+ * @param {string | undefined | null} s
+ * @returns {string}
+ */
+export const norm = (s) => (s || '').toLowerCase().replace(/[\u2019']/g, '').replace(/[^a-z0-9]+/g, ' ').trim();
+
+/**
+ * D10 — the eval grammar is parsed, not positional.
+ * Inline mode:  [substr?] src           — the LAST arg is always the JS source.
+ * b64 mode:     [b64payload, substr?]   — the payload is consumed by the caller
+ *               (it already stripped --b64), so anything LEFT is the substring.
+ * Returns an object with src and substr, undefined where absent.
+ * @param {string[]} rest
+ * @param {{ b64?: boolean } | undefined} [opts]
+ * @returns {{ src: string | undefined, substr: string | undefined }}
+ */
+export function parseEvalArgs(rest, opts) {
+  const b64 = !!(opts && opts.b64);
+  if (b64) {
+    return { src: rest[0], substr: rest.length > 1 ? rest[1] : undefined };
+  }
+  if (rest.length > 1) return { substr: rest[0], src: rest[1] };
+  return { src: rest[0], substr: undefined };
+}
+
+/**
+ * D9 — the play match consumes EVERY play term.
+ * True only when every whitespace-split term of play appears in the
+ * normalized title. An empty or absent play value means no filter (true) —
+ * the yt verb then takes the first result, unchanged behavior.
+ * @param {string} title
+ * @param {string | undefined | null} play
+ * @returns {boolean}
+ */
+export function matchAllTerms(title, play) {
+  const terms = (play || '').split(/\s+/).filter(Boolean);
+  if (!terms.length) return true;
+  const t = norm(title);
+  return terms.every((term) => t.includes(norm(term)));
+}

package/.agents/skills/glass-url/scripts/_connect.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * _connect.mjs — shared glass connection for the glass-url / glass-dsi drivers.
+ *
+ * EXPORTS (do not guess — this header is the contract, keep it in sync):
+ *   die(msg)                 — print a JSON error and exit 1.
+ *   identityFrom(argv)       — caller identity, first-wins: --owner-session
+ *                              flag > GLASS_OWNER_SESSION > DSH_SESSION_ID
+ *                              (the harness built-in is CONDITIONAL —
+ *                              dsh-shell-env index.js:89 injects it only
+ *                              when the execution carries an agent binding,
+ *                              RCA 2026-10-30 "the session id is gone" —
+ *                              so explicit beats inherited).
+ *   pickSession(sessions, envId)
+ *                            — PURE D7 resolver (unit-tested): match the
+ *                              caller's identity to ownerSessionId. NEVER
+ *                              registry index (ADR-0045 amendment 3).
+ *                              Returns { session } | { session:null, error }.
+ *   connect()                — GET /api/browser (the ONLY source of truth,
+ *                              ADR-0030) → pickSession → CDP connect →
+ *                              { session, browser, ctx }. Dies LOUDLY on
+ *                              ambiguity; degraded single-session runs print
+ *                              a warning on stderr and proceed.
+ *   pick(ctx, substr)        — page whose URL contains substr; NEVER
+ *                              positional "newest" among foreign tabs (D2).
+ */
+import { chromium } from 'playwright-core';
+
+/**
+ * @typedef {Object} GlassSession
+ * @property {string} id
+ * @property {number} [port]
+ * @property {string|null} [ownerSessionId]
+ * @property {string} [createdAt]
+ * @typedef {Object} PickResult
+ * @property {GlassSession|null|undefined} session
+ * @property {boolean} [degraded]
+ * @property {string} [note]
+ * @property {string} [error]
+ */
+
+const DSI = 'http://127.0.0.1:5175';
+
+/** @param {string} msg @returns {never} */
+export function die(msg) {
+  console.error(JSON.stringify({ error: msg, fallback: 'SKILL.md Step 1 — ask the OPERATOR to click the Browser chip IN THE RIGHT CONVERSATION, then catch the session via GET /api/browser. If DSH_SESSION_ID is absent from env, pass --owner-session <id> (the session id you already know from context).' }));
+  process.exit(1);
+}
+
+/** @param {string[]} argv @returns {string|undefined} */
+export function identityFrom(argv) {
+  const flag = argv.indexOf('--owner-session');
+  if (flag !== -1 && argv[flag + 1]) return argv[flag + 1];
+  if (process.env.GLASS_OWNER_SESSION) return process.env.GLASS_OWNER_SESSION;
+  if (process.env.DSH_SESSION_ID) return process.env.DSH_SESSION_ID;
+  return undefined;
+}
+
+/** @param {GlassSession[]|null|undefined} sessions @param {string|undefined} envId @returns {PickResult} */
+export function pickSession(sessions, envId) {
+  const list = sessions ?? [];
+  if (envId) {
+    const mine = list.filter((s) => (s.ownerSessionId ?? null) === envId);
+    if (mine.length === 1) return { session: mine[0], degraded: false };
+    if (mine.length > 1) {
+      const newest = [...mine].sort((a, b) => String(a.createdAt ?? '').localeCompare(String(b.createdAt ?? ''))).at(-1);
+      return { session: newest, degraded: false, note: 'multiple glasses owned by ' + envId + ' — newest wins' };
+    }
+    if (list.length === 1 && (list[0].ownerSessionId ?? null) === null) {
+      return { session: list[0], degraded: true, note: 'legacy session without ownerSessionId — degraded match' };
+    }
+    return { session: null, error: 'no glass owned by ' + envId + ' — your glass is dead or never summoned (click the Browser chip in THIS conversation); live glasses belong to other conversations and are untouchable (D7)' };
+  }
+  if (list.length === 1) {
+    return { session: list[0], degraded: true, note: 'no explicit identity in env — degraded single-session resolution' };
+  }
+  return { session: null, error: 'multiple live glasses and no explicit identity — pass --owner-session <id> (or GLASS_OWNER_SESSION) from the session id you already know; refusing to guess (D7)' };
+}
+
+/** @returns {Promise<{ session: GlassSession, browser: import('playwright-core').Browser, ctx: import('playwright-core').BrowserContext }>} */
+export async function connect() {
+  let reg;
+  try {
+    reg = await (await fetch(DSI + '/api/browser')).json();
+  } catch {
+    die('DSI dev server not reachable on 5175 — floor not up (dsi dsh --sync --dev --playwright-mcp)');
+  }
+  const { session, degraded, note, error } = pickSession(reg.sessions, identityFrom(process.argv));
+  if (!session) die(error ?? 'no glass session resolved — operator must click the Browser chip');
+  if (degraded || note) console.error(JSON.stringify({ warn: note ?? 'degraded', sessionId: session.id }));
+  const browser = await chromium.connectOverCDP('http://127.0.0.1:' + session.port).catch(() => null);
+  if (!browser) die('CDP connect failed on port ' + session.port);
+  return { session, browser, ctx: browser.contexts()[0] };
+}
+
+/** @param {import('playwright-core').BrowserContext} ctx @param {string} substr @returns {import('playwright-core').Page|undefined} */
+export function pick(ctx, substr) {
+  return ctx.pages().find((p) => p.url().includes(substr));
+}

package/.agents/skills/glass-url/scripts/glass-url.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * glass-url.mjs — the glass-url URL path (2026-10-29, hardened 2026-10-30,
+ * RCA "The Hardening That Missed the Token Burn").
+ *
+ * Drives NON-DSI surfaces (YouTube, docs, anything) on the operator's
+ * glass. Never touches the DSI tab. One command per intent:
+ *
+ *   node …/glass-url.mjs yt <search terms…> --play "<title-substring>" [--shot f.png]
+ *       search YouTube → normalized title match → open watch tab →
+ *       unmute+play → gate twice (paused:false, rising t) → optional shot.
+ *       Prints ONE JSON with every intermediate stage, then EXITS.
+ *   node …/glass-url.mjs open <url>
+ *   node …/glass-url.mjs pages
+ *   node …/glass-url.mjs eval [url-substring] <js>   # inline JS: LAST arg is the source
+ *   node …/glass-url.mjs eval --b64 <base64-js> [url-substring]
+ *       # base64 mode: quote-proof transport; anything left after the
+ *       # payload IS the url-substring (parsed by shape — D10, _args.mjs).
+ *       # yt --play consumes EVERY term (artist AND title) — D9.
+ *       # A NO_MATCH / die is an ANSWER: report and stop (D11, SKILL.md).
+ *   node …/glass-url.mjs shot [file.png] [url-substring]
+ *
+ * EXIT DISCIPLINE: this script always process.exit()s — a driver that
+ * played media once hung its caller for a full timeout (RCA trap 5).
+ */
+import { connect, die, pick } from './_connect.mjs';
+import { norm, parseEvalArgs, matchAllTerms } from './_args.mjs';
+
+const argv = process.argv.slice(2);
+const { session, browser, ctx } = await connect();
+const out = (v) => { console.log(JSON.stringify(v, null, 1)); return process.exit(0); };
+
+// target tab: url-substring when given; else last http(s) page that is
+// neither the glass placeholder nor :5175 (contract, not position — D2).
+const target = (substr) => {
+  if (substr) {
+    const p = pick(ctx, substr);
+    if (!p) die('no tab matching "' + substr + '" — run: pages');
+    return p;
+  }
+  const pages = ctx.pages().filter((p) => p.url().startsWith('http') && !p.url().includes(':5175'));
+  if (!pages.length) die('no non-DSI tab to drive — run: glass-url.mjs open <url>');
+  return pages[pages.length - 1];
+};
+
+// gate: read playback state; double-read proves time rises
+const gate = async (page) => page.evaluate(() => { const v = document.querySelector('video'); if (!v) return { err: 'novideo' }; v.muted = false; try { v.play(); } catch {} return { t: Math.round(v.currentTime * 10) / 10, paused: v.paused }; });
+
+const cmd = argv[0];
+
+if (cmd === 'open') {
+  const url = argv[1];
+  if (!url) die('open needs a url');
+  const page = await ctx.newPage();
+  await page.goto(url, { waitUntil: 'domcontentloaded' }).catch((e) => die('goto failed: ' + e.message));
+  await page.waitForTimeout(1500); // let the SPA settle
+  await page.bringToFront(); // make the opened tab the active/visible one
+  out({ ok: true, sessionId: session.id, url: page.url(), title: await page.title() });
+} else if (cmd === 'pages') {
+  out(await Promise.all(ctx.pages().map(async (p) => ({ url: p.url(), title: await p.title() }))));
+} else if (cmd === 'eval') {
+  let rest = argv.slice(1);
+  let substr;
+  let src;
+  let b64 = false;
+  if (rest[0] === '--b64') { b64 = true; rest = rest.slice(1); } // payload stays in rest; parseEvalArgs takes it from here (D10)
+  const parsed = parseEvalArgs(rest, { b64 });
+  src = parsed.src; substr = parsed.substr;
+  if (b64 && src) src = Buffer.from(src, 'base64').toString('utf8');
+  if (!src) die('eval needs js (inline or --b64 <base64>)');
+  out(await target(substr).evaluate(async (s) => await eval(s), src));
+} else if (cmd === 'shot') {
+  const file = argv[1] ?? 'tmp/glass-url-shot.png';
+  const substr = argv[2];
+  await target(substr).screenshot({ path: file });
+  out({ ok: true, file });
+} else if (cmd === 'yt') {
+  const dash = argv.indexOf('--play');
+  const shotFlag = argv.indexOf('--shot');
+  const terms = argv.slice(1, dash === -1 ? (shotFlag === -1 ? argv.length : shotFlag) : dash).join(' ');
+  const matchSub = dash !== -1 ? argv[dash + 1] : null;
+  const shotFile = shotFlag !== -1 ? argv[shotFlag + 1] ?? 'tmp/glass-url-yt.png' : null;
+  if (!terms) die('yt needs search terms');
+  const stages = {};
+  const sp = await ctx.newPage();
+  await sp.goto('https://www.youtube.com/results?search_query=' + encodeURIComponent(terms), { waitUntil: 'domcontentloaded' });
+  await sp.waitForTimeout(3500);
+  const raw = await sp.evaluate(() => [...document.querySelectorAll('a#video-title')].slice(0, 25).map((a) => ({ t: a.title || a.textContent.trim(), h: a.href })));
+  stages.candidates = raw.length;
+  const hit = raw.find((r) => matchAllTerms(r.t, matchSub));
+  if (!hit) out({ ok: false, stage: 'match', play: matchSub, titles: raw.slice(0, 10).map((r) => r.t) }); // D9: a refusal is an answer
+  stages.matched = hit.t;
+  const wp = await ctx.newPage();
+  const watchUrl = 'https://www.youtube.com/watch?v=' + new URL(hit.h).searchParams.get('v');
+  await wp.goto(watchUrl, { waitUntil: 'domcontentloaded' });
+  await wp.waitForTimeout(6000);
+  await wp.bringToFront();
+  // gate loop: paused:false with RISING t on the last two reads. YouTube
+  // may restart the video once as settings settle (observed 2026-10-30:
+  // t 5.9 then 3.8) — re-read up to 3x instead of failing an honest play.
+  const reads = [await gate(wp)];
+  for (let i = 0; i < 2; i++) { await wp.waitForTimeout(4000); reads.push(await gate(wp)); }
+  stages.gates = reads;
+  const last = reads.slice(-2);
+  stages.passed = last.every((r) => r.paused === false && !r.err) && last[1].t > last[0].t;
+  if (shotFile) { await wp.screenshot({ path: shotFile }); stages.shot = shotFile; }
+  stages.watchUrl = wp.url();
+  await sp.close().catch(() => {});
+  out({ ok: stages.passed, sessionId: session.id, ...stages });
+} else {
+  die('unknown command: ' + cmd + ' (see header usage)');
+}
+await browser.close().catch(() => {});
+process.exit(0);

package/bin/dsi.mjs

@@ -5,8 +5,11 @@
 // relative to this file, not the cwd, so a globally installed or npx-run
 // package serves its own bundled build from any directory.
 // `--zai` (on `dsi web` / `dsi dsh --sync`) bootstraps a fresh DSH install:
-// it adds the ZAI provider and the default model to ~/.dsh/settings.yaml
-// (idempotent — existing entries win). The standalone `dsi zai` command was
+// it adds the ZAI provider and the default model as patch entries in the
+// active profile's ~/.dsh/profiles/<profile>/cordis.patch.yml — the file the
+// host composes entry config from (idempotent — existing entries win). The
+// legacy flat ~/.dsh/settings.yaml is DSH's import-tombstoned past; the
+// standalone `dsi zai` command was
 // decommissioned — the flag does the same work before anything boots.
 // `dsi dsh --token <token>` copies a dsh launch token into DSI's config
 // ($DSI_CONFIG_PATH or ~/.dsi/settings.yaml, key dsh.authToken — the same
@@ -30,6 +33,7 @@ import { parse, stringify } from 'yaml';
 import { mirrorSkills } from './lib/mirror-skills.mjs';
 import { dshLauncherCmd, parsePluginArgs, takeoverFloorPorts, hostBounceDecision, floorUiPort, parseDevFloorPids, launchUrl, tokenFromSettings } from './lib/plugin-chain.mjs';
 import { parseDevArg, devModeEnv, modeFromBoolean, resolveBounceMode, extractInspectArgs, parseInspectArgsFromEnv } from './lib/dev-mode.mjs';
+import { addZaiProvider as addZaiPatch, zaiPatchPath } from './lib/zai-patch.mjs';
 
 // Layman-facing help: wrapped near 76 columns, continuation lines indented,
 // the recommended one-liner first. --zai is optional on purpose — no GLM
@@ -47,7 +51,8 @@ const USAGE = [
 	'',
 	'      --sync   sync the one-time launch token into ~/.dsi/settings.yaml,',
 	'               then serve host + page as one pair',
-	'      --zai    bootstrap the GLM (Z.AI) provider into ~/.dsh/settings.yaml',
+	'      --zai    bootstrap the GLM (Z.AI) provider into the active profile',
+	'               ~/.dsh/profiles/<profile>/cordis.patch.yml',
 	'               before anything boots. No GLM account? Skip it — drop this',
 	'               flag and keep whatever provider you already configured:',
 	'',
@@ -122,37 +127,6 @@ const OV_PLUGIN = '@openviking/dsh-memory-plugin';
 
 // ── dsi zai ────────────────────────────────────────────────────────────────
 
-/** The ZAI provider block, byte-for-byte the fresh-install shape. */
-const ZAI_PROVIDER = {
-	apiKeyEnv: 'ZAI_API_KEY',
-	api: 'openai-completions',
-	baseURL: 'https://api.z.ai/api/coding/paas/v4',
-	compat: { thinkingFormat: 'zai' },
-	models: [
-		{ id: 'glm-4.7' },
-		{ id: 'glm-5-turbo' },
-		{ id: 'glm-5.1' },
-		{ id: 'glm-5.2' },
-		{
-			id: 'glm-5.3',
-			name: 'GLM-5.3',
-			contextWindow: 1_000_000,
-			maxTokens: 131_072,
-			input: ['text']
-		},
-		{
-			id: 'glm-5.3-flash',
-			name: 'GLM-5.3-Flash',
-			contextWindow: 1_000_000,
-			maxTokens: 131_072,
-			input: ['text', 'image']
-		}
-	]
-};
-
-/** The default-model block a fresh ZAI install wants. */
-const ZAI_DEFAULT_MODEL = { provider: 'zai', model: 'glm-5.3-flash' };
-
 function isRecord(value) {
 	return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -635,50 +609,25 @@ function readFloorEnv(pid) {
 	}
 }
 
-/** Add the ZAI provider and default model to ~/.dsh/settings.yaml when
- *  absent. Existing entries always win — an already-configured host is
- *  rewritten only when at least one block was added. Exits non-zero when
- *  the settings file exists but is not parseable YAML. */
+/** Add the ZAI provider and default model as patch entries in the active
+ *  profile's cordis.patch.yml (bin/lib/zai-patch.mjs, ADR D7-D10). Existing
+ *  entries always win — an already-configured profile is untouched. Exits 65
+ *  when the patch file exists but is not a parseable patch array. */
 function addZaiProvider() {
-	const settingsPath =
-		process.env.DSH_SETTINGS_PATH ?? path.join(homedir(), '.dsh', 'settings.yaml');
-
-	let doc = {};
-	if (existsSync(settingsPath)) {
-		try {
-			const parsed = parse(readFileSync(settingsPath, 'utf-8'));
-			if (!isRecord(parsed)) throw new Error('not a YAML mapping');
-			doc = parsed;
-		} catch (error) {
-			console.error(`dsi zai: cannot parse ${settingsPath}: ${error?.message ?? error}`);
-			process.exit(65);
-		}
-	}
-
-	const added = [];
-	if (!isRecord(doc['llm-pi-ai']) || !isRecord(doc['llm-pi-ai'].providers)) {
-		doc['llm-pi-ai'] = { providers: {} };
-	}
-	if (!isRecord(doc['llm-pi-ai'].providers.zai)) {
-		doc['llm-pi-ai'].providers.zai = ZAI_PROVIDER;
-		added.push('llm-pi-ai.providers.zai');
-	}
-	if (doc['agent-default-model'] === undefined) {
-		doc['agent-default-model'] = ZAI_DEFAULT_MODEL;
-		added.push('agent-default-model');
+	const target = zaiPatchPath();
+	let result;
+	try {
+		result = addZaiPatch(target);
+	} catch (error) {
+		console.error(`dsi zai: ${error?.message ?? error}`);
+		process.exit(65);
 	}
-
-	if (added.length === 0) {
-		console.log(`dsi zai: ${settingsPath} already has the ZAI provider — nothing to do`);
+	if (result.added.length === 0) {
+		console.log(`dsi zai: ${target} already has the ZAI provider — nothing to do`);
 		return;
 	}
-
-	mkdirSync(path.dirname(settingsPath), { recursive: true });
-	const temp = `${settingsPath}.${process.pid}.tmp`;
-	writeFileSync(temp, stringify(doc), 'utf-8');
-	renameSync(temp, settingsPath);
-	for (const entry of added) console.log(`dsi zai: added ${entry}`);
-	console.log(`dsi zai: ${settingsPath} updated — set ZAI_API_KEY in the harness env, then restart dsh web`);
+	for (const entry of result.added) console.log(`dsi zai: added ${entry}`);
+	console.log(`dsi zai: ${target} updated — set ZAI_API_KEY in the harness env, then restart dsh web`);
 }
 
 /** Install the OpenViking memory plugin into the active dsh profile by

package/bin/lib/zai-patch.mjs

@@ -0,0 +1,115 @@
+// The --zai bootstrap: add the GLM (Z.AI) provider and the default model to
+// the ACTIVE dsh profile's Cordis patch file (~/.dsh/profiles/<profile>/
+// cordis.patch.yml) — the file the host actually composes entry config from.
+// The legacy flat ~/.dsh/settings.yaml was imported once and tombstoned as
+// settings.yaml.imported by dsh-settings (ADR: The Packaged Insight 2026-09-11,
+// amendment 2026-11-03, D7-D10), so writing it again only bought a re-import
+// round-trip per boot. Idempotent — existing entries always win: only MISSING
+// keys are added, the operator's other patch entries are never touched.
+// Throws ZaiPatchError on an unparsable/non-array patch file; the bin wiring
+// turns that into exit 65 (same fail-loud contract as before).
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { parse, stringify } from 'yaml';
+
+export class ZaiPatchError extends Error {}
+
+export const ZAI_PROVIDER = {
+	providers: {
+		zai: {
+			apiKeyEnv: 'ZAI_API_KEY',
+			api: 'openai-completions',
+			baseURL: 'https://api.z.ai/api/coding/paas/v4',
+			compat: { thinkingFormat: 'zai' },
+			models: [
+				{ id: 'glm-4.7' },
+				{ id: 'glm-5-turbo' },
+				{ id: 'glm-5.1' },
+				{ id: 'glm-5.2' },
+				{
+					id: 'glm-5.3',
+					name: 'GLM-5.3',
+					contextWindow: 1000000,
+					maxTokens: 131072,
+					input: ['text'],
+				},
+				{
+					id: 'glm-5.3-flash',
+					name: 'GLM-5.3-Flash',
+					contextWindow: 1000000,
+					maxTokens: 131072,
+					input: ['text', 'image'],
+				},
+			],
+		},
+	},
+};
+
+export const ZAI_DEFAULT_MODEL = { provider: 'zai', model: 'glm-5.3-flash' };
+
+const LLM_ENTRY_NAME = '@deepseek-ai/dsh-llm-pi-ai';
+const MODEL_ENTRY_NAME = '@deepseek-ai/dsh-agent-default-model';
+
+/** Resolve the patch file the bootstrap writes: DSH_PATCH_PATH override,
+ *  else the active profile's cordis.patch.yml (DSH_PROFILE, default web). */
+export function zaiPatchPath() {
+	if (process.env.DSH_PATCH_PATH !== undefined) return process.env.DSH_PATCH_PATH;
+	const profile = process.env.DSH_PROFILE ?? 'web';
+	return path.join(homedir(), '.dsh', 'profiles', profile, 'cordis.patch.yml');
+}
+
+function isRecord(value) {
+	return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Add the ZAI provider and default model as patch entries when absent.
+ *  Returns { added, path } — added lists the dotted keys newly written.
+ *  @param {string | undefined} target explicit patch path (tests); default zaiPatchPath() */
+export function addZaiProvider(target = zaiPatchPath()) {
+	let entries = [];
+	if (existsSync(target)) {
+		let parsed;
+		try {
+			parsed = parse(readFileSync(target, 'utf-8'));
+		} catch (error) {
+			throw new ZaiPatchError(`cannot parse ${target}: ${error?.message ?? error}`);
+		}
+		if (!Array.isArray(parsed) || parsed.some((row) => !isRecord(row))) {
+			throw new ZaiPatchError(`${target} is not a Cordis patch array of entries`);
+		}
+		entries = parsed;
+	}
+
+	const added = [];
+
+	// llm-pi-ai — create the entry when absent, merge zai when its provider map lacks it.
+	let llm = entries.find((row) => row.id === 'llm-pi-ai');
+	if (!isRecord(llm)) {
+		llm = { id: 'llm-pi-ai', name: LLM_ENTRY_NAME, config: {} };
+		entries.push(llm);
+	}
+	if (!isRecord(llm.config)) llm.config = {};
+	if (!isRecord(llm.config.providers)) llm.config.providers = {};
+	if (!isRecord(llm.config.providers.zai)) {
+		llm.config.providers.zai = ZAI_PROVIDER.providers.zai;
+		added.push('llm-pi-ai.providers.zai');
+	}
+
+	// agent-default-model — the entry IS the setting; absent means unset.
+	if (!entries.some((row) => row.id === 'agent-default-model')) {
+		entries.push({ id: 'agent-default-model', name: MODEL_ENTRY_NAME, config: ZAI_DEFAULT_MODEL });
+		added.push('agent-default-model');
+	}
+
+	if (added.length === 0) {
+		return { added, path: target };
+	}
+
+	mkdirSync(path.dirname(target), { recursive: true });
+	const temp = `${target}.${process.pid}.tmp`;
+	writeFileSync(temp, stringify(entries), 'utf-8');
+	renameSync(temp, target);
+	return { added, path: target };
+}