@stackmemoryai/stackmemory 1.10.5 → 1.12.0

package/dist/src/core/provenance/provenance-store.js

@@ -0,0 +1,194 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { logger } from "../monitoring/logger.js";
+import { TraceEventSchema } from "./types.js";
+class ProvenanceStore {
+  db;
+  constructor(db) {
+    this.db = db;
+    this.initializeSchema();
+  }
+  /**
+   * Initialize database schema for trace events
+   */
+  initializeSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS trace_events (
+        trace_id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        parent_trace_id TEXT,
+        tenant_id TEXT NOT NULL,
+        timestamp TEXT NOT NULL,
+        actor TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        inputs TEXT NOT NULL,
+        outputs TEXT NOT NULL,
+        tokens_in INTEGER NOT NULL DEFAULT 0,
+        tokens_out INTEGER NOT NULL DEFAULT 0,
+        cost_usd REAL NOT NULL DEFAULT 0,
+        score REAL,
+        feedback TEXT,
+        provenance TEXT NOT NULL,
+        created_at INTEGER DEFAULT (unixepoch())
+      )
+    `);
+    this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_trace_events_session_id ON trace_events(session_id);
+      CREATE INDEX IF NOT EXISTS idx_trace_events_tenant_id ON trace_events(tenant_id);
+      CREATE INDEX IF NOT EXISTS idx_trace_events_operation ON trace_events(operation);
+      CREATE INDEX IF NOT EXISTS idx_trace_events_timestamp ON trace_events(timestamp);
+      CREATE INDEX IF NOT EXISTS idx_trace_events_parent_trace_id ON trace_events(parent_trace_id);
+    `);
+  }
+  /**
+   * Record a trace event
+   */
+  record(event) {
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO trace_events (
+        trace_id, session_id, parent_trace_id, tenant_id, timestamp,
+        actor, operation, inputs, outputs,
+        tokens_in, tokens_out, cost_usd, score, feedback, provenance
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    try {
+      stmt.run(
+        event.traceId,
+        event.sessionId,
+        event.parentTraceId ?? null,
+        event.tenantId,
+        event.timestamp,
+        JSON.stringify(event.actor),
+        event.operation,
+        JSON.stringify(event.inputs),
+        JSON.stringify(event.outputs),
+        event.tokensIn,
+        event.tokensOut,
+        event.costUsd,
+        event.score ?? null,
+        event.feedback ?? null,
+        JSON.stringify(event.provenance)
+      );
+      logger.debug(`Recorded trace event ${event.traceId}`);
+    } catch (error) {
+      logger.error(
+        `Failed to record trace event ${event.traceId}:`,
+        error
+      );
+      throw error;
+    }
+  }
+  /**
+   * Get a trace event by traceId
+   */
+  get(traceId) {
+    const row = this.db.prepare("SELECT * FROM trace_events WHERE trace_id = ?").get(traceId);
+    if (!row) return void 0;
+    return this.rowToEvent(row);
+  }
+  /**
+   * Query trace events with filters
+   */
+  query(opts = {}) {
+    const conditions = [];
+    const params = [];
+    if (opts.sessionId) {
+      conditions.push("session_id = ?");
+      params.push(opts.sessionId);
+    }
+    if (opts.tenantId) {
+      conditions.push("tenant_id = ?");
+      params.push(opts.tenantId);
+    }
+    if (opts.operation) {
+      conditions.push("operation = ?");
+      params.push(opts.operation);
+    }
+    if (opts.since) {
+      conditions.push("timestamp >= ?");
+      params.push(opts.since);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = opts.limit ?? 100;
+    const rows = this.db.prepare(
+      `SELECT * FROM trace_events ${where} ORDER BY timestamp DESC LIMIT ?`
+    ).all(...params, limit);
+    return rows.map((row) => this.rowToEvent(row));
+  }
+  /**
+   * Mark a trace event as superseded by another
+   */
+  supersede(traceId, supersededBy) {
+    const row = this.db.prepare("SELECT provenance FROM trace_events WHERE trace_id = ?").get(traceId);
+    if (!row) return;
+    const provenance = JSON.parse(row.provenance);
+    provenance.supersededBy = supersededBy;
+    this.db.prepare("UPDATE trace_events SET provenance = ? WHERE trace_id = ?").run(JSON.stringify(provenance), traceId);
+  }
+  /**
+   * Follow parentTraceId chain to build lineage
+   */
+  getLineage(traceId) {
+    const lineage = [];
+    let currentId = traceId;
+    while (currentId) {
+      const event = this.get(currentId);
+      if (!event) break;
+      lineage.push(event);
+      currentId = event.parentTraceId;
+    }
+    return lineage;
+  }
+  /**
+   * Aggregate stats across trace events
+   */
+  getStats(tenantId) {
+    const where = tenantId ? "WHERE tenant_id = ?" : "";
+    const params = tenantId ? [tenantId] : [];
+    const row = this.db.prepare(
+      `
+        SELECT
+          COUNT(*) as total_events,
+          COALESCE(SUM(tokens_in), 0) as total_tokens_in,
+          COALESCE(SUM(tokens_out), 0) as total_tokens_out,
+          COALESCE(SUM(cost_usd), 0) as total_cost_usd,
+          COALESCE(AVG(json_extract(provenance, '$.confidence')), 0) as avg_confidence
+        FROM trace_events ${where}
+      `
+    ).get(...params);
+    return {
+      totalEvents: row.total_events,
+      totalTokensIn: row.total_tokens_in,
+      totalTokensOut: row.total_tokens_out,
+      totalCostUsd: row.total_cost_usd,
+      avgConfidence: row.avg_confidence
+    };
+  }
+  /**
+   * Convert a database row to a TraceEvent
+   */
+  rowToEvent(row) {
+    return TraceEventSchema.parse({
+      timestamp: row.timestamp,
+      sessionId: row.session_id,
+      traceId: row.trace_id,
+      parentTraceId: row.parent_trace_id ?? void 0,
+      tenantId: row.tenant_id,
+      actor: JSON.parse(row.actor),
+      operation: row.operation,
+      inputs: JSON.parse(row.inputs),
+      outputs: JSON.parse(row.outputs),
+      tokensIn: row.tokens_in,
+      tokensOut: row.tokens_out,
+      costUsd: row.cost_usd,
+      score: row.score ?? void 0,
+      feedback: row.feedback ?? void 0,
+      provenance: JSON.parse(row.provenance)
+    });
+  }
+}
+export {
+  ProvenanceStore
+};

package/dist/src/core/provenance/types.js

@@ -0,0 +1,82 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { z } from "zod";
+const SourceRefSchema = z.object({
+  system: z.string(),
+  // e.g., "linear", "github", "slack", "manual"
+  externalId: z.string(),
+  // ID in source system
+  url: z.string().optional(),
+  // link to source
+  fetchedAt: z.string().datetime(),
+  // ISO8601
+  hash: z.string().optional()
+  // content hash for change detection
+});
+const ProvenanceRecordSchema = z.object({
+  sources: z.array(SourceRefSchema),
+  derivation: z.array(z.string()),
+  // chain of transformations
+  confidence: z.number().min(0).max(1),
+  supersededBy: z.string().optional(),
+  // ID of superseding record
+  programVersion: z.string().optional()
+  // version that produced this
+});
+const ActorSchema = z.object({
+  host: z.string(),
+  // e.g., "claude-code", "cursor", "codex"
+  agent: z.string(),
+  // agent identifier
+  user: z.string()
+  // user identifier
+});
+const TraceEventSchema = z.object({
+  timestamp: z.string().datetime(),
+  // ISO8601
+  sessionId: z.string(),
+  traceId: z.string(),
+  parentTraceId: z.string().optional(),
+  tenantId: z.string(),
+  actor: ActorSchema,
+  operation: z.string(),
+  // what happened
+  inputs: z.unknown(),
+  outputs: z.unknown(),
+  tokensIn: z.number().int().min(0),
+  tokensOut: z.number().int().min(0),
+  costUsd: z.number().min(0),
+  score: z.number().optional(),
+  // numeric eval (ASI-shaped)
+  feedback: z.string().optional(),
+  // textual feedback for GEPA
+  provenance: ProvenanceRecordSchema
+});
+const ConfidenceClassificationSchema = z.enum([
+  "accept",
+  "review",
+  "discard"
+]);
+const ConfidenceScoreSchema = z.object({
+  confidence: z.number().min(0).max(1),
+  signals: z.record(z.string(), z.unknown()),
+  classification: ConfidenceClassificationSchema
+});
+const ConfidenceConfigSchema = z.object({
+  thresholds: z.object({
+    accept: z.number().min(0).max(1),
+    review: z.number().min(0).max(1)
+  }),
+  weights: z.record(z.string(), z.number())
+});
+export {
+  ActorSchema,
+  ConfidenceClassificationSchema,
+  ConfidenceConfigSchema,
+  ConfidenceScoreSchema,
+  ProvenanceRecordSchema,
+  SourceRefSchema,
+  TraceEventSchema
+};

package/dist/src/core/session/project-handoff.js

@@ -0,0 +1,64 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+function getProjectHandoffPaths(projectRoot) {
+  return {
+    handoffPath: join(projectRoot, ".stackmemory", "last-handoff.md"),
+    metadataPath: join(projectRoot, ".stackmemory", "last-handoff-meta.json")
+  };
+}
+function parseBranchFromHandoffContent(content) {
+  const compactMatch = content.match(/^# Handoff:\s+.+?@([^\n]+)$/m);
+  if (compactMatch?.[1]) {
+    return compactMatch[1].trim();
+  }
+  const verboseMatch = content.match(/^\*\*Branch\*\*:\s+([^\n]+)$/m);
+  if (verboseMatch?.[1]) {
+    return verboseMatch[1].trim();
+  }
+  const ultraMatch = content.match(/^\[H\].+?@([^|\n]+)\|/m);
+  if (ultraMatch?.[1]) {
+    return ultraMatch[1].trim();
+  }
+  return null;
+}
+function loadProjectHandoff(projectRoot, currentBranch) {
+  const { handoffPath, metadataPath } = getProjectHandoffPaths(projectRoot);
+  if (!existsSync(handoffPath)) {
+    return null;
+  }
+  const content = readFileSync(handoffPath, "utf8").trim();
+  if (!content) {
+    return null;
+  }
+  let metadata = null;
+  if (existsSync(metadataPath)) {
+    try {
+      metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+    } catch {
+      metadata = null;
+    }
+  }
+  const branch = metadata?.branch || parseBranchFromHandoffContent(content);
+  if (currentBranch && branch && branch !== currentBranch) {
+    return {
+      content,
+      branch,
+      compatible: false,
+      mismatchReason: `handoff is for branch ${branch}, current branch is ${currentBranch}`
+    };
+  }
+  return {
+    content,
+    branch: branch || null,
+    compatible: true
+  };
+}
+export {
+  getProjectHandoffPaths,
+  loadProjectHandoff,
+  parseBranchFromHandoffContent
+};

package/dist/src/core/session/session-manager.js

@@ -7,6 +7,7 @@ import * as fs from "fs/promises";
 import * as path from "path";
 import { logger } from "../monitoring/logger.js";
 import { SystemError, ErrorCode } from "../errors/index.js";
+import { canonicalStateStore } from "../shared-state/canonical-store.js";
 function _getEnv(key, defaultValue) {
   const value = process.env[key];
   if (value === void 0) {
@@ -119,6 +120,16 @@ class SessionManager {
     };
     await this.saveSession(session);
     await this.setProjectActiveSession(params.projectId, session.sessionId);
+    await canonicalStateStore.appendEvent({
+      type: "session_created",
+      tool: "stackmemory",
+      sessionId: session.sessionId,
+      projectId: session.projectId,
+      branch: session.branch,
+      payload: {
+        state: session.state
+      }
+    });
     this.currentSession = session;
     logger.info("Created new session", {
       sessionId: session.sessionId,
@@ -152,6 +163,14 @@ class SessionManager {
       `${session.sessionId}.json`
     );
     await fs.writeFile(sessionPath, JSON.stringify(session, null, 2));
+    await canonicalStateStore.upsertSession({
+      sessionId: session.sessionId,
+      tool: "stackmemory",
+      projectId: session.projectId,
+      branch: session.branch,
+      status: session.state,
+      metadata: session.metadata
+    });
   }
   async suspendSession(sessionId) {
     const id = sessionId || this.currentSession?.sessionId;
@@ -193,6 +212,15 @@ class SessionManager {
         `${session.sessionId}.json`
       );
       await fs.rename(sessionPath, historyPath);
+      await canonicalStateStore.endSession(session.sessionId, "closed");
+      await canonicalStateStore.appendEvent({
+        type: "session_closed",
+        tool: "stackmemory",
+        sessionId: session.sessionId,
+        projectId: session.projectId,
+        branch: session.branch,
+        payload: {}
+      });
     }
   }
   async listSessions(filter) {