@ory/amp 0.10.0

package/dist/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Amp (Sourcegraph's coding agent) plugin types.
+ *
+ * Verified against the installed `amp` binary (Bun-compiled, embedded JS
+ * bundle exposing the `@ampcode/plugin` API). Amp's integration is a HYBRID
+ * of two mechanisms:
+ *
+ *   1. Permission delegate helper (PRIMARY, blocking) — a standalone
+ *      program named in `amp.permissions` as `{ tool, action: "delegate",
+ *      to: "<program>" }`. Amp invokes it as a subprocess, passing the tool
+ *      parameters as JSON on stdin. The program decides by exit code:
+ *      0 = allow, 1 = ask the user, ≥2 = reject (stderr → model reason).
+ *      A 10-second delegate timeout applies (a timed-out delegate is
+ *      treated as a reject). See `AmpDelegateInput` below.
+ *
+ *   2. In-process plugin (SECONDARY, tracing/auth) — a default-exported
+ *      factory placed under `.amp/plugins/*.ts` that receives a `PluginAPI`
+ *      (the `@ampcode/plugin` contract). Runs under Bun's TypeScript
+ *      runtime. Used here ONLY for advisory session-start auth and
+ *      post-tool tracing; the blocking decision lives in the delegate
+ *      helper for cleaner subprocess parity.
+ *
+ * We model the `@ampcode/plugin` API surface locally (the plugin package
+ * takes no harness SDK dependency — see AGENTS.md). The shapes mirror the
+ * binary's `PluginEventMap` / `PluginEventContext` exactly.
+ */
+/**
+ * JSON payload Amp writes to the delegate program's stdin.
+ *
+ * The delegate receives the tool name and its arguments. We read several
+ * plausible spellings for the tool name (`tool` / `toolName` / `name`) and
+ * arguments (`input` / `params` / `arguments` / `args`) so the helper
+ * degrades gracefully across Amp revisions; anything we cannot find falls
+ * back to "unknown", which fails open (allow) per the design rules.
+ */
+export interface AmpDelegateInput {
+    /** Tool being invoked (canonical: `tool`). */
+    tool?: string;
+    /** Alternate spellings tolerated for forward/backward compatibility. */
+    toolName?: string;
+    name?: string;
+    /** Tool parameters (canonical: `input`). */
+    input?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    arguments?: Record<string, unknown>;
+    args?: Record<string, unknown>;
+    /** Optional session/thread correlation id, if Amp supplies one. */
+    threadID?: string;
+    sessionID?: string;
+    session_id?: string;
+    [key: string]: unknown;
+}
+/**
+ * Exit codes the delegate program returns to Amp.
+ * NOTE the inversion vs. other harnesses: deny is exit ≥2, not exit 0/1.
+ */
+export declare const AMP_DELEGATE_EXIT: {
+    /** Allow the tool call. */
+    readonly ALLOW: 0;
+    /**
+     * Ask the user. Reserved — not produced by this version. Ory observe
+     * mode passes through (exit 0) and enforce mode rejects (exit 2); there
+     * is no "ask Ory then ask the user" middle state yet.
+     */
+    readonly ASK: 1;
+    /** Reject the tool call; stderr is forwarded to the model as the reason. */
+    readonly REJECT: 2;
+};
+/** Thread reference carried on every plugin event. */
+export interface AmpThreadRef {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * The result an in-process `tool.call` handler can return to influence a
+ * tool invocation. We never return a blocking action from the in-process
+ * plugin — the delegate helper owns blocking — but the type is modeled in
+ * full to match `@ampcode/plugin`.
+ */
+export type AmpToolCallResult = {
+    action: "allow";
+} | {
+    action: "reject-and-continue";
+    message: string;
+} | {
+    action: "modify";
+    input: Record<string, unknown>;
+} | {
+    action: "synthesize";
+    result: {
+        output: string;
+        exitCode?: number;
+    };
+} | {
+    action: "error";
+    message: string;
+};
+/** `session.start` — a new thread/session begins. */
+export interface AmpSessionStartEvent {
+    thread: AmpThreadRef;
+    [key: string]: unknown;
+}
+/** `agent.start` — the user submitted a prompt; a turn begins. */
+export interface AmpAgentStartEvent {
+    thread: AmpThreadRef;
+    [key: string]: unknown;
+}
+/** `tool.call` — a tool is about to execute (pre-execution). */
+export interface AmpToolCallEvent {
+    toolUseID: string;
+    tool: string;
+    input: Record<string, unknown>;
+    thread: AmpThreadRef;
+    [key: string]: unknown;
+}
+/** `tool.result` — a tool finished executing (post-execution). */
+export interface AmpToolResultEvent {
+    toolUseID: string;
+    tool: string;
+    input: Record<string, unknown>;
+    status: "done" | "error" | "cancelled";
+    error?: string;
+    output?: unknown;
+    thread: AmpThreadRef;
+    [key: string]: unknown;
+}
+/** `agent.end` — a turn ended, carrying the produced messages. */
+export interface AmpAgentEndEvent {
+    thread: AmpThreadRef;
+    messages?: unknown[];
+    [key: string]: unknown;
+}
+/**
+ * Context (`PluginEventContext`) passed as the SECOND argument to every
+ * handler. Carries Amp's UI helpers, a shell runner (`$`), etc. Modeled as
+ * an open object — this plugin only authenticates and traces, so it does
+ * not depend on any specific context member.
+ */
+export interface AmpPluginEventContext {
+    [key: string]: unknown;
+}
+/**
+ * Map of Amp plugin event name → payload type. Handlers receive the payload
+ * as the first arg and a `PluginEventContext` as the second.
+ */
+export interface AmpEventMap {
+    "session.start": AmpSessionStartEvent;
+    "agent.start": AmpAgentStartEvent;
+    "tool.call": AmpToolCallEvent;
+    "tool.result": AmpToolResultEvent;
+    "agent.end": AmpAgentEndEvent;
+}
+export type AmpEvent = keyof AmpEventMap;
+/** Return type for each event handler. */
+export interface AmpEventReturn {
+    "session.start": void;
+    "agent.start": void;
+    "tool.call": void | AmpToolCallResult;
+    "tool.result": void;
+    "agent.end": void;
+}
+/** Handler signature for a given event: `(event, ctx) => result`. */
+export type AmpEventHandler<E extends AmpEvent> = (event: AmpEventMap[E], ctx: AmpPluginEventContext) => AmpEventReturn[E] | Promise<AmpEventReturn[E]>;
+/**
+ * The PluginAPI object Amp passes to the default-exported plugin factory
+ * (`@ampcode/plugin`'s `PluginAPI`).
+ */
+export interface AmpPluginApi {
+    /** Subscribe to a lifecycle event. */
+    on<E extends AmpEvent>(event: E, handler: AmpEventHandler<E>): void;
+    /** Register a custom tool. Unused by this plugin; modeled for completeness. */
+    registerTool?: (name: string, def: unknown) => void;
+    [key: string]: unknown;
+}
+/** The default-exported plugin factory Amp invokes at load time. */
+export type AmpPlugin = (api: AmpPluginApi) => void | Promise<void>;

package/dist/types.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Amp (Sourcegraph's coding agent) plugin types.
+ *
+ * Verified against the installed `amp` binary (Bun-compiled, embedded JS
+ * bundle exposing the `@ampcode/plugin` API). Amp's integration is a HYBRID
+ * of two mechanisms:
+ *
+ *   1. Permission delegate helper (PRIMARY, blocking) — a standalone
+ *      program named in `amp.permissions` as `{ tool, action: "delegate",
+ *      to: "<program>" }`. Amp invokes it as a subprocess, passing the tool
+ *      parameters as JSON on stdin. The program decides by exit code:
+ *      0 = allow, 1 = ask the user, ≥2 = reject (stderr → model reason).
+ *      A 10-second delegate timeout applies (a timed-out delegate is
+ *      treated as a reject). See `AmpDelegateInput` below.
+ *
+ *   2. In-process plugin (SECONDARY, tracing/auth) — a default-exported
+ *      factory placed under `.amp/plugins/*.ts` that receives a `PluginAPI`
+ *      (the `@ampcode/plugin` contract). Runs under Bun's TypeScript
+ *      runtime. Used here ONLY for advisory session-start auth and
+ *      post-tool tracing; the blocking decision lives in the delegate
+ *      helper for cleaner subprocess parity.
+ *
+ * We model the `@ampcode/plugin` API surface locally (the plugin package
+ * takes no harness SDK dependency — see AGENTS.md). The shapes mirror the
+ * binary's `PluginEventMap` / `PluginEventContext` exactly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AMP_DELEGATE_EXIT = void 0;
+/**
+ * Exit codes the delegate program returns to Amp.
+ * NOTE the inversion vs. other harnesses: deny is exit ≥2, not exit 0/1.
+ */
+exports.AMP_DELEGATE_EXIT = {
+    /** Allow the tool call. */
+    ALLOW: 0,
+    /**
+     * Ask the user. Reserved — not produced by this version. Ory observe
+     * mode passes through (exit 0) and enforce mode rejects (exit 2); there
+     * is no "ask Ory then ask the user" middle state yet.
+     */
+    ASK: 1,
+    /** Reject the tool call; stderr is forwarded to the model as the reason. */
+    REJECT: 2,
+};

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@ory/amp",
+  "version": "0.10.0",
+  "description": "Ory plugin for Amp (Sourcegraph's coding agent): a permission delegate that authorizes every tool call plus an in-process plugin for session auth and audit tracing",
+  "license": "Apache-2.0",
+  "homepage": "https://ory.com",
+  "keywords": [
+    "ory",
+    "amp",
+    "ampcode",
+    "sourcegraph",
+    "coding-agent",
+    "permissions",
+    "plugin",
+    "delegate",
+    "identity",
+    "identity-management",
+    "iam",
+    "authentication",
+    "authorization",
+    "access-control",
+    "rbac",
+    "zanzibar",
+    "oauth",
+    "oauth2",
+    "openid-connect",
+    "oidc",
+    "session",
+    "mfa",
+    "sso",
+    "audit",
+    "audit-log",
+    "compliance",
+    "agent",
+    "ai-agent",
+    "agent-security",
+    "guardrails",
+    "llm",
+    "tracing",
+    "distributed-tracing",
+    "observability",
+    "kratos",
+    "keto",
+    "hydra"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "ory-amp": "dist/cli/main.js",
+    "ory-amp-permission": "dist/permission.js",
+    "ory-amp-setup": "dist/cli/setup.js"
+  },
+  "files": [
+    "dist",
+    "!dist/dev",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@ory/argus": "0.10.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vitest": "4.1.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "dev": "node dist/dev/launcher.js"
+  }
+}