instar 0.9.11 → 0.9.13

package/dist/core/CanonicalState.js

@@ -0,0 +1,297 @@
+/**
+ * Canonical State — Registry-first state management for agents.
+ *
+ * Inspired by Dawn's 223rd Lesson: "For ANY question about current state,
+ * check the canonical state file BEFORE dispatching broad searches."
+ *
+ * Three canonical registries every agent maintains:
+ *   1. quick-facts.json — Fast answers to common questions
+ *   2. anti-patterns.json — Things NOT to do (learned from mistakes)
+ *   3. project-registry.json — All projects this agent knows about
+ *
+ * These are the "one file designed to answer the question" pattern.
+ * Agents check these FIRST, then explore only if the answer isn't there.
+ *
+ * Born from the Luna incident (2026-02-25): The agent had no fast way
+ * to answer "what project is this topic for?" — it had to search broadly
+ * through config and session history, and got it wrong.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export class CanonicalState {
+    stateDir;
+    constructor(config) {
+        this.stateDir = config.stateDir;
+    }
+    // ── Quick Facts ─────────────────────────────────────────────────
+    /**
+     * Get all quick facts.
+     */
+    getQuickFacts() {
+        return this.loadJson('quick-facts.json', []);
+    }
+    /**
+     * Find a quick fact by searching question text.
+     */
+    findFact(query) {
+        const facts = this.getQuickFacts();
+        const lower = query.toLowerCase();
+        return facts.find(f => f.question.toLowerCase().includes(lower) ||
+            f.answer.toLowerCase().includes(lower)) ?? null;
+    }
+    /**
+     * Add or update a quick fact.
+     */
+    setFact(question, answer, source) {
+        const facts = this.getQuickFacts();
+        const existing = facts.findIndex(f => f.question === question);
+        const fact = {
+            question,
+            answer,
+            lastVerified: new Date().toISOString(),
+            source,
+        };
+        if (existing >= 0) {
+            facts[existing] = fact;
+        }
+        else {
+            facts.push(fact);
+        }
+        this.saveJson('quick-facts.json', facts);
+    }
+    /**
+     * Remove a quick fact by question text.
+     */
+    removeFact(question) {
+        const facts = this.getQuickFacts();
+        const filtered = facts.filter(f => f.question !== question);
+        if (filtered.length === facts.length)
+            return false;
+        this.saveJson('quick-facts.json', filtered);
+        return true;
+    }
+    // ── Anti-Patterns ───────────────────────────────────────────────
+    /**
+     * Get all anti-patterns.
+     */
+    getAntiPatterns() {
+        return this.loadJson('anti-patterns.json', []);
+    }
+    /**
+     * Add a new anti-pattern.
+     */
+    addAntiPattern(pattern) {
+        const patterns = this.getAntiPatterns();
+        const id = `AP-${String(patterns.length + 1).padStart(3, '0')}`;
+        const entry = {
+            ...pattern,
+            id,
+            learnedAt: new Date().toISOString(),
+        };
+        patterns.push(entry);
+        this.saveJson('anti-patterns.json', patterns);
+        return entry;
+    }
+    /**
+     * Search anti-patterns for relevant warnings.
+     */
+    findAntiPatterns(query) {
+        const patterns = this.getAntiPatterns();
+        const lower = query.toLowerCase();
+        return patterns.filter(p => p.pattern.toLowerCase().includes(lower) ||
+            p.consequence.toLowerCase().includes(lower) ||
+            p.alternative.toLowerCase().includes(lower));
+    }
+    // ── Project Registry ────────────────────────────────────────────
+    /**
+     * Get all registered projects.
+     */
+    getProjects() {
+        return this.loadJson('project-registry.json', []);
+    }
+    /**
+     * Find a project by name, directory, or topic ID.
+     */
+    findProject(query) {
+        const projects = this.getProjects();
+        if (query.topicId) {
+            const byTopic = projects.find(p => p.topicIds?.includes(query.topicId));
+            if (byTopic)
+                return byTopic;
+        }
+        if (query.name) {
+            const byName = projects.find(p => p.name.toLowerCase() === query.name.toLowerCase());
+            if (byName)
+                return byName;
+        }
+        if (query.dir) {
+            const byDir = projects.find(p => p.dir === query.dir);
+            if (byDir)
+                return byDir;
+        }
+        return null;
+    }
+    /**
+     * Register or update a project.
+     */
+    setProject(project) {
+        const projects = this.getProjects();
+        const existing = projects.findIndex(p => p.name === project.name);
+        const entry = {
+            ...project,
+            lastVerified: new Date().toISOString(),
+        };
+        if (existing >= 0) {
+            projects[existing] = entry;
+        }
+        else {
+            projects.push(entry);
+        }
+        this.saveJson('project-registry.json', projects);
+    }
+    /**
+     * Bind a topic ID to a project.
+     */
+    bindTopicToProject(topicId, projectName) {
+        const projects = this.getProjects();
+        const project = projects.find(p => p.name === projectName);
+        if (!project)
+            return false;
+        if (!project.topicIds)
+            project.topicIds = [];
+        if (!project.topicIds.includes(topicId)) {
+            project.topicIds.push(topicId);
+        }
+        this.saveJson('project-registry.json', projects);
+        return true;
+    }
+    // ── Initialization ──────────────────────────────────────────────
+    /**
+     * Initialize canonical state files with sensible defaults.
+     * Only creates files that don't exist (additive only).
+     */
+    initialize(projectName, projectDir) {
+        const created = [];
+        const skipped = [];
+        // Quick facts
+        if (!this.fileExists('quick-facts.json')) {
+            this.saveJson('quick-facts.json', [
+                {
+                    question: 'What project am I working on?',
+                    answer: `${projectName} at ${projectDir}`,
+                    lastVerified: new Date().toISOString(),
+                    source: 'instar init',
+                },
+            ]);
+            created.push('quick-facts.json');
+        }
+        else {
+            skipped.push('quick-facts.json');
+        }
+        // Anti-patterns
+        if (!this.fileExists('anti-patterns.json')) {
+            this.saveJson('anti-patterns.json', [
+                {
+                    id: 'AP-001',
+                    pattern: 'Deploying without verifying the target project matches the current topic',
+                    consequence: 'Deploy to wrong production environment (Luna incident)',
+                    alternative: 'Always run POST /coherence/check before deploying. Verify topic-project binding.',
+                    learnedAt: new Date().toISOString(),
+                    incident: 'Luna deployed SageMind code to Dental City topic',
+                },
+                {
+                    id: 'AP-002',
+                    pattern: 'Saying "I can\'t" without checking /capabilities first',
+                    consequence: 'Missed opportunity to use existing infrastructure',
+                    alternative: 'Check GET /capabilities before claiming any limitation.',
+                    learnedAt: new Date().toISOString(),
+                },
+                {
+                    id: 'AP-003',
+                    pattern: 'Presenting a menu of next steps instead of doing them',
+                    consequence: 'Forces user to project-manage the agent',
+                    alternative: 'Do the obvious next steps. Only ask when genuinely ambiguous.',
+                    learnedAt: new Date().toISOString(),
+                },
+            ]);
+            created.push('anti-patterns.json');
+        }
+        else {
+            skipped.push('anti-patterns.json');
+        }
+        // Project registry
+        if (!this.fileExists('project-registry.json')) {
+            this.saveJson('project-registry.json', [
+                {
+                    name: projectName,
+                    dir: projectDir,
+                    lastVerified: new Date().toISOString(),
+                    description: 'Primary project for this agent',
+                },
+            ]);
+            created.push('project-registry.json');
+        }
+        else {
+            skipped.push('project-registry.json');
+        }
+        return { created, skipped };
+    }
+    /**
+     * Generate a compact summary of canonical state for session injection.
+     */
+    getCompactSummary() {
+        const facts = this.getQuickFacts();
+        const patterns = this.getAntiPatterns();
+        const projects = this.getProjects();
+        const lines = [];
+        if (facts.length > 0) {
+            lines.push('Quick Facts:');
+            for (const f of facts.slice(0, 5)) {
+                lines.push(`  Q: ${f.question}`);
+                lines.push(`  A: ${f.answer}`);
+            }
+            if (facts.length > 5) {
+                lines.push(`  ... and ${facts.length - 5} more (GET /state/quick-facts)`);
+            }
+        }
+        if (patterns.length > 0) {
+            lines.push('');
+            lines.push('Anti-Patterns (things NOT to do):');
+            for (const p of patterns.slice(0, 3)) {
+                lines.push(`  - ${p.pattern}`);
+            }
+            if (patterns.length > 3) {
+                lines.push(`  ... and ${patterns.length - 3} more (GET /state/anti-patterns)`);
+            }
+        }
+        if (projects.length > 1) {
+            lines.push('');
+            lines.push('Known Projects:');
+            for (const p of projects) {
+                const topics = p.topicIds?.length ? ` (topics: ${p.topicIds.join(', ')})` : '';
+                lines.push(`  - ${p.name}: ${p.dir}${topics}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    // ── Helpers ─────────────────────────────────────────────────────
+    loadJson(filename, defaultValue) {
+        const filePath = path.join(this.stateDir, filename);
+        try {
+            if (fs.existsSync(filePath)) {
+                return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            }
+        }
+        catch { /* corrupt file */ }
+        return defaultValue;
+    }
+    saveJson(filename, data) {
+        const filePath = path.join(this.stateDir, filename);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+    }
+    fileExists(filename) {
+        return fs.existsSync(path.join(this.stateDir, filename));
+    }
+}
+//# sourceMappingURL=CanonicalState.js.map

package/dist/core/CanonicalState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CanonicalState.js","sourceRoot":"","sources":["../../src/core/CanonicalState.ts"],"names":[],"mappings":"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"}

package/dist/core/CoherenceGate.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Coherence Gate — Pre-action verification for agent coherence.
+ *
+ * Before high-risk actions (deployment, git push, external API calls),
+ * the agent pauses to verify: "Am I in the right project? Does this
+ * action match my identity and mission?"
+ *
+ * Born from the Luna incident (2026-02-25): An agent deployed to the
+ * wrong production target because nothing validated that the intended
+ * action matched the agent's current context.
+ *
+ * Design principle: Not a dumb pattern match — an intelligent
+ * self-verification that gives the agent the ability to step back,
+ * review what it's doing, and catch incoherence before it manifests.
+ *
+ * Three verification levels:
+ * 1. Structural — git remote, working directory, project name match
+ * 2. Contextual — action aligns with current topic/conversation scope
+ * 3. Intent — action aligns with stated mission/boundaries in AGENT.md
+ */
+export interface CoherenceCheckResult {
+    /** Whether the action passed all coherence checks */
+    passed: boolean;
+    /** Individual check results */
+    checks: CoherenceCheck[];
+    /** Human-readable summary */
+    summary: string;
+    /** Recommended action: proceed, warn, or block */
+    recommendation: 'proceed' | 'warn' | 'block';
+    /** Timestamp */
+    checkedAt: string;
+}
+export interface CoherenceCheck {
+    /** Check name */
+    name: string;
+    /** Whether this check passed */
+    passed: boolean;
+    /** What was expected */
+    expected: string;
+    /** What was found */
+    actual: string;
+    /** Severity if failed: error blocks, warning alerts */
+    severity: 'error' | 'warning' | 'info';
+    /** Human-readable message */
+    message: string;
+}
+export interface CoherenceGateConfig {
+    /** Project root directory */
+    projectDir: string;
+    /** Instar state directory */
+    stateDir: string;
+    /** Expected project name (from config) */
+    projectName: string;
+    /** Expected git remote (if known) */
+    expectedGitRemote?: string;
+    /** Topic-project bindings */
+    topicProjects?: Record<string, TopicProjectBinding>;
+}
+export interface TopicProjectBinding {
+    /** Human-readable project name */
+    projectName: string;
+    /** Path to the project directory */
+    projectDir: string;
+    /** Expected git remote URL */
+    gitRemote?: string;
+    /** Deployment target URLs */
+    deploymentTargets?: string[];
+    /** Description of this project */
+    description?: string;
+}
+/** Actions that trigger coherence checking */
+export type HighRiskAction = 'deploy' | 'git-push' | 'external-api' | 'file-modify-outside-project' | 'production-change';
+export declare class CoherenceGate {
+    private config;
+    constructor(config: CoherenceGateConfig);
+    /**
+     * Run a full coherence check for a proposed action.
+     */
+    check(action: HighRiskAction, context?: {
+        targetUrl?: string;
+        targetPath?: string;
+        topicId?: number;
+        description?: string;
+    }): CoherenceCheckResult;
+    /**
+     * Generate a self-verification prompt for the agent to reflect before acting.
+     * This is the "step back and review" mechanism.
+     */
+    generateReflectionPrompt(action: HighRiskAction, context?: {
+        targetUrl?: string;
+        targetPath?: string;
+        topicId?: number;
+        topicName?: string;
+        description?: string;
+    }): string;
+    /**
+     * Get the topic-project binding for a specific topic.
+     */
+    getTopicBinding(topicId: number): TopicProjectBinding | null;
+    /**
+     * Register a topic-to-project binding.
+     */
+    setTopicBinding(topicId: number, binding: TopicProjectBinding): void;
+    /**
+     * Load topic-project bindings from disk.
+     */
+    loadTopicBindings(): Record<string, TopicProjectBinding>;
+    /**
+     * Save topic-project bindings to disk.
+     */
+    private saveTopicBindings;
+    private checkWorkingDirectory;
+    private checkGitRemote;
+    private checkTopicProjectAlignment;
+    private checkDeploymentTarget;
+    private checkPathScope;
+    private checkAgentIdentity;
+    private detectGitRemote;
+    private normalizeGitUrl;
+    private normalizePath;
+}
+//# sourceMappingURL=CoherenceGate.d.ts.map

package/dist/core/CoherenceGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoherenceGate.d.ts","sourceRoot":"","sources":["../../src/core/CoherenceGate.ts"],"names":[],"mappings":"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"}