@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/BitwardenProvider.js

@@ -0,0 +1,437 @@
+/**
+ * Bitwarden CLI integration for secret management.
+ *
+ * Wraps the `bw` CLI to provide scoped secret storage per agent.
+ * Secrets are stored as Bitwarden Secure Notes in a folder per agent.
+ *
+ * Folder structure in Bitwarden:
+ *   instar/
+ *     {agentName}/
+ *       telegram-token
+ *       telegram-chat-id
+ *       auth-token
+ *       dashboard-pin
+ *       tunnel-token
+ *
+ * The session key is cached in memory and refreshed as needed.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+// ── Constants ────────────────────────────────────────────────────────
+const BW_TIMEOUT = 15000; // 15 second timeout for CLI calls
+const FOLDER_PREFIX = 'instar';
+// ── Provider ─────────────────────────────────────────────────────────
+export class BitwardenProvider {
+    agentName;
+    sessionKey = null;
+    bwPath = null;
+    bwPathOverridden = false;
+    constructor(config) {
+        this.agentName = config.agentName;
+        if (config.bwPath !== undefined) {
+            this.bwPath = config.bwPath;
+            this.bwPathOverridden = true;
+        }
+    }
+    // ── Status ────────────────────────────────────────────────────────
+    /** Check Bitwarden CLI status. */
+    getStatus() {
+        const bw = this.findBw();
+        if (!bw) {
+            return { installed: false, loggedIn: false, unlocked: false };
+        }
+        try {
+            const output = execFileSync(bw, ['status', '--raw'], {
+                encoding: 'utf-8',
+                timeout: BW_TIMEOUT,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            const status = JSON.parse(output);
+            return {
+                installed: true,
+                loggedIn: status.status !== 'unauthenticated',
+                unlocked: status.status === 'unlocked',
+                email: status.userEmail || undefined,
+            };
+        }
+        catch {
+            return { installed: true, loggedIn: false, unlocked: false };
+        }
+    }
+    /** Whether Bitwarden is ready to use (installed, logged in, unlocked). */
+    isReady() {
+        const status = this.getStatus();
+        return status.installed && status.loggedIn && status.unlocked;
+    }
+    // ── Session Management ────────────────────────────────────────────
+    /**
+     * Unlock the vault with a master password.
+     * Returns true if successful.
+     */
+    unlock(masterPassword) {
+        const bw = this.requireBw();
+        try {
+            // First check if already unlocked
+            const status = this.getStatus();
+            if (status.unlocked) {
+                // Get existing session key
+                this.sessionKey = this.getExistingSession();
+                return this.sessionKey !== null;
+            }
+            // Unlock with password
+            const session = execFileSync(bw, ['unlock', masterPassword, '--raw'], {
+                encoding: 'utf-8',
+                timeout: BW_TIMEOUT,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            this.sessionKey = session;
+            return true;
+        }
+        catch {
+            // @silent-fallback-ok — vault locked or key not found — caller handles missing secret
+            return false;
+        }
+    }
+    /**
+     * Log in with email and master password.
+     * Returns true if successful.
+     */
+    login(email, masterPassword) {
+        const bw = this.requireBw();
+        try {
+            const session = execFileSync(bw, ['login', email, masterPassword, '--raw'], {
+                encoding: 'utf-8',
+                timeout: 30000, // Login can be slower
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            this.sessionKey = session;
+            return true;
+        }
+        catch {
+            // @silent-fallback-ok — vault locked or key not found — caller handles missing secret
+            return false;
+        }
+    }
+    // ── Secret Operations ─────────────────────────────────────────────
+    /**
+     * Get a secret by key name.
+     * Returns null if not found.
+     */
+    get(key) {
+        const bw = this.requireBw();
+        const session = this.requireSession();
+        const itemName = this.scopedName(key);
+        try {
+            const output = execFileSync(bw, [
+                'list', 'items',
+                '--search', itemName,
+                '--session', session,
+                '--raw',
+            ], {
+                encoding: 'utf-8',
+                timeout: BW_TIMEOUT,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            const items = JSON.parse(output);
+            // Find exact match in the correct folder
+            const folderId = this.getOrCreateFolderId();
+            const match = items.find((item) => item.name === itemName && item.folderId === folderId);
+            if (!match)
+                return null;
+            // Secure notes store value in notes field
+            if (match.type === 2 && match.notes) {
+                return match.notes;
+            }
+            // Login items store in password field
+            if (match.type === 1 && match.login?.password) {
+                return match.login.password;
+            }
+            return null;
+        }
+        catch {
+            // @silent-fallback-ok — vault locked or key not found — caller handles missing secret
+            return null;
+        }
+    }
+    /**
+     * Set a secret by key name.
+     * Creates or updates the item in Bitwarden.
+     */
+    set(key, value) {
+        const bw = this.requireBw();
+        const session = this.requireSession();
+        const itemName = this.scopedName(key);
+        const folderId = this.getOrCreateFolderId();
+        try {
+            // Check if item already exists
+            const existingId = this.findItemId(itemName, folderId);
+            if (existingId) {
+                // Update existing item
+                const existingJson = execFileSync(bw, [
+                    'get', 'item', existingId,
+                    '--session', session,
+                    '--raw',
+                ], {
+                    encoding: 'utf-8',
+                    timeout: BW_TIMEOUT,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                }).trim();
+                const existing = JSON.parse(existingJson);
+                existing.notes = value;
+                const encoded = Buffer.from(JSON.stringify(existing)).toString('base64');
+                execFileSync(bw, [
+                    'edit', 'item', existingId,
+                    encoded,
+                    '--session', session,
+                ], {
+                    encoding: 'utf-8',
+                    timeout: BW_TIMEOUT,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+            }
+            else {
+                // Create new secure note
+                const item = {
+                    type: 2, // Secure note
+                    name: itemName,
+                    notes: value,
+                    folderId,
+                    secureNote: { type: 0 },
+                };
+                const encoded = Buffer.from(JSON.stringify(item)).toString('base64');
+                execFileSync(bw, [
+                    'create', 'item',
+                    encoded,
+                    '--session', session,
+                ], {
+                    encoding: 'utf-8',
+                    timeout: BW_TIMEOUT,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+            }
+            return true;
+        }
+        catch {
+            // @silent-fallback-ok — vault locked or key not found — caller handles missing secret
+            return false;
+        }
+    }
+    /**
+     * Check if a secret exists.
+     */
+    has(key) {
+        return this.get(key) !== null;
+    }
+    /**
+     * Delete a secret by key name.
+     */
+    delete(key) {
+        const bw = this.requireBw();
+        const session = this.requireSession();
+        const itemName = this.scopedName(key);
+        const folderId = this.getOrCreateFolderId();
+        try {
+            const itemId = this.findItemId(itemName, folderId);
+            if (!itemId)
+                return false;
+            execFileSync(bw, [
+                'delete', 'item', itemId,
+                '--session', session,
+            ], {
+                encoding: 'utf-8',
+                timeout: BW_TIMEOUT,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return true;
+        }
+        catch {
+            // @silent-fallback-ok — vault locked or key not found — caller handles missing secret
+            return false;
+        }
+    }
+    /**
+     * List all secrets for this agent.
+     * Returns key-value pairs.
+     */
+    listAll() {
+        const bw = this.requireBw();
+        const session = this.requireSession();
+        const folderId = this.getOrCreateFolderId();
+        try {
+            const output = execFileSync(bw, [
+                'list', 'items',
+                '--folderid', folderId,
+                '--session', session,
+                '--raw',
+            ], {
+                encoding: 'utf-8',
+                timeout: BW_TIMEOUT,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            const items = JSON.parse(output);
+            const result = {};
+            const prefix = this.scopedName('');
+            for (const item of items) {
+                if (item.name.startsWith(prefix)) {
+                    const key = item.name.substring(prefix.length);
+                    if (item.type === 2 && item.notes) {
+                        result[key] = item.notes;
+                    }
+                }
+            }
+            return result;
+        }
+        catch {
+            // @silent-fallback-ok — vault locked or key not found — caller handles missing secret
+            return {};
+        }
+    }
+    // ── Folder Management ─────────────────────────────────────────────
+    getOrCreateFolderId() {
+        const bw = this.requireBw();
+        const session = this.requireSession();
+        const folderName = `${FOLDER_PREFIX}/${this.agentName}`;
+        try {
+            // List existing folders
+            const output = execFileSync(bw, [
+                'list', 'folders',
+                '--session', session,
+                '--raw',
+            ], {
+                encoding: 'utf-8',
+                timeout: BW_TIMEOUT,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            const folders = JSON.parse(output);
+            const existing = folders.find((f) => f.name === folderName);
+            if (existing)
+                return existing.id;
+            // Create the folder
+            const folderData = { name: folderName };
+            const encoded = Buffer.from(JSON.stringify(folderData)).toString('base64');
+            const created = execFileSync(bw, [
+                'create', 'folder',
+                encoded,
+                '--session', session,
+                '--raw',
+            ], {
+                encoding: 'utf-8',
+                timeout: BW_TIMEOUT,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            const result = JSON.parse(created);
+            return result.id;
+        }
+        catch (err) {
+            throw new Error(`Failed to get/create Bitwarden folder: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // ── Helpers ───────────────────────────────────────────────────────
+    scopedName(key) {
+        return key ? `${FOLDER_PREFIX}-${this.agentName}-${key}` : `${FOLDER_PREFIX}-${this.agentName}-`;
+    }
+    findItemId(itemName, folderId) {
+        const bw = this.requireBw();
+        const session = this.requireSession();
+        try {
+            const output = execFileSync(bw, [
+                'list', 'items',
+                '--search', itemName,
+                '--session', session,
+                '--raw',
+            ], {
+                encoding: 'utf-8',
+                timeout: BW_TIMEOUT,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            const items = JSON.parse(output);
+            const match = items.find((item) => item.name === itemName && item.folderId === folderId);
+            return match?.id || null;
+        }
+        catch {
+            // @silent-fallback-ok — vault locked or key not found — caller handles missing secret
+            return null;
+        }
+    }
+    findBw() {
+        // If path was explicitly set via config, use it directly (even if null)
+        if (this.bwPathOverridden)
+            return this.bwPath;
+        // Cached from previous detection
+        if (this.bwPath)
+            return this.bwPath;
+        const candidates = [
+            '/opt/homebrew/bin/bw',
+            '/usr/local/bin/bw',
+            '/usr/bin/bw',
+        ];
+        for (const candidate of candidates) {
+            if (fs.existsSync(candidate)) {
+                this.bwPath = candidate;
+                return candidate;
+            }
+        }
+        // Check PATH
+        try {
+            const result = execFileSync('which', ['bw'], {
+                encoding: 'utf-8',
+                timeout: 5000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+            if (result && fs.existsSync(result)) {
+                this.bwPath = result;
+                return result;
+            }
+        }
+        catch {
+            // Not in PATH
+        }
+        return null;
+    }
+    requireBw() {
+        const bw = this.findBw();
+        if (!bw) {
+            throw new Error('Bitwarden CLI (bw) not found. Install with:\n' +
+                '  brew install bitwarden-cli   (macOS)\n' +
+                '  npm install -g @bitwarden/cli (any platform)\n' +
+                '  snap install bw              (Linux)');
+        }
+        return bw;
+    }
+    requireSession() {
+        if (this.sessionKey)
+            return this.sessionKey;
+        // Try to get session from environment
+        const envSession = process.env.BW_SESSION;
+        if (envSession) {
+            this.sessionKey = envSession;
+            return envSession;
+        }
+        // Try to check if vault is already unlocked (some bw setups auto-persist session)
+        const existing = this.getExistingSession();
+        if (existing) {
+            this.sessionKey = existing;
+            return existing;
+        }
+        throw new Error('Bitwarden vault is locked. Call unlock(password) first or set BW_SESSION env var.');
+    }
+    getExistingSession() {
+        const bw = this.findBw();
+        if (!bw)
+            return null;
+        try {
+            // Try listing with no session — works if vault was unlocked externally
+            execFileSync(bw, ['list', 'folders', '--raw'], {
+                encoding: 'utf-8',
+                timeout: BW_TIMEOUT,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            return ''; // Empty string = session not needed (already unlocked)
+        }
+        catch {
+            // @silent-fallback-ok — vault locked or key not found — caller handles missing secret
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=BitwardenProvider.js.map

package/dist/core/BitwardenProvider.js.map

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

package/dist/core/BlockerLearningLoop.d.ts

@@ -0,0 +1,99 @@
+/**
+ * BlockerLearningLoop — Captures and promotes blocker resolutions.
+ *
+ * Part of PROP-232 Autonomy Guard (Phase 3: Learning Loop).
+ *
+ * When a blocker is resolved during a job session, this class:
+ * 1. Eagerly captures the resolution to the pending queue (crash safety)
+ * 2. Tracks reuse success across sessions
+ * 3. Promotes resolutions after N successful reuses (N-confirmation)
+ * 4. Prunes expired or low-success entries
+ *
+ * Promotion thresholds:
+ * - `resolvedBy: 'human'` → promote immediately to confirmed
+ * - `resolvedBy: 'research-agent'` → require 2 successful reuses
+ * - `resolvedBy: 'agent'` → require 3 successful reuses
+ *
+ * Storage: Updates commonBlockers in the job's definition file (jobs.json).
+ */
+import type { CommonBlocker } from './types.js';
+export interface BlockerResolution {
+    /** Job slug this resolution applies to */
+    jobSlug: string;
+    /** Machine-friendly key for this blocker pattern */
+    blockerKey: string;
+    /** Human-readable description of the blocker */
+    description: string;
+    /** How the blocker was resolved */
+    resolution: string;
+    /** Tools used in the resolution */
+    toolsUsed: string[];
+    /** Who resolved it */
+    resolvedBy: 'agent' | 'research-agent' | 'human';
+    /** Session ID where the resolution was discovered */
+    resolvedInSession: string;
+    /** ISO timestamp of resolution */
+    resolvedAt: string;
+    /** Credentials used (if any) */
+    credentials?: string | string[];
+}
+export interface LearningLoopConfig {
+    /** Path to .instar state directory */
+    stateDir: string;
+    /** Path to jobs.json file */
+    jobsFile: string;
+    /** Promotion thresholds by resolver type */
+    promotionThresholds?: Record<string, number>;
+    /** Days before an unused resolution expires. Default: 90 */
+    expirationDays?: number;
+    /** Days before a low-success pending resolution is pruned. Default: 30 */
+    pendingPruneDays?: number;
+    /** Max entries per job. Default: 20 */
+    maxEntriesPerJob?: number;
+}
+export interface ReuseSummary {
+    /** Key of the reused blocker */
+    blockerKey: string;
+    /** New success count */
+    successCount: number;
+    /** Whether this reuse triggered promotion */
+    promoted: boolean;
+}
+export declare class BlockerLearningLoop {
+    private config;
+    private thresholds;
+    private expirationMs;
+    private pendingPruneMs;
+    private maxEntries;
+    constructor(config: LearningLoopConfig);
+    /**
+     * Capture a blocker resolution eagerly (at resolution time, not session-end).
+     * Writes to the pending queue in the job's commonBlockers.
+     *
+     * Returns the blocker key used for tracking.
+     */
+    capture(resolution: BlockerResolution): string;
+    /**
+     * Record a successful reuse of a blocker resolution.
+     * Increments successCount and promotes if threshold met.
+     *
+     * Returns a summary of what happened.
+     */
+    recordReuse(jobSlug: string, blockerKey: string, resolvedBy?: string): ReuseSummary | null;
+    /**
+     * Prune expired and low-success entries for a job.
+     * - Confirmed entries expire after expirationDays of no use
+     * - Pending entries prune after pendingPruneDays of no use
+     * - Over-limit: remove lowest-success entries first
+     *
+     * Returns the number of entries pruned.
+     */
+    prune(jobSlug: string): number;
+    /**
+     * Get all blockers for a job (for inspection/debugging).
+     */
+    getBlockers(jobSlug: string): Record<string, CommonBlocker> | null;
+    private loadJobs;
+    private saveJobs;
+}
+//# sourceMappingURL=BlockerLearningLoop.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BlockerLearningLoop.d.ts","sourceRoot":"","sources":["../../src/core/BlockerLearningLoop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAM/D,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,sBAAsB;IACtB,UAAU,EAAE,OAAO,GAAG,gBAAgB,GAAG,OAAO,CAAC;IACjD,qDAAqD;IACrD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,QAAQ,EAAE,OAAO,CAAC;CACnB;AAgBD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,kBAAkB;IAQtC;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM;IA8C9C;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IA+B1F;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAkE9B;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,IAAI;IAUlE,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,QAAQ;CAGjB"}