@cardor/agent-harness-kit 2.3.1 → 2.4.0

package/dist/cli.js

@@ -12,7 +12,7 @@ import {
   resolveGlobalStorageDir,
   resolveSqlitePath,
   resolveSqlitePathForScope
-} from "./chunk-JTACLEGM.js";
+} from "./chunk-TWG3KVZQ.js";
 
 // src/cli.ts
 import { Command, InvalidArgumentError } from "commander";
@@ -2735,7 +2735,7 @@ async function runMigrateStorage(cwd2, opts, homeDir = homedir3()) {
 }
 async function probeTaskCount(dbPath) {
   if (!existsSync15(dbPath)) return 0;
-  const { SQLiteDriver } = await import("./sqlite-5OWKTUUZ.js");
+  const { SQLiteDriver } = await import("./sqlite-UDXCFIEN.js");
   const driver = new SQLiteDriver(dbPath);
   try {
     await driver.ensureSchema();
@@ -2756,7 +2756,7 @@ async function migrateScopeOnly(cwd2, config, homeDir, fromScope, toScope, opts)
   }
   const destExists = existsSync15(destDb);
   if (destExists) {
-    const { SQLiteDriver } = await import("./sqlite-5OWKTUUZ.js");
+    const { SQLiteDriver } = await import("./sqlite-UDXCFIEN.js");
     const destDriver = new SQLiteDriver(destDb);
     let destEmpty;
     try {
@@ -2771,12 +2771,12 @@ async function migrateScopeOnly(cwd2, config, homeDir, fromScope, toScope, opts)
       );
     }
     if (!destEmpty && opts.force) {
-      const { SQLiteDriver: Driver } = await import("./sqlite-5OWKTUUZ.js");
+      const { SQLiteDriver: Driver } = await import("./sqlite-UDXCFIEN.js");
       const backupDriver = new Driver(destDb);
       let data;
       try {
         await backupDriver.ensureSchema();
-        const { HarnessDB } = await import("./db-L3AADJF5.js");
+        const { HarnessDB } = await import("./db-3B2W2EBA.js");
         const tmpDb = new HarnessDB(backupDriver, config, homeDir);
         data = await tmpDb.exportJson();
       } finally {
@@ -2815,14 +2815,14 @@ async function migrateAcrossDbType(cwd2, config, homeDir, sourceScope, opts) {
   if (!existsSync15(srcPath)) {
     fail(`Source sqlite database not found at ${srcPath} (expected ${sourceScope} scope) \u2014 nothing to migrate.`);
   }
-  const { SQLiteDriver } = await import("./sqlite-5OWKTUUZ.js");
+  const { SQLiteDriver } = await import("./sqlite-UDXCFIEN.js");
   const srcDriver = new SQLiteDriver(srcPath);
   let sourceData;
   let sourceCounts;
   try {
     await srcDriver.ensureSchema();
     sourceCounts = await getRowCounts(srcDriver);
-    const { HarnessDB } = await import("./db-L3AADJF5.js");
+    const { HarnessDB } = await import("./db-3B2W2EBA.js");
     const srcDb = new HarnessDB(srcDriver, config, homeDir);
     sourceData = await srcDb.exportJson();
   } finally {
@@ -3117,7 +3117,7 @@ var TOOLS = [
         taskId: { type: "number", description: "The task ID from tasks.get" },
         agent: {
           type: "string",
-          description: "Agent name: lead | explorer | builder | reviewer | custom:<name>"
+          description: "Agent name: lead | explorer | consultant | builder | reviewer | custom:<name>"
         }
       },
       required: ["taskId", "agent"]
@@ -3156,7 +3156,7 @@ var TOOLS = [
   },
   {
     name: "actions.get",
-    description: "Get the full action history for a task (all agents, all sections).",
+    description: "Full task action history, including every action and section. Potentially large; use only for audit or diagnosis.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3165,6 +3165,84 @@ var TOOLS = [
       required: ["taskId"]
     }
   },
+  {
+    name: "actions.list",
+    description: "Compact newest-first action index. Use to discover actions before reading a specific action or section.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "number", description: "Task ID" },
+        agent: { type: "string", description: "Optional agent filter" },
+        status: { type: "string", enum: ["in_progress", "completed", "blocked"], description: "Optional action status filter" },
+        cursor: { type: "string", description: "Opaque cursor returned as nextCursor" },
+        limit: { type: "number", description: "Maximum items (1-100; default 20)" }
+      },
+      required: ["taskId"]
+    }
+  },
+  {
+    name: "actions.get_by_id",
+    description: "Get one action and a compact index of its sections; section contents are not included.",
+    inputSchema: { type: "object", properties: { actionId: { type: "number", description: "Action ID" } }, required: ["actionId"] }
+  },
+  {
+    name: "actions.sections.list",
+    description: "Compact newest-first section index for one action. Filter by section types without loading content.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "number", description: "Action ID" },
+        types: { type: "array", items: { type: "string" }, description: "Optional section-type filter" },
+        cursor: { type: "string", description: "Opaque cursor returned as nextCursor" },
+        limit: { type: "number", description: "Maximum items (1-100; default 20)" }
+      },
+      required: ["actionId"]
+    }
+  },
+  {
+    name: "actions.sections.get",
+    description: "Read one section content with an explicit character range. This is the only generic action reader that returns long text.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sectionId: { type: "number", description: "Section ID" },
+        offset: { type: "number", description: "Zero-based character offset (default 0)" },
+        length: { type: "number", description: "Characters to return (1-12000; default 8000)" }
+      },
+      required: ["sectionId"]
+    }
+  },
+  {
+    name: "actions.handoff.write",
+    description: "Write a validated, recipient-directed, bounded handoff for a completed action to resume work without loading the full history.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "number", description: "Producer action ID" },
+        recipient: { type: "string", enum: ["lead", "explorer", "consultant", "builder", "reviewer"] },
+        goal: { type: "string" },
+        completed: { type: "array", items: { type: "string" } },
+        decisions: { type: "array", items: { type: "string" } },
+        files: { type: "array", items: { type: "string" } },
+        verification: { type: "array", items: { type: "string" } },
+        blockers: { type: "array", items: { type: "string" } },
+        nextStep: { type: "string" }
+      },
+      required: ["actionId", "recipient", "goal", "completed", "decisions", "files", "verification", "blockers", "nextStep"]
+    }
+  },
+  {
+    name: "actions.handoff.get",
+    description: "Get the newest completed canonical handoff addressed to a recipient. Returns HANDOFF_NOT_FOUND instead of falling back to history.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        taskId: { type: "number", description: "Task ID" },
+        recipient: { type: "string", enum: ["lead", "explorer", "consultant", "builder", "reviewer"], description: "Recipient role; defaults to builder" }
+      },
+      required: ["taskId"]
+    }
+  },
   {
     name: "tasks.get",
     description: "List tasks, optionally filtered by status. Excludes archived tasks by default.",
@@ -3426,6 +3504,7 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
     case "actions.write": {
       const actionId = num(args, "actionId");
       const sectionType = str(args, "sectionType");
+      if (sectionType === "handoff") throw new Error("handoff sections must be written with actions.handoff.write");
       const content = str(args, "content");
       await db.writeSection(actionId, sectionType, content);
       return ok2(JSON.stringify({ recorded: true }));
@@ -3460,6 +3539,56 @@ async function dispatch(name, args, db, docsPath, cwd2, config) {
       );
       return ok2(JSON.stringify(full));
     }
+    case "actions.list": {
+      const taskId = num(args, "taskId");
+      const limit = boundedInt(args, "limit", 20, 1, 100);
+      const rows = await db.listActionsForTask(taskId, { agent: optionalAgent(args, "agent"), status: optionalActionStatus(args, "status"), cursor: decodeActionCursor(optionalStr(args, "cursor")), limit });
+      const last = rows.at(-1);
+      return ok2(JSON.stringify({ items: rows.map((row) => ({ id: row.id, agent: row.agent, status: row.status, createdAt: row.created_at, completedAt: row.completed_at, summaryPreview: preview(row.summary), sectionCount: Number(row.section_count) })), nextCursor: rows.length === limit && last ? encodeActionCursor(last.created_at, last.id) : null }));
+    }
+    case "actions.get_by_id": {
+      const actionId = num(args, "actionId");
+      const action = await db.getAction(actionId);
+      if (!action) return ok2(JSON.stringify({ error: "ACTION_NOT_FOUND", actionId }), true);
+      const sections = await db.listActionSections(actionId, { limit: 100 });
+      return ok2(JSON.stringify({ id: action.id, taskId: action.task_id, agent: action.agent, status: action.status, summary: action.summary, createdAt: action.created_at, completedAt: action.completed_at, sections: sections.map(sectionIndex) }));
+    }
+    case "actions.sections.list": {
+      const actionId = num(args, "actionId");
+      const limit = boundedInt(args, "limit", 20, 1, 100);
+      const rows = await db.listActionSections(actionId, { types: optionalStringArray(args, "types"), cursor: decodeSectionCursor(optionalStr(args, "cursor")), limit });
+      const last = rows.at(-1);
+      return ok2(JSON.stringify({ items: rows.map(sectionIndex), nextCursor: rows.length === limit && last ? encodeSectionCursor(last.id) : null }));
+    }
+    case "actions.sections.get": {
+      const sectionId = num(args, "sectionId");
+      const offset = boundedInt(args, "offset", 0, 0, Number.MAX_SAFE_INTEGER);
+      const length = boundedInt(args, "length", 8e3, 1, 12e3);
+      const section = await db.getActionSection(sectionId);
+      if (!section) return ok2(JSON.stringify({ error: "SECTION_NOT_FOUND", sectionId }), true);
+      const content = section.content.slice(offset, offset + length);
+      const nextOffset = offset + content.length;
+      return ok2(JSON.stringify({ sectionId: section.id, type: section.section_type, content, truncated: nextOffset < section.content.length, nextOffset: nextOffset < section.content.length ? nextOffset : null }));
+    }
+    case "actions.handoff.write": {
+      const actionId = num(args, "actionId");
+      const recipient = recipientRole(args["recipient"]);
+      const handoff = handoffFromArgs(args);
+      const serialized = JSON.stringify({ version: 1, recipient, handoff });
+      if (Buffer.byteLength(serialized, "utf8") > 12e3) throw new Error("handoff must not exceed 12000 UTF-8 bytes");
+      await db.writeSection(actionId, "handoff", serialized);
+      return ok2(JSON.stringify({ recorded: true, recipient }));
+    }
+    case "actions.handoff.get": {
+      const taskId = num(args, "taskId");
+      const recipient = recipientRole(args["recipient"] ?? "builder");
+      for (const candidate of await db.getCompletedHandoffSections(taskId)) {
+        const decoded = decodeHandoff(candidate.content);
+        if (decoded?.recipient !== recipient) continue;
+        return ok2(JSON.stringify({ found: true, taskId, sourceActionId: candidate.action_id, sourceAgent: candidate.agent, recipient, createdAt: candidate.created_at, handoff: decoded.handoff }));
+      }
+      return ok2(JSON.stringify({ found: false, reason: "HANDOFF_NOT_FOUND" }));
+    }
     case "tasks.get": {
       const status = args["status"];
       const includeArchived = args["includeArchived"];
@@ -3712,6 +3841,88 @@ function num(args, key) {
   if (typeof v4 !== "number") throw new Error(`${key} must be a number`);
   return v4;
 }
+function optionalStr(args, key) {
+  const value = args[key];
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") throw new Error(`${key} must be a string`);
+  return value;
+}
+function boundedInt(args, key, fallback, min, max) {
+  const value = args[key];
+  if (value === void 0) return fallback;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) throw new Error(`${key} must be an integer between ${min} and ${max}`);
+  return value;
+}
+function optionalStringArray(args, key) {
+  const value = args[key];
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.length === 0)) throw new Error(`${key} must be an array of non-empty strings`);
+  return value;
+}
+var RECIPIENTS = ["lead", "explorer", "consultant", "builder", "reviewer"];
+function recipientRole(value) {
+  if (typeof value !== "string" || !RECIPIENTS.includes(value)) throw new Error(`recipient must be one of: ${RECIPIENTS.join(", ")}`);
+  return value;
+}
+function requiredStringArray(args, key) {
+  if (!(key in args)) throw new Error(`${key} is required`);
+  return optionalStringArray(args, key) ?? [];
+}
+function handoffFromArgs(args) {
+  const goal = str(args, "goal");
+  const nextStep = str(args, "nextStep");
+  if (!goal.trim() || !nextStep.trim()) throw new Error("goal and nextStep must be non-empty strings");
+  return { goal, completed: requiredStringArray(args, "completed"), decisions: requiredStringArray(args, "decisions"), files: requiredStringArray(args, "files"), verification: requiredStringArray(args, "verification"), blockers: requiredStringArray(args, "blockers"), nextStep };
+}
+function decodeHandoff(content) {
+  try {
+    const value = JSON.parse(content);
+    if (value.version !== 1 || !value.handoff) return null;
+    return { recipient: recipientRole(value.recipient), handoff: handoffFromArgs(value.handoff) };
+  } catch {
+    return null;
+  }
+}
+function optionalAgent(args, key) {
+  const value = optionalStr(args, key);
+  if (value === void 0) return void 0;
+  if (!["lead", "explorer", "consultant", "builder", "reviewer"].includes(value) && !value.startsWith("custom:")) throw new Error("agent must be a known role or custom:<name>");
+  return value;
+}
+function optionalActionStatus(args, key) {
+  const value = optionalStr(args, key);
+  if (value === void 0) return void 0;
+  if (!["in_progress", "completed", "blocked"].includes(value)) throw new Error("status must be in_progress, completed, or blocked");
+  return value;
+}
+function encodeActionCursor(createdAt, id) {
+  return Buffer.from(JSON.stringify({ createdAt, id })).toString("base64url");
+}
+function decodeActionCursor(cursor) {
+  if (!cursor) return void 0;
+  try {
+    const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    if (typeof value.createdAt !== "string" || typeof value.id !== "number" || !Number.isInteger(value.id)) throw new Error();
+    return { createdAt: value.createdAt, id: value.id };
+  } catch {
+    throw new Error("cursor is invalid");
+  }
+}
+function encodeSectionCursor(id) {
+  return Buffer.from(String(id)).toString("base64url");
+}
+function decodeSectionCursor(cursor) {
+  if (!cursor) return void 0;
+  const id = Number(Buffer.from(cursor, "base64url").toString("utf8"));
+  if (!Number.isInteger(id) || id < 1) throw new Error("cursor is invalid");
+  return id;
+}
+function preview(summary) {
+  return summary ? summary.slice(0, 240) : null;
+}
+function sectionIndex(section) {
+  return { id: section.id, type: section.section_type, chars: Number(section.chars), createdAt: section.created_at };
+}
 function nonEmptyArray(args, key) {
   const v4 = args[key];
   if (!Array.isArray(v4) || v4.length === 0) {