trellis 1.0.8 → 2.0.6

package/src/decisions/auto-capture.ts

@@ -0,0 +1,136 @@
+/**
+ * Decision Auto-Capture Middleware
+ *
+ * Wraps MCP tool handlers to automatically emit vcs:decisionRecord ops
+ * for every tool invocation. Pre/post hooks can enrich the trace with
+ * rationale, alternatives, and prompt context.
+ */
+
+import type { HookRegistry } from './hooks.js';
+import type { DecisionInput, DecisionContext } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A generic MCP tool handler: receives params, returns a result. */
+export type ToolHandler = (params: Record<string, unknown>) => Promise<unknown>;
+
+/** Callback invoked after auto-capture builds the DecisionInput. */
+export type DecisionRecorder = (decision: DecisionInput) => Promise<void>;
+
+export interface AutoCaptureOpts {
+  /** The hook registry for pre/post enrichment. */
+  hooks: HookRegistry;
+  /** Called to persist the decision as a VcsOp. */
+  recorder: DecisionRecorder;
+  /** Tool names to exclude from auto-capture (e.g. read-only queries). */
+  exclude?: Set<string>;
+}
+
+// ---------------------------------------------------------------------------
+// Wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap an MCP tool handler for automatic decision trace capture.
+ */
+export function wrapToolHandler(
+  toolName: string,
+  handler: ToolHandler,
+  opts: AutoCaptureOpts,
+): ToolHandler {
+  return async (params: Record<string, unknown>) => {
+    // Skip excluded tools
+    if (opts.exclude?.has(toolName)) {
+      return handler(params);
+    }
+
+    // Run pre-hooks
+    const preContext: DecisionContext = await opts.hooks.runPreHooks(
+      toolName,
+      params,
+    );
+
+    // Execute the actual tool
+    const result = await handler(params);
+
+    // Run post-hooks
+    const enrichment = await opts.hooks.runPostHooks(
+      toolName,
+      params,
+      result,
+      preContext,
+    );
+
+    // Build the decision input
+    const decision: DecisionInput = {
+      toolName,
+      input: sanitizeInput(params),
+      outputSummary: summarize(result),
+      context: preContext.prompt ?? preContext.conversationId,
+      rationale: enrichment.rationale,
+      alternatives: enrichment.alternatives,
+      confidence: enrichment.confidence,
+      relatedEntities: enrichment.relatedEntities,
+      custom: {
+        ...preContext.custom,
+        ...enrichment.custom,
+        agentModel: preContext.agentModel,
+      },
+    };
+
+    // Record asynchronously — don't block tool response
+    opts.recorder(decision).catch(() => {
+      // Silently ignore recording failures
+    });
+
+    return result;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove potentially large/sensitive fields from tool input before storing.
+ */
+function sanitizeInput(
+  params: Record<string, unknown>,
+): Record<string, unknown> {
+  const sanitized: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (typeof value === 'string' && value.length > 2000) {
+      sanitized[key] = value.slice(0, 2000) + '…';
+    } else {
+      sanitized[key] = value;
+    }
+  }
+  return sanitized;
+}
+
+/**
+ * Summarize a tool result to a concise string (max 500 chars).
+ */
+function summarize(result: unknown): string {
+  if (result === null || result === undefined) return '';
+
+  // MCP-style { content: [{ type: 'text', text: '...' }] }
+  if (typeof result === 'object' && result !== null && 'content' in result) {
+    const content = (result as any).content;
+    if (Array.isArray(content)) {
+      const texts = content
+        .filter((c: any) => c.type === 'text')
+        .map((c: any) => c.text)
+        .join('\n');
+      return texts.length > 500 ? texts.slice(0, 500) + '…' : texts;
+    }
+  }
+
+  const str =
+    typeof result === 'string' ? result : JSON.stringify(result, null, 0);
+  return str.length > 500 ? str.slice(0, 500) + '…' : str;
+}
+
+export { summarize as _summarizeForTest };

package/src/decisions/hooks.ts

@@ -0,0 +1,163 @@
+/**
+ * Decision Hook Registry
+ *
+ * External agent harnesses register pre/post hooks to enrich decision traces
+ * with rationale, alternatives, prompt context, etc.
+ */
+
+import type {
+  DecisionPreHook,
+  DecisionPostHook,
+  DecisionContext,
+  DecisionEnrichment,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Hook Registry
+// ---------------------------------------------------------------------------
+
+export class HookRegistry {
+  private preHooks: DecisionPreHook[] = [];
+  private postHooks: DecisionPostHook[] = [];
+
+  /**
+   * Register a pre-hook that runs before a tool handler.
+   */
+  registerPreHook(hook: DecisionPreHook): void {
+    this.preHooks.push(hook);
+  }
+
+  /**
+   * Register a post-hook that runs after a tool handler.
+   */
+  registerPostHook(hook: DecisionPostHook): void {
+    this.postHooks.push(hook);
+  }
+
+  /**
+   * Remove a pre-hook by name.
+   */
+  removePreHook(name: string): void {
+    this.preHooks = this.preHooks.filter((h) => h.name !== name);
+  }
+
+  /**
+   * Remove a post-hook by name.
+   */
+  removePostHook(name: string): void {
+    this.postHooks = this.postHooks.filter((h) => h.name !== name);
+  }
+
+  /**
+   * Get all pre-hooks matching a tool name.
+   */
+  getPreHooks(toolName: string): DecisionPreHook[] {
+    return this.preHooks.filter((h) => matchesPattern(h.toolPattern, toolName));
+  }
+
+  /**
+   * Get all post-hooks matching a tool name.
+   */
+  getPostHooks(toolName: string): DecisionPostHook[] {
+    return this.postHooks.filter((h) =>
+      matchesPattern(h.toolPattern, toolName),
+    );
+  }
+
+  /**
+   * Run all matching pre-hooks and merge their contexts.
+   */
+  async runPreHooks(
+    toolName: string,
+    input: Record<string, unknown>,
+  ): Promise<DecisionContext> {
+    const hooks = this.getPreHooks(toolName);
+    const merged: DecisionContext = {};
+
+    for (const hook of hooks) {
+      try {
+        const ctx = await hook.handler(toolName, input);
+        Object.assign(merged, ctx);
+        if (ctx.custom) {
+          merged.custom = { ...merged.custom, ...ctx.custom };
+        }
+      } catch {
+        // Hooks should not break tool execution
+      }
+    }
+
+    return merged;
+  }
+
+  /**
+   * Run all matching post-hooks and merge their enrichments.
+   */
+  async runPostHooks(
+    toolName: string,
+    input: Record<string, unknown>,
+    output: unknown,
+    preContext: DecisionContext,
+  ): Promise<DecisionEnrichment> {
+    const hooks = this.getPostHooks(toolName);
+    const merged: DecisionEnrichment = {};
+
+    for (const hook of hooks) {
+      try {
+        const enrichment = await hook.handler(
+          toolName,
+          input,
+          output,
+          preContext,
+        );
+        if (enrichment.rationale) merged.rationale = enrichment.rationale;
+        if (enrichment.alternatives)
+          merged.alternatives = enrichment.alternatives;
+        if (enrichment.confidence !== undefined)
+          merged.confidence = enrichment.confidence;
+        if (enrichment.relatedEntities) {
+          merged.relatedEntities = [
+            ...(merged.relatedEntities ?? []),
+            ...enrichment.relatedEntities,
+          ];
+        }
+        if (enrichment.custom) {
+          merged.custom = { ...merged.custom, ...enrichment.custom };
+        }
+      } catch {
+        // Hooks should not break tool execution
+      }
+    }
+
+    return merged;
+  }
+
+  /**
+   * Clear all hooks.
+   */
+  clear(): void {
+    this.preHooks = [];
+    this.postHooks = [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Match a tool name against a glob-like pattern or RegExp.
+ * Supports `*` as a wildcard in string patterns (e.g. "trellis_issue_*").
+ */
+function matchesPattern(pattern: string | RegExp, toolName: string): boolean {
+  if (pattern instanceof RegExp) {
+    return pattern.test(toolName);
+  }
+  if (pattern === '*') return true;
+  if (!pattern.includes('*')) return pattern === toolName;
+
+  // Convert glob to regex: escape special chars, replace * with .*
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`).test(toolName);
+}

package/src/decisions/index.ts

@@ -0,0 +1,261 @@
+/**
+ * Decision Traces Module
+ *
+ * Auto-captures agent decision traces from MCP tool invocations as
+ * first-class Decision entities in the EAV store.
+ *
+ * Public API:
+ * - recordDecision()   — persist a decision as a vcs:decisionRecord op
+ * - queryDecisions()   — filter/list decisions from the EAV store
+ * - getDecisionChain() — all decisions that affected a given entity
+ * - HookRegistry       — pre/post hook registration for external harnesses
+ * - wrapToolHandler()  — MCP middleware for auto-capture
+ */
+
+export { HookRegistry } from './hooks.js';
+export {
+  wrapToolHandler,
+  type ToolHandler,
+  type DecisionRecorder,
+  type AutoCaptureOpts,
+} from './auto-capture.js';
+export type {
+  Decision,
+  DecisionInput,
+  DecisionFilter,
+  DecisionContext,
+  DecisionEnrichment,
+  DecisionPreHook,
+  DecisionPostHook,
+} from './types.js';
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { createVcsOp } from '../vcs/ops.js';
+import { decisionEntityId } from '../vcs/types.js';
+import type { VcsOp } from '../vcs/types.js';
+import type { EngineContext } from '../vcs/engine-context.js';
+import type { Decision, DecisionInput, DecisionFilter } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Sequential Decision ID (file-based, matching issue counter pattern)
+// ---------------------------------------------------------------------------
+
+function getDecisionCounterPath(rootPath: string): string {
+  return join(rootPath, '.trellis', 'decision-counter.json');
+}
+
+function nextDecisionId(rootPath: string): string {
+  const counterPath = getDecisionCounterPath(rootPath);
+  let counter = 0;
+  if (existsSync(counterPath)) {
+    try {
+      counter = JSON.parse(readFileSync(counterPath, 'utf-8')).counter ?? 0;
+    } catch {}
+  }
+  counter++;
+  const dir = dirname(counterPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(counterPath, JSON.stringify({ counter }, null, 2));
+  return `DEC-${counter}`;
+}
+
+// ---------------------------------------------------------------------------
+// Record
+// ---------------------------------------------------------------------------
+
+/**
+ * Record a decision trace as a vcs:decisionRecord op.
+ */
+export async function recordDecision(
+  ctx: EngineContext,
+  rootPath: string,
+  input: DecisionInput,
+): Promise<VcsOp> {
+  const id = nextDecisionId(rootPath);
+
+  const op = await createVcsOp('vcs:decisionRecord', {
+    agentId: ctx.agentId,
+    previousHash: ctx.getLastOp()?.hash,
+    vcs: {
+      decisionId: id,
+      decisionToolName: input.toolName,
+      decisionToolInput: input.input ? JSON.stringify(input.input) : undefined,
+      decisionToolOutput: input.outputSummary,
+      decisionContext: input.context,
+      decisionRationale: input.rationale,
+      decisionAlternatives: input.alternatives
+        ? JSON.stringify(input.alternatives)
+        : undefined,
+    },
+  });
+  ctx.applyOp(op);
+
+  // Store related entity links
+  if (input.relatedEntities) {
+    const eid = decisionEntityId(id);
+    const links = input.relatedEntities.map((target) => ({
+      e1: eid,
+      a: 'relatedTo',
+      e2: target,
+    }));
+    if (links.length > 0) {
+      ctx.store.addLinks(links);
+    }
+  }
+
+  return op;
+}
+
+// ---------------------------------------------------------------------------
+// Query
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a Decision from EAV facts for a given entity ID.
+ */
+function buildDecision(ctx: EngineContext, entityId: string): Decision {
+  const facts = ctx.store.getFactsByEntity(entityId);
+  const get = (a: string) => {
+    const matches = facts.filter((f) => f.a === a);
+    return matches.length > 0
+      ? (matches[matches.length - 1].v as string)
+      : undefined;
+  };
+
+  // Gather related entity links
+  const links = ctx.store.getLinksByAttribute('relatedTo');
+  const related = links.filter((l) => l.e1 === entityId).map((l) => l.e2);
+
+  const bareId = entityId.replace(/^decision:/, '');
+
+  const alternativesRaw = get('alternatives');
+  let alternatives: string[] | undefined;
+  if (alternativesRaw) {
+    try {
+      alternatives = JSON.parse(alternativesRaw);
+    } catch {
+      alternatives = [alternativesRaw];
+    }
+  }
+
+  const confidenceRaw = get('confidence');
+  const confidence =
+    confidenceRaw !== undefined ? parseFloat(confidenceRaw) : undefined;
+
+  return {
+    id: bareId,
+    toolName: get('toolName') ?? '',
+    outputSummary: get('outputSummary'),
+    context: get('context'),
+    rationale: get('rationale'),
+    alternatives,
+    confidence,
+    createdAt: get('createdAt'),
+    createdBy: get('createdBy'),
+    relatedEntities: related,
+  };
+}
+
+/**
+ * Query decisions with optional filters.
+ */
+export function queryDecisions(
+  ctx: EngineContext,
+  filter?: DecisionFilter,
+): Decision[] {
+  const decisionFacts = ctx.store
+    .getFactsByAttribute('type')
+    .filter((f) => f.v === 'Decision');
+
+  let decisions = decisionFacts.map((f) => buildDecision(ctx, f.e));
+
+  if (filter?.toolPattern) {
+    const pattern = filter.toolPattern;
+    const regex = pattern.includes('*')
+      ? new RegExp(
+          `^${pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`,
+        )
+      : null;
+    decisions = decisions.filter((d) =>
+      regex ? regex.test(d.toolName) : d.toolName === pattern,
+    );
+  }
+
+  if (filter?.agentId) {
+    decisions = decisions.filter((d) => d.createdBy === filter.agentId);
+  }
+
+  if (filter?.since) {
+    const since = new Date(filter.since).getTime();
+    decisions = decisions.filter(
+      (d) => d.createdAt && new Date(d.createdAt).getTime() >= since,
+    );
+  }
+
+  if (filter?.until) {
+    const until = new Date(filter.until).getTime();
+    decisions = decisions.filter(
+      (d) => d.createdAt && new Date(d.createdAt).getTime() <= until,
+    );
+  }
+
+  if (filter?.entityId) {
+    decisions = decisions.filter((d) =>
+      d.relatedEntities.includes(filter.entityId!),
+    );
+  }
+
+  // Sort by createdAt descending (newest first)
+  decisions.sort((a, b) => {
+    if (!a.createdAt || !b.createdAt) return 0;
+    return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+  });
+
+  if (filter?.limit && filter.limit > 0) {
+    decisions = decisions.slice(0, filter.limit);
+  }
+
+  return decisions;
+}
+
+/**
+ * Get all decisions that affected a given entity (the decision chain).
+ */
+export function getDecisionChain(
+  ctx: EngineContext,
+  entityId: string,
+): Decision[] {
+  // Find all decision entities linked to this entity
+  const allLinks = ctx.store.getLinksByAttribute('relatedTo');
+  const decisionEids = new Set(
+    allLinks
+      .filter((l) => l.e2 === entityId)
+      .map((l) => l.e1)
+      .filter((e) => e.startsWith('decision:')),
+  );
+
+  const decisions = Array.from(decisionEids).map((eid) =>
+    buildDecision(ctx, eid),
+  );
+
+  // Sort chronologically
+  decisions.sort((a, b) => {
+    if (!a.createdAt || !b.createdAt) return 0;
+    return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+  });
+
+  return decisions;
+}
+
+/**
+ * Get a single decision by ID.
+ */
+export function getDecision(ctx: EngineContext, id: string): Decision | null {
+  const eid = decisionEntityId(id);
+  const typeFact = ctx.store
+    .getFactsByEntity(eid)
+    .find((f) => f.a === 'type' && f.v === 'Decision');
+  if (!typeFact) return null;
+  return buildDecision(ctx, eid);
+}

package/src/decisions/types.ts

@@ -0,0 +1,103 @@
+/**
+ * Decision Trace Types
+ *
+ * Types for auto-captured agent decision traces. Decisions are first-class
+ * entities in the EAV store, emitted automatically from MCP tool calls
+ * and enrichable via pre/post hooks.
+ */
+
+// ---------------------------------------------------------------------------
+// Decision Entity
+// ---------------------------------------------------------------------------
+
+export interface Decision {
+  id: string;
+  toolName: string;
+  input?: Record<string, unknown>;
+  outputSummary?: string;
+  context?: string;
+  rationale?: string;
+  alternatives?: string[];
+  confidence?: number;
+  createdAt?: string;
+  createdBy?: string;
+  /** IDs of related entities (issues, files, milestones) affected by this decision */
+  relatedEntities: string[];
+  custom?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Decision Input (for recording)
+// ---------------------------------------------------------------------------
+
+export interface DecisionInput {
+  toolName: string;
+  input?: Record<string, unknown>;
+  outputSummary?: string;
+  context?: string;
+  rationale?: string;
+  alternatives?: string[];
+  confidence?: number;
+  /** Entity IDs this decision relates to (e.g. "issue:TRL-5") */
+  relatedEntities?: string[];
+  custom?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Decision Filters (for querying)
+// ---------------------------------------------------------------------------
+
+export interface DecisionFilter {
+  /** Filter by MCP tool name (glob-like, e.g. "trellis_issue_*") */
+  toolPattern?: string;
+  /** Filter by agent ID */
+  agentId?: string;
+  /** Only decisions after this ISO timestamp */
+  since?: string;
+  /** Only decisions before this ISO timestamp */
+  until?: string;
+  /** Only decisions referencing this entity */
+  entityId?: string;
+  /** Max results */
+  limit?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Hook Types
+// ---------------------------------------------------------------------------
+
+export interface DecisionContext {
+  prompt?: string;
+  conversationId?: string;
+  agentModel?: string;
+  custom?: Record<string, unknown>;
+}
+
+export interface DecisionEnrichment {
+  rationale?: string;
+  alternatives?: string[];
+  confidence?: number;
+  relatedEntities?: string[];
+  custom?: Record<string, unknown>;
+}
+
+export interface DecisionPreHook {
+  name: string;
+  /** Which tools to intercept — string (glob) or RegExp */
+  toolPattern: string | RegExp;
+  handler: (
+    toolName: string,
+    input: Record<string, unknown>,
+  ) => Promise<DecisionContext>;
+}
+
+export interface DecisionPostHook {
+  name: string;
+  toolPattern: string | RegExp;
+  handler: (
+    toolName: string,
+    input: Record<string, unknown>,
+    output: unknown,
+    preContext: DecisionContext,
+  ) => Promise<DecisionEnrichment>;
+}