@ory/amp 0.10.0

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractToolName = exports.decideToolPermission = exports.createOryPlugin = void 0;
+const plugin_js_1 = require("./plugin.js");
+Object.defineProperty(exports, "createOryPlugin", { enumerable: true, get: function () { return plugin_js_1.createOryPlugin; } });
+// Re-export the delegate decision logic for programmatic use / testing.
+var permission_js_1 = require("./permission.js");
+Object.defineProperty(exports, "decideToolPermission", { enumerable: true, get: function () { return permission_js_1.decideToolPermission; } });
+Object.defineProperty(exports, "extractToolName", { enumerable: true, get: function () { return permission_js_1.extractToolName; } });
+// Amp loads in-process plugins via import() and expects a default-exported
+// plugin function `(api) => void`. CJS output (module: nodenext → CJS)
+// surfaces `module.exports` as the ESM `default`, so a single default
+// export is what Amp's loader receives. Instantiate the plugin from env.
+// eslint-disable-next-line import/no-default-export
+exports.default = (0, plugin_js_1.createOryPlugin)();

package/dist/permission.d.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Amp permission delegate helper (PRIMARY blocking gate).
+ *
+ * Amp's `amp.permissions` config can route a tool to
+ * `{ action: "delegate", to: "ory-amp-permission" }`. Amp then runs this
+ * program as a subprocess for each matching tool call, passing the tool
+ * parameters as JSON on stdin and reading the decision from the exit code:
+ *
+ *   exit 0  = allow
+ *   exit 1  = ask the user   (RESERVED — not produced by this version)
+ *   exit ≥2 = reject; stderr is forwarded to the model as the reason
+ *
+ * NOTE the inversion vs. the other harnesses' subprocess hooks (where
+ * exit 2 blocks but the allow path is exit 0 with structured stdout):
+ * here a denial is exit 2 *plus a stderr message*, and stdout is unused.
+ *
+ * TIMEOUT: Amp enforces a 10-second delegate timeout. A delegate that does
+ * not exit within 10s is treated as a reject, so every Ory call below
+ * (session resolution + permission check) must complete well inside that
+ * window; the fail-open arms below keep slow/unreachable Ory from wedging
+ * the agent, but a hard 10s hang would still surface as a reject.
+ *
+ * Fail-open: any error — parse failure, network error, rate limit, crash —
+ * resolves to exit 0 (allow). The delegate must never wedge the agent.
+ *
+ * Verified against the installed `amp` binary (delegate exit-code contract
+ * and 10s timeout).
+ */
+import { OryAgentClient } from "@ory/argus";
+import { type AmpDelegateInput } from "./types.js";
+export interface DelegateDecision {
+    /** Process exit code to return to Amp. */
+    exitCode: number;
+    /** Reason to write to stderr (only set when rejecting). */
+    reason?: string;
+}
+/** Pull the tool name out of the (undocumented) delegate payload. */
+export declare function extractToolName(input: AmpDelegateInput): string;
+/**
+ * Core decision logic, factored out so tests can call it directly without
+ * spawning a subprocess or hitting `process.exit`. Resolves to the exit
+ * code (and stderr reason) Amp expects. Always fails open: any thrown
+ * error resolves to ALLOW.
+ */
+export declare function decideToolPermission(input: AmpDelegateInput, client: OryAgentClient): Promise<DelegateDecision>;

package/dist/permission.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Amp permission delegate helper (PRIMARY blocking gate).
+ *
+ * Amp's `amp.permissions` config can route a tool to
+ * `{ action: "delegate", to: "ory-amp-permission" }`. Amp then runs this
+ * program as a subprocess for each matching tool call, passing the tool
+ * parameters as JSON on stdin and reading the decision from the exit code:
+ *
+ *   exit 0  = allow
+ *   exit 1  = ask the user   (RESERVED — not produced by this version)
+ *   exit ≥2 = reject; stderr is forwarded to the model as the reason
+ *
+ * NOTE the inversion vs. the other harnesses' subprocess hooks (where
+ * exit 2 blocks but the allow path is exit 0 with structured stdout):
+ * here a denial is exit 2 *plus a stderr message*, and stdout is unused.
+ *
+ * TIMEOUT: Amp enforces a 10-second delegate timeout. A delegate that does
+ * not exit within 10s is treated as a reject, so every Ory call below
+ * (session resolution + permission check) must complete well inside that
+ * window; the fail-open arms below keep slow/unreachable Ory from wedging
+ * the agent, but a hard 10s hang would still surface as a reject.
+ *
+ * Fail-open: any error — parse failure, network error, rate limit, crash —
+ * resolves to exit 0 (allow). The delegate must never wedge the agent.
+ *
+ * Verified against the installed `amp` binary (delegate exit-code contract
+ * and 10s timeout).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractToolName = extractToolName;
+exports.decideToolPermission = decideToolPermission;
+const argus_1 = require("@ory/argus");
+const types_js_1 = require("./types.js");
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+}
+/** Pull the tool name out of the (undocumented) delegate payload. */
+function extractToolName(input) {
+    return input.tool ?? input.toolName ?? input.name ?? "unknown";
+}
+/** Pull the session/thread id out of the delegate payload, if present. */
+function extractSessionId(input) {
+    return input.threadID ?? input.sessionID ?? input.session_id;
+}
+/**
+ * Core decision logic, factored out so tests can call it directly without
+ * spawning a subprocess or hitting `process.exit`. Resolves to the exit
+ * code (and stderr reason) Amp expects. Always fails open: any thrown
+ * error resolves to ALLOW.
+ */
+async function decideToolPermission(input, client) {
+    const toolName = extractToolName(input);
+    const sessionId = extractSessionId(input);
+    client.tracer.setContext({
+        traceId: (0, argus_1.deriveTraceId)(sessionId ?? toolName),
+        sessionId,
+    });
+    client.logger.info("delegate.received", { toolName, sessionId });
+    // Audit-only mode: never block, just record the invocation.
+    if ((0, argus_1.resolveConfig)().auditOnly) {
+        client.tracer.record("tool.invoke", "ok", {
+            attributes: { toolName, mode: "audit-only" },
+        });
+        return { exitCode: types_js_1.AMP_DELEGATE_EXIT.ALLOW };
+    }
+    const subject = (0, argus_1.resolveUserSubject)(client, sessionId ? `session:${sessionId}` : undefined);
+    const subjectId = (0, argus_1.subjectLabel)(subject);
+    try {
+        const outcome = await (0, argus_1.gateToolCall)(client, {
+            harness: "amp",
+            toolName,
+            check: {
+                namespace: resolveNamespace(),
+                object: toolName,
+                relation: "use",
+                ...subject,
+            },
+            spanAttributes: { toolName },
+        });
+        // Interactive tools (operator-extensible via ORY_INTERACTIVE_TOOLS):
+        // the user.interaction span is already recorded; allow so Amp can
+        // surface the prompt to the user.
+        if (outcome.kind === "interactive") {
+            return { exitCode: types_js_1.AMP_DELEGATE_EXIT.ALLOW };
+        }
+        const decision = outcome;
+        const attrs = { toolName };
+        const decisionAttrs = decision.spanAttributes;
+        if (decision.kind === "fail_open") {
+            // network_error / rate_limited / unknown → allow.
+            client.logger.warn("delegate.fail_open", {
+                toolName,
+                code: decision.error.code,
+                message: "Ory unreachable or errored, failing open",
+            });
+            return { exitCode: types_js_1.AMP_DELEGATE_EXIT.ALLOW };
+        }
+        if (decision.kind === "allow") {
+            client.tracer.record("tool.invoke", "ok", {
+                attributes: { ...attrs, ...decisionAttrs, allowed: true },
+            });
+            return { exitCode: types_js_1.AMP_DELEGATE_EXIT.ALLOW };
+        }
+        if (decision.kind === "observe") {
+            // Observe mode: log the would-be denial but let the tool through.
+            client.tracer.record("tool.block", "denied", {
+                attributes: { ...attrs, ...decisionAttrs, allowed: false, ...(0, argus_1.alertAttributes)(false) },
+            });
+            client.tracer.record("tool.invoke", "ok", {
+                attributes: { ...attrs, ...decisionAttrs, allowed: false, observed: true },
+            });
+            return { exitCode: types_js_1.AMP_DELEGATE_EXIT.ALLOW };
+        }
+        // decision.kind === "deny" → enforce mode hard block.
+        client.tracer.record("tool.block", "denied", {
+            attributes: { ...attrs, ...decisionAttrs, allowed: false, ...(0, argus_1.alertAttributes)(true) },
+        });
+        const reason = (0, argus_1.formatDenialMessage)({
+            tool: toolName,
+            subjectId,
+            namespace: resolveNamespace(),
+        });
+        client.logger.warn("tool.denied", { toolName, subjectId, message: reason });
+        return { exitCode: types_js_1.AMP_DELEGATE_EXIT.REJECT, reason };
+    }
+    catch (err) {
+        // Fail open on any unexpected error.
+        client.logger.error("delegate.error", {
+            toolName,
+            message: err instanceof Error ? err.message : String(err),
+        });
+        return { exitCode: types_js_1.AMP_DELEGATE_EXIT.ALLOW };
+    }
+}
+/**
+ * Read all of stdin as a string.
+ *
+ * Uses event listeners instead of `for await` so we don't depend on the
+ * parent closing stdin (sending EOF). If no EOF arrives, we resolve after
+ * a short idle gap once data has been received. Copied from the gemini-cli
+ * subprocess hook for robustness parity.
+ */
+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"));
+            }
+        }
+        let idleTimer;
+        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);
+            }
+        });
+    });
+}
+async function main() {
+    const client = argus_1.OryAgentClient.fromEnv("amp");
+    const raw = await readStdin();
+    let input;
+    try {
+        input = raw.trim() ? JSON.parse(raw) : {};
+    }
+    catch {
+        // Parse failure — fail open (allow) rather than wedging the agent.
+        client.logger.error("delegate.stdin.parse_failed", { raw: raw.slice(0, 200) });
+        await client.tracer.shutdown();
+        process.exit(types_js_1.AMP_DELEGATE_EXIT.ALLOW);
+    }
+    const { exitCode, reason } = await decideToolPermission(input, client);
+    if (exitCode === types_js_1.AMP_DELEGATE_EXIT.REJECT && reason) {
+        // stderr is forwarded to the model as the rejection reason.
+        process.stderr.write(reason + "\n");
+    }
+    await client.tracer.shutdown();
+    process.exit(exitCode);
+}
+// Only run the stdin→exit-code pipeline when invoked as the CLI entry
+// point. Tests import this module to call `decideToolPermission` directly,
+// so guarding here keeps `main()` (and its `process.exit`) from firing on
+// import. `module` exists under CJS output (module: nodenext → CJS).
+if (require.main === module) {
+    main().catch((err) => {
+        // Top-level safety net: never block on an unexpected crash.
+        process.stderr.write(`[ory-agent] delegate fatal: ${err}\n`);
+        process.exit(types_js_1.AMP_DELEGATE_EXIT.ALLOW);
+    });
+}

package/dist/plugin.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Amp in-process plugin (SECONDARY: session auth + post-tool tracing).
+ *
+ * Amp loads a default-exported factory from `.amp/plugins/*.ts` modules and
+ * calls it with a `PluginAPI` (the `@ampcode/plugin` contract, Bun runtime).
+ * Each handler receives the event payload and a `PluginEventContext`. We
+ * subscribe to:
+ *
+ *   session.start → run the user gate (advisory, allowBlock:false), the
+ *                   agent gate, and write the user→agent delegation tuple.
+ *   tool.result   → record a `tool.complete` audit span.
+ *
+ * The BLOCKING permission decision deliberately does NOT live here. Amp's
+ * in-process `tool.call` event *can* block (via a `reject-and-continue`
+ * result), but we route blocking through the standalone permission delegate
+ * helper (`permission.ts`) instead — that gives the same subprocess parity
+ * as the other harnesses and keeps the in-process module purely
+ * observational. The delegate runs as its own process and decides by exit
+ * code; this module only authenticates and traces.
+ *
+ * Because Amp's `session.start` handler has no return-value channel for
+ * blocking, the user login runs in advisory mode (allowBlock:false), like
+ * the OpenCode / OpenClaw factory plugins.
+ */
+import { OryAgentClient, ensureUserAuthenticated, ensureAgentIdentity } from "@ory/argus";
+import type { AmpPlugin } from "./types.js";
+export interface CreateOryPluginDeps {
+    /** Test injection point for the user login flow. */
+    userLogin?: typeof ensureUserAuthenticated;
+    /** Test injection point for the agent identity gate. */
+    agentGate?: typeof ensureAgentIdentity;
+}
+/**
+ * Create the Amp in-process plugin factory.
+ *
+ * Returns a function matching Amp's `AmpPlugin` contract: it receives the
+ * PluginAPI and registers event handlers via `api.on(...)`.
+ */
+export declare function createOryPlugin(clientOrConfig?: OryAgentClient | {
+    projectUrl: string;
+    apiKey?: string;
+}, deps?: CreateOryPluginDeps): AmpPlugin;

package/dist/plugin.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Amp in-process plugin (SECONDARY: session auth + post-tool tracing).
+ *
+ * Amp loads a default-exported factory from `.amp/plugins/*.ts` modules and
+ * calls it with a `PluginAPI` (the `@ampcode/plugin` contract, Bun runtime).
+ * Each handler receives the event payload and a `PluginEventContext`. We
+ * subscribe to:
+ *
+ *   session.start → run the user gate (advisory, allowBlock:false), the
+ *                   agent gate, and write the user→agent delegation tuple.
+ *   tool.result   → record a `tool.complete` audit span.
+ *
+ * The BLOCKING permission decision deliberately does NOT live here. Amp's
+ * in-process `tool.call` event *can* block (via a `reject-and-continue`
+ * result), but we route blocking through the standalone permission delegate
+ * helper (`permission.ts`) instead — that gives the same subprocess parity
+ * as the other harnesses and keeps the in-process module purely
+ * observational. The delegate runs as its own process and decides by exit
+ * code; this module only authenticates and traces.
+ *
+ * Because Amp's `session.start` handler has no return-value channel for
+ * blocking, the user login runs in advisory mode (allowBlock:false), like
+ * the OpenCode / OpenClaw factory plugins.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOryPlugin = createOryPlugin;
+const argus_1 = require("@ory/argus");
+/**
+ * Create the Amp in-process plugin factory.
+ *
+ * Returns a function matching Amp's `AmpPlugin` contract: it receives the
+ * PluginAPI and registers event handlers via `api.on(...)`.
+ */
+function createOryPlugin(clientOrConfig, deps = {}) {
+    return (api) => {
+        const client = clientOrConfig instanceof argus_1.OryAgentClient
+            ? clientOrConfig
+            : clientOrConfig
+                ? new argus_1.OryAgentClient({ ...clientOrConfig, harness: "amp" })
+                : argus_1.OryAgentClient.fromEnv("amp");
+        api.on("session.start", createSessionStartHandler(client, deps));
+        api.on("tool.result", createToolResultHandler(client));
+    };
+}
+// ─── session.start ─────────────────────────────────────────────────
+function createSessionStartHandler(client, deps) {
+    return async (event, _ctx) => {
+        const sessionId = event.thread?.id;
+        client.logger.info("lifecycle.session_start", { sessionId });
+        client.tracer.setContext({
+            traceId: (0, argus_1.deriveTraceId)(sessionId ?? "amp"),
+            sessionId,
+        });
+        client.tracer.record("session.start", "ok", {
+            attributes: sessionId ? { sessionId } : {},
+        });
+        // Run the user login. Amp's session.start has no block primitive, so
+        // allowBlock is false — the flow emits the user.auth audit span,
+        // refreshes tokens, and may prompt when interactive, but never
+        // prevents the session from starting. When ORY_USER_LOGIN is unset it
+        // is a no-op (mode === "disabled") and we fall through to legacy
+        // logging.
+        const userGate = deps.userLogin ?? argus_1.ensureUserAuthenticated;
+        const decision = await userGate(client, {
+            binName: "ory-amp",
+            harness: "amp",
+            allowBlock: false,
+        });
+        // 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: "amp" });
+        // Once both principals are populated, write the user→agent delegation
+        // tuple. Idempotent + fail-open: audit-trail data only.
+        await recordUserDelegatesAgent(client);
+        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-amp configure' to connect to an Ory project.",
+            });
+            return;
+        }
+        const sessionToken = process.env.ORY_SESSION_TOKEN;
+        const oauth2Token = process.env.ORY_OAUTH2_TOKEN;
+        if (sessionToken) {
+            await verifySessionToken(client, sessionToken);
+            return;
+        }
+        if (oauth2Token) {
+            await verifyOAuth2Token(client, oauth2Token);
+            return;
+        }
+        client.logger.warn("session.no_credentials", {
+            message: "Neither ORY_SESSION_TOKEN nor ORY_OAUTH2_TOKEN is set. " +
+                "Skipping authentication.",
+        });
+    };
+}
+async function verifySessionToken(client, token) {
+    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) {
+        client.logger.warn("session.verify_failed", {
+            code: isOryError(err) ? err.code : "unknown",
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+async function verifyOAuth2Token(client, token) {
+    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,
+        });
+    }
+    catch (err) {
+        client.logger.warn("oauth2.introspect_failed", {
+            code: isOryError(err) ? err.code : "unknown",
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+// ─── tool.result ───────────────────────────────────────────────────
+function createToolResultHandler(client) {
+    return async (event, _ctx) => {
+        const toolName = event.tool ?? "unknown";
+        const sessionId = event.thread?.id;
+        const hasError = event.status === "error";
+        client.tracer.setContext({
+            traceId: (0, argus_1.deriveTraceId)(sessionId ?? "amp"),
+            sessionId,
+        });
+        client.logger.info("lifecycle.tool_result", {
+            toolName,
+            sessionId,
+            status: event.status,
+            hasError,
+        });
+        client.tracer.record("tool.complete", hasError ? "error" : "ok", {
+            attributes: {
+                toolName,
+                status: event.status,
+                ...(0, argus_1.summarizeToolInput)(toolName, event.input),
+                ...(0, argus_1.summarizeToolOutput)(toolName, event.output),
+                ...(event.error ? { error: event.error } : {}),
+            },
+        });
+    };
+}
+// ─── Helpers ───────────────────────────────────────────────────────
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+}
+function isOryError(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        "message" in err);
+}
+/**
+ * Write the user→agent delegation tuple. Idempotent and fail-open:
+ * requires both principal subjects to be populated; any error (including
+ * an unconfigured projectUrl, which manifests as a network_error) is
+ * logged and swallowed. Purely audit-trail data — does not affect
+ * enforcement.
+ */
+async function recordUserDelegatesAgent(client) {
+    const user = client.userPrincipal.subject;
+    const agent = client.agentPrincipal.subject;
+    if (!user || !agent) {
+        client.logger.debug("delegation.skip", {
+            reason: "missing principal",
+            hasUser: !!user,
+            hasAgent: !!agent,
+        });
+        return;
+    }
+    try {
+        await client.createRelationship({
+            namespace: resolveNamespace(),
+            object: `agent:${agent}`,
+            relation: "delegate",
+            subjectId: `user:${user}`,
+        }, { spanAttributes: { delegation: "user-to-agent" } });
+    }
+    catch (err) {
+        const oryErr = err;
+        client.logger.warn("delegation.user_to_agent.failed", {
+            code: oryErr.code,
+            message: oryErr.message,
+        });
+    }
+}