agent-trajectories 0.5.2 → 0.5.4

package/dist/{chunk-4MACDCF4.js → chunk-W222QB6V.js}

@@ -1,3 +1,9 @@
+// src/sdk/client.ts
+import { spawn } from "child_process";
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { createRequire } from "module";
+import { dirname, resolve as resolvePath } from "path";
+
 // src/core/id.ts
 import { webcrypto } from "crypto";
 var ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
@@ -18,7 +24,7 @@ function generateChapterId() {
   return `chap_${generateRandomId()}`;
 }
 function isValidTrajectoryId(id) {
-  return /^traj_[a-z0-9]{12}$/.test(id);
+  return /^traj_[a-z0-9_]+$/.test(id);
 }
 function isValidChapterId(id) {
   return /^chap_[a-z0-9]{12}$/.test(id);
@@ -50,18 +56,20 @@ var TrajectoryStatusSchema = z.enum([
   "completed",
   "abandoned"
 ]);
-var TrajectoryEventTypeSchema = z.enum([
-  "prompt",
-  "thinking",
-  "tool_call",
-  "tool_result",
-  "message_sent",
-  "message_received",
-  "decision",
-  "finding",
-  "reflection",
-  "note",
-  "error"
+var TrajectoryEventTypeSchema = z.union([
+  z.literal("prompt"),
+  z.literal("thinking"),
+  z.literal("tool_call"),
+  z.literal("tool_result"),
+  z.literal("message_sent"),
+  z.literal("message_received"),
+  z.literal("decision"),
+  z.literal("finding"),
+  z.literal("reflection"),
+  z.literal("note"),
+  z.literal("error"),
+  z.string()
+  // Allow event types emitted by other tools (e.g. agent-relay's completion-evidence / completion-marker). Downstream code filters to known types.
 ]);
 var EventSignificanceSchema = z.enum([
   "low",
@@ -91,7 +99,7 @@ var DecisionSchema = z.object({
 });
 var AgentParticipationSchema = z.object({
   name: z.string().min(1, "Agent name is required"),
-  role: z.enum(["lead", "contributor", "reviewer"]),
+  role: z.string().min(1, "Agent role is required"),
   joinedAt: z.string().datetime(),
   leftAt: z.string().datetime().optional()
 });
@@ -151,7 +159,7 @@ var TrajectoryTraceRefSchema = z.object({
   traceId: z.string().optional()
 });
 var TrajectorySchema = z.object({
-  id: z.string().regex(/^traj_[a-z0-9]+$/, "Invalid trajectory ID format"),
+  id: z.string().regex(/^traj_[a-z0-9_]+$/, "Invalid trajectory ID format"),
   version: z.literal(1),
   task: TaskReferenceSchema,
   status: TrajectoryStatusSchema,
@@ -160,10 +168,11 @@ var TrajectorySchema = z.object({
   agents: z.array(AgentParticipationSchema),
   chapters: z.array(ChapterSchema),
   retrospective: RetrospectiveSchema.optional(),
-  commits: z.array(z.string()),
-  filesChanged: z.array(z.string()),
-  projectId: z.string(),
-  tags: z.array(z.string()),
+  commits: z.array(z.string()).default([]),
+  filesChanged: z.array(z.string()).default([]),
+  projectId: z.string().optional(),
+  workflowId: z.string().optional(),
+  tags: z.array(z.string()).default([]),
   _trace: TrajectoryTraceRefSchema.optional()
 });
 var CreateTrajectoryInputSchema = z.object({
@@ -696,11 +705,129 @@ var FileStorage = class {
         trajectories: {}
       });
     }
+    await this.reconcileIndex();
+  }
+  /**
+   * Scan active/ and completed/ recursively and add any trajectory files
+   * missing from the index. Existing entries are preserved — reconcile
+   * only adds, never removes.
+   *
+   * Handles three on-disk layouts in completed/:
+   *   - flat:      completed/{id}.json         (legacy workforce data)
+   *   - monthly:   completed/YYYY-MM/{id}.json (current save() writes)
+   *   - nested:    completed/.../{id}.json     (defensive — any depth)
+   *
+   * Returns a ReconcileSummary so tests and CLI wrappers can observe
+   * outcomes without parsing logs. Only writes the index if anything was
+   * added.
+   */
+  async reconcileIndex() {
+    const summary = {
+      scanned: 0,
+      added: 0,
+      alreadyIndexed: 0,
+      skippedMalformedJson: 0,
+      skippedSchemaViolation: 0,
+      skippedIoError: 0
+    };
+    const index = await this.loadIndex();
+    const before = Object.keys(index.trajectories).length;
+    const discovered = [];
+    try {
+      const activeFiles = await readdir(this.activeDir);
+      for (const file of activeFiles) {
+        if (!file.endsWith(".json")) continue;
+        discovered.push(join(this.activeDir, file));
+      }
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    await this.walkJsonFilesInto(this.completedDir, discovered);
+    for (const filePath of discovered) {
+      summary.scanned += 1;
+      const result = await this.readTrajectoryFile(filePath);
+      if (!result.ok) {
+        if (result.reason === "malformed_json") {
+          summary.skippedMalformedJson += 1;
+        } else if (result.reason === "schema_violation") {
+          summary.skippedSchemaViolation += 1;
+        } else {
+          summary.skippedIoError += 1;
+        }
+        continue;
+      }
+      const trajectory2 = result.trajectory;
+      if (index.trajectories[trajectory2.id]) {
+        summary.alreadyIndexed += 1;
+        continue;
+      }
+      index.trajectories[trajectory2.id] = {
+        title: trajectory2.task.title,
+        status: trajectory2.status,
+        startedAt: trajectory2.startedAt,
+        completedAt: trajectory2.completedAt,
+        path: filePath
+      };
+      summary.added += 1;
+    }
+    if (Object.keys(index.trajectories).length !== before) {
+      await this.saveIndex(index);
+    }
+    const hadSkips = summary.skippedMalformedJson + summary.skippedSchemaViolation + summary.skippedIoError > 0;
+    if (summary.added > 0 || hadSkips) {
+      const parts = [`reconciled ${summary.added}/${summary.scanned}`];
+      if (summary.skippedMalformedJson > 0) {
+        parts.push(`malformed: ${summary.skippedMalformedJson}`);
+      }
+      if (summary.skippedSchemaViolation > 0) {
+        parts.push(`invalid: ${summary.skippedSchemaViolation}`);
+      }
+      if (summary.skippedIoError > 0) {
+        parts.push(`io: ${summary.skippedIoError}`);
+      }
+      console.warn(`[trajectories] ${parts.join(", ")}`);
+    }
+    return summary;
   }
   /**
-   * Save a trajectory
+   * Recursively collect all .json file paths under `dir` into `out`.
+   * Silently treats a missing directory as empty.
    */
-  async save(trajectory2) {
+  async walkJsonFilesInto(dir, out) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === "ENOENT") return;
+      throw error;
+    }
+    for (const entry of entries) {
+      const entryPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await this.walkJsonFilesInto(entryPath, out);
+      } else if (entry.isFile() && entry.name.endsWith(".json")) {
+        out.push(entryPath);
+      }
+    }
+  }
+  /**
+   * Save a trajectory.
+   *
+   * Validates the input against the trajectory schema before touching
+   * disk. Closes the historical read/write asymmetry where save() would
+   * happily write data that the reader then rejected, producing files
+   * that could never be loaded back.
+   */
+  async save(input) {
+    const validation = validateTrajectory(input);
+    if (!validation.success) {
+      const issues = validation.errors?.issues.map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "root";
+        return `${path}: ${issue.message}`;
+      }).join("; ") ?? "unknown validation error";
+      throw new Error(`Cannot save invalid trajectory: ${issues}`);
+    }
+    const trajectory2 = validation.data;
     const isCompleted = trajectory2.status === "completed" || trajectory2.status === "abandoned";
     let filePath;
     if (isCompleted) {
@@ -730,19 +857,23 @@ var FileStorage = class {
   async get(id) {
     const activePath = join(this.activeDir, `${id}.json`);
     if (existsSync(activePath)) {
-      return this.readTrajectoryFile(activePath);
+      return this.readTrajectoryOrNull(activePath);
     }
     const index = await this.loadIndex();
     const entry = index.trajectories[id];
     if (entry?.path && existsSync(entry.path)) {
-      return this.readTrajectoryFile(entry.path);
+      return this.readTrajectoryOrNull(entry.path);
     }
     try {
+      const flatPath = join(this.completedDir, `${id}.json`);
+      if (existsSync(flatPath)) {
+        return this.readTrajectoryOrNull(flatPath);
+      }
       const months = await readdir(this.completedDir);
       for (const month of months) {
         const filePath = join(this.completedDir, month, `${id}.json`);
         if (existsSync(filePath)) {
-          return this.readTrajectoryFile(filePath);
+          return this.readTrajectoryOrNull(filePath);
         }
       }
     } catch (error) {
@@ -765,7 +896,7 @@ var FileStorage = class {
       let mostRecent = null;
       let mostRecentTime = 0;
       for (const file of jsonFiles) {
-        const trajectory2 = await this.readTrajectoryFile(
+        const trajectory2 = await this.readTrajectoryOrNull(
           join(this.activeDir, file)
         );
         if (trajectory2) {
@@ -893,20 +1024,44 @@ var FileStorage = class {
   async close() {
   }
   // Private helpers
+  /**
+   * Read a trajectory file and return a tagged result so callers can
+   * distinguish missing files, malformed JSON, and schema violations.
+   *
+   * Does NOT log. Callers choose whether to warn, swallow, or throw.
+   */
   async readTrajectoryFile(path) {
+    let content;
     try {
-      const content = await readFile(path, "utf-8");
-      const data = JSON.parse(content);
-      const validation = validateTrajectory(data);
-      if (validation.success) {
-        return validation.data;
-      }
-      console.error(`Invalid trajectory at ${path}:`, validation.errors);
-      return null;
+      content = await readFile(path, "utf-8");
     } catch (error) {
-      console.error(`Failed to read trajectory at ${path}:`, error);
-      return null;
+      return { ok: false, reason: "io_error", path, error };
+    }
+    let data;
+    try {
+      data = JSON.parse(content);
+    } catch (error) {
+      return { ok: false, reason: "malformed_json", path, error };
     }
+    const validation = validateTrajectory(data);
+    if (validation.success) {
+      return { ok: true, trajectory: validation.data };
+    }
+    return {
+      ok: false,
+      reason: "schema_violation",
+      path,
+      error: validation.errors
+    };
+  }
+  /**
+   * Convenience wrapper for callers that only care whether they got a
+   * trajectory. Returns null for any failure and writes nothing to the
+   * console — so nothing leaks into test output or the CLI spinner.
+   */
+  async readTrajectoryOrNull(path) {
+    const result = await this.readTrajectoryFile(path);
+    return result.ok ? result.trajectory : null;
   }
   async loadIndex() {
     try {
@@ -944,6 +1099,124 @@ var FileStorage = class {
 };
 
 // src/sdk/client.ts
+var require2 = createRequire(import.meta.url);
+function normalizeOptionalString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+function normalizeAutoCompactOptions(autoCompact) {
+  if (!autoCompact) {
+    return false;
+  }
+  if (autoCompact === true) {
+    return { mechanical: false, markdown: true };
+  }
+  return {
+    mechanical: autoCompact.mechanical ?? false,
+    markdown: autoCompact.markdown ?? true
+  };
+}
+function resolveStartWorkflowId(options) {
+  if (options !== void 0 && Object.prototype.hasOwnProperty.call(options, "workflowId")) {
+    return normalizeOptionalString(options.workflowId);
+  }
+  return normalizeOptionalString(process.env.TRAJECTORIES_WORKFLOW_ID);
+}
+function resolveTrajectoryCliInvocation() {
+  const explicitCli = normalizeOptionalString(process.env.TRAJECTORIES_CLI);
+  if (explicitCli) {
+    if (/\.(?:cjs|mjs|js)$/i.test(explicitCli)) {
+      return { command: process.execPath, args: [explicitCli] };
+    }
+    return { command: explicitCli, args: [] };
+  }
+  try {
+    const packageJsonPath = require2.resolve("agent-trajectories/package.json");
+    const pkg = JSON.parse(
+      readFileSync(packageJsonPath, "utf-8")
+    );
+    const binEntry = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.trail ?? (pkg.name ? pkg.bin?.[pkg.name] : void 0);
+    if (binEntry) {
+      const cliPath = resolvePath(dirname(packageJsonPath), binEntry);
+      if (existsSync2(cliPath)) {
+        return { command: process.execPath, args: [cliPath] };
+      }
+    }
+  } catch {
+  }
+  return { command: "trail", args: [] };
+}
+function parseCompactWorkflowOutput(stdout) {
+  const compactedPath = stdout.match(
+    /^\s*Compacted trajectory saved to:\s*(.+)$/m
+  )?.[1];
+  const markdownPath = stdout.match(
+    /^\s*Markdown summary saved to:\s*(.+)$/m
+  )?.[1];
+  if (!compactedPath) {
+    throw new Error("compactWorkflow failed: unable to parse compacted path");
+  }
+  return {
+    compactedPath: compactedPath.trim(),
+    ...markdownPath ? { markdownPath: markdownPath.trim() } : {}
+  };
+}
+async function compactWorkflow(workflowId, options) {
+  const normalizedWorkflowId = normalizeOptionalString(workflowId);
+  if (!normalizedWorkflowId) {
+    throw new Error("compactWorkflow failed: workflowId is required");
+  }
+  const cli = resolveTrajectoryCliInvocation();
+  const args = [
+    ...cli.args,
+    "compact",
+    "--workflow",
+    normalizedWorkflowId,
+    "--all"
+  ];
+  if (options?.markdown) {
+    args.push("--markdown");
+  }
+  if (options?.mechanical) {
+    args.push("--mechanical");
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn(cli.command, args, {
+      cwd: options?.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const stdoutChunks = [];
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdoutChunks.push(Buffer.from(chunk));
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+      process.stderr.write(chunk);
+    });
+    child.on("error", (error) => {
+      reject(new Error(`compactWorkflow failed: ${error.message}`));
+    });
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(
+          new Error(
+            `compactWorkflow failed: ${stderr.trim() || `exit code ${code}`}`
+          )
+        );
+        return;
+      }
+      try {
+        const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
+        resolve(parseCompactWorkflowOutput(stdout));
+      } catch (error) {
+        reject(
+          error instanceof Error ? error : new Error("compactWorkflow failed: unable to parse CLI output")
+        );
+      }
+    });
+  });
+}
 var TrajectorySession = class {
   trajectory;
   client;
@@ -965,6 +1238,23 @@ var TrajectorySession = class {
   get id() {
     return this.trajectory.id;
   }
+  async autoCompactIfConfigured() {
+    const autoCompact = this.client.getAutoCompactOptions();
+    if (!autoCompact || !this.trajectory.workflowId) {
+      return;
+    }
+    try {
+      await compactWorkflow(this.trajectory.workflowId, {
+        ...autoCompact,
+        cwd: this.client.getAutoCompactCwd()
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(
+        `Warning: autoCompact failed for workflow ${this.trajectory.workflowId}: ${message}`
+      );
+    }
+  }
   /**
    * Start a new chapter
    * @param title - Chapter title
@@ -1074,6 +1364,7 @@ var TrajectorySession = class {
   async complete(input) {
     this.trajectory = completeTrajectory(this.trajectory, input);
     await this.client.save(this.trajectory);
+    await this.autoCompactIfConfigured();
     return this.trajectory;
   }
   /**
@@ -1139,11 +1430,21 @@ var TrajectoryClient = class {
   defaultAgent;
   projectId;
   autoSave;
+  autoCompactCwd;
+  autoCompact;
   constructor(options = {}) {
     this.storage = options.storage ?? new FileStorage(options.dataDir);
     this.defaultAgent = options.defaultAgent ?? process.env.TRAJECTORIES_AGENT;
     this.projectId = options.projectId ?? process.env.TRAJECTORIES_PROJECT;
     this.autoSave = options.autoSave ?? true;
+    this.autoCompact = normalizeAutoCompactOptions(options.autoCompact);
+    this.autoCompactCwd = options.storage ? void 0 : options.dataDir;
+  }
+  getAutoCompactOptions() {
+    return this.autoCompact;
+  }
+  getAutoCompactCwd() {
+    return this.autoCompactCwd;
   }
   /**
    * Initialize the client (creates storage directories, etc.)
@@ -1183,13 +1484,16 @@ var TrajectoryClient = class {
         "Complete or abandon the active trajectory first"
       );
     }
+    const workflowId = resolveStartWorkflowId(options);
+    const { workflowId: _workflowId, ...createOptions } = options ?? {};
     const trajectory2 = createTrajectory({
       title,
       projectId: this.projectId,
-      ...options
+      ...createOptions
     });
-    await this.storage.save(trajectory2);
-    return new TrajectorySession(trajectory2, this, this.autoSave);
+    const stampedTrajectory = workflowId ? { ...trajectory2, workflowId } : trajectory2;
+    await this.storage.save(stampedTrajectory);
+    return new TrajectorySession(stampedTrajectory, this, this.autoSave);
   }
   /**
    * Resume the currently active trajectory
@@ -1573,7 +1877,7 @@ function trajectory(title) {
 
 // src/core/trailers.ts
 import { execSync as execSync2 } from "child_process";
-import { readFileSync } from "fs";
+import { readFileSync as readFileSync2 } from "fs";
 
 // src/core/trace.ts
 import { execSync } from "child_process";
@@ -1615,7 +1919,7 @@ function parseTrajectoryFromMessage(commitMessage) {
   const lines = commitMessage.split("\n");
   for (const line of lines) {
     const match = line.match(
-      new RegExp(`^${TRAJECTORY_TRAILER_KEY}:\\s*(traj_[a-z0-9]+)$`)
+      new RegExp(`^${TRAJECTORY_TRAILER_KEY}:\\s*(traj_[a-z0-9_]+)$`)
     );
     if (match) {
       return match[1];
@@ -1717,6 +2021,7 @@ export {
   exportToPRSummary,
   exportToTimeline,
   FileStorage,
+  compactWorkflow,
   TrajectorySession,
   TrajectoryClient,
   TrajectoryBuilder,
@@ -1728,4 +2033,4 @@ export {
   getCommitsBetween,
   getFilesChangedBetween
 };
-//# sourceMappingURL=chunk-4MACDCF4.js.map
+//# sourceMappingURL=chunk-W222QB6V.js.map