ostacky 0.5.8 → 0.5.10

package/assets/mcp/ostacky-controller/index.js

@@ -3,15 +3,63 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import * as z from 'zod/v4';
-import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { readFileSync, writeFileSync, renameSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { dirname, basename } from 'node:path';
+
+const MAX_TASKS = 50;
+const MAX_SNAPSHOT_JSON_LENGTH = 100 * 1024; // 100KB per snapshot serialized
+const MAX_STATE_FILE_SIZE = 1024 * 1024; // 1MB hard cap for the entire state file
+
+/**
+ * Safe JSON.stringify that won't throw on circular references.
+ */
+function safeJsonStringify(obj, pretty = false) {
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(
+            obj,
+            (key, value) => {
+                if (typeof value === 'object' && value !== null) {
+                    if (seen.has(value)) return '[Circular]';
+                    seen.add(value);
+                }
+                return value;
+            },
+            pretty ? 2 : undefined
+        );
+    } catch (e) {
+        return `[Unstringifiable: ${e.message}]`;
+    }
+}
 
 function log(event, data) {
     const ts = new Date().toISOString();
-    const payload = data ? ` ${JSON.stringify(data)}` : '';
+    const payload = data ? ` ${safeJsonStringify(data)}` : '';
     console.error(`[${ts}] ${event}${payload}`);
 }
 
+/**
+ * Cleans up stale .tmp.* files from a previous crash.
+ */
+function cleanupTmpFiles(statePath) {
+    if (!statePath) return;
+    const dir = dirname(statePath);
+    const name = basename(statePath);
+    try {
+        for (const entry of readdirSync(dir)) {
+            if (entry.startsWith(name + '.tmp.')) {
+                try {
+                    unlinkSync(dir + '/' + entry);
+                } catch {
+                    /* best-effort */
+                }
+            }
+        }
+    } catch {
+        /* directory may not exist yet */
+    }
+}
+
 const STATES = Object.freeze({
     INTERPRETATION_PENDING: 'INTERPRETATION_PENDING',
     CLARIFICATION_PENDING: 'CLARIFICATION_PENDING',
@@ -50,8 +98,13 @@ class OstackyController {
 
     constructor(opts = {}) {
         this.#statePath = opts.statePath;
-        this.#state = opts.initialState ? { ...DEFAULT_STATE, ...opts.initialState } : null;
-        this.#loaded = false;
+        if (opts.initialState) {
+            this.#state = { ...DEFAULT_STATE, ...opts.initialState };
+            this.#loaded = true;
+        } else {
+            this.#state = null;
+            this.#loaded = false;
+        }
     }
 
     #load() {
@@ -61,11 +114,32 @@ class OstackyController {
             this.#loaded = true;
             return;
         }
+        // Try primary state file
         try {
             const raw = readFileSync(this.#statePath, 'utf8');
+            if (raw.length > MAX_STATE_FILE_SIZE) throw new Error(`State file too large: ${raw.length} bytes`);
             this.#state = { ...DEFAULT_STATE, ...JSON.parse(raw) };
+            this.#loaded = true;
+            return;
+        } catch (err) {
+            log('warn:load_primary_failed', { error: err.message });
+        }
+        // Fallback: try .backup
+        const backupPath = this.#statePath + '.backup';
+        try {
+            const raw = readFileSync(backupPath, 'utf8');
+            if (raw.length > MAX_STATE_FILE_SIZE) throw new Error(`Backup too large: ${raw.length} bytes`);
+            this.#state = { ...DEFAULT_STATE, ...JSON.parse(raw), error: 'State restored from backup' };
+            log('warn:state_restored_from_backup');
+            this.#loaded = true;
+            return;
         } catch {
-            this.#state = { ...DEFAULT_STATE };
+            // No backup either — set error state instead of silent reset
+            this.#state = {
+                ...DEFAULT_STATE,
+                error: `State file corrupt: ${err.message}. No backup available. State reset to default.`,
+            };
+            log('warn:state_reset', { error: err.message });
         }
         this.#loaded = true;
     }
@@ -74,15 +148,57 @@ class OstackyController {
         if (!this.#statePath) return;
         const dir = dirname(this.#statePath);
         mkdirSync(dir, { recursive: true });
+        const serialized = safeJsonStringify(this.#state, true);
+        // Hard cap — if state exceeds 1MB, trim snapshots and retry
+        if (serialized.length > MAX_STATE_FILE_SIZE) {
+            log('warn:state_oversized', { size: serialized.length });
+            this.#state.snapshots = { codegraph: null, execution: null };
+            const trimmed = safeJsonStringify(this.#state, true);
+            if (trimmed.length > MAX_STATE_FILE_SIZE) {
+                log('error:state_too_large_even_after_trim');
+                return; // Don't persist — better to keep old state than write garbage
+            }
+            const tmp = this.#statePath + '.tmp.' + process.pid;
+            writeFileSync(tmp, trimmed, 'utf8');
+            renameSync(tmp, this.#statePath);
+            return;
+        }
         const tmp = this.#statePath + '.tmp.' + process.pid;
-        writeFileSync(tmp, JSON.stringify(this.#state, null, 2), 'utf8');
+        writeFileSync(tmp, serialized, 'utf8');
         renameSync(tmp, this.#statePath);
+        // Best-effort backup
+        try {
+            const backupPath = this.#statePath + '.backup';
+            writeFileSync(backupPath, serialized, 'utf8');
+        } catch {
+            /* backup is best-effort */
+        }
+    }
+
+    /**
+     * Trims old completed tasks when we exceed MAX_TASKS.
+     * Keeps the most recent MAX_TASKS entries.
+     */
+    #trimTasks() {
+        if (!this.#state.tasks) return;
+        const entries = Object.entries(this.#state.tasks);
+        if (entries.length <= MAX_TASKS) return;
+        // Sort by completedAt (desc), keep newest MAX_TASKS
+        entries.sort((a, b) => {
+            const da = a[1].completedAt || '';
+            const db = b[1].completedAt || '';
+            return db.localeCompare(da);
+        });
+        const trimmed = Object.fromEntries(entries.slice(0, MAX_TASKS));
+        this.#state.tasks = trimmed;
+        log('warn:tasks_trimmed', { before: entries.length, after: MAX_TASKS });
     }
 
     #transition(to, changes = {}) {
         this.#state.revision++;
         this.#state.state = to;
         Object.assign(this.#state, changes);
+        this.#trimTasks();
         this.#persist();
     }
 
@@ -201,7 +317,7 @@ class OstackyController {
         const to = this.#isAllowedTransition(this.#state.state, 'record_discovery');
         if (!to) return { error: `Cannot record discovery from state ${this.#state.state}` };
         if (!['0', '0+1', '1+'].includes(level)) return { error: `Invalid level: ${level}` };
-        this.#transition('ROUTE_DECISION_PENDING', {
+        this.#transition(to, {
             routeDecisionId: routeDecisionId || 'route-' + Date.now(),
             routeChoice: null,
             snapshots: { ...this.#state.snapshots, codegraph: snapshot || this.#state.snapshots.codegraph },
@@ -396,6 +512,7 @@ class OstackyController {
             if (!this.#state.fileFingerprints) this.#state.fileFingerprints = {};
             this.#state.fileFingerprints[filePath] = fileHash;
         }
+        this.#trimTasks();
         this.#persist();
         return {
             taskId,
@@ -404,14 +521,42 @@ class OstackyController {
                 .length,
         };
     }
+
+    /**
+     * Public flush — force-persists current state to disk.
+     * Used by graceful shutdown (private fields not accessible from outside).
+     */
+    flush() {
+        this.#persist();
+    }
 }
 
 const statePath = process.env.OSTACKY_STATE_PATH || '.opencode/ostacky-state.json';
 const controller = new OstackyController({ statePath });
 
+/**
+ * Wraps an async tool handler to ALWAYS return a response (even on error).
+ * Without this, an unhandled exception in any tool handler leaves the LLM
+ * waiting forever — the root cause of agent freezes.
+ */
+function safeHandler(fn) {
+    return async (params) => {
+        try {
+            const result = await fn(params);
+            return { content: [{ type: 'text', text: safeJsonStringify(result) }] };
+        } catch (error) {
+            log('tool:error', { name: fn.name || 'anonymous', error: error.message });
+            return {
+                content: [{ type: 'text', text: safeJsonStringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    };
+}
+
 const server = new McpServer({
     name: 'ostacky-controller',
-    version: '0.5.8',
+    version: '0.5.10',
 });
 
 server.registerTool(
@@ -423,11 +568,10 @@ server.registerTool(
             changeId: z.string().optional().describe('Optional change ID for OpenSpec tracking'),
         }),
     },
-    async ({ requestId, changeId }) => {
+    safeHandler(async ({ requestId, changeId }) => {
         log('tool:start_request');
-        const result = await controller.startRequest({ requestId, changeId });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.startRequest({ requestId, changeId });
+    })
 );
 
 server.registerTool(
@@ -438,11 +582,10 @@ server.registerTool(
             question: z.string().optional().describe('The clarification question'),
         }),
     },
-    async ({ question }) => {
+    safeHandler(async ({ question }) => {
         log('tool:request_clarification');
-        const result = await controller.requestClarification({ question });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.requestClarification({ question });
+    })
 );
 
 server.registerTool(
@@ -451,11 +594,10 @@ server.registerTool(
         description: 'Record that clarification was answered. Transitions to DISCOVERY.',
         inputSchema: z.object({}),
     },
-    async () => {
+    safeHandler(async () => {
         log('tool:record_clarification');
-        const result = await controller.recordClarification();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.recordClarification();
+    })
 );
 
 server.registerTool(
@@ -468,11 +610,10 @@ server.registerTool(
             snapshot: z.any().optional().describe('Optional CodeGraph snapshot'),
         }),
     },
-    async ({ level, routeDecisionId, snapshot }) => {
+    safeHandler(async ({ level, routeDecisionId, snapshot }) => {
         log('tool:record_discovery', { level });
-        const result = await controller.recordDiscovery({ level, routeDecisionId, snapshot });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.recordDiscovery({ level, routeDecisionId, snapshot });
+    })
 );
 
 server.registerTool(
@@ -484,11 +625,10 @@ server.registerTool(
             choice: z.enum(['SPEC', 'DIRECT']).describe('Route choice'),
         }),
     },
-    async ({ decisionId, choice }) => {
+    safeHandler(async ({ decisionId, choice }) => {
         log('tool:consume_route_decision', { choice });
-        const result = await controller.consumeRouteDecision({ decisionId, choice });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.consumeRouteDecision({ decisionId, choice });
+    })
 );
 
 server.registerTool(
@@ -497,11 +637,10 @@ server.registerTool(
         description: 'Mark specification phase as complete. Transitions to EXECUTION_ANALYSIS.',
         inputSchema: z.object({}),
     },
-    async () => {
+    safeHandler(async () => {
         log('tool:spec_complete');
-        const result = await controller.specComplete();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.specComplete();
+    })
 );
 
 server.registerTool(
@@ -513,11 +652,10 @@ server.registerTool(
             snapshot: z.any().optional().describe('Execution analysis snapshot'),
         }),
     },
-    async ({ executionDecisionId, snapshot }) => {
+    safeHandler(async ({ executionDecisionId, snapshot }) => {
         log('tool:record_execution_analysis');
-        const result = await controller.recordExecutionAnalysis({ executionDecisionId, snapshot });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.recordExecutionAnalysis({ executionDecisionId, snapshot });
+    })
 );
 
 server.registerTool(
@@ -529,11 +667,10 @@ server.registerTool(
             mode: z.enum(['INLINE', 'SUBAGENT_DRIVEN']).describe('Execution mode'),
         }),
     },
-    async ({ decisionId, mode }) => {
+    safeHandler(async ({ decisionId, mode }) => {
         log('tool:consume_execution_decision', { mode });
-        const result = await controller.consumeExecutionDecision({ decisionId, mode });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.consumeExecutionDecision({ decisionId, mode });
+    })
 );
 
 server.registerTool(
@@ -542,11 +679,10 @@ server.registerTool(
         description: 'Mark implementation as complete. Transitions to SYNC.',
         inputSchema: z.object({}),
     },
-    async () => {
+    safeHandler(async () => {
         log('tool:implementation_complete');
-        const result = await controller.implementationComplete();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.implementationComplete();
+    })
 );
 
 server.registerTool(
@@ -555,11 +691,10 @@ server.registerTool(
         description: 'Mark sync as complete. Transitions to DONE.',
         inputSchema: z.object({}),
     },
-    async () => {
+    safeHandler(async () => {
         log('tool:sync_complete');
-        const result = await controller.syncComplete();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.syncComplete();
+    })
 );
 
 server.registerTool(
@@ -570,11 +705,10 @@ server.registerTool(
             reason: z.string().optional().describe('Reason for blocking'),
         }),
     },
-    async ({ reason }) => {
+    safeHandler(async ({ reason }) => {
         log('tool:block');
-        const result = await controller.block({ reason });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.block({ reason });
+    })
 );
 
 server.registerTool(
@@ -585,11 +719,10 @@ server.registerTool(
             reason: z.string().optional().describe('Reason for replanning'),
         }),
     },
-    async ({ reason }) => {
+    safeHandler(async ({ reason }) => {
         log('tool:replan');
-        const result = await controller.replan({ reason });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.replan({ reason });
+    })
 );
 
 server.registerTool(
@@ -598,10 +731,9 @@ server.registerTool(
         description: 'Get the current controller state (reads persistent store).',
         inputSchema: z.object({}),
     },
-    async () => {
-        const result = await controller.getState();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+    safeHandler(async () => {
+        return await controller.getState();
+    })
 );
 
 server.registerTool(
@@ -610,10 +742,9 @@ server.registerTool(
         description: 'Get current task states.',
         inputSchema: z.object({}),
     },
-    async () => {
-        const result = await controller.getTasks();
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+    safeHandler(async () => {
+        return await controller.getTasks();
+    })
 );
 
 server.registerTool(
@@ -621,19 +752,34 @@ server.registerTool(
     {
         description:
             'Validate an edit against current file content. Returns EDITABLE, ALREADY_APPLIED, or CONFLICT. ' +
-            'Call BEFORE executing an edit tool. Only valid in EXECUTING_INLINE or EXECUTING_SUBAGENTS states.',
+            'Call BEFORE executing an edit tool. Only valid in EXECUTING_INLINE or EXECUTING_SUBAGENTS states. ' +
+            'IMPORTANT: content parameter is REQUIRED. Read the file first, then pass the full content.',
         inputSchema: z.object({
             oldString: z.string().describe('The exact string to find in content (must be unique).'),
             newString: z.string().describe('The replacement string.'),
-            content: z.string().describe('The current file content (read fresh with Read tool).'),
+            content: z
+                .string()
+                .describe(
+                    'REQUIRED — The current file content. Read the file first with Read tool, then pass the full content here.'
+                ),
             taskId: z.string().optional().describe('Optional task ID for tracking.'),
         }),
     },
-    async ({ oldString, newString, content, taskId }) => {
-        log('tool:validate_edit', { taskId, oldLen: oldString.length, newLen: newString.length });
-        const result = await controller.validateEdit({ oldString, newString, content, taskId });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+    safeHandler(async ({ oldString, newString, content, taskId }) => {
+        log('tool:validate_edit', {
+            taskId,
+            oldLen: oldString?.length,
+            newLen: newString?.length,
+            hasContent: !!content,
+        });
+        if (typeof content !== 'string' || typeof oldString !== 'string' || typeof newString !== 'string') {
+            return {
+                outcome: 'CONFLICT',
+                reason: 'Missing required fields: content, oldString, and newString are all required. Read the file first, then pass content to validate_edit.',
+            };
+        }
+        return await controller.validateEdit({ oldString, newString, content, taskId });
+    })
 );
 
 server.registerTool(
@@ -648,22 +794,59 @@ server.registerTool(
             fileHash: z.string().optional().describe('Optional SHA-256 hash of the file after modification.'),
         }),
     },
-    async ({ taskId, filePath, fileHash }) => {
+    safeHandler(async ({ taskId, filePath, fileHash }) => {
         log('tool:complete_task', { taskId, filePath });
-        const result = await controller.completeTask({ taskId, filePath, fileHash });
-        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
+        return await controller.completeTask({ taskId, filePath, fileHash });
+    })
 );
 
+/**
+ * Graceful shutdown: clean up tmp files and flush state.
+ */
+function setupGracefulShutdown(ctrl) {
+    const shutdown = (signal) => {
+        log('shutdown', { signal });
+        // Final persist attempt (flush via public method, sync inside)
+        try {
+            if (ctrl) ctrl.flush();
+        } catch {
+            /* best-effort */
+        }
+        // Clean up own tmp files
+        try {
+            cleanupTmpFiles(statePath);
+        } catch {
+            /* best-effort */
+        }
+        process.exit(signal === 'SIGINT' ? 130 : 0);
+    };
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    // Prevent unhandled rejections from silently killing the server
+    process.on('unhandledRejection', (reason) => {
+        log('unhandled_rejection', { reason: String(reason) });
+    });
+}
+
 async function main() {
     log('Starting ostacky-controller MCP...');
     log('State path:', { path: statePath });
+    // Clean up stale tmp files from previous runs
+    cleanupTmpFiles(statePath);
+    setupGracefulShutdown(controller);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     log('ostacky-controller connected and ready');
 }
 
-main().catch((error) => {
-    console.error('Fatal error:', error);
-    process.exit(1);
-});
+const isDirectRun =
+    process.argv[1] && (process.argv[1].endsWith('/index.js') || process.argv[1].endsWith('\\index.js'));
+
+if (isDirectRun) {
+    main().catch((error) => {
+        console.error('Fatal error:', error);
+        process.exit(1);
+    });
+}
+
+export { OstackyController };

package/assets/mcp/ostacky-controller/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ostacky-controller",
-    "version": "0.5.8",
+    "version": "0.5.10",
     "private": true,
     "type": "module",
     "dependencies": {