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

package/src/runtime/advice/client.js

@@ -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.js');
+const { checkEndpoint } = require('./endpoint-guard.js');
+const { strengthOf } = require('./strength.js');
+const { validateQuestionSet, validateStaticAnswer } = require('./kinds.js');
+const { appendPick, appendMiss } = require('./record.js');
+
+// Keep this map literal: module reachability must be auditable without dynamic require paths.
+const ADAPTERS                      = Object.freeze({
+  'ollama-systemone': require('./providers/ollama-systemone.js'),
+});
+
+function durationSince(startedAt     ) {
+  return Math.max(0, Date.now() - startedAt);
+}
+
+function versionTuple(version     ) {
+  const match = typeof version === 'string' && version.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function versionAtLeast(version     , minimum     ) {
+  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     ) {
+  return error?.code === 'ADVICE_TIMEOUT' || error?.code === 'ETIMEDOUT' || error?.code === 'ESOCKETTIMEDOUT'
+    ? 'timeout' : 'unreachable';
+}
+
+function requestAction({ endpoint, action, pinnedLookup, timeoutMs, httpModule = http, httpsModule = https }     ) {
+  return new Promise     ((resolve, reject) => {
+    let request     ;
+    let settled = false;
+    const finish = (error     , response      ) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) reject(error);
+      else resolve(response);
+    };
+    const timer = setTimeout(() => {
+      const error      = 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     ) => {
+        const chunks        = [];
+        response.on('data', (chunk     ) => chunks.push(Buffer.from(chunk)));
+        response.on('error', (error     ) => finish(error));
+        response.on('end', () => finish(null, {
+          status: response.statusCode || 0,
+          bodyText: Buffer.concat(chunks).toString('utf8'),
+        }));
+      });
+      request.on('error', (error     ) => finish(error));
+      if (body === undefined) request.end();
+      else request.end(body);
+    } catch (error     ) {
+      finish(error);
+    }
+  });
+}
+
+function emptyAdviceResult(status     , reason     , detail     , setting     , durationMs     ) {
+  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(),
+}      = {}) {
+  async function ask({ questionSet, kind, staticAnswer, caller, taskId = null, record = true }      = {}) {
+    const startedAt = Date.now();
+    let setting      = null;
+    const effectiveKind = typeof kind === 'string' && kind ? kind : 'adhoc';
+    const shouldRecord = record !== false;
+
+    function unavailable(reason     , detail     ) {
+      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     ) => 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     ) => 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     ) {
+        const reason = networkReason(error);
+        return unavailable(reason, error.message);
+      }
+
+      let parsed;
+      try { parsed = adapter.parseReply(response.status, response.bodyText, questionSet); }
+      catch (error     ) { 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     , index     ) => {
+        const strength = strengthOf(answer, adviceRegistry.strength);
+        const answerStatic = questionSet.questions.length === 1 ? staticAnswer ?? null : null;
+        const result      = {
+          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     ) {
+      return unavailable('config-invalid', error?.message || 'advice request failed');
+    }
+  }
+
+  async function inspect({ endpoint, model, provider: providerId = 'ollama', file, minVersion, timeoutMs }      = {}) {
+    const unavailable = (state     , message     , version      = null, versionOk = false) => ({
+      endpoint: { state, version, versionOk, message: message ?? null },
+      models: [],
+      model: { installed: false, decisionCapable: false },
+    });
+    try {
+      const provider = adviceRegistry?.providers?.find((entry     ) => 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     ) => {
+        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     ) { 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     ) => adapter.modelMatches(model, entry.name));
+      const fallbackIndexes = models.map((entry     , index     ) => index)
+        .filter((index     ) => !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     ) => adapter.modelMatches(model, entry.name));
+      return {
+        endpoint: endpointResult,
+        models,
+        model: {
+          installed: Boolean(match),
+          decisionCapable: Boolean(match?.capabilities?.includes(provider.capability)),
+        },
+      };
+    } catch (error     ) {
+      return unavailable('unreachable', error?.message || 'decision model inspection failed');
+    }
+  }
+
+  return { ask, inspect };
+}
+
+module.exports = { createAdviceClient, versionAtLeast };

package/src/runtime/advice/config.js

@@ -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.js');
+
+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     )          {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function offResult(reason        , decidedBy     , notes           = [], setting      = {})      {
+  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               , fsImpl     )                                                {
+  if (!file) return { exists: false };
+  try {
+    return { exists: true, value: JSON.parse(fsImpl.readFileSync(file, 'utf8')) };
+  } catch (error     ) {
+    if (error?.code === 'ENOENT') return { exists: false };
+    return { exists: true, error };
+  }
+}
+
+function parseUserSetting(value     , adviceRegistry     )      {
+  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     ) => 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     )      {
+  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           = [];
+  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,
+}      = {})      {
+  const notes           = [];
+  let resolvedRoots = roots;
+  try {
+    if (!resolvedRoots) resolvedRoots = resolveRoots({ registry: storageRegistry, projectRoot, global, env });
+  } catch (error     ) {
+    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 }      = {})      {
+  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      = {};
+  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     ) {
+        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     ) {
+    return { ok: false, reason: 'config-invalid', detail: `${file}: ${error.message}` };
+  }
+}
+
+module.exports = { resolveSetting, writeSetting };