@ory/gemini-cli 0.1.0

package/dist/handlers.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleHookEvent = handleHookEvent;
+const argus_1 = require("@ory/argus");
+/**
+ * Route a Gemini CLI hook event to the appropriate Ory integration.
+ */
+async function handleHookEvent(input, client, deps = {}) {
+    const event = input.hook_event_name;
+    client.logger.debug("hook.received", {
+        event,
+        sessionId: input.session_id,
+        toolName: input.tool_name,
+    });
+    // Set trace context so all spans within this hook invocation correlate
+    client.tracer.setContext({
+        traceId: (0, argus_1.deriveTraceId)(input.session_id),
+        sessionId: input.session_id,
+    });
+    try {
+        switch (event) {
+            case "SessionStart":
+                return await handleSessionStart(input, client, deps);
+            case "SessionEnd":
+                return await handleSessionEnd(input, client);
+            case "BeforeTool":
+                return await handleBeforeTool(input, client);
+            case "AfterTool":
+                return await handleAfterTool(input, client);
+            case "BeforeToolSelection":
+                return await handleBeforeToolSelection(input, client);
+            case "Notification":
+                return await handleNotification(input, client);
+            case "PreCompress":
+                return await handlePreCompress(input, client);
+            default:
+                client.logger.debug("hook.passthrough", { event });
+                client.tracer.record("hook.passthrough", "skipped", {
+                    attributes: { event },
+                });
+                return {};
+        }
+    }
+    finally {
+        client.tracer.clearContext();
+    }
+}
+// ─── SessionStart ───────────────────────────────────────────────────
+async function handleSessionStart(input, client, deps) {
+    client.logger.info("lifecycle.session_start", {
+        sessionId: input.session_id,
+        source: input.source,
+        cwd: input.cwd,
+    });
+    client.tracer.record("session.start", "ok", {
+        attributes: { source: input.source },
+    });
+    const userGate = deps.authGate ?? argus_1.ensureUserAuthenticated;
+    const decision = await userGate(client, {
+        binName: "ory-gemini",
+        harness: "gemini-cli",
+        allowBlock: true,
+    });
+    // Resolve the agent identity (machine credentials). Never blocks;
+    // attaches the agent's bearer token to outgoing Ory API calls.
+    const agentGate = deps.agentGate ?? argus_1.ensureAgentIdentity;
+    await agentGate(client, { projectUrl: (0, argus_1.resolveConfig)().projectUrl, harness: "gemini-cli" });
+    if (!decision.proceed) {
+        return { decision: "deny", reason: decision.reason };
+    }
+    if (decision.mode !== "disabled") {
+        return {};
+    }
+    const resolved = (0, argus_1.resolveConfig)();
+    if (resolved.auditOnly) {
+        client.logger.info("config.audit_only", {
+            message: "Audit-only mode enabled. Auth and permission checks are disabled.",
+        });
+        return {};
+    }
+    if (!resolved.projectUrl) {
+        client.logger.warn("config.not_configured", {
+            message: "Ory plugin is not configured. Auth and permission checks are disabled. " +
+                "Run 'npx ory-gemini configure' to connect to an Ory project.",
+        });
+        return {};
+    }
+    // Try session token first, then OAuth2 token
+    const sessionToken = process.env.ORY_SESSION_TOKEN;
+    const oauth2Token = process.env.ORY_OAUTH2_TOKEN;
+    if (sessionToken) {
+        await verifySessionToken(sessionToken, client);
+        return {};
+    }
+    if (oauth2Token) {
+        await verifyOAuth2Token(oauth2Token, client);
+        return {};
+    }
+    client.logger.warn("session.no_credentials", {
+        message: "Neither ORY_SESSION_TOKEN nor ORY_OAUTH2_TOKEN is set. " +
+            "Skipping authentication.",
+    });
+    return {};
+}
+async function verifySessionToken(token, client) {
+    try {
+        const session = await client.verifySession(token);
+        if (!session.active) {
+            client.logger.warn("session.inactive", {
+                message: "Ory session is not active. Re-authenticate to enable auth checks.",
+            });
+        }
+    }
+    catch (err) {
+        const oryErr = err;
+        client.logger.warn("session.verify_failed", {
+            code: oryErr.code,
+            message: oryErr.message,
+        });
+    }
+}
+async function verifyOAuth2Token(token, client) {
+    try {
+        const tokenInfo = await client.introspectToken(token);
+        if (!tokenInfo.active) {
+            client.logger.warn("oauth2.token_inactive", {
+                message: "Ory OAuth2 token is not active. Obtain a new token to enable auth checks.",
+            });
+            return;
+        }
+        client.logger.info("oauth2.session_authenticated", {
+            clientId: tokenInfo.clientId,
+            subject: tokenInfo.subject,
+            scope: tokenInfo.scope,
+        });
+    }
+    catch (err) {
+        const oryErr = err;
+        client.logger.warn("oauth2.introspect_failed", {
+            code: oryErr.code,
+            message: oryErr.message,
+        });
+    }
+}
+// ─── BeforeTool ────────────────────────────────────────────────────
+async function handleBeforeTool(input, client) {
+    const toolName = input.tool_name ?? "unknown";
+    client.logger.info("lifecycle.before_tool", {
+        sessionId: input.session_id,
+        toolName,
+        toolInput: input.tool_input,
+    });
+    const inputSummary = (0, argus_1.summarizeToolInput)(toolName, input.tool_input);
+    // In audit-only mode, log the invocation but skip permission checks
+    if ((0, argus_1.resolveConfig)().auditOnly) {
+        client.tracer.record("tool.invoke", "ok", {
+            attributes: { toolName, ...inputSummary },
+        });
+        return {};
+    }
+    const subject = (0, argus_1.resolveUserSubject)(client, `session:${input.session_id}`);
+    const subjectId = (0, argus_1.subjectLabel)(subject);
+    const mcpTool = (0, argus_1.parseGeminiMcpTool)(toolName, input.mcp_context);
+    try {
+        if (mcpTool) {
+            const mcpResult = await (0, argus_1.checkMcpPermission)(client, mcpTool, {
+                subject,
+                spanAttributes: { toolName },
+            });
+            if (!mcpResult.allowed) {
+                client.tracer.record("tool.block", "denied", {
+                    attributes: { toolName, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName, ...inputSummary, ...(0, argus_1.alertAttributes)(true) },
+                });
+                return {
+                    decision: "deny",
+                    reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }),
+                    systemMessage: (0, argus_1.formatDenialSummary)({ tool: toolName, subjectId, mcp: mcpTool }),
+                };
+            }
+            client.tracer.record("tool.invoke", "ok", {
+                attributes: { toolName, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName, ...inputSummary },
+            });
+            return {};
+        }
+        const namespace = resolveNamespace();
+        const result = await client.checkPermission({
+            namespace,
+            object: toolName,
+            relation: "use",
+            ...subject,
+        }, { spanAttributes: { toolName } });
+        if (!result.allowed) {
+            client.tracer.record("tool.block", "denied", {
+                attributes: { toolName, ...inputSummary, allowed: result.allowed, ...(0, argus_1.alertAttributes)(true) },
+            });
+            return {
+                decision: "deny",
+                reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }),
+                systemMessage: (0, argus_1.formatDenialSummary)({ tool: toolName, subjectId, namespace }),
+            };
+        }
+        client.tracer.record("tool.invoke", "ok", {
+            attributes: { toolName, ...inputSummary, allowed: result.allowed },
+        });
+        return {};
+    }
+    catch (err) {
+        return handlePermissionError(err, toolName, client);
+    }
+}
+// ─── AfterTool ─────────────────────────────────────────────────────
+async function handleAfterTool(input, client) {
+    const toolName = input.tool_name ?? "unknown";
+    client.logger.info("lifecycle.after_tool", {
+        sessionId: input.session_id,
+        toolName,
+        toolResponse: input.tool_response,
+    });
+    client.tracer.record("tool.complete", "ok", {
+        attributes: {
+            toolName,
+            ...(0, argus_1.summarizeToolInput)(toolName, input.tool_input),
+            ...(0, argus_1.summarizeToolOutput)(toolName, input.tool_response),
+        },
+    });
+    return {};
+}
+// ─── SessionEnd ────────────────────────────────────────────────────
+async function handleSessionEnd(input, client) {
+    client.logger.info("lifecycle.session_end", {
+        sessionId: input.session_id,
+        reason: input.reason,
+    });
+    client.tracer.record("session.end", "ok", {
+        attributes: { reason: input.reason },
+    });
+    return {};
+}
+// ─── BeforeToolSelection ───────────────────────────────────────────
+//
+// Fires after BeforeModel and before tool dispatch with the LLM request
+// payload (containing the candidate tool list). The hook can return
+// `hookSpecificOutput.toolConfig.{ mode, allowedFunctionNames }` to filter
+// the model's tool surface in one shot, collapsing many BeforeTool denials
+// into one upstream check. We currently emit an audit span only — a future
+// enhancement should extract `tools` from `llm_request` and call
+// `client.batchCheckPermissions()` to populate `allowedFunctionNames`.
+async function handleBeforeToolSelection(input, client) {
+    client.logger.info("lifecycle.before_tool_selection", {
+        sessionId: input.session_id,
+    });
+    client.tracer.record("permission.batch_check", "ok", {
+        attributes: { stage: "before_tool_selection" },
+    });
+    return {};
+}
+// ─── Notification ──────────────────────────────────────────────────
+//
+// Fires on tool-permission prompts and other UI notifications. Cannot
+// block; observability only.
+async function handleNotification(input, client) {
+    client.logger.info("lifecycle.notification", {
+        sessionId: input.session_id,
+        notificationType: input.notification_type,
+        message: input.message,
+    });
+    client.tracer.record("notification", "ok", {
+        attributes: {
+            notificationType: input.notification_type,
+            message: input.message,
+        },
+    });
+    return {};
+}
+// ─── PreCompress ───────────────────────────────────────────────────
+async function handlePreCompress(input, client) {
+    client.logger.info("lifecycle.pre_compress", {
+        sessionId: input.session_id,
+        trigger: input.trigger,
+    });
+    client.tracer.record("compaction", "ok", {
+        attributes: { trigger: input.trigger, stage: "pre_compress" },
+    });
+    return {};
+}
+// ─── Helpers ────────────────────────────────────────────────────────
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+}
+function handlePermissionError(oryErr, toolName, client) {
+    if (oryErr.code === "network_error") {
+        client.logger.warn("permission.network_error", {
+            toolName,
+            message: "Ory unreachable, failing open",
+        });
+        return {};
+    }
+    if (oryErr.code === "rate_limited") {
+        client.logger.warn("permission.rate_limited", {
+            toolName,
+            message: "Ory rate limited, failing open",
+        });
+        return {};
+    }
+    // For other errors, also fail open but log prominently
+    client.logger.error("permission.check.error", {
+        toolName,
+        code: oryErr.code,
+        message: oryErr.message,
+    });
+    return {};
+}

package/dist/hook.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Gemini CLI hook entry point.
+ * This script is invoked by Gemini CLI for each hook event.
+ * Input: JSON on stdin
+ * Output: JSON on stdout
+ * Exit code 2 = block the action
+ */
+export {};

package/dist/hook.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Gemini CLI hook entry point.
+ * This script is invoked by Gemini CLI for each hook event.
+ * Input: JSON on stdin
+ * Output: JSON on stdout
+ * Exit code 2 = block the action
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const argus_1 = require("@ory/argus");
+const handlers_js_1 = require("./handlers.js");
+/**
+ * Read all of stdin as a string.
+ *
+ * Uses event listeners instead of `for await` so that we don't depend on the
+ * parent process closing stdin (sending EOF). If no EOF arrives, we resolve
+ * after a short idle gap once data has been received.
+ */
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let resolved = false;
+        function done() {
+            if (!resolved) {
+                resolved = true;
+                resolve(Buffer.concat(chunks).toString("utf-8"));
+            }
+        }
+        process.stdin.on("data", (chunk) => {
+            chunks.push(chunk);
+            clearTimeout(idleTimer);
+            idleTimer = setTimeout(done, 100);
+        });
+        process.stdin.on("end", done);
+        process.stdin.on("error", (err) => {
+            if (!resolved) {
+                resolved = true;
+                reject(err);
+            }
+        });
+        let idleTimer;
+    });
+}
+async function main() {
+    const client = argus_1.OryAgentClient.fromEnv("gemini-cli");
+    const raw = await readStdin();
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        client.logger.error("hook.stdin.parse_failed", { raw: raw.slice(0, 200) });
+        await client.tracer.shutdown();
+        process.exit(0); // Don't block on parse errors
+    }
+    const output = await (0, handlers_js_1.handleHookEvent)(input, client);
+    if (output.decision === "deny" || output.decision === "block") {
+        process.stdout.write(JSON.stringify(output));
+        await client.tracer.shutdown();
+        process.exit(2);
+    }
+    if (output.hookSpecificOutput ||
+        output.systemMessage ||
+        output.decision === "allow") {
+        process.stdout.write(JSON.stringify(output));
+    }
+    await client.tracer.shutdown();
+    process.exit(0);
+}
+main().catch((err) => {
+    process.stderr.write(`[ory-agent] fatal: ${err}\n`);
+    process.exit(0); // Fail open
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { handleHookEvent } from "./handlers.js";
+export { generateSettings } from "./settings.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSettings = exports.handleHookEvent = void 0;
+var handlers_js_1 = require("./handlers.js");
+Object.defineProperty(exports, "handleHookEvent", { enumerable: true, get: function () { return handlers_js_1.handleHookEvent; } });
+var settings_js_1 = require("./settings.js");
+Object.defineProperty(exports, "generateSettings", { enumerable: true, get: function () { return settings_js_1.generateSettings; } });

package/dist/settings.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generate the .gemini/settings.json hooks section that configures Ory hooks.
+ */
+export declare function generateSettings(hookScriptPath: string): object;
+/**
+ * Generate settings assuming the plugin is installed via npm/pnpm.
+ */
+export declare function generateInstalledSettings(): object;
+/**
+ * Generate settings pointing to a local dev build.
+ */
+export declare function generateDevSettings(packageDir: string): object;

package/dist/settings.js

@@ -0,0 +1,66 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSettings = generateSettings;
+exports.generateInstalledSettings = generateInstalledSettings;
+exports.generateDevSettings = generateDevSettings;
+const path = __importStar(require("node:path"));
+const argus_1 = require("@ory/argus");
+/**
+ * Generate the .gemini/settings.json hooks section that configures Ory hooks.
+ */
+function generateSettings(hookScriptPath) {
+    const cmd = `node ${hookScriptPath}`;
+    return {
+        hooks: {
+            SessionStart: (0, argus_1.matcherHookEntry)(cmd),
+            BeforeTool: (0, argus_1.matcherHookEntry)(cmd),
+            AfterTool: (0, argus_1.matcherHookEntry)(cmd),
+        },
+    };
+}
+/**
+ * Generate settings assuming the plugin is installed via npm/pnpm.
+ */
+function generateInstalledSettings() {
+    return generateSettings("ory-gemini-hook");
+}
+/**
+ * Generate settings pointing to a local dev build.
+ */
+function generateDevSettings(packageDir) {
+    const hookPath = path.resolve(packageDir, "dist", "hook.js");
+    return generateSettings(hookPath);
+}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Gemini CLI hook event payload delivered on stdin.
+ *
+ * Gemini CLI invokes hooks as shell commands, passing JSON on stdin
+ * and reading JSON from stdout. Exit code 2 blocks the action.
+ *
+ * Events: SessionStart, SessionEnd, BeforeAgent, AfterAgent,
+ * BeforeModel, BeforeToolSelection, AfterModel, BeforeTool, AfterTool,
+ * Notification, PreCompress.
+ *
+ * See: https://geminicli.com/docs/hooks/reference/
+ */
+export interface GeminiHookInput {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    hook_event_name: string;
+    timestamp?: string;
+    source?: string;
+    reason?: string;
+    prompt?: string;
+    prompt_response?: string;
+    stop_hook_active?: boolean;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    tool_response?: Record<string, unknown>;
+    mcp_context?: Record<string, unknown>;
+    original_request_name?: string;
+    llm_request?: Record<string, unknown>;
+    llm_response?: Record<string, unknown>;
+    notification_type?: string;
+    message?: string;
+    details?: Record<string, unknown>;
+    trigger?: "auto" | "manual";
+}
+/**
+ * Gemini CLI hook output written to stdout.
+ */
+export interface GeminiHookOutput {
+    decision?: "allow" | "deny" | "block";
+    reason?: string;
+    systemMessage?: string;
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    hookSpecificOutput?: GeminiHookSpecificOutput;
+}
+export interface GeminiHookSpecificOutput {
+    /** BeforeTool: override tool arguments */
+    tool_input?: Record<string, unknown>;
+    /** AfterTool: append to tool result */
+    additionalContext?: string;
+    /** AfterTool: chain a follow-up tool call */
+    tailToolCallRequest?: Record<string, unknown>;
+    /** AfterAgent: clear agent context */
+    clearContext?: boolean;
+    /** BeforeModel: synthesize an llm_response and short-circuit the model call */
+    llm_response?: Record<string, unknown>;
+    /** BeforeToolSelection: restrict the tools the model can pick */
+    toolConfig?: {
+        mode?: "AUTO" | "ANY" | "NONE";
+        allowedFunctionNames?: string[];
+    };
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/gemini-extension/GEMINI.md

@@ -0,0 +1,5 @@
+This project has the Ory agent plugin installed. Tool invocations are checked against Ory Permissions (Zanzibar-style) and traced automatically.
+
+If a tool call is blocked, the reason will indicate which permission is missing. The user may need to update their Ory Permissions configuration to grant access.
+
+To check configuration status, the user can run: `npx ory-gemini status`

package/gemini-extension/gemini-extension.json

@@ -0,0 +1,26 @@
+{
+  "name": "ory",
+  "version": "0.1.0",
+  "description": "Ory authentication, authorization, and distributed tracing for Gemini CLI",
+  "contextFileName": "GEMINI.md",
+  "settings": [
+    {
+      "name": "Ory Project URL",
+      "description": "Your Ory project URL (e.g. https://your-project.projects.oryapis.com)",
+      "envVar": "ORY_PROJECT_URL",
+      "sensitive": false
+    },
+    {
+      "name": "Ory API Key",
+      "description": "Your Ory API key (starts with ory_pat_)",
+      "envVar": "ORY_API_KEY",
+      "sensitive": true
+    },
+    {
+      "name": "Session Token",
+      "description": "Session token for agent authentication",
+      "envVar": "ORY_SESSION_TOKEN",
+      "sensitive": true
+    }
+  ]
+}