trellis 2.0.13 → 2.1.2

package/src/decisions/hooks.ts

@@ -1,163 +0,0 @@
-/**
- * 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

@@ -1,261 +0,0 @@
-/**
- * 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

@@ -1,103 +0,0 @@
-/**
- * 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>;
-}