@tenuo/core 0.2.4-beta.0 → 0.3.0-beta.0

package/README.md

@@ -38,18 +38,60 @@ ceiling. `devRoot()` requires `NODE_ENV=development` or `test`,
 `devRoot({ allowInProduction: true })`, or `TENUO_ALLOW_DEV=1`. Unset
 `NODE_ENV` is not treated as development.
 
-Production loads an issued warrant and a trusted root:
+Production loads an issued warrant and a trusted root. Prefer `Runtime` when
+the same holder identity, roots, revocation list, and receipt buffer should
+outlive a single call:
 
 ```ts
-const tenuo = createTenuo({
+const identity = createTenuo.identity(createTenuo.holderKeyFromEnv("TENUO_HOLDER_SECRET"));
+const runtime = createTenuo.runtime({
+  identity,
   trustedRoots: [createTenuo.publicKeyFromEnv("TENUO_ROOT_PUBLIC_KEY")],
+  receipts: "collect",
 });
-const session = tenuo.sessionFromWire({
-  warrant: process.env.TENUO_WARRANT!,
-  holderKey: createTenuo.holderKeyFromEnv("TENUO_HOLDER_SECRET"),
+const session = runtime.sessionFromWire(process.env.TENUO_WARRANT!);
+await readFile.execute({ path: "/data/q3.pdf" }, { session });
+const receipts = session.drainReceipts(); // persist, then upload
+```
+
+`createTenuo.parseConnectToken(raw)` decodes a `tenuo_ct_…` token. It does not
+read environment variables or invent an origin. Relative `/v1` endpoints need
+`token.resolveEndpoint({ localBase })`. Callers append `/v1/…` to the bare
+origin.
+
+See [Receipt delivery](../../README.md#receipt-delivery) for peek / drain / ack
+guarantees. This package does not perform HTTP, discovery, or upload.
+
+Delegation to another agent rebinds a narrower child to that agent's key. The
+current holder signs; core refuses any child that is not within its parent
+before a token exists; a copied chain fails `TENUO_INVALID_POP` under any other
+key:
+
+```ts
+const holderKey = createTenuo.generateHolderKey();          // in the worker, once
+const workerPublicKey = createTenuo.publicKeyFromHolderKey(holderKey);
+
+const handed = tenuo.narrow(session, { path: under("/data/reports") }, {
+  holder: workerPublicKey,
+  ttlSeconds: 300,
+  terminal: true, // the worker cannot hand it on
 });
+// worker: tenuo.sessionFromWire({ warrant: handed.toWire(), holderKey })
 ```
 
+`session({ holder, maxDepth })` issues straight to an agent's key and caps how
+far the chain may go; `issuerPublicKey()` is what agents put in `trustedRoots`;
+`session.inspect()` shows depth, ceiling, tools, and holder public key.
+
+The rest of the protocol is here too: a stable issuer key
+(`createTenuo({ root: createTenuo.issuerKeyFromEnv("TENUO_ISSUER_SECRET") })`),
+issuer sessions and `tenuo.issue()`, clearance / session id / agent id, the
+full constraint set (`range`, `regex`, `cidr`, `urlSafe`, `shlex`, `anyOf`,
+`cel`, ...), approval gates with `ApprovalRequiredError.request`,
+`createTenuo.signApproval()` and the control-plane v1 wire shape, revocation
+lists (`tenuo.revocationList()`), public receipt verification, `tenuo.explain()`,
+and `tenuo.present()` / `tenuo.verify()` for boundaries that are not MCP.
+
 MCP wire helpers live on `tenuo.mcp` (`attach` / `verify` / `handler`). They do
 not depend on an MCP framework. For the official v2 server, use `@tenuo/mcp`.
 For `@modelcontextprotocol/sdk` v1, copy the recipe in `examples/mcp/host.ts`.
@@ -57,6 +99,8 @@ For `@modelcontextprotocol/sdk` v1, copy the recipe in `examples/mcp/host.ts`.
 or an async Redis `checkAndRecord`) to reject an exact replayed PoP; that is
 opt-in. PoP v1 is otherwise replayable in-window, including approval-gated
 calls. Pass `nonceStore` on those tools if an approval must be one-use.
+`memoryNonceStore({ ttlSeconds })` defaults to 180 seconds; an explicit TTL must
+be positive, finite, and small enough to represent in milliseconds.
 
 See the [workspace README](../../README.md) for the full API, refuse list, and
 how to rebuild WASM from this monorepo.

package/dist/api.d.ts

@@ -4,11 +4,19 @@
  * Names and shapes here are the review surface — do not grow this file with
  * protocol vocabulary (`Warrant`, `mint`, `guard`) as the lead API.
  */
-export type TenuoErrorCode = "TENUO_NOT_READY" | "TENUO_CONFIGURATION" | "TENUO_CONSTRAINT_VIOLATION" | "TENUO_TOOL_NOT_AUTHORIZED" | "TENUO_WARRANT_EXPIRED" | "TENUO_UNTRUSTED_ROOT" | "TENUO_INVALID_POP" | "TENUO_SIGNATURE_INVALID" | "TENUO_CHAIN_INVALID" | "TENUO_REVOKED" | "TENUO_APPROVAL_REQUIRED" | "TENUO_INSUFFICIENT_APPROVALS" | "TENUO_CANONICALIZATION" | "TENUO_NOT_IMPLEMENTED";
+/** Canonical kebab-case codes from Rust `ErrorCode::name()` / `Denial::code()`. */
+export type ProtocolDenialCode = "signature-invalid" | "untrusted-root" | "chain-broken" | "depth-exceeded" | "warrant-expired" | "tool-not-authorized" | "constraint-violation" | "pop-signature-invalid" | "approval-required" | "insufficient-approvals" | "warrant-revoked";
+/** Legacy SCREAMING_SNAKE aliases accepted by existing TypeScript callers. */
+export type LegacyTenuoErrorCode = "TENUO_NOT_READY" | "TENUO_CONFIGURATION" | "TENUO_CONSTRAINT_VIOLATION" | "TENUO_TOOL_NOT_AUTHORIZED" | "TENUO_WARRANT_EXPIRED" | "TENUO_UNTRUSTED_ROOT" | "TENUO_INVALID_POP" | "TENUO_SIGNATURE_INVALID" | "TENUO_CHAIN_INVALID" | "TENUO_DEPTH_EXCEEDED" | "TENUO_REVOKED" | "TENUO_APPROVAL_REQUIRED" | "TENUO_INSUFFICIENT_APPROVALS" | "TENUO_CANONICALIZATION" | "TENUO_NOT_IMPLEMENTED";
+export type TenuoErrorCode = ProtocolDenialCode | LegacyTenuoErrorCode;
 /** Path-traversal-safe prefix. Core evaluates this; TypeScript does not. */
 export type UnderConstraint = {
     readonly kind: "under";
     readonly root: string;
+    /** Default true. */
+    readonly caseSensitive?: boolean;
+    /** Whether the root itself is allowed. Default true. */
+    readonly allowEqual?: boolean;
 };
 export type EmailConstraint = {
     readonly kind: "email";
@@ -18,19 +26,83 @@ export type MaxConstraint = {
     readonly kind: "max";
     readonly value: number;
 };
+export type MinConstraint = {
+    readonly kind: "min";
+    readonly value: number;
+};
+export type RangeConstraint = {
+    readonly kind: "range";
+    readonly min?: number;
+    readonly max?: number;
+    readonly minExclusive?: boolean;
+    readonly maxExclusive?: boolean;
+};
 export type OneOfConstraint = {
     readonly kind: "oneOf";
     readonly values: readonly string[];
 };
+export type NotOneOfConstraint = {
+    readonly kind: "notOneOf";
+    readonly values: readonly string[];
+};
 export type PatternConstraint = {
     readonly kind: "pattern";
     readonly pattern: string;
 };
+export type RegexConstraint = {
+    readonly kind: "regex";
+    readonly source: string;
+};
 export type ExactConstraint = {
     readonly kind: "exact";
     readonly value: string | number | boolean;
 };
-export type ConstraintExpr = UnderConstraint | EmailConstraint | MaxConstraint | OneOfConstraint | PatternConstraint | ExactConstraint;
+export type WildcardConstraint = {
+    readonly kind: "wildcard";
+};
+export type CidrConstraint = {
+    readonly kind: "cidr";
+    readonly network: string;
+};
+export type UrlPatternConstraint = {
+    readonly kind: "urlPattern";
+    readonly pattern: string;
+};
+export type UrlSafeConstraint = {
+    readonly kind: "urlSafe";
+    readonly schemes?: readonly string[];
+    readonly allowDomains?: readonly string[];
+    readonly denyDomains?: readonly string[];
+};
+export type ShlexConstraint = {
+    readonly kind: "shlex";
+    readonly allow: readonly string[];
+};
+export type ContainsConstraint = {
+    readonly kind: "contains";
+    readonly values: readonly (string | number | boolean)[];
+};
+export type SubsetConstraint = {
+    readonly kind: "subset";
+    readonly values: readonly (string | number | boolean)[];
+};
+export type AnyOfConstraint = {
+    readonly kind: "anyOf";
+    readonly constraints: readonly ConstraintExpr[];
+};
+export type AllConstraint = {
+    readonly kind: "all";
+    readonly constraints: readonly ConstraintExpr[];
+};
+export type NotConstraint = {
+    readonly kind: "not";
+    readonly constraint: ConstraintExpr;
+};
+export type CelConstraint = {
+    readonly kind: "cel";
+    readonly expression: string;
+};
+export type ConstraintExpr = UnderConstraint | EmailConstraint | MaxConstraint | MinConstraint | RangeConstraint | OneOfConstraint | NotOneOfConstraint | PatternConstraint | RegexConstraint | ExactConstraint | WildcardConstraint | CidrConstraint | UrlPatternConstraint | UrlSafeConstraint | ShlexConstraint | ContainsConstraint | SubsetConstraint | AnyOfConstraint | AllConstraint | NotConstraint | CelConstraint;
 /** Per-argument allow policy. Not a Zod schema. */
 export type AllowPolicy = {
     readonly [field: string]: ConstraintExpr;
@@ -44,13 +116,16 @@ export type ToolLike<TArgs extends Record<string, unknown> = Record<string, unkn
     readonly parameters?: unknown;
     execute: (args: TArgs, options?: unknown) => TResult | Promise<TResult>;
 };
-export type ToolPolicy = {
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+export type ToolPolicy<TArgs = undefined> = {
     /**
      * Host ceiling. AND'd with the session in Rust.
      * Non-empty maps are zero-trust: every call argument must be named here.
      * `{}` means no extra ceiling (session/warrant only).
      */
-    readonly allow: AllowPolicy;
+    readonly allow: [NonNullable<TArgs>] extends [object] ? [KeysOfUnion<NonNullable<TArgs>>] extends [never] ? AllowPolicy : string extends KeysOfUnion<NonNullable<TArgs>> ? AllowPolicy : number extends KeysOfUnion<NonNullable<TArgs>> ? AllowPolicy : symbol extends KeysOfUnion<NonNullable<TArgs>> ? AllowPolicy : {
+        readonly [Field in KeysOfUnion<NonNullable<TArgs>>]?: ConstraintExpr;
+    } : AllowPolicy;
     readonly capability?: string;
 };
 /** Compile-time brand only — never assigned at runtime. Do not `in`/`has` this key. */
@@ -83,22 +158,246 @@ export type ProtectedTool<T extends {
     execute: (args: Parameters<T["execute"]>[0], options?: ExecuteOptions & ExtraExecuteOptions<T>) => Promise<Awaited<ReturnType<T["execute"]>>>;
     readonly [protectedBrand]: true;
 };
-/** Whole-tool approval gate. Host collects SignedApproval bytes; Rust decides. */
+/** Per-argument trigger for an approval gate. */
+export type ArgApprovalGate = 
+/** Every value of this argument fires the gate. */
+"all"
+/** Only values satisfying the constraint fire the gate. */
+ | {
+    readonly when: ConstraintExpr;
+}
+/** Every value except those satisfying the constraint fires the gate. Narrowable across delegation. */
+ | {
+    readonly exempt: ConstraintExpr;
+};
+/** Gate on one tool: a message for the approver and optional per-argument triggers. */
+export type ToolApprovalGate = {
+    readonly message?: string;
+    /** Absent: the whole tool is gated. */
+    readonly args?: {
+        readonly [field: string]: ArgApprovalGate;
+    };
+};
+/** Approval requirement. Host collects SignedApproval envelopes; Rust decides. */
 export type RequireApproval = {
     readonly approvers: readonly PublicKeyHandle[];
     readonly min: number;
+    /** Whole-tool gates. Defaults to every tool in the session when `gates` is absent too. */
     readonly tools?: readonly string[];
+    /** Per-tool gates with messages and per-argument triggers. */
+    readonly gates?: {
+        readonly [tool: string]: ToolApprovalGate;
+    };
+};
+/** What an approval service needs to present a call to a human. Not a signed artifact. */
+export type ApprovalRequest = {
+    readonly requestId: string;
+    readonly warrantId: string;
+    readonly tool: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Hex SHA-256 committing to warrant id, tool, canonical args, and holder. */
+    readonly requestHash: string;
+    readonly holderPublicKey: string;
+    readonly requiredApprovers: readonly string[];
+    readonly minApprovals: number;
+    /** Unix seconds. An approval cannot outlive the warrant. */
+    readonly warrantExpiresAt: number;
+    readonly createdAt: number;
+    readonly message: string;
+};
+/** Holder-signed statement that it is the one asking. Carried in a control-plane request. */
+export type ApprovalContextAttestation = {
+    readonly version: number;
+    readonly canonicalization: string;
+    readonly warrantId: string;
+    readonly tool: string;
+    readonly requestHash: string;
+    readonly holderKeyHex: string;
+    readonly argsCanonicalCborB64: string;
+    readonly signerKeyHex: string;
+    readonly signatureB64: string;
+};
+/** Wire body for a control-plane approval API. Field names are the wire names. */
+export type ControlPlaneApprovalRequestV1 = {
+    readonly schema_version: 1;
+    readonly request_id_hex: string;
+    readonly warrant_id: string;
+    readonly tool: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+    readonly request_hash_hex: string;
+    readonly holder_public_key_hex: string;
+    readonly required_approver_keys_hex: readonly string[];
+    readonly min_approvals: number;
+    readonly warrant_expires_at_unix: number;
+    readonly created_at_unix: number;
+    readonly attestation?: Readonly<Record<string, unknown>>;
+    readonly temporal?: Readonly<Record<string, string>>;
+    readonly message?: string;
+};
+export type ControlPlaneApprovalResponseV1 = {
+    readonly status: string;
+    readonly signed_approvals_b64?: readonly string[];
+    readonly error?: string;
+    readonly server_request_id?: string;
+};
+export type SignApprovalOptions = {
+    /** Who approved, in the approver system's own terms. Required. */
+    readonly externalId: string;
+    /** Approval lifetime. Default one hour, always clamped to the warrant's expiry when given. */
+    readonly ttlSeconds?: number;
+    readonly warrantExpiresAt?: number;
+};
+/** Decoded approval envelope. Not authorization. */
+export type ApprovalInfo = {
+    readonly approverPublicKey: string;
+    readonly requestHash: string;
+    readonly externalId: string;
+    readonly approvedAt: number;
+    readonly expiresAt: number;
+    readonly expired: boolean;
+    readonly signatureValid: boolean;
+    readonly error?: string;
 };
 export type SessionAllow = {
     readonly [capability: string]: AllowPolicy;
 };
+/** Named level or a number 0-255. Delegation can only lower it. */
+export type Clearance = number | "untrusted" | "external" | "partner" | "internal" | "privileged" | "system";
 export type SessionInput = {
-    /** Capability map. Optional when `tools` is set. */
+    /** Capability map. Optional when `tools` is set. Issuer sessions may omit it. */
     readonly allow?: SessionAllow;
     /** Wrapped tools from `tenuo.tool()`. Their `allow` is minted into the session. */
     readonly tools?: readonly object[];
     readonly ttlSeconds?: number;
     readonly requireApproval?: RequireApproval;
+    /**
+     * Issue to another agent's key instead of a fresh local holder. The
+     * returned session cannot authorize here (it has no holder secret); send
+     * `toWire()` to that agent, which imports it with `sessionFromWire()`.
+     */
+    readonly holder?: PublicKeyHandle;
+    /**
+     * How many times this authority may be delegated below the root.
+     * `0` makes the session terminal. Omit for the protocol maximum.
+     * Delegation can lower this ceiling and never raise it.
+     */
+    readonly maxDepth?: number;
+    /**
+     * `"execution"` (default) can call tools. `"issuer"` cannot call tools; its
+     * holder can mint execution sessions with `tenuo.issue()` for the tools in
+     * `issuableTools`, within `constraintBounds`, without the root key.
+     */
+    readonly kind?: "execution" | "issuer";
+    readonly clearance?: Clearance;
+    /** Free-form task correlation id. Inherited unchanged through delegation. */
+    readonly sessionId?: string;
+    /** Free-form agent label. Delegation may change it. */
+    readonly agentId?: string;
+    /** Issuer sessions only. */
+    readonly issuableTools?: readonly string[];
+    /** Issuer sessions only: ceiling on the constraints of anything issued, by field. */
+    readonly constraintBounds?: AllowPolicy;
+    /** Issuer sessions only: how deep issued sessions may themselves delegate. */
+    readonly maxIssueDepth?: number;
+};
+/** Options for `tenuo.narrow()`. All optional; the default keeps the holder. */
+export type NarrowOptions = {
+    /**
+     * Bind the child to another agent's key. This is delegation: the current
+     * holder signs, the child belongs to `holder`, and the returned session
+     * cannot authorize here. Hand `toWire()` to that agent.
+     */
+    readonly holder?: PublicKeyHandle;
+    /** Child lifetime. Clamped to what the parent has left. */
+    readonly ttlSeconds?: number;
+    /** The child's holder cannot delegate further. */
+    readonly terminal?: boolean;
+    /** Lower the delegation ceiling. Cannot exceed the parent's. */
+    readonly maxDepth?: number;
+    /** Lower the clearance. Cannot exceed the parent's. */
+    readonly clearance?: Clearance;
+    readonly agentId?: string;
+    /** Approvers can only be added. */
+    readonly addApprovers?: readonly PublicKeyHandle[];
+    /** The threshold can only go up. */
+    readonly minApprovals?: number;
+};
+/** Options for `tenuo.issue()`: an execution session minted from an issuer session. */
+export type IssueInput = {
+    readonly allow: SessionAllow;
+    /** The distinct agent that will use it. Issuer/holder separation is enforced. */
+    readonly holder: PublicKeyHandle;
+    readonly ttlSeconds?: number;
+    readonly maxDepth?: number;
+    readonly clearance?: Clearance;
+    readonly sessionId?: string;
+    readonly agentId?: string;
+    /** Approval policy for the issued execution session. Defaults to gating every issued tool. */
+    readonly requireApproval?: RequireApproval;
+};
+/** Public view of a session's leaf. Never includes the holder secret. */
+export type SessionInfo = {
+    readonly kind: "execution" | "issuer";
+    /** Hex public key the leaf is bound to. */
+    readonly holderPublicKey: string;
+    /** Hex public key that signed the root of the chain. */
+    readonly rootPublicKey: string;
+    /** 0 for a root session, +1 per delegation. */
+    readonly depth: number;
+    /** Delegation ceiling in force for this leaf. */
+    readonly maxDepth: number;
+    /** True when `depth >= maxDepth`: cannot be narrowed further. */
+    readonly terminal: boolean;
+    /** Unix seconds. */
+    readonly expiresAt: number;
+    readonly tools: readonly string[];
+    /** Warrant ids, root first. */
+    readonly warrantIds: readonly string[];
+    /**
+     * True when this process holds the leaf's holder secret. False for a
+     * session issued or delegated to another agent: `toWire()` works,
+     * `execute` and `narrow` do not.
+     */
+    readonly canAuthorize: boolean;
+    readonly clearance?: number;
+    readonly sessionId?: string;
+    readonly agentId?: string;
+    readonly issuableTools?: readonly string[];
+    readonly maxIssueDepth?: number;
+    readonly requiredApprovers?: readonly string[];
+    readonly minApprovals?: number;
+    readonly approvalGatedTools: readonly string[];
+};
+/** One constrained argument in an `explain()` result. */
+export type ExplainedField = {
+    readonly field: string;
+    /** Core constraint type name, e.g. `"Subpath"`, `"Range"`. */
+    readonly kind: string;
+    /** The constraint as core serializes it. */
+    readonly constraint: unknown;
+    /** Absent when the argument was not supplied. */
+    readonly value?: unknown;
+    readonly satisfied: boolean;
+    readonly reason?: string;
+};
+/** What a session would decide for `tool(args)`, field by field. No proof-of-possession involved. */
+export type Explanation = {
+    readonly tool: string;
+    readonly kind: "execution" | "issuer";
+    readonly outcome: "allow" | "deny";
+    readonly code?: TenuoErrorCode;
+    readonly field?: string;
+    readonly message?: string;
+    readonly toolGranted: boolean;
+    readonly fields: readonly ExplainedField[];
+    /** Arguments the session does not name. Zero-trust policies reject these. */
+    readonly unknownFields: readonly string[];
+    /** Constrained arguments the call did not supply. */
+    readonly missingFields: readonly string[];
+    readonly expired: boolean;
+    readonly expiresAt: number;
+    readonly chainValid: boolean;
+    readonly chainError?: TenuoErrorCode;
 };
 export type DevRoot = {
     readonly kind: "dev-root";
@@ -108,6 +407,11 @@ export type DevRoot = {
      */
     readonly allowInProduction?: boolean;
 };
+/** A stable issuer secret: this process is a control plane. */
+export type IssuerKey = {
+    readonly kind: "issuer-key";
+    readonly secret: Uint8Array;
+};
 export type PublicKeyHandle = {
     readonly kind: "public-key";
     readonly source: "env" | "hex" | "bytes";
@@ -125,11 +429,18 @@ export type SessionFromWireInput = {
 export type NarrowInput = AllowPolicy | SessionAllow;
 export type CreateTenuoOptions = {
     readonly trustedRoots?: readonly PublicKeyHandle[];
-    readonly root?: DevRoot | PublicKeyHandle;
+    /**
+     * `devRoot()` for development; an `issuerKey*` for a control plane that
+     * mints with a stable key; a public key for a verifier. An issuer key
+     * trusts itself plus `trustedRoots`.
+     */
+    readonly root?: DevRoot | IssuerKey | PublicKeyHandle;
     /** Published SignedRevocationList (hex or standard base64). Verified against a trusted root. */
     readonly revocationList?: string | Uint8Array;
+    /** 32-byte holder seed used to sign verifier receipts. Runtime supplies this. */
+    readonly receiptSigner?: Uint8Array;
 };
-export type ApprovalRequest = {
+export type ApprovalRequestSummary = {
     readonly tool: string;
     readonly required: number;
     readonly received: number;
@@ -143,7 +454,53 @@ export type Decision = {
     readonly field?: string;
 } | {
     readonly outcome: "approval_required";
-    readonly request: ApprovalRequest;
+    readonly request: ApprovalRequestSummary;
+};
+export type RevocationListInput = {
+    readonly revoke: readonly string[];
+    /** Monotonic; verifiers refuse an older version. Default 1. */
+    readonly version?: number;
+};
+export type RevocationListInfo = {
+    readonly version: number;
+    readonly issuedAt: number;
+    readonly issuerPublicKey: string;
+    readonly revokedIds: readonly string[];
+    readonly signatureValid: boolean;
+};
+/** Signature authenticity of a receipt. Not authorization. */
+export type ReceiptInfo = {
+    readonly authentic: true;
+    /** Hex key the receipt is signed under — resolve against your own authorizer set. */
+    readonly signerKey: string;
+    readonly outcome: "allow" | "deny";
+    readonly action: string;
+    readonly decisionCode?: string;
+    readonly requestId: string;
+    readonly srlVersion?: number;
+    readonly srlHash?: string;
+    readonly requestHash?: string;
+    readonly policyDefinitionHash?: string;
+    readonly prevReceiptHash?: string;
+    readonly trustedRootsHash?: string;
+};
+/** Root-anchored receipt check: the embedded chain against trusted roots at decision time. */
+export type ReceiptChainInfo = {
+    readonly signerKey: string;
+    readonly outcome: "allow" | "deny";
+    readonly decisionCode?: string;
+    readonly timestamp: number;
+    readonly chainValid: boolean;
+    readonly chainError?: string;
+    readonly corroboratesDenial?: boolean;
+    readonly rootIssuer?: string;
+    readonly leafHolder?: string;
+};
+/** Warrant chain plus proof-of-possession for one call. Transport-agnostic. */
+export type PresentedCall = {
+    readonly warrant: string;
+    readonly signature: string;
+    readonly approvals?: readonly string[];
 };
 export interface Session {
     readonly [Symbol.toStringTag]: "TenuoSession";
@@ -151,6 +508,25 @@ export interface Session {
     toWire(): readonly string[];
     /** SHA-256 of `(warrant_id, tool, canonical args)`. App-level idempotency, not PoP. */
     dedupKey(tool: string, args: Readonly<Record<string, unknown>>): string;
+    /** Holder public key, depth, ceiling, lifetime, tools. Never the secret. */
+    inspect(): SessionInfo;
+    /**
+     * Receipt helpers below are required for `createTenuo.runtime({ receipts:
+     * "collect" })`. Implementers that are not runtime sessions can return
+     * empty snapshots and `0` from acknowledge.
+     */
+    /**
+     * Receipts collected for this session and not yet drained. Empty when the
+     * session was not created by a Runtime with `receipts: "collect"`.
+     */
+    peekReceipts(): readonly string[];
+    /**
+     * Snapshot of collected receipts. Same as `peekReceipts`; nothing is removed
+     * until `acknowledgeReceipts`.
+     */
+    drainReceipts(): readonly string[];
+    /** Remove the first `count` pending receipts. */
+    acknowledgeReceipts(count: number): number;
 }
 export interface Tenuo {
     /**
@@ -159,12 +535,40 @@ export interface Tenuo {
      */
     tool<T extends {
         execute: (args: never) => unknown;
-    }>(inner: T, policy: ToolPolicy): ProtectedTool<T>;
+    }>(inner: T, policy: ToolPolicy<Parameters<T["execute"]>[0]>): ProtectedTool<T>;
     session(input: SessionInput): Session;
     /** Import a warrant minted elsewhere (Rust / Python / another process). */
     sessionFromWire(input: SessionFromWireInput): Session;
     withSession<R>(session: Session, fn: () => R): R;
-    narrow(session: Session, allow: NarrowInput): Session;
+    /**
+     * Child session with less authority. Without options the same holder keeps
+     * it; with `options.holder` it is delegated to another agent's key. Core
+     * rejects any child that is not within its parent before a token exists.
+     */
+    narrow(session: Session, allow: NarrowInput, options?: NarrowOptions): Session;
+    /**
+     * Mint an execution session from an issuer session, signed by the issuer
+     * session's holder. Core checks tools against `issuableTools`, constraints
+     * against `constraintBounds`, clearance, and issue depth. No root key.
+     */
+    issue(issuer: Session, input: IssueInput): Session;
+    /**
+     * Public key of the local issuer (dev root or issuer key). Other processes
+     * put it in `trustedRoots` to accept warrants this context mints.
+     */
+    issuerPublicKey(): PublicKeyHandle;
+    /** What the session would decide for `tool(args)`, field by field. Never runs the tool. */
+    explain(session: Session, tool: string, args: Readonly<Record<string, unknown>>): Explanation;
+    /** Everything an approval service needs to present `tool(args)` to a human. */
+    approvalRequest(session: Session, tool: string, args: Readonly<Record<string, unknown>>): ApprovalRequest;
+    /** Holder-signed proof that this session is the one asking for `tool(args)`. */
+    attestApprovalRequest(session: Session, tool: string, args: Readonly<Record<string, unknown>>): ApprovalContextAttestation;
+    /** Authorize locally, then produce warrant + proof-of-possession for another boundary to verify. */
+    present(session: Session, tool: string, args: Readonly<Record<string, unknown>>, options?: McpAttachOptions): PresentedCall;
+    /** Verify a presented call at any boundary. Resolves with the authorized arguments; the tool must not run otherwise. */
+    verify(presented: PresentedCall, tool: string, args: Readonly<Record<string, unknown>>, options?: McpVerifyOptions): Promise<Readonly<Record<string, unknown>>>;
+    /** Sign a revocation list with this context's issuer key. Load it with `revoke()` where this issuer is trusted. */
+    revocationList(input: RevocationListInput): string;
     /** Load a published SignedRevocationList. Rust verifies the issuer against trusted roots. */
     revoke(list: string | Uint8Array): void;
     /** MCP `_meta.tenuo` attach / verify. No MCP SDK dependency. */
@@ -173,11 +577,7 @@ export interface Tenuo {
 }
 /** Wire envelope Python and TypeScript both read from `params._meta`. */
 export type TenuoMcpMeta = {
-    readonly tenuo: {
-        readonly warrant: string;
-        readonly signature: string;
-        readonly approvals?: readonly string[];
-    };
+    readonly tenuo: PresentedCall;
 };
 export type McpAttachOptions = {
     readonly approvals?: readonly (string | Uint8Array)[];
@@ -267,4 +667,3 @@ export interface TenuoMcp {
     jsonRpcError(error: unknown): McpJsonRpcError;
 }
 export {};
-//# sourceMappingURL=api.d.ts.map