memorix 1.5.1 → 1.6.0

package/src/orchestrate/pipeline-trace.ts

@@ -1,131 +1,131 @@
-/**
- * Pipeline Tracing — Phase 6g: Structured event logging.
- *
- * Writes trace events to SQLite for observability and debugging.
- * Built-in pruning retains only the last N pipelines (pays D9 debt).
- */
-
-import type Database from 'better-sqlite3';
-
-// ── Types ──────────────────────────────────────────────────────────
-
-export type TraceEventType =
-  | 'plan' | 'materialize' | 'dispatch' | 'complete' | 'fail'
-  | 'retry' | 'timeout' | 'stale' | 'replan' | 'worktree:create'
-  | 'worktree:merge' | 'worktree:cleanup' | 'pipeline:start' | 'pipeline:end';
-
-export interface TraceEvent {
-  pipelineId: string;
-  timestamp: number;
-  type: TraceEventType;
-  taskId?: string;
-  agent?: string;
-  detail: string;
-  durationMs?: number;
-}
-
-// ── Schema ─────────────────────────────────────────────────────────
-
-const CREATE_TABLE_SQL = `
-  CREATE TABLE IF NOT EXISTS pipeline_traces (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    pipeline_id TEXT NOT NULL,
-    timestamp INTEGER NOT NULL,
-    type TEXT NOT NULL,
-    task_id TEXT,
-    agent TEXT,
-    detail TEXT NOT NULL,
-    duration_ms INTEGER
-  )
-`;
-
-const CREATE_INDEX_SQL = `
-  CREATE INDEX IF NOT EXISTS idx_pipeline_traces_pipeline
-  ON pipeline_traces (pipeline_id, timestamp)
-`;
-
-// ── Init ───────────────────────────────────────────────────────────
-
-export function initTraceTable(db: Database.Database): void {
-  db.exec(CREATE_TABLE_SQL);
-  db.exec(CREATE_INDEX_SQL);
-}
-
-// ── Write ──────────────────────────────────────────────────────────
-
-let _insertStmt: Database.Statement | null = null;
-
-export function writeTrace(db: Database.Database, event: TraceEvent): void {
-  if (!_insertStmt) {
-    _insertStmt = db.prepare(`
-      INSERT INTO pipeline_traces (pipeline_id, timestamp, type, task_id, agent, detail, duration_ms)
-      VALUES (?, ?, ?, ?, ?, ?, ?)
-    `);
-  }
-  _insertStmt.run(
-    event.pipelineId,
-    event.timestamp,
-    event.type,
-    event.taskId ?? null,
-    event.agent ?? null,
-    event.detail,
-    event.durationMs ?? null,
-  );
-}
-
-// ── Read ───────────────────────────────────────────────────────────
-
-export function getTraces(db: Database.Database, pipelineId: string): TraceEvent[] {
-  const rows = db.prepare(
-    'SELECT * FROM pipeline_traces WHERE pipeline_id = ? ORDER BY timestamp ASC',
-  ).all(pipelineId) as Array<{
-    pipeline_id: string; timestamp: number; type: string;
-    task_id: string | null; agent: string | null; detail: string;
-    duration_ms: number | null;
-  }>;
-
-  return rows.map(r => ({
-    pipelineId: r.pipeline_id,
-    timestamp: r.timestamp,
-    type: r.type as TraceEventType,
-    taskId: r.task_id ?? undefined,
-    agent: r.agent ?? undefined,
-    detail: r.detail,
-    durationMs: r.duration_ms ?? undefined,
-  }));
-}
-
-// ── Prune ──────────────────────────────────────────────────────────
-
-/**
- * Remove traces from old pipelines, keeping only the last `keepPipelines`.
- */
-export function pruneOldTraces(db: Database.Database, keepPipelines: number = 20): number {
-  // Two-step approach: find pipelines to keep, then delete the rest.
-  // SQLite doesn't allow aggregate + ORDER BY + LIMIT in a subquery easily.
-  const kept = db.prepare(`
-    SELECT pipeline_id FROM (
-      SELECT pipeline_id, MAX(timestamp) AS latest
-      FROM pipeline_traces
-      GROUP BY pipeline_id
-      ORDER BY latest DESC
-      LIMIT ?
-    )
-  `).all(keepPipelines) as Array<{ pipeline_id: string }>;
-
-  if (kept.length === 0) return 0;
-
-  const keepIds = kept.map(r => r.pipeline_id);
-  const placeholders = keepIds.map(() => '?').join(',');
-  const result = db.prepare(
-    `DELETE FROM pipeline_traces WHERE pipeline_id NOT IN (${placeholders})`,
-  ).run(...keepIds);
-  return result.changes;
-}
-
-/**
- * Reset the cached prepared statement (for testing or DB handle changes).
- */
-export function resetTraceCache(): void {
-  _insertStmt = null;
-}
+/**
+ * Pipeline Tracing — Phase 6g: Structured event logging.
+ *
+ * Writes trace events to SQLite for observability and debugging.
+ * Built-in pruning retains only the last N pipelines (pays D9 debt).
+ */
+
+import type Database from 'better-sqlite3';
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export type TraceEventType =
+  | 'plan' | 'materialize' | 'dispatch' | 'complete' | 'fail'
+  | 'retry' | 'timeout' | 'stale' | 'replan' | 'worktree:create'
+  | 'worktree:merge' | 'worktree:cleanup' | 'pipeline:start' | 'pipeline:end';
+
+export interface TraceEvent {
+  pipelineId: string;
+  timestamp: number;
+  type: TraceEventType;
+  taskId?: string;
+  agent?: string;
+  detail: string;
+  durationMs?: number;
+}
+
+// ── Schema ─────────────────────────────────────────────────────────
+
+const CREATE_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS pipeline_traces (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    pipeline_id TEXT NOT NULL,
+    timestamp INTEGER NOT NULL,
+    type TEXT NOT NULL,
+    task_id TEXT,
+    agent TEXT,
+    detail TEXT NOT NULL,
+    duration_ms INTEGER
+  )
+`;
+
+const CREATE_INDEX_SQL = `
+  CREATE INDEX IF NOT EXISTS idx_pipeline_traces_pipeline
+  ON pipeline_traces (pipeline_id, timestamp)
+`;
+
+// ── Init ───────────────────────────────────────────────────────────
+
+export function initTraceTable(db: Database.Database): void {
+  db.exec(CREATE_TABLE_SQL);
+  db.exec(CREATE_INDEX_SQL);
+}
+
+// ── Write ──────────────────────────────────────────────────────────
+
+let _insertStmt: Database.Statement | null = null;
+
+export function writeTrace(db: Database.Database, event: TraceEvent): void {
+  if (!_insertStmt) {
+    _insertStmt = db.prepare(`
+      INSERT INTO pipeline_traces (pipeline_id, timestamp, type, task_id, agent, detail, duration_ms)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+  }
+  _insertStmt.run(
+    event.pipelineId,
+    event.timestamp,
+    event.type,
+    event.taskId ?? null,
+    event.agent ?? null,
+    event.detail,
+    event.durationMs ?? null,
+  );
+}
+
+// ── Read ───────────────────────────────────────────────────────────
+
+export function getTraces(db: Database.Database, pipelineId: string): TraceEvent[] {
+  const rows = db.prepare(
+    'SELECT * FROM pipeline_traces WHERE pipeline_id = ? ORDER BY timestamp ASC',
+  ).all(pipelineId) as Array<{
+    pipeline_id: string; timestamp: number; type: string;
+    task_id: string | null; agent: string | null; detail: string;
+    duration_ms: number | null;
+  }>;
+
+  return rows.map(r => ({
+    pipelineId: r.pipeline_id,
+    timestamp: r.timestamp,
+    type: r.type as TraceEventType,
+    taskId: r.task_id ?? undefined,
+    agent: r.agent ?? undefined,
+    detail: r.detail,
+    durationMs: r.duration_ms ?? undefined,
+  }));
+}
+
+// ── Prune ──────────────────────────────────────────────────────────
+
+/**
+ * Remove traces from old pipelines, keeping only the last `keepPipelines`.
+ */
+export function pruneOldTraces(db: Database.Database, keepPipelines: number = 20): number {
+  // Two-step approach: find pipelines to keep, then delete the rest.
+  // SQLite doesn't allow aggregate + ORDER BY + LIMIT in a subquery easily.
+  const kept = db.prepare(`
+    SELECT pipeline_id FROM (
+      SELECT pipeline_id, MAX(timestamp) AS latest
+      FROM pipeline_traces
+      GROUP BY pipeline_id
+      ORDER BY latest DESC
+      LIMIT ?
+    )
+  `).all(keepPipelines) as Array<{ pipeline_id: string }>;
+
+  if (kept.length === 0) return 0;
+
+  const keepIds = kept.map(r => r.pipeline_id);
+  const placeholders = keepIds.map(() => '?').join(',');
+  const result = db.prepare(
+    `DELETE FROM pipeline_traces WHERE pipeline_id NOT IN (${placeholders})`,
+  ).run(...keepIds);
+  return result.changes;
+}
+
+/**
+ * Reset the cached prepared statement (for testing or DB handle changes).
+ */
+export function resetTraceCache(): void {
+  _insertStmt = null;
+}

package/src/orchestrate/prompt-builder.ts

@@ -1,155 +1,155 @@
-/**
- * Prompt Builder — Constructs agent prompts for orchestrated task execution.
- *
- * Builds a structured prompt that includes:
- * 1. Role and task description
- * 2. Handoff context from previous agents (if any)
- * 3. Memorix tool usage instructions
- * 4. Completion criteria
- */
-
-import type { TeamTaskRow } from '../team/team-store.js';
-import { isPlannerTask } from './planner.js';
-
-export interface HandoffContext {
-  fromAgent: string;
-  fromTaskId?: string;
-  fromRole?: string;
-  summary: string;
-  context: string;
-  outputFiles?: string[];
-  keyDecisions?: string[];
-  openQuestions?: string[];
-  /** @deprecated Use outputFiles instead */
-  filesModified?: string[];
-}
-
-export interface PromptInput {
-  task: TeamTaskRow;
-  handoffs: HandoffContext[];
-  agentId: string;
-  projectId: string;
-  projectDir: string;
-  /** Phase 6d: Ledger context for pipeline progress */
-  ledgerContext?: string;
-  /** Phase 6d: Task position in pipeline (0-indexed) */
-  taskIndex?: number;
-  /** Phase 6d: Total tasks in pipeline */
-  totalTasks?: number;
-  /** Phase 7: Lesson context from Memorix (advisory) */
-  lessonContext?: string;
-  /** Phase 7: Goal verification — acceptance criteria for this task */
-  goals?: string[];
-}
-
-export function buildAgentPrompt(input: PromptInput): string {
-  const sections: string[] = [];
-
-  // 1. Role assignment
-  sections.push([
-    `You are an autonomous coding agent working on project "${input.projectId}".`,
-    `Coordinator agent ID (for reference only, NOT your identity): ${input.agentId}`,
-    `Working directory: ${input.projectDir}`,
-  ].join('\n'));
-
-  // 2. Task description
-  sections.push([
-    '## Your Task',
-    '',
-    `Task ID: ${input.task.task_id}`,
-    `Description: ${input.task.description}`,
-    input.task.metadata ? `Metadata: ${input.task.metadata}` : '',
-  ].filter(Boolean).join('\n'));
-
-  // 3. Ledger context (Phase 6d — pipeline progress)
-  if (input.ledgerContext) {
-    sections.push(input.ledgerContext);
-  }
-
-  // Phase 7: Lesson injection (advisory)
-  if (input.lessonContext) {
-    sections.push(input.lessonContext);
-  }
-
-  // Phase 7: Goal verification — acceptance criteria
-  if (input.goals && input.goals.length > 0) {
-    sections.push([
-      '## Acceptance Criteria',
-      '',
-      'Your work will be verified against these goals:',
-      ...input.goals.map((g, i) => `${i + 1}. ${g}`),
-      '',
-      'Ensure ALL criteria are satisfied before finishing.',
-    ].join('\n'));
-  }
-
-  // 4. Handoff context from previous agents
-  if (input.handoffs.length > 0) {
-    const handoffLines = input.handoffs.map((h, i) => {
-      const lines = [
-        `### Handoff ${i + 1} (from ${h.fromAgent}${h.fromRole ? ` [${h.fromRole}]` : ''})`,
-        `Summary: ${h.summary}`,
-        `Context: ${h.context}`,
-      ];
-      const files = h.outputFiles ?? h.filesModified;
-      if (files?.length) lines.push(`Files: ${files.join(', ')}`);
-      if (h.keyDecisions?.length) lines.push(`Key decisions: ${h.keyDecisions.join('; ')}`);
-      if (h.openQuestions?.length) lines.push(`Open questions: ${h.openQuestions.join('; ')}`);
-      return lines.filter(Boolean).join('\n');
-    });
-
-    sections.push([
-      '## Context from Previous Agents',
-      '',
-      'The following handoff artifacts were left by agents who worked on related tasks.',
-      'Use this context to avoid re-doing work and to understand the current state.',
-      '',
-      ...handoffLines,
-    ].join('\n'));
-  }
-
-  // 4. Memorix tool instructions
-  const plannerMeta = isPlannerTask(input.task.metadata);
-  const isAutonomous = !!plannerMeta;
-  // Structured plan tasks (plannerType='plan') output JSON only — the coordinator materializes.
-  // They must NOT call team_task create, or tasks get double-created.
-  // Review tasks and decomposition tasks still need team_task create for fix/follow-up tasks.
-  const isStructuredPlan = plannerMeta?.plannerType === 'plan';
-
-  const taskInstruction = isAutonomous && !isStructuredPlan
-    ? '5. You have FULL ACCESS to `team_task action="create"` for creating subtasks. Follow the instructions in your task description.'
-    : isStructuredPlan
-    ? '5. Do NOT call `team_task` — output ONLY the structured JSON plan as specified. The coordinator will materialize tasks from your JSON output.'
-    : '5. Focus on completing the work. Do NOT call `team_task` — the orchestrator manages task state.';
-
-  const creationRule = isAutonomous && !isStructuredPlan
-    ? '8. Create tasks as instructed in your task description. Respect the task budget and include proper dependencies.'
-    : isStructuredPlan
-    ? '8. Output ONLY the JSON plan inside a ```json code fence. Do NOT create tasks directly — the system will parse your JSON and create them automatically.'
-    : '8. Do NOT create new tasks unless the original task explicitly requires subtask decomposition.';
-
-  sections.push([
-    '## Instructions',
-    '',
-    '1. Start by calling `memorix_session_start` to bind to this project.',
-    '2. Use the agentId returned by `memorix_session_start` as YOUR identity for any identity-bearing calls (e.g. `memorix_handoff` fromAgentId). Do NOT use the coordinator agent ID above — that belongs to the orchestrator, not to you.',
-    '3. Call `memorix_poll` to check for any additional context or messages.',
-    `4. Work on the task described above. The task is already claimed and managed by the orchestrator.`,
-    taskInstruction,
-    '6. If you want to leave context for the next agent, call `memorix_handoff` with a summary of what you did.',
-    '7. Use `memorix_store` to save any important discoveries, decisions, or gotchas.',
-    creationRule,
-  ].join('\n'));
-
-  // 5. Completion criteria
-  sections.push([
-    '## Completion Criteria',
-    '',
-    '- Exit with code 0 when the task is successfully completed.',
-    '- Exit with a non-zero code if you cannot complete the task.',
-    '- The orchestrator will determine task success/failure based on your exit code.',
-    '- You do NOT need to mark the task as completed or failed — that is handled automatically.',
-  ].join('\n'));
-
-  return sections.join('\n\n');
-}
+/**
+ * Prompt Builder — Constructs agent prompts for orchestrated task execution.
+ *
+ * Builds a structured prompt that includes:
+ * 1. Role and task description
+ * 2. Handoff context from previous agents (if any)
+ * 3. Memorix tool usage instructions
+ * 4. Completion criteria
+ */
+
+import type { TeamTaskRow } from '../team/team-store.js';
+import { isPlannerTask } from './planner.js';
+
+export interface HandoffContext {
+  fromAgent: string;
+  fromTaskId?: string;
+  fromRole?: string;
+  summary: string;
+  context: string;
+  outputFiles?: string[];
+  keyDecisions?: string[];
+  openQuestions?: string[];
+  /** @deprecated Use outputFiles instead */
+  filesModified?: string[];
+}
+
+export interface PromptInput {
+  task: TeamTaskRow;
+  handoffs: HandoffContext[];
+  agentId: string;
+  projectId: string;
+  projectDir: string;
+  /** Phase 6d: Ledger context for pipeline progress */
+  ledgerContext?: string;
+  /** Phase 6d: Task position in pipeline (0-indexed) */
+  taskIndex?: number;
+  /** Phase 6d: Total tasks in pipeline */
+  totalTasks?: number;
+  /** Phase 7: Lesson context from Memorix (advisory) */
+  lessonContext?: string;
+  /** Phase 7: Goal verification — acceptance criteria for this task */
+  goals?: string[];
+}
+
+export function buildAgentPrompt(input: PromptInput): string {
+  const sections: string[] = [];
+
+  // 1. Role assignment
+  sections.push([
+    `You are an autonomous coding agent working on project "${input.projectId}".`,
+    `Coordinator agent ID (for reference only, NOT your identity): ${input.agentId}`,
+    `Working directory: ${input.projectDir}`,
+  ].join('\n'));
+
+  // 2. Task description
+  sections.push([
+    '## Your Task',
+    '',
+    `Task ID: ${input.task.task_id}`,
+    `Description: ${input.task.description}`,
+    input.task.metadata ? `Metadata: ${input.task.metadata}` : '',
+  ].filter(Boolean).join('\n'));
+
+  // 3. Ledger context (Phase 6d — pipeline progress)
+  if (input.ledgerContext) {
+    sections.push(input.ledgerContext);
+  }
+
+  // Phase 7: Lesson injection (advisory)
+  if (input.lessonContext) {
+    sections.push(input.lessonContext);
+  }
+
+  // Phase 7: Goal verification — acceptance criteria
+  if (input.goals && input.goals.length > 0) {
+    sections.push([
+      '## Acceptance Criteria',
+      '',
+      'Your work will be verified against these goals:',
+      ...input.goals.map((g, i) => `${i + 1}. ${g}`),
+      '',
+      'Ensure ALL criteria are satisfied before finishing.',
+    ].join('\n'));
+  }
+
+  // 4. Handoff context from previous agents
+  if (input.handoffs.length > 0) {
+    const handoffLines = input.handoffs.map((h, i) => {
+      const lines = [
+        `### Handoff ${i + 1} (from ${h.fromAgent}${h.fromRole ? ` [${h.fromRole}]` : ''})`,
+        `Summary: ${h.summary}`,
+        `Context: ${h.context}`,
+      ];
+      const files = h.outputFiles ?? h.filesModified;
+      if (files?.length) lines.push(`Files: ${files.join(', ')}`);
+      if (h.keyDecisions?.length) lines.push(`Key decisions: ${h.keyDecisions.join('; ')}`);
+      if (h.openQuestions?.length) lines.push(`Open questions: ${h.openQuestions.join('; ')}`);
+      return lines.filter(Boolean).join('\n');
+    });
+
+    sections.push([
+      '## Context from Previous Agents',
+      '',
+      'The following handoff artifacts were left by agents who worked on related tasks.',
+      'Use this context to avoid re-doing work and to understand the current state.',
+      '',
+      ...handoffLines,
+    ].join('\n'));
+  }
+
+  // 4. Memorix tool instructions
+  const plannerMeta = isPlannerTask(input.task.metadata);
+  const isAutonomous = !!plannerMeta;
+  // Structured plan tasks (plannerType='plan') output JSON only — the coordinator materializes.
+  // They must NOT call team_task create, or tasks get double-created.
+  // Review tasks and decomposition tasks still need team_task create for fix/follow-up tasks.
+  const isStructuredPlan = plannerMeta?.plannerType === 'plan';
+
+  const taskInstruction = isAutonomous && !isStructuredPlan
+    ? '5. You have FULL ACCESS to `team_task action="create"` for creating subtasks. Follow the instructions in your task description.'
+    : isStructuredPlan
+    ? '5. Do NOT call `team_task` — output ONLY the structured JSON plan as specified. The coordinator will materialize tasks from your JSON output.'
+    : '5. Focus on completing the work. Do NOT call `team_task` — the orchestrator manages task state.';
+
+  const creationRule = isAutonomous && !isStructuredPlan
+    ? '8. Create tasks as instructed in your task description. Respect the task budget and include proper dependencies.'
+    : isStructuredPlan
+    ? '8. Output ONLY the JSON plan inside a ```json code fence. Do NOT create tasks directly — the system will parse your JSON and create them automatically.'
+    : '8. Do NOT create new tasks unless the original task explicitly requires subtask decomposition.';
+
+  sections.push([
+    '## Instructions',
+    '',
+    '1. Start by calling `memorix_session_start` to bind to this project.',
+    '2. Use the agentId returned by `memorix_session_start` as YOUR identity for any identity-bearing calls (e.g. `memorix_handoff` fromAgentId). Do NOT use the coordinator agent ID above — that belongs to the orchestrator, not to you.',
+    '3. Call `memorix_poll` to check for any additional context or messages.',
+    `4. Work on the task described above. The task is already claimed and managed by the orchestrator.`,
+    taskInstruction,
+    '6. If you want to leave context for the next agent, call `memorix_handoff` with a summary of what you did.',
+    '7. Use `memorix_store` to save any important discoveries, decisions, or gotchas.',
+    creationRule,
+  ].join('\n'));
+
+  // 5. Completion criteria
+  sections.push([
+    '## Completion Criteria',
+    '',
+    '- Exit with code 0 when the task is successfully completed.',
+    '- Exit with a non-zero code if you cannot complete the task.',
+    '- The orchestrator will determine task success/failure based on your exit code.',
+    '- You do NOT need to mark the task as completed or failed — that is handled automatically.',
+  ].join('\n'));
+
+  return sections.join('\n\n');
+}

package/src/orchestrate/ring-buffer.ts

@@ -1,37 +1,37 @@
-/**
- * RingBuffer — Bounded line buffer for agent process output.
- *
- * Captures the last N lines of stdout/stderr without unbounded memory growth.
- * Used by agent adapters to provide tail output for diagnostics.
- */
-
-export class RingBuffer {
-  private lines: string[] = [];
-
-  constructor(private maxLines: number = 50) {}
-
-  push(text: string): void {
-    for (const line of text.split('\n')) {
-      if (line.trim()) {
-        this.lines.push(line);
-        if (this.lines.length > this.maxLines) this.lines.shift();
-      }
-    }
-  }
-
-  getLines(): string[] {
-    return [...this.lines];
-  }
-
-  toString(): string {
-    return this.lines.join('\n');
-  }
-
-  get length(): number {
-    return this.lines.length;
-  }
-
-  clear(): void {
-    this.lines = [];
-  }
-}
+/**
+ * RingBuffer — Bounded line buffer for agent process output.
+ *
+ * Captures the last N lines of stdout/stderr without unbounded memory growth.
+ * Used by agent adapters to provide tail output for diagnostics.
+ */
+
+export class RingBuffer {
+  private lines: string[] = [];
+
+  constructor(private maxLines: number = 50) {}
+
+  push(text: string): void {
+    for (const line of text.split('\n')) {
+      if (line.trim()) {
+        this.lines.push(line);
+        if (this.lines.length > this.maxLines) this.lines.shift();
+      }
+    }
+  }
+
+  getLines(): string[] {
+    return [...this.lines];
+  }
+
+  toString(): string {
+    return this.lines.join('\n');
+  }
+
+  get length(): number {
+    return this.lines.length;
+  }
+
+  clear(): void {
+    this.lines = [];
+  }
+}