@gramatr/mcp 0.0.5

package/dist/bin/gramatr-mcp.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * gramatr-mcp — Local MCP server entry point.
+ *
+ * Usage:
+ *   gramatr-mcp              Start the stdio MCP server (default)
+ *   gramatr-mcp setup claude Auto-configure Claude Code MCP settings
+ *   gramatr-mcp --version    Print version
+ *   gramatr-mcp --help       Show help
+ *
+ * MCP clients configure this as:
+ *   { "command": "node", "args": ["~/.gramatr/mcp/bin/gramatr-mcp.js"] }
+ *
+ * Or via npx (slower, checks npm on every invocation):
+ *   { "command": "npx", "args": ["-y", "@gramatr/mcp"] }
+ */
+export {};
+//# sourceMappingURL=gramatr-mcp.d.ts.map

package/dist/bin/gramatr-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gramatr-mcp.d.ts","sourceRoot":"","sources":["../../src/bin/gramatr-mcp.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}

package/dist/bin/gramatr-mcp.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * gramatr-mcp — Local MCP server entry point.
+ *
+ * Usage:
+ *   gramatr-mcp              Start the stdio MCP server (default)
+ *   gramatr-mcp setup claude Auto-configure Claude Code MCP settings
+ *   gramatr-mcp --version    Print version
+ *   gramatr-mcp --help       Show help
+ *
+ * MCP clients configure this as:
+ *   { "command": "node", "args": ["~/.gramatr/mcp/bin/gramatr-mcp.js"] }
+ *
+ * Or via npx (slower, checks npm on every invocation):
+ *   { "command": "npx", "args": ["-y", "@gramatr/mcp"] }
+ */
+import { startServer } from '../server/server.js';
+import { setupClaude } from './setup.js';
+const args = process.argv.slice(2);
+if (args.includes('--version') || args.includes('-v')) {
+    process.stdout.write('0.0.5\n');
+    process.exit(0);
+}
+if (args.includes('--help') || args.includes('-h')) {
+    process.stderr.write(`
+  gramatr-mcp — Local MCP server for grāmatr
+
+  Proxies all remote gramatr tools with local auth injection, caching,
+  offline queueing, and local web tools.
+
+  Usage:
+    gramatr-mcp              Start the server (stdio)
+    gramatr-mcp setup claude Configure Claude Code to use this server
+    gramatr-mcp --version    Print version
+    gramatr-mcp --help       Show this help
+
+  Configuration:
+    Auth token:    ~/.gramatr.json (token field)
+    Server URL:    GRAMATR_URL env or ~/.gramatr.json server_url
+    API key:       GRAMATR_API_KEY env (overrides token)
+
+  Setup:
+    gramatr-mcp setup claude             Write MCP config to ~/.claude.json
+    gramatr-mcp setup claude --dry       Preview without writing
+`);
+    process.exit(0);
+}
+async function main() {
+    // Handle setup subcommand
+    if (args[0] === 'setup') {
+        const target = args[1];
+        const dryRun = args.includes('--dry');
+        if (target === 'claude') {
+            setupClaude(dryRun);
+            return;
+        }
+        process.stderr.write(`[gramatr-mcp] Unknown setup target: ${target}\n`);
+        process.stderr.write('  Supported: gramatr-mcp setup claude\n');
+        process.exit(1);
+    }
+    // Default: start the stdio server
+    await startServer();
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`[gramatr-mcp] Fatal: ${message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=gramatr-mcp.js.map

package/dist/bin/gramatr-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gramatr-mcp.js","sourceRoot":"","sources":["../../src/bin/gramatr-mcp.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;CAoBtB,CAAC,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,0BAA0B;IAC1B,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAEtC,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,WAAW,CAAC,MAAM,CAAC,CAAC;YACpB,OAAO;QACT,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uCAAuC,MAAM,IAAI,CAAC,CAAC;QACxE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,kCAAkC;IAClC,MAAM,WAAW,EAAE,CAAC;AACtB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB,OAAO,IAAI,CAAC,CAAC;IAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/bin/setup.d.ts

@@ -0,0 +1,13 @@
+/**
+ * gramatr setup claude — auto-configure Claude Code to use the local MCP server.
+ *
+ * Writes the mcpServers entry into ~/.claude.json (Claude Code's global MCP config).
+ * Safe: reads existing config, merges in the gramatr server entry, writes back.
+ * Idempotent: running it twice produces the same result.
+ *
+ * Usage:
+ *   gramatr-mcp setup claude       Configure Claude Code
+ *   gramatr-mcp setup claude --dry Run without writing
+ */
+export declare function setupClaude(dryRun?: boolean): void;
+//# sourceMappingURL=setup.d.ts.map

package/dist/bin/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/bin/setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA2DH,wBAAgB,WAAW,CAAC,MAAM,UAAQ,GAAG,IAAI,CA+ChD"}

package/dist/bin/setup.js

@@ -0,0 +1,93 @@
+/**
+ * gramatr setup claude — auto-configure Claude Code to use the local MCP server.
+ *
+ * Writes the mcpServers entry into ~/.claude.json (Claude Code's global MCP config).
+ * Safe: reads existing config, merges in the gramatr server entry, writes back.
+ * Idempotent: running it twice produces the same result.
+ *
+ * Usage:
+ *   gramatr-mcp setup claude       Configure Claude Code
+ *   gramatr-mcp setup claude --dry Run without writing
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// gramatr-allow: C1 — CLI entry point, reads HOME for config path
+const HOME = process.env.HOME || process.env.USERPROFILE || '';
+/**
+ * Resolve the path to the gramatr-mcp binary.
+ * Prefers the compiled dist version, falls back to npx.
+ */
+function resolveBinaryPath() {
+    // Check if we're installed globally or locally
+    const localBin = resolve(__dirname, '../bin/gramatr-mcp.js');
+    if (existsSync(localBin)) {
+        return { command: 'node', args: [localBin] };
+    }
+    // Fallback to npx (slower but always works)
+    return { command: 'npx', args: ['-y', '@gramatr/mcp'] };
+}
+/**
+ * Get the Claude Code config file path.
+ * Claude Code stores global MCP config in ~/.claude.json
+ */
+function getClaudeConfigPath() {
+    return join(HOME, '.claude.json');
+}
+/**
+ * Read existing Claude config or return empty.
+ */
+function readClaudeConfig(configPath) {
+    try {
+        const raw = readFileSync(configPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function setupClaude(dryRun = false) {
+    const configPath = getClaudeConfigPath();
+    const config = readClaudeConfig(configPath);
+    // Build the MCP server entry
+    const { command, args } = resolveBinaryPath();
+    const serverEntry = { command };
+    if (args.length > 0) {
+        serverEntry.args = args;
+    }
+    // Check if already configured
+    const existing = config.mcpServers?.['gramatr'];
+    if (existing) {
+        const existingCmd = existing.command;
+        const existingArgs = existing.args || [];
+        if (existingCmd === command && JSON.stringify(existingArgs) === JSON.stringify(args)) {
+            process.stderr.write('[gramatr-mcp] Claude Code already configured. No changes needed.\n');
+            return;
+        }
+        process.stderr.write('[gramatr-mcp] Updating existing gramatr MCP server config.\n');
+    }
+    // Merge into config
+    if (!config.mcpServers) {
+        config.mcpServers = {};
+    }
+    config.mcpServers['gramatr'] = serverEntry;
+    if (dryRun) {
+        process.stderr.write('[gramatr-mcp] Dry run — would write to: ' + configPath + '\n');
+        process.stderr.write(JSON.stringify(config.mcpServers['gramatr'], null, 2) + '\n');
+        return;
+    }
+    // Write back
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    process.stderr.write(`[gramatr-mcp] Configured Claude Code MCP server in ${configPath}\n`);
+    process.stderr.write('[gramatr-mcp] Restart Claude Code to pick up the change.\n');
+    // Show what was written
+    process.stderr.write('\n  mcpServers.gramatr:\n');
+    process.stderr.write(`    command: ${command}\n`);
+    if (args.length > 0) {
+        process.stderr.write(`    args: ${JSON.stringify(args)}\n`);
+    }
+    process.stderr.write('\n');
+}
+//# sourceMappingURL=setup.js.map

package/dist/bin/setup.js.map

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

package/dist/cache/lru-cache.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Simple in-memory LRU cache for reducing redundant remote round-trips.
+ *
+ * - Keyed by tool name + serialized args
+ * - TTL-based expiration (default 60s)
+ * - Evicts on mutation tools (create, update, delete, batch)
+ * - Max 100 entries, LRU eviction when full
+ * - Dies with the process — no persistence, no disk
+ */
+export declare class LRUCache {
+    private cache;
+    private maxSize;
+    private ttlMs;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(maxSize?: number, ttlMs?: number);
+    /**
+     * Build a cache key from tool name + args.
+     */
+    private key;
+    /**
+     * Check if a tool call is cacheable.
+     */
+    isCacheable(toolName: string): boolean;
+    /**
+     * Check if a tool is a mutation (triggers cache invalidation).
+     */
+    isMutation(toolName: string): boolean;
+    /**
+     * Get a cached result. Returns undefined on miss or expiry.
+     */
+    get(toolName: string, args: Record<string, unknown>): unknown | undefined;
+    /**
+     * Store a result in the cache.
+     */
+    set(toolName: string, args: Record<string, unknown>, value: unknown): void;
+    /**
+     * Clear the entire cache. Called on mutation tool calls.
+     */
+    clear(): void;
+    /**
+     * Get cache statistics for the local status tool.
+     */
+    stats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+        hits: number;
+        misses: number;
+        evictions: number;
+        hitRate: string;
+    };
+}
+/** Singleton cache instance. */
+export declare const cache: LRUCache;
+//# sourceMappingURL=lru-cache.d.ts.map

package/dist/cache/lru-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru-cache.d.ts","sourceRoot":"","sources":["../../src/cache/lru-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+DH,qBAAa,QAAQ;IACnB,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,SAAS,CAAK;gBAEV,OAAO,SAAmB,EAAE,KAAK,SAAiB;IAK9D;;OAEG;IACH,OAAO,CAAC,GAAG;IAIX;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAItC;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIrC;;OAEG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,GAAG,SAAS;IAsBzE;;OAEG;IACH,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAuB1E;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAY5H;AAED,gCAAgC;AAChC,eAAO,MAAM,KAAK,UAAiB,CAAC"}

package/dist/cache/lru-cache.js

@@ -0,0 +1,159 @@
+/**
+ * Simple in-memory LRU cache for reducing redundant remote round-trips.
+ *
+ * - Keyed by tool name + serialized args
+ * - TTL-based expiration (default 60s)
+ * - Evicts on mutation tools (create, update, delete, batch)
+ * - Max 100 entries, LRU eviction when full
+ * - Dies with the process — no persistence, no disk
+ */
+const DEFAULT_MAX_SIZE = 100;
+const DEFAULT_TTL_MS = 60_000; // 60 seconds
+/** Tools that mutate state — any call to these invalidates the entire cache. */
+const MUTATION_TOOLS = new Set([
+    'create_entity',
+    'update_entity',
+    'mark_entity_inactive',
+    'reactivate_entity',
+    'add_observation',
+    'update_observation',
+    'mark_observation_inactive',
+    'create_relation',
+    'batch_create_entities',
+    'batch_add_observations',
+    'batch_create_relations',
+    'bulk_update_metadata',
+    'change_embedding_model',
+    // gramatr_ prefixed mutations
+    'gramatr_save_diary',
+    'gramatr_save_handoff',
+    'gramatr_save_prd',
+    'gramatr_save_reflection',
+    'gramatr_submit_feedback',
+    'gramatr_update_criteria',
+    'gramatr_update_hard_problem',
+    'gramatr_session_start',
+    'gramatr_session_end',
+    'gramatr_batch_save_turns',
+    'gramatr_phase_transition',
+    'gramatr_classification_feedback',
+    'gramatr_generation_feedback',
+    'gramatr_suggestion_feedback',
+    'gramatr_groom_knowledge',
+    'gramatr_maintain_state',
+    'gramatr_compose_agent',
+    'gramatr_create_api_key',
+    'gramatr_revoke_api_key',
+    'gramatr_onboard_user',
+    'gramatr_classifier_manage',
+]);
+/** Tools that should never be cached (real-time or side-effectful). */
+const UNCACHEABLE_TOOLS = new Set([
+    'gramatr_doctor',
+    'gramatr_get_metrics',
+    'gramatr_route_request',
+    'gramatr_execute_intent',
+    'gramatr_summarize_turn',
+    'gramatr_route_skills',
+    'gramatr_invoke_agent',
+    'gramatr_get_enrichment',
+    'gramatr_competitive_position',
+    'aggregate_stats',
+]);
+export class LRUCache {
+    cache = new Map();
+    maxSize;
+    ttlMs;
+    hits = 0;
+    misses = 0;
+    evictions = 0;
+    constructor(maxSize = DEFAULT_MAX_SIZE, ttlMs = DEFAULT_TTL_MS) {
+        this.maxSize = maxSize;
+        this.ttlMs = ttlMs;
+    }
+    /**
+     * Build a cache key from tool name + args.
+     */
+    key(toolName, args) {
+        return `${toolName}:${JSON.stringify(args, Object.keys(args).sort())}`;
+    }
+    /**
+     * Check if a tool call is cacheable.
+     */
+    isCacheable(toolName) {
+        return !MUTATION_TOOLS.has(toolName) && !UNCACHEABLE_TOOLS.has(toolName);
+    }
+    /**
+     * Check if a tool is a mutation (triggers cache invalidation).
+     */
+    isMutation(toolName) {
+        return MUTATION_TOOLS.has(toolName);
+    }
+    /**
+     * Get a cached result. Returns undefined on miss or expiry.
+     */
+    get(toolName, args) {
+        const k = this.key(toolName, args);
+        const entry = this.cache.get(k);
+        if (!entry) {
+            this.misses++;
+            return undefined;
+        }
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(k);
+            this.misses++;
+            return undefined;
+        }
+        // LRU: move to end (most recently used)
+        this.cache.delete(k);
+        this.cache.set(k, entry);
+        this.hits++;
+        return entry.value;
+    }
+    /**
+     * Store a result in the cache.
+     */
+    set(toolName, args, value) {
+        if (!this.isCacheable(toolName))
+            return;
+        const k = this.key(toolName, args);
+        // Delete first to reset position in Map iteration order
+        this.cache.delete(k);
+        // Evict oldest if full
+        while (this.cache.size >= this.maxSize) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined) {
+                this.cache.delete(oldest);
+                this.evictions++;
+            }
+        }
+        this.cache.set(k, {
+            value,
+            expiresAt: Date.now() + this.ttlMs,
+        });
+    }
+    /**
+     * Clear the entire cache. Called on mutation tool calls.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get cache statistics for the local status tool.
+     */
+    stats() {
+        const total = this.hits + this.misses;
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs,
+            hits: this.hits,
+            misses: this.misses,
+            evictions: this.evictions,
+            hitRate: total > 0 ? `${((this.hits / total) * 100).toFixed(1)}%` : '0%',
+        };
+    }
+}
+/** Singleton cache instance. */
+export const cache = new LRUCache();
+//# sourceMappingURL=lru-cache.js.map

package/dist/cache/lru-cache.js.map

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

package/dist/intelligence/packet2-fetcher.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Packet 2 Auto-Fetcher — automatically fetches enrichment when route_request
+ * returns packet_2_status: "pending".
+ *
+ * Flow:
+ *   1. Agent calls gramatr_route_request
+ *   2. Server returns Packet 1 immediately with enrichment_id
+ *   3. This module detects pending status, calls gramatr_get_enrichment
+ *   4. Merges Packet 2 into the response before returning to agent
+ *
+ * The agent never has to manually call gramatr_get_enrichment — it just works.
+ */
+interface ToolCallResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Check if a tool result is a route_request response with pending Packet 2.
+ */
+export declare function hasPendingPacket2(result: ToolCallResult): {
+    pending: boolean;
+    enrichmentId?: string;
+};
+/**
+ * Fetch Packet 2 enrichment and merge into the original response.
+ * Retries up to 3 times with 500ms delay (enrichment may still be generating).
+ */
+export declare function fetchAndMergePacket2(result: ToolCallResult, enrichmentId: string): Promise<ToolCallResult>;
+export {};
+//# sourceMappingURL=packet2-fetcher.d.ts.map

package/dist/intelligence/packet2-fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packet2-fetcher.d.ts","sourceRoot":"","sources":["../../src/intelligence/packet2-fetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,UAAU,cAAc;IACtB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAKD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAarG;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,cAAc,EACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,cAAc,CAAC,CAkCzB"}

package/dist/intelligence/packet2-fetcher.js

@@ -0,0 +1,87 @@
+/**
+ * Packet 2 Auto-Fetcher — automatically fetches enrichment when route_request
+ * returns packet_2_status: "pending".
+ *
+ * Flow:
+ *   1. Agent calls gramatr_route_request
+ *   2. Server returns Packet 1 immediately with enrichment_id
+ *   3. This module detects pending status, calls gramatr_get_enrichment
+ *   4. Merges Packet 2 into the response before returning to agent
+ *
+ * The agent never has to manually call gramatr_get_enrichment — it just works.
+ */
+import { callRemoteTool } from '../proxy/remote-client.js';
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 500;
+/**
+ * Check if a tool result is a route_request response with pending Packet 2.
+ */
+export function hasPendingPacket2(result) {
+    if (!result.content?.[0]?.text)
+        return { pending: false };
+    try {
+        const data = JSON.parse(result.content[0].text);
+        if (data.packet_2_status === 'pending' && data.enrichment_id) {
+            return { pending: true, enrichmentId: data.enrichment_id };
+        }
+    }
+    catch {
+        // Not JSON or not the expected shape
+    }
+    return { pending: false };
+}
+/**
+ * Fetch Packet 2 enrichment and merge into the original response.
+ * Retries up to 3 times with 500ms delay (enrichment may still be generating).
+ */
+export async function fetchAndMergePacket2(result, enrichmentId) {
+    let enrichment = null;
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+            enrichment = await callRemoteTool('gramatr_get_enrichment', {
+                enrichment_id: enrichmentId,
+            });
+            // Check if enrichment is ready
+            const enrichResult = enrichment;
+            if (enrichResult?.content?.[0]?.text) {
+                const enrichData = JSON.parse(enrichResult.content[0].text);
+                if (enrichData.status !== 'pending') {
+                    // Enrichment is ready — merge it
+                    return mergePackets(result, enrichResult);
+                }
+            }
+        }
+        catch {
+            // Enrichment call failed — continue with retries
+        }
+        // Wait before retrying
+        if (attempt < MAX_RETRIES - 1) {
+            await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+        }
+    }
+    // Enrichment not ready after retries — return original Packet 1 as-is
+    // The agent can still work with Packet 1 alone
+    process.stderr.write(`[gramatr-mcp] Packet 2 not ready after ${MAX_RETRIES} retries, returning Packet 1 only\n`);
+    return result;
+}
+/**
+ * Merge Packet 2 enrichment into the Packet 1 response.
+ * Adds enrichment data under a `packet_2` key in the response.
+ */
+function mergePackets(packet1, packet2) {
+    try {
+        const p1Data = JSON.parse(packet1.content[0].text);
+        const p2Data = JSON.parse(packet2.content[0].text);
+        // Merge Packet 2 into Packet 1
+        p1Data.packet_2 = p2Data;
+        p1Data.packet_2_status = 'merged';
+        return {
+            content: [{ type: 'text', text: JSON.stringify(p1Data) }],
+        };
+    }
+    catch {
+        // If merge fails, return Packet 1 unchanged
+        return packet1;
+    }
+}
+//# sourceMappingURL=packet2-fetcher.js.map

package/dist/intelligence/packet2-fetcher.js.map

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

package/dist/intelligence/session-manager.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Session Manager — automatic session lifecycle for the local MCP server.
+ *
+ * - Auto session_start on first proxied tool call
+ * - Auto session_end on process exit (SIGTERM, SIGINT)
+ * - Tracks session ID for correlation
+ * - Tracks tool call count for session metrics
+ */
+/**
+ * Ensure a session is started. Called before the first proxied tool call.
+ * Idempotent — only starts once per process lifetime.
+ */
+export declare function ensureSession(): Promise<void>;
+/**
+ * Get the current session ID (for correlation).
+ */
+export declare function getSessionId(): string | null;
+/**
+ * Get the tool call count for the current session.
+ */
+export declare function getToolCallCount(): number;
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/intelligence/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../src/intelligence/session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH;;;GAGG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CA6CnD;AAuBD;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}