@iflow-mcp/jkheadley-instar 0.26.2

package/dist/core/UpgradeNotifyManager.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Upgrade Notify Manager — reliable delivery of upgrade guides to agents.
+ *
+ * After an update, a short Claude session is spawned to:
+ *   1. Notify the user via Telegram
+ *   2. Update MEMORY.md with new capabilities
+ *   3. Acknowledge the guide (instar upgrade-ack)
+ *
+ * This module owns the verification and retry logic:
+ *   - After the session completes, check if the pending guide was cleared
+ *   - If not, retry with a more capable model (haiku → sonnet)
+ *   - Log success/failure for observability
+ *
+ * Born from the observation that fire-and-forget Haiku sessions silently
+ * fail ~30% of the time on multi-step tasks. Verification closes the loop.
+ */
+import type { ModelTier, Session } from './types.js';
+export interface UpgradeNotifyConfig {
+    /** Path to pending-upgrade-guide.md */
+    pendingGuidePath: string;
+    /** Project directory */
+    projectDir: string;
+    /** .instar state directory */
+    stateDir: string;
+    /** Server port */
+    port: number;
+    /** Dashboard PIN (if set) */
+    dashboardPin: string;
+    /** Tunnel URL (if available) */
+    tunnelUrl: string;
+    /** Current installed version */
+    currentVersion: string;
+    /** Telegram reply script path (empty if not found) */
+    replyScript: string;
+    /** Telegram topic ID for upgrade notifications */
+    notifyTopicId: number;
+}
+export interface UpgradeNotifyResult {
+    /** Whether the upgrade guide was successfully acknowledged */
+    success: boolean;
+    /** Model used for the successful attempt (or last attempted) */
+    model: ModelTier;
+    /** Number of attempts made */
+    attempts: number;
+    /** Error message if failed */
+    error?: string;
+}
+/** Callback to spawn a Claude session — injected for testability */
+export type SessionSpawner = (options: {
+    name: string;
+    prompt: string;
+    model: ModelTier;
+    jobSlug: string;
+    maxDurationMinutes: number;
+}) => Promise<Session>;
+/** Callback to check if a session has completed */
+export type SessionCompletionChecker = (sessionId: string) => boolean;
+/** Callback to log activity events */
+export type ActivityLogger = (event: {
+    type: string;
+    summary: string;
+    metadata?: Record<string, unknown>;
+}) => void;
+export interface UpgradeNotifyTiming {
+    sessionTimeoutMs?: number;
+    pollIntervalMs?: number;
+    postCompletionDelayMs?: number;
+}
+export declare class UpgradeNotifyManager {
+    private config;
+    private spawnSession;
+    private isSessionComplete;
+    private logActivity;
+    private timing;
+    constructor(config: UpgradeNotifyConfig, spawnSession: SessionSpawner, isSessionComplete: SessionCompletionChecker, logActivity: ActivityLogger, timing?: UpgradeNotifyTiming);
+    /**
+     * Run the upgrade notification with verification and retry.
+     * Returns the result of the notification attempt.
+     */
+    notify(): Promise<UpgradeNotifyResult>;
+    /**
+     * Build the upgrade-notify prompt with all context.
+     */
+    buildPrompt(guideContent: string): string;
+    /**
+     * Check if the pending guide has been acknowledged (file removed by upgrade-ack).
+     */
+    isAcknowledged(): boolean;
+    /**
+     * Read the pending upgrade guide content. Returns null if no guide exists.
+     */
+    private readPendingGuide;
+    /**
+     * Poll until the session completes or times out.
+     */
+    private waitForCompletion;
+}
+//# sourceMappingURL=UpgradeNotifyManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UpgradeNotifyManager.d.ts","sourceRoot":"","sources":["../../src/core/UpgradeNotifyManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,SAAS,CAAC;IACjB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,oEAAoE;AACpE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,mDAAmD;AACnD,MAAM,MAAM,wBAAwB,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;AAEtE,sCAAsC;AACtC,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,KAAK,IAAI,CAAC;AAUX,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,iBAAiB,CAA2B;IACpD,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,MAAM,CAAgC;gBAG5C,MAAM,EAAE,mBAAmB,EAC3B,YAAY,EAAE,cAAc,EAC5B,iBAAiB,EAAE,wBAAwB,EAC3C,WAAW,EAAE,cAAc,EAC3B,MAAM,CAAC,EAAE,mBAAmB;IAa9B;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAuE5C;;OAEG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAgEzC;;OAEG;IACH,cAAc,IAAI,OAAO;IAIzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;YACW,iBAAiB;CAYhC"}

package/dist/core/UpgradeNotifyManager.js

@@ -0,0 +1,205 @@
+/**
+ * Upgrade Notify Manager — reliable delivery of upgrade guides to agents.
+ *
+ * After an update, a short Claude session is spawned to:
+ *   1. Notify the user via Telegram
+ *   2. Update MEMORY.md with new capabilities
+ *   3. Acknowledge the guide (instar upgrade-ack)
+ *
+ * This module owns the verification and retry logic:
+ *   - After the session completes, check if the pending guide was cleared
+ *   - If not, retry with a more capable model (haiku → sonnet)
+ *   - Log success/failure for observability
+ *
+ * Born from the observation that fire-and-forget Haiku sessions silently
+ * fail ~30% of the time on multi-step tasks. Verification closes the loop.
+ */
+import fs from 'node:fs';
+/** Model escalation chain — try faster models first, escalate on failure */
+const MODEL_CHAIN = ['haiku', 'sonnet'];
+/** Default timing constants (overridable via UpgradeNotifyTiming for testing) */
+const DEFAULT_SESSION_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_POLL_INTERVAL_MS = 10_000; // 10 seconds
+const DEFAULT_POST_COMPLETION_DELAY_MS = 5_000; // 5 seconds
+export class UpgradeNotifyManager {
+    config;
+    spawnSession;
+    isSessionComplete;
+    logActivity;
+    timing;
+    constructor(config, spawnSession, isSessionComplete, logActivity, timing) {
+        this.config = config;
+        this.spawnSession = spawnSession;
+        this.isSessionComplete = isSessionComplete;
+        this.logActivity = logActivity;
+        this.timing = {
+            sessionTimeoutMs: timing?.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS,
+            pollIntervalMs: timing?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+            postCompletionDelayMs: timing?.postCompletionDelayMs ?? DEFAULT_POST_COMPLETION_DELAY_MS,
+        };
+    }
+    /**
+     * Run the upgrade notification with verification and retry.
+     * Returns the result of the notification attempt.
+     */
+    async notify() {
+        const guideContent = this.readPendingGuide();
+        if (!guideContent) {
+            return { success: true, model: 'haiku', attempts: 0 }; // Nothing to do
+        }
+        let lastError;
+        for (let i = 0; i < MODEL_CHAIN.length; i++) {
+            const model = MODEL_CHAIN[i];
+            const attempt = i + 1;
+            console.log(`[UpgradeNotify] Attempt ${attempt}/${MODEL_CHAIN.length} with ${model}...`);
+            try {
+                const prompt = this.buildPrompt(guideContent);
+                const session = await this.spawnSession({
+                    name: 'upgrade-notify',
+                    prompt,
+                    model,
+                    jobSlug: 'upgrade-notify',
+                    maxDurationMinutes: 5,
+                });
+                // Wait for session to complete
+                const completed = await this.waitForCompletion(session.id);
+                if (!completed) {
+                    lastError = `Session timed out after ${this.timing.sessionTimeoutMs / 1000}s`;
+                    console.warn(`[UpgradeNotify] ${lastError} (${model})`);
+                    continue;
+                }
+                // Brief delay for filesystem sync
+                await new Promise(r => setTimeout(r, this.timing.postCompletionDelayMs));
+                // Check if the pending guide was acknowledged
+                if (this.isAcknowledged()) {
+                    console.log(`[UpgradeNotify] Success — guide acknowledged on attempt ${attempt} (${model})`);
+                    this.logActivity({
+                        type: 'upgrade_notify_success',
+                        summary: `Upgrade guide delivered and acknowledged (${model}, attempt ${attempt})`,
+                        metadata: { model, attempt },
+                    });
+                    return { success: true, model, attempts: attempt };
+                }
+                lastError = `Session completed but guide was not acknowledged`;
+                console.warn(`[UpgradeNotify] ${lastError} (${model}) — ${i < MODEL_CHAIN.length - 1 ? 'escalating model' : 'no more retries'}`);
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err.message : String(err);
+                console.error(`[UpgradeNotify] Spawn failed (${model}): ${lastError}`);
+            }
+        }
+        // All attempts exhausted
+        console.error(`[UpgradeNotify] All ${MODEL_CHAIN.length} attempts failed. Pending guide preserved for next session-start.`);
+        this.logActivity({
+            type: 'upgrade_notify_failed',
+            summary: `Upgrade guide notification failed after ${MODEL_CHAIN.length} attempts: ${lastError}`,
+            metadata: { attempts: MODEL_CHAIN.length, lastError },
+        });
+        return {
+            success: false,
+            model: MODEL_CHAIN[MODEL_CHAIN.length - 1],
+            attempts: MODEL_CHAIN.length,
+            error: lastError,
+        };
+    }
+    /**
+     * Build the upgrade-notify prompt with all context.
+     */
+    buildPrompt(guideContent) {
+        const { dashboardPin, currentVersion, replyScript, notifyTopicId } = this.config;
+        const dashboardUrl = this.config.tunnelUrl
+            ? `${this.config.tunnelUrl}/dashboard`
+            : `http://localhost:${this.config.port}/dashboard`;
+        const hasReplyScript = !!replyScript;
+        return [
+            'IMPORTANT: You are a SHORT-LIVED session with a SPECIFIC task. Do NOT search for files or explore the codebase. Everything you need is in this prompt.',
+            '',
+            'You have been updated to a new Instar version. Read the upgrade guide below, then do ALL THREE steps.',
+            'IMPORTANT: The guide below contains ONLY what is new in THIS update. Do not mention features from previous updates.',
+            '',
+            '',
+            '## Step 1: Notify your user',
+            '',
+            'Compose a brief, personalized message (3-8 sentences) for your user about the new features.',
+            '   RULES:',
+            '   - Write like you\'re texting a friend — warm, conversational, no jargon',
+            '   - This should NOT look like a changelog or release notes',
+            '   - Lead with the biggest USER-VISIBLE feature',
+            '   - Include CONCRETE details — actual URLs, PINs, things they can click/use right now',
+            '   - NEVER mention "bearer tokens", "auth tokens", version numbers in headers, or internal implementation details',
+            '   - Focus on what matters to THEM, not internal plumbing',
+            '   - NO bullet lists, NO markdown headers, NO technical formatting — just natural sentences',
+            '',
+            '   CONCRETE DETAILS TO INCLUDE:',
+            `   - Dashboard URL: ${dashboardUrl}`,
+            dashboardPin ? `   - Dashboard PIN: ${dashboardPin}` : '   - No dashboard PIN set',
+            `   - Current version: ${currentVersion}`,
+            '',
+            'Send the message via Telegram:',
+            hasReplyScript && notifyTopicId
+                ? `   Run: cat <<'MSGEOF' | bash ${replyScript} ${notifyTopicId}\nYOUR_MESSAGE_HERE\nMSGEOF`
+                : '   Use the telegram-reply script in .instar/scripts/ to send to the updates topic.',
+            '',
+            '## Step 2: Update your memory with new capabilities',
+            '',
+            'Read the upgrade guide\'s "Summary of New Capabilities" section and add the relevant information to your MEMORY.md file (.instar/MEMORY.md).',
+            'This ensures you KNOW about these capabilities in every future session — not just this one.',
+            '',
+            'Add a section like:',
+            '```',
+            '## Capabilities Added in vX.Y.Z',
+            '- Brief description of each capability',
+            '- How to use it (API endpoints, commands, automatic behaviors)',
+            '- Any behavioral changes you should be aware of',
+            '```',
+            '',
+            'Keep it concise — focus on WHAT you can now do and HOW to do it, not the implementation details.',
+            'If there are existing capability notes in MEMORY.md, update or merge rather than duplicate.',
+            '',
+            '## Step 3: Acknowledge',
+            '',
+            'Run: instar upgrade-ack',
+            '',
+            'Do all three steps, then exit. Do not search for files or read config files beyond MEMORY.md.',
+            '',
+            '--- UPGRADE GUIDE ---',
+            guideContent,
+            '--- END GUIDE ---',
+        ].join('\n');
+    }
+    /**
+     * Check if the pending guide has been acknowledged (file removed by upgrade-ack).
+     */
+    isAcknowledged() {
+        return !fs.existsSync(this.config.pendingGuidePath);
+    }
+    /**
+     * Read the pending upgrade guide content. Returns null if no guide exists.
+     */
+    readPendingGuide() {
+        try {
+            if (!fs.existsSync(this.config.pendingGuidePath))
+                return null;
+            const content = fs.readFileSync(this.config.pendingGuidePath, 'utf-8');
+            return content.trim() || null;
+        }
+        catch {
+            // @silent-fallback-ok — pending guide returns null
+            return null;
+        }
+    }
+    /**
+     * Poll until the session completes or times out.
+     */
+    async waitForCompletion(sessionId) {
+        const deadline = Date.now() + this.timing.sessionTimeoutMs;
+        while (Date.now() < deadline) {
+            if (this.isSessionComplete(sessionId)) {
+                return true;
+            }
+            await new Promise(r => setTimeout(r, this.timing.pollIntervalMs));
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=UpgradeNotifyManager.js.map

package/dist/core/UpgradeNotifyManager.js.map

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

package/dist/core/WorkLedger.d.ts

@@ -0,0 +1,144 @@
+/**
+ * WorkLedger — Per-machine work tracking for inter-agent awareness.
+ *
+ * Each machine writes only its own ledger file. The aggregate view is
+ * computed by reading all files in the ledger directory. This eliminates
+ * write contention entirely — conflicts on ledger files are structurally
+ * impossible in single-user scenarios.
+ *
+ * From INTELLIGENT_SYNC_SPEC Section 6 (The Work Ledger) and Section 8
+ * (Conflict Prevention Through Awareness).
+ */
+export type LedgerEntryStatus = 'active' | 'paused' | 'completed' | 'stale';
+export interface LedgerEntry {
+    /** Unique entry ID (work_<random>). */
+    id: string;
+    /** Machine that owns this entry. */
+    machineId: string;
+    /** User ID (for multi-user scenarios). */
+    userId?: string;
+    /** Session ID (e.g., AUT-150). */
+    sessionId: string;
+    /** When the work started. */
+    startedAt: string;
+    /** Last update timestamp. */
+    updatedAt: string;
+    /** Current status. */
+    status: LedgerEntryStatus;
+    /** Human-readable task description. */
+    task: string;
+    /** Files the agent plans to modify. */
+    filesPlanned: string[];
+    /** Files actually modified so far. */
+    filesModified: string[];
+    /** Branch name (if working on a task branch). */
+    branch?: string;
+    /** Estimated completion time. */
+    estimatedCompletion?: string;
+    /** Ed25519 signature (optional in Phase 2). */
+    signature?: string;
+    /** Fields included in the signature. */
+    signedFields?: string[];
+}
+export interface MachineLedger {
+    schemaVersion: number;
+    machineId: string;
+    lastUpdated: string;
+    entries: LedgerEntry[];
+    lastCleanup: string;
+}
+export type OverlapTier = 0 | 1 | 2 | 3;
+export interface OverlapWarning {
+    /** Severity tier (0=none, 1=planned, 2=active, 3=architectural). */
+    tier: OverlapTier;
+    /** The entry that overlaps with planned work. */
+    entry: LedgerEntry;
+    /** Files that overlap. */
+    overlappingFiles: string[];
+    /** Human-readable description. */
+    message: string;
+}
+export interface WorkLedgerConfig {
+    /** State directory (.instar). */
+    stateDir: string;
+    /** This machine's ID. */
+    machineId: string;
+    /** User ID (for multi-user scenarios). */
+    userId?: string;
+    /** Max age for completed entries before cleanup (ms, default: 24h). */
+    completedMaxAgeMs?: number;
+    /** Max age for stale detection (ms, default: 2h). */
+    staleThresholdMs?: number;
+    /** Max age for stale entries before removal (ms, default: 6h). */
+    staleMaxAgeMs?: number;
+}
+export declare class WorkLedger {
+    private stateDir;
+    private machineId;
+    private userId?;
+    private ledgerDir;
+    private completedMaxAgeMs;
+    private staleThresholdMs;
+    private staleMaxAgeMs;
+    constructor(config: WorkLedgerConfig);
+    /**
+     * Record the start of a work session. Returns the created entry.
+     */
+    startWork(opts: {
+        sessionId: string;
+        task: string;
+        filesPlanned?: string[];
+        branch?: string;
+        estimatedCompletion?: string;
+    }): LedgerEntry;
+    /**
+     * Update an active work entry (called periodically during work).
+     */
+    updateWork(entryId: string, updates: {
+        task?: string;
+        filesModified?: string[];
+        filesPlanned?: string[];
+        estimatedCompletion?: string;
+    }): boolean;
+    /**
+     * End a work session (mark as completed or paused).
+     */
+    endWork(entryId: string, status?: 'completed' | 'paused'): boolean;
+    /**
+     * Read this machine's ledger file.
+     */
+    readOwnLedger(): MachineLedger;
+    /**
+     * Get aggregate view of all active/paused entries across all machines.
+     */
+    getActiveEntries(): LedgerEntry[];
+    /**
+     * Get all entries across all machines (including completed/stale).
+     */
+    getAllEntries(): LedgerEntry[];
+    /**
+     * Read all machine ledger files.
+     */
+    readAllLedgers(): MachineLedger[];
+    /**
+     * Check for overlap between planned files and active ledger entries.
+     * Returns warnings sorted by severity (highest first).
+     */
+    detectOverlap(myPlannedFiles: string[]): OverlapWarning[];
+    /**
+     * Clean up this machine's ledger entries:
+     * - Remove completed entries older than 24h
+     * - Mark entries with stale updatedAt (>2h) as "stale"
+     * - Remove stale entries older than 6h
+     *
+     * Returns the number of entries removed/modified.
+     */
+    cleanup(): {
+        removed: number;
+        markedStale: number;
+    };
+    private ledgerFilePath;
+    private readLedgerFile;
+    private writeOwnLedger;
+}
+//# sourceMappingURL=WorkLedger.d.ts.map

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

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