mcp-codex-subagent 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# Codex MCP Server
+
+[![npm version](https://img.shields.io/npm/v/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server)
+[![license](https://img.shields.io/npm/l/codex-mcp-server.svg)](https://www.npmjs.com/package/codex-mcp-server)
+
+Bridge between Claude and OpenAI's Codex CLI — get AI-powered code analysis, generation, and review right in your editor.
+
+```mermaid
+graph LR
+    A[Claude Code] --> B[Codex MCP Server]
+    B --> C[Codex CLI]
+    C --> D[OpenAI API]
+
+    style A fill:#FF6B35
+    style B fill:#4A90E2
+    style C fill:#00D4AA
+    style D fill:#FFA500
+```
+
+## Quick Start
+
+### 1. Install Codex CLI
+
+```bash
+npm i -g @openai/codex
+codex login --api-key "your-openai-api-key"
+```
+
+### 2. Add to Claude Code
+
+```bash
+claude mcp add codex-cli -- npx -y codex-mcp-server
+```
+
+### 3. Start Using
+
+```
+Ask codex to explain this function
+Use codex to refactor this code for better performance
+Use review to check my uncommitted changes
+```
+
+## One-Click Install
+
+[![VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=codex-cli&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22codex-mcp-server%22%5D%7D)
+[![VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=codex-cli&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22codex-mcp-server%22%5D%7D)
+[![Cursor](https://img.shields.io/badge/Cursor-Install-00D8FF?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=codex&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IC15IGNvZGV4LW1jcC1zZXJ2ZXIiLCJlbnYiOnt9fQ%3D%3D)
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `codex` | AI coding assistant with session support, model selection, and structured output metadata |
+| `review` | AI-powered code review for uncommitted changes, branches, or commits |
+| `listSessions` | View active conversation sessions |
+| `ping` | Test server connection |
+| `help` | Get Codex CLI help |
+
+## Examples
+
+**Code analysis:**
+```
+Use codex to analyze this authentication logic for security issues
+```
+
+**Multi-turn conversations:**
+```
+Use codex with sessionId "refactor" to analyze this module
+Use codex with sessionId "refactor" to implement your suggestions
+```
+Passing a sessionId creates the session on first use, so listSessions will show
+it (for this server instance) and subsequent calls can resume context.
+
+**Code review:**
+```
+Use review with base "main" to check my PR changes
+Use review with uncommitted true to review my local changes
+```
+
+**Advanced options:**
+```
+Use codex with model "o3" and reasoningEffort "high" for complex analysis
+Use codex with fullAuto true and sandbox "workspace-write" for automated tasks
+Use codex with callbackUri "http://localhost:1234/callback" for static callbacks
+Use codex to return structuredContent with threadId metadata when available
+```
+
+## Requirements
+
+- **Codex CLI v0.75.0+** — Install with `npm i -g @openai/codex` or `brew install codex`
+- **OpenAI API key** — Run `codex login --api-key "your-key"` to authenticate
+
+## Codex 0.87 Compatibility
+- **Thread ID + structured output**: When Codex CLI emits `threadId`, this server returns it in content metadata and `structuredContent`, and advertises an `outputSchema` for structured responses.
+
+## Documentation
+
+- **[API Reference](docs/api-reference.md)** — Full tool parameters and response formats
+- **[Session Management](docs/session-management.md)** — How conversations work
+- **[Codex CLI Integration](docs/codex-cli-integration.md)** — Version compatibility and CLI details
+
+## Environment Variables
+- `CODEX_MCP_CALLBACK_URI`: Static MCP callback URI passed to Codex when set (overridden by `callbackUri` tool arg)
+
+## Development
+
+```bash
+npm install    # Install dependencies
+npm run dev    # Development mode
+npm run build  # Build for production
+npm test       # Run tests
+```
+
+## Related Projects
+
+- **[gemini-mcp-server](https://github.com/tuannvm/gemini-mcp-server)** — MCP server for Gemini CLI with 1M+ token context, web search, and media analysis
+
+## License
+
+ISC

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+export declare class ToolExecutionError extends Error {
+    readonly toolName: string;
+    readonly cause?: unknown | undefined;
+    constructor(toolName: string, message: string, cause?: unknown | undefined);
+}
+export declare class CommandExecutionError extends Error {
+    readonly command: string;
+    readonly cause?: unknown | undefined;
+    constructor(command: string, message: string, cause?: unknown | undefined);
+}
+export declare class ValidationError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string, message: string);
+}
+export declare function handleError(error: unknown, context: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,QAAQ,EAAE,MAAM;aAEhB,KAAK,CAAC,EAAE,OAAO;gBAFf,QAAQ,EAAE,MAAM,EAChC,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC;AAED,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,OAAO,EAAE,MAAM;aAEf,KAAK,CAAC,EAAE,OAAO;gBAFf,OAAO,EAAE,MAAM,EAC/B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC;AAED,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM,EAChC,OAAO,EAAE,MAAM;CAKlB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKnE"}

package/dist/errors.js

@@ -0,0 +1,35 @@
+export class ToolExecutionError extends Error {
+    toolName;
+    cause;
+    constructor(toolName, message, cause) {
+        super(`Failed to execute tool "${toolName}": ${message}`);
+        this.toolName = toolName;
+        this.cause = cause;
+        this.name = 'ToolExecutionError';
+    }
+}
+export class CommandExecutionError extends Error {
+    command;
+    cause;
+    constructor(command, message, cause) {
+        super(`Command execution failed for "${command}": ${message}`);
+        this.command = command;
+        this.cause = cause;
+        this.name = 'CommandExecutionError';
+    }
+}
+export class ValidationError extends Error {
+    toolName;
+    constructor(toolName, message) {
+        super(`Validation failed for tool "${toolName}": ${message}`);
+        this.toolName = toolName;
+        this.name = 'ValidationError';
+    }
+}
+export function handleError(error, context) {
+    if (error instanceof Error) {
+        return `Error in ${context}: ${error.message}`;
+    }
+    return `Error in ${context}: ${String(error)}`;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEzB;IAEA;IAHlB,YACkB,QAAgB,EAChC,OAAe,EACC,KAAe;QAE/B,KAAK,CAAC,2BAA2B,QAAQ,MAAM,OAAO,EAAE,CAAC,CAAC;QAJ1C,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAE5B;IAEA;IAHlB,YACkB,OAAe,EAC/B,OAAe,EACC,KAAe;QAE/B,KAAK,CAAC,iCAAiC,OAAO,MAAM,OAAO,EAAE,CAAC,CAAC;QAJ/C,YAAO,GAAP,OAAO,CAAQ;QAEf,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAEtB;IADlB,YACkB,QAAgB,EAChC,OAAe;QAEf,KAAK,CAAC,+BAA+B,QAAQ,MAAM,OAAO,EAAE,CAAC,CAAC;QAH9C,aAAQ,GAAR,QAAQ,CAAQ;QAIhC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,OAAe;IACzD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,YAAY,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACjD,CAAC;IACD,OAAO,YAAY,OAAO,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACjD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import chalk from 'chalk';
+import { CodexMcpServer } from './server.js';
+const SERVER_CONFIG = {
+    name: 'codex-mcp-server',
+    version: '0.0.6',
+};
+async function main() {
+    try {
+        const server = new CodexMcpServer(SERVER_CONFIG);
+        await server.start();
+    }
+    catch (error) {
+        console.error(chalk.red('Failed to start server:'), error);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,aAAa,GAAG;IACpB,IAAI,EAAE,kBAAkB;IACxB,OAAO,EAAE,OAAO;CACR,CAAC;AAEX,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,aAAa,CAAC,CAAC;QACjD,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAyB,CAAC,EAAE,KAAK,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import { type ServerConfig } from './types.js';
+export declare class CodexMcpServer {
+    private readonly server;
+    private readonly config;
+    constructor(config: ServerConfig);
+    private setupHandlers;
+    private isValidToolName;
+    start(): Promise<void>;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,YAAY,EAKlB,MAAM,YAAY,CAAC;AAKpB,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;gBAE1B,MAAM,EAAE,YAAY;IAiBhC,OAAO,CAAC,aAAa;IA4DrB,OAAO,CAAC,eAAe;IAIjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}

package/dist/server.js

@@ -0,0 +1,90 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import chalk from 'chalk';
+import { TOOLS, } from './types.js';
+import { handleError } from './errors.js';
+import { toolDefinitions } from './tools/definitions.js';
+import { toolHandlers } from './tools/handlers.js';
+export class CodexMcpServer {
+    server;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.server = new Server({
+            name: config.name,
+            version: config.version,
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        // List tools handler
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return { tools: toolDefinitions };
+        });
+        // Call tool handler
+        this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+            const { name, arguments: args } = request.params;
+            const progressToken = request.params._meta?.progressToken;
+            // Create progress sender that uses MCP notifications
+            const createProgressContext = () => {
+                let progressCount = 0;
+                return {
+                    progressToken,
+                    sendProgress: async (message, progress, total) => {
+                        if (!progressToken)
+                            return;
+                        progressCount++;
+                        try {
+                            await extra.sendNotification({
+                                method: 'notifications/progress',
+                                params: {
+                                    progressToken,
+                                    progress: progress ?? progressCount,
+                                    total,
+                                    message,
+                                },
+                            });
+                        }
+                        catch (err) {
+                            // Log but don't fail the operation if progress notification fails
+                            console.error(chalk.yellow('Failed to send progress notification:'), err);
+                        }
+                    },
+                };
+            };
+            try {
+                if (!this.isValidToolName(name)) {
+                    throw new Error(`Unknown tool: ${name}`);
+                }
+                const handler = toolHandlers[name];
+                const context = createProgressContext();
+                return await handler.execute(args, context);
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: handleError(error, `tool "${name}"`),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    isValidToolName(name) {
+        return Object.values(TOOLS).includes(name);
+    }
+    async start() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error(chalk.green(`${this.config.name} started successfully`));
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/session/storage.d.ts

@@ -0,0 +1,44 @@
+export interface ConversationTurn {
+    prompt: string;
+    response: string;
+    timestamp: Date;
+}
+export interface SessionData {
+    id: string;
+    createdAt: Date;
+    lastAccessedAt: Date;
+    turns: ConversationTurn[];
+    codexConversationId?: string;
+}
+export interface SessionStorage {
+    createSession(): string;
+    ensureSession(sessionId: string): void;
+    getSession(sessionId: string): SessionData | undefined;
+    updateSession(sessionId: string, data: Partial<SessionData>): void;
+    deleteSession(sessionId: string): boolean;
+    listSessions(): SessionData[];
+    addTurn(sessionId: string, turn: ConversationTurn): void;
+    resetSession(sessionId: string): void;
+    setCodexConversationId(sessionId: string, conversationId: string): void;
+    getCodexConversationId(sessionId: string): string | undefined;
+}
+export declare class InMemorySessionStorage implements SessionStorage {
+    private sessions;
+    private readonly maxSessions;
+    private readonly sessionTtl;
+    private readonly maxSessionIdLength;
+    private readonly sessionIdPattern;
+    createSession(): string;
+    ensureSession(sessionId: string): void;
+    getSession(sessionId: string): SessionData | undefined;
+    updateSession(sessionId: string, data: Partial<SessionData>): void;
+    deleteSession(sessionId: string): boolean;
+    listSessions(): SessionData[];
+    addTurn(sessionId: string, turn: ConversationTurn): void;
+    resetSession(sessionId: string): void;
+    setCodexConversationId(sessionId: string, conversationId: string): void;
+    getCodexConversationId(sessionId: string): string | undefined;
+    private cleanupExpiredSessions;
+    private enforceMaxSessions;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/session/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/session/storage.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,IAAI,CAAC;IAChB,cAAc,EAAE,IAAI,CAAC;IACrB,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,IAAI,MAAM,CAAC;IACxB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IACvD,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;IACnE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1C,YAAY,IAAI,WAAW,EAAE,CAAC;IAC9B,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACzD,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACxE,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC/D;AAED,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAO;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAO;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsB;IAEvD,aAAa,IAAI,MAAM;IAiBvB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IA+BtC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAQtD,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAQlE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIzC,YAAY,IAAI,WAAW,EAAE;IAO7B,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI;IAYxD,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IASrC,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI;IAQvE,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK7D,OAAO,CAAC,sBAAsB;IAS9B,OAAO,CAAC,kBAAkB;CAU3B"}

package/dist/session/storage.js

@@ -0,0 +1,113 @@
+import { randomUUID } from 'crypto';
+import { TOOLS } from '../types.js';
+import { ValidationError } from '../errors.js';
+export class InMemorySessionStorage {
+    sessions = new Map();
+    maxSessions = 100;
+    sessionTtl = 24 * 60 * 60 * 1000; // 24 hours
+    maxSessionIdLength = 256;
+    sessionIdPattern = /^[a-zA-Z0-9_-]+$/;
+    createSession() {
+        this.cleanupExpiredSessions();
+        const sessionId = randomUUID();
+        const now = new Date();
+        this.sessions.set(sessionId, {
+            id: sessionId,
+            createdAt: now,
+            lastAccessedAt: now,
+            turns: [],
+        });
+        this.enforceMaxSessions();
+        return sessionId;
+    }
+    ensureSession(sessionId) {
+        this.cleanupExpiredSessions();
+        if (!sessionId ||
+            sessionId.length > this.maxSessionIdLength ||
+            !this.sessionIdPattern.test(sessionId)) {
+            throw new ValidationError(TOOLS.CODEX, 'Session ID must be 1-256 characters and contain only letters, numbers, hyphens, and underscores');
+        }
+        const existing = this.sessions.get(sessionId);
+        if (existing) {
+            existing.lastAccessedAt = new Date();
+            return;
+        }
+        const now = new Date();
+        this.sessions.set(sessionId, {
+            id: sessionId,
+            createdAt: now,
+            lastAccessedAt: now,
+            turns: [],
+        });
+        this.enforceMaxSessions();
+    }
+    getSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.lastAccessedAt = new Date();
+        }
+        return session;
+    }
+    updateSession(sessionId, data) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            Object.assign(session, data);
+            session.lastAccessedAt = new Date();
+        }
+    }
+    deleteSession(sessionId) {
+        return this.sessions.delete(sessionId);
+    }
+    listSessions() {
+        this.cleanupExpiredSessions();
+        return Array.from(this.sessions.values()).sort((a, b) => b.lastAccessedAt.getTime() - a.lastAccessedAt.getTime());
+    }
+    addTurn(sessionId, turn) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            // Ensure turns array exists and is valid
+            if (!Array.isArray(session.turns)) {
+                session.turns = [];
+            }
+            session.turns.push(turn);
+            session.lastAccessedAt = new Date();
+        }
+    }
+    resetSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.turns = [];
+            session.codexConversationId = undefined;
+            session.lastAccessedAt = new Date();
+        }
+    }
+    setCodexConversationId(sessionId, conversationId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.codexConversationId = conversationId;
+            session.lastAccessedAt = new Date();
+        }
+    }
+    getCodexConversationId(sessionId) {
+        const session = this.sessions.get(sessionId);
+        return session?.codexConversationId;
+    }
+    cleanupExpiredSessions() {
+        const now = Date.now();
+        for (const [sessionId, session] of this.sessions) {
+            if (now - session.lastAccessedAt.getTime() > this.sessionTtl) {
+                this.sessions.delete(sessionId);
+            }
+        }
+    }
+    enforceMaxSessions() {
+        if (this.sessions.size <= this.maxSessions)
+            return;
+        const sessions = this.listSessions();
+        const sessionsToDelete = sessions.slice(this.maxSessions);
+        for (const session of sessionsToDelete) {
+            this.sessions.delete(session.id);
+        }
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/session/storage.js.map

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

package/dist/templates/index.d.ts

@@ -0,0 +1,22 @@
+export declare const TASK_TYPES: {
+    readonly 'super-coder': "super coder for all coding tasks";
+    readonly 'super-planner': "super planner for all planning tasks";
+    readonly 'super-researcher': "super researcher for answering any question";
+    readonly 'super-tester': "super tester to test stuff properly";
+};
+export type TaskType = keyof typeof TASK_TYPES;
+export declare const TASK_TYPE_IDS: TaskType[];
+export declare function isValidTaskType(type: string): type is TaskType;
+/**
+ * Matryoshka template resolution:
+ *   base template (super-coder.mdx)
+ *     + specialization overlay (overlays/coder-typescript.mdx)
+ *       + user prompt (injected at {{user_prompt}})
+ *
+ * The overlay is inserted before the "## BEGIN" section of the base template.
+ * If no overlay or no BEGIN section, overlay is appended before user prompt injection.
+ *
+ * When MCP_ENABLED_TOOLS is set, TOOLKIT table rows are filtered to only show enabled tools.
+ */
+export declare function applyTemplate(taskType: TaskType, userPrompt: string, specialization?: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,UAAU;;;;;CAKb,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,UAAU,CAAC;AAC/C,eAAO,MAAM,aAAa,EAA8B,QAAQ,EAAE,CAAC;AAmFnE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,QAAQ,CAE9D;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAsCrG"}