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

package/src/runtime/advice/config.ts

@@ -0,0 +1,189 @@
+'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 { resolveRoots } = require('../storage/roots.ts');
+
+const SETTING_FILE = 'decision-model.json';
+const PROJECT_NOTE = 'a project cannot enable the decision model or choose its endpoint';
+const KNOWN_KEYS = new Set(['schema', 'enabled', 'provider', 'endpoint', 'model']);
+
+function isObject(value: any): boolean {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function offResult(reason: string, decidedBy: any, notes: string[] = [], setting: any = {}): any {
+  return {
+    state: 'off', reason,
+    provider: setting.provider ?? null,
+    endpoint: setting.endpoint ?? null,
+    model: setting.model ?? null,
+    decidedBy,
+    modelFrom: setting.model ? setting.modelFrom ?? null : null,
+    notes,
+  };
+}
+
+function readJson(file: string | null, fsImpl: any): { exists: boolean; value?: any; error?: any } {
+  if (!file) return { exists: false };
+  try {
+    return { exists: true, value: JSON.parse(fsImpl.readFileSync(file, 'utf8')) };
+  } catch (error: any) {
+    if (error?.code === 'ENOENT') return { exists: false };
+    return { exists: true, error };
+  }
+}
+
+function parseUserSetting(value: any, adviceRegistry: any): any {
+  if (!isObject(value)) return { error: 'user setting must be a JSON object' };
+  if (value.schema !== 1) return { error: 'user setting schema must be 1' };
+  if (typeof value.enabled !== 'boolean') return { error: 'user setting enabled must be a boolean' };
+
+  const providers = Array.isArray(adviceRegistry?.providers) ? adviceRegistry.providers : [];
+  const providerId = value.provider === undefined ? 'ollama' : value.provider;
+  const provider = providers.find((item: any) => item?.id === providerId);
+  if (typeof providerId !== 'string' || !provider) return { error: `user setting provider '${providerId}' is not in advice.json providers` };
+
+  let endpoint = provider.defaultEndpoint;
+  if (value.endpoint !== undefined) {
+    if (typeof value.endpoint !== 'string' || !value.endpoint.trim()) return { error: 'user setting endpoint must be a URL string' };
+    try { new URL(value.endpoint); } catch { return { error: 'user setting endpoint must be a URL string' }; }
+    endpoint = value.endpoint;
+  }
+  if (typeof endpoint !== 'string' || !endpoint) return { error: `providers.${providerId}.defaultEndpoint is missing` };
+
+  if (value.model !== undefined && (typeof value.model !== 'string' || !value.model.trim())) {
+    return { error: 'user setting model must be a non-empty string' };
+  }
+  if (value.enabled && (typeof value.model !== 'string' || !value.model.trim())) {
+    return { error: 'user setting model is required when enabled is true' };
+  }
+
+  const notes = Object.keys(value)
+    .filter((key) => !KNOWN_KEYS.has(key))
+    .map((key) => `unknown user key '${key}' ignored`);
+  return {
+    value: { enabled: value.enabled, provider: providerId, endpoint, model: value.model ?? null },
+    notes,
+  };
+}
+
+function parseProjectSetting(value: any): any {
+  if (!isObject(value)) return { error: 'project setting must be a JSON object' };
+  if (value.schema !== 1) return { error: 'project setting schema must be 1' };
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') return { error: 'project setting enabled must be a boolean' };
+  if (value.model !== undefined && (typeof value.model !== 'string' || !value.model.trim())) return { error: 'project setting model must be a non-empty string' };
+
+  const notes: string[] = [];
+  if (value.enabled === true) notes.push(`project key 'enabled' ignored: ${PROJECT_NOTE}`);
+  for (const key of ['endpoint', 'provider']) {
+    if (Object.hasOwn(value, key)) notes.push(`project key '${key}' ignored: ${PROJECT_NOTE}`);
+  }
+  for (const key of Object.keys(value)) {
+    if (!['schema', 'enabled', 'model', 'endpoint', 'provider'].includes(key)) notes.push(`unknown project key '${key}' ignored`);
+  }
+  return { value: { disabled: value.enabled === false, model: value.model ?? null }, notes };
+}
+
+function resolveSetting({
+  adviceRegistry,
+  roots,
+  storageRegistry,
+  projectRoot,
+  global = false,
+  env = process.env,
+  fsImpl = fs,
+}: any = {}): any {
+  const notes: string[] = [];
+  let resolvedRoots = roots;
+  try {
+    if (!resolvedRoots) resolvedRoots = resolveRoots({ registry: storageRegistry, projectRoot, global, env });
+  } catch (error: any) {
+    return offResult('config-invalid', { user: null, project: null }, [`storage roots could not be resolved: ${error.message}`]);
+  }
+  const userFile = resolvedRoots?.['config-home'] ? path.join(resolvedRoots['config-home'], SETTING_FILE) : null;
+  const projectFile = resolvedRoots?.['project-doflow'] ? path.join(resolvedRoots['project-doflow'], SETTING_FILE) : null;
+  const decidedBy = { user: null, project: null };
+  const userRead = readJson(userFile, fsImpl);
+  if (!userRead.exists) return offResult('not-configured', decidedBy, notes);
+  if (userRead.error) {
+    return offResult('config-invalid', { user: userFile, project: null }, [`user setting at ${userFile} could not be read: ${userRead.error.message}`]);
+  }
+  const user = parseUserSetting(userRead.value, adviceRegistry);
+  if (user.error) return offResult('config-invalid', { user: userFile, project: null }, [`${user.error} (${userFile})`]);
+  decidedBy.user = userFile;
+  notes.push(...user.notes);
+
+  const base = { ...user.value, modelFrom: user.value.model ? 'user' : null };
+  if (!user.value.enabled) return offResult('user-disabled', decidedBy, notes, base);
+
+  const projectRead = readJson(projectFile, fsImpl);
+  if (projectRead.exists) {
+    if (projectRead.error) {
+      notes.push(`project setting at ${projectFile} ignored: ${projectRead.error.message}`);
+    } else {
+      const project = parseProjectSetting(projectRead.value);
+      if (project.error) {
+        notes.push(`project setting at ${projectFile} ignored: ${project.error}`);
+      } else {
+        notes.push(...project.notes);
+        if (project.value.disabled) {
+          decidedBy.project = projectFile;
+          return offResult('project-disabled', decidedBy, notes, base);
+        }
+        if (project.value.model) {
+          decidedBy.project = projectFile;
+          return {
+            state: 'on', reason: null, provider: base.provider, endpoint: base.endpoint,
+            model: project.value.model, decidedBy, modelFrom: 'project', notes,
+          };
+        }
+      }
+    }
+  }
+  return {
+    state: 'on', reason: null, provider: base.provider, endpoint: base.endpoint,
+    model: base.model, decidedBy, modelFrom: base.modelFrom, notes,
+  };
+}
+
+function writeSetting({ file, setting, level = 'user', force = false, fsImpl = fs }: any = {}): any {
+  if (typeof file !== 'string' || !file || !isObject(setting)) {
+    return { ok: false, reason: 'config-invalid', detail: 'file and setting object are required' };
+  }
+  const directory = path.dirname(file);
+  let existing: any = {};
+  try {
+    if (fsImpl.existsSync(file)) {
+      try {
+        const parsed = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+        if (!isObject(parsed)) throw new Error('setting must be a JSON object');
+        existing = parsed;
+      } catch (error: any) {
+        if (!force) return { ok: false, reason: 'config-invalid', detail: `${file}: ${error.message}` };
+      }
+    }
+
+    const preserved = Object.fromEntries(Object.entries(existing).filter(([key]) => !KNOWN_KEYS.has(key)));
+    const retainedUserFields = level === 'user' && setting.enabled === false
+      ? Object.fromEntries(['provider', 'endpoint', 'model'].filter((key) => existing[key] !== undefined).map((key) => [key, existing[key]]))
+      : {};
+    const output = { ...preserved, ...retainedUserFields, ...setting };
+    fsImpl.mkdirSync(directory, { recursive: true });
+    const suffix = `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    const temporary = path.join(directory, `.${path.basename(file)}.${suffix}.tmp`);
+    try {
+      fsImpl.writeFileSync(temporary, `${JSON.stringify(output, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+      fsImpl.renameSync(temporary, file);
+    } finally {
+      try { if (fsImpl.existsSync(temporary)) fsImpl.unlinkSync(temporary); } catch { /* keep the primary result */ }
+    }
+    return { ok: true, file, setting: output };
+  } catch (error: any) {
+    return { ok: false, reason: 'config-invalid', detail: `${file}: ${error.message}` };
+  }
+}
+
+module.exports = { resolveSetting, writeSetting };

package/src/runtime/advice/doctor.ts

@@ -0,0 +1,169 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const { resolveRoots } = require('../storage/roots.ts');
+const { loadStorageRegistry } = require('../storage/registry.ts');
+const { loadAdviceRegistry } = require('./registry.ts');
+const { resolveSetting } = require('./config.ts');
+const { createAdviceClient } = require('./client.ts');
+const { readWindow } = require('./record.ts');
+const { REPO_ROOT } = require('../../helper/repo-root.ts');
+
+const WINDOW_DAYS = 90;
+const DONE_PHRASES: Record<string, string> = Object.freeze({
+  'classify-verdict': 'accepted class',
+  'brief-record': 'tier the brief named',
+  caller: 'value the caller recorded',
+});
+
+function selectedStore(roots: any) {
+  if (roots?.['project-state']) return { id: 'advice-picks-project', root: roots['project-state'] };
+  return { id: 'advice-picks-user', root: roots?.['user-state'] || null };
+}
+
+function latestCall(records: any) {
+  const calls = records.filter(({ record }: any) => record.type === 'pick' || record.type === 'miss');
+  if (!calls.length) return null;
+  const record = calls.reduce((latest: any, entry: any) => !latest || String(entry.record.at).localeCompare(String(latest.record.at)) >= 0
+    ? entry : latest).record;
+  return record.type === 'pick'
+    ? { at: record.at, status: 'answered', reason: null }
+    : { at: record.at, status: 'unavailable', reason: record.reason || null };
+}
+
+function agreementRows(registry: any, records: any) {
+  const picks = records.filter(({ record }: any) => record.type === 'pick');
+  const outcomes = new Map();
+  for (const { record } of records) {
+    if (record.type !== 'outcome' || typeof record.pickId !== 'string') continue;
+    const current = outcomes.get(record.pickId);
+    if (!current || String(record.at).localeCompare(String(current.at)) >= 0) outcomes.set(record.pickId, record);
+  }
+  const misses = records.filter(({ record }: any) => record.type === 'miss');
+  const ids = [...(registry.kinds || []).map((kind: any) => kind.id)];
+  if (picks.some(({ record }: any) => record.kind === 'adhoc')) ids.push('adhoc');
+  return ids.map((kind) => {
+    const kindPicks = picks.filter(({ record }: any) => record.kind === kind);
+    const completed = kindPicks.map(({ record }: any) => ({ pick: record.pick, outcome: outcomes.get(record.pickId) }))
+      .filter(({ outcome }: any) => outcome);
+    const sources = [...new Set(completed.map(({ outcome }: any) => outcome.source).filter((source: any) => DONE_PHRASES[source]))];
+    return {
+      kind,
+      picks: kindPicks.length,
+      withOutcome: completed.length,
+      matched: completed.filter(({ pick, outcome }: any) => outcome.actual === pick).length,
+      unavailable: misses.filter(({ record }: any) => record.kind === kind).length,
+      outcomeSources: sources,
+    };
+  });
+}
+
+function offReason(setting: any) {
+  if (setting.reason === 'not-configured') return 'not configured';
+  if (setting.reason === 'config-invalid') return `unreadable setting in ${setting.decidedBy?.user || setting.decidedBy?.project || 'decision-model.json'}`;
+  if (setting.reason === 'project-disabled') return `switched off in ${setting.decidedBy?.project}`;
+  return `switched off in ${setting.decidedBy?.user || 'decision-model.json'}`;
+}
+
+async function buildAdviceDoctor({ repoRoot = REPO_ROOT, projectRoot = process.cwd(), env = process.env, fsImpl = fs,
+  adviceRegistry: suppliedRegistry, storageRegistry: suppliedStorage, client: suppliedClient, lookup, httpModule, httpsModule,
+  probeTimeoutMs, doctorBudgetMs, now = () => new Date() }: any = {}) {
+  try {
+    const root = repoRoot;
+    const loaded = suppliedRegistry ? { ok: true, registry: suppliedRegistry } : loadAdviceRegistry({ repoRoot: root, fsImpl });
+    const registry = loaded.registry;
+    const storage = suppliedStorage || loadStorageRegistry({ repoRoot: root, fsImpl });
+    const roots = resolveRoots({ registry: storage, projectRoot, env });
+    const setting = loaded.ok ? resolveSetting({ adviceRegistry: registry, roots, fsImpl }) : {
+      state: 'off', reason: 'config-invalid', decidedBy: { user: null, project: null }, modelFrom: null, notes: [loaded.detail],
+    };
+    const store = selectedStore(roots);
+    const selectedRoots = store.id === 'advice-picks-project'
+      ? { 'project-state': store.root }
+      : { 'user-state': store.root };
+    const window = readWindow({ roots: selectedRoots, now, fsImpl, maxAgeDays: WINDOW_DAYS });
+    const advice = {
+      windowDays: WINDOW_DAYS,
+      store: store.id,
+      kinds: agreementRows(registry || { kinds: [] }, window.records),
+      unreadableLines: window.unreadable,
+    };
+    let decisionModel;
+    let inspection = null;
+    if (setting.state === 'on' && loaded.ok) {
+      const effectiveRegistry = { ...registry, probeTimeoutMs: probeTimeoutMs ?? registry.probeTimeoutMs,
+        doctorBudgetMs: doctorBudgetMs ?? registry.doctorBudgetMs };
+      const client = suppliedClient || createAdviceClient({ adviceRegistry: effectiveRegistry, roots, fsImpl, lookup, httpModule, httpsModule });
+      inspection = await client.inspect({ endpoint: setting.endpoint, model: setting.model, provider: setting.provider,
+        file: setting.decidedBy?.user, minVersion: registry.providers.find((p: any) => p.id === setting.provider)?.minVersion,
+        timeoutMs: probeTimeoutMs ?? registry.probeTimeoutMs });
+      const provider = registry.providers.find((p: any) => p.id === setting.provider) || {};
+      decisionModel = {
+        setting: { state: 'on', reason: null, decidedBy: setting.decidedBy, modelFrom: setting.modelFrom, notes: setting.notes || [] },
+        endpoint: { url: setting.endpoint, state: inspection.endpoint.state, version: inspection.endpoint.version,
+          minVersion: provider.minVersion || null, versionOk: inspection.endpoint.versionOk, message: inspection.endpoint.message },
+        model: { name: setting.model, installed: inspection.model.installed, decisionCapable: inspection.model.decisionCapable },
+        decisionModels: inspection.models.filter((model: any) => model.capabilities?.includes(provider.capability)).map((model: any) => model.name),
+        lastCall: latestCall(window.records),
+      };
+    } else {
+      decisionModel = {
+        setting: { state: 'off', reason: setting.reason, decidedBy: setting.decidedBy || { user: null, project: null }, modelFrom: setting.modelFrom || null, notes: setting.notes || [] },
+        endpoint: { url: setting.endpoint || null, state: 'not-checked', version: null, minVersion: registry?.providers?.[0]?.minVersion || null, versionOk: false, message: null },
+        model: { name: setting.model || null, installed: false, decisionCapable: false },
+        decisionModels: [], lastCall: latestCall(window.records),
+      };
+    }
+    return { decisionModel, advice, _inspection: inspection, _offReason: setting.state === 'off' ? offReason(setting) : null };
+  } catch (error: any) {
+    return { decisionModel: { setting: { state: 'off', reason: 'config-invalid', decidedBy: { user: null, project: null }, modelFrom: null, notes: [error.message] },
+      endpoint: { url: null, state: 'not-checked', version: null, minVersion: null, versionOk: false, message: null },
+      model: { name: null, installed: false, decisionCapable: false }, decisionModels: [], lastCall: null },
+      advice: { windowDays: WINDOW_DAYS, store: 'advice-picks-user', kinds: [], unreadableLines: 0 }, _inspection: null, _offReason: 'unreadable setting in decision-model.json' };
+  }
+}
+
+function printAdviceDoctor(report: any) {
+  const decision = report.decisionModel;
+  const inspection = report._inspection;
+  console.log('\n[Decision Model] — advisory, never blocking');
+  if (decision.setting.state === 'off') {
+    console.log(`  off (${report._offReason}). To turn it on: doflow advise --action configure --model <a decision-capable model>`);
+    console.log('  or write ~/.config/doflow/decision-model.json:');
+    console.log('  {"schema": 1, "enabled": true, "endpoint": "http://127.0.0.1:11434", "model": "<a decision-capable model>"}');
+  } else {
+    const setting = decision.setting;
+    console.log(`  setting       on (${setting.decidedBy.user || 'user setting'}${setting.modelFrom === 'project' ? `; model from ${setting.decidedBy.project}` : ''})`);
+    const endpoint = decision.endpoint;
+    if (endpoint.state === 'refused') console.log(`  endpoint      ${endpoint.url}  ✗ REFUSED  ${endpoint.message || inspection?.endpoint.message || 'endpoint refused'}`);
+    else if (endpoint.state === 'unreachable') console.log(`  endpoint      ${endpoint.url}  ○ UNREACHABLE  start Ollama yourself; DoFlow does not start it`);
+    else if (endpoint.version && !endpoint.versionOk) console.log(`  endpoint      ${endpoint.url}  ▲ Ollama ${endpoint.version} is older than ${endpoint.minVersion}`);
+    else if (endpoint.state === 'reached') console.log(`  endpoint      ${endpoint.url}  ✓ REACHED  Ollama ${endpoint.version || 'version unknown'}`);
+    else console.log(`  endpoint      ${endpoint.url}  ○ UNREACHABLE  start Ollama yourself; DoFlow does not start it`);
+    const model = decision.model;
+    if (!model.installed) console.log(`  model         ${model.name}  ✗ not installed; run 'ollama pull ${model.name}' yourself; DoFlow does not download models`);
+    else if (!model.decisionCapable) console.log(`  model         ${model.name}  ✗ installed, not decision-capable`);
+    else console.log(`  model         ${model.name}  ✓ installed, decision-capable`);
+    console.log(`  decision-capable here: ${decision.decisionModels.length ? decision.decisionModels.join(', ') : 'none'}`);
+    for (const model of inspection?.models || []) {
+      if (!Array.isArray(model.capabilities)) console.log(`  ${model.name}  capability unknown`);
+    }
+    if (!decision.lastCall) console.log('  last call     none recorded');
+    else if (decision.lastCall.status === 'unavailable') console.log(`  last call     unavailable (${decision.lastCall.reason}) ${decision.lastCall.at}`);
+    else console.log(`  last call     answered ${decision.lastCall.at}`);
+  }
+
+  console.log('\n[Advice Agreement] — picks kept for 90 days in this project; agreement with what was done, not correctness');
+  if (!report.advice.kinds.some((row: any) => row.picks) && !report.advice.unreadableLines) console.log('  No picks recorded here.');
+  for (const row of report.advice.kinds) {
+    if (!row.picks) { console.log(`  ${row.kind.padEnd(17)}no picks recorded`); continue; }
+    const phrases = row.outcomeSources.map((source: any) => DONE_PHRASES[source]).filter(Boolean);
+    const done = phrases.length ? ` (done = ${phrases.join(' or ')})` : '';
+    console.log(`  ${row.kind.padEnd(17)}${row.picks} picks, ${row.withOutcome} with a known outcome, matched ${row.matched} of ${row.withOutcome}${done}; ${row.unavailable} calls unavailable`);
+  }
+  if (report.advice.unreadableLines) console.log(`  ${report.advice.unreadableLines} line(s) could not be read`);
+}
+
+module.exports = { buildAdviceDoctor, printAdviceDoctor };

package/src/runtime/advice/endpoint-guard.ts

@@ -0,0 +1,134 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const dns = require('node:dns');
+
+function displayEndpoint(value: any): string {
+  return typeof value === 'string' ? value : String(value ?? '');
+}
+
+function ipv4Octets(address: any): number[] | null {
+  if (typeof address !== 'string' || !/^\d{1,3}(?:\.\d{1,3}){3}$/.test(address)) return null;
+  const octets = address.split('.').map(Number);
+  return octets.every((octet) => octet >= 0 && octet <= 255) ? octets : null;
+}
+
+function ipv6Words(address: any): number[] | null {
+  if (typeof address !== 'string' || !address.includes(':')) return null;
+  let value = address.toLowerCase();
+  if (value.includes('.')) {
+    const lastColon = value.lastIndexOf(':');
+    const octets = ipv4Octets(value.slice(lastColon + 1));
+    if (!octets) return null;
+    const high = ((octets[0] << 8) | octets[1]).toString(16);
+    const low = ((octets[2] << 8) | octets[3]).toString(16);
+    value = `${value.slice(0, lastColon + 1)}${high}:${low}`;
+  }
+  const doubleColon = value.indexOf('::');
+  if (doubleColon !== -1 && value.indexOf('::', doubleColon + 2) !== -1) return null;
+  let words: string[];
+  if (doubleColon === -1) {
+    words = value.split(':');
+    if (words.length !== 8) return null;
+  } else {
+    const left = value.slice(0, doubleColon) ? value.slice(0, doubleColon).split(':') : [];
+    const right = value.slice(doubleColon + 2) ? value.slice(doubleColon + 2).split(':') : [];
+    const zeros = 8 - left.length - right.length;
+    if (zeros < 1) return null;
+    words = [...left, ...Array(zeros).fill('0'), ...right];
+  }
+  if (words.length !== 8 || words.some((word) => !/^[0-9a-f]{1,4}$/.test(word))) return null;
+  return words.map((word) => Number.parseInt(word, 16));
+}
+
+function isLoopback(address: any): boolean {
+  const octets = ipv4Octets(address);
+  if (octets) return octets[0] === 127;
+  const words = ipv6Words(address);
+  if (!words) return false;
+  if (words.slice(0, 7).every((word) => word === 0) && words[7] === 1) return true;
+  const mapped = words.slice(0, 5).every((word) => word === 0) && words[5] === 0xffff;
+  if (!mapped) return false;
+  return (words[6] >> 8) === 127;
+}
+
+function literalFamily(address: any): 4 | 6 {
+  return ipv4Octets(address) ? 4 : 6;
+}
+
+function isLiteralIp(host: any): boolean {
+  return Boolean(ipv4Octets(host) || ipv6Words(host));
+}
+
+function refuse(value: any, file?: string): { ok: false; message: string } {
+  return {
+    ok: false,
+    message: `decision model: endpoint ${value} refused: only loopback addresses are allowed (127.0.0.0/8, ::1); set in ${file || 'provider default'}`,
+  };
+}
+
+function lookupAll(host: string, lookup: any, timeoutMs?: number): Promise<any> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (error: any, addresses?: any) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) reject(error);
+      else resolve(addresses);
+    };
+    const timer = Number.isFinite(timeoutMs) ? setTimeout(() => {
+      finish(Object.assign(new Error('decision model DNS validation timed out'), { code: 'ADVICE_TIMEOUT' }));
+    }, Math.max(0, timeoutMs as number)) : undefined;
+    try {
+      const returned = lookup(host, { all: true, verbatim: true }, finish);
+      if (returned && typeof returned.then === 'function') returned.then((addresses: any) => finish(null, addresses), finish);
+      else if (Array.isArray(returned)) finish(null, returned);
+    } catch (error) {
+      finish(error);
+    }
+  });
+}
+
+function pinnedLookup(address: string, family: number) {
+  return (hostname: string, options: any, callback?: any) => {
+    if (typeof options === 'function') {
+      callback = options;
+      options = {};
+    }
+    if (typeof callback !== 'function') throw new TypeError('lookup callback is required');
+    if (options?.all) callback(null, [{ address, family }]);
+    else callback(null, address, family);
+  };
+}
+
+async function checkEndpoint(value: any, { lookup = dns.lookup, file, timeoutMs }: any = {}): Promise<any> {
+  const display = displayEndpoint(value);
+  let url: any;
+  try { url = new URL(display); } catch { return refuse(display, file); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) return refuse(display, file);
+
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  if (isLiteralIp(host)) {
+    if (!isLoopback(host)) return refuse(display, file);
+    const family = literalFamily(host);
+    return { ok: true, address: host, family, pinnedLookup: pinnedLookup(host, family) };
+  }
+
+  let addresses: any;
+  try { addresses = await lookupAll(host, lookup, timeoutMs); } catch (error: any) {
+    if (error?.code === 'ADVICE_TIMEOUT') return { ok: false, reason: 'timeout', message: error.message };
+    return refuse(display, file);
+  }
+  if (!Array.isArray(addresses) || addresses.length === 0) return refuse(display, file);
+  const checked: any[] = addresses.map((entry: any) => {
+    if (!entry || typeof entry.address !== 'string') return null;
+    return { address: entry.address, family: literalFamily(entry.address) };
+  });
+  if (checked.some((entry: any) => !entry || !isLoopback(entry.address))) return refuse(display, file);
+  const first = checked[0];
+  return { ok: true, address: first.address, family: first.family, pinnedLookup: pinnedLookup(first.address, first.family) };
+}
+
+module.exports = { checkEndpoint };

package/src/runtime/advice/kinds.ts

@@ -0,0 +1,154 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+function isObject(value: any): boolean {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function invalid(detail: string, reason: string = 'config-invalid'): { ok: false; reason: string; detail: string } {
+  return { ok: false, reason, detail };
+}
+
+function optionCount(question: any): number {
+  if (question.type === 'score') return Array.isArray(question.criteria) ? question.criteria.length : 0;
+  return question.type === 'choice' ? Object.keys(question.options || {}).length : 2;
+}
+
+function checkOptionRange(count: number, limits: any, owner: string): { ok: false; reason: string; detail: string } | null {
+  if (!Number.isInteger(limits?.minOptions) || !Number.isInteger(limits?.maxOptions)) {
+    return invalid(`${owner} cannot be built: invalid limits in core/registry/advice.json`);
+  }
+  if (count < limits.minOptions) {
+    return invalid(`${owner} has ${count} options; minimum is ${limits.minOptions} (core/registry/advice.json limits.minOptions)`);
+  }
+  if (count > limits.maxOptions) {
+    return invalid(`${owner} has ${count} options; maximum is ${limits.maxOptions} (core/registry/advice.json limits.maxOptions)`);
+  }
+  return null;
+}
+
+function criteriaFrom(source: string, sources: any): Record<string, any> | null {
+  let entries: [string, any][];
+  if (source === 'workflows.classes') {
+    const classes = sources?.workflows?.classes;
+    if (!isObject(classes)) return null;
+    entries = Object.entries(classes).map(([id, item]: [string, any]) => [id, item?.description]);
+  } else if (source === 'verification.riskLevels') {
+    const levels = sources?.verification?.riskLevels;
+    if (!isObject(levels)) return null;
+    entries = Object.entries(levels).map(([id, item]: [string, any]) => [id, item?.description]);
+  } else {
+    return null;
+  }
+  if (entries.some(([, description]) => typeof description !== 'string' || !description.trim())) return null;
+  return Object.fromEntries(entries);
+}
+
+function materializeKind(kindId: string, { adviceRegistry, sources = {}, server }: any = {}): any {
+  const kinds = adviceRegistry?.kinds;
+  if (!Array.isArray(kinds)) return invalid('kinds are missing from core/registry/advice.json');
+  const kind = kinds.find((entry: any) => entry?.id === kindId);
+  if (!kind) return invalid(`unknown kind '${kindId}'`, 'usage-error');
+
+  const serverSource = kind.criteriaFrom === 'mcp.servers[].trigger';
+  if (server !== undefined && !serverSource) return invalid('--server is valid only for mcp-need', 'usage-error');
+
+  let question: any;
+  if (serverSource) {
+    if (typeof server !== 'string' || !server.trim()) return invalid('--server is required for mcp-need', 'usage-error');
+    const servers = sources?.mcp?.servers;
+    if (!Array.isArray(servers)) return invalid('mcp.servers is missing from core/registry/mcp.json');
+    const match = servers.find((entry: any) => entry?.id === server);
+    if (!match) return invalid(`server '${server}' is not present in core/registry/mcp.json`, 'usage-error');
+    if (typeof match.trigger !== 'string' || !match.trigger.trim()) return invalid(`mcp.servers.${server}.trigger is missing`);
+    question = { name: kind.id, type: 'yesno', instructions: match.trigger, no: kind.no, yes: kind.yes };
+  } else if (kind.type === 'choice') {
+    const options = Object.hasOwn(kind, 'criteria') ? kind.criteria : criteriaFrom(kind.criteriaFrom, sources);
+    if (!isObject(options) || Object.values(options).some((value) => typeof value !== 'string' || !value.trim())) {
+      return invalid(`criteria source for kind '${kind.id}' is unavailable or invalid`);
+    }
+    question = { name: kind.id, type: 'choice', instructions: kind.instructions, options };
+  } else if (kind.type === 'yesno') {
+    question = { name: kind.id, type: 'yesno', instructions: kind.instructions, no: kind.no, yes: kind.yes };
+  } else {
+    return invalid(`kind '${kind.id}' has an unsupported type`);
+  }
+
+  const rangeError = checkOptionRange(optionCount(question), adviceRegistry.limits, `kind '${kind.id}'`);
+  if (rangeError) return rangeError;
+  const validation = validateQuestionSet({ state: '', questions: [question] }, { adviceRegistry });
+  if (!validation.ok) return invalid(`kind '${kind.id}': ${validation.detail}`);
+  return { ok: true, kind: kind.id, question };
+}
+
+function validateQuestionSet(questionSet: any, { adviceRegistry }: any = {}): any {
+  const limits = adviceRegistry?.limits;
+  if (!isObject(limits)) return invalid('limits are missing from core/registry/advice.json');
+  if (!isObject(questionSet)) return invalid('question set must be an object (core/registry/advice.json limits.minQuestions)');
+  if (typeof questionSet.state !== 'string') return invalid('question set state must be a string (IC-005)');
+  if (!Array.isArray(questionSet.questions)) return invalid('questions must be an array (core/registry/advice.json limits.minQuestions)');
+  if (questionSet.questions.length < limits.minQuestions) {
+    return invalid(`question count is below ${limits.minQuestions} (core/registry/advice.json limits.minQuestions)`);
+  }
+  if (questionSet.questions.length > limits.maxQuestions) {
+    return invalid(`question count exceeds ${limits.maxQuestions} (core/registry/advice.json limits.maxQuestions)`);
+  }
+
+  let namePattern: RegExp;
+  try { namePattern = new RegExp(limits.questionName); } catch {
+    return invalid('questionName does not compile (core/registry/advice.json limits.questionName)');
+  }
+  const names = new Set();
+  for (const [index, question] of questionSet.questions.entries()) {
+    const prefix = `questions[${index}]`;
+    if (!isObject(question)) return invalid(`${prefix} must be an object (core/registry/advice.json limits.questionName)`);
+    if (typeof question.name !== 'string' || !namePattern.test(question.name)) {
+      return invalid(`${prefix}.name must match ${limits.questionName} (core/registry/advice.json limits.questionName)`);
+    }
+    if (names.has(question.name)) return invalid(`question names must be unique: '${question.name}' (core/registry/advice.json limits.questionName)`);
+    names.add(question.name);
+    if (typeof question.instructions !== 'string' || !question.instructions.trim()) {
+      return invalid(`${prefix}.instructions must be a non-empty string (core/registry/advice.json)`);
+    }
+    if (question.type === 'choice') {
+      if (!isObject(question.options)) return invalid(`${prefix}.options must be an object (core/registry/advice.json limits.minOptions)`);
+      const count = Object.keys(question.options).length;
+      const rangeError = checkOptionRange(count, limits, `${prefix}.options`);
+      if (rangeError) return rangeError;
+      if (Object.values(question.options).some((description) => typeof description !== 'string' || !description.trim())) {
+        return invalid(`${prefix}.options values must be non-empty descriptions (core/registry/advice.json limits.minOptions)`);
+      }
+    } else if (question.type === 'yesno') {
+      if (typeof question.no !== 'string' || !question.no.trim()) return invalid(`${prefix}.no is required (core/registry/advice.json limits.minOptions)`);
+      if (typeof question.yes !== 'string' || !question.yes.trim()) return invalid(`${prefix}.yes is required (core/registry/advice.json limits.minOptions)`);
+      const rangeError = checkOptionRange(2, limits, prefix);
+      if (rangeError) return rangeError;
+    } else if (question.type === 'score') {
+      if (!Array.isArray(question.criteria)) return invalid(`${prefix}.criteria must be an array of criterion strings (core/registry/advice.json limits.minOptions)`);
+      const rangeError = checkOptionRange(question.criteria.length, limits, `${prefix}.criteria`);
+      if (rangeError) return rangeError;
+      if (question.criteria.some((criterion: any) => typeof criterion !== 'string' || !criterion.trim())) {
+        return invalid(`${prefix}.criteria must be non-empty strings (core/registry/advice.json limits.minOptions)`);
+      }
+      if (new Set(question.criteria).size !== question.criteria.length) {
+        return invalid(`${prefix}.criteria must be distinct (core/registry/advice.json limits.minOptions)`);
+      }
+    } else {
+      return invalid(`${prefix}.type must be choice, yesno or score (core/registry/advice.json)`);
+    }
+  }
+  return { ok: true, questionSet };
+}
+
+function validateStaticAnswer(question: any, value: any): { ok: boolean; reason?: string; detail?: string } {
+  if (value === undefined || value === null) return { ok: true };
+  const validOptions = question?.type === 'choice'
+    ? Object.keys(question.options || {})
+    : question?.type === 'yesno' ? ['no', 'yes']
+      : question?.type === 'score' && Array.isArray(question.criteria) ? question.criteria : [];
+  if (validOptions.includes(value)) return { ok: true };
+  return invalid(`static answer must be one of: ${validOptions.join(', ')}`, 'usage-error');
+}
+
+module.exports = { materializeKind, validateQuestionSet, validateStaticAnswer };