@psiclawops/hypermem 0.5.0 → 0.5.1

package/dist/secret-scanner.js

@@ -0,0 +1,248 @@
+/**
+ * hypermem Secret Scanner
+ *
+ * Lightweight regex-based gate to prevent secrets from leaking into
+ * shared memory (visibility >= 'org'). Runs before any write that
+ * promotes content to org/council/fleet visibility.
+ *
+ * Design principles:
+ *   - Fast: regex-only, no LLM dependency
+ *   - Conservative: false positives are okay; false negatives are not
+ *   - Auditable: each hit includes the rule name and matched region (redacted)
+ *   - Not a full DLP system: blocks the obvious leaks; does not guarantee clean content
+ *
+ * Patterns sourced from:
+ *   - gitleaks ruleset (https://github.com/gitleaks/gitleaks)
+ *   - trufflehog common patterns
+ *   - Manual additions for OpenClaw-specific secrets
+ */
+const RULES = [
+    // ── API Keys ──────────────────────────────────────────────
+    {
+        id: 'anthropic-api-key',
+        description: 'Anthropic API key',
+        pattern: /\bsk-ant-[a-zA-Z0-9\-_]{20,}\b/g,
+    },
+    {
+        id: 'openai-api-key',
+        description: 'OpenAI API key',
+        pattern: /\bsk-[a-zA-Z0-9\-_]{20,}\b/g,
+    },
+    {
+        id: 'openai-org-id',
+        description: 'OpenAI organization ID',
+        pattern: /\borg-[a-zA-Z0-9]{16,}\b/g,
+    },
+    {
+        id: 'github-pat-classic',
+        description: 'GitHub personal access token (classic)',
+        pattern: /\bghp_[a-zA-Z0-9]{36}\b/g,
+    },
+    {
+        id: 'github-pat-fine',
+        description: 'GitHub fine-grained personal access token',
+        pattern: /\bgithub_pat_[a-zA-Z0-9_]{82}\b/g,
+    },
+    {
+        id: 'github-oauth-token',
+        description: 'GitHub OAuth token',
+        pattern: /\bgho_[a-zA-Z0-9]{36}\b/g,
+    },
+    {
+        id: 'github-app-token',
+        description: 'GitHub App installation token',
+        pattern: /\bghs_[a-zA-Z0-9]{36}\b/g,
+    },
+    {
+        id: 'github-refresh-token',
+        description: 'GitHub refresh token',
+        pattern: /\bghr_[a-zA-Z0-9]{76}\b/g,
+    },
+    {
+        id: 'aws-access-key',
+        description: 'AWS access key ID',
+        pattern: /\b(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}\b/g,
+    },
+    {
+        id: 'aws-secret-key',
+        description: 'AWS secret access key (heuristic)',
+        pattern: /(?:aws_secret_access_key|AWS_SECRET_ACCESS_KEY)["\s:=]+([A-Za-z0-9\/+]{40})\b/gi,
+    },
+    {
+        id: 'google-api-key',
+        description: 'Google API key',
+        pattern: /\bAIza[0-9A-Za-z_\-]{35}\b/g,
+    },
+    {
+        id: 'google-oauth',
+        description: 'Google OAuth client secret',
+        pattern: /\bGOCSPX-[0-9A-Za-z_\-]{28}\b/g,
+    },
+    {
+        id: 'slack-token',
+        description: 'Slack API token',
+        pattern: /\bxox[baprs]-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,32}\b/g,
+    },
+    {
+        id: 'slack-webhook',
+        description: 'Slack incoming webhook URL',
+        pattern: /https:\/\/hooks\.slack\.com\/services\/[A-Z0-9]{9,11}\/[A-Z0-9]{9,11}\/[a-zA-Z0-9]{24}/g,
+    },
+    {
+        id: 'discord-token',
+        description: 'Discord bot token',
+        pattern: /\b[MNO][a-zA-Z0-9]{23}\.[a-zA-Z0-9_\-]{6}\.[a-zA-Z0-9_\-]{27}\b/g,
+    },
+    {
+        id: 'discord-webhook',
+        description: 'Discord webhook URL',
+        pattern: /https:\/\/discord(?:app)?\.com\/api\/webhooks\/[0-9]{17,19}\/[a-zA-Z0-9_\-]{68}/g,
+    },
+    {
+        id: 'stripe-key',
+        description: 'Stripe API key',
+        pattern: /\b(?:sk|pk|rk)_(?:live|test)_[a-zA-Z0-9]{24,99}\b/g,
+    },
+    {
+        id: 'sendgrid-key',
+        description: 'SendGrid API key',
+        pattern: /\bSG\.[a-zA-Z0-9\-_]{22,}\.[a-zA-Z0-9\-_]{43,}\b/g,
+    },
+    {
+        id: 'twilio-account-sid',
+        description: 'Twilio Account SID',
+        pattern: /\bAC[0-9a-fA-F]{32}\b/g,
+    },
+    {
+        id: 'twilio-auth-token',
+        description: 'Twilio Auth Token (heuristic)',
+        pattern: /(?:twilio[_\s\-]*(?:auth[_\s\-]*)?token)["\s:=]+([0-9a-f]{32})\b/gi,
+    },
+    // ── Private Keys / Certificates ───────────────────────────
+    {
+        id: 'pem-private-key',
+        description: 'PEM private key block',
+        pattern: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----/g,
+    },
+    {
+        id: 'pem-certificate',
+        description: 'PEM certificate (may contain private data)',
+        pattern: /-----BEGIN CERTIFICATE-----/g,
+    },
+    // ── Passwords in common config patterns ───────────────────
+    {
+        id: 'password-assignment',
+        description: 'Password in config-like assignment',
+        // Matches: password=<value>, "password": "<value>", PASSWORD=<value>
+        pattern: /(?:^|[,{;\n])\s*(?:password|passwd|secret|token|api_key|apikey|api-key|access_token|auth_token|client_secret)\s*[=:]\s*["']([^"'\n]{8,})["']/gim,
+        minEntropy: 2.5,
+    },
+    // ── Database connection strings ────────────────────────────
+    {
+        id: 'db-connection-string',
+        description: 'Database connection string with credentials',
+        pattern: /(?:postgres|postgresql|mysql|mongodb|redis):\/\/[^:]+:[^@]{6,}@/gi,
+    },
+    // ── Bearer tokens ─────────────────────────────────────────
+    {
+        id: 'bearer-token-header',
+        description: 'Bearer token in Authorization header value',
+        pattern: /Authorization[:\s]+Bearer\s+([a-zA-Z0-9\-_=.]{20,})/gi,
+    },
+    // ── JWT ───────────────────────────────────────────────────
+    {
+        id: 'jwt-token',
+        description: 'JSON Web Token',
+        pattern: /\beyJ[a-zA-Z0-9\-_]+\.eyJ[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\b/g,
+        minEntropy: 3.0,
+    },
+    // ── OpenClaw-specific ──────────────────────────────────────
+    {
+        id: 'openclaw-api-key',
+        description: 'OpenClaw API key',
+        pattern: /\boc_[a-zA-Z0-9\-_]{24,}\b/g,
+    },
+];
+// ─── Entropy Calculation ─────────────────────────────────────────
+/**
+ * Calculate Shannon entropy of a string (bits per character, base 2).
+ * Used to filter out low-entropy false positives like "password=example".
+ */
+function shannonEntropy(s) {
+    if (s.length === 0)
+        return 0;
+    const freq = new Map();
+    for (const ch of s) {
+        freq.set(ch, (freq.get(ch) || 0) + 1);
+    }
+    let entropy = 0;
+    for (const count of freq.values()) {
+        const p = count / s.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+// ─── Redaction ───────────────────────────────────────────────────
+/**
+ * Redact a matched value: show first 3 and last 3 characters, mask the middle.
+ */
+function redact(value) {
+    if (value.length <= 8)
+        return '[REDACTED]';
+    const prefix = value.slice(0, 3);
+    const suffix = value.slice(-3);
+    const masked = '*'.repeat(Math.min(value.length - 6, 20));
+    return `${prefix}${masked}${suffix}`;
+}
+// ─── Public API ──────────────────────────────────────────────────
+/**
+ * Scan content for secrets before promoting to shared visibility.
+ *
+ * Returns { clean: true } when no secrets found.
+ * Returns { clean: false, hits } when secrets are detected.
+ *
+ * Callers must NOT write content with visibility >= 'org' when clean is false.
+ */
+export function scanForSecrets(content) {
+    const hits = [];
+    for (const rule of RULES) {
+        // Reset lastIndex for global regexes
+        rule.pattern.lastIndex = 0;
+        let match;
+        while ((match = rule.pattern.exec(content)) !== null) {
+            const matched = match[1] ?? match[0]; // prefer capture group 1 if present
+            // Entropy filter
+            if (rule.minEntropy && shannonEntropy(matched) < rule.minEntropy) {
+                continue;
+            }
+            hits.push({
+                rule: rule.id,
+                description: rule.description,
+                redactedMatch: redact(matched),
+                offset: match.index,
+            });
+            // Cap at 10 hits per content to avoid O(n²) explosion on adversarial input
+            if (hits.length >= 10)
+                break;
+        }
+        if (hits.length >= 10)
+            break;
+    }
+    return { clean: hits.length === 0, hits };
+}
+/**
+ * Returns true when content is safe to promote to shared visibility (>= 'org').
+ * Convenience wrapper around scanForSecrets.
+ */
+export function isSafeForSharedVisibility(content) {
+    return scanForSecrets(content).clean;
+}
+/**
+ * Check whether a visibility level requires secret scanning.
+ * Scanning is required for 'org', 'council', and 'fleet'.
+ * 'private' content stays with the owner — no cross-agent risk.
+ */
+export function requiresScan(visibility) {
+    return visibility === 'org' || visibility === 'council' || visibility === 'fleet';
+}
+//# sourceMappingURL=secret-scanner.js.map

package/dist/seed.d.ts

@@ -0,0 +1,108 @@
+/**
+ * hypermem Workspace Seeder
+ *
+ * Reads ACA workspace files, chunks them by logical section, and indexes
+ * into hypermem for demand-loaded retrieval (ACA offload).
+ *
+ * Usage:
+ *   const seeder = new WorkspaceSeeder(hypermem);
+ *   const result = await seeder.seedWorkspace('/path/to/workspace', { agentId: 'forge' });
+ *
+ * Idempotent: skips files whose source hash hasn't changed since last index.
+ * Atomic: each file's chunks are swapped in a single transaction.
+ *
+ * Files seeded (from ACA_COLLECTIONS):
+ *   POLICY.md      → governance/policy   (shared-fleet)
+ *   CHARTER.md     → governance/charter  (per-tier)
+ *   COMMS.md       → governance/comms    (shared-fleet)
+ *   AGENTS.md      → operations/agents   (per-tier)
+ *   TOOLS.md       → operations/tools    (per-agent)
+ *   SOUL.md        → identity/soul       (per-agent)
+ *   JOB.md         → identity/job        (per-agent)
+ *   MOTIVATIONS.md → identity/motivations(per-agent)
+ *   MEMORY.md      → memory/decisions    (per-agent)
+ *   memory/*.md    → memory/daily        (per-agent)
+ */
+import { type IndexResult } from './doc-chunk-store.js';
+export interface SeedOptions {
+    /** Agent ID for per-agent scoped chunks */
+    agentId?: string;
+    /** Tier for per-tier scoped chunks (council/director) */
+    tier?: string;
+    /** Whether to force re-index even if hash unchanged */
+    force?: boolean;
+    /** Only seed specific collections (e.g., ['governance/policy']) */
+    collections?: string[];
+    /** Whether to include daily memory files (memory/YYYY-MM-DD.md) */
+    includeDailyMemory?: boolean;
+    /** Max daily memory files to include (most recent first) */
+    dailyMemoryLimit?: number;
+}
+export interface SeedFileResult {
+    filePath: string;
+    collection: string;
+    result: IndexResult;
+}
+export interface SeedResult {
+    /** Files successfully processed */
+    files: SeedFileResult[];
+    /** Total new chunks inserted */
+    totalInserted: number;
+    /** Total stale chunks deleted */
+    totalDeleted: number;
+    /** Files that were up to date (skipped) */
+    skipped: number;
+    /** Files that were re-indexed */
+    reindexed: number;
+    /** Files that had errors */
+    errors: Array<{
+        filePath: string;
+        error: string;
+    }>;
+}
+export declare class WorkspaceSeeder {
+    private db;
+    private chunkStore;
+    constructor(db: import('node:sqlite').DatabaseSync);
+    /**
+     * Seed all ACA files from a workspace directory.
+     */
+    seedWorkspace(workspaceDir: string, opts?: SeedOptions): Promise<SeedResult>;
+    /**
+     * Seed a single file explicitly.
+     */
+    seedFile(filePath: string, collection: string, opts?: SeedOptions): SeedFileResult;
+    /**
+     * Check which workspace files need re-indexing.
+     */
+    checkStaleness(workspaceDir: string, opts?: SeedOptions): Array<{
+        filePath: string;
+        collection: string;
+        needsReindex: boolean;
+    }>;
+    /**
+     * Get stats about what's currently indexed.
+     */
+    getIndexStats(): {
+        collection: string;
+        count: number;
+        sources: number;
+        totalTokens: number;
+    }[];
+    /**
+     * Query indexed chunks by collection.
+     */
+    queryChunks(collection: string, opts?: {
+        agentId?: string;
+        tier?: string;
+        limit?: number;
+        keyword?: string;
+    }): import("./doc-chunk-store.js").DocChunkRow[];
+    private discoverFiles;
+}
+/**
+ * Seed a workspace directly from a DatabaseSync instance.
+ * Convenience wrapper for use in the hook handler and CLI.
+ */
+export declare function seedWorkspace(db: import('node:sqlite').DatabaseSync, workspaceDir: string, opts?: SeedOptions): Promise<SeedResult>;
+//# sourceMappingURL=seed.d.ts.map

package/dist/seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../src/seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAIvE,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,mCAAmC;IACnC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAID,qBAAa,eAAe;IAGd,OAAO,CAAC,EAAE;IAFtB,OAAO,CAAC,UAAU,CAAgB;gBAEd,EAAE,EAAE,OAAO,aAAa,EAAE,YAAY;IAI1D;;OAEG;IACG,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAmDtF;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,cAAc;IAmBtF;;OAEG;IACH,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,KAAK,CAAC;QAClE,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;IAeF;;OAEG;IACH,aAAa;;;;;;IAIb;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO;IAMhH,OAAO,CAAC,aAAa;CAuCtB;AAID;;;GAGG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,OAAO,aAAa,EAAE,YAAY,EACtC,YAAY,EAAE,MAAM,EACpB,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,UAAU,CAAC,CAGrB"}

package/dist/seed.js

@@ -0,0 +1,177 @@
+/**
+ * hypermem Workspace Seeder
+ *
+ * Reads ACA workspace files, chunks them by logical section, and indexes
+ * into hypermem for demand-loaded retrieval (ACA offload).
+ *
+ * Usage:
+ *   const seeder = new WorkspaceSeeder(hypermem);
+ *   const result = await seeder.seedWorkspace('/path/to/workspace', { agentId: 'forge' });
+ *
+ * Idempotent: skips files whose source hash hasn't changed since last index.
+ * Atomic: each file's chunks are swapped in a single transaction.
+ *
+ * Files seeded (from ACA_COLLECTIONS):
+ *   POLICY.md      → governance/policy   (shared-fleet)
+ *   CHARTER.md     → governance/charter  (per-tier)
+ *   COMMS.md       → governance/comms    (shared-fleet)
+ *   AGENTS.md      → operations/agents   (per-tier)
+ *   TOOLS.md       → operations/tools    (per-agent)
+ *   SOUL.md        → identity/soul       (per-agent)
+ *   JOB.md         → identity/job        (per-agent)
+ *   MOTIVATIONS.md → identity/motivations(per-agent)
+ *   MEMORY.md      → memory/decisions    (per-agent)
+ *   memory/*.md    → memory/daily        (per-agent)
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { chunkFile, inferCollection, ACA_COLLECTIONS, hashContent } from './doc-chunker.js';
+import { DocChunkStore } from './doc-chunk-store.js';
+// ─── Seeder ──────────────────────────────────────────────────────
+export class WorkspaceSeeder {
+    db;
+    chunkStore;
+    constructor(db) {
+        this.db = db;
+        this.chunkStore = new DocChunkStore(db);
+    }
+    /**
+     * Seed all ACA files from a workspace directory.
+     */
+    async seedWorkspace(workspaceDir, opts = {}) {
+        const result = {
+            files: [],
+            totalInserted: 0,
+            totalDeleted: 0,
+            skipped: 0,
+            reindexed: 0,
+            errors: [],
+        };
+        const filesToProcess = this.discoverFiles(workspaceDir, opts);
+        for (const { filePath, collectionDef } of filesToProcess) {
+            // Skip if collection filter provided
+            if (opts.collections && !opts.collections.includes(collectionDef.collection)) {
+                continue;
+            }
+            try {
+                const chunks = chunkFile(filePath, {
+                    collection: collectionDef.collection,
+                    scope: collectionDef.scope,
+                    tier: collectionDef.scope === 'per-tier' ? (opts.tier ?? 'all') : undefined,
+                    agentId: collectionDef.scope === 'per-agent' ? opts.agentId : undefined,
+                });
+                if (chunks.length === 0)
+                    continue;
+                // Force re-index if requested
+                if (opts.force) {
+                    this.chunkStore.deleteSource(filePath, collectionDef.collection);
+                }
+                const indexResult = this.chunkStore.indexChunks(chunks);
+                result.files.push({ filePath, collection: collectionDef.collection, result: indexResult });
+                result.totalInserted += indexResult.inserted;
+                result.totalDeleted += indexResult.deleted;
+                if (indexResult.skipped)
+                    result.skipped++;
+                if (indexResult.reindexed)
+                    result.reindexed++;
+            }
+            catch (err) {
+                result.errors.push({
+                    filePath,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Seed a single file explicitly.
+     */
+    seedFile(filePath, collection, opts = {}) {
+        const collectionDef = Object.values(ACA_COLLECTIONS).find(d => d.collection === collection)
+            ?? { collection, scope: 'per-agent', description: '' };
+        if (opts.force) {
+            this.chunkStore.deleteSource(filePath, collection);
+        }
+        const chunks = chunkFile(filePath, {
+            collection,
+            scope: collectionDef.scope,
+            tier: collectionDef.scope === 'per-tier' ? (opts.tier ?? 'all') : undefined,
+            agentId: collectionDef.scope === 'per-agent' ? opts.agentId : undefined,
+        });
+        const indexResult = this.chunkStore.indexChunks(chunks);
+        return { filePath, collection, result: indexResult };
+    }
+    /**
+     * Check which workspace files need re-indexing.
+     */
+    checkStaleness(workspaceDir, opts = {}) {
+        const filesToProcess = this.discoverFiles(workspaceDir, opts);
+        return filesToProcess.map(({ filePath, collectionDef }) => {
+            try {
+                const content = readFileSync(filePath, 'utf-8');
+                const hash = hashContent(content);
+                const needsReindex = this.chunkStore.needsReindex(filePath, collectionDef.collection, hash);
+                return { filePath, collection: collectionDef.collection, needsReindex };
+            }
+            catch {
+                return { filePath, collection: collectionDef.collection, needsReindex: true };
+            }
+        });
+    }
+    /**
+     * Get stats about what's currently indexed.
+     */
+    getIndexStats() {
+        return this.chunkStore.getStats();
+    }
+    /**
+     * Query indexed chunks by collection.
+     */
+    queryChunks(collection, opts = {}) {
+        return this.chunkStore.queryChunks({ collection, ...opts });
+    }
+    // ─── Private helpers ─────────────────────────────────────────
+    discoverFiles(workspaceDir, opts) {
+        const files = [];
+        // Known ACA files in workspace root
+        for (const fileName of Object.keys(ACA_COLLECTIONS)) {
+            const filePath = path.join(workspaceDir, fileName);
+            if (!existsSync(filePath))
+                continue;
+            const collectionDef = inferCollection(fileName, opts.agentId);
+            if (!collectionDef)
+                continue;
+            files.push({ filePath, collectionDef });
+        }
+        // Daily memory files
+        if (opts.includeDailyMemory !== false) {
+            const memoryDir = path.join(workspaceDir, 'memory');
+            if (existsSync(memoryDir)) {
+                const memFiles = readdirSync(memoryDir)
+                    .filter(f => /^\d{4}-\d{2}-\d{2}\.md$/.test(f))
+                    .sort()
+                    .reverse(); // Most recent first
+                const limit = opts.dailyMemoryLimit ?? 30;
+                for (const memFile of memFiles.slice(0, limit)) {
+                    const filePath = path.join(memoryDir, memFile);
+                    const collectionDef = inferCollection(memFile, opts.agentId);
+                    if (collectionDef) {
+                        files.push({ filePath, collectionDef });
+                    }
+                }
+            }
+        }
+        return files;
+    }
+}
+// ─── Standalone seed function ────────────────────────────────────
+/**
+ * Seed a workspace directly from a DatabaseSync instance.
+ * Convenience wrapper for use in the hook handler and CLI.
+ */
+export async function seedWorkspace(db, workspaceDir, opts = {}) {
+    const seeder = new WorkspaceSeeder(db);
+    return seeder.seedWorkspace(workspaceDir, opts);
+}
+//# sourceMappingURL=seed.js.map

package/dist/session-flusher.d.ts

@@ -0,0 +1,53 @@
+/**
+ * session-flusher.ts
+ *
+ * Provides a clean, operator-safe way to flush a session's hot cache from Redis
+ * without touching long-term memory (facts, vectors, episodes, knowledge graph).
+ *
+ * Used to implement the /fresh slash command — lets users start a new unwarmed
+ * session on demand without requiring a gateway restart.
+ *
+ * Long-term memory (facts, vectors, episodes) is intentionally preserved.
+ * It will re-warm naturally on the next session bootstrap.
+ */
+import type { CacheLayer } from './cache.js';
+export interface FlushSessionOptions {
+    /** If true, also clears topic-level Redis keys for this session */
+    includeTopics?: boolean;
+}
+export interface FlushSessionResult {
+    success: boolean;
+    agentId: string;
+    sessionKey: string;
+    /** ISO timestamp of the flush */
+    flushedAt: string;
+    /** What was cleared */
+    cleared: string[];
+    error?: string;
+}
+/**
+ * Flush a session's cache hot layer.
+ *
+ * Safe to call at any time. Long-term stores (SQLite facts, vectors, episodes,
+ * knowledge graph) are not touched. The next session bootstrap will re-warm
+ * from those stores naturally.
+ *
+ * @param cache   Connected CacheLayer instance
+ * @param agentId Agent identifier (e.g. "forge")
+ * @param sessionKey  Full session key (e.g. "agent:forge:webchat:scratchpad")
+ * @param opts    Optional flags
+ */
+export declare function flushSession(cache: CacheLayer, agentId: string, sessionKey: string, opts?: FlushSessionOptions): Promise<FlushSessionResult>;
+/**
+ * Convenience class for operator tooling that holds a bound agentId.
+ */
+export declare class SessionFlusher {
+    private readonly cache;
+    private readonly agentId;
+    constructor(cache: CacheLayer, agentId: string);
+    /**
+     * Flush the hot cache for a specific session.
+     */
+    flush(sessionKey: string, opts?: FlushSessionOptions): Promise<FlushSessionResult>;
+}
+//# sourceMappingURL=session-flusher.d.ts.map

package/dist/session-flusher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-flusher.d.ts","sourceRoot":"","sources":["../src/session-flusher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM;IAGlC;;OAEG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGzF"}

package/dist/session-flusher.js

@@ -0,0 +1,69 @@
+/**
+ * session-flusher.ts
+ *
+ * Provides a clean, operator-safe way to flush a session's hot cache from Redis
+ * without touching long-term memory (facts, vectors, episodes, knowledge graph).
+ *
+ * Used to implement the /fresh slash command — lets users start a new unwarmed
+ * session on demand without requiring a gateway restart.
+ *
+ * Long-term memory (facts, vectors, episodes) is intentionally preserved.
+ * It will re-warm naturally on the next session bootstrap.
+ */
+/**
+ * Flush a session's cache hot layer.
+ *
+ * Safe to call at any time. Long-term stores (SQLite facts, vectors, episodes,
+ * knowledge graph) are not touched. The next session bootstrap will re-warm
+ * from those stores naturally.
+ *
+ * @param cache   Connected CacheLayer instance
+ * @param agentId Agent identifier (e.g. "forge")
+ * @param sessionKey  Full session key (e.g. "agent:forge:webchat:scratchpad")
+ * @param opts    Optional flags
+ */
+export async function flushSession(cache, agentId, sessionKey, opts = {}) {
+    const cleared = [];
+    try {
+        // Core eviction — clears: system, identity, history, window, cursor,
+        // context, facts, tools, meta — and removes from active sessions set
+        await cache.evictSession(agentId, sessionKey);
+        cleared.push('system', 'identity', 'history', 'window', 'cursor', 'context', 'facts', 'tools', 'meta', 'active-sessions');
+        return {
+            success: true,
+            agentId,
+            sessionKey,
+            flushedAt: new Date().toISOString(),
+            cleared,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return {
+            success: false,
+            agentId,
+            sessionKey,
+            flushedAt: new Date().toISOString(),
+            cleared,
+            error,
+        };
+    }
+}
+/**
+ * Convenience class for operator tooling that holds a bound agentId.
+ */
+export class SessionFlusher {
+    cache;
+    agentId;
+    constructor(cache, agentId) {
+        this.cache = cache;
+        this.agentId = agentId;
+    }
+    /**
+     * Flush the hot cache for a specific session.
+     */
+    async flush(sessionKey, opts) {
+        return flushSession(this.cache, this.agentId, sessionKey, opts);
+    }
+}
+//# sourceMappingURL=session-flusher.js.map