@agent-surface/orpc 0.13.0 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -33
- package/dist/react.d.ts +3 -1
- package/dist/react.js +25 -4
- package/dist/react.js.map +1 -1
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,40 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@agent-surface/orpc`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
Docs: https://agent-surface-docs.vercel.app
|
|
6
|
-
|
|
7
|
-
## Install
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
pnpm add @agent-surface/core @agent-surface/orpc
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Use
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
import { createOrpcAgentBridge } from "@agent-surface/orpc";
|
|
17
|
-
|
|
18
|
-
export const bridge = createOrpcAgentBridge({
|
|
19
|
-
client: orpcClient, // the app's existing typed oRPC client
|
|
20
|
-
manifest: agentManifest, // which procedures orpc-agent exposes (the ceiling)
|
|
21
|
-
});
|
|
22
|
-
registry.setProcedureExecutor(bridge.executor);
|
|
23
|
-
```
|
|
3
|
+
Bind compiler-declared domain procedures to authoritative oRPC client paths.
|
|
24
4
|
|
|
25
5
|
```tsx
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
useAgentProcedure(bridge.refs.devices.disable, {
|
|
6
|
+
useAgentProcedure(devicesDisableContract, bridge.refs.devices.disable, {
|
|
7
|
+
bind: () => ({ deviceIds: selectedIds }),
|
|
29
8
|
when: () => selectedIds.length > 0,
|
|
30
|
-
unavailableReason: "Select at least one device first",
|
|
31
|
-
bind: () => ({ deviceIds: selectedIds }), // locked: the agent cannot override it
|
|
32
|
-
confirmation: "required",
|
|
33
9
|
});
|
|
34
10
|
```
|
|
35
11
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
Full specification: [docs/05](https://github.com/Wiseair-srl/agent-surface/blob/main/docs/05-orpc-integration.md).
|
|
39
|
-
|
|
40
|
-
MIT © Wiseair S.r.l.
|
|
12
|
+
The compiled contract owns identity/schemas/effect/confirmation. The bridge owns execution and server error mapping. See [oRPC integration](../../docs/05-orpc-integration.md).
|
package/dist/react.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
+
import { JsonValue, AgentProcedureContract } from '@agent-surface/core';
|
|
1
2
|
import { AgentProcedureRef, AgentProcedureBindingConfig } from './index.js';
|
|
2
|
-
import '@agent-surface/core';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Declares that an EXISTING domain procedure is relevant in the current view,
|
|
@@ -11,6 +11,8 @@ import '@agent-surface/core';
|
|
|
11
11
|
* A ref not backed by the manifest registers NOTHING — the manifest, produced
|
|
12
12
|
* by the backend's orpc-agent configuration, is the exposure ceiling.
|
|
13
13
|
*/
|
|
14
|
+
declare function useAgentProcedure<TIn extends Record<string, JsonValue>, TOut extends JsonValue, TBound extends Partial<TIn> = Partial<TIn>>(contract: AgentProcedureContract<TIn, TOut>, ref: AgentProcedureRef<TIn, TOut>, config?: AgentProcedureBindingConfig<TIn, TBound>): void;
|
|
15
|
+
/** @deprecated Pass a compiler-generated procedure contract as the first argument. */
|
|
14
16
|
declare function useAgentProcedure<TIn extends object, TOut, TBound extends Partial<TIn> = Partial<TIn>>(ref: AgentProcedureRef<TIn, TOut>, config?: AgentProcedureBindingConfig<TIn, TBound>): void;
|
|
15
17
|
|
|
16
18
|
export { useAgentProcedure };
|
package/dist/react.js
CHANGED
|
@@ -5,12 +5,19 @@ import {
|
|
|
5
5
|
|
|
6
6
|
// src/react.ts
|
|
7
7
|
import { useEffect, useRef, useState } from "react";
|
|
8
|
+
import {
|
|
9
|
+
COMPILED_CAPABILITY_PROVENANCE,
|
|
10
|
+
tryCompiledCapabilityToken
|
|
11
|
+
} from "@agent-surface/core";
|
|
8
12
|
import {
|
|
9
13
|
useAgentSurface,
|
|
10
14
|
unstable_readRenderScopeContext
|
|
11
15
|
} from "@agent-surface/react";
|
|
12
16
|
var hookInstanceCounter = 0;
|
|
13
|
-
function useAgentProcedure(
|
|
17
|
+
function useAgentProcedure(contractOrRef, refOrConfig, maybeConfig) {
|
|
18
|
+
const contract = "kind" in contractOrRef && contractOrRef.kind === "agent-procedure-contract" ? contractOrRef : void 0;
|
|
19
|
+
const ref = contract ? refOrConfig : contractOrRef;
|
|
20
|
+
const config = contract ? maybeConfig : refOrConfig;
|
|
14
21
|
const registry = useAgentSurface();
|
|
15
22
|
const latestConfig = useRef(config);
|
|
16
23
|
latestConfig.current = config;
|
|
@@ -57,13 +64,27 @@ function useAgentProcedure(ref, config) {
|
|
|
57
64
|
};
|
|
58
65
|
const binding = bindAgentProcedure(ref, delegating);
|
|
59
66
|
if (contextRef.current) binding.contextLink = { ...contextRef.current };
|
|
60
|
-
const
|
|
67
|
+
const definition = {
|
|
61
68
|
// Procedure-only registration: excluded from snapshot.components.
|
|
62
69
|
type: "orpc-ref",
|
|
63
70
|
instanceId: instanceRef.current,
|
|
64
71
|
description: `Contextual reference to ${ref.path}`,
|
|
65
72
|
procedures: [binding]
|
|
66
|
-
}
|
|
73
|
+
};
|
|
74
|
+
if (contract) {
|
|
75
|
+
const token = tryCompiledCapabilityToken(contract);
|
|
76
|
+
if (token) {
|
|
77
|
+
Object.defineProperty(definition, COMPILED_CAPABILITY_PROVENANCE, {
|
|
78
|
+
value: {
|
|
79
|
+
manifestHash: token.manifestHash,
|
|
80
|
+
declarationId: token.declarationId,
|
|
81
|
+
capabilities: { [token.capabilityId]: token }
|
|
82
|
+
},
|
|
83
|
+
enumerable: false
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
const handle = registry.register(definition);
|
|
67
88
|
handleRef.current = handle;
|
|
68
89
|
lastPushed.current = null;
|
|
69
90
|
setStatus(handle.status === "active" ? "active" : "rejected");
|
|
@@ -71,7 +92,7 @@ function useAgentProcedure(ref, config) {
|
|
|
71
92
|
handle.unregister();
|
|
72
93
|
handleRef.current = null;
|
|
73
94
|
};
|
|
74
|
-
}, [registry, refId, manifestBacked]);
|
|
95
|
+
}, [registry, refId, manifestBacked, contract]);
|
|
75
96
|
useEffect(() => {
|
|
76
97
|
const handle = handleRef.current;
|
|
77
98
|
if (!handle || handle.status !== "active" || !manifestBacked) return;
|
package/dist/react.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/react.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport type {
|
|
1
|
+
{"version":3,"sources":["../src/react.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport {\n COMPILED_CAPABILITY_PROVENANCE,\n tryCompiledCapabilityToken,\n} from \"@agent-surface/core\";\nimport type {\n AgentComponentDefinition,\n AgentProcedureContract,\n AgentRegistrationHandle,\n JsonValue,\n} 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 Record<string, JsonValue>,\n TOut extends JsonValue,\n TBound extends Partial<TIn> = Partial<TIn>,\n>(\n contract: AgentProcedureContract<TIn, TOut>,\n ref: AgentProcedureRef<TIn, TOut>,\n config?: AgentProcedureBindingConfig<TIn, TBound>,\n): void;\n/** @deprecated Pass a compiler-generated procedure contract as the first argument. */\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;\nexport function useAgentProcedure(\n contractOrRef: AgentProcedureContract<any, any> | AgentProcedureRef<any, any>,\n refOrConfig?: AgentProcedureRef<any, any> | AgentProcedureBindingConfig<any, any>,\n maybeConfig?: AgentProcedureBindingConfig<any, any>,\n): void {\n const contract: AgentProcedureContract<any, any> | undefined =\n \"kind\" in contractOrRef && contractOrRef.kind === \"agent-procedure-contract\"\n ? contractOrRef\n : undefined;\n const ref = (contract ? refOrConfig : contractOrRef) as AgentProcedureRef<any, any>;\n const config = (contract ? maybeConfig : refOrConfig) as\n | AgentProcedureBindingConfig<any, any>\n | undefined;\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<any, any> = {\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?.() ?? {} }\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 definition: AgentComponentDefinition = {\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 if (contract) {\n const token = tryCompiledCapabilityToken(contract);\n if (token) {\n Object.defineProperty(definition, COMPILED_CAPABILITY_PROVENANCE, {\n value: {\n manifestHash: token.manifestHash,\n declarationId: token.declarationId,\n capabilities: { [token.capabilityId]: token },\n },\n enumerable: false,\n });\n }\n }\n const handle = registry.register(definition);\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, contract]);\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
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agent-surface/orpc",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.16.0",
|
|
4
4
|
"description": "Contextual references to oRPC domain procedures exposed via orpc-agent — binding, gating, executor bridge",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
"LICENSE"
|
|
23
23
|
],
|
|
24
24
|
"dependencies": {
|
|
25
|
-
"@agent-surface/core": "^0.
|
|
25
|
+
"@agent-surface/core": "^0.16.0"
|
|
26
26
|
},
|
|
27
27
|
"peerDependencies": {
|
|
28
28
|
"@agent-surface/react": ">=0.1.0",
|
|
@@ -42,8 +42,8 @@
|
|
|
42
42
|
"@types/react": "^19.1.9",
|
|
43
43
|
"@testing-library/react": "^16.3.0",
|
|
44
44
|
"zod": "^4.1.5",
|
|
45
|
-
"@agent-surface/react": "0.
|
|
46
|
-
"@agent-surface/testing": "0.
|
|
45
|
+
"@agent-surface/react": "0.16.0",
|
|
46
|
+
"@agent-surface/testing": "0.16.0"
|
|
47
47
|
},
|
|
48
48
|
"author": "Paolo Barbato",
|
|
49
49
|
"engines": {
|