@bahulam/code 0.1.23 → 0.1.25

package/src/core/request-retry.mjs

@@ -0,0 +1,106 @@
+/**
+ * Shared retry policy for one-shot model HTTP requests.
+ *
+ * Streaming /api/execute has its own event-id resume protocol in
+ * stream-client.mjs. This helper is for npm-owned local/direct model calls
+ * where the request must finish before the agent loop can continue.
+ */
+
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504, 529]);
+const NETWORK_CODES = new Set([
+  'ECONNRESET', 'ECONNREFUSED', 'ECONNABORTED', 'ETIMEDOUT',
+  'EAI_AGAIN', 'ENETUNREACH', 'ENETDOWN', 'EHOSTUNREACH', 'UND_ERR_CONNECT_TIMEOUT',
+]);
+
+function numberEnv(name, fallback) {
+  const value = Number.parseInt(process.env[name] || '', 10);
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+export function isNetworkError(error) {
+  const code = error?.cause?.code || error?.code;
+  return error?.name === 'AbortError'
+    || NETWORK_CODES.has(String(code || '').toUpperCase())
+    || /fetch failed|network|socket|timed out|timeout|connection reset|connection refused/i.test(String(error?.message || ''));
+}
+
+export function isRetryableStatus(status) {
+  return RETRYABLE_STATUS.has(Number(status));
+}
+
+function retryDelay(attempt, base, max) {
+  const exponential = Math.min(max, base * (2 ** Math.max(0, attempt - 1)));
+  return Math.min(max, Math.round(exponential * (0.8 + Math.random() * 0.4)));
+}
+
+function wait(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export class RequestError extends Error {
+  constructor(message, { status = null, code = 'request_error', retryable = false, attempts = 1, cause = null } = {}) {
+    super(message, { cause: cause || undefined });
+    this.name = 'RequestError';
+    this.status = status;
+    this.code = code;
+    this.retryable = retryable;
+    this.attempts = attempts;
+  }
+}
+
+/**
+ * Fetch with bounded retry for transient transport/server failures.
+ * 401/403 and all other non-retryable 4xx responses return immediately.
+ */
+export async function fetchWithRetry(url, options = {}, {
+  fetchImpl = globalThis.fetch,
+  maxRetries = numberEnv('BAHULAM_REQUEST_MAX_RETRIES', 2),
+  baseDelayMs = numberEnv('BAHULAM_REQUEST_RETRY_BASE_MS', 500),
+  maxDelayMs = numberEnv('BAHULAM_REQUEST_RETRY_MAX_MS', 8000),
+  onRetry = null,
+} = {}) {
+  const retries = Math.max(0, Number(maxRetries) || 0);
+  let attempt = 0;
+
+  while (true) {
+    attempt++;
+    let response;
+    try {
+      response = await fetchImpl(url, options);
+    } catch (error) {
+      if (!isNetworkError(error) || attempt > retries + 1) {
+        throw new RequestError(
+          `Network request failed after ${attempt} attempt${attempt === 1 ? '' : 's'}: ${error?.message || error}`,
+          { code: 'network_error', retryable: true, attempts: attempt, cause: error },
+        );
+      }
+      const delayMs = retryDelay(attempt, baseDelayMs, maxDelayMs);
+      onRetry?.({ attempt, delayMs, reason: 'network', error });
+      await wait(delayMs);
+      continue;
+    }
+
+    if (!isRetryableStatus(response.status) || attempt > retries + 1) {
+      return response;
+    }
+
+    // Release the failed response before retrying. The final response remains
+    // available to the caller for its normal provider-specific error body.
+    try { response.body?.cancel?.(); } catch {}
+    const delayMs = retryDelay(attempt, baseDelayMs, maxDelayMs);
+    onRetry?.({ attempt, delayMs, reason: `http_${response.status}`, status: response.status });
+    await wait(delayMs);
+  }
+}
+
+export function requestErrorData(error, { phase = 'model', provider = null } = {}) {
+  return {
+    message: error?.message || String(error),
+    code: error?.code || (error?.status ? `http_${error.status}` : 'request_error'),
+    phase,
+    provider,
+    status: error?.status ?? null,
+    retryable: error?.retryable === true || isRetryableStatus(error?.status),
+    attempts: error?.attempts || 1,
+  };
+}

package/src/core/tool-error.mjs

@@ -0,0 +1,155 @@
+/**
+ * Structured tool errors.
+ *
+ * Plugin tool handlers used to return { success: false, output: "<msg>" }
+ * and thrown errors got wrapped the same way — the message became a
+ * blob the agent had to re-read to figure out what went wrong.
+ *
+ * This module standardizes the envelope so the trace UI can filter and
+ * the agent can self-correct on the next turn without re-parsing prose.
+ *
+ * Handler patterns
+ * ----------------
+ *
+ * Return a structured error explicitly:
+ *
+ *   import { toolError } from '../../src/core/tool-error.mjs';
+ *   if (!scene) return toolError('MISSING_SCENE', `Scene "${slug}" not found.`,
+ *                                'Call create_scene(name="<slug>") first.');
+ *
+ * OR throw a ToolError:
+ *
+ *   throw new ToolError('INVALID_ARGS', 'position must be [x,y,z]', 'Pass a length-3 array.');
+ *
+ * OR throw a plain Error — normalizeToolResult wraps it as { code: 'UNKNOWN' }
+ * so nothing crashes the executor.
+ *
+ * Error codes (extend freely; keep short, SCREAMING_SNAKE_CASE)
+ * ---
+ *   INVALID_ARGS       — schema violation or missing required field
+ *   MISSING_RESOURCE   — referenced id (node, ref, section, ...) not found
+ *   IO                 — filesystem or network operation failed
+ *   PROVIDER_UNAVAILABLE — external provider missing key or offline
+ *   PROVIDER_ERROR     — external provider returned an error response
+ *   STATE_ERROR        — plugin state DB read/write failure
+ *   RATE_LIMITED       — provider or platform rate limit hit
+ *   TIMEOUT            — operation exceeded its deadline
+ *   UNKNOWN            — thrown Error that wasn't a ToolError (fallback)
+ */
+
+export class ToolError extends Error {
+  constructor(code, message, hint) {
+    super(message);
+    this.name = 'ToolError';
+    this.code = String(code || 'UNKNOWN');
+    this.hint = hint ? String(hint) : null;
+  }
+}
+
+/**
+ * Build a structured error envelope suitable for `return`-ing from a
+ * plugin tool handler. Never throws.
+ */
+export function toolError(code, message, hint) {
+  return {
+    success: false,
+    output: String(message || ''),
+    error: {
+      code: String(code || 'UNKNOWN'),
+      message: String(message || ''),
+      ...(hint ? { hint: String(hint) } : {}),
+    },
+  };
+}
+
+/**
+ * Normalize an arbitrary handler return value or thrown error into the
+ * canonical shape:
+ *
+ *   Success:  { success: true,  output, _tool, _plugin }
+ *   Failure:  { success: false, output, error: { code, message, hint?, stack? },
+ *               _tool, _plugin }
+ *
+ * `stack` is only attached in DEBUG mode so the trace export can show
+ * it without leaking noise into normal responses.
+ *
+ * `traceId` is optional; when provided by the caller it's forwarded so
+ * export / logs can join back to the trace row.
+ */
+export function normalizeToolResult({ tool, plugin, traceId }, result, thrown) {
+  const meta = {
+    _tool: tool,
+    ...(plugin ? { _plugin: plugin } : {}),
+    ...(traceId ? { _trace_id: traceId } : {}),
+  };
+
+  if (thrown) {
+    const err = thrown instanceof ToolError
+      ? { code: thrown.code, message: thrown.message, ...(thrown.hint ? { hint: thrown.hint } : {}) }
+      : { code: 'UNKNOWN', message: String(thrown?.message || thrown) };
+    if (process.env.DEBUG && thrown?.stack) err.stack = String(thrown.stack).split('\n').slice(0, 6).join('\n');
+    const outputText = [`[${err.code}] ${err.message}`, err.hint ? `(hint: ${err.hint})` : ''].filter(Boolean).join(' ');
+    return { success: false, output: outputText, error: err, ...meta };
+  }
+
+  if (!result || typeof result !== 'object') {
+    return { success: true, output: result, ...meta };
+  }
+
+  if (result.success !== false) {
+    return { success: true, output: result.output ?? result, ...meta };
+  }
+
+  // success === false — extract structured error if present, else synthesize one
+  const err = result.error && typeof result.error === 'object'
+    ? {
+        code: String(result.error.code || 'UNKNOWN'),
+        message: String(result.error.message || result.output || 'Tool call failed.'),
+        ...(result.error.hint ? { hint: String(result.error.hint) } : {}),
+      }
+    : {
+        code: 'UNKNOWN',
+        message: typeof result.output === 'string' ? result.output : JSON.stringify(result.output ?? 'Tool call failed.'),
+      };
+
+  // The agent reads `output` on the next turn — make it self-contained so
+  // the LLM doesn't need to re-parse. Format: [CODE] message (hint: ...)
+  const rawOutput = typeof result.output === 'string' && result.output.trim()
+    ? result.output
+    : err.message;
+  const alreadyHasCode = rawOutput.startsWith(`[${err.code}]`);
+  const alreadyHasHint = err.hint && rawOutput.toLowerCase().includes(String(err.hint).toLowerCase());
+  const outputText = [
+    alreadyHasCode ? rawOutput : `[${err.code}] ${rawOutput}`,
+    err.hint && !alreadyHasHint ? `(hint: ${err.hint})` : '',
+  ].filter(Boolean).join(' ');
+  return { success: false, output: outputText, error: err, ...meta };
+}
+
+/**
+ * Format an error envelope as a short one-line summary for logs and
+ * compact trace rows.
+ */
+export function formatErrorSummary(err) {
+  if (!err) return '';
+  const code = err.code || 'UNKNOWN';
+  const msg = String(err.message || '').replace(/\s+/g, ' ').slice(0, 240);
+  return `[${code}] ${msg}${err.hint ? ` — hint: ${String(err.hint).slice(0, 140)}` : ''}`;
+}
+
+/**
+ * Build a compact hint the next agent turn can consume so it can
+ * self-correct without re-reading a raw stack trace.
+ *
+ * Example:
+ *   "Previous tool call `create_node` failed. [MISSING_RESOURCE] Node
+ *    'chair_99' not found. Hint: call get_scene(slug='cafe') to see
+ *    current node ids."
+ */
+export function buildNextTurnHint({ tool, error }) {
+  if (!error) return '';
+  const parts = [`Previous tool call \`${tool || 'unknown'}\` failed.`];
+  parts.push(`[${error.code || 'UNKNOWN'}] ${error.message || ''}`.trim());
+  if (error.hint) parts.push(`Hint: ${error.hint}`);
+  return parts.join(' ');
+}

package/src/core/tool-executor.mjs

@@ -152,8 +152,13 @@ export function createToolExecutor({
         return project.resource.root;
     }
 
-    async function commandCwd(args = {}) {
-        return await resolvePath(args.cwd || null, args);
+    async function commandCwd(args = {}, { readOnly = false } = {}) {
+        try {
+            return await resolvePath(args.cwd || null, args);
+        } catch (err) {
+            if (readOnly) return args.cwd ? path.resolve(args.cwd) : process.cwd();
+            throw err;
+        }
     }
 
     function shellTargetPath(cwd, target) {
@@ -1390,7 +1395,7 @@ export function createToolExecutor({
                 args._riskReason = classification.reason || shellCheck.reason;
             }
             args._classification = classification.classification; // 'safe' or 'contained'
-            const cwd = await commandCwd(args);
+            const cwd = await commandCwd(args, { readOnly: classification.classification === 'safe' });
 
             // Background execution: start via the BackgroundTasks registry
             // and return immediately. Safety checks above still apply;

package/src/core/usage-normalization.mjs

@@ -0,0 +1,32 @@
+/**
+ * Normalize provider/gateway usage into the npm agent's canonical shape.
+ *
+ * Providers use prompt_tokens/completion_tokens, Anthropic-style callers use
+ * input_tokens/output_tokens, and remote complete events use total_* fields.
+ * Keeping this conversion here prevents each runtime mode from drifting.
+ */
+export function normalizeUsage(usage) {
+    if (!usage) return null;
+
+    const input = usage.input_tokens
+        ?? usage.total_input_tokens
+        ?? usage.prompt_tokens
+        ?? 0;
+    const output = usage.output_tokens
+        ?? usage.total_output_tokens
+        ?? usage.completion_tokens
+        ?? 0;
+    const promptDetails = usage.prompt_tokens_details || {};
+
+    return {
+        input_tokens: input,
+        output_tokens: output,
+        cache_read_input_tokens: usage.cache_read_input_tokens
+            ?? usage.cache_read_tokens
+            ?? promptDetails.cached_tokens
+            ?? 0,
+        cache_creation_input_tokens: usage.cache_creation_input_tokens
+            ?? usage.cache_creation_tokens
+            ?? 0,
+    };
+}