chainlesschain 0.162.31 → 0.162.33

package/src/lib/goal-assess.js

@@ -0,0 +1,228 @@
+/**
+ * goal-assess — run-end LLM self-assessment of goal progress (cc goal Phase 2).
+ *
+ * After an agent run bound to a goal (--goal-assess), an LLM is asked to judge,
+ * from the run transcript, whether the goal advanced — and to propose key-result
+ * updates, a one-line progress note, and any concerns. The proposal is then
+ * persisted through goal-store (progress / key results / agent note / drift).
+ *
+ * This is OPT-IN because it spends extra tokens (one bonus completion per run).
+ * The LLM call is injected as `chat(promptString) => Promise<string>` so the
+ * orchestration is deterministically unit-testable without a provider.
+ *
+ * Parsing is deliberately tolerant: models wrap JSON in prose / code fences, so
+ * we extract the first balanced `{...}` block and validate the fields we use.
+ */
+
+import {
+  recordProgress,
+  setKeyResult,
+  addDriftFlags,
+  getGoal,
+} from "./goal-store.js";
+
+/** Bound the transcript we feed the judge so the assessment stays cheap. */
+const MAX_FINAL_TEXT = 2000;
+const MAX_TOOLS = 40;
+
+/**
+ * Build the assessment prompt. Asks for a strict JSON object describing whether
+ * the goal advanced + proposed updates.
+ * @param {object} goal
+ * @param {object} transcript { prompt, finalText, toolCalls:[{tool,args}] }
+ */
+export function buildAssessPrompt(goal, transcript = {}) {
+  const krLines = (goal.keyResults || [])
+    .map(
+      (k) =>
+        `  - id=${k.id} | "${k.text}"` +
+        (k.target != null ? ` | ${k.current ?? 0}/${k.target}` : "") +
+        (k.done ? " | DONE" : ""),
+    )
+    .join("\n");
+
+  const tools = (transcript.toolCalls || [])
+    .slice(0, MAX_TOOLS)
+    .map((t) => t.tool)
+    .join(", ");
+
+  const finalText = String(transcript.finalText || "").slice(0, MAX_FINAL_TEXT);
+
+  return [
+    "You are assessing whether a single agent run advanced a long-running goal.",
+    "",
+    `GOAL: ${goal.objective}`,
+    `CURRENT PROGRESS: ${goal.progress ?? 0}%`,
+    goal.keyResults?.length
+      ? `KEY RESULTS:\n${krLines}`
+      : "KEY RESULTS: (none)",
+    "",
+    `RUN TASK: ${String(transcript.prompt || "").slice(0, 500)}`,
+    tools ? `TOOLS USED: ${tools}` : "TOOLS USED: (none)",
+    `RUN RESULT:\n${finalText || "(no final text)"}`,
+    "",
+    "Reply with ONLY a JSON object (no prose, no code fence) of this shape:",
+    "{",
+    '  "advanced": true|false,            // did this run move the goal forward?',
+    '  "progress": <0-100 or null>,        // your estimate of new overall progress, or null to leave unchanged',
+    '  "keyResults": [                     // updates for specific key results (omit if none)',
+    '    {"id": "<kr-id>", "current": <number or null>, "done": true|false}',
+    "  ],",
+    '  "note": "<one short sentence summarizing what changed>",',
+    '  "concerns": ["<short concern>", ...]   // anything blocking/at-risk (omit if none)',
+    "}",
+  ].join("\n");
+}
+
+/**
+ * Tolerantly parse the judge's reply into a normalized assessment, or null.
+ * @param {string} text
+ * @returns {{advanced:boolean, progress:number|null, keyResults:object[], note:string, concerns:string[]}|null}
+ */
+export function parseAssessment(text) {
+  if (!text || typeof text !== "string") return null;
+  const json = extractFirstJsonObject(text);
+  if (!json) return null;
+  let obj;
+  try {
+    obj = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (!obj || typeof obj !== "object") return null;
+
+  const progress =
+    obj.progress == null || obj.progress === "" ? null : clampPct(obj.progress);
+
+  const keyResults = Array.isArray(obj.keyResults)
+    ? obj.keyResults
+        .filter((k) => k && k.id)
+        .map((k) => ({
+          id: String(k.id),
+          current:
+            k.current == null || k.current === "" ? null : Number(k.current),
+          done: k.done === true,
+        }))
+    : [];
+
+  const concerns = Array.isArray(obj.concerns)
+    ? obj.concerns.map((c) => String(c)).filter(Boolean)
+    : [];
+
+  return {
+    advanced: obj.advanced === true,
+    progress,
+    keyResults,
+    note: obj.note ? String(obj.note) : "",
+    concerns,
+  };
+}
+
+function clampPct(v) {
+  const n = Math.round(Number(v));
+  if (!Number.isFinite(n)) return null;
+  return Math.max(0, Math.min(100, n));
+}
+
+/** Extract the first balanced top-level {...} block from text (fence-tolerant). */
+function extractFirstJsonObject(text) {
+  const start = text.indexOf("{");
+  if (start < 0) return null;
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (ch === "\\") esc = true;
+      else if (ch === '"') inStr = false;
+      continue;
+    }
+    if (ch === '"') inStr = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+/**
+ * Persist a parsed assessment to the goal via goal-store. Each sub-update is
+ * isolated (a bad key-result id can't void the progress note). Returns the
+ * final goal state.
+ * @param {string} goalId
+ * @param {object} a  output of parseAssessment
+ * @param {object} [opts] { root }
+ */
+export function applyAssessment(goalId, a, opts = {}) {
+  if (!a) return getGoal(goalId, opts);
+
+  // Key-result updates first (they may drive derived progress).
+  for (const kr of a.keyResults || []) {
+    try {
+      setKeyResult(goalId, kr.id, { current: kr.current, done: kr.done }, opts);
+    } catch {
+      /* unknown / stale key-result id — skip, don't void the rest */
+    }
+  }
+
+  // Explicit progress and/or the agent note.
+  if (a.progress != null || a.note) {
+    try {
+      recordProgress(
+        goalId,
+        { pct: a.progress, note: a.note, by: "agent" },
+        opts,
+      );
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  // Drift: a no-advance run, plus any explicit concerns.
+  const flags = [];
+  if (!a.advanced) {
+    flags.push({ kind: "no-progress", detail: "run did not advance the goal" });
+  }
+  for (const c of a.concerns || []) flags.push({ kind: "concern", detail: c });
+  if (flags.length) {
+    try {
+      addDriftFlags(goalId, flags, opts);
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  return getGoal(goalId, opts);
+}
+
+/**
+ * Full orchestration: prompt → chat → parse → apply. Returns
+ * `{ assessment, goal }` (assessment is null when the judge gave no usable JSON).
+ * @param {object} params { goal, transcript, chat, opts }
+ *        chat: (promptString) => Promise<string>
+ */
+export async function assessGoalProgress({
+  goal,
+  transcript,
+  chat,
+  opts = {},
+}) {
+  if (!goal || typeof chat !== "function") {
+    return { assessment: null, goal: goal || null };
+  }
+  const prompt = buildAssessPrompt(goal, transcript);
+  let reply;
+  try {
+    reply = await chat(prompt);
+  } catch {
+    return { assessment: null, goal };
+  }
+  const assessment = parseAssessment(reply);
+  if (!assessment) return { assessment: null, goal };
+  const updated = applyAssessment(goal.id, assessment, opts);
+  return { assessment, goal: updated };
+}

package/src/lib/goal-context.js

@@ -0,0 +1,87 @@
+/**
+ * goal-context — turn-scoped injection of the active goal into the agent loop.
+ *
+ * When a goal is bound to a run, a compact reminder of its objective + open key
+ * results is supplemented into each LLM call (via agent-core's `prepareCall`
+ * seam), so every turn is measured against the goal without polluting the
+ * persistent message history.
+ *
+ * IMPORTANT: this composes WITH the existing `defaultPrepareCall` (turn-context)
+ * rather than replacing it — both suffixes are concatenated. Keep the produced
+ * text terse: it is re-sent on every iteration and is billed each time.
+ */
+
+/** Hard cap on the open key results we list, to bound per-turn token cost. */
+const MAX_KEY_RESULTS = 8;
+
+/**
+ * Build the compact system-prompt supplement for a goal, or null when the goal
+ * is missing / not active.
+ * @param {object|null} goal
+ * @returns {string|null}
+ */
+export function buildGoalContext(goal) {
+  if (!goal || goal.status !== "active") return null;
+  const objective = String(goal.objective || "").trim();
+  if (!objective) return null;
+
+  const pct = Number.isFinite(goal.progress) ? goal.progress : 0;
+  const lines = [`Active goal (${pct}% complete): ${objective}`];
+
+  const open = (goal.keyResults || []).filter((k) => k && !k.done);
+  for (const kr of open.slice(0, MAX_KEY_RESULTS)) {
+    const target =
+      kr.target != null ? ` [${kr.current ?? 0}/${kr.target}]` : "";
+    lines.push(`- key result: ${kr.text}${target}`);
+  }
+  if (open.length > MAX_KEY_RESULTS) {
+    lines.push(`- (+${open.length - MAX_KEY_RESULTS} more key results)`);
+  }
+
+  lines.push(
+    "Each turn, prefer actions that advance these key results; if you must diverge, briefly say why.",
+  );
+  return lines.join("\n");
+}
+
+/**
+ * A `prepareCall`-shaped function bound to a goal. Defensive: never throws
+ * (agent-core swallows prepareCall errors, but we avoid relying on that).
+ * @param {object|null} goal
+ * @returns {(ctx:object) => ({systemSuffix:string}|null)}
+ */
+export function goalPrepareCall(goal) {
+  return () => {
+    try {
+      const suffix = buildGoalContext(goal);
+      return suffix ? { systemSuffix: suffix } : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+/**
+ * Compose several `prepareCall` functions into one. Each is invoked per turn
+ * and their non-empty `systemSuffix` strings are concatenated. A failing
+ * member is skipped, never fatal.
+ * @param {Array<Function|null|undefined>} fns
+ * @returns {(ctx:object) => Promise<{systemSuffix:string}|null>}
+ */
+export function composePrepareCall(fns) {
+  const list = (fns || []).filter((f) => typeof f === "function");
+  return async (ctx) => {
+    const parts = [];
+    for (const fn of list) {
+      try {
+        const r = await fn(ctx);
+        if (r && typeof r.systemSuffix === "string" && r.systemSuffix.trim()) {
+          parts.push(r.systemSuffix);
+        }
+      } catch {
+        /* a failing member must not break the turn */
+      }
+    }
+    return parts.length ? { systemSuffix: parts.join("\n\n") } : null;
+  };
+}

package/src/lib/goal-store.js

@@ -0,0 +1,341 @@
+/**
+ * goal-store — cross-session persistent goals / OKRs for `cc goal`.
+ *
+ * Unlike a session (short-lived context) or a checkpoint (file state), a goal
+ * is a long-lived objective the agent should advance toward across many
+ * sessions. This is the standalone store + ops; wiring the goal into the agent
+ * loop (so each turn is measured against it) lives in goal-context.js.
+ *
+ * On-disk layout (under <home>/goals, overridable via opts.root for tests):
+ *   <root>/<id>.json        one goal per file
+ *
+ * Distinct from:
+ *   - cc session   (short-term conversation context)
+ *   - cc memory    (durable facts, not objectives)
+ *   - cc planmode  (a single run's plan, not a cross-session objective)
+ *   - cc workflow  (execution orchestration, not intent)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getHomeDir } from "./paths.js";
+
+/** Valid goal lifecycle states. `active` goals are the ones injected. */
+export const GOAL_STATUS = Object.freeze({
+  ACTIVE: "active",
+  PAUSED: "paused",
+  DONE: "done",
+  ABANDONED: "abandoned",
+});
+
+const STATUS_VALUES = new Set(Object.values(GOAL_STATUS));
+
+function defaultRoot() {
+  return path.join(getHomeDir(), "goals");
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function newId(prefix) {
+  // Date.now/random are fine here (plain CLI lib, not a resumable workflow).
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${prefix}-${Date.now()}-${rand}`;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function goalFile(root, id) {
+  return path.join(root, `${id}.json`);
+}
+
+/** Clamp a value to a 0–100 integer percentage, or null when not a number. */
+function clampPct(v) {
+  if (v == null || v === "") return null;
+  const n = Math.round(Number(v));
+  if (!Number.isFinite(n)) return null;
+  return Math.max(0, Math.min(100, n));
+}
+
+/**
+ * Derive a 0–100 progress from completed key results. Returns null when there
+ * are no key results (caller may keep a manually-set progress instead).
+ */
+function derivedProgress(keyResults) {
+  if (!Array.isArray(keyResults) || keyResults.length === 0) return null;
+  const done = keyResults.filter((k) => k.done).length;
+  return Math.round((done / keyResults.length) * 100);
+}
+
+/**
+ * Create a goal.
+ * @param {object} input { objective, title, keyResults?: string[]|object[] }
+ * @param {object} [opts] { root }
+ * @returns {object} the persisted goal
+ */
+export function createGoal(input = {}, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const objective = String(input.objective || "").trim();
+  if (!objective) {
+    throw new Error("createGoal requires an objective");
+  }
+  const id = input.id || newId("goal");
+  const keyResults = (input.keyResults || []).map((kr) => normalizeKr(kr));
+  const goal = {
+    id,
+    title: String(input.title || objective).trim(),
+    objective,
+    keyResults,
+    status: GOAL_STATUS.ACTIVE,
+    progress: derivedProgress(keyResults) ?? 0,
+    linkedSessions: [],
+    notes: [],
+    drift: { lastProgressAt: null, flags: [] },
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  };
+  ensureDir(root);
+  fs.writeFileSync(goalFile(root, id), JSON.stringify(goal, null, 2), "utf-8");
+  return goal;
+}
+
+function normalizeKr(kr) {
+  if (typeof kr === "string") {
+    return {
+      id: newId("kr"),
+      text: kr.trim(),
+      target: null,
+      current: 0,
+      done: false,
+    };
+  }
+  return {
+    id: kr.id || newId("kr"),
+    text: String(kr.text || "").trim(),
+    target: kr.target == null ? null : Number(kr.target),
+    current: Number(kr.current) || 0,
+    done: !!kr.done,
+  };
+}
+
+/** Load a goal by id, or null. */
+export function getGoal(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const file = goalFile(root, id);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function saveGoal(goal, opts = {}) {
+  const root = opts.root || defaultRoot();
+  ensureDir(root);
+  goal.updatedAt = nowIso();
+  fs.writeFileSync(
+    goalFile(root, goal.id),
+    JSON.stringify(goal, null, 2),
+    "utf-8",
+  );
+  return goal;
+}
+
+/** List goals, newest first. Optionally filter by status. */
+export function listGoals(opts = {}) {
+  const root = opts.root || defaultRoot();
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(root)) {
+    if (!name.endsWith(".json")) continue;
+    const g = getGoal(name.slice(0, -5), { root });
+    if (!g) continue;
+    if (opts.status && g.status !== opts.status) continue;
+    out.push(g);
+  }
+  return out.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+}
+
+/** Mutate a goal via `fn(goal)`; throws if not found. */
+function mutate(id, fn, opts = {}) {
+  const goal = getGoal(id, opts);
+  if (!goal) throw new Error(`no such goal: ${id}`);
+  fn(goal);
+  return saveGoal(goal, opts);
+}
+
+/** Add a key result to a goal. */
+export function addKeyResult(id, text, krOpts = {}, opts = {}) {
+  return mutate(
+    id,
+    (g) => {
+      g.keyResults.push(normalizeKr({ text, target: krOpts.target }));
+      const dp = derivedProgress(g.keyResults);
+      if (dp != null) g.progress = dp;
+    },
+    opts,
+  );
+}
+
+/** Update a key result (current value and/or done flag). */
+export function setKeyResult(id, krId, patch = {}, opts = {}) {
+  return mutate(
+    id,
+    (g) => {
+      const kr = g.keyResults.find((k) => k.id === krId);
+      if (!kr) throw new Error(`no such key result: ${krId}`);
+      if (patch.current != null) kr.current = Number(patch.current);
+      if (patch.done != null) kr.done = !!patch.done;
+      if (
+        kr.target != null &&
+        patch.current != null &&
+        Number(patch.current) >= kr.target
+      ) {
+        kr.done = true;
+      }
+      const dp = derivedProgress(g.keyResults);
+      if (dp != null) g.progress = dp;
+      g.drift.lastProgressAt = nowIso();
+    },
+    opts,
+  );
+}
+
+/**
+ * Record progress: set an explicit percentage and/or append a note.
+ * @param {object} input { pct?, note?, by? }
+ */
+export function recordProgress(id, input = {}, opts = {}) {
+  return mutate(
+    id,
+    (g) => {
+      const pct = clampPct(input.pct);
+      if (pct != null) g.progress = pct;
+      if (input.note) {
+        g.notes.push({
+          at: nowIso(),
+          text: String(input.note),
+          by: input.by === "agent" ? "agent" : "user",
+        });
+      }
+      g.drift.lastProgressAt = nowIso();
+    },
+    opts,
+  );
+}
+
+/** Attach a session id to a goal (idempotent). */
+export function linkSession(id, sessionId, opts = {}) {
+  if (!sessionId) throw new Error("linkSession requires a sessionId");
+  return mutate(
+    id,
+    (g) => {
+      if (!g.linkedSessions.includes(sessionId)) {
+        g.linkedSessions.push(sessionId);
+      }
+    },
+    opts,
+  );
+}
+
+/** Detach a session id from a goal. */
+export function unlinkSession(id, sessionId, opts = {}) {
+  return mutate(
+    id,
+    (g) => {
+      g.linkedSessions = g.linkedSessions.filter((s) => s !== sessionId);
+    },
+    opts,
+  );
+}
+
+/** Set a goal's status (active/paused/done/abandoned). */
+export function setStatus(id, status, opts = {}) {
+  if (!STATUS_VALUES.has(status)) {
+    throw new Error(
+      `invalid status "${status}" — expected one of: ${[...STATUS_VALUES].join(", ")}`,
+    );
+  }
+  return mutate(
+    id,
+    (g) => {
+      g.status = status;
+      if (status === GOAL_STATUS.DONE && g.progress < 100) g.progress = 100;
+    },
+    opts,
+  );
+}
+
+/**
+ * Append drift flags to a goal's `drift.flags` list. Each flag is normalized to
+ * `{ at, kind, detail }`. Used by the run-end assessment (cc goal Phase 2) to
+ * record "no progress this run" / concern signals. Capped at 20 (newest kept).
+ * @param {string} id
+ * @param {Array<string|object>} flags
+ */
+export function addDriftFlags(id, flags, opts = {}) {
+  const list = (Array.isArray(flags) ? flags : [flags]).filter(Boolean);
+  if (list.length === 0) return getGoal(id, opts);
+  return mutate(
+    id,
+    (g) => {
+      for (const f of list) {
+        const flag =
+          typeof f === "string"
+            ? { at: nowIso(), kind: "concern", detail: f }
+            : {
+                at: nowIso(),
+                kind: f.kind || "concern",
+                detail: f.detail || "",
+              };
+        g.drift.flags.push(flag);
+      }
+      // Keep only the most recent 20 to bound the file size.
+      if (g.drift.flags.length > 20) {
+        g.drift.flags = g.drift.flags.slice(-20);
+      }
+    },
+    opts,
+  );
+}
+
+/** Delete a goal. Returns true if it existed. */
+export function deleteGoal(id, opts = {}) {
+  const root = opts.root || defaultRoot();
+  const file = goalFile(root, id);
+  if (!fs.existsSync(file)) return false;
+  fs.rmSync(file);
+  return true;
+}
+
+/**
+ * Resolve the goal that should be bound to the current run, in priority order:
+ *   1. explicit id (--goal <id>)
+ *   2. an active goal linked to the current session
+ *   3. when exactly one active goal exists, that one
+ *   4. null
+ *
+ * Only `active` goals are ever auto-resolved (steps 2–3); an explicit id is
+ * honored regardless of status so a user can re-inspect a paused goal.
+ *
+ * @param {object} [sel] { explicitId, sessionId }
+ * @param {object} [opts] { root }
+ */
+export function resolveActiveGoal(sel = {}, opts = {}) {
+  if (sel.explicitId) {
+    return getGoal(sel.explicitId, opts);
+  }
+  const active = listGoals({ ...opts, status: GOAL_STATUS.ACTIVE });
+  if (active.length === 0) return null;
+  if (sel.sessionId) {
+    const linked = active.find((g) => g.linkedSessions.includes(sel.sessionId));
+    if (linked) return linked;
+  }
+  if (active.length === 1) return active[0];
+  // Ambiguous (multiple active, none linked) — caller must pick explicitly.
+  return null;
+}