@odingard/guardian-sdk 0.0.0-stage → 0.2.0

package/dist-dts/contracts/action-registry.d.ts

@@ -0,0 +1,287 @@
+import { type TransactionDeclaration } from "./transaction.js";
+import { type ActionAuthorityFacts } from "./commerce.js";
+import type { ResourceClaim } from "./resource-claims.js";
+import { type ProtectedCatalogEntry } from "./protected-data.js";
+import { type ToolDescriptor } from "./tools.js";
+/**
+ * GUA-UNIVERSAL-001 §7 — Universal Action Registry.
+ *
+ * Every consequential action is registered independently of provider. The
+ * authority kernel resolves an action_id to an ActionDefinition and invokes
+ * its hooks uniformly; it never branches on action/provider identity (K15).
+ * Adding a new action means adding a registry definition plus an adapter —
+ * no kernel change.
+ */
+export type Reversibility = "reversible" | "limited" | "difficult" | "destructive" | "safety-sensitive";
+export type RiskClass = "R0" | "R1" | "R2" | "R3" | "R4" | "R5";
+/** The connection facts an action definition may bind against. */
+export type ActionConnectionBinding = Readonly<{
+    provider: string;
+    mailboxAddress?: string;
+    endpointAllowlist?: readonly string[];
+    /** Provider "tool" connections carry the installed tool-server catalog. */
+    toolServer?: Readonly<{
+        serverName: string;
+        serverVersion: string;
+        tools: readonly ToolDescriptor[];
+    }>;
+    /** Tool names enabled for the requesting agent (agent_tools registry). */
+    enabledToolNames?: readonly string[];
+    calendarId?: string;
+    /** Canonical path prefixes file ops may touch (files provider). */
+    pathAllowlist?: readonly string[];
+    /** Canonical path prefixes a file may be shared from (files provider). */
+    shareAllowlist?: readonly string[];
+    /** Declared protected fields for this connection (protected_data). */
+    protectedCatalog?: readonly ProtectedCatalogEntry[];
+    /**
+     * WO-016 — provider "guardian" connections bind delegation facts for the
+     * requesting agent: which sub-agents are bonded to it, and the parent's
+     * derived authority ceiling per target connection. An unbonded child id or
+     * a delegation outside the ceiling fails the binding (DENY).
+     */
+    bondedSubAgentIds?: readonly string[];
+    delegationCeilings?: Readonly<Record<string, {
+        actionIds: readonly string[];
+    }>>;
+    /**
+     * WO-021 — the universal Resource Claim projected from this connection's
+     * binding facts (guardian.resource-claim.v1). Built-in definitions keep
+     * reading the legacy vertical fields above; pack-defined actions evaluate
+     * their declarative claim/binding rules against this claim only.
+     */
+    claims?: ResourceClaim;
+}>;
+export type ActionBindingResult = Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    reasonCode: string;
+}>;
+/**
+ * WO-028 (§34) — the full canonical lifecycle declared on consequential
+ * action kinds. An intent may union its own declaration on top; the
+ * effective lifecycle binds into the canonical action digest.
+ */
+export declare const FULL_TRANSACTION_LIFECYCLE: TransactionDeclaration;
+export interface ActionDefinition<P = unknown> {
+    readonly actionId: string;
+    readonly schemaVersion: 1;
+    readonly actionFamily: string;
+    readonly humanLabel: string;
+    readonly description: string;
+    /** Typed kind returned to the pipeline after parameter validation. */
+    readonly parametersKind: string;
+    /** Raw field names, for rendering + policy primitives. */
+    readonly requiredParameters: readonly string[];
+    /** Fields bound into the material-parameter digest (TOCTOU, §27). */
+    readonly materialParameters: readonly string[];
+    /** Resource pattern: `${resourceType}:${connectionId}`. */
+    readonly resourceType: string;
+    /** Providers a connection may use for this action. */
+    readonly providers: readonly string[];
+    readonly counterpartyRules: string;
+    readonly dataEffects: string;
+    readonly reversibility: Reversibility;
+    readonly riskClass: RiskClass;
+    readonly defaultDecisionPosture: "allow" | "ask" | "deny";
+    /** Generic fields the Authority Slip renders. */
+    readonly approvalPresentationSchema: readonly string[];
+    /**
+     * WO-021 — optional labelled display fields. Signed Action Packs set these
+     * from their verified `approvalDisplay` metadata so the slip can render
+     * trusted labels against the bound material parameters; built-ins leave
+     * this unset and keep today's rendering.
+     */
+    readonly approvalDisplayFields?: readonly Readonly<{
+        field: string;
+        label: string;
+    }>[];
+    readonly capabilityRequirements: Readonly<{
+        uses: number;
+    }>;
+    readonly executionContract: string;
+    readonly verificationContract: Readonly<{
+        level: string;
+    }>;
+    readonly evidenceRequirements: readonly string[];
+    readonly version: 1;
+    readonly status: "active" | "deprecated" | "disabled";
+    /**
+     * When true the action is capability-expanding: authority derivation never
+     * auto-includes it in a grant's action set. It can only enter a grant when
+     * a human selects it explicitly (WO-015 self-serve-escalation denial).
+     */
+    readonly requiresExplicitGrant?: boolean;
+    /**
+     * WO-019 — minimum principal class allowed to hold authority for this
+     * action. "adult" marks governance and identity-level actions that a
+     * child-classed principal can never be granted: the control plane excludes
+     * them when emitting authority for a child, so the kernel DENYs with
+     * ACTION_NOT_ALLOWED. Absent means any principal class may hold it.
+     */
+    readonly minPrincipalClass?: "adult";
+    /**
+     * WO-028 (§34–35) — when set, every action of this kind executes under
+     * a recorded guardian.transaction.v1 lifecycle. Unioned with the
+     * governing intent's own declaration (canonical order; never shrinks);
+     * the effective declaration binds into the canonical action digest.
+     */
+    readonly transaction?: TransactionDeclaration;
+    /**
+     * WO-028 (§36) — declared compensation mapping: this action kind
+     * compensates `compensatesAction` (e.g. commerce.refund compensates
+     * commerce.purchase). A compensating action still runs the full
+     * authority path — it never bypasses ASK or enlarges authority.
+     */
+    readonly compensatesAction?: string;
+    /**
+     * Action-specific logic lives HERE — inside the registered definition —
+     * never inside the kernel. Hooks receive only kernel-verified inputs.
+     */
+    validateParameters(materialParameters: unknown): Readonly<{
+        ok: true;
+        params: P;
+    } | {
+        ok: false;
+    }>;
+    /** Pre-execution binding the agent's params to the leased connection. */
+    validateBinding(input: {
+        params: P;
+        connection: ActionConnectionBinding;
+    }): ActionBindingResult;
+    /** Canonical projection whose digest the verified outcome must match. */
+    verificationProjection(params: P): unknown;
+    /** Envelope projection recorded at reservation time. */
+    envelopeProjection(params: P): unknown;
+    /**
+     * Generic monetary-authority facts derived from validated parameters
+     * (WO-014). When present, the envelope's declared facts must equal the
+     * derived values, so an agent cannot understate an amount or smuggle a
+     * merchant/category/recurrence fact past the kernel.
+     */
+    authorityFacts?(params: P): ActionAuthorityFacts;
+}
+export type ActionRegistry = Readonly<{
+    get(actionId: string): ActionDefinition | undefined;
+    entries(): readonly ActionDefinition[];
+}>;
+export declare function createActionRegistry(definitions: readonly ActionDefinition[]): ActionRegistry;
+export declare const EMAIL_SEND_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.email.send.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    replyTo: never[];
+    subject: string;
+    body: {
+        format: "text/plain";
+        text: string;
+    };
+    attachments: never[];
+    inReplyTo: null;
+}>;
+export declare const API_REQUEST_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.api.request.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+    url: string;
+    headers: {
+        name: string;
+        value: string;
+    }[];
+    body?: string | undefined;
+    idempotencyKey?: string | undefined;
+}>;
+export declare const TOOL_INVOKE_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.tool.invoke.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    toolName: string;
+    arguments: Record<string, unknown>;
+}>;
+export declare const MCP_INSTALL_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.mcp.install.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    tool: {
+        name: string;
+        method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+        url: string;
+        description?: string | undefined;
+        transport?: "http" | undefined;
+    } | {
+        name: string;
+        transport: "record";
+        description?: string | undefined;
+    };
+}>;
+export declare const MCP_ENABLE_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.mcp.enable.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    toolName: string;
+}>;
+export declare const COMMERCE_PURCHASE_DEFINITION: ActionDefinition<{
+    schema: "commerce.purchase.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    merchantId: string;
+    merchantCategory: string;
+    amountCents: number;
+    currency: "USD";
+    orderDescription: string;
+    idempotencyKey: string;
+    taskId?: (string & import("zod").$brand<"TaskId">) | undefined;
+}>;
+export declare const COMMERCE_REFUND_DEFINITION: ActionDefinition<{
+    schema: "commerce.refund.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    chargeId: string;
+    reason: string;
+    amountCents?: number | undefined;
+}>;
+export declare const COMMERCE_RETURN_DEFINITION: ActionDefinition<{
+    schema: "commerce.return.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    chargeId: string;
+    reason: string;
+}>;
+export declare const SUBSCRIPTION_CREATE_DEFINITION: ActionDefinition<{
+    schema: "subscription.create.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    merchantId: string;
+    planId: string;
+    amountCents: number;
+    currency: "USD";
+    interval: "week" | "month" | "year";
+    idempotencyKey: string;
+}>;
+export declare const LOCAL_EXEC_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.local.exec.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    command: string;
+    cwd?: string | undefined;
+}>;
+export declare const LOCAL_EXEC_PUBLISH_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.local.exec.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    command: string;
+    cwd?: string | undefined;
+}>;
+export declare const LOCAL_EXEC_DESTROY_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.local.exec.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    command: string;
+    cwd?: string | undefined;
+}>;
+export declare const LOCAL_EGRESS_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.local.egress.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    url: string;
+    method: "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+}>;
+export declare const LOCAL_BROWSE_DEFINITION: ActionDefinition<{
+    schema: "odingard.guardian.local.browse.v1";
+    connectionId: string & import("zod").$brand<"ConnectionId">;
+    url: string;
+}>;
+export declare const universalActionRegistry: ActionRegistry;