@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/src/release/sync-plugin-versions.ts

@@ -0,0 +1,66 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// ── One release version, projected into every distribution manifest ─────────────────────────────
+//
+// package.json is the single source of the release version. The three plugin manifests (Codex,
+// Claude, Copilot) each repeat it, and v1.2.1 shipped with all three still reading 1.2.0 — the
+// guard tests comparing them were failing correctly (architecture review R8). Hand-editing four
+// files in step is exactly the drift class this repo removes elsewhere by generation, so the
+// npm `version` lifecycle hook runs this script: `npm version <bump>` rewrites the manifests and
+// stages them into the same release commit. The equality guards in test/install/doflow.test.js
+// stay as the independent check that the projection actually happened.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../helper/repo-root.ts');
+
+/** Every distribution manifest that repeats the release version, relative to the repo root. */
+const PLUGIN_MANIFESTS = [
+  'core/.codex-plugin/plugin.json',
+  'core/.claude-plugin/plugin.json',
+  'core/.plugin/plugin.json',
+];
+
+/**
+ * Rewrites each plugin manifest's version to package.json's, preserving formatting by targeted
+ * string replacement rather than re-serializing the whole file.
+ * @param {Object} [options]
+ * @param {string} [options.repoRoot]
+ * @param {Object} [options.fsImpl]
+ * @returns {{version: string, updated: Array<string>, unchanged: Array<string>}}
+ */
+function syncPluginVersions({ repoRoot = REPO_ROOT, fsImpl = fs }: { repoRoot?: string, fsImpl?: any } = {}): { version: string, updated: string[], unchanged: string[] } {
+  const pkg = JSON.parse(fsImpl.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  if (typeof pkg.version !== 'string' || pkg.version.trim() === '') {
+    throw new Error('package.json declares no version to project');
+  }
+
+  const updated: string[] = [];
+  const unchanged: string[] = [];
+  for (const rel of PLUGIN_MANIFESTS) {
+    const file = path.join(repoRoot, rel);
+    const text = fsImpl.readFileSync(file, 'utf8');
+    const manifest = JSON.parse(text);
+    if (manifest.version === pkg.version) {
+      unchanged.push(rel);
+      continue;
+    }
+    const next = text.replace(/"version":\s*"[^"]*"/, `"version": "${pkg.version}"`);
+    if (!/"version":\s*"/.test(text)) {
+      throw new Error(`${rel} has no version field to rewrite — the manifest shape changed; update PLUGIN_MANIFESTS`);
+    }
+    fsImpl.writeFileSync(file, next, 'utf8');
+    updated.push(rel);
+  }
+  return { version: pkg.version, updated, unchanged };
+}
+
+if (require.main === module) {
+  const result = syncPluginVersions();
+  for (const rel of result.updated) console.log(`synced ${rel} -> ${result.version}`);
+  if (result.updated.length === 0) console.log(`all plugin manifests already at ${result.version}`);
+}
+
+module.exports = { syncPluginVersions, PLUGIN_MANIFESTS };

package/src/runtime/advice/cli.ts

@@ -0,0 +1,283 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { finishRuntime, usageError } = require('../cli-result.ts');
+const { REPO_ROOT } = require('../../helper/repo-root.ts');
+const { loadAdviceRegistry } = require('./registry.ts');
+const { loadStorageRegistry } = require('../storage/registry.ts');
+const { resolveRoots } = require('../storage/roots.ts');
+const { resolveSetting, writeSetting } = require('./config.ts');
+const { createAdviceClient } = require('./client.ts');
+const { materializeKind, validateQuestionSet, validateStaticAnswer } = require('./kinds.ts');
+const { findPick, appendOutcome } = require('./record.ts');
+const { strengthWords } = require('./strength.ts');
+
+function loadSources(repoRoot: any) {
+  const read = (name: any) => JSON.parse(fs.readFileSync(path.join(repoRoot, 'core/registry', name), 'utf8'));
+  return {
+    workflows: read('workflows.json'),
+    verification: read('verification.json'),
+    mcp: read('mcp.json'),
+  };
+}
+
+function loadRuntime({ projectRoot, global = false }: any = {}) {
+  const advice = loadAdviceRegistry({ repoRoot: REPO_ROOT });
+  const storage = loadStorageRegistry({ repoRoot: REPO_ROOT });
+  const roots = resolveRoots({ registry: storage, projectRoot, global });
+  const sources = loadSources(REPO_ROOT);
+  const adviceRegistry = advice.ok ? advice.registry : null;
+  return { adviceRegistry, adviceError: advice.ok ? null : advice.detail, storage, roots, sources };
+}
+
+function emitResult(result: any, { json, kind }: any) {
+  if (result.reason === 'over-limit') {
+    return usageError('advise', result.detail || 'request exceeds an advice limit', json);
+  }
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.status === 'answered') {
+    for (const answer of result.answers) {
+      const staticText = answer.staticAnswer === null ? '' : ` Static answer: ${answer.staticAnswer}.`;
+      console.log(`Advice (${kind}): ${answer.pick}, ${strengthWords(answer.strength)}.${staticText}`);
+    }
+  } else {
+    console.log(`Advice (${kind}): none; the static answer stands.`);
+  }
+  return finishRuntime(0);
+}
+
+function isPresent(value: any) {
+  return value !== undefined && value !== null;
+}
+
+function readState({ state, stateFile, json }: any) {
+  if (isPresent(state) === isPresent(stateFile)) {
+    usageError('advise', 'provide exactly one of --state or --state-file', json);
+    return null;
+  }
+  if (isPresent(state)) return state;
+  try {
+    const content = fs.readFileSync(stateFile, 'utf8');
+    if (!content.length) throw new Error('file is empty');
+    return content;
+  } catch (error: any) {
+    usageError('advise', `cannot read state file ${stateFile}: ${error.message}`, json);
+    return null;
+  }
+}
+
+function readQuestions(file: any, json: any) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !Array.isArray(parsed.questions)) {
+      throw new Error('expected an object with a questions array');
+    }
+    return parsed.questions;
+  } catch (error: any) {
+    usageError('advise', `cannot read questions file ${file}: ${error.message}`, json);
+    return null;
+  }
+}
+
+function parseAskInput(options: any) {
+  const hasKind = typeof options.kind === 'string' && options.kind.length > 0;
+  const hasQuestionsFile = isPresent(options.questionsFile);
+  if (hasKind === hasQuestionsFile) {
+    usageError('advise', 'provide exactly one of --kind or --questions-file', options.json);
+    return null;
+  }
+  const state = readState({ state: options.state, stateFile: options.stateFile, json: options.json });
+  if (state === null) return null;
+  if (options.server !== undefined && !hasKind) {
+    usageError('advise', '--server is only valid with --kind mcp-need', options.json);
+    return null;
+  }
+  if (options.staticAnswer !== undefined && !hasKind) {
+    usageError('advise', '--static is only valid with a named --kind', options.json);
+    return null;
+  }
+  return { state, hasKind, hasQuestionsFile };
+}
+
+function endpointSource(userSetting: any, endpoint: any) {
+  if (userSetting?.decidedBy?.user) {
+    try {
+      const file = JSON.parse(fs.readFileSync(userSetting.decidedBy.user, 'utf8'));
+      if (file.endpoint === endpoint) return userSetting.decidedBy.user;
+    } catch { /* an invalid file will be reported by its resolver/writer */ }
+  }
+  return 'provider default';
+}
+
+function inspectFailure(inspected: any, { endpoint, model, provider }: any) {
+  if (inspected.endpoint.state === 'refused') return inspected.endpoint.message;
+  if (inspected.endpoint.state !== 'reached') {
+    return `advise: Ollama did not answer at ${endpoint}; start it yourself and re-run. Nothing was written.`;
+  }
+  if (!inspected.endpoint.versionOk) {
+    return `advise: Ollama ${inspected.endpoint.version || 'unknown'} at ${endpoint} is older than ${provider.minVersion}. Nothing was written.`;
+  }
+  if (!inspected.model.installed) {
+    return `advise: model ${model} is not installed; run 'ollama pull ${model}' yourself. Nothing was written.`;
+  }
+  if (!inspected.model.decisionCapable) {
+    const capable = inspected.models
+      .filter((entry: any) => Array.isArray(entry.capabilities) && entry.capabilities.includes(provider.capability))
+      .map((entry: any) => entry.name);
+    return `advise: model ${model} is not decision-capable; decision-capable here: ${capable.length ? capable.join(', ') : 'none'}. Nothing was written.`;
+  }
+  return null;
+}
+
+function writeFailure(message: any, json: any) {
+  if (json) console.log(JSON.stringify({ ok: false, error: 'write-failed', message }, null, 2));
+  else if (message.startsWith('decision model: endpoint ') || message.startsWith('advise:')) console.error(message);
+  else console.error(`advise: ${message}`);
+  return finishRuntime(1);
+}
+
+async function handleConfigure(options: any, runtime: any) {
+  const { adviceRegistry, adviceError, roots, sources } = runtime;
+  const { json, project, global, force } = options;
+  const hasModel = typeof options.model === 'string' && options.model.length > 0;
+  const hasOff = options.off === true;
+  if (hasModel && hasOff) return usageError('advise', 'cannot combine --model and --off', json);
+  if (!hasModel && !hasOff) return usageError('advise', 'provide exactly one of --model or --off', json);
+  if (project && options.endpoint !== undefined) return usageError('advise', '--endpoint cannot be used with --project', json);
+  if (hasOff && options.endpoint !== undefined) return usageError('advise', '--endpoint cannot be used with --off', json);
+  if (project && (global || !options.projectRoot)) return usageError('advise', '--project requires a project root', json);
+  if (adviceError || !adviceRegistry) return writeFailure(`advice registry is invalid: ${adviceError || 'missing registry'}`, json);
+
+  const file = project
+    ? path.join(roots['project-doflow'], 'decision-model.json')
+    : path.join(roots['config-home'], 'decision-model.json');
+  const fsImpl = fs;
+  if (hasOff) {
+    const setting = project ? { schema: 1, enabled: false } : { schema: 1, enabled: false };
+    const written = writeSetting({ file, level: project ? 'project' : 'user', setting, force, fsImpl });
+    if (!written.ok) return writeFailure(written.detail, json);
+    const effective = resolveSetting({ adviceRegistry, roots, fsImpl });
+    if (json) console.log(JSON.stringify({ written: file, setting: effective }, null, 2));
+    else console.log(project ? `Decision model for this project: off (wrote ${file}).` : `Decision model off (wrote ${file}).`);
+    return finishRuntime(0);
+  }
+
+  let userRoots = roots;
+  if (project) userRoots = { ...roots, 'project-doflow': null };
+  const userSetting = resolveSetting({ adviceRegistry, roots: userRoots, fsImpl });
+  if (project && userSetting.state !== 'on') {
+    return writeFailure('turn the decision model on at user level first; a project cannot enable it', json);
+  }
+  const providerId = userSetting.provider || 'ollama';
+  const provider = adviceRegistry.providers.find((entry: any) => entry.id === providerId);
+  if (!provider) return writeFailure(`provider '${providerId}' is not in core/registry/advice.json`, json);
+  const endpoint = project
+    ? userSetting.endpoint
+    : options.endpoint || userSetting.endpoint || provider.defaultEndpoint;
+  const endpointFile = options.endpoint ? '--endpoint' : endpointSource(userSetting, endpoint);
+  const client = createAdviceClient({ adviceRegistry, roots, sources });
+  const inspected = await client.inspect({ endpoint, model: options.model, provider: provider.id, minVersion: provider.minVersion, file: endpointFile });
+  const failure = inspectFailure(inspected, { endpoint, model: options.model, provider });
+  if (failure) return writeFailure(failure, json);
+
+  const setting = project
+    ? { schema: 1, model: options.model }
+    : { schema: 1, enabled: true, provider: provider.id, endpoint, model: options.model };
+  const written = writeSetting({ file, level: project ? 'project' : 'user', setting, force, fsImpl });
+  if (!written.ok) return writeFailure(written.detail, json);
+  const effective = resolveSetting({ adviceRegistry, roots, fsImpl });
+  if (json) console.log(JSON.stringify({ written: file, setting: effective }, null, 2));
+  else console.log(project
+    ? `Decision model for this project: ${options.model} (wrote ${file}).`
+    : `Decision model on: ${options.model} at ${endpoint} (wrote ${file}).`);
+  return finishRuntime(0);
+}
+
+async function handleAsk(options: any, runtime: any) {
+  const parsed = parseAskInput(options);
+  if (!parsed) return finishRuntime(2);
+  const { adviceRegistry, adviceError, roots, sources } = runtime;
+  if (adviceError || !adviceRegistry) {
+    const result = {
+      status: 'off', reason: 'config-invalid', detail: adviceError || 'advice registry is missing',
+      provider: null, model: null, endpoint: null, decidedBy: { user: null, project: null }, durationMs: 0, answers: [],
+    };
+    return emitResult(result, { json: options.json, kind: options.kind || 'adhoc' });
+  }
+
+  let kind = 'adhoc';
+  let questionSet;
+  let questionError = null;
+  if (parsed.hasKind) {
+    kind = options.kind;
+    const built = materializeKind(kind, { adviceRegistry, sources, server: options.server });
+    if (!built.ok && built.reason === 'usage-error') return usageError('advise', built.detail, options.json);
+    if (built.ok) questionSet = { state: parsed.state, questions: [built.question] };
+    else {
+      questionSet = { state: parsed.state, questions: [] };
+      questionError = built.detail;
+    }
+    if (options.staticAnswer !== undefined && built.ok) {
+      const validation = validateStaticAnswer(built.question, options.staticAnswer);
+      if (!validation.ok) return usageError('advise', validation.detail, options.json);
+    }
+  } else {
+    const questions = readQuestions(options.questionsFile, options.json);
+    if (!questions) return finishRuntime(2);
+    questionSet = { state: parsed.state, questions };
+    const validation = validateQuestionSet(questionSet, { adviceRegistry });
+    if (!validation.ok) return usageError('advise', validation.detail, options.json);
+  }
+
+  const client = createAdviceClient({ adviceRegistry, roots, sources });
+  const result = await client.ask({
+    questionSet, kind, staticAnswer: options.staticAnswer, caller: 'advise', taskId: options.taskId,
+    record: true,
+  });
+  // Preserve the kind materialiser's source-specific diagnostic while the client owns miss recording.
+  if (questionError && result.reason === 'config-invalid') result.detail = questionError;
+  return emitResult(result, { json: options.json, kind });
+}
+
+function handleOutcome(options: any, runtime: any) {
+  const { json } = options;
+  if (typeof options.pickId !== 'string' || !options.pickId) return usageError('advise', '--pick-id is required', json);
+  if (typeof options.actual !== 'string' || !options.actual) return usageError('advise', '--actual is required', json);
+  const found = findPick({ pickId: options.pickId, roots: runtime.roots });
+  if (!found) {
+    if (json) console.log(JSON.stringify({ ok: false, error: 'not-found', message: `no pick ${options.pickId} in the retained record` }, null, 2));
+    else console.error(`advise: no pick ${options.pickId} in the retained record`);
+    return finishRuntime(1);
+  }
+  if (!found.pick.options?.includes(options.actual)) {
+    return usageError('advise', `--actual must be one of: ${found.pick.options.join(', ')}`, json);
+  }
+  const written = appendOutcome({
+    pickId: options.pickId, actual: options.actual, source: 'caller', roots: runtime.roots, store: found.store,
+  });
+  if (!written) return writeFailure(`could not record outcome for ${options.pickId}`, json);
+  if (json) console.log(JSON.stringify({ pickId: options.pickId, actual: options.actual, recorded: true, file: written.file }, null, 2));
+  else console.log(`Recorded outcome ${options.actual} for ${options.pickId}.`);
+  return finishRuntime(0);
+}
+
+async function handleAdviseCommand(options: any = {}) {
+  const action = options.actionGiven ? options.action : 'ask';
+  if (!['ask', 'outcome', 'configure'].includes(action)) return usageError('advise', `unknown action '${action}'`, options.json);
+  try {
+    const projectRoot = options.global ? null : path.resolve(options.projectRoot || process.cwd());
+    const runtime = loadRuntime({ projectRoot, global: options.global });
+    const shaped = { ...options, projectRoot };
+    if (action === 'configure') return await handleConfigure(shaped, runtime);
+    if (action === 'outcome') return handleOutcome(shaped, runtime);
+    return await handleAsk(shaped, runtime);
+  } catch (error: any) {
+    return writeFailure(error?.message || 'advice command failed', options.json);
+  }
+}
+
+module.exports = { handleAdviseCommand };

package/src/runtime/advice/client.ts

@@ -0,0 +1,324 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const http = require('node:http');
+const https = require('node:https');
+const { resolveSetting } = require('./config.ts');
+const { checkEndpoint } = require('./endpoint-guard.ts');
+const { strengthOf } = require('./strength.ts');
+const { validateQuestionSet, validateStaticAnswer } = require('./kinds.ts');
+const { appendPick, appendMiss } = require('./record.ts');
+
+// Keep this map literal: module reachability must be auditable without dynamic require paths.
+const ADAPTERS: Record<string, any> = Object.freeze({
+  'ollama-systemone': require('./providers/ollama-systemone.ts'),
+});
+
+function durationSince(startedAt: any) {
+  return Math.max(0, Date.now() - startedAt);
+}
+
+function versionTuple(version: any) {
+  const match = typeof version === 'string' && version.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function versionAtLeast(version: any, minimum: any) {
+  const actual = versionTuple(version);
+  const required = versionTuple(minimum);
+  if (!actual || !required) return false;
+  for (let index = 0; index < 3; index += 1) {
+    if (actual[index] > required[index]) return true;
+    if (actual[index] < required[index]) return false;
+  }
+  return true;
+}
+
+function networkReason(error: any) {
+  return error?.code === 'ADVICE_TIMEOUT' || error?.code === 'ETIMEDOUT' || error?.code === 'ESOCKETTIMEDOUT'
+    ? 'timeout' : 'unreachable';
+}
+
+function requestAction({ endpoint, action, pinnedLookup, timeoutMs, httpModule = http, httpsModule = https }: any) {
+  return new Promise<any>((resolve, reject) => {
+    let request: any;
+    let settled = false;
+    const finish = (error: any, response?: any) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) reject(error);
+      else resolve(response);
+    };
+    const timer = setTimeout(() => {
+      const error: any = new Error(`decision model request timed out after ${timeoutMs}ms`);
+      error.code = 'ADVICE_TIMEOUT';
+      request?.destroy(error);
+      finish(error);
+    }, timeoutMs);
+
+    try {
+      const url = new URL(endpoint);
+      const transport = url.protocol === 'https:' ? httpsModule : httpModule;
+      const prefix = url.pathname.replace(/\/+$/, '');
+      const requestPath = `${prefix}${action.path}` || action.path;
+      const body = action.body === undefined ? undefined : JSON.stringify(action.body);
+      const options = {
+        protocol: url.protocol,
+        hostname: url.hostname.replace(/^\[|\]$/g, ''),
+        port: url.port ? Number(url.port) : undefined,
+        path: requestPath,
+        method: action.method,
+        agent: false,
+        lookup: pinnedLookup,
+        headers: body === undefined ? undefined : {
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(body),
+        },
+      };
+      request = transport.request(options, (response: any) => {
+        const chunks: any[] = [];
+        response.on('data', (chunk: any) => chunks.push(Buffer.from(chunk)));
+        response.on('error', (error: any) => finish(error));
+        response.on('end', () => finish(null, {
+          status: response.statusCode || 0,
+          bodyText: Buffer.concat(chunks).toString('utf8'),
+        }));
+      });
+      request.on('error', (error: any) => finish(error));
+      if (body === undefined) request.end();
+      else request.end(body);
+    } catch (error: any) {
+      finish(error);
+    }
+  });
+}
+
+function emptyAdviceResult(status: any, reason: any, detail: any, setting: any, durationMs: any) {
+  return {
+    status, reason, detail: detail ?? null,
+    provider: setting?.provider ?? null,
+    model: setting?.model ?? null,
+    endpoint: setting?.endpoint ?? null,
+    decidedBy: setting?.decidedBy ?? { user: null, project: null },
+    durationMs,
+    answers: [],
+  };
+}
+
+function createAdviceClient({
+  adviceRegistry,
+  roots,
+  fsImpl = fs,
+  lookup,
+  httpModule = http,
+  httpsModule = https,
+  clock = () => new Date(),
+}: any = {}) {
+  async function ask({ questionSet, kind, staticAnswer, caller, taskId = null, record = true }: any = {}) {
+    const startedAt = Date.now();
+    let setting: any = null;
+    const effectiveKind = typeof kind === 'string' && kind ? kind : 'adhoc';
+    const shouldRecord = record !== false;
+
+    function unavailable(reason: any, detail: any) {
+      const durationMs = durationSince(startedAt);
+      if (shouldRecord && setting?.state === 'on') {
+        try { appendMiss({ roots, now: clock, fsImpl, kind: effectiveKind, caller, reason, model: setting.model, durationMs }); }
+        catch { /* recording failure does not change an AdviceResult */ }
+      }
+      return emptyAdviceResult('unavailable', reason, detail, setting, durationMs);
+    }
+
+    try {
+      setting = resolveSetting({ adviceRegistry, roots, fsImpl });
+      if (setting.state !== 'on') {
+        return emptyAdviceResult('off', setting.reason, setting.notes?.[0] || null, setting, durationSince(startedAt));
+      }
+
+      const provider = adviceRegistry?.providers?.find((entry: any) => entry.id === setting.provider);
+      const adapter = provider && ADAPTERS[provider.adapter];
+      if (!provider || !adapter) return unavailable('config-invalid', `provider adapter '${provider?.adapter || setting.provider}' is unavailable`);
+
+      if (effectiveKind !== 'adhoc') {
+        const namedKind = adviceRegistry.kinds?.find((entry: any) => entry.id === effectiveKind);
+        if (!namedKind || questionSet?.questions?.length !== 1 || questionSet.questions[0]?.name !== effectiveKind) {
+          return unavailable('config-invalid', `question set does not match kind '${effectiveKind}'`);
+        }
+      }
+      const questionValidation = validateQuestionSet(questionSet, { adviceRegistry });
+      if (!questionValidation.ok) return unavailable('config-invalid', questionValidation.detail);
+      if (staticAnswer !== undefined && staticAnswer !== null) {
+        const staticValidation = validateStaticAnswer(questionSet.questions[0], staticAnswer);
+        if (!staticValidation.ok) return unavailable('config-invalid', staticValidation.detail);
+      }
+
+      const stateBytes = Buffer.byteLength(questionSet.state, 'utf8');
+      if (stateBytes > adviceRegistry.limits.maxStateBytes) {
+        return unavailable('over-limit', `state is ${stateBytes} bytes; the limit is ${adviceRegistry.limits.maxStateBytes} (core/registry/advice.json limits.maxStateBytes)`);
+      }
+      const request = adapter.buildRequest(questionSet, { model: setting.model });
+      const bodyText = JSON.stringify(request.body);
+      const bodyBytes = Buffer.byteLength(bodyText, 'utf8');
+      if (bodyBytes > adviceRegistry.limits.maxBodyBytes) {
+        return unavailable('over-limit', `request body is ${bodyBytes} bytes; the limit is ${adviceRegistry.limits.maxBodyBytes} (core/registry/advice.json limits.maxBodyBytes)`);
+      }
+
+      const endpointCheck = await checkEndpoint(setting.endpoint, {
+        lookup,
+        file: setting.decidedBy?.user || 'provider default',
+        timeoutMs: Math.max(0, adviceRegistry.timeoutMs - durationSince(startedAt)),
+      });
+      if (!endpointCheck.ok) return unavailable(endpointCheck.reason || 'non-loopback', endpointCheck.message);
+      const remainingMs = adviceRegistry.timeoutMs - durationSince(startedAt);
+      if (remainingMs <= 0) return unavailable('timeout', 'decision model request budget exhausted');
+
+      let response;
+      try {
+        response = await requestAction({
+          endpoint: setting.endpoint,
+          action: request,
+          pinnedLookup: endpointCheck.pinnedLookup,
+          timeoutMs: remainingMs,
+          httpModule,
+          httpsModule,
+        });
+      } catch (error: any) {
+        const reason = networkReason(error);
+        return unavailable(reason, error.message);
+      }
+
+      let parsed;
+      try { parsed = adapter.parseReply(response.status, response.bodyText, questionSet); }
+      catch (error: any) { return unavailable('malformed-reply', error.message); }
+      if (!parsed?.ok) return unavailable(parsed?.reason || 'malformed-reply', parsed?.detail || 'reply could not be parsed');
+
+      const answers = parsed.answers.map((answer: any, index: any) => {
+        const strength = strengthOf(answer, adviceRegistry.strength);
+        const answerStatic = questionSet.questions.length === 1 ? staticAnswer ?? null : null;
+        const result: any = {
+          name: answer.name,
+          kind: effectiveKind,
+          type: answer.type,
+          pick: answer.pick,
+          strength,
+          probabilities: answer.probabilities,
+          confidence: answer.confidence ?? null,
+          staticAnswer: answerStatic,
+          agrees: answerStatic === null ? null : answer.pick === answerStatic,
+          pickId: null,
+        };
+        if (answer.type === 'score') {
+          result.pickIndex = answer.pickIndex;
+          result.score = answer.score;
+          result.criteria = answer.criteria;
+        }
+        if (shouldRecord) {
+          const written = appendPick({
+            roots, now: clock, fsImpl, kind: effectiveKind,
+            answer: { ...answer, strength },
+            question: questionSet.questions[index],
+            staticAnswer: answerStatic,
+            provider: setting.provider,
+            model: setting.model,
+            state: questionSet.state,
+            caller,
+            taskId,
+            durationMs: durationSince(startedAt),
+          });
+          if (written) result.pickId = written.pickId;
+        }
+        return result;
+      });
+      return {
+        status: 'answered', reason: null, detail: null,
+        provider: setting.provider, model: setting.model, endpoint: setting.endpoint,
+        decidedBy: setting.decidedBy, durationMs: durationSince(startedAt), answers,
+      };
+    } catch (error: any) {
+      return unavailable('config-invalid', error?.message || 'advice request failed');
+    }
+  }
+
+  async function inspect({ endpoint, model, provider: providerId = 'ollama', file, minVersion, timeoutMs }: any = {}) {
+    const unavailable = (state: any, message: any, version: any = null, versionOk = false) => ({
+      endpoint: { state, version, versionOk, message: message ?? null },
+      models: [],
+      model: { installed: false, decisionCapable: false },
+    });
+    try {
+      const provider = adviceRegistry?.providers?.find((entry: any) => entry.id === providerId);
+      const adapter = provider && ADAPTERS[provider.adapter];
+      if (!provider || !adapter) return unavailable('refused', `provider '${providerId}' is unavailable`);
+      const probeLimit = Number.isFinite(timeoutMs) ? timeoutMs : adviceRegistry.probeTimeoutMs;
+      const budgetMs = Number.isFinite(adviceRegistry.doctorBudgetMs) ? adviceRegistry.doctorBudgetMs : probeLimit * 4;
+      const startedAt = Date.now();
+      const remaining = () => Math.max(0, budgetMs - (Date.now() - startedAt));
+      const endpointCheck = await checkEndpoint(endpoint, { lookup, file, timeoutMs: remaining() });
+      if (!endpointCheck.ok) return unavailable(endpointCheck.reason === 'timeout' ? 'unreachable' : 'refused', endpointCheck.message);
+      const requestProbe = (action: any) => {
+        const left = remaining();
+        if (left <= 0) throw Object.assign(new Error('decision model probe budget exhausted'), { code: 'ADVICE_TIMEOUT' });
+        return requestAction({
+          endpoint, action, pinnedLookup: endpointCheck.pinnedLookup,
+          timeoutMs: Math.min(probeLimit, left), httpModule, httpsModule,
+        });
+      };
+
+      let versionResponse;
+      try { versionResponse = await requestProbe(adapter.versionRequest()); }
+      catch (error: any) { return unavailable('unreachable', error.message); }
+      const version = adapter.parseVersion(versionResponse.status, versionResponse.bodyText)?.version ?? null;
+      const minimum = minVersion || provider.minVersion;
+      const versionOk = version ? versionAtLeast(version, minimum) : false;
+      const endpointResult = {
+        state: 'reached',
+        version,
+        versionOk,
+        message: version ? null : `Ollama version endpoint returned HTTP ${versionResponse.status}`,
+      };
+
+      let models = [];
+      try {
+        const listResponse = await requestProbe(adapter.listRequest());
+        models = adapter.parseList(listResponse.status, listResponse.bodyText);
+      } catch {
+        return { endpoint: endpointResult, models, model: { installed: false, decisionCapable: false } };
+      }
+
+      const configuredIndex = models.findIndex((entry: any) => adapter.modelMatches(model, entry.name));
+      const fallbackIndexes = models.map((entry: any, index: any) => index)
+        .filter((index: any) => !Array.isArray(models[index].capabilities));
+      if (configuredIndex >= 0 && fallbackIndexes.includes(configuredIndex)) {
+        fallbackIndexes.splice(fallbackIndexes.indexOf(configuredIndex), 1);
+        fallbackIndexes.unshift(configuredIndex);
+      }
+      for (const index of fallbackIndexes.slice(0, 8)) {
+        try {
+          const showResponse = await requestProbe(adapter.showRequest(models[index].name));
+          const shown = adapter.parseShow(showResponse.status, showResponse.bodyText);
+          if (shown) models[index] = { ...models[index], capabilities: shown.capabilities };
+        } catch {
+          // Keep capabilities unknown when the read-only fallback is unavailable.
+        }
+      }
+      const match = models.find((entry: any) => adapter.modelMatches(model, entry.name));
+      return {
+        endpoint: endpointResult,
+        models,
+        model: {
+          installed: Boolean(match),
+          decisionCapable: Boolean(match?.capabilities?.includes(provider.capability)),
+        },
+      };
+    } catch (error: any) {
+      return unavailable('unreachable', error?.message || 'decision model inspection failed');
+    }
+  }
+
+  return { ask, inspect };
+}
+
+module.exports = { createAdviceClient, versionAtLeast };