@agent-surface/orpc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wiseair S.r.l.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @agent-surface/orpc
+
+Contextual references to oRPC domain procedures for [agent-surface](https://github.com/Wiseair-srl/agent-surface). A frontend never redefines a domain operation: it **references** one exposed via [orpc-agent](https://orpc-agent.dev) — same identity, same server authority — and adds the three things only the frontend can know: whether it is relevant right now, which inputs come from UI state, and what the user must confirm before it runs.
+
+Docs: https://agent-surface-docs.vercel.app
+
+## Install
+
+```bash
+pnpm add @agent-surface/core @agent-surface/orpc
+```
+
+## Use
+
+```ts
+import { createOrpcAgentBridge } from "@agent-surface/orpc";
+
+export const bridge = createOrpcAgentBridge({
+  client: orpcClient,      // the app's existing typed oRPC client
+  manifest: agentManifest, // which procedures orpc-agent exposes (the ceiling)
+});
+registry.setProcedureExecutor(bridge.executor);
+```
+
+```tsx
+import { useAgentProcedure } from "@agent-surface/orpc/react";
+
+useAgentProcedure(bridge.refs.devices.disable, {
+  when: () => selectedIds.length > 0,
+  unavailableReason: "Select at least one device first",
+  bind: () => ({ deviceIds: selectedIds }), // locked: the agent cannot override it
+  confirmation: "required",
+});
+```
+
+Bound fields are removed from the agent-facing schema and locked by default; `bind()` runs at execution time on live UI state; the merged input is re-validated against the full schema before forwarding; the server re-validates everything regardless.
+
+Full specification: [docs/05](https://github.com/Wiseair-srl/agent-surface/blob/main/docs/05-orpc-integration.md).
+
+MIT © Wiseair S.r.l.

package/dist/chunk-PIGF6NNJ.js

@@ -0,0 +1,211 @@
+// src/bridge.ts
+import {
+  AgentSurfaceError
+} from "@agent-surface/core";
+var BRIDGE_REF = /* @__PURE__ */ Symbol("agent-surface.orpc-ref");
+function walkClient(client, path) {
+  let node = client;
+  for (const segment of path.split(".")) {
+    if (typeof node !== "object" || node === null) return void 0;
+    const next = node[segment];
+    if (next === void 0) return void 0;
+    node = next;
+  }
+  return typeof node === "function" ? node : void 0;
+}
+function isRecord(v) {
+  return typeof v === "object" && v !== null;
+}
+function defaultMapServerError(error) {
+  if (!isRecord(error)) return void 0;
+  const code = error.code ?? error.status;
+  if (code === "UNAUTHORIZED" || code === "FORBIDDEN" || code === 401 || code === 403) {
+    return {
+      code: "NOT_AUTHORIZED",
+      message: "The server rejected this call as not authorized.",
+      retry: "no",
+      details: { origin: "server" }
+    };
+  }
+  const data = isRecord(error.data) ? error.data : void 0;
+  if (code === "APPROVAL_REQUIRED" || data?.approvalRequired === true) {
+    return {
+      code: "CONFIRMATION_REQUIRED",
+      message: "The server requires its own approval for this operation. Wait for approval, then retry.",
+      retry: "with-confirmation",
+      details: {
+        origin: "server",
+        ...typeof data?.approvalId === "string" ? { confirmationId: data.approvalId } : {}
+      }
+    };
+  }
+  return void 0;
+}
+function createOrpcAgentBridge(options) {
+  const client = options.client;
+  const { manifest } = options;
+  const mapError = options.mapServerError ?? defaultMapServerError;
+  const refs = {};
+  for (const [path, tool] of Object.entries(manifest.tools)) {
+    const segments = path.split(".");
+    let node = refs;
+    for (const segment of segments.slice(0, -1)) {
+      node[segment] = node[segment] ?? {};
+      node = node[segment];
+    }
+    const leaf = segments[segments.length - 1];
+    const ref = {
+      id: `domain:${path}`,
+      path,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      ...tool.outputSchema ? { outputSchema: tool.outputSchema } : {},
+      effect: tool.effect,
+      ...tool.requiresApproval !== void 0 ? { requiresApproval: tool.requiresApproval } : {},
+      [BRIDGE_REF]: true,
+      async call(input, ctx) {
+        const fn = walkClient(client, path);
+        if (!fn) {
+          throw new AgentSurfaceError({
+            code: "EXECUTION_FAILED",
+            message: "The server call failed.",
+            retry: "no",
+            details: { reason: "transport" }
+          });
+        }
+        return fn(input, {
+          signal: ctx.signal,
+          ...options.callContext ? { context: options.callContext(ctx) } : {}
+        });
+      }
+    };
+    node[leaf] = ref;
+  }
+  const executor = {
+    paths: Object.keys(manifest.tools),
+    async execute({ path, input, info }) {
+      const tool = manifest.tools[path];
+      const fn = walkClient(client, path);
+      if (!tool || !fn) {
+        throw new AgentSurfaceError({
+          code: "EXECUTION_FAILED",
+          message: "The server call failed.",
+          retry: "no",
+          details: { reason: "transport" }
+        });
+      }
+      try {
+        const output = await fn(input, {
+          signal: info.signal,
+          ...options.callContext ? { context: options.callContext(info) } : {}
+        });
+        return output;
+      } catch (error) {
+        const mapped = mapError(error) ?? defaultMapServerError(error);
+        if (mapped) throw new AgentSurfaceError(mapped, { cause: error });
+        throw new AgentSurfaceError(
+          {
+            code: "EXECUTION_FAILED",
+            message: "The server call failed.",
+            retry: isTransient(error) ? "after-delay" : "no",
+            details: {
+              reason: "transport",
+              ...isTransient(error) ? { transient: true, retryAfterMs: 1e3 } : {}
+            }
+          },
+          { cause: error }
+        );
+      }
+    }
+  };
+  return {
+    refs,
+    executor,
+    hasPath: (path) => path in manifest.tools,
+    manifest
+  };
+}
+function isTransient(error) {
+  if (error instanceof TypeError) return true;
+  return isRecord(error) && error.transient === true;
+}
+function isBridgeRef(value) {
+  return isRecord(value) && value[BRIDGE_REF] === true;
+}
+
+// src/binding.ts
+function reduceInputSchema(full, boundKeys, overridable) {
+  const clone = JSON.parse(JSON.stringify(full));
+  const properties = clone.properties ?? {};
+  const lockedKeys = boundKeys.filter((k) => !overridable.has(k));
+  for (const key of lockedKeys) {
+    delete properties[key];
+  }
+  for (const key of boundKeys) {
+    if (!overridable.has(key)) continue;
+    const prop = properties[key];
+    if (typeof prop === "object" && prop !== null) {
+      const record = prop;
+      const note = "Defaults to the current UI value at execution time when omitted.";
+      record.description = typeof record.description === "string" && record.description.length > 0 ? `${record.description} ${note}` : note;
+    }
+  }
+  if (Array.isArray(clone.required)) {
+    const removed = new Set(boundKeys);
+    clone.required = clone.required.filter((k) => !removed.has(k));
+    if (clone.required.length === 0) delete clone.required;
+  }
+  if (Object.keys(properties).length === 0) {
+    return { type: "object", properties: {}, additionalProperties: false };
+  }
+  clone.properties = properties;
+  return clone;
+}
+function bindAgentProcedure(ref, config) {
+  let boundKeys = [];
+  if (config?.bind) {
+    try {
+      boundKeys = Object.keys(config.bind() ?? {});
+    } catch (err) {
+      console.warn(
+        `[agent-surface] bind() threw while capturing bound keys for ${ref.id}; treating as unbound`,
+        err
+      );
+    }
+  }
+  const overridable = /* @__PURE__ */ new Set([...config?.overridableFields ?? []]);
+  const lockedKeys = boundKeys.filter((k) => !overridable.has(k));
+  return {
+    kind: "procedure-binding",
+    ref: {
+      id: ref.id,
+      path: ref.path,
+      description: ref.description,
+      inputSchema: ref.inputSchema,
+      ...ref.outputSchema ? { outputSchema: ref.outputSchema } : {},
+      effect: ref.effect,
+      ...ref.requiresApproval !== void 0 ? { requiresApproval: ref.requiresApproval } : {}
+    },
+    config: {
+      ...config?.when ? { when: config.when } : {},
+      ...config?.unavailableReason !== void 0 ? { unavailableReason: config.unavailableReason } : {},
+      ...config?.bind ? { bind: config.bind } : {},
+      ...config?.overridableFields ? { overridableFields: config.overridableFields } : {},
+      ...config?.confirmation ? { confirmation: config.confirmation } : {},
+      ...config?.policies ? { policies: config.policies } : {},
+      ...config?.describe ? { describe: config.describe } : {},
+      ...config?.meta ? { meta: config.meta } : {}
+    },
+    boundKeys,
+    lockedKeys,
+    reducedInputSchema: reduceInputSchema(ref.inputSchema, boundKeys, overridable)
+  };
+}
+
+export {
+  createOrpcAgentBridge,
+  isBridgeRef,
+  reduceInputSchema,
+  bindAgentProcedure
+};
+//# sourceMappingURL=chunk-PIGF6NNJ.js.map

package/dist/chunk-PIGF6NNJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridge.ts","../src/binding.ts"],"sourcesContent":["import {\n  AgentSurfaceError,\n  type AgentProcedureEffect,\n  type AgentProcedureExecutor,\n  type JsonSchema,\n  type JsonValue,\n  type ProcedureCallInfo,\n} from \"@agent-surface/core\";\n\n/**\n * [Experimental] Minimal contract this package needs from orpc-agent\n * (docs/05, OQ-1). Derivable from a build-time export of the capability\n * registry inventory or a bootstrap `runtime.describe()` fetch; hand-writing\n * it remains the escape hatch.\n */\nexport interface OrpcAgentManifest {\n  tools: Record<\n    string, // key: dot path, \"devices.disable\"\n    {\n      description: string;\n      inputSchema: JsonSchema;\n      outputSchema?: JsonSchema;\n      effect: AgentProcedureEffect;\n      /** Server-declared flags the client must respect (e.g. approval required). */\n      requiresApproval?: boolean;\n    }\n  >;\n}\n\nexport interface AgentProcedureRef<TIn extends object, TOut> {\n  readonly id: string; // \"domain:devices.disable\"\n  readonly path: string; // \"devices.disable\"\n  readonly description: string;\n  readonly inputSchema: JsonSchema;\n  readonly outputSchema?: JsonSchema;\n  readonly effect: AgentProcedureEffect;\n  readonly requiresApproval?: boolean;\n  call(input: TIn, ctx: ProcedureCallInfo): Promise<TOut>;\n  /** Phantom generics carrier (never read at runtime). */\n  readonly __types?: { input: TIn; output: TOut };\n}\n\nexport const BRIDGE_REF: unique symbol = Symbol(\"agent-surface.orpc-ref\");\n\n/** oRPC-style typed client: nested records of callable procedures. */\nexport type AnyClientLeaf = (input: never, options?: unknown) => Promise<unknown>;\nexport interface ClientTree {\n  [key: string]: AnyClientLeaf | ClientTree;\n}\n\nexport type RefsFor<TClient> = {\n  [K in keyof TClient]: TClient[K] extends (input: infer I, ...rest: never[]) => Promise<infer O>\n    ? AgentProcedureRef<I & object, O>\n    : RefsFor<TClient[K]>;\n};\n\nexport interface OrpcAgentBridgeOptions<TClient extends object> {\n  /** The app's existing typed oRPC client (the user's session transport). */\n  client: TClient;\n  /** Which procedures orpc-agent exposes — the exposure CEILING (docs/05). */\n  manifest: OrpcAgentManifest;\n  /** Forward confirmation evidence / metadata into the call context. */\n  callContext?: (ctx: ProcedureCallInfo) => Record<string, unknown>;\n  /** Escape hatch: map raw server errors to typed payloads. */\n  mapServerError?: (\n    error: unknown,\n  ) => import(\"@agent-surface/core\").AgentCapabilityErrorPayload | undefined;\n}\n\nexport interface OrpcAgentBridge<TClient extends object> {\n  /** Typed refs mirroring the router path — only manifest paths exist. */\n  refs: RefsFor<TClient>;\n  /** Install via registry.setProcedureExecutor(bridge.executor). */\n  executor: AgentProcedureExecutor;\n  hasPath(path: string): boolean;\n  manifest: OrpcAgentManifest;\n}\n\nfunction walkClient(client: ClientTree, path: string): AnyClientLeaf | undefined {\n  let node: ClientTree | AnyClientLeaf = client;\n  for (const segment of path.split(\".\")) {\n    if (typeof node !== \"object\" || node === null) return undefined;\n    const next: ClientTree | AnyClientLeaf | undefined = (node as ClientTree)[segment];\n    if (next === undefined) return undefined;\n    node = next;\n  }\n  return typeof node === \"function\" ? node : undefined;\n}\n\nfunction isRecord(v: unknown): v is Record<string, unknown> {\n  return typeof v === \"object\" && v !== null;\n}\n\nfunction defaultMapServerError(\n  error: unknown,\n): import(\"@agent-surface/core\").AgentCapabilityErrorPayload | undefined {\n  if (!isRecord(error)) return undefined;\n  const code = error.code ?? error.status;\n  if (code === \"UNAUTHORIZED\" || code === \"FORBIDDEN\" || code === 401 || code === 403) {\n    return {\n      code: \"NOT_AUTHORIZED\",\n      message: \"The server rejected this call as not authorized.\",\n      retry: \"no\",\n      details: { origin: \"server\" },\n    };\n  }\n  const data = isRecord(error.data) ? error.data : undefined;\n  if (code === \"APPROVAL_REQUIRED\" || data?.approvalRequired === true) {\n    return {\n      code: \"CONFIRMATION_REQUIRED\",\n      message:\n        \"The server requires its own approval for this operation. Wait for approval, then retry.\",\n      retry: \"with-confirmation\",\n      details: {\n        origin: \"server\",\n        ...(typeof data?.approvalId === \"string\" ? { confirmationId: data.approvalId } : {}),\n      },\n    };\n  }\n  return undefined;\n}\n\n/**\n * Creates the manifest-gated bridge between the app's oRPC client and the\n * agent surface. The frontend can narrow domain exposure (by not\n * referencing) but can never widen it — the manifest is the ceiling.\n */\nexport function createOrpcAgentBridge<TClient extends object>(\n  options: OrpcAgentBridgeOptions<TClient>,\n): OrpcAgentBridge<TClient> {\n  const client = options.client as ClientTree;\n  const { manifest } = options;\n  const mapError = options.mapServerError ?? defaultMapServerError;\n\n  const refs: Record<string, unknown> = {};\n  for (const [path, tool] of Object.entries(manifest.tools)) {\n    const segments = path.split(\".\");\n    let node = refs;\n    for (const segment of segments.slice(0, -1)) {\n      node[segment] = node[segment] ?? {};\n      node = node[segment] as Record<string, unknown>;\n    }\n    const leaf = segments[segments.length - 1]!;\n    const ref: AgentProcedureRef<object, unknown> & { [BRIDGE_REF]: true } = {\n      id: `domain:${path}`,\n      path,\n      description: tool.description,\n      inputSchema: tool.inputSchema,\n      ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),\n      effect: tool.effect,\n      ...(tool.requiresApproval !== undefined ? { requiresApproval: tool.requiresApproval } : {}),\n      [BRIDGE_REF]: true,\n      async call(input: object, ctx: ProcedureCallInfo): Promise<unknown> {\n        const fn = walkClient(client, path);\n        if (!fn) {\n          throw new AgentSurfaceError({\n            code: \"EXECUTION_FAILED\",\n            message: \"The server call failed.\",\n            retry: \"no\",\n            details: { reason: \"transport\" },\n          });\n        }\n        return fn(input as never, {\n          signal: ctx.signal,\n          ...(options.callContext ? { context: options.callContext(ctx) } : {}),\n        });\n      },\n    };\n    node[leaf] = ref;\n  }\n\n  const executor: AgentProcedureExecutor = {\n    paths: Object.keys(manifest.tools),\n    async execute({ path, input, info }): Promise<JsonValue> {\n      const tool = manifest.tools[path];\n      const fn = walkClient(client, path);\n      if (!tool || !fn) {\n        throw new AgentSurfaceError({\n          code: \"EXECUTION_FAILED\",\n          message: \"The server call failed.\",\n          retry: \"no\",\n          details: { reason: \"transport\" },\n        });\n      }\n      try {\n        const output = await fn(input as never, {\n          signal: info.signal,\n          ...(options.callContext ? { context: options.callContext(info) } : {}),\n        });\n        return output as JsonValue;\n      } catch (error) {\n        const mapped = mapError(error) ?? defaultMapServerError(error);\n        if (mapped) throw new AgentSurfaceError(mapped, { cause: error });\n        // Transport/procedure errors are SANITIZED (docs/05 step 5, docs/07):\n        // never pass error.message through to the agent.\n        throw new AgentSurfaceError(\n          {\n            code: \"EXECUTION_FAILED\",\n            message: \"The server call failed.\",\n            retry: isTransient(error) ? \"after-delay\" : \"no\",\n            details: {\n              reason: \"transport\",\n              ...(isTransient(error) ? { transient: true, retryAfterMs: 1000 } : {}),\n            },\n          },\n          { cause: error },\n        );\n      }\n    },\n  };\n\n  return {\n    refs: refs as RefsFor<TClient>,\n    executor,\n    hasPath: (path) => path in manifest.tools,\n    manifest,\n  };\n}\n\nfunction isTransient(error: unknown): boolean {\n  if (error instanceof TypeError) return true; // fetch network failure shape\n  return isRecord(error) && error.transient === true;\n}\n\nexport function isBridgeRef(value: unknown): value is AgentProcedureRef<object, unknown> {\n  return isRecord(value) && (value as { [BRIDGE_REF]?: unknown })[BRIDGE_REF] === true;\n}\n","import type {\n  AgentPolicy,\n  AgentProcedureBinding,\n  JsonSchema,\n  JsonValue,\n} from \"@agent-surface/core\";\nimport type { AgentProcedureRef } from \"./bridge.js\";\n\nexport interface AgentProcedureBindingConfig<\n  TIn extends object,\n  TBound extends Partial<TIn>,\n> {\n  /** Contextual availability; same semantics as capability `when`. */\n  when?: () => boolean;\n  unavailableReason?: string | (() => string);\n  /**\n   * UI-derived inputs. Evaluated at EXECUTION time (never cached from\n   * discovery). Throwing or returning schema-invalid values fails the\n   * invocation with PRECONDITION_FAILED (details.reason: \"binding-failed\").\n   */\n  bind?: () => TBound;\n  /**\n   * Bound fields the agent MAY override. Default: none — bound fields are\n   * locked (D8). Use sparingly.\n   */\n  overridableFields?: ReadonlyArray<keyof TBound & string>;\n  /** Escalate (never lower) the manifest's confirmation requirement. */\n  confirmation?: \"optional\" | \"required\";\n  /** Extra frontend policies (client-side, advisory). */\n  policies?: AgentPolicy[];\n  /** Contextual description appended to the manifest description. */\n  describe?: () => string;\n  meta?: Record<string, JsonValue>;\n}\n\n/**\n * D7 rule 1 — agent-facing schema surgery: locked bound keys are removed from\n * `properties` and `required`; overridable bound keys stay, annotated as\n * defaulting to the current UI value. All-bound ⇒ empty closed object schema.\n */\nexport function reduceInputSchema(\n  full: JsonSchema,\n  boundKeys: ReadonlyArray<string>,\n  overridable: ReadonlySet<string>,\n): JsonSchema {\n  const clone = JSON.parse(JSON.stringify(full)) as JsonSchema;\n  const properties = (clone.properties ?? {}) as Record<string, unknown>;\n  const lockedKeys = boundKeys.filter((k) => !overridable.has(k));\n\n  for (const key of lockedKeys) {\n    delete properties[key];\n  }\n  for (const key of boundKeys) {\n    if (!overridable.has(key)) continue;\n    const prop = properties[key];\n    if (typeof prop === \"object\" && prop !== null) {\n      const record = prop as Record<string, unknown>;\n      const note = \"Defaults to the current UI value at execution time when omitted.\";\n      record.description =\n        typeof record.description === \"string\" && record.description.length > 0\n          ? `${record.description} ${note}`\n          : note;\n    }\n  }\n  if (Array.isArray(clone.required)) {\n    // Locked keys are supplied by the binding; overridable keys become\n    // optional for the agent (the bound value applies when omitted).\n    const removed = new Set(boundKeys);\n    clone.required = (clone.required as string[]).filter((k) => !removed.has(k));\n    if ((clone.required as string[]).length === 0) delete clone.required;\n  }\n  if (Object.keys(properties).length === 0) {\n    return { type: \"object\", properties: {}, additionalProperties: false };\n  }\n  clone.properties = properties;\n  return clone;\n}\n\n/**\n * Creates a procedure binding for AgentComponentDefinition.procedures or the\n * React hook. The binding's identity IS the procedure's identity — there is\n * deliberately no place to put an execute handler here (docs/05).\n */\nexport function bindAgentProcedure<\n  TIn extends object,\n  TOut,\n  TBound extends Partial<TIn> = Partial<TIn>,\n>(\n  ref: AgentProcedureRef<TIn, TOut>,\n  config?: AgentProcedureBindingConfig<TIn, TBound>,\n): AgentProcedureBinding<TIn, TOut> {\n  // Bound-key capture at binding creation: bind() must be key-stable; a\n  // throwing bind() here degrades to \"no bound keys\" with a warning.\n  let boundKeys: string[] = [];\n  if (config?.bind) {\n    try {\n      boundKeys = Object.keys(config.bind() ?? {});\n    } catch (err) {\n      // eslint-disable-next-line no-console\n      console.warn(\n        `[agent-surface] bind() threw while capturing bound keys for ${ref.id}; treating as unbound`,\n        err,\n      );\n    }\n  }\n  const overridable = new Set<string>([...(config?.overridableFields ?? [])]);\n  const lockedKeys = boundKeys.filter((k) => !overridable.has(k));\n\n  return {\n    kind: \"procedure-binding\",\n    ref: {\n      id: ref.id,\n      path: ref.path,\n      description: ref.description,\n      inputSchema: ref.inputSchema,\n      ...(ref.outputSchema ? { outputSchema: ref.outputSchema } : {}),\n      effect: ref.effect,\n      ...(ref.requiresApproval !== undefined ? { requiresApproval: ref.requiresApproval } : {}),\n    },\n    config: {\n      ...(config?.when ? { when: config.when } : {}),\n      ...(config?.unavailableReason !== undefined\n        ? { unavailableReason: config.unavailableReason }\n        : {}),\n      ...(config?.bind ? { bind: config.bind as () => Record<string, JsonValue> } : {}),\n      ...(config?.overridableFields\n        ? { overridableFields: config.overridableFields as ReadonlyArray<string> }\n        : {}),\n      ...(config?.confirmation ? { confirmation: config.confirmation } : {}),\n      ...(config?.policies ? { policies: config.policies } : {}),\n      ...(config?.describe ? { describe: config.describe } : {}),\n      ...(config?.meta ? { meta: config.meta } : {}),\n    },\n    boundKeys,\n    lockedKeys,\n    reducedInputSchema: reduceInputSchema(ref.inputSchema, boundKeys, overridable),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import * as _agent_surface_core from '@agent-surface/core';
+import { JsonSchema, AgentProcedureEffect, ProcedureCallInfo, AgentProcedureExecutor, AgentPolicy, JsonValue, AgentProcedureBinding } from '@agent-surface/core';
+
+/**
+ * [Experimental] Minimal contract this package needs from orpc-agent
+ * (docs/05, OQ-1). Derivable from a build-time export of the capability
+ * registry inventory or a bootstrap `runtime.describe()` fetch; hand-writing
+ * it remains the escape hatch.
+ */
+interface OrpcAgentManifest {
+    tools: Record<string, // key: dot path, "devices.disable"
+    {
+        description: string;
+        inputSchema: JsonSchema;
+        outputSchema?: JsonSchema;
+        effect: AgentProcedureEffect;
+        /** Server-declared flags the client must respect (e.g. approval required). */
+        requiresApproval?: boolean;
+    }>;
+}
+interface AgentProcedureRef<TIn extends object, TOut> {
+    readonly id: string;
+    readonly path: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    readonly outputSchema?: JsonSchema;
+    readonly effect: AgentProcedureEffect;
+    readonly requiresApproval?: boolean;
+    call(input: TIn, ctx: ProcedureCallInfo): Promise<TOut>;
+    /** Phantom generics carrier (never read at runtime). */
+    readonly __types?: {
+        input: TIn;
+        output: TOut;
+    };
+}
+/** oRPC-style typed client: nested records of callable procedures. */
+type AnyClientLeaf = (input: never, options?: unknown) => Promise<unknown>;
+interface ClientTree {
+    [key: string]: AnyClientLeaf | ClientTree;
+}
+type RefsFor<TClient> = {
+    [K in keyof TClient]: TClient[K] extends (input: infer I, ...rest: never[]) => Promise<infer O> ? AgentProcedureRef<I & object, O> : RefsFor<TClient[K]>;
+};
+interface OrpcAgentBridgeOptions<TClient extends object> {
+    /** The app's existing typed oRPC client (the user's session transport). */
+    client: TClient;
+    /** Which procedures orpc-agent exposes — the exposure CEILING (docs/05). */
+    manifest: OrpcAgentManifest;
+    /** Forward confirmation evidence / metadata into the call context. */
+    callContext?: (ctx: ProcedureCallInfo) => Record<string, unknown>;
+    /** Escape hatch: map raw server errors to typed payloads. */
+    mapServerError?: (error: unknown) => _agent_surface_core.AgentCapabilityErrorPayload | undefined;
+}
+interface OrpcAgentBridge<TClient extends object> {
+    /** Typed refs mirroring the router path — only manifest paths exist. */
+    refs: RefsFor<TClient>;
+    /** Install via registry.setProcedureExecutor(bridge.executor). */
+    executor: AgentProcedureExecutor;
+    hasPath(path: string): boolean;
+    manifest: OrpcAgentManifest;
+}
+/**
+ * Creates the manifest-gated bridge between the app's oRPC client and the
+ * agent surface. The frontend can narrow domain exposure (by not
+ * referencing) but can never widen it — the manifest is the ceiling.
+ */
+declare function createOrpcAgentBridge<TClient extends object>(options: OrpcAgentBridgeOptions<TClient>): OrpcAgentBridge<TClient>;
+declare function isBridgeRef(value: unknown): value is AgentProcedureRef<object, unknown>;
+
+interface AgentProcedureBindingConfig<TIn extends object, TBound extends Partial<TIn>> {
+    /** Contextual availability; same semantics as capability `when`. */
+    when?: () => boolean;
+    unavailableReason?: string | (() => string);
+    /**
+     * UI-derived inputs. Evaluated at EXECUTION time (never cached from
+     * discovery). Throwing or returning schema-invalid values fails the
+     * invocation with PRECONDITION_FAILED (details.reason: "binding-failed").
+     */
+    bind?: () => TBound;
+    /**
+     * Bound fields the agent MAY override. Default: none — bound fields are
+     * locked (D8). Use sparingly.
+     */
+    overridableFields?: ReadonlyArray<keyof TBound & string>;
+    /** Escalate (never lower) the manifest's confirmation requirement. */
+    confirmation?: "optional" | "required";
+    /** Extra frontend policies (client-side, advisory). */
+    policies?: AgentPolicy[];
+    /** Contextual description appended to the manifest description. */
+    describe?: () => string;
+    meta?: Record<string, JsonValue>;
+}
+/**
+ * D7 rule 1 — agent-facing schema surgery: locked bound keys are removed from
+ * `properties` and `required`; overridable bound keys stay, annotated as
+ * defaulting to the current UI value. All-bound ⇒ empty closed object schema.
+ */
+declare function reduceInputSchema(full: JsonSchema, boundKeys: ReadonlyArray<string>, overridable: ReadonlySet<string>): JsonSchema;
+/**
+ * Creates a procedure binding for AgentComponentDefinition.procedures or the
+ * React hook. The binding's identity IS the procedure's identity — there is
+ * deliberately no place to put an execute handler here (docs/05).
+ */
+declare function bindAgentProcedure<TIn extends object, TOut, TBound extends Partial<TIn> = Partial<TIn>>(ref: AgentProcedureRef<TIn, TOut>, config?: AgentProcedureBindingConfig<TIn, TBound>): AgentProcedureBinding<TIn, TOut>;
+
+export { type AgentProcedureBindingConfig, type AgentProcedureRef, type ClientTree, type OrpcAgentBridge, type OrpcAgentBridgeOptions, type OrpcAgentManifest, type RefsFor, bindAgentProcedure, createOrpcAgentBridge, isBridgeRef, reduceInputSchema };

package/dist/index.js

@@ -0,0 +1,13 @@
+import {
+  bindAgentProcedure,
+  createOrpcAgentBridge,
+  isBridgeRef,
+  reduceInputSchema
+} from "./chunk-PIGF6NNJ.js";
+export {
+  bindAgentProcedure,
+  createOrpcAgentBridge,
+  isBridgeRef,
+  reduceInputSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/react.d.ts

@@ -0,0 +1,16 @@
+import { AgentProcedureRef, AgentProcedureBindingConfig } from './index.js';
+import '@agent-surface/core';
+
+/**
+ * Declares that an EXISTING domain procedure is relevant in the current view,
+ * optionally pre-filling inputs from UI state (docs/05). Lifecycle mirrors
+ * useAgentComponent: registers in an effect, unregisters on unmount;
+ * bind/when/describe are read through the latest ref (fresh at execution);
+ * availability is pushed on change.
+ *
+ * A ref not backed by the manifest registers NOTHING — the manifest, produced
+ * by the backend's orpc-agent configuration, is the exposure ceiling.
+ */
+declare function useAgentProcedure<TIn extends object, TOut, TBound extends Partial<TIn> = Partial<TIn>>(ref: AgentProcedureRef<TIn, TOut>, config?: AgentProcedureBindingConfig<TIn, TBound>): void;
+
+export { useAgentProcedure };

package/dist/react.js

@@ -0,0 +1,109 @@
+import {
+  bindAgentProcedure,
+  isBridgeRef
+} from "./chunk-PIGF6NNJ.js";
+
+// src/react.ts
+import { useEffect, useRef, useState } from "react";
+import {
+  useAgentSurface,
+  unstable_readRenderScopeContext
+} from "@agent-surface/react";
+var hookInstanceCounter = 0;
+function useAgentProcedure(ref, config) {
+  const registry = useAgentSurface();
+  const latestConfig = useRef(config);
+  latestConfig.current = config;
+  const contextLink = unstable_readRenderScopeContext();
+  const contextRef = useRef(contextLink);
+  contextRef.current = contextLink ?? contextRef.current;
+  const instanceRef = useRef(null);
+  if (instanceRef.current === null) {
+    hookInstanceCounter += 1;
+    instanceRef.current = `ref-${hookInstanceCounter}`;
+  }
+  const handleRef = useRef(null);
+  const lastPushed = useRef(null);
+  const [, setStatus] = useState("pending");
+  const manifestBacked = isBridgeRef(ref);
+  const refId = ref?.id;
+  useEffect(() => {
+    if (!manifestBacked) {
+      console.error(
+        `[agent-surface] useAgentProcedure: ref "${String(refId)}" is not backed by the orpc-agent manifest \u2014 registering nothing. The manifest is the exposure ceiling.`
+      );
+      return;
+    }
+    const delegating = {
+      when: () => {
+        const when = latestConfig.current?.when;
+        return when ? when() !== false : true;
+      },
+      unavailableReason: () => {
+        const reason = latestConfig.current?.unavailableReason;
+        try {
+          if (typeof reason === "function") return reason();
+          if (typeof reason === "string") return reason;
+        } catch {
+        }
+        return "Currently unavailable";
+      },
+      ...latestConfig.current?.bind ? { bind: () => latestConfig.current?.bind?.() ?? {} } : {},
+      ...latestConfig.current?.overridableFields ? { overridableFields: latestConfig.current.overridableFields } : {},
+      ...latestConfig.current?.confirmation ? { confirmation: latestConfig.current.confirmation } : {},
+      ...latestConfig.current?.policies ? { policies: latestConfig.current.policies } : {},
+      ...latestConfig.current?.describe ? { describe: () => latestConfig.current?.describe?.() ?? "" } : {},
+      ...latestConfig.current?.meta ? { meta: latestConfig.current.meta } : {}
+    };
+    const binding = bindAgentProcedure(ref, delegating);
+    if (contextRef.current) binding.contextLink = { ...contextRef.current };
+    const handle = registry.register({
+      // Procedure-only registration: excluded from snapshot.components.
+      type: "orpc-ref",
+      instanceId: instanceRef.current,
+      description: `Contextual reference to ${ref.path}`,
+      procedures: [binding]
+    });
+    handleRef.current = handle;
+    lastPushed.current = null;
+    setStatus(handle.status === "active" ? "active" : "rejected");
+    return () => {
+      handle.unregister();
+      handleRef.current = null;
+    };
+  }, [registry, refId, manifestBacked]);
+  useEffect(() => {
+    const handle = handleRef.current;
+    if (!handle || handle.status !== "active" || !manifestBacked) return;
+    const when = latestConfig.current?.when;
+    let available = true;
+    try {
+      available = when ? when() !== false : true;
+    } catch {
+      available = false;
+    }
+    if (lastPushed.current === available) return;
+    lastPushed.current = available;
+    const reason = latestConfig.current?.unavailableReason;
+    let reasonText;
+    if (!available) {
+      try {
+        reasonText = typeof reason === "function" ? reason() : reason;
+      } catch {
+        reasonText = void 0;
+      }
+    }
+    handle.update({
+      availability: {
+        [ref.path]: {
+          available,
+          ...reasonText !== void 0 ? { reason: reasonText } : {}
+        }
+      }
+    });
+  });
+}
+export {
+  useAgentProcedure
+};
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport type { AgentRegistrationHandle } from \"@agent-surface/core\";\nimport {\n  useAgentSurface,\n  unstable_readRenderScopeContext,\n} from \"@agent-surface/react\";\nimport type { AgentProcedureRef } from \"./bridge.js\";\nimport { isBridgeRef } from \"./bridge.js\";\nimport { bindAgentProcedure, type AgentProcedureBindingConfig } from \"./binding.js\";\n\nlet hookInstanceCounter = 0;\n\n/**\n * Declares that an EXISTING domain procedure is relevant in the current view,\n * optionally pre-filling inputs from UI state (docs/05). Lifecycle mirrors\n * useAgentComponent: registers in an effect, unregisters on unmount;\n * bind/when/describe are read through the latest ref (fresh at execution);\n * availability is pushed on change.\n *\n * A ref not backed by the manifest registers NOTHING — the manifest, produced\n * by the backend's orpc-agent configuration, is the exposure ceiling.\n */\nexport function useAgentProcedure<\n  TIn extends object,\n  TOut,\n  TBound extends Partial<TIn> = Partial<TIn>,\n>(ref: AgentProcedureRef<TIn, TOut>, config?: AgentProcedureBindingConfig<TIn, TBound>): void {\n  const registry = useAgentSurface();\n\n  const latestConfig = useRef(config);\n  latestConfig.current = config;\n\n  // Capture the render-scope link (owning useAgentComponent, when present)\n  // during render; the registration effect uses the captured value.\n  const contextLink = unstable_readRenderScopeContext();\n  const contextRef = useRef(contextLink);\n  contextRef.current = contextLink ?? contextRef.current;\n\n  const instanceRef = useRef<string | null>(null);\n  if (instanceRef.current === null) {\n    hookInstanceCounter += 1;\n    instanceRef.current = `ref-${hookInstanceCounter}`;\n  }\n\n  const handleRef = useRef<AgentRegistrationHandle | null>(null);\n  const lastPushed = useRef<boolean | null>(null);\n  const [, setStatus] = useState<\"pending\" | \"active\" | \"rejected\">(\"pending\");\n\n  const manifestBacked = isBridgeRef(ref);\n  const refId = ref?.id;\n\n  useEffect(() => {\n    if (!manifestBacked) {\n      // Exposure gating (docs/05): register nothing, say so loudly.\n      // eslint-disable-next-line no-console\n      console.error(\n        `[agent-surface] useAgentProcedure: ref \"${String(refId)}\" is not backed by the orpc-agent manifest — registering nothing. The manifest is the exposure ceiling.`,\n      );\n      return;\n    }\n\n    const delegating: AgentProcedureBindingConfig<TIn, TBound> = {\n      when: () => {\n        const when = latestConfig.current?.when;\n        return when ? when() !== false : true;\n      },\n      unavailableReason: () => {\n        const reason = latestConfig.current?.unavailableReason;\n        try {\n          if (typeof reason === \"function\") return reason();\n          if (typeof reason === \"string\") return reason;\n        } catch {\n          /* fall through */\n        }\n        return \"Currently unavailable\";\n      },\n      ...(latestConfig.current?.bind\n        ? { bind: () => (latestConfig.current?.bind?.() ?? {}) as TBound }\n        : {}),\n      ...(latestConfig.current?.overridableFields\n        ? { overridableFields: latestConfig.current.overridableFields }\n        : {}),\n      ...(latestConfig.current?.confirmation\n        ? { confirmation: latestConfig.current.confirmation }\n        : {}),\n      ...(latestConfig.current?.policies ? { policies: latestConfig.current.policies } : {}),\n      ...(latestConfig.current?.describe\n        ? { describe: () => latestConfig.current?.describe?.() ?? \"\" }\n        : {}),\n      ...(latestConfig.current?.meta ? { meta: latestConfig.current.meta } : {}),\n    };\n\n    const binding = bindAgentProcedure(ref, delegating);\n    if (contextRef.current) binding.contextLink = { ...contextRef.current };\n\n    const handle = registry.register({\n      // Procedure-only registration: excluded from snapshot.components.\n      type: \"orpc-ref\",\n      instanceId: instanceRef.current!,\n      description: `Contextual reference to ${ref.path}`,\n      procedures: [binding],\n    });\n    handleRef.current = handle;\n    lastPushed.current = null;\n    setStatus(handle.status === \"active\" ? \"active\" : \"rejected\");\n\n    return () => {\n      handle.unregister();\n      handleRef.current = null;\n    };\n  }, [registry, refId, manifestBacked]);\n\n  // Push availability when the `when` predicate flips (per commit).\n  useEffect(() => {\n    const handle = handleRef.current;\n    if (!handle || handle.status !== \"active\" || !manifestBacked) return;\n    const when = latestConfig.current?.when;\n    let available = true;\n    try {\n      available = when ? when() !== false : true;\n    } catch {\n      available = false;\n    }\n    if (lastPushed.current === available) return;\n    lastPushed.current = available;\n    const reason = latestConfig.current?.unavailableReason;\n    let reasonText: string | undefined;\n    if (!available) {\n      try {\n        reasonText = typeof reason === \"function\" ? reason() : reason;\n      } catch {\n        reasonText = undefined;\n      }\n    }\n    handle.update({\n      availability: {\n        [ref.path]: {\n          available,\n          ...(reasonText !== undefined ? { reason: reasonText } : {}),\n        },\n      },\n    });\n  });\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@agent-surface/orpc",
+  "version": "0.1.0",
+  "description": "Contextual references to oRPC domain procedures exposed via orpc-agent — binding, gating, executor bridge",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@agent-surface/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.2",
+    "@agent-surface/react": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@agent-surface/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "@types/react": "^19.1.9",
+    "@testing-library/react": "^16.3.0",
+    "zod": "^4.1.5",
+    "@agent-surface/react": "0.1.0",
+    "@agent-surface/testing": "0.1.0"
+  },
+  "author": "Paolo Barbato",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wiseair-srl/agent-surface.git",
+    "directory": "packages/orpc"
+  },
+  "homepage": "https://agent-surface-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/Wiseair-srl/agent-surface/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agent-surface",
+    "agent",
+    "ai",
+    "llm",
+    "frontend",
+    "capabilities",
+    "typescript",
+    "orpc",
+    "orpc-agent",
+    "rpc"
+  ],
+  "size-limit": [
+    {
+      "path": "dist/index.js",
+      "limit": "8 kB",
+      "ignore": [
+        "@agent-surface/core",
+        "@agent-surface/react",
+        "react"
+      ]
+    }
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "size": "size-limit"
+  }
+}