@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/candidate.js

@@ -2,7 +2,7 @@
 
 // TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
 
-const { measureFreshness } = require('./freshness.js');
+const { measureFreshness, fileRootFor } = require('./freshness.js');
 const { measureTreeState, sourceVersionFor } = require('./source-version.js');
 const { VALID_EVIDENCE_KINDS, VALID_PROVENANCE } = require('./evidence-ledger.js');
 const { resolveLocator, describeResolution } = require('./locator-resolve.js');
@@ -58,6 +58,7 @@ function getProviderFreshness(provider        , root        , ctx      )      {
                   
                          
                      
+                      
                       
                        
                        
@@ -114,7 +115,7 @@ const EVIDENCE_REFUSED_SOURCE_FIELDS = new Map
 ]);
 
 /**
- * Normalises a locator given either as an object or as a `file[:line]` / URI string.
+ * Normalises a locator given either as an object or as a `file[:line[-line]]` / URI string.
  * @param {Object|string} raw
  * @returns {Object}
  */
@@ -123,8 +124,13 @@ function parseLocator(raw     ) {
     const text = raw.trim();
     if (text === '') throw new Error('locator is empty');
     if (/^[a-z][a-z0-9+.-]*:\/\//i.test(text)) return { uri: text };
-    const withLine = text.match(/^(.+):(\d+)$/);
-    if (withLine) return { file: withLine[1], line: Number(withLine[2]) };
+    // `path:77-104` names a range; the locator keeps its first line (it has no end-line field), so the
+    // end is checked only to be a range at all, not against the file's length.
+    const withLine = text.match(/^(.+):(\d+)(?:-(\d+))?$/);
+    if (withLine) {
+      if (withLine[3] !== undefined && Number(withLine[3]) < Number(withLine[2])) throw new Error(`locator line range '${withLine[2]}-${withLine[3]}' ends before it starts`);
+      return { file: withLine[1], line: Number(withLine[2]) };
+    }
     return { file: text };
   }
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
@@ -159,11 +165,12 @@ function parseLocator(raw     ) {
  * @param {Object} raw
  * @param {string} taskId the task the batch is being written to
  * @param {string} taskId the task the batch is being written to
- * @param {string} repoRoot root a relative locator resolves against
+ * @param {string} repoRoot the task's state root (its retrieval plan)
  * @param {string|null} [slug] feature slug
+ * @param {string} [sourceRoot] the checkout a relative locator resolves in (default repoRoot)
  * @returns {{kind:string, provenance:string, source:Object, locator:Object, content:(string|null)}}
  */
-function validateEvidenceItem(raw     , taskId     , repoRoot     , slug      = null) {
+function validateEvidenceItem(raw     , taskId     , repoRoot     , slug      = null, sourceRoot      = repoRoot) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('an evidence item must be a JSON object');
   assertNoScoreFields(raw, '');
 
@@ -253,7 +260,8 @@ function validateEvidenceItem(raw     , taskId     , repoRoot     , slug      =
   // gate. The refusal names what the file actually offers, so the writer can correct it here rather
   // than discover it at the gate.
   if (!isAbsence && raw.provenance === 'extracted' && locator) {
-    const resolution = resolveLocator({ locator, repoRoot });
+    // IC-007: a relative locator names a file in the checkout the verb runs in (fileRootFor).
+    const resolution = resolveLocator({ locator, repoRoot: fileRootFor(sourceRoot, repoRoot, locator) });
     if (!resolution.resolved) {
       throw new Error(`the locator does not resolve: ${describeResolution(locator, resolution)}. `
         + "An 'extracted' item asserts a read of the repository, so a locator that points at nothing "
@@ -372,6 +380,7 @@ function toEvidence(
   const taskId = ctx.taskId;
   const root = ctx.root || process.cwd();
   const treeState = ctx.treeState || measureTreeState(root);
+  const sourceRoot = ctx.sourceRoot || root;
 
   let rawItem     ;
 
@@ -398,7 +407,7 @@ function toEvidence(
       if (typeof loc === 'string') {
         loc = parseLocator(loc);
       }
-      const sv = sourceVersionFor(root, loc, treeState);
+      const sv = sourceVersionFor(fileRootFor(sourceRoot, root, loc), loc, treeState);
       const measuredHash = sv.fileHash;
       const searchedHash = candidate.sourceVersion.fileHash;
       if (searchedHash !== measuredHash) {
@@ -432,8 +441,8 @@ function toEvidence(
     throw new Error("toEvidence requires either 'candidate' or 'item'");
   }
 
-  const validated = validateEvidenceItem(rawItem, taskId, root, ctx.slug);
-  const sv = sourceVersionFor(root, validated.locator, treeState);
+  const validated = validateEvidenceItem(rawItem, taskId, root, ctx.slug, sourceRoot);
+  const sv = sourceVersionFor(fileRootFor(sourceRoot, root, validated.locator), validated.locator, treeState);
 
   const source                      = { ...validated.source };
 
@@ -482,7 +491,7 @@ function toEvidence(
     }
   } else {
     freshness = {
-      ...measureFreshness(root, validated.locator, sv.gitCommit),
+      ...measureFreshness(root, validated.locator, sv.gitCommit, sourceRoot),
       isDirty: sv.isDirty,
     };
   }

package/src/runtime/capabilities/executor.js

@@ -0,0 +1,450 @@
+'use strict';
+
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+const execFileAsync = promisify(execFile);
+const { validateLoopbackUrl } = require('./loopback.js');
+const { sanitizeCapabilityOutput } = require('./sanitizer.js');
+
+const DEFAULT_TIMEOUT_MS = 10000;
+const MAX_TIMEOUT_MS = 60000;
+const DEFAULT_MAX_BUFFER_BYTES = 16 * 1024 * 1024; // 16 MiB
+
+                           
+                
+                    
+                               
+                               
+ 
+
+                                      
+                     
+                      
+                          
+                           
+                     
+               
+ 
+
+                                     
+              
+                       
+                            
+                                                           
+                                            
+             
+                       
+                    
+                     
+    
+                 
+ 
+
+function extractPath(obj     , pathStr         )      {
+  if (!pathStr || !obj) return obj;
+  const parts = pathStr.split('.');
+  let cur = obj;
+  for (const part of parts) {
+    if (cur === null || cur === undefined) return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+function interpolateTemplate(template     , input     )      {
+  if (typeof template === 'string') {
+    return template
+      .replaceAll('{text}', input.text ?? '')
+      .replaceAll('{filePath}', input.filePath ?? '')
+      .replaceAll('{inputPath}', input.inputPath ?? input.filePath ?? '');
+  }
+  if (Array.isArray(template)) {
+    return template.map((item) => interpolateTemplate(item, input));
+  }
+  if (template !== null && typeof template === 'object') {
+    const result                      = {};
+    for (const [k, v] of Object.entries(template)) {
+      result[k] = interpolateTemplate(v, input);
+    }
+    return result;
+  }
+  return template;
+}
+
+class LocalCapabilityExecutor {
+  fsImpl     ;
+  fetchImpl              ;
+  execFileImpl     ;
+  maxBufferBytes        ;
+
+  constructor(options                                                                                          = {}) {
+    this.fsImpl = options.fsImpl || require('node:fs');
+    this.fetchImpl = options.fetchImpl || globalThis.fetch;
+    this.execFileImpl = options.execFileImpl || execFileAsync;
+    this.maxBufferBytes = options.maxBufferBytes || DEFAULT_MAX_BUFFER_BYTES;
+  }
+
+  async execute(
+    capabilityId        ,
+    provider     ,
+    input                  = {},
+    options                             = {}
+  )                                     {
+    const providerId = provider?.id || null;
+    if (!provider) {
+      return {
+        ok: false,
+        capabilityId,
+        providerId: null,
+        status: 'UNAVAILABLE',
+        data: null,
+        error: 'No provider specified for capability execution',
+      };
+    }
+
+    const effectiveTimeout = Math.min(
+      options.timeoutMs ?? provider.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      MAX_TIMEOUT_MS
+    );
+    const maxBuffer = options.maxBufferBytes || this.maxBufferBytes;
+    const fetchImpl = options.fetchImpl || this.fetchImpl;
+    const execFileImpl = options.execFileImpl || this.execFileImpl;
+
+    if (provider.kind === 'http') {
+      return await this.executeHttp(capabilityId, provider, input, {
+        effectiveTimeout,
+        maxBuffer,
+        fetchImpl,
+      });
+    }
+
+    if (provider.kind === 'cli') {
+      return await this.executeCli(capabilityId, provider, input, {
+        effectiveTimeout,
+        maxBuffer,
+        execFileImpl,
+      });
+    }
+
+    return {
+      ok: false,
+      capabilityId,
+      providerId,
+      status: 'ERROR',
+      data: null,
+      error: `Unsupported provider kind '${provider.kind}'`,
+    };
+  }
+
+  async executeHttp(
+    capabilityId        ,
+    provider     ,
+    input                 ,
+    { effectiveTimeout, maxBuffer, fetchImpl }     
+  )                                     {
+    const providerId = provider.id || null;
+    const endpoint = provider.endpoint;
+
+    const urlCheck = validateLoopbackUrl(endpoint);
+    if (!urlCheck.ok) {
+      return {
+        ok: false,
+        capabilityId,
+        providerId,
+        status: 'ERROR',
+        data: null,
+        error: urlCheck.reason,
+      };
+    }
+
+    const method = provider.method || 'POST';
+    const headers = {
+      'Content-Type': 'application/json',
+      ...(provider.headers || {}),
+    };
+
+    let bodyData      = null;
+    try {
+      if (provider.requestTemplate) {
+        bodyData = interpolateTemplate(provider.requestTemplate, input);
+      } else {
+        bodyData = {
+          prompt: input.text,
+          text: input.text,
+          filePath: input.filePath,
+          schema: input.schema,
+          ...(input.params || {}),
+        };
+      }
+    } catch (err     ) {
+      return {
+        ok: false,
+        capabilityId,
+        providerId,
+        status: 'ERROR',
+        data: null,
+        error: `Request preparation error: ${err?.message || String(err)}`,
+      };
+    }
+
+    const bodyStr = method !== 'GET' ? JSON.stringify(bodyData) : undefined;
+    const bytesIn = bodyStr ? Buffer.byteLength(bodyStr, 'utf8') : 0;
+    const started = Number(process.hrtime.bigint() / 1000000n);
+
+    try {
+      const res = await fetchImpl(endpoint, {
+        method,
+        headers,
+        body: bodyStr,
+        redirect: 'error',
+        signal: AbortSignal.timeout(effectiveTimeout),
+      });
+
+      if (!res.ok) {
+        return {
+          ok: false,
+          capabilityId,
+          providerId,
+          status: 'UNAVAILABLE',
+          data: null,
+          error: `HTTP error ${res.status}: ${res.statusText}`,
+        };
+      }
+
+      const textOutput = await res.text();
+      const bytesOut = Buffer.byteLength(textOutput, 'utf8');
+      if (bytesOut > maxBuffer) {
+        return {
+          ok: false,
+          capabilityId,
+          providerId,
+          status: 'ERROR',
+          data: null,
+          error: `Output exceeded buffer limit of ${maxBuffer} bytes`,
+        };
+      }
+
+      let parsed     ;
+      try {
+        parsed = JSON.parse(textOutput);
+      } catch {
+        parsed = textOutput;
+      }
+
+      const extracted = provider.responsePath ? extractPath(parsed, provider.responsePath) : parsed;
+      const sanitized = sanitizeCapabilityOutput(extracted);
+
+      if (sanitized.refused) {
+        return {
+          ok: false,
+          capabilityId,
+          providerId,
+          status: 'ERROR',
+          data: null,
+          error: `DECISION_INJECTION_REFUSED: ${sanitized.refusalReason}`,
+        };
+      }
+
+      const durationMs = Math.round(Number(process.hrtime.bigint() / 1000000n) - started);
+      return {
+        ok: true,
+        capabilityId,
+        providerId,
+        status: 'HEALTHY',
+        data: sanitized.data,
+        metrics: {
+          durationMs,
+          bytesIn,
+          bytesOut,
+        },
+      };
+    } catch (err     ) {
+      const durationMs = Math.round(Number(process.hrtime.bigint() / 1000000n) - started);
+      const isUnavailable =
+        err.code === 'ECONNREFUSED' ||
+        err.code === 'ETIMEDOUT' ||
+        err.name === 'TimeoutError' ||
+        err.name === 'AbortError' ||
+        /fetch failed/i.test(err.message);
+      return {
+        ok: false,
+        capabilityId,
+        providerId,
+        status: isUnavailable ? 'UNAVAILABLE' : 'ERROR',
+        data: null,
+        error: isUnavailable
+          ? `Local server at ${endpoint} is not running (${err.message})`
+          : err.message,
+        metrics: {
+          durationMs,
+          bytesIn,
+          bytesOut: 0,
+        },
+      };
+    }
+  }
+
+  async executeCli(
+    capabilityId        ,
+    provider     ,
+    input                 ,
+    { effectiveTimeout, maxBuffer, execFileImpl }     
+  )                                     {
+    const providerId = provider.id || null;
+    const binary = provider.binary || provider.program;
+    if (!binary) {
+      return {
+        ok: false,
+        capabilityId,
+        providerId,
+        status: 'ERROR',
+        data: null,
+        error: 'No program or binary specified for CLI provider',
+      };
+    }
+
+    let args           = [];
+    if (provider.argvTemplate && Array.isArray(provider.argvTemplate)) {
+      args = provider.argvTemplate.map((arg        ) =>
+        arg
+          .replaceAll('{filePath}', input.filePath || '')
+          .replaceAll('{inputPath}', input.filePath || '')
+          .replaceAll('{text}', input.text || '')
+      );
+    } else {
+      if (input.filePath) args.push(input.filePath);
+      else if (input.text) args.push(input.text);
+    }
+
+    const started = Number(process.hrtime.bigint() / 1000000n);
+    const bytesIn = Buffer.byteLength(args.join(' '), 'utf8');
+
+    try {
+      let stdout        ;
+      if (typeof execFileImpl === 'function' && execFileImpl.length === 4) {
+        const cbAsync = promisify(execFileImpl);
+        const res = await cbAsync(binary, args, {
+          shell: false,
+          timeout: effectiveTimeout,
+          maxBuffer,
+        });
+        stdout = res.stdout;
+      } else {
+        const res = await execFileImpl(binary, args, {
+          shell: false,
+          timeout: effectiveTimeout,
+          maxBuffer,
+        });
+        stdout = res.stdout !== undefined ? res.stdout : res;
+      }
+
+      const outStr = String(stdout || '');
+      const bytesOut = Buffer.byteLength(outStr, 'utf8');
+      if (bytesOut > maxBuffer) {
+        return {
+          ok: false,
+          capabilityId,
+          providerId,
+          status: 'ERROR',
+          data: null,
+          error: `Output exceeded buffer limit of ${maxBuffer} bytes`,
+        };
+      }
+
+      let parsed     ;
+      try {
+        parsed = JSON.parse(outStr);
+      } catch {
+        parsed = outStr.trim();
+      }
+
+      const extracted = provider.responsePath ? extractPath(parsed, provider.responsePath) : parsed;
+      const sanitized = sanitizeCapabilityOutput(extracted);
+
+      if (sanitized.refused) {
+        return {
+          ok: false,
+          capabilityId,
+          providerId,
+          status: 'ERROR',
+          data: null,
+          error: `DECISION_INJECTION_REFUSED: ${sanitized.refusalReason}`,
+        };
+      }
+
+      const durationMs = Math.round(Number(process.hrtime.bigint() / 1000000n) - started);
+      return {
+        ok: true,
+        capabilityId,
+        providerId,
+        status: 'HEALTHY',
+        data: sanitized.data,
+        metrics: {
+          durationMs,
+          bytesIn,
+          bytesOut,
+        },
+      };
+    } catch (err     ) {
+      const durationMs = Math.round(Number(process.hrtime.bigint() / 1000000n) - started);
+      const isUnavailable = err.code === 'ENOENT' || err.killed || err.signal === 'SIGTERM';
+      return {
+        ok: false,
+        capabilityId,
+        providerId,
+        status: isUnavailable ? 'UNAVAILABLE' : 'ERROR',
+        data: null,
+        error: isUnavailable ? `Binary '${binary}' not available or timed out: ${err.message}` : err.message,
+        metrics: {
+          durationMs,
+          bytesIn,
+          bytesOut: 0,
+        },
+      };
+    }
+  }
+}
+
+async function probeHttpEndpoint(
+  endpoint        ,
+  options                                          = {}
+)                                                                                                         {
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? 1500;
+  const started = Number(process.hrtime.bigint() / 1000000n);
+
+  try {
+    const res = await fetchImpl(endpoint, {
+      method: 'GET',
+      redirect: 'error',
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const durationMs = Math.round(Number(process.hrtime.bigint() / 1000000n) - started);
+    return {
+      ok: res.status >= 200 && res.status < 300,
+      status: res.status,
+      durationMs,
+    };
+  } catch (err     ) {
+    const durationMs = Math.round(Number(process.hrtime.bigint() / 1000000n) - started);
+    const isUnavailable =
+      err.code === 'ECONNREFUSED' ||
+      err.code === 'ETIMEDOUT' ||
+      err.name === 'TimeoutError' ||
+      err.name === 'AbortError' ||
+      /fetch failed/i.test(err.message);
+    return {
+      ok: false,
+      durationMs,
+      error: err.message,
+      isUnavailable,
+    };
+  }
+}
+
+module.exports = {
+  LocalCapabilityExecutor,
+  extractPath,
+  interpolateTemplate,
+  probeHttpEndpoint,
+};

package/src/runtime/capabilities/loopback.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+
+                                    
+              
+                  
+ 
+
+function validateLoopbackUrl(urlStr        )                           {
+  if (typeof urlStr !== 'string' || !urlStr.trim()) {
+    return { ok: false, reason: 'URL must be a non-empty string' };
+  }
+
+  let parsed     ;
+  try {
+    parsed = new URL(urlStr);
+  } catch (err     ) {
+    return { ok: false, reason: `Invalid URL: ${err.message}` };
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return { ok: false, reason: `Protocol '${parsed.protocol}' is not allowed; must be http: or https:` };
+  }
+
+  const hostname = parsed.hostname.toLowerCase();
+  const unbracketed = hostname.startsWith('[') && hostname.endsWith(']')
+    ? hostname.slice(1, -1)
+    : hostname;
+
+  if (!LOOPBACK_HOSTS.has(hostname) && !LOOPBACK_HOSTS.has(unbracketed)) {
+    return {
+      ok: false,
+      reason: `Host '${hostname}' is not a permitted loopback host (must be 127.0.0.1, localhost, or [::1]): DISALLOWED_REMOTE_ENDPOINT`,
+    };
+  }
+
+  return { ok: true };
+}
+
+module.exports = { validateLoopbackUrl, LOOPBACK_HOSTS };

package/src/runtime/capabilities/sanitizer.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const FORBIDDEN_DECISION_KEYS = Object.freeze([
+  'verdict',
+  'gate',
+  'taskClass',
+  'decision',
+  'approved',
+  'pass',
+  'disagreement',
+]);
+
+const FORBIDDEN_SET = new Set(FORBIDDEN_DECISION_KEYS.map((k) => k.toLowerCase()));
+
+                          
+            
+                     
+                         
+                    
+                         
+ 
+
+function sanitizeCapabilityOutput(output     )                 {
+  if (output === null || output === undefined) {
+    return { data: output, sanitized: false, strippedKeys: [] };
+  }
+
+  if (typeof output !== 'object') {
+    return { data: output, sanitized: false, strippedKeys: [] };
+  }
+
+  const strippedKeys           = [];
+  let refused = false;
+  let refusalReason                    ;
+
+  if (!Array.isArray(output) && typeof output === 'object') {
+    for (const [key, val] of Object.entries(output)) {
+      const lowerKey = key.toLowerCase();
+      if (lowerKey === 'verdict') {
+        const strVal = String(val).trim().toUpperCase();
+        if (strVal === 'PASS' || strVal === 'FAIL') {
+          refused = true;
+          refusalReason = 'DECISION_INJECTION_REFUSED';
+        }
+      } else if (lowerKey === 'gate') {
+        const strVal = String(val).trim().toUpperCase();
+        if (strVal === 'APPROVED') {
+          refused = true;
+          refusalReason = 'DECISION_INJECTION_REFUSED';
+        }
+      }
+    }
+  }
+
+  function clean(val     )      {
+    if (val === null || val === undefined) return val;
+    if (Array.isArray(val)) {
+      return val.map((item) => clean(item));
+    }
+    if (typeof val === 'object') {
+      const cleanedObj                      = {};
+      for (const [k, v] of Object.entries(val)) {
+        if (FORBIDDEN_SET.has(k.toLowerCase())) {
+          strippedKeys.push(k);
+        } else {
+          cleanedObj[k] = clean(v);
+        }
+      }
+      return cleanedObj;
+    }
+    return val;
+  }
+
+  const data = clean(output);
+  const sanitized = strippedKeys.length > 0;
+
+  return {
+    data,
+    sanitized,
+    strippedKeys,
+    ...(refused ? { refused: true, refusalReason } : {}),
+  };
+}
+
+module.exports = {
+  FORBIDDEN_DECISION_KEYS,
+  sanitizeCapabilityOutput,
+};