chainlesschain 0.45.66 → 0.45.70

package/src/lib/ws-session-manager.js

@@ -349,6 +349,10 @@ export class WSSessionManager {
       planManager,
       contextEngine,
       permanentMemory,
+      reviewState: null,
+      pendingPatches: new Map(),
+      patchHistory: [],
+      taskGraph: null,
       interaction: null, // Set by ws-server after creation
       createdAt: new Date().toISOString(),
       lastActivity: new Date().toISOString(),
@@ -456,6 +460,12 @@ export class WSSessionManager {
         planManager,
         contextEngine,
         permanentMemory,
+        reviewState: metadata.reviewState || null,
+        pendingPatches: this._hydratePendingPatches(metadata.pendingPatches),
+        patchHistory: Array.isArray(metadata.patchHistory)
+          ? metadata.patchHistory
+          : [],
+        taskGraph: this._hydrateTaskGraph(metadata.taskGraph),
         interaction: null,
         createdAt: dbSession.created_at,
         lastActivity: new Date().toISOString(),
@@ -611,6 +621,583 @@ export class WSSessionManager {
     return session;
   }
 
+  /**
+   * Enter explicit review mode for a session. While in review, handlers
+   * MUST gate new sendMessage calls until the review is resolved. Reviewer
+   * sub-agents and human reviewers both feed into the same `comments` /
+   * `checklist` arrays.
+   *
+   * @param {string} sessionId
+   * @param {{
+   *   reason?: string,
+   *   requestedBy?: string,
+   *   checklist?: Array<{ id?: string, title: string, note?: string }>,
+   *   blocking?: boolean,
+   * }} [options]
+   */
+  enterReview(sessionId, options = {}) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+
+    // If already in pending review, return the existing state unchanged so
+    // callers can retry safely.
+    if (session.reviewState && session.reviewState.status === "pending") {
+      return session.reviewState;
+    }
+
+    const reviewId = `review-${this._generateId()}`;
+    const now = new Date().toISOString();
+    const checklist = Array.isArray(options.checklist)
+      ? options.checklist.map((item, index) => ({
+          id: item.id || `chk-${index}-${Date.now()}`,
+          title: item.title || `Item ${index + 1}`,
+          note: item.note || null,
+          done: false,
+        }))
+      : [];
+
+    session.reviewState = {
+      reviewId,
+      status: "pending",
+      reason: options.reason || null,
+      requestedBy: options.requestedBy || "user",
+      requestedAt: now,
+      resolvedAt: null,
+      resolvedBy: null,
+      decision: null,
+      blocking: options.blocking !== false,
+      comments: [],
+      checklist,
+    };
+    session.lastActivity = now;
+    this._persistSessionState(sessionId);
+    return session.reviewState;
+  }
+
+  /**
+   * Submit an incremental update to the active review — append a comment
+   * and/or toggle a checklist item. Returns the updated reviewState, or null
+   * if the session has no active review.
+   *
+   * @param {string} sessionId
+   * @param {{
+   *   comment?: { author?: string, content: string },
+   *   checklistItemId?: string,
+   *   checklistItemDone?: boolean,
+   *   checklistItemNote?: string,
+   * }} update
+   */
+  submitReviewComment(sessionId, update = {}) {
+    const session = this.sessions.get(sessionId);
+    if (!session || !session.reviewState) return null;
+    if (session.reviewState.status !== "pending") return null;
+
+    const now = new Date().toISOString();
+
+    if (update.comment && update.comment.content) {
+      session.reviewState.comments.push({
+        id: `cmt-${session.reviewState.comments.length}-${Date.now()}`,
+        author: update.comment.author || "user",
+        content: String(update.comment.content),
+        timestamp: now,
+      });
+    }
+
+    if (update.checklistItemId) {
+      const item = session.reviewState.checklist.find(
+        (c) => c.id === update.checklistItemId,
+      );
+      if (item) {
+        if (typeof update.checklistItemDone === "boolean") {
+          item.done = update.checklistItemDone;
+        }
+        if (typeof update.checklistItemNote === "string") {
+          item.note = update.checklistItemNote;
+        }
+      }
+    }
+
+    session.lastActivity = now;
+    this._persistSessionState(sessionId);
+    return session.reviewState;
+  }
+
+  /**
+   * Resolve the active review with an approved/rejected decision. After
+   * resolve the session can accept new messages again (reviewState becomes
+   * non-blocking but is retained for audit).
+   *
+   * @param {string} sessionId
+   * @param {{ decision: "approved"|"rejected", resolvedBy?: string, summary?: string }} payload
+   */
+  resolveReview(sessionId, payload = {}) {
+    const session = this.sessions.get(sessionId);
+    if (!session || !session.reviewState) return null;
+    if (session.reviewState.status !== "pending") {
+      return session.reviewState;
+    }
+
+    const decision =
+      payload.decision === "approved" || payload.decision === "rejected"
+        ? payload.decision
+        : "approved";
+
+    session.reviewState.status = decision;
+    session.reviewState.decision = decision;
+    session.reviewState.resolvedAt = new Date().toISOString();
+    session.reviewState.resolvedBy = payload.resolvedBy || "user";
+    session.reviewState.blocking = false;
+    if (payload.summary) {
+      session.reviewState.summary = String(payload.summary);
+    }
+
+    session.lastActivity = session.reviewState.resolvedAt;
+    this._persistSessionState(sessionId);
+    return session.reviewState;
+  }
+
+  /**
+   * Returns true when the session currently has a blocking review gate
+   * open. Callers (e.g. handleSessionMessage) should short-circuit with a
+   * REVIEW_BLOCKING error instead of running the agent turn.
+   */
+  isReviewBlocking(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session || !session.reviewState) return false;
+    return (
+      session.reviewState.status === "pending" &&
+      session.reviewState.blocking === true
+    );
+  }
+
+  getReviewState(sessionId) {
+    const session = this.sessions.get(sessionId);
+    return session ? session.reviewState || null : null;
+  }
+
+  /**
+   * Record a proposed patch on the session. Accepts one or more file hunks
+   * that a tool wanted to write but should be previewed before they land.
+   *
+   * @param {string} sessionId
+   * @param {{
+   *   files: Array<{
+   *     path: string,
+   *     op?: "create"|"modify"|"delete",
+   *     before?: string|null,
+   *     after?: string|null,
+   *     diff?: string|null,
+   *     stats?: { added?: number, removed?: number }
+   *   }>,
+   *   origin?: string,
+   *   reason?: string,
+   *   requestId?: string|null
+   * }} payload
+   * @returns {object|null} patch record, or null if the session is missing
+   */
+  proposePatch(sessionId, payload = {}) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+
+    const files = Array.isArray(payload.files) ? payload.files : [];
+    if (files.length === 0) return null;
+
+    const patchId = `patch-${this._generateId()}`;
+    const now = new Date().toISOString();
+    const normalizedFiles = files.map((file, index) => {
+      const op = file.op || (file.before == null ? "create" : "modify");
+      const stats = this._computePatchStats(file);
+      return {
+        index,
+        path: file.path || `unknown-${index}`,
+        op,
+        before: file.before == null ? null : String(file.before),
+        after: file.after == null ? null : String(file.after),
+        diff: file.diff == null ? null : String(file.diff),
+        stats,
+      };
+    });
+
+    const totalStats = normalizedFiles.reduce(
+      (acc, file) => ({
+        added: acc.added + (file.stats.added || 0),
+        removed: acc.removed + (file.stats.removed || 0),
+      }),
+      { added: 0, removed: 0 },
+    );
+
+    const patch = {
+      patchId,
+      status: "pending",
+      origin: payload.origin || "tool",
+      reason: payload.reason || null,
+      requestId: payload.requestId || null,
+      proposedAt: now,
+      resolvedAt: null,
+      resolvedBy: null,
+      files: normalizedFiles,
+      stats: {
+        fileCount: normalizedFiles.length,
+        added: totalStats.added,
+        removed: totalStats.removed,
+      },
+    };
+
+    if (!(session.pendingPatches instanceof Map)) {
+      session.pendingPatches = new Map();
+    }
+    session.pendingPatches.set(patchId, patch);
+    session.lastActivity = now;
+    this._persistSessionState(sessionId);
+    return patch;
+  }
+
+  /**
+   * Mark a pending patch as applied. Moves the record to patchHistory so it
+   * is still visible in the summary view but no longer counts as pending.
+   */
+  applyPatch(sessionId, patchId, options = {}) {
+    const session = this.sessions.get(sessionId);
+    if (!session || !(session.pendingPatches instanceof Map)) return null;
+    const patch = session.pendingPatches.get(patchId);
+    if (!patch) return null;
+
+    patch.status = "applied";
+    patch.resolvedAt = new Date().toISOString();
+    patch.resolvedBy = options.resolvedBy || "user";
+    if (options.note) {
+      patch.note = String(options.note);
+    }
+
+    session.pendingPatches.delete(patchId);
+    if (!Array.isArray(session.patchHistory)) {
+      session.patchHistory = [];
+    }
+    session.patchHistory.push(patch);
+    session.lastActivity = patch.resolvedAt;
+    this._persistSessionState(sessionId);
+    return patch;
+  }
+
+  /**
+   * Discard a pending patch. Same bookkeeping as applyPatch but records a
+   * "rejected" decision instead.
+   */
+  rejectPatch(sessionId, patchId, options = {}) {
+    const session = this.sessions.get(sessionId);
+    if (!session || !(session.pendingPatches instanceof Map)) return null;
+    const patch = session.pendingPatches.get(patchId);
+    if (!patch) return null;
+
+    patch.status = "rejected";
+    patch.resolvedAt = new Date().toISOString();
+    patch.resolvedBy = options.resolvedBy || "user";
+    if (options.reason) {
+      patch.rejectionReason = String(options.reason);
+    }
+
+    session.pendingPatches.delete(patchId);
+    if (!Array.isArray(session.patchHistory)) {
+      session.patchHistory = [];
+    }
+    session.patchHistory.push(patch);
+    session.lastActivity = patch.resolvedAt;
+    this._persistSessionState(sessionId);
+    return patch;
+  }
+
+  /**
+   * Return a flattened summary of all pending + resolved patches on the
+   * session. Shape matches what the renderer strip consumes:
+   *   { pending: [...], history: [...], totals: { added, removed, fileCount } }
+   */
+  getPatchSummary(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+
+    const pending =
+      session.pendingPatches instanceof Map
+        ? Array.from(session.pendingPatches.values())
+        : [];
+    const history = Array.isArray(session.patchHistory)
+      ? session.patchHistory
+      : [];
+
+    const totals = [...pending, ...history].reduce(
+      (acc, patch) => ({
+        fileCount: acc.fileCount + (patch.stats?.fileCount || 0),
+        added: acc.added + (patch.stats?.added || 0),
+        removed: acc.removed + (patch.stats?.removed || 0),
+      }),
+      { fileCount: 0, added: 0, removed: 0 },
+    );
+
+    return { pending, history, totals };
+  }
+
+  hasPendingPatches(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session || !(session.pendingPatches instanceof Map)) return false;
+    return session.pendingPatches.size > 0;
+  }
+
+  _computePatchStats(file) {
+    if (file && file.stats && typeof file.stats === "object") {
+      return {
+        added: Number(file.stats.added) || 0,
+        removed: Number(file.stats.removed) || 0,
+      };
+    }
+    const before = file && typeof file.before === "string" ? file.before : "";
+    const after = file && typeof file.after === "string" ? file.after : "";
+    const beforeLines = before ? before.split(/\r?\n/).length : 0;
+    const afterLines = after ? after.split(/\r?\n/).length : 0;
+    // Rough heuristic when no explicit diff is provided: full replace counts
+    // the entire file as added/removed.
+    if (!before && after) return { added: afterLines, removed: 0 };
+    if (before && !after) return { added: 0, removed: beforeLines };
+    return {
+      added: Math.max(0, afterLines - beforeLines),
+      removed: Math.max(0, beforeLines - afterLines),
+    };
+  }
+
+  /**
+   * Create or replace the task graph for a session. A graph is a DAG of
+   * `nodes` keyed by id; each node has `{ id, title, status, dependsOn[],
+   * metadata }`. Returns the serialized graph.
+   */
+  createTaskGraph(sessionId, payload = {}) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+
+    const graphId = payload.graphId || `graph-${this._generateId()}`;
+    const now = new Date().toISOString();
+    const nodes = {};
+    const incomingNodes = Array.isArray(payload.nodes) ? payload.nodes : [];
+    for (const raw of incomingNodes) {
+      if (!raw || !raw.id) continue;
+      nodes[raw.id] = this._normalizeTaskNode(raw, now);
+    }
+
+    const graph = {
+      graphId,
+      title: payload.title || null,
+      description: payload.description || null,
+      status: "active",
+      createdAt: now,
+      updatedAt: now,
+      completedAt: null,
+      nodes,
+      order: Object.keys(nodes),
+    };
+
+    session.taskGraph = graph;
+    session.lastActivity = now;
+    this._persistSessionState(sessionId);
+    return this._cloneTaskGraph(graph);
+  }
+
+  /**
+   * Add a node to the existing task graph. Fails if no graph exists or if
+   * the node id already exists.
+   */
+  addTaskNode(sessionId, payload = {}) {
+    const session = this.sessions.get(sessionId);
+    if (!session || !session.taskGraph) return null;
+    if (!payload || !payload.id) return null;
+    const graph = session.taskGraph;
+    if (graph.nodes[payload.id]) return null;
+
+    const now = new Date().toISOString();
+    graph.nodes[payload.id] = this._normalizeTaskNode(payload, now);
+    graph.order = [...(graph.order || []), payload.id];
+    graph.updatedAt = now;
+    session.lastActivity = now;
+    this._persistSessionState(sessionId);
+    return this._cloneTaskGraph(graph);
+  }
+
+  /**
+   * Update a node's status / metadata. Valid statuses: pending, ready,
+   * running, completed, failed, skipped.
+   */
+  updateTaskNode(sessionId, nodeId, updates = {}) {
+    const session = this.sessions.get(sessionId);
+    if (!session || !session.taskGraph) return null;
+    const graph = session.taskGraph;
+    const node = graph.nodes[nodeId];
+    if (!node) return null;
+
+    const now = new Date().toISOString();
+    if (updates.status) {
+      node.status = String(updates.status);
+      if (node.status === "running" && !node.startedAt) {
+        node.startedAt = now;
+      }
+      if (
+        node.status === "completed" ||
+        node.status === "failed" ||
+        node.status === "skipped"
+      ) {
+        node.completedAt = now;
+      }
+    }
+    if (updates.title !== undefined) node.title = updates.title;
+    if (updates.result !== undefined) node.result = updates.result;
+    if (updates.error !== undefined) node.error = updates.error;
+    if (updates.metadata !== undefined) {
+      node.metadata = { ...(node.metadata || {}), ...(updates.metadata || {}) };
+    }
+    node.updatedAt = now;
+    graph.updatedAt = now;
+
+    // Check graph completion
+    const allDone = Object.values(graph.nodes).every((n) =>
+      ["completed", "failed", "skipped"].includes(n.status),
+    );
+    if (allDone) {
+      graph.status = Object.values(graph.nodes).some(
+        (n) => n.status === "failed",
+      )
+        ? "failed"
+        : "completed";
+      graph.completedAt = now;
+    }
+
+    session.lastActivity = now;
+    this._persistSessionState(sessionId);
+    return this._cloneTaskGraph(graph);
+  }
+
+  /**
+   * Advance the task graph: mark any `pending` node whose dependencies are
+   * all `completed` (or `skipped`) as `ready`. Returns the list of node ids
+   * that became ready and the updated graph snapshot.
+   */
+  advanceTaskGraph(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session || !session.taskGraph) return null;
+    const graph = session.taskGraph;
+
+    const becameReady = [];
+    for (const node of Object.values(graph.nodes)) {
+      if (node.status !== "pending") continue;
+      const deps = Array.isArray(node.dependsOn) ? node.dependsOn : [];
+      const blocked = deps.some((depId) => {
+        const dep = graph.nodes[depId];
+        if (!dep) return true;
+        return dep.status !== "completed" && dep.status !== "skipped";
+      });
+      if (!blocked) {
+        node.status = "ready";
+        node.updatedAt = new Date().toISOString();
+        becameReady.push(node.id);
+      }
+    }
+
+    if (becameReady.length > 0) {
+      graph.updatedAt = new Date().toISOString();
+      session.lastActivity = graph.updatedAt;
+      this._persistSessionState(sessionId);
+    }
+
+    return {
+      graph: this._cloneTaskGraph(graph),
+      becameReady,
+    };
+  }
+
+  getTaskGraph(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session || !session.taskGraph) return null;
+    return this._cloneTaskGraph(session.taskGraph);
+  }
+
+  clearTaskGraph(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+    session.taskGraph = null;
+    session.lastActivity = new Date().toISOString();
+    this._persistSessionState(sessionId);
+    return true;
+  }
+
+  _normalizeTaskNode(raw, now) {
+    const status = raw.status || "pending";
+    return {
+      id: raw.id,
+      title: raw.title || raw.id,
+      description: raw.description || null,
+      status,
+      dependsOn: Array.isArray(raw.dependsOn)
+        ? raw.dependsOn.filter((x) => typeof x === "string")
+        : [],
+      metadata:
+        raw.metadata && typeof raw.metadata === "object" ? raw.metadata : {},
+      createdAt: raw.createdAt || now,
+      updatedAt: raw.updatedAt || now,
+      startedAt: raw.startedAt || null,
+      completedAt: raw.completedAt || null,
+      result: raw.result || null,
+      error: raw.error || null,
+    };
+  }
+
+  _cloneTaskGraph(graph) {
+    if (!graph) return null;
+    return {
+      graphId: graph.graphId,
+      title: graph.title,
+      description: graph.description,
+      status: graph.status,
+      createdAt: graph.createdAt,
+      updatedAt: graph.updatedAt,
+      completedAt: graph.completedAt,
+      order: Array.isArray(graph.order)
+        ? [...graph.order]
+        : Object.keys(graph.nodes || {}),
+      nodes: Object.fromEntries(
+        Object.entries(graph.nodes || {}).map(([id, node]) => [
+          id,
+          {
+            ...node,
+            dependsOn: [...(node.dependsOn || [])],
+            metadata: { ...(node.metadata || {}) },
+          },
+        ]),
+      ),
+    };
+  }
+
+  _hydrateTaskGraph(data) {
+    if (!data || typeof data !== "object") return null;
+    if (!data.graphId || !data.nodes) return null;
+    const nodes = {};
+    for (const [id, node] of Object.entries(data.nodes)) {
+      nodes[id] = this._normalizeTaskNode(
+        { ...node, id },
+        node.createdAt || new Date().toISOString(),
+      );
+    }
+    return {
+      graphId: data.graphId,
+      title: data.title || null,
+      description: data.description || null,
+      status: data.status || "active",
+      createdAt: data.createdAt || new Date().toISOString(),
+      updatedAt: data.updatedAt || new Date().toISOString(),
+      completedAt: data.completedAt || null,
+      order: Array.isArray(data.order) ? data.order : Object.keys(nodes),
+      nodes,
+    };
+  }
+
+  _serializeTaskGraph(graph) {
+    if (!graph) return null;
+    return this._cloneTaskGraph(graph);
+  }
+
   /**
    * Persist current messages for a session.
    */
@@ -689,9 +1276,30 @@ export class WSSessionManager {
       worktreeIsolation: session.worktreeIsolation === true,
       worktree: session.worktree || null,
       planSnapshot: this._serializePlanManager(session.planManager),
+      reviewState: session.reviewState || null,
+      pendingPatches:
+        session.pendingPatches instanceof Map
+          ? Array.from(session.pendingPatches.values())
+          : [],
+      patchHistory: Array.isArray(session.patchHistory)
+        ? session.patchHistory
+        : [],
+      taskGraph: this._serializeTaskGraph(session.taskGraph),
     };
   }
 
+  _hydratePendingPatches(list) {
+    const map = new Map();
+    if (Array.isArray(list)) {
+      for (const patch of list) {
+        if (patch && patch.patchId) {
+          map.set(patch.patchId, patch);
+        }
+      }
+    }
+    return map;
+  }
+
   _serializePlanManager(planManager) {
     if (!planManager) {
       return null;

package/src/runtime/coding-agent-events.cjs

@@ -78,6 +78,50 @@ const CODING_AGENT_EVENT_TYPES = Object.freeze({
   SERVER_STARTING: "runtime.server.starting",
   SERVER_READY: "runtime.server.ready",
   SERVER_STOPPED: "runtime.server.stopped",
+
+  // Sub-agent delegation — lifecycle of child agents spawned from a parent
+  // session via the spawn_sub_agent tool. Sequence within a parent requestId
+  // stays strictly increasing; parent session + sub-agent id are carried in
+  // the payload so UIs can group child events under the parent turn.
+  SUB_AGENT_STARTED: "sub-agent.started",
+  SUB_AGENT_PROGRESS: "sub-agent.progress",
+  SUB_AGENT_COMPLETED: "sub-agent.completed",
+  SUB_AGENT_FAILED: "sub-agent.failed",
+  SUB_AGENT_LIST: "sub-agent.list",
+
+  // Review mode — explicit human-in-the-loop (or reviewer sub-agent) gate.
+  // When a session enters review mode the runtime MUST block sendMessage
+  // until the review is resolved (approved / rejected). Comments can be
+  // submitted incrementally by either human reviewers via the UI or by a
+  // reviewer role sub-agent writing async findings back to the parent
+  // session.
+  REVIEW_REQUESTED: "review.requested",
+  REVIEW_UPDATED: "review.updated",
+  REVIEW_RESOLVED: "review.resolved",
+  REVIEW_STATE: "review.state",
+
+  // Patch preview / diff summary — proposed file edits that the user can
+  // preview, approve (apply) or reject before they land on disk. Used to
+  // surface a "diff summary" strip in the UI that batches multiple writes
+  // from a single turn into a reviewable hunk list.
+  PATCH_PROPOSED: "patch.proposed",
+  PATCH_APPLIED: "patch.applied",
+  PATCH_REJECTED: "patch.rejected",
+  PATCH_SUMMARY: "patch.summary",
+
+  // Persistent task graph + orchestrator — a session-scoped DAG of tasks
+  // with dependencies. The runtime serializes the graph to session metadata
+  // so it survives CLI restarts; the orchestrator advances the graph by
+  // marking ready nodes as `running` when their dependencies complete.
+  TASK_GRAPH_CREATED: "task-graph.created",
+  TASK_GRAPH_UPDATED: "task-graph.updated",
+  TASK_GRAPH_NODE_ADDED: "task-graph.node.added",
+  TASK_GRAPH_NODE_UPDATED: "task-graph.node.updated",
+  TASK_GRAPH_NODE_COMPLETED: "task-graph.node.completed",
+  TASK_GRAPH_NODE_FAILED: "task-graph.node.failed",
+  TASK_GRAPH_ADVANCED: "task-graph.advanced",
+  TASK_GRAPH_COMPLETED: "task-graph.completed",
+  TASK_GRAPH_STATE: "task-graph.state",
 });
 
 const VALID_TYPE_SET = new Set(Object.values(CODING_AGENT_EVENT_TYPES));
@@ -330,6 +374,7 @@ const CodingAgentEventType = Object.freeze({
   SERVER_STOPPED: CODING_AGENT_EVENT_TYPES.SERVER_STOPPED,
   SESSION_CREATED: CODING_AGENT_EVENT_TYPES.SESSION_STARTED,
   SESSION_RESUMED: CODING_AGENT_EVENT_TYPES.SESSION_RESUMED,
+  SESSION_INTERRUPTED: CODING_AGENT_EVENT_TYPES.SESSION_INTERRUPTED,
   SESSION_CLOSED: CODING_AGENT_EVENT_TYPES.SESSION_CLOSED,
   SESSION_LIST: CODING_AGENT_EVENT_TYPES.SESSION_LIST,
   WORKTREE_LIST: CODING_AGENT_EVENT_TYPES.WORKTREE_LIST,