memorix 1.9.4 → 1.9.6

package/src/orchestrate/coordinator.ts

@@ -24,6 +24,7 @@ import { classifyError, resetBackoff, type RecoveryAction } from './error-recove
 import { calculatePipelineCost, isBudgetExceeded, formatCostSummary } from './cost-tracker.js';
 import { writeTaskEvidence, writePipelineSummary, type TaskEvidence } from './evidence.js';
 import { TaskToolTracker } from './permission.js';
+import { AgentEffectLedger } from './effect-ledger.js';
 import { storeVerifiedFix, storeFixExhausted, searchKnownFixes, searchLessons, storeTaskCompletion, storePipelineSummary as memStorePipelineSummary, type BridgeConfig, DEFAULT_BRIDGE_CONFIG } from './memorix-bridge.js';
 
 // ── Types ──────────────────────────────────────────────────────────
@@ -232,10 +233,12 @@ export async function runCoordinationLoop(config: CoordinatorConfig): Promise<Co
 
   // Phase 6g: Pipeline tracing
   let traceDb: ReturnType<typeof teamStore.getDb> | null = null;
+  let effectLedger: AgentEffectLedger | null = null;
   try {
     traceDb = teamStore.getDb();
     resetTraceCache();
     initTraceTable(traceDb);
+    if (pipelineId) effectLedger = new AgentEffectLedger(traceDb);
   } catch { /* best-effort: tracing is non-critical */ }
 
   // Phase 6i: Cleanup orphan worktrees from previous crashed runs
@@ -567,6 +570,31 @@ export async function runCoordinationLoop(config: CoordinatorConfig): Promise<Co
               for await (const msg of agentProcess.messages!) {
                 if (msg.type === 'tool_use') {
                   dispatch.toolCount++;
+                  const effectKey = msg.callId ?? `seq:${dispatch.toolCount}`;
+                  const effect = effectLedger?.observe({
+                    pipelineId: pipelineId!,
+                    taskId: dispatch.taskId,
+                    attempt: dispatch.attempt,
+                    effectKey,
+                    tool: msg.tool ?? 'unknown',
+                    ...(msg.callId ? { callId: msg.callId } : {}),
+                    ...(msg.input ? { input: msg.input } : {}),
+                  });
+                  if (effect && traceDb && pipelineId) {
+                    try {
+                      writeTrace(traceDb, {
+                        pipelineId,
+                        timestamp: Date.now(),
+                        type: 'effect',
+                        taskId: dispatch.taskId,
+                        agent: dispatch.adapterName,
+                        detail: `observed tool=${effect.tool} risk=${effect.riskTier} replay=${effect.replayPolicy} effect=${effect.effectKey}`,
+                        attempt: dispatch.attempt,
+                        riskTier: effect.riskTier,
+                        effectKey: effect.effectKey,
+                      });
+                    } catch { /* effect trace is best-effort */ }
+                  }
                   // Phase 7: Record tool usage for risk profiling
                   if (msg.tool) tracker.record(msg.tool);
                   emit('agent:tool_use', `[${adapter.name}] tool #${dispatch.toolCount}: ${msg.tool ?? 'unknown'}`, {
@@ -587,6 +615,16 @@ export async function runCoordinationLoop(config: CoordinatorConfig): Promise<Co
                     } catch { /* trace is best-effort */ }
                   }
                 }
+                if (msg.type === 'tool_result' && msg.callId && effectLedger && pipelineId) {
+                  effectLedger.settle({
+                    pipelineId,
+                    taskId: dispatch.taskId,
+                    attempt: dispatch.attempt,
+                    effectKey: msg.callId,
+                    status: 'succeeded',
+                    detail: 'tool result observed',
+                  });
+                }
                 // Accumulate text for planner output extraction (avoids ring buffer truncation)
                 if (msg.type === 'text' && msg.content) {
                   dispatch.accumulatedText += msg.content;
@@ -671,6 +709,9 @@ export async function runCoordinationLoop(config: CoordinatorConfig): Promise<Co
           if (result.sessionId) {
             taskSessionIds.set(dispatch.taskId, result.sessionId);
           }
+          if (effectLedger && pipelineId) {
+            effectLedger.markAttemptUnknown(pipelineId, dispatch.taskId, dispatch.attempt);
+          }
 
           // ── 方案 A: Orchestrator owns task lifecycle ──
           // Agent does NOT call team_task. Orchestrator infers outcome from exit code.
@@ -755,6 +796,25 @@ export async function runCoordinationLoop(config: CoordinatorConfig): Promise<Co
                       for await (const msg of fixProcess.messages!) {
                         if (msg.type === 'tool_use') {
                           fixDispatch.toolCount++;
+                          effectLedger?.observe({
+                            pipelineId: pipelineId!,
+                            taskId: fixDispatch.taskId,
+                            attempt: fixDispatch.attempt,
+                            effectKey: msg.callId ?? `seq:${fixDispatch.toolCount}`,
+                            tool: msg.tool ?? 'unknown',
+                            ...(msg.callId ? { callId: msg.callId } : {}),
+                            ...(msg.input ? { input: msg.input } : {}),
+                          });
+                        }
+                        if (msg.type === 'tool_result' && msg.callId && effectLedger && pipelineId) {
+                          effectLedger.settle({
+                            pipelineId,
+                            taskId: fixDispatch.taskId,
+                            attempt: fixDispatch.attempt,
+                            effectKey: msg.callId,
+                            status: 'succeeded',
+                            detail: 'tool result observed',
+                          });
                         }
                         if (msg.type === 'text' && msg.content) {
                           fixDispatch.accumulatedText += msg.content;

package/src/orchestrate/effect-ledger.ts

@@ -0,0 +1,160 @@
+/**
+ * Durable, privacy-safe records for agent tool effects.
+ *
+ * This is deliberately not a claim of exactly-once tool delivery. It records
+ * what the coordinator observed, whether a result arrived, and what replay
+ * policy a future recovery path must apply before repeating the effect.
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+import { sanitizeCredentials } from '../memory/secret-filter.js';
+import { classifyTool, type RiskTier } from './permission.js';
+
+export type AgentEffectStatus = 'observed' | 'succeeded' | 'failed' | 'unknown';
+export type AgentEffectReplayPolicy = 'safe' | 'requires-idempotency-key';
+
+export interface AgentEffectRecord {
+  id: string;
+  pipelineId: string;
+  taskId: string;
+  attempt: number;
+  effectKey: string;
+  tool: string;
+  riskTier: RiskTier;
+  replayPolicy: AgentEffectReplayPolicy;
+  status: AgentEffectStatus;
+  callId?: string;
+  idempotencyKey: string;
+  inputFingerprint?: string;
+  detail?: string;
+  startedAt: number;
+  finishedAt?: number;
+}
+
+export function fingerprintEffectInput(input: unknown): string | undefined {
+  if (input === undefined) return undefined;
+  try {
+    const safe = sanitizeCredentials(JSON.stringify(input));
+    return createHash('sha256').update(safe).digest('hex').slice(0, 24);
+  } catch {
+    return undefined;
+  }
+}
+
+function rowToEffect(row: any): AgentEffectRecord {
+  return {
+    id: String(row.id),
+    pipelineId: String(row.pipeline_id),
+    taskId: String(row.task_id),
+    attempt: Number(row.attempt),
+    effectKey: String(row.effect_key),
+    tool: String(row.tool),
+    riskTier: row.risk_tier as RiskTier,
+    replayPolicy: row.replay_policy as AgentEffectReplayPolicy,
+    status: row.status as AgentEffectStatus,
+    ...(row.call_id ? { callId: String(row.call_id) } : {}),
+    idempotencyKey: String(row.idempotency_key),
+    ...(row.input_fingerprint ? { inputFingerprint: String(row.input_fingerprint) } : {}),
+    ...(row.detail ? { detail: String(row.detail) } : {}),
+    startedAt: Number(row.started_at),
+    ...(row.finished_at ? { finishedAt: Number(row.finished_at) } : {}),
+  };
+}
+
+export class AgentEffectLedger {
+  constructor(private readonly db: any) {}
+
+  observe(input: {
+    pipelineId: string;
+    taskId: string;
+    attempt: number;
+    effectKey: string;
+    tool: string;
+    callId?: string;
+    input?: unknown;
+  }): AgentEffectRecord {
+    const existing = this.db.prepare(`
+      SELECT * FROM agent_effects
+      WHERE pipeline_id = ? AND task_id = ? AND attempt = ? AND effect_key = ?
+    `).get(input.pipelineId, input.taskId, input.attempt, input.effectKey);
+    if (existing) return rowToEffect(existing);
+
+    const riskTier = classifyTool(input.tool);
+    const replayPolicy: AgentEffectReplayPolicy = riskTier === 'safe'
+      ? 'safe'
+      : 'requires-idempotency-key';
+    const idempotencyKey = `${input.pipelineId}:${input.taskId}:${input.attempt}:${input.effectKey}`;
+    const now = Date.now();
+    const record: AgentEffectRecord = {
+      id: randomUUID(),
+      pipelineId: input.pipelineId,
+      taskId: input.taskId,
+      attempt: input.attempt,
+      effectKey: input.effectKey,
+      tool: input.tool.slice(0, 200),
+      riskTier,
+      replayPolicy,
+      status: 'observed',
+      ...(input.callId ? { callId: input.callId.slice(0, 200) } : {}),
+      idempotencyKey,
+      ...(fingerprintEffectInput(input.input) ? { inputFingerprint: fingerprintEffectInput(input.input) } : {}),
+      startedAt: now,
+    };
+    this.db.prepare(`
+      INSERT OR IGNORE INTO agent_effects (
+        id, pipeline_id, task_id, attempt, effect_key, tool, risk_tier,
+        replay_policy, status, call_id, idempotency_key, input_fingerprint,
+        detail, started_at, finished_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      record.id, record.pipelineId, record.taskId, record.attempt, record.effectKey,
+      record.tool, record.riskTier, record.replayPolicy, record.status,
+      record.callId ?? null, record.idempotencyKey, record.inputFingerprint ?? null,
+      null, record.startedAt, null,
+    );
+    return rowToEffect(this.db.prepare(`
+      SELECT * FROM agent_effects
+      WHERE pipeline_id = ? AND task_id = ? AND attempt = ? AND effect_key = ?
+    `).get(input.pipelineId, input.taskId, input.attempt, input.effectKey));
+  }
+
+  settle(input: {
+    pipelineId: string;
+    taskId: string;
+    attempt: number;
+    effectKey: string;
+    status: Exclude<AgentEffectStatus, 'observed'>;
+    detail?: string;
+  }): AgentEffectRecord | undefined {
+    const detail = input.detail ? sanitizeCredentials(input.detail).slice(0, 500) : undefined;
+    this.db.prepare(`
+      UPDATE agent_effects
+      SET status = ?, detail = ?, finished_at = ?
+      WHERE pipeline_id = ? AND task_id = ? AND attempt = ? AND effect_key = ?
+    `).run(
+      input.status, detail ?? null, Date.now(), input.pipelineId, input.taskId,
+      input.attempt, input.effectKey,
+    );
+    const row = this.db.prepare(`
+      SELECT * FROM agent_effects
+      WHERE pipeline_id = ? AND task_id = ? AND attempt = ? AND effect_key = ?
+    `).get(input.pipelineId, input.taskId, input.attempt, input.effectKey);
+    return row ? rowToEffect(row) : undefined;
+  }
+
+  markAttemptUnknown(pipelineId: string, taskId: string, attempt: number): number {
+    const result = this.db.prepare(`
+      UPDATE agent_effects
+      SET status = 'unknown', detail = COALESCE(detail, 'No matching tool result observed'), finished_at = ?
+      WHERE pipeline_id = ? AND task_id = ? AND attempt = ? AND status = 'observed'
+    `).run(Date.now(), pipelineId, taskId, attempt);
+    return Number(result.changes ?? 0);
+  }
+
+  list(pipelineId: string, taskId?: string): AgentEffectRecord[] {
+    const rows = taskId
+      ? this.db.prepare('SELECT * FROM agent_effects WHERE pipeline_id = ? AND task_id = ? ORDER BY started_at ASC, rowid ASC').all(pipelineId, taskId)
+      : this.db.prepare('SELECT * FROM agent_effects WHERE pipeline_id = ? ORDER BY started_at ASC, rowid ASC').all(pipelineId);
+    return rows.map(rowToEffect);
+  }
+}

package/src/orchestrate/pipeline-trace.ts

@@ -6,13 +6,15 @@
  */
 
 import type Database from 'better-sqlite3';
+import { sanitizeCredentials } from '../memory/secret-filter.js';
 
 // ── Types ──────────────────────────────────────────────────────────
 
 export type TraceEventType =
   | 'plan' | 'materialize' | 'dispatch' | 'complete' | 'fail'
   | 'retry' | 'timeout' | 'stale' | 'replan' | 'worktree:create'
-  | 'worktree:merge' | 'worktree:cleanup' | 'pipeline:start' | 'pipeline:end';
+  | 'worktree:merge' | 'worktree:cleanup' | 'pipeline:start' | 'pipeline:end'
+  | 'effect';
 
 export interface TraceEvent {
   pipelineId: string;
@@ -22,6 +24,10 @@ export interface TraceEvent {
   agent?: string;
   detail: string;
   durationMs?: number;
+  attempt?: number;
+  riskTier?: 'safe' | 'moderate' | 'dangerous';
+  effectKey?: string;
+  memoryRefs?: string[];
 }
 
 // ── Schema ─────────────────────────────────────────────────────────
@@ -35,7 +41,11 @@ const CREATE_TABLE_SQL = `
     task_id TEXT,
     agent TEXT,
     detail TEXT NOT NULL,
-    duration_ms INTEGER
+    duration_ms INTEGER,
+    attempt INTEGER,
+    risk_tier TEXT,
+    effect_key TEXT,
+    memory_refs TEXT
   )
 `;
 
@@ -48,6 +58,9 @@ const CREATE_INDEX_SQL = `
 
 export function initTraceTable(db: Database.Database): void {
   db.exec(CREATE_TABLE_SQL);
+  for (const column of ['attempt INTEGER', 'risk_tier TEXT', 'effect_key TEXT', 'memory_refs TEXT']) {
+    try { db.exec(`ALTER TABLE pipeline_traces ADD COLUMN ${column}`); } catch { /* already exists */ }
+  }
   db.exec(CREATE_INDEX_SQL);
 }
 
@@ -58,8 +71,10 @@ 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 (?, ?, ?, ?, ?, ?, ?)
+      INSERT INTO pipeline_traces (
+        pipeline_id, timestamp, type, task_id, agent, detail, duration_ms,
+        attempt, risk_tier, effect_key, memory_refs
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
   }
   _insertStmt.run(
@@ -68,8 +83,12 @@ export function writeTrace(db: Database.Database, event: TraceEvent): void {
     event.type,
     event.taskId ?? null,
     event.agent ?? null,
-    event.detail,
+    sanitizeCredentials(event.detail).slice(0, 2_000),
     event.durationMs ?? null,
+    event.attempt ?? null,
+    event.riskTier ?? null,
+    event.effectKey ?? null,
+    event.memoryRefs ? JSON.stringify(event.memoryRefs.slice(0, 16)) : null,
   );
 }
 
@@ -81,7 +100,8 @@ export function getTraces(db: Database.Database, pipelineId: string): TraceEvent
   ).all(pipelineId) as Array<{
     pipeline_id: string; timestamp: number; type: string;
     task_id: string | null; agent: string | null; detail: string;
-    duration_ms: number | null;
+    duration_ms: number | null; attempt: number | null; risk_tier: string | null;
+    effect_key: string | null; memory_refs: string | null;
   }>;
 
   return rows.map(r => ({
@@ -92,9 +112,23 @@ export function getTraces(db: Database.Database, pipelineId: string): TraceEvent
     agent: r.agent ?? undefined,
     detail: r.detail,
     durationMs: r.duration_ms ?? undefined,
+    attempt: r.attempt ?? undefined,
+    riskTier: r.risk_tier as TraceEvent['riskTier'] ?? undefined,
+    effectKey: r.effect_key ?? undefined,
+    memoryRefs: parseMemoryRefs(r.memory_refs),
   }));
 }
 
+function parseMemoryRefs(value: string | null): string[] | undefined {
+  if (!value) return undefined;
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.filter((item): item is string => typeof item === 'string') : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 // ── Prune ──────────────────────────────────────────────────────────
 
 /**

package/src/runtime/maintenance-jobs.ts

@@ -92,6 +92,7 @@ const DEFAULT_LEASE_MS = 30_000;
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const MAX_ERROR_LENGTH = 1_000;
 const DEFAULT_COMPLETED_HISTORY_RETENTION_MS = 7 * 24 * 60 * 60 * 1_000;
+export const DEFAULT_FAILED_HISTORY_RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
 
 function parsePayload(raw: unknown): Record<string, unknown> {
   if (typeof raw !== 'string' || !raw) return {};
@@ -292,20 +293,25 @@ export class MaintenanceJobStore {
 
   /**
    * Completed jobs are useful recent operator history, not permanent data.
-   * Failed jobs stay available for diagnosis until an operator explicitly
-   * resolves them or clears the database.
+   * Failed diagnostics are retained longer, but are still bounded so a
+   * permanently failing job kind cannot grow the database forever.
    */
-  pruneCompletedHistory(options: { now?: number; maxAgeMs?: number } = {}): number {
+  pruneCompletedHistory(options: { now?: number; maxAgeMs?: number; failedMaxAgeMs?: number } = {}): number {
     const now = options.now ?? Date.now();
     const maxAgeMs = Number.isFinite(options.maxAgeMs)
       ? Math.max(0, Math.floor(options.maxAgeMs!))
       : DEFAULT_COMPLETED_HISTORY_RETENTION_MS;
+    const failedMaxAgeMs = Number.isFinite(options.failedMaxAgeMs)
+      ? Math.max(0, Math.floor(options.failedMaxAgeMs!))
+      : DEFAULT_FAILED_HISTORY_RETENTION_MS;
     const result = this.db.prepare(`
       DELETE FROM maintenance_jobs
-      WHERE status = 'completed'
+      WHERE (status = 'completed'
         AND completed_at IS NOT NULL
-        AND completed_at < ?
-    `).run(now - maxAgeMs);
+        AND completed_at < ?)
+        OR (status = 'failed'
+        AND updated_at < ?)
+    `).run(now - maxAgeMs, now - failedMaxAgeMs);
     return Number(result.changes ?? 0);
   }
 

package/src/sdk.ts

@@ -28,6 +28,7 @@ import type {
   ObservationReader,
   RetrievalQuality,
 } from './types.js';
+import path from 'node:path';
 import {
   canManageObservation,
   canReadObservation,
@@ -101,6 +102,9 @@ export interface ResolveResult {
   notFound: number[];
 }
 
+const activeSdkClients = new Map<string, number>();
+let activeSdkDataDir: string | null = null;
+
 /**
  * A lightweight, self-contained memory client for reading and writing
  * Memorix observations without MCP overhead.
@@ -124,6 +128,7 @@ export class MemoryClient {
   private _oramaStore!: typeof import('./store/orama-store.js');
   private _obsStore!: typeof import('./store/obs-store.js');
   private _freshness!: typeof import('./memory/freshness.js');
+  private _sdkRefRegistered = false;
 
   /** @internal — use createMemoryClient() instead */
   constructor(projectId: string, projectRoot: string, dataDir: string) {
@@ -147,6 +152,12 @@ export class MemoryClient {
    * Called by createMemoryClient(). Do not call directly.
    */
   async _init(silent: boolean): Promise<void> {
+    const normalizedDataDir = path.resolve(this._dataDir);
+    if (activeSdkDataDir && activeSdkDataDir !== normalizedDataDir) {
+      throw new Error(
+        '[memorix-sdk] Multiple active clients with different data directories are not supported in one process; use separate processes.',
+      );
+    }
     // Suppress logs if requested
     const originalError = console.error;
     if (silent) {
@@ -167,6 +178,9 @@ export class MemoryClient {
 
       // Prepare search index (hydrate Orama from SQLite)
       await this._observations.prepareSearchIndex();
+      activeSdkDataDir = normalizedDataDir;
+      activeSdkClients.set(normalizedDataDir, (activeSdkClients.get(normalizedDataDir) ?? 0) + 1);
+      this._sdkRefRegistered = true;
     } finally {
       if (silent) {
         console.error = originalError;
@@ -298,6 +312,16 @@ export class MemoryClient {
   async close(): Promise<void> {
     if (this._closed) return;
     this._closed = true;
+    const normalizedDataDir = path.resolve(this._dataDir);
+    const currentRefs = activeSdkClients.get(normalizedDataDir) ?? 0;
+    const remainingRefs = Math.max(0, currentRefs - (this._sdkRefRegistered ? 1 : 0));
+    if (remainingRefs > 0) {
+      activeSdkClients.set(normalizedDataDir, remainingRefs);
+      this._sdkRefRegistered = false;
+      return;
+    }
+    activeSdkClients.delete(normalizedDataDir);
+    if (activeSdkDataDir === normalizedDataDir) activeSdkDataDir = null;
     try {
       this._obsStore.resetObservationStore();
       await this._oramaStore.resetDb();

package/src/server/mcp-binding-store.ts

@@ -1,6 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { getDatabase } from '../store/sqlite-db.js';
 
+export const DEFAULT_MCP_BINDING_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
 export interface McpProjectBinding {
   handleId: string;
   projectId: string;
@@ -38,6 +40,7 @@ export class McpBindingStore {
 
   create(input: { projectId: string; projectRoot: string; dataDir: string; ttlMs?: number }): McpProjectBinding {
     const now = new Date();
+    const ttlMs = input.ttlMs ?? DEFAULT_MCP_BINDING_TTL_MS;
     const binding: McpProjectBinding = {
       handleId: `mxh_${randomUUID().replace(/-/g, '')}`,
       projectId: input.projectId,
@@ -45,7 +48,7 @@ export class McpBindingStore {
       dataDir: input.dataDir,
       createdAt: now.toISOString(),
       lastUsedAt: now.toISOString(),
-      ...(input.ttlMs && input.ttlMs > 0 ? { expiresAt: new Date(now.getTime() + input.ttlMs).toISOString() } : {}),
+      ...(ttlMs > 0 ? { expiresAt: new Date(now.getTime() + ttlMs).toISOString() } : {}),
     };
     this.requireDb().prepare(`
       INSERT INTO mcp_bindings (handle_id, project_id, project_root, data_dir, created_at, last_used_at, expires_at)
@@ -69,8 +72,16 @@ export class McpBindingStore {
     const binding = this.get(handleId);
     if (!binding) return undefined;
     const lastUsedAt = new Date().toISOString();
-    this.requireDb().prepare(`UPDATE mcp_bindings SET last_used_at = ? WHERE handle_id = ?`).run(lastUsedAt, handleId);
-    return { ...binding, lastUsedAt };
+    const expiresAt = new Date(Date.now() + DEFAULT_MCP_BINDING_TTL_MS).toISOString();
+    this.requireDb().prepare(`UPDATE mcp_bindings SET last_used_at = ?, expires_at = ? WHERE handle_id = ?`).run(lastUsedAt, expiresAt, handleId);
+    return { ...binding, lastUsedAt, expiresAt };
+  }
+
+  cleanupExpired(now = Date.now()): number {
+    const result = this.requireDb().prepare(
+      `DELETE FROM mcp_bindings WHERE expires_at IS NOT NULL AND expires_at <= ?`,
+    ).run(new Date(now).toISOString());
+    return Number(result.changes ?? 0);
   }
 
   /** Reuse the most recent valid extension handle for a verified project root. */