chainlesschain 0.45.75 → 0.45.76

package/src/lib/execution-backend.js

@@ -0,0 +1,239 @@
+/**
+ * Execution Backend — abstraction for command execution environments.
+ *
+ * Provides LocalBackend (default), DockerBackend, and SSHBackend.
+ * The agent's run_shell and run_code tools delegate to the active backend.
+ *
+ * Config: .chainlesschain/config.json → agent.executionBackend
+ * Feature flag: EXECUTION_BACKENDS (off by default)
+ *
+ * @module execution-backend
+ */
+
+import { execSync } from "node:child_process";
+
+// ─── Exported for test injection ────────────────────────────────────
+
+export const _deps = {
+  execSync,
+};
+
+// ─── Base class ─────────────────────────────────────────────────────
+
+export class ExecutionBackend {
+  constructor(options = {}) {
+    this.type = "base";
+    this.options = options;
+  }
+
+  /**
+   * Execute a command.
+   * @param {string} command - The command to run
+   * @param {object} [opts]
+   * @param {string} [opts.cwd] - Working directory
+   * @param {number} [opts.timeout] - Timeout in ms
+   * @param {number} [opts.maxBuffer] - Max output buffer size
+   * @returns {{ stdout: string, stderr: string, exitCode: number }}
+   */
+  execute(command, opts = {}) {
+    throw new Error("execute() must be implemented by subclass");
+  }
+
+  /** @returns {string} Backend description for logging */
+  describe() {
+    return `${this.type} backend`;
+  }
+}
+
+// ─── Local Backend ──────────────────────────────────────────────────
+
+export class LocalBackend extends ExecutionBackend {
+  constructor(options = {}) {
+    super(options);
+    this.type = "local";
+  }
+
+  execute(command, opts = {}) {
+    const cwd = opts.cwd || process.cwd();
+    const timeout = opts.timeout || 60000;
+    const maxBuffer = opts.maxBuffer || 1024 * 1024;
+
+    try {
+      const stdout = _deps.execSync(command, {
+        cwd,
+        encoding: "utf8",
+        timeout,
+        maxBuffer,
+      });
+      return { stdout: stdout || "", stderr: "", exitCode: 0 };
+    } catch (err) {
+      return {
+        stdout: (err.stdout || "").toString(),
+        stderr: (err.stderr || err.message || "").toString(),
+        exitCode: err.status || 1,
+      };
+    }
+  }
+
+  describe() {
+    return "local (direct execution)";
+  }
+}
+
+// ─── Docker Backend ─────────────────────────────────────────────────
+
+export class DockerBackend extends ExecutionBackend {
+  /**
+   * @param {object} options
+   * @param {string} options.container - Container name or ID (for exec mode)
+   * @param {string} [options.image] - Image name (for run mode — ephemeral containers)
+   * @param {string} [options.workdir] - Working directory inside container
+   * @param {string[]} [options.volumes] - Volume mounts (host:container format)
+   * @param {string} [options.shell] - Shell to use (default: sh)
+   */
+  constructor(options = {}) {
+    super(options);
+    this.type = "docker";
+    this.container = options.container || null;
+    this.image = options.image || null;
+    this.workdir = options.workdir || "/workspace";
+    this.volumes = options.volumes || [];
+    this.shell = options.shell || "sh";
+  }
+
+  execute(command, opts = {}) {
+    const timeout = opts.timeout || 60000;
+    const maxBuffer = opts.maxBuffer || 1024 * 1024;
+    const cwd = opts.cwd || this.workdir;
+
+    let dockerCmd;
+    if (this.container) {
+      // Exec into existing container
+      dockerCmd = `docker exec -w "${cwd}" ${this.container} ${this.shell} -c "${this._escapeCommand(command)}"`;
+    } else if (this.image) {
+      // Run ephemeral container
+      const volumeArgs = this.volumes.map((v) => `-v "${v}"`).join(" ");
+      dockerCmd = `docker run --rm -w "${cwd}" ${volumeArgs} ${this.image} ${this.shell} -c "${this._escapeCommand(command)}"`;
+    } else {
+      return {
+        stdout: "",
+        stderr: "Docker backend: neither container nor image specified",
+        exitCode: 1,
+      };
+    }
+
+    try {
+      const stdout = _deps.execSync(dockerCmd, {
+        encoding: "utf8",
+        timeout,
+        maxBuffer,
+      });
+      return { stdout: stdout || "", stderr: "", exitCode: 0 };
+    } catch (err) {
+      return {
+        stdout: (err.stdout || "").toString(),
+        stderr: (err.stderr || err.message || "").toString(),
+        exitCode: err.status || 1,
+      };
+    }
+  }
+
+  _escapeCommand(cmd) {
+    return cmd.replace(/"/g, '\\"');
+  }
+
+  describe() {
+    if (this.container) return `docker exec (container: ${this.container})`;
+    return `docker run (image: ${this.image})`;
+  }
+}
+
+// ─── SSH Backend ────────────────────────────────────────────────────
+
+export class SSHBackend extends ExecutionBackend {
+  /**
+   * @param {object} options
+   * @param {string} options.host - Remote host
+   * @param {string} [options.user] - SSH user
+   * @param {string} [options.key] - Path to SSH private key
+   * @param {number} [options.port] - SSH port (default: 22)
+   * @param {string} [options.workdir] - Remote working directory
+   */
+  constructor(options = {}) {
+    super(options);
+    this.type = "ssh";
+    this.host = options.host;
+    this.user = options.user || "";
+    this.key = options.key || "";
+    this.port = options.port || 22;
+    this.workdir = options.workdir || "~";
+  }
+
+  execute(command, opts = {}) {
+    const timeout = opts.timeout || 60000;
+    const maxBuffer = opts.maxBuffer || 1024 * 1024;
+    const cwd = opts.cwd || this.workdir;
+
+    if (!this.host) {
+      return {
+        stdout: "",
+        stderr: "SSH backend: host not specified",
+        exitCode: 1,
+      };
+    }
+
+    const userHost = this.user ? `${this.user}@${this.host}` : this.host;
+    const keyArg = this.key ? `-i "${this.key}"` : "";
+    const portArg = this.port !== 22 ? `-p ${this.port}` : "";
+    const remoteCmd = `cd "${cwd}" && ${command}`;
+
+    const sshCmd = `ssh ${keyArg} ${portArg} -o StrictHostKeyChecking=no -o ConnectTimeout=10 ${userHost} "${this._escapeCommand(remoteCmd)}"`;
+
+    try {
+      const stdout = _deps.execSync(sshCmd, {
+        encoding: "utf8",
+        timeout,
+        maxBuffer,
+      });
+      return { stdout: stdout || "", stderr: "", exitCode: 0 };
+    } catch (err) {
+      return {
+        stdout: (err.stdout || "").toString(),
+        stderr: (err.stderr || err.message || "").toString(),
+        exitCode: err.status || 1,
+      };
+    }
+  }
+
+  _escapeCommand(cmd) {
+    return cmd.replace(/"/g, '\\"');
+  }
+
+  describe() {
+    const userHost = this.user ? `${this.user}@${this.host}` : this.host;
+    return `ssh (${userHost}:${this.port})`;
+  }
+}
+
+// ─── Factory ────────────────────────────────────────────────────────
+
+/**
+ * Create an execution backend from config.
+ * @param {object} [config] - Backend config from config.json
+ * @param {string} [config.type] - "local" | "docker" | "ssh"
+ * @param {object} [config.options] - Backend-specific options
+ * @returns {ExecutionBackend}
+ */
+export function createBackend(config = {}) {
+  const type = (config.type || "local").toLowerCase();
+
+  switch (type) {
+    case "docker":
+      return new DockerBackend(config.options || {});
+    case "ssh":
+      return new SSHBackend(config.options || {});
+    case "local":
+    default:
+      return new LocalBackend(config.options || {});
+  }
+}

package/src/lib/hook-manager.js

@@ -58,6 +58,8 @@ export const HookEvents = {
   PostGitCommit: "PostGitCommit",
   PreGitPush: "PreGitPush",
   CIFailure: "CIFailure",
+  IterationWarning: "IterationWarning",
+  IterationBudgetExhausted: "IterationBudgetExhausted",
 };
 
 /**

package/src/lib/iteration-budget.js

@@ -0,0 +1,175 @@
+/**
+ * Iteration Budget — shared, configurable iteration limit for agent loops.
+ *
+ * Replaces the hardcoded MAX_ITERATIONS constant with a first-class budget
+ * object that is shared across parent and child agents, supports progressive
+ * warnings, and can be configured via config.json or environment variable.
+ *
+ * Inspired by Hermes Agent's shared iteration budget system.
+ *
+ * @module iteration-budget
+ */
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const DEFAULT_BUDGET = 50;
+const WARNING_THRESHOLD = 0.7; // 70%
+const WRAPPING_UP_THRESHOLD = 0.9; // 90%
+
+/**
+ * Warning level enum.
+ */
+export const WarningLevel = {
+  NONE: "none",
+  WARNING: "warning", // 70-89%
+  WRAPPING_UP: "wrapping-up", // 90-99%
+  EXHAUSTED: "exhausted", // 100%
+};
+
+// ─── IterationBudget ────────────────────────────────────────────────────────
+
+export class IterationBudget {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.limit] - Maximum iterations (default: 50)
+   * @param {string} [options.owner] - Identifier for the budget creator (e.g. session ID)
+   */
+  constructor(options = {}) {
+    this._limit = options.limit || IterationBudget.resolveLimit();
+    this._consumed = 0;
+    this._owner = options.owner || null;
+    this._warnings = []; // timestamps of emitted warnings
+  }
+
+  /**
+   * Resolve the budget limit from config/env/default.
+   * Priority: CC_ITERATION_BUDGET env > default
+   */
+  static resolveLimit() {
+    const env = process.env.CC_ITERATION_BUDGET;
+    if (env) {
+      const parsed = parseInt(env, 10);
+      if (!isNaN(parsed) && parsed > 0) return parsed;
+    }
+    return DEFAULT_BUDGET;
+  }
+
+  /** Total iteration limit. */
+  get limit() {
+    return this._limit;
+  }
+
+  /** Number of iterations consumed so far. */
+  get consumed() {
+    return this._consumed;
+  }
+
+  /**
+   * Consume one iteration. Returns the current warning level after consumption.
+   * @returns {string} WarningLevel value
+   */
+  consume() {
+    this._consumed++;
+    return this.warningLevel();
+  }
+
+  /**
+   * Number of iterations remaining.
+   * @returns {number}
+   */
+  remaining() {
+    return Math.max(0, this._limit - this._consumed);
+  }
+
+  /**
+   * Percentage of budget consumed (0.0 – 1.0+).
+   * @returns {number}
+   */
+  percentage() {
+    if (this._limit === 0) return 1;
+    return this._consumed / this._limit;
+  }
+
+  /**
+   * Whether the budget is exhausted.
+   * @returns {boolean}
+   */
+  isExhausted() {
+    return this._consumed >= this._limit;
+  }
+
+  /**
+   * Whether there is still budget remaining.
+   * @returns {boolean}
+   */
+  hasRemaining() {
+    return this._consumed < this._limit;
+  }
+
+  /**
+   * Current warning level based on consumption percentage.
+   * @returns {string} WarningLevel value
+   */
+  warningLevel() {
+    const pct = this.percentage();
+    if (pct >= 1) return WarningLevel.EXHAUSTED;
+    if (pct >= WRAPPING_UP_THRESHOLD) return WarningLevel.WRAPPING_UP;
+    if (pct >= WARNING_THRESHOLD) return WarningLevel.WARNING;
+    return WarningLevel.NONE;
+  }
+
+  /**
+   * Record that a warning was emitted (for dedup in the agent loop).
+   * @param {string} level - WarningLevel value
+   */
+  recordWarning(level) {
+    this._warnings.push({ level, at: this._consumed });
+  }
+
+  /**
+   * Whether a warning at this level has already been recorded.
+   * @param {string} level
+   * @returns {boolean}
+   */
+  hasWarned(level) {
+    return this._warnings.some((w) => w.level === level);
+  }
+
+  /**
+   * Generate a human-readable summary of budget usage.
+   * Useful when the budget is exhausted and the agent needs to report status.
+   * @returns {string}
+   */
+  toSummary() {
+    const pct = Math.round(this.percentage() * 100);
+    return (
+      `Iteration budget: ${this._consumed}/${this._limit} (${pct}%). ` +
+      `${this.remaining()} iterations remaining.`
+    );
+  }
+
+  /**
+   * Create a warning message suitable for appending to tool results.
+   * @returns {string|null} Warning message or null if no warning needed
+   */
+  toWarningMessage() {
+    const level = this.warningLevel();
+    const remaining = this.remaining();
+    switch (level) {
+      case WarningLevel.WARNING:
+        return `[Budget Warning] ${remaining} iterations remaining out of ${this._limit}. Start wrapping up your work.`;
+      case WarningLevel.WRAPPING_UP:
+        return `[Budget Critical] Only ${remaining} iterations remaining! Finish immediately and return your results.`;
+      case WarningLevel.EXHAUSTED:
+        return `[Budget Exhausted] No iterations remaining. Returning work summary.`;
+      default:
+        return null;
+    }
+  }
+}
+
+// ─── Defaults ───────────────────────────────────────────────────────────────
+
+export const DEFAULT_ITERATION_BUDGET = DEFAULT_BUDGET;
+export const BUDGET_WARNING_THRESHOLD = WARNING_THRESHOLD;
+export const BUDGET_WRAPPING_UP_THRESHOLD = WRAPPING_UP_THRESHOLD;

package/src/lib/learning/learning-hooks.js

@@ -0,0 +1,117 @@
+/**
+ * Learning Loop — Hook registration.
+ *
+ * Wires the TrajectoryStore into the existing hook infrastructure:
+ *   - UserPromptSubmit → startTrajectory()
+ *   - PostToolUse      → appendToolCall()
+ *   - SessionEnd       → (reserved for ReflectionEngine in P3)
+ *
+ * This module does NOT modify agent-core.js or agent-repl.js.
+ * Instead it provides an init function that the REPL calls once
+ * during session setup, passing a LearningLoop context object.
+ *
+ * Design:
+ *   - Fire-and-forget: learning failures never break the host flow
+ *   - No-op when learningCtx is null or disabled
+ *   - Stateless — the trajectory ID is tracked on learningCtx
+ */
+
+/**
+ * @typedef {object} LearningContext
+ * @property {import("./trajectory-store.js").TrajectoryStore} trajectoryStore
+ * @property {string|null} currentTrajectoryId — set per user turn
+ * @property {boolean} enabled
+ * @property {string} sessionId
+ */
+
+/**
+ * Called on UserPromptSubmit — starts a new trajectory for this turn.
+ * @param {LearningContext} ctx
+ * @param {string} prompt — the user's raw input
+ */
+export function onUserPromptSubmit(ctx, prompt) {
+  if (!ctx || !ctx.enabled || !ctx.trajectoryStore) return;
+  try {
+    ctx.currentTrajectoryId = ctx.trajectoryStore.startTrajectory(
+      ctx.sessionId,
+      prompt,
+    );
+  } catch (_err) {
+    // Learning failures never break the REPL
+    ctx.currentTrajectoryId = null;
+  }
+}
+
+/**
+ * Called on PostToolUse — appends a tool call to the current trajectory.
+ * @param {LearningContext} ctx
+ * @param {{tool:string, args:any, result:any, durationMs?:number, status?:string}} record
+ */
+export function onPostToolUse(ctx, record) {
+  if (!ctx || !ctx.enabled || !ctx.trajectoryStore || !ctx.currentTrajectoryId)
+    return;
+  try {
+    ctx.trajectoryStore.appendToolCall(ctx.currentTrajectoryId, record);
+  } catch (_err) {
+    // Swallow — never break the agent loop
+  }
+}
+
+/**
+ * Called on response-complete — completes the current trajectory.
+ * @param {LearningContext} ctx
+ * @param {{finalResponse?:string, tags?:string[]}} data
+ * @returns {object|null} completed trajectory or null
+ */
+export function onResponseComplete(ctx, data) {
+  if (!ctx || !ctx.enabled || !ctx.trajectoryStore || !ctx.currentTrajectoryId)
+    return null;
+  try {
+    const trajectory = ctx.trajectoryStore.completeTrajectory(
+      ctx.currentTrajectoryId,
+      data,
+    );
+    // Reset for next turn
+    const finishedId = ctx.currentTrajectoryId;
+    ctx.currentTrajectoryId = null;
+    return trajectory;
+  } catch (_err) {
+    ctx.currentTrajectoryId = null;
+    return null;
+  }
+}
+
+/**
+ * Called on SessionEnd — reserved for ReflectionEngine (P3).
+ * Currently a no-op placeholder.
+ * @param {LearningContext} ctx
+ */
+export function onSessionEnd(ctx) {
+  if (!ctx || !ctx.enabled) return;
+  // P3: will call reflectionEngine.onSessionEnd(ctx.sessionId)
+}
+
+/**
+ * Create a LearningContext for a session.
+ * Returns null if db is not available or learning is disabled.
+ *
+ * @param {import("better-sqlite3").Database|null} db
+ * @param {string} sessionId
+ * @param {{enabled?:boolean}} [config]
+ * @returns {LearningContext|null}
+ */
+export function createLearningContext(db, sessionId, config = {}) {
+  if (!db) return null;
+  const enabled = config.enabled !== false;
+  if (!enabled) return null;
+
+  // Lazy import to avoid circular deps — TrajectoryStore calls ensureLearningTables
+  const { TrajectoryStore } = require("./trajectory-store.js");
+
+  return {
+    trajectoryStore: new TrajectoryStore(db),
+    currentTrajectoryId: null,
+    enabled: true,
+    sessionId,
+  };
+}

package/src/lib/learning/learning-tables.js

@@ -0,0 +1,66 @@
+/**
+ * Learning Loop — Database table definitions.
+ *
+ * Tables:
+ *   - learning_trajectories    — full execution traces (intent → tools → response)
+ *   - learning_trajectory_tags — per-trajectory tag index for pattern matching
+ *   - skill_improvement_log    — skill patch history (Phase P2)
+ */
+
+/**
+ * Create all learning-related tables. Idempotent (IF NOT EXISTS).
+ * @param {import("better-sqlite3").Database} db
+ */
+export function ensureLearningTables(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS learning_trajectories (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL,
+      user_intent TEXT,
+      tool_chain TEXT NOT NULL DEFAULT '[]',
+      tool_count INTEGER DEFAULT 0,
+      final_response TEXT,
+      outcome_score REAL,
+      outcome_source TEXT,
+      complexity_level TEXT DEFAULT 'simple',
+      synthesized_skill TEXT,
+      created_at TEXT DEFAULT (datetime('now')),
+      completed_at TEXT
+    )
+  `);
+
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_traj_session
+      ON learning_trajectories(session_id)
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_traj_score
+      ON learning_trajectories(outcome_score)
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_traj_complexity
+      ON learning_trajectories(complexity_level)
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS learning_trajectory_tags (
+      trajectory_id TEXT NOT NULL,
+      tag TEXT NOT NULL,
+      UNIQUE(trajectory_id, tag)
+    )
+  `);
+
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_traj_tags_tid
+      ON learning_trajectory_tags(trajectory_id)
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS skill_improvement_log (
+      skill_name TEXT NOT NULL,
+      trigger_type TEXT NOT NULL,
+      detail TEXT,
+      created_at TEXT DEFAULT (datetime('now'))
+    )
+  `);
+}