@gramatr/client 0.5.1

package/desktop/lib/desktop-install-utils.ts

@@ -0,0 +1,70 @@
+import { join } from 'path';
+
+const DEFAULT_MCP_URL = 'https://mcp.gramatr.com/mcp';
+
+export interface DesktopMcpServerEntry {
+  gramatr: {
+    url: string;
+    headers: {
+      Authorization: string;
+    };
+  };
+}
+
+export interface DesktopConfig {
+  mcpServers?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Returns the Claude Desktop config file path for the given platform.
+ *
+ * macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+ * Windows: %APPDATA%\Claude\claude_desktop_config.json (APPDATA = <home>\AppData\Roaming)
+ */
+export function getDesktopConfigPath(
+  home: string,
+  platform: string = process.platform,
+): string {
+  if (platform === 'win32') {
+    return join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+  }
+
+  // macOS (darwin) and fallback for other platforms
+  return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+}
+
+/**
+ * Build the mcpServers.gramatr entry for Claude Desktop config.
+ * Uses StreamableHTTP transport — Claude Desktop connects directly to the remote URL.
+ */
+export function buildMcpServerEntry(
+  apiKey: string,
+  serverUrl: string = DEFAULT_MCP_URL,
+): DesktopMcpServerEntry {
+  return {
+    gramatr: {
+      url: serverUrl,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+      },
+    },
+  };
+}
+
+/**
+ * Safely merge a gramatr MCP server entry into an existing Claude Desktop config.
+ * Preserves all other mcpServers and top-level config keys.
+ */
+export function mergeDesktopConfig(
+  existing: DesktopConfig,
+  gramatrEntry: DesktopMcpServerEntry,
+): DesktopConfig {
+  return {
+    ...existing,
+    mcpServers: {
+      ...(existing.mcpServers || {}),
+      ...gramatrEntry,
+    },
+  };
+}

package/gemini/README.md

@@ -0,0 +1,95 @@
+# Gemini CLI Integration
+
+This directory contains the Gemini CLI platform shim for gramatr.
+
+gramatr is an intelligent AI middleware that pre-classifies every request using a local model before expensive LLMs process them, saving tokens on every interaction. It provides persistent vector-indexed memory, decision routing, pattern learning, and predictive suggestions across sessions and platforms.
+
+## Architecture
+
+The Gemini CLI integration follows the same platform shim pattern as the Codex integration:
+
+```
+gemini/
+  install.ts                    -- installer: copies runtime to ~/.gemini/extensions/gramatr/
+  hooks/
+    session-start.ts            -- SessionStart: loads session context + handoff
+    user-prompt-submit.ts       -- BeforeAgent: routes prompts through gramatr intelligence
+    stop.ts                     -- SessionEnd: submits classification feedback
+  lib/
+    gemini-hook-utils.ts        -- Gemini-specific output formatting (GeminiHookOutput envelope)
+    gemini-install-utils.ts     -- manifest builder, hooks.json builder, install helpers
+  README.md
+```
+
+Hooks are thin adapters that call shared core functions from `core/routing.ts`, `core/session.ts`, and `core/formatting.ts`. Platform-specific concerns (output envelope format) live in `lib/gemini-hook-utils.ts`.
+
+## How It Works
+
+Gemini CLI supports extensions via `~/.gemini/extensions/<name>/`. Each extension has a `gemini-extension.json` manifest that can define MCP servers, hooks, settings, and custom commands.
+
+The gramatr extension:
+1. Registers the gramatr MCP server (Streamable HTTP at `api.gramatr.com/mcp`)
+2. Hooks into `SessionStart` to load project context and handoff state
+3. Hooks into `BeforeAgent` to route every prompt through gramatr intelligence (effort classification, capability audit, ISC scaffold, memory pre-load)
+4. Hooks into `SessionEnd` to submit classification feedback for the learning flywheel
+5. Declares `GRAMATR_API_KEY` as a sensitive setting (stored in system keychain by Gemini CLI)
+
+## Installation
+
+### Option A: From the monorepo
+
+```bash
+pnpm --filter @gramatr/client install-gemini
+```
+
+### Option B: Direct
+
+```bash
+cd packages/client && bun gemini/install.ts
+```
+
+### Option C: Manual (advanced)
+
+Copy the extension to the Gemini extensions directory and configure auth:
+
+```bash
+mkdir -p ~/.gemini/extensions/gramatr
+cp -r packages/client/gemini/* ~/.gemini/extensions/gramatr/
+echo "GRAMATR_API_KEY=your-key-here" > ~/.gemini/extensions/gramatr/.env
+```
+
+## Authentication
+
+gramatr requires a Bearer token for all MCP calls. The installer handles this by:
+
+1. Checking `~/.gmtr.json` for an existing token (shared with Claude Code / Codex)
+2. Checking the `GRAMATR_API_KEY` environment variable
+3. Prompting for a token interactively
+
+To authenticate before installing, run:
+
+```bash
+bun packages/client/bin/gmtr-login.ts
+```
+
+This stores the token in `~/.gmtr.json`, which the installer reads automatically.
+
+API keys start with `gmtr_sk_` and can be created at [gramatr.com](https://gramatr.com) or via the `gmtr_create_api_key` MCP tool.
+
+## Hook Event Mapping
+
+| Gemini CLI Event | gramatr Hook | Purpose |
+|------------------|-------------|---------|
+| `SessionStart` | `session-start.ts` | Register session, load handoff context |
+| `BeforeAgent` | `user-prompt-submit.ts` | Pre-classify prompt, inject intelligence packet |
+| `SessionEnd` | `stop.ts` | Submit classification feedback |
+
+## Verifying the Installation
+
+After installing and restarting Gemini CLI:
+
+```
+> @gramatr search for recent learning signals
+```
+
+If the MCP server responds, the extension is working. If you see auth errors, re-run the installer or check `~/.gmtr.json`.

package/gemini/hooks/session-start.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import {
+  getGitContext,
+  readHookInput,
+} from '../../hooks/lib/gmtr-hook-utils.ts';
+import {
+  loadProjectHandoff,
+  normalizeSessionStartResponse,
+  persistSessionRegistration,
+  prepareProjectSessionState,
+  startRemoteSession,
+} from '../../core/session.ts';
+import {
+  buildGeminiHookOutput,
+  buildSessionStartAdditionalContext,
+  type HandoffResponse,
+  type SessionStartResponse,
+} from '../lib/gemini-hook-utils.ts';
+
+async function main(): Promise<void> {
+  try {
+    const input = await readHookInput();
+    const git = getGitContext();
+    if (!git) return;
+
+    const transcriptPath = input.transcript_path || '';
+    const sessionId = input.session_id || 'unknown';
+    const prepared = prepareProjectSessionState({
+      git,
+      sessionId,
+      transcriptPath,
+    });
+
+    const sessionStart = (await startRemoteSession({
+      clientType: 'gemini-cli',
+      sessionId: input.session_id,
+      projectId: prepared.projectId,
+      projectName: git.projectName,
+      gitRemote: git.remote,
+      directory: git.root,
+    })) as SessionStartResponse | null;
+
+    if (sessionStart) {
+      persistSessionRegistration(git.root, sessionStart);
+    }
+
+    const handoff = (await loadProjectHandoff(prepared.projectId)) as HandoffResponse | null;
+    const normalizedSessionStart = sessionStart
+      ? {
+          ...sessionStart,
+          interaction_id: normalizeSessionStartResponse(sessionStart).interactionId || undefined,
+        }
+      : null;
+
+    const additionalContext = buildSessionStartAdditionalContext(
+      prepared.projectId,
+      normalizedSessionStart,
+      handoff,
+    );
+    const output = buildGeminiHookOutput(
+      additionalContext,
+      'gramatr session context loaded',
+    );
+
+    process.stdout.write(JSON.stringify(output));
+  } catch {
+    // Never block startup if the hook fails.
+  }
+}
+
+void main();

package/gemini/hooks/stop.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import {
+  getGitContext,
+  readHookInput,
+} from '../../hooks/lib/gmtr-hook-utils.ts';
+import { submitPendingClassificationFeedback } from '../../hooks/lib/classification-feedback.ts';
+
+async function main(): Promise<void> {
+  try {
+    const input = await readHookInput();
+    if (!input.session_id) return;
+
+    const git = getGitContext();
+    if (!git) return;
+
+    await submitPendingClassificationFeedback({
+      rootDir: git.root,
+      sessionId: input.session_id,
+      originalPrompt: '',
+      clientType: 'gemini-cli',
+      agentName: 'Gemini CLI',
+      downstreamProvider: 'google',
+    });
+  } catch {
+    // Never block completion if the hook fails.
+  }
+}
+
+void main();

package/gemini/hooks/user-prompt-submit.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+import {
+  deriveProjectId,
+  getGitContext,
+  readHookInput,
+} from '../../hooks/lib/gmtr-hook-utils.ts';
+import {
+  describeRoutingFailure,
+  persistClassificationResult,
+  routePrompt,
+  shouldSkipPromptRouting,
+} from '../../core/routing.ts';
+import {
+  buildHookFailureAdditionalContext,
+  buildGeminiHookOutput,
+  buildUserPromptAdditionalContext,
+  type RouteResponse,
+} from '../lib/gemini-hook-utils.ts';
+
+async function main(): Promise<void> {
+  try {
+    const input = await readHookInput();
+    const prompt = (input.prompt || input.message || '').trim();
+
+    if (shouldSkipPromptRouting(prompt)) {
+      return;
+    }
+
+    const git = getGitContext();
+    const projectId = git ? deriveProjectId(git.remote, git.projectName) : undefined;
+    const result = await routePrompt({
+      prompt,
+      projectId,
+      sessionId: input.session_id,
+      timeoutMs: 15000,
+      // #496 Phase 3: ask the server for a composed [GMTR Status] block.
+      includeStatusline: true,
+      statuslineSize: 'small',
+    });
+    const route = result.route as RouteResponse | null;
+
+    if (!route) {
+      if (result.error) {
+        const failure = describeRoutingFailure(result.error);
+        const output = buildGeminiHookOutput(
+          buildHookFailureAdditionalContext(failure),
+          'gramatr request routing unavailable',
+        );
+        process.stdout.write(JSON.stringify(output));
+      }
+      return;
+    }
+
+    const additionalContext = buildUserPromptAdditionalContext(route);
+    if (git) {
+      persistClassificationResult({
+        rootDir: git.root,
+        prompt,
+        route,
+        downstreamModel: null,
+        clientType: 'gemini-cli',
+        agentName: 'Gemini CLI',
+      });
+    }
+    const output = buildGeminiHookOutput(
+      additionalContext,
+      'gramatr request routing active',
+    );
+
+    process.stdout.write(JSON.stringify(output));
+  } catch {
+    // Never block the user prompt if the hook fails.
+  }
+}
+
+void main();

package/gemini/install.ts

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  buildExtensionManifest,
+  buildGeminiHooksFile,
+  getGramatrExtensionDir,
+  readStoredApiKey,
+} from './lib/gemini-install-utils.ts';
+
+function log(message: string): void {
+  process.stdout.write(`${message}\n`);
+}
+
+function ensureDir(path: string): void {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true });
+}
+
+function copyRecursive(source: string, target: string): void {
+  const stats = statSync(source);
+
+  if (stats.isDirectory()) {
+    ensureDir(target);
+    for (const entry of readdirSync(source)) {
+      copyRecursive(join(source, entry), join(target, entry));
+    }
+    return;
+  }
+
+  ensureDir(dirname(target));
+  copyFileSync(source, target);
+}
+
+async function promptForApiKey(): Promise<string | null> {
+  log('');
+  log('  gramatr requires authentication.');
+  log('  Options:');
+  log('    1. Run `bun gmtr-login.ts` first to authenticate via browser');
+  log('    2. Paste an API key below (starts with gmtr_sk_)');
+  log('');
+  process.stdout.write('  API Key (enter to skip): ');
+
+  const { createInterface } = await import('readline');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const key = await new Promise<string>((resolve) => {
+    rl.on('line', (line: string) => { rl.close(); resolve(line.trim()); });
+  });
+  return key || null;
+}
+
+async function testApiKey(key: string): Promise<boolean> {
+  try {
+    const res = await fetch('https://api.gramatr.com/mcp', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+        Authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: { name: 'aggregate_stats', arguments: {} },
+      }),
+      signal: AbortSignal.timeout(10000),
+    });
+
+    const text = await res.text();
+    if (
+      text.includes('JWT token is required') ||
+      text.includes('signature validation failed') ||
+      text.includes('Unauthorized')
+    ) {
+      return false;
+    }
+
+    for (const line of text.split('\n')) {
+      if (line.startsWith('data: ')) {
+        try {
+          const d = JSON.parse(line.slice(6));
+          if (d?.result?.content?.[0]?.text && !d?.result?.isError) {
+            return true;
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveApiKey(home: string): Promise<string | null> {
+  // 1. Check if already stored in ~/.gmtr.json (shared with other platforms)
+  const stored = readStoredApiKey(home);
+  if (stored) {
+    log(`  Found existing token in ~/.gmtr.json`);
+    log('  Testing token...');
+    const valid = await testApiKey(stored);
+    if (valid) {
+      log('  OK Token is valid');
+      return stored;
+    }
+    log('  Token is invalid or expired. Please provide a new one.');
+  }
+
+  // 2. Check env var
+  const envKey = process.env.GRAMATR_API_KEY;
+  if (envKey) {
+    log('  Found GRAMATR_API_KEY in environment');
+    log('  Testing token...');
+    const valid = await testApiKey(envKey);
+    if (valid) {
+      log('  OK Token is valid');
+      return envKey;
+    }
+    log('  Environment token is invalid.');
+  }
+
+  // 3. Prompt (skip in non-interactive mode)
+  const nonInteractive = process.argv.includes('--yes') || process.argv.includes('-y') || !process.stdin.isTTY;
+  if (nonInteractive) {
+    log('  Non-interactive: no token found. Run gmtr-login after install.');
+    return null;
+  }
+  const prompted = await promptForApiKey();
+  if (prompted) {
+    log('  Testing token...');
+    const valid = await testApiKey(prompted);
+    if (valid) {
+      log('  OK Token is valid');
+      // Save to ~/.gmtr.json for cross-platform reuse
+      const configPath = join(home, '.gmtr.json');
+      let config: Record<string, unknown> = {};
+      if (existsSync(configPath)) {
+        try {
+          config = JSON.parse(readFileSync(configPath, 'utf8'));
+        } catch {
+          // start fresh
+        }
+      }
+      config.token = prompted;
+      config.token_type =
+        prompted.startsWith('gmtr_sk_') || prompted.startsWith('aios_sk_')
+          ? 'api_key'
+          : 'oauth';
+      config.authenticated_at = new Date().toISOString();
+      writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+      log('  OK Saved to ~/.gmtr.json');
+      return prompted;
+    }
+    log('  Token rejected by server.');
+  }
+
+  return null;
+}
+
+export async function main(): Promise<void> {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (!home) {
+    throw new Error('HOME is not set');
+  }
+
+  log('');
+  log('  gramatr Gemini CLI extension installer');
+  log('  ======================================');
+
+  // ── Resolve authentication ──
+  const apiKey = await resolveApiKey(home);
+  if (!apiKey) {
+    log('');
+    log('  WARNING: No valid API key configured.');
+    log('  The extension will be installed but MCP calls will fail without auth.');
+    log('  Run `bun gmtr-login.ts` to authenticate, then reinstall.');
+    log('');
+  }
+
+  // ── Determine paths ──
+  const currentFile = fileURLToPath(import.meta.url);
+  const geminiSourceDir = dirname(currentFile);
+  const clientSourceDir = dirname(geminiSourceDir);
+  const extensionDir = getGramatrExtensionDir(home);
+  const sharedHookUtilsSource = join(clientSourceDir, 'hooks', 'lib', 'gmtr-hook-utils.ts');
+  const sharedFeedbackSource = join(clientSourceDir, 'hooks', 'lib', 'classification-feedback.ts');
+  const sharedTranscriptSource = join(clientSourceDir, 'hooks', 'lib', 'transcript-parser.ts');
+  const sharedIdentitySource = join(clientSourceDir, 'hooks', 'lib', 'identity.ts');
+  const coreDir = join(clientSourceDir, 'core');
+
+  // ── Create extension directory ──
+  ensureDir(extensionDir);
+  ensureDir(join(extensionDir, 'hooks'));
+  ensureDir(join(extensionDir, 'hooks', 'lib'));
+  ensureDir(join(extensionDir, 'core'));
+
+  // ── Copy hook files ──
+  copyRecursive(join(geminiSourceDir, 'hooks'), join(extensionDir, 'hooks'));
+  copyRecursive(join(geminiSourceDir, 'lib'), join(extensionDir, 'lib'));
+  log('  OK Copied Gemini hook scripts');
+
+  // ── Copy shared dependencies ──
+  for (const sharedFile of [sharedHookUtilsSource, sharedFeedbackSource, sharedTranscriptSource, sharedIdentitySource]) {
+    if (existsSync(sharedFile)) {
+      const relativeDest = sharedFile.replace(clientSourceDir, '');
+      copyFileSync(sharedFile, join(extensionDir, relativeDest));
+    }
+  }
+
+  // Copy core shared modules
+  if (existsSync(coreDir)) {
+    for (const file of readdirSync(coreDir)) {
+      if (file.endsWith('.ts') && !file.endsWith('.test.ts')) {
+        copyFileSync(join(coreDir, file), join(extensionDir, 'core', file));
+      }
+    }
+  }
+  log('  OK Copied shared core and hook utilities');
+
+  // ── Write extension manifest ──
+  const manifest = buildExtensionManifest();
+  writeFileSync(
+    join(extensionDir, 'gemini-extension.json'),
+    JSON.stringify(manifest, null, 2) + '\n',
+  );
+  log('  OK Wrote gemini-extension.json manifest');
+
+  // ── Write hooks.json ──
+  const hooksFile = buildGeminiHooksFile();
+  writeFileSync(
+    join(extensionDir, 'hooks', 'hooks.json'),
+    JSON.stringify(hooksFile, null, 2) + '\n',
+  );
+  log('  OK Wrote hooks/hooks.json');
+
+  // ── Store token in ~/.gmtr.json (canonical source, not in extension dir) ──
+  if (apiKey) {
+    const gmtrJsonPath = join(home, '.gmtr.json');
+    let gmtrConfig: Record<string, unknown> = {};
+    if (existsSync(gmtrJsonPath)) {
+      try { gmtrConfig = JSON.parse(readFileSync(gmtrJsonPath, 'utf8')); } catch {}
+    }
+    gmtrConfig.token = apiKey;
+    gmtrConfig.token_updated_at = new Date().toISOString();
+    writeFileSync(gmtrJsonPath, JSON.stringify(gmtrConfig, null, 2) + '\n');
+    log('  OK Token stored in ~/.gmtr.json (hooks read from here at runtime)');
+  }
+
+  // ── Summary ──
+  log('');
+  log(`  Extension installed to: ${extensionDir}`);
+  log('');
+  log('  What was installed:');
+  log('    - gemini-extension.json  (MCP server + settings manifest)');
+  log('    - hooks/hooks.json       (SessionStart, BeforeAgent, SessionEnd)');
+  log('    - hooks/*.ts             (gramatr hook implementations)');
+  log('    - core/*.ts              (shared routing/session/formatting logic)');
+  if (apiKey) {
+    log('    - .env                   (authenticated API key)');
+  }
+  log('');
+  log('  Restart Gemini CLI to load the extension.');
+  log('');
+}
+
+// Run directly when executed as a script
+const isDirectRun = typeof require !== 'undefined'
+  ? require.main === module
+  : !import.meta.url.includes('node_modules/gramatr/bin/');
+if (isDirectRun) main();

package/gemini/lib/gemini-hook-utils.ts

@@ -0,0 +1,63 @@
+import {
+  buildHookFailureAdditionalContext,
+  buildSessionStartAdditionalContext,
+  buildUserPromptAdditionalContext,
+} from '../../core/formatting.ts';
+import type {
+  HandoffResponse,
+  HookFailure,
+  RouteResponse,
+  SessionStartResponse,
+} from '../../core/types.ts';
+
+export type {
+  HandoffResponse,
+  HookFailure,
+  RouteResponse,
+  SessionStartResponse,
+};
+
+/**
+ * Gemini CLI hook output envelope.
+ *
+ * Gemini hooks return JSON on stdout with these fields:
+ *   continue    — whether to proceed with the agent loop
+ *   decision    — "allow" | "deny" | "block" (for gating hooks)
+ *   systemMessage — displayed in the terminal
+ *   hookSpecificOutput.additionalContext — injected into the LLM context
+ *
+ * See: https://github.com/google-gemini/gemini-cli/blob/main/docs/hooks/reference.md
+ */
+export interface GeminiHookOutput {
+  continue: boolean;
+  decision?: 'allow' | 'deny';
+  hookSpecificOutput?: {
+    additionalContext?: string;
+  };
+  systemMessage?: string;
+  suppressOutput?: boolean;
+}
+
+export {
+  buildHookFailureAdditionalContext,
+  buildSessionStartAdditionalContext,
+  buildUserPromptAdditionalContext,
+};
+
+export function buildGeminiHookOutput(
+  additionalContext: string,
+  systemMessage?: string,
+): GeminiHookOutput {
+  return {
+    continue: true,
+    ...(additionalContext
+      ? {
+          hookSpecificOutput: {
+            additionalContext,
+          },
+        }
+      : {}),
+    ...(systemMessage ? { systemMessage } : {}),
+    suppressOutput: true,
+  };
+}