gramatr 0.3.0

package/core/targets.ts

@@ -0,0 +1,292 @@
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export type IntegrationTargetId =
+  | 'claude-code'
+  | 'claude-desktop'
+  | 'chatgpt-desktop'
+  | 'codex'
+  | 'gemini-cli'
+  | 'remote-mcp'
+  | 'claude-web'
+  | 'chatgpt-web';
+
+export interface IntegrationTarget {
+  id: IntegrationTargetId;
+  label: string;
+  kind: 'local' | 'remote';
+  description: string;
+  detect: () => DetectionResult;
+}
+
+export interface DetectionResult {
+  detected: boolean;
+  location?: string;
+  details?: string;
+}
+
+export interface DetectionContext {
+  exists: (path: string) => boolean;
+  readText: (path: string) => string;
+  home: string;
+}
+
+function defaultContext(): DetectionContext {
+  return {
+    exists: (path) => existsSync(path),
+    readText: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : ''),
+    home: homedir(),
+  };
+}
+
+function homePath(ctx: DetectionContext, ...segments: string[]): string {
+  return join(ctx.home, ...segments);
+}
+
+function detectClaudeCode(ctx: DetectionContext): DetectionResult {
+  const claudeDir = homePath(ctx, '.claude');
+  if (!ctx.exists(claudeDir)) {
+    return { detected: false, details: '~/.claude not found' };
+  }
+
+  const settingsPath = join(claudeDir, 'settings.json');
+  return {
+    detected: true,
+    location: claudeDir,
+    details: ctx.exists(settingsPath) ? settingsPath : 'Claude directory exists',
+  };
+}
+
+function detectCodex(ctx: DetectionContext): DetectionResult {
+  const codexDir = homePath(ctx, '.codex');
+  if (!ctx.exists(codexDir)) {
+    return { detected: false, details: '~/.codex not found' };
+  }
+
+  const hooksPath = join(codexDir, 'hooks.json');
+  const configPath = join(codexDir, 'config.toml');
+  const details = [hooksPath, configPath].filter((path) => ctx.exists(path)).join(', ') || codexDir;
+
+  return {
+    detected: true,
+    location: codexDir,
+    details,
+  };
+}
+
+function detectGeminiCli(ctx: DetectionContext): DetectionResult {
+  const geminiDir = homePath(ctx, '.gemini');
+  if (!ctx.exists(geminiDir)) {
+    return { detected: false, details: '~/.gemini not found' };
+  }
+
+  const settingsPath = join(geminiDir, 'settings.json');
+  const extensionsDir = join(geminiDir, 'extensions');
+  const details = [settingsPath, extensionsDir].filter((path) => ctx.exists(path)).join(', ') || geminiDir;
+
+  return {
+    detected: true,
+    location: geminiDir,
+    details,
+  };
+}
+
+function detectClaudeDesktop(ctx: DetectionContext): DetectionResult {
+  // macOS path — Claude Desktop is only available on macOS and Windows
+  const macConfigPath = join(
+    ctx.home,
+    'Library',
+    'Application Support',
+    'Claude',
+    'claude_desktop_config.json',
+  );
+  // Windows path — APPDATA is typically <home>\AppData\Roaming
+  const winConfigPath = join(ctx.home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+
+  if (ctx.exists(macConfigPath)) {
+    return {
+      detected: true,
+      location: macConfigPath,
+      details: 'Claude Desktop config found (macOS)',
+    };
+  }
+
+  if (ctx.exists(winConfigPath)) {
+    return {
+      detected: true,
+      location: winConfigPath,
+      details: 'Claude Desktop config found (Windows)',
+    };
+  }
+
+  return {
+    detected: false,
+    details: 'Claude Desktop config not found',
+  };
+}
+
+function detectChatGPTDesktop(ctx: DetectionContext): DetectionResult {
+  // macOS path — ChatGPT Desktop uses ~/.chatgpt/mcp.json
+  const macConfigDir = join(ctx.home, '.chatgpt');
+  const macConfigPath = join(macConfigDir, 'mcp.json');
+
+  // Windows path — APPDATA is typically <home>\AppData\Roaming
+  const winConfigDir = join(ctx.home, 'AppData', 'Roaming', 'ChatGPT');
+  const winConfigPath = join(winConfigDir, 'mcp.json');
+
+  if (ctx.exists(macConfigPath)) {
+    return {
+      detected: true,
+      location: macConfigPath,
+      details: 'ChatGPT Desktop config found (macOS)',
+    };
+  }
+
+  if (ctx.exists(macConfigDir)) {
+    return {
+      detected: true,
+      location: macConfigDir,
+      details: 'ChatGPT Desktop directory found (macOS, no mcp.json yet)',
+    };
+  }
+
+  if (ctx.exists(winConfigPath)) {
+    return {
+      detected: true,
+      location: winConfigPath,
+      details: 'ChatGPT Desktop config found (Windows)',
+    };
+  }
+
+  if (ctx.exists(winConfigDir)) {
+    return {
+      detected: true,
+      location: winConfigDir,
+      details: 'ChatGPT Desktop directory found (Windows, no mcp.json yet)',
+    };
+  }
+
+  return {
+    detected: false,
+    details: 'ChatGPT Desktop config not found',
+  };
+}
+
+function detectRemoteTarget(
+  kind: 'claude-web' | 'chatgpt-web' | 'remote-mcp',
+  ctx: DetectionContext,
+): DetectionResult {
+  const claudeJson = ctx.readText(homePath(ctx, '.claude.json'));
+  if (claudeJson.includes('gramatr') || claudeJson.includes('mcpServers')) {
+    return {
+      detected: true,
+      location: homePath(ctx, '.claude.json'),
+      details: 'Remote MCP-capable configuration file found',
+    };
+  }
+
+  return {
+    detected: false,
+    details:
+      kind === 'remote-mcp'
+        ? 'Remote MCP setup is available but not configured locally'
+        : `${kind} is a hosted target and requires remote MCP setup`,
+  };
+}
+
+export const INTEGRATION_TARGETS: IntegrationTarget[] = [
+  {
+    id: 'claude-code',
+    label: 'Claude Code',
+    kind: 'local',
+    description: 'Local Claude Code hook integration',
+    detect: () => detectClaudeCode(defaultContext()),
+  },
+  {
+    id: 'claude-desktop',
+    label: 'Claude Desktop',
+    kind: 'local',
+    description: 'Claude Desktop app with MCP server support (Tier 3 — MCP only, no hooks)',
+    detect: () => detectClaudeDesktop(defaultContext()),
+  },
+  {
+    id: 'chatgpt-desktop',
+    label: 'ChatGPT Desktop',
+    kind: 'local',
+    description: 'ChatGPT Desktop app with MCP server support (Tier 3 — MCP only, no hooks)',
+    detect: () => detectChatGPTDesktop(defaultContext()),
+  },
+  {
+    id: 'codex',
+    label: 'Codex',
+    kind: 'local',
+    description: 'Local Codex hook integration',
+    detect: () => detectCodex(defaultContext()),
+  },
+  {
+    id: 'gemini-cli',
+    label: 'Gemini CLI',
+    kind: 'local',
+    description: 'Local Gemini CLI extension integration',
+    detect: () => detectGeminiCli(defaultContext()),
+  },
+  {
+    id: 'remote-mcp',
+    label: 'Remote MCP',
+    kind: 'remote',
+    description: 'Shared remote MCP setup for hosted integrations',
+    detect: () => detectRemoteTarget('remote-mcp', defaultContext()),
+  },
+  {
+    id: 'claude-web',
+    label: 'Claude Web',
+    kind: 'remote',
+    description: 'Claude.ai web connector via remote MCP (Settings > Connectors)',
+    detect: () => detectRemoteTarget('claude-web', defaultContext()),
+  },
+  {
+    id: 'chatgpt-web',
+    label: 'ChatGPT Web',
+    kind: 'remote',
+    description: 'Hosted ChatGPT target via remote MCP',
+    detect: () => detectRemoteTarget('chatgpt-web', defaultContext()),
+  },
+];
+
+export function listTargets(): IntegrationTarget[] {
+  return INTEGRATION_TARGETS;
+}
+
+export function findTarget(id: string): IntegrationTarget | undefined {
+  return INTEGRATION_TARGETS.find((target) => target.id === id);
+}
+
+export function detectTargets(): Array<IntegrationTarget & { detection: DetectionResult }> {
+  return detectTargetsWithContext(defaultContext());
+}
+
+export function detectTargetsWithContext(
+  ctx: DetectionContext,
+): Array<IntegrationTarget & { detection: DetectionResult }> {
+  const detectors: Record<string, (ctx: DetectionContext) => DetectionResult> = {
+    'claude-code': detectClaudeCode,
+    'claude-desktop': detectClaudeDesktop,
+    'chatgpt-desktop': detectChatGPTDesktop,
+    codex: detectCodex,
+    'gemini-cli': detectGeminiCli,
+  };
+
+  return INTEGRATION_TARGETS.map((target) => ({
+    ...target,
+    detection: detectors[target.id]
+      ? detectors[target.id](ctx)
+      : detectRemoteTarget(target.id, ctx),
+  }));
+}
+
+export function summarizeDetectedLocalTargets(): IntegrationTargetId[] {
+  return detectTargets()
+    .filter((target) => target.kind === 'local' && target.detection.detected)
+    .map((target) => target.id);
+}

package/core/types.ts

@@ -0,0 +1,178 @@
+export interface RouteClassification {
+  effort_level?: string;
+  intent_type?: string;
+  confidence?: number;
+  memory_tier?: string;
+  matched_skills?: string[];
+  constraints_extracted?: string[];
+  reverse_engineering?: {
+    explicit_wants?: string[];
+    implicit_wants?: string[];
+    explicit_dont_wants?: string[];
+    implicit_dont_wants?: string[];
+    gotchas?: string[];
+  };
+  suggested_capabilities?: string[];
+  isc_scaffold?: string[];
+  is_fallback?: boolean;
+}
+
+export interface CapabilityAuditEntry {
+  id?: number;
+  name?: string;
+  section?: string;
+  disposition?: string;
+  reason?: string;
+  phase?: string;
+}
+
+export interface CapabilityAuditResult {
+  entries?: CapabilityAuditEntry[];
+  use_count?: number;
+  decline_count?: number;
+  na_count?: number;
+  formatted_summary?: string;
+}
+
+export interface PhaseTemplate {
+  header?: string;
+  time_check?: string;
+  voice_message?: string;
+  phase_description?: string;
+}
+
+export interface QualityGateRule {
+  id?: string;
+  name?: string;
+  description?: string;
+  min_effort?: string | null;
+  automated?: boolean;
+}
+
+export interface QualityGateConfig {
+  rules?: QualityGateRule[];
+  min_criteria?: number;
+  anti_required?: boolean;
+  word_range?: { min?: number; max?: number };
+}
+
+export interface ContextPreLoadPlan {
+  entity_types?: string[];
+  fetch_limits?: Record<string, number>;
+  tier?: string;
+}
+
+export interface RouteResponse {
+  classification?: RouteClassification;
+  capability_audit?: CapabilityAuditResult;
+  phase_template?: PhaseTemplate;
+  quality_gate_config?: QualityGateConfig;
+  context_pre_load_plan?: ContextPreLoadPlan;
+  project_state?: {
+    project_id?: string;
+    active_prd_id?: string | null;
+    active_prd_title?: string | null;
+    isc_summary?: { total?: number; passing?: number; failing?: number; pending?: number };
+    current_phase?: string | null;
+    active_client?: { client_id?: string; client_type?: string } | null;
+    last_updated?: string;
+    session_history_summary?: string;
+  } | null;
+  packet_diagnostics?: {
+    memory_context?: {
+      status?: string;
+      requested_types?: string[];
+      delivered_count?: number;
+      error?: string;
+    };
+    project_state?: {
+      status?: string;
+      project_id?: string;
+      error?: string;
+    };
+  };
+  curated_context?: string;
+  context_references?: Array<{
+    id?: string;
+    type?: string;
+    name?: string;
+  }> | string[];
+  behavioral_directives?: string[];
+  suggested_agents?: Array<{
+    display_name?: string;
+    model?: string;
+    reason?: string;
+  }>;
+  composed_agents?: Array<{
+    name?: string;
+    display_name?: string;
+    system_prompt?: string;
+    expertise_areas?: string[];
+    task_domain?: string;
+    model_preference?: string;
+    context_summary?: string;
+  }>;
+  memory_context?: {
+    total_count?: number;
+    results?: Array<{
+      entity_name?: string;
+      entity_type?: string;
+      content?: string;
+      similarity?: number;
+    }>;
+  };
+  token_savings?: {
+    claude_md_reduction?: number;
+    observe_work_offloaded?: number;
+    reasoning_tokens_used?: number;
+    total_saved?: number;
+    tokens_saved?: number;
+    savings_ratio?: number;
+  };
+  execution_summary?: {
+    qwen_model?: string;
+    qwen_time_ms?: number;
+    execution_time_ms?: number;
+    server_version?: string;
+    stage_timing?: Record<string, number>;
+    degraded_components?: string[];
+  };
+}
+
+export interface SessionStartResponse {
+  project_id?: string;
+  interaction_id?: string;
+  entity_id?: string;
+}
+
+export interface HandoffMeta {
+  saved_at?: string;
+  branch?: string;
+  session_id?: string;
+  conversation_id?: string;
+  platform?: string;
+  legacy_missing_platform?: boolean;
+}
+
+export interface HandoffResponse {
+  status?: string;
+  source?: string;
+  project_id?: string;
+  session_id?: string;
+  branch?: string;
+  platform?: string;
+  created_at?: string;
+  section_count?: number;
+  _meta?: HandoffMeta;
+  where_we_are?: string;
+  what_shipped?: string;
+  whats_next?: string;
+  key_context?: string;
+  dont_forget?: string;
+}
+
+export interface HookFailure {
+  title: string;
+  detail: string;
+  action?: string;
+}

package/core/version.ts

@@ -0,0 +1,2 @@
+/** Auto-generated by version-sync.ts — do not edit */
+export const VERSION = '0.3.0';

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 @aios-v2/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();