@hollis-labs/surface-genui 0.0.0-stage → 0.2.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 +26 -2
- package/contract/LICENSE +21 -0
- package/contract/provenance.json +203 -0
- package/contract/schema/catalog.json +917 -0
- package/contract/schema/contract.schema.json +1078 -0
- package/dist/contract/schema/contract.schema.json +1078 -0
- package/dist/src/contract.d.ts +40 -0
- package/dist/src/contract.js +194 -0
- package/dist/src/controller.d.ts +59 -0
- package/dist/src/controller.js +261 -0
- package/dist/src/decode.d.ts +8 -0
- package/dist/src/decode.js +156 -0
- package/dist/src/generated.d.ts +206 -0
- package/dist/src/generated.js +1 -0
- package/dist/src/index.d.ts +4 -0
- package/dist/src/index.js +3 -0
- package/dist/src/validators.d.ts +33 -0
- package/dist/src/validators.js +6717 -0
- package/package.json +42 -4
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { Call, Envelope, FormField, Input, JSONValue, Outcome } from "./generated.ts";
|
|
2
|
+
import * as validators from "./validators.js";
|
|
3
|
+
export declare const SURFACE_KIND: string;
|
|
4
|
+
export declare const SURFACE_VERSION: string;
|
|
5
|
+
export declare const CATALOG_ID: string;
|
|
6
|
+
export declare const MAX_SURFACE_BYTES: number;
|
|
7
|
+
export declare const MAX_ACTION_BYTES: number;
|
|
8
|
+
/** A definition in the contract schema; validators.js has one validator per definition. */
|
|
9
|
+
export type SchemaName = keyof typeof validators;
|
|
10
|
+
export declare function validates(name: SchemaName, value: unknown): boolean;
|
|
11
|
+
export declare function isRecord(value: unknown): value is Record<string, JSONValue>;
|
|
12
|
+
/** Form state is draft data. These checks never authorize the eventual operation. */
|
|
13
|
+
export declare function draftErrors(fields: readonly FormField[], draft: Input): Readonly<Record<string, string>>;
|
|
14
|
+
export declare function parseEnvelope(raw: string | Uint8Array): Envelope;
|
|
15
|
+
export declare function parseCall(raw: string | Uint8Array): Call;
|
|
16
|
+
export declare function parseOutcome(raw: string | Uint8Array): Outcome;
|
|
17
|
+
export declare function isTerminal(outcome: Outcome): boolean;
|
|
18
|
+
export declare function serializeCall(call: Call): string;
|
|
19
|
+
/** Reject JavaScript-only values rather than normalizing them with JSON.stringify. */
|
|
20
|
+
export declare function assertSerializable(value: unknown, depth?: number): void;
|
|
21
|
+
export type ResponseObservation = {
|
|
22
|
+
kind: "known";
|
|
23
|
+
functionCallId: string;
|
|
24
|
+
outcome: Outcome;
|
|
25
|
+
terminal: boolean;
|
|
26
|
+
} | {
|
|
27
|
+
kind: "unknown";
|
|
28
|
+
functionCallId: string;
|
|
29
|
+
status: string;
|
|
30
|
+
} | {
|
|
31
|
+
kind: "protocol_error";
|
|
32
|
+
functionCallId: string;
|
|
33
|
+
};
|
|
34
|
+
/** Unknown future statuses are preserved as unresolved, never mapped to success/failure. */
|
|
35
|
+
export declare function parseResponse(raw: string | Uint8Array, expectedFunctionCallId?: string): ResponseObservation;
|
|
36
|
+
/** Decode the host's read-only recovery wrapper before ordinary JSON parsing can lose evidence. */
|
|
37
|
+
export declare function parseRecovery(raw: string | Uint8Array, expectedFunctionCallId?: string): {
|
|
38
|
+
response: string;
|
|
39
|
+
request?: string;
|
|
40
|
+
};
|
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
import schema from "../contract/schema/contract.schema.json" with { type: "json" };
|
|
2
|
+
import { ContractError, decodeJSON, freeze } from "./decode.js";
|
|
3
|
+
import * as validators from "./validators.js";
|
|
4
|
+
export const SURFACE_KIND = schema.$defs.Envelope.properties.type.const;
|
|
5
|
+
export const SURFACE_VERSION = schema.$defs.Envelope.properties.typeVersion.const;
|
|
6
|
+
export const CATALOG_ID = schema.$defs.CreateSurface.properties.catalogId.const;
|
|
7
|
+
export const MAX_SURFACE_BYTES = 256 * 1024;
|
|
8
|
+
export const MAX_ACTION_BYTES = 64 * 1024;
|
|
9
|
+
export function validates(name, value) {
|
|
10
|
+
// biome-ignore lint/performance/noDynamicNamespaceImportAccess: the validator is chosen by schema name
|
|
11
|
+
return validators[name](value);
|
|
12
|
+
}
|
|
13
|
+
function assertSchema(name, value) {
|
|
14
|
+
if (!validates(name, value))
|
|
15
|
+
throw new ContractError();
|
|
16
|
+
}
|
|
17
|
+
export function isRecord(value) {
|
|
18
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
19
|
+
}
|
|
20
|
+
/** Form state is draft data. These checks never authorize the eventual operation. */
|
|
21
|
+
export function draftErrors(fields, draft) {
|
|
22
|
+
const errors = Object.create(null);
|
|
23
|
+
const known = new Set(fields.map((field) => field.key));
|
|
24
|
+
for (const key of Object.keys(draft))
|
|
25
|
+
if (!known.has(key))
|
|
26
|
+
errors[key] = "This field is not editable.";
|
|
27
|
+
for (const field of fields) {
|
|
28
|
+
const v = Object.hasOwn(draft, field.key) ? draft[field.key] : undefined;
|
|
29
|
+
if (v === undefined) {
|
|
30
|
+
if (field.required)
|
|
31
|
+
errors[field.key] = "A value is required.";
|
|
32
|
+
continue;
|
|
33
|
+
}
|
|
34
|
+
if (field.type === "checkbox") {
|
|
35
|
+
if (typeof v !== "boolean")
|
|
36
|
+
errors[field.key] = "Choose yes or no.";
|
|
37
|
+
}
|
|
38
|
+
else if (field.type === "integer") {
|
|
39
|
+
if (typeof v !== "number" || !Number.isSafeInteger(v) || Object.is(v, -0))
|
|
40
|
+
errors[field.key] = "Enter a whole number.";
|
|
41
|
+
else if (field.min !== undefined && v < field.min)
|
|
42
|
+
errors[field.key] = `Use a value of at least ${field.min}.`;
|
|
43
|
+
else if (field.max !== undefined && v > field.max)
|
|
44
|
+
errors[field.key] = `Use a value no greater than ${field.max}.`;
|
|
45
|
+
}
|
|
46
|
+
else if (typeof v !== "string")
|
|
47
|
+
errors[field.key] = "Enter text.";
|
|
48
|
+
else if (field.required && v === "")
|
|
49
|
+
errors[field.key] = "A value is required.";
|
|
50
|
+
else if (Array.from(v).length > (field.maxLength ?? 16384))
|
|
51
|
+
errors[field.key] = "The text is too long.";
|
|
52
|
+
}
|
|
53
|
+
return errors;
|
|
54
|
+
}
|
|
55
|
+
export function parseEnvelope(raw) {
|
|
56
|
+
const value = decodeJSON(raw, MAX_SURFACE_BYTES);
|
|
57
|
+
assertSchema("Envelope", value);
|
|
58
|
+
const envelope = value;
|
|
59
|
+
const surface = envelope.data.createSurface;
|
|
60
|
+
if (envelope.id !== surface.surfaceId)
|
|
61
|
+
throw new ContractError();
|
|
62
|
+
const root = surface.components[0];
|
|
63
|
+
if (root.component !== "GenuiForm" && surface.dataModel.draft !== undefined)
|
|
64
|
+
throw new ContractError();
|
|
65
|
+
const names = { GenuiApproval: "approval", GenuiForm: "form", GenuiListDetail: "list_detail" };
|
|
66
|
+
if (surface.metadata.extensions.genui_pattern.id !== names[root.component])
|
|
67
|
+
throw new ContractError();
|
|
68
|
+
if (root.component === "GenuiForm") {
|
|
69
|
+
const keys = root.props.fields.map((field) => field.key);
|
|
70
|
+
if (new Set(keys).size !== keys.length)
|
|
71
|
+
throw new ContractError();
|
|
72
|
+
for (const field of root.props.fields) {
|
|
73
|
+
if (field.type !== "integer" && (field.min !== undefined || field.max !== undefined))
|
|
74
|
+
throw new ContractError();
|
|
75
|
+
if (field.type !== "text" && field.type !== "textarea" && field.maxLength !== undefined)
|
|
76
|
+
throw new ContractError();
|
|
77
|
+
if (field.min !== undefined && field.max !== undefined && field.min > field.max)
|
|
78
|
+
throw new ContractError();
|
|
79
|
+
}
|
|
80
|
+
if (Object.hasOwn(root.props.submit.callFunction.args.input, "draft"))
|
|
81
|
+
throw new ContractError();
|
|
82
|
+
const draft = surface.dataModel.draft ?? {};
|
|
83
|
+
const fields = root.props.fields.map((field) => ({ ...field, required: false }));
|
|
84
|
+
if (Object.keys(draftErrors(fields, draft)).length)
|
|
85
|
+
throw new ContractError();
|
|
86
|
+
}
|
|
87
|
+
else if (root.component === "GenuiListDetail") {
|
|
88
|
+
const ids = root.props.items.map((item) => item.id);
|
|
89
|
+
if (new Set(ids).size !== ids.length ||
|
|
90
|
+
(root.props.selectedId !== undefined && !ids.includes(root.props.selectedId)) ||
|
|
91
|
+
(root.props.detail !== undefined && root.props.selectedId === undefined))
|
|
92
|
+
throw new ContractError();
|
|
93
|
+
}
|
|
94
|
+
const choices = root.component === "GenuiApproval" ? root.props.choices : root.component === "GenuiForm" ? [root.props.submit] : [];
|
|
95
|
+
for (const choice of choices)
|
|
96
|
+
if (choice.callFunction.args.genui_action.confirmation !== undefined)
|
|
97
|
+
throw new ContractError();
|
|
98
|
+
return freeze(envelope);
|
|
99
|
+
}
|
|
100
|
+
export function parseCall(raw) {
|
|
101
|
+
const value = decodeJSON(raw, MAX_ACTION_BYTES);
|
|
102
|
+
assertSchema("Call", value);
|
|
103
|
+
return freeze(value);
|
|
104
|
+
}
|
|
105
|
+
export function parseOutcome(raw) {
|
|
106
|
+
const value = decodeJSON(raw, MAX_ACTION_BYTES);
|
|
107
|
+
assertSchema("Outcome", value);
|
|
108
|
+
let current = value;
|
|
109
|
+
let depth = 0;
|
|
110
|
+
while (current.status === "conflict") {
|
|
111
|
+
if (++depth > 2)
|
|
112
|
+
throw new ContractError();
|
|
113
|
+
current = current.recorded;
|
|
114
|
+
}
|
|
115
|
+
return freeze(value);
|
|
116
|
+
}
|
|
117
|
+
export function isTerminal(outcome) {
|
|
118
|
+
return !["accepted", "needs_confirmation", "stale"].includes(outcome.status);
|
|
119
|
+
}
|
|
120
|
+
export function serializeCall(call) {
|
|
121
|
+
assertSerializable(call);
|
|
122
|
+
// Validate before serialization so unsupported values cannot silently normalize.
|
|
123
|
+
const raw = JSON.stringify(call);
|
|
124
|
+
parseCall(raw);
|
|
125
|
+
return raw;
|
|
126
|
+
}
|
|
127
|
+
/** Reject JavaScript-only values rather than normalizing them with JSON.stringify. */
|
|
128
|
+
export function assertSerializable(value, depth = 0) {
|
|
129
|
+
if (depth > 32)
|
|
130
|
+
throw new ContractError();
|
|
131
|
+
if (value === null || typeof value === "boolean" || typeof value === "string")
|
|
132
|
+
return;
|
|
133
|
+
if (typeof value === "number") {
|
|
134
|
+
if (!Number.isSafeInteger(value) || Object.is(value, -0))
|
|
135
|
+
throw new ContractError();
|
|
136
|
+
return;
|
|
137
|
+
}
|
|
138
|
+
if (Array.isArray(value)) {
|
|
139
|
+
if (Object.getPrototypeOf(value) !== Array.prototype || Reflect.ownKeys(value).length !== value.length + 1)
|
|
140
|
+
throw new ContractError();
|
|
141
|
+
for (let i = 0; i < value.length; i++) {
|
|
142
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
|
|
143
|
+
if (!descriptor?.enumerable || !("value" in descriptor))
|
|
144
|
+
throw new ContractError();
|
|
145
|
+
assertSerializable(descriptor.value, depth + 1);
|
|
146
|
+
}
|
|
147
|
+
return;
|
|
148
|
+
}
|
|
149
|
+
if (typeof value !== "object" ||
|
|
150
|
+
(Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null))
|
|
151
|
+
throw new ContractError();
|
|
152
|
+
for (const key of Reflect.ownKeys(value)) {
|
|
153
|
+
if (typeof key !== "string")
|
|
154
|
+
throw new ContractError();
|
|
155
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, key);
|
|
156
|
+
if (!descriptor?.enumerable || !("value" in descriptor))
|
|
157
|
+
throw new ContractError();
|
|
158
|
+
assertSerializable(descriptor.value, depth + 1);
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
/** Unknown future statuses are preserved as unresolved, never mapped to success/failure. */
|
|
162
|
+
export function parseResponse(raw, expectedFunctionCallId) {
|
|
163
|
+
const value = decodeJSON(raw, MAX_ACTION_BYTES);
|
|
164
|
+
assertSchema("ReceiverResponse", value);
|
|
165
|
+
const response = value.agentFunctionResponse;
|
|
166
|
+
if (expectedFunctionCallId !== undefined && response.functionCallId !== expectedFunctionCallId)
|
|
167
|
+
throw new ContractError();
|
|
168
|
+
if ("error" in response)
|
|
169
|
+
return freeze({ kind: "protocol_error", functionCallId: response.functionCallId });
|
|
170
|
+
if (!validates("Outcome", response.value))
|
|
171
|
+
return freeze({ kind: "unknown", functionCallId: response.functionCallId, status: response.value.status });
|
|
172
|
+
const outcome = parseOutcome(JSON.stringify(response.value));
|
|
173
|
+
return freeze({ kind: "known", functionCallId: response.functionCallId, outcome, terminal: isTerminal(outcome) });
|
|
174
|
+
}
|
|
175
|
+
/** Decode the host's read-only recovery wrapper before ordinary JSON parsing can lose evidence. */
|
|
176
|
+
export function parseRecovery(raw, expectedFunctionCallId) {
|
|
177
|
+
// Two bounded native messages plus the fixed wrapper. Its sole extra nesting
|
|
178
|
+
// level is removed before each native parser enforces the canonical depth.
|
|
179
|
+
const value = decodeJSON(raw, MAX_ACTION_BYTES * 2 + 256, 33);
|
|
180
|
+
if (!isRecord(value) ||
|
|
181
|
+
!Object.hasOwn(value, "response") ||
|
|
182
|
+
Object.keys(value).some((key) => key !== "response" && key !== "request"))
|
|
183
|
+
throw new ContractError();
|
|
184
|
+
const response = JSON.stringify(value.response);
|
|
185
|
+
const observation = parseResponse(response, expectedFunctionCallId);
|
|
186
|
+
if (!Object.hasOwn(value, "request"))
|
|
187
|
+
return freeze({ response });
|
|
188
|
+
const request = JSON.stringify(value.request);
|
|
189
|
+
const call = parseCall(request);
|
|
190
|
+
if (call.callAgentFunction.functionCallId !== observation.functionCallId ||
|
|
191
|
+
call.callAgentFunction.callFunction.args.genui_action.confirmation !== undefined)
|
|
192
|
+
throw new ContractError();
|
|
193
|
+
return freeze({ response, request });
|
|
194
|
+
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { type ResponseObservation } from "./contract.ts";
|
|
2
|
+
import type { Envelope, Input, Outcome } from "./generated.ts";
|
|
3
|
+
export interface RecoverRequest {
|
|
4
|
+
surfaceId: string;
|
|
5
|
+
actionId: string;
|
|
6
|
+
functionCallId: string;
|
|
7
|
+
}
|
|
8
|
+
export interface Recovery {
|
|
9
|
+
/** Canonical AgentFunctionResponse from a host read, correlated to this read's functionCallId. */
|
|
10
|
+
response: string;
|
|
11
|
+
/** Optional original canonical Call retained by the host. Never reconstructed from an action ID. */
|
|
12
|
+
request?: string;
|
|
13
|
+
}
|
|
14
|
+
export interface ConfirmationRequest extends RecoverRequest {
|
|
15
|
+
call: string;
|
|
16
|
+
challenge: Extract<Outcome, {
|
|
17
|
+
status: "needs_confirmation";
|
|
18
|
+
}>["confirm"];
|
|
19
|
+
}
|
|
20
|
+
export interface GenuiTransport {
|
|
21
|
+
submit(call: string, signal: AbortSignal): Promise<string>;
|
|
22
|
+
recover(request: RecoverRequest, signal: AbortSignal): Promise<Recovery>;
|
|
23
|
+
/** Host performs the real confirmation workflow and returns its opaque proof; UI does not mint it. */
|
|
24
|
+
confirm?(request: ConfirmationRequest, signal: AbortSignal): Promise<string>;
|
|
25
|
+
}
|
|
26
|
+
export type Phase = "ready" | "busy" | "pending" | "confirmation" | "unknown" | "terminal" | "stale";
|
|
27
|
+
export interface GenuiSnapshot {
|
|
28
|
+
envelope: Envelope;
|
|
29
|
+
phase: Phase;
|
|
30
|
+
actionId?: string;
|
|
31
|
+
observation?: ResponseObservation;
|
|
32
|
+
message?: string;
|
|
33
|
+
canConfirm: boolean;
|
|
34
|
+
}
|
|
35
|
+
/** One presentation's coordinator. The host owns registration, policy, durable state and idempotency. */
|
|
36
|
+
export declare class GenuiController {
|
|
37
|
+
private state;
|
|
38
|
+
private listeners;
|
|
39
|
+
private operation?;
|
|
40
|
+
private original?;
|
|
41
|
+
private disposed;
|
|
42
|
+
private readonly transport;
|
|
43
|
+
private readonly invocationId;
|
|
44
|
+
constructor(raw: string | Uint8Array, transport: GenuiTransport, invocationId?: () => string);
|
|
45
|
+
getSnapshot: () => GenuiSnapshot;
|
|
46
|
+
subscribe: (listener: () => void) => (() => void);
|
|
47
|
+
private update;
|
|
48
|
+
private begin;
|
|
49
|
+
private current;
|
|
50
|
+
private receive;
|
|
51
|
+
private uncertain;
|
|
52
|
+
submit(choiceIndex: number, draft?: Input): Promise<void>;
|
|
53
|
+
private validateRecorded;
|
|
54
|
+
/** Read-only recovery. Never submits a choice, and never infers input from an action ID. */
|
|
55
|
+
recover(actionId?: string | undefined): Promise<void>;
|
|
56
|
+
confirm(): Promise<void>;
|
|
57
|
+
/** Stops this view's requests, not the host operation. Remount and recover to read durable status. */
|
|
58
|
+
dispose(): void;
|
|
59
|
+
}
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
import { assertSerializable, CATALOG_ID, draftErrors, parseCall, parseEnvelope, parseResponse, serializeCall, } from "./contract.js";
|
|
2
|
+
import { ContractError, freeze } from "./decode.js";
|
|
3
|
+
function equal(a, b) {
|
|
4
|
+
if (Object.is(a, b))
|
|
5
|
+
return true;
|
|
6
|
+
if (!a || !b || typeof a !== "object" || typeof b !== "object")
|
|
7
|
+
return false;
|
|
8
|
+
if (Array.isArray(a) !== Array.isArray(b))
|
|
9
|
+
return false;
|
|
10
|
+
const ak = Object.keys(a), bk = Object.keys(b);
|
|
11
|
+
return (ak.length === bk.length &&
|
|
12
|
+
ak.every((key) => Object.hasOwn(b, key) && equal(a[key], b[key])));
|
|
13
|
+
}
|
|
14
|
+
function offered(envelope) {
|
|
15
|
+
const root = envelope.data.createSurface.components[0];
|
|
16
|
+
return root.component === "GenuiApproval"
|
|
17
|
+
? root.props.choices
|
|
18
|
+
: root.component === "GenuiForm"
|
|
19
|
+
? [root.props.submit]
|
|
20
|
+
: [];
|
|
21
|
+
}
|
|
22
|
+
function withoutProof(call) {
|
|
23
|
+
const clean = parseCall(serializeCall(call));
|
|
24
|
+
const action = { ...clean.callAgentFunction.callFunction.args.genui_action };
|
|
25
|
+
delete action.confirmation;
|
|
26
|
+
return {
|
|
27
|
+
...clean,
|
|
28
|
+
callAgentFunction: {
|
|
29
|
+
...clean.callAgentFunction,
|
|
30
|
+
callFunction: {
|
|
31
|
+
...clean.callAgentFunction.callFunction,
|
|
32
|
+
args: { ...clean.callAgentFunction.callFunction.args, genui_action: action },
|
|
33
|
+
},
|
|
34
|
+
},
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
// Canonical Go ChoiceDigest defaults the catalog and excludes the advisory risk hint.
|
|
38
|
+
// This matches a stored choice only; actual risk and authority remain host decisions.
|
|
39
|
+
function choiceAction(call) {
|
|
40
|
+
const action = { ...call.args.genui_action };
|
|
41
|
+
delete action.risk;
|
|
42
|
+
return action;
|
|
43
|
+
}
|
|
44
|
+
function semanticCall(call) {
|
|
45
|
+
return { ...call, catalogId: call.catalogId ?? CATALOG_ID, args: { ...call.args, genui_action: choiceAction(call) } };
|
|
46
|
+
}
|
|
47
|
+
/** One presentation's coordinator. The host owns registration, policy, durable state and idempotency. */
|
|
48
|
+
export class GenuiController {
|
|
49
|
+
state;
|
|
50
|
+
listeners = new Set();
|
|
51
|
+
operation;
|
|
52
|
+
original;
|
|
53
|
+
disposed = false;
|
|
54
|
+
transport;
|
|
55
|
+
invocationId;
|
|
56
|
+
constructor(raw, transport, invocationId = () => crypto.randomUUID()) {
|
|
57
|
+
this.transport = transport;
|
|
58
|
+
this.invocationId = invocationId;
|
|
59
|
+
this.state = freeze({ envelope: parseEnvelope(raw), phase: "ready", canConfirm: false });
|
|
60
|
+
}
|
|
61
|
+
getSnapshot = () => this.state;
|
|
62
|
+
subscribe = (listener) => {
|
|
63
|
+
this.listeners.add(listener);
|
|
64
|
+
return () => this.listeners.delete(listener);
|
|
65
|
+
};
|
|
66
|
+
update(change) {
|
|
67
|
+
this.state = freeze({ ...this.state, ...change });
|
|
68
|
+
for (const listener of this.listeners)
|
|
69
|
+
listener();
|
|
70
|
+
}
|
|
71
|
+
begin(actionId) {
|
|
72
|
+
this.operation?.abort();
|
|
73
|
+
const op = new AbortController();
|
|
74
|
+
this.operation = op;
|
|
75
|
+
this.update({ phase: "busy", actionId, canConfirm: false, message: undefined });
|
|
76
|
+
return op;
|
|
77
|
+
}
|
|
78
|
+
current(op) {
|
|
79
|
+
return !this.disposed && this.operation === op && !op.signal.aborted;
|
|
80
|
+
}
|
|
81
|
+
receive(raw, id, op) {
|
|
82
|
+
const observation = parseResponse(raw, id);
|
|
83
|
+
if (!this.current(op))
|
|
84
|
+
return;
|
|
85
|
+
if (observation.kind !== "known") {
|
|
86
|
+
this.update({
|
|
87
|
+
phase: "unknown",
|
|
88
|
+
observation,
|
|
89
|
+
canConfirm: false,
|
|
90
|
+
message: "The result is not yet understood. Check the host status before taking further action.",
|
|
91
|
+
});
|
|
92
|
+
return;
|
|
93
|
+
}
|
|
94
|
+
const status = observation.outcome.status;
|
|
95
|
+
const phase = observation.terminal
|
|
96
|
+
? "terminal"
|
|
97
|
+
: status === "needs_confirmation"
|
|
98
|
+
? "confirmation"
|
|
99
|
+
: status === "stale"
|
|
100
|
+
? "stale"
|
|
101
|
+
: "pending";
|
|
102
|
+
this.update({
|
|
103
|
+
phase,
|
|
104
|
+
observation,
|
|
105
|
+
message: undefined,
|
|
106
|
+
canConfirm: phase === "confirmation" && this.original !== undefined && this.transport.confirm !== undefined,
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
uncertain(op) {
|
|
110
|
+
if (this.current(op))
|
|
111
|
+
this.update({
|
|
112
|
+
phase: "unknown",
|
|
113
|
+
canConfirm: false,
|
|
114
|
+
message: "The host result could not be verified. This action has not been retried.",
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
async submit(choiceIndex, draft) {
|
|
118
|
+
if (this.disposed || this.state.phase !== "ready")
|
|
119
|
+
return;
|
|
120
|
+
const root = this.state.envelope.data.createSurface.components[0];
|
|
121
|
+
if (root.props.state !== "ready")
|
|
122
|
+
throw new ContractError("This surface is not ready for submission.");
|
|
123
|
+
const choice = offered(this.state.envelope)[choiceIndex];
|
|
124
|
+
if (!choice)
|
|
125
|
+
throw new ContractError();
|
|
126
|
+
let input = choice.callFunction.args.input;
|
|
127
|
+
if (root.component === "GenuiForm") {
|
|
128
|
+
if (draft === undefined || Object.keys(draftErrors(root.props.fields, draft)).length)
|
|
129
|
+
throw new ContractError("Review the form values.");
|
|
130
|
+
assertSerializable(draft);
|
|
131
|
+
input = { ...input, draft };
|
|
132
|
+
}
|
|
133
|
+
else if (draft !== undefined)
|
|
134
|
+
throw new ContractError();
|
|
135
|
+
const functionCallId = this.invocationId();
|
|
136
|
+
const call = {
|
|
137
|
+
version: "1.0",
|
|
138
|
+
callAgentFunction: {
|
|
139
|
+
surfaceId: this.state.envelope.data.createSurface.surfaceId,
|
|
140
|
+
functionCallId,
|
|
141
|
+
callFunction: { ...choice.callFunction, args: { ...choice.callFunction.args, input } },
|
|
142
|
+
},
|
|
143
|
+
};
|
|
144
|
+
const raw = serializeCall(call);
|
|
145
|
+
this.original = parseCall(raw);
|
|
146
|
+
const op = this.begin(call.callAgentFunction.callFunction.args.genui_action.id);
|
|
147
|
+
try {
|
|
148
|
+
this.receive(await this.transport.submit(raw, op.signal), functionCallId, op);
|
|
149
|
+
}
|
|
150
|
+
catch {
|
|
151
|
+
this.uncertain(op);
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
validateRecorded(raw, actionId) {
|
|
155
|
+
const call = parseCall(raw);
|
|
156
|
+
if (call.callAgentFunction.callFunction.args.genui_action.confirmation !== undefined)
|
|
157
|
+
throw new ContractError();
|
|
158
|
+
const invocation = call.callAgentFunction;
|
|
159
|
+
if (invocation.surfaceId !== this.state.envelope.data.createSurface.surfaceId ||
|
|
160
|
+
invocation.callFunction.args.genui_action.id !== actionId)
|
|
161
|
+
throw new ContractError();
|
|
162
|
+
const root = this.state.envelope.data.createSurface.components[0];
|
|
163
|
+
const match = offered(this.state.envelope).some((choice) => {
|
|
164
|
+
const recorded = invocation.callFunction;
|
|
165
|
+
const base = choice.callFunction;
|
|
166
|
+
if (recorded["@call"] !== base["@call"] ||
|
|
167
|
+
(recorded.catalogId ?? CATALOG_ID) !== (base.catalogId ?? CATALOG_ID) ||
|
|
168
|
+
!equal(choiceAction(recorded), choiceAction(base)))
|
|
169
|
+
return false;
|
|
170
|
+
if (root.component !== "GenuiForm")
|
|
171
|
+
return equal(recorded.args.input, base.args.input);
|
|
172
|
+
const { draft, ...rest } = recorded.args.input;
|
|
173
|
+
return (draft !== null &&
|
|
174
|
+
typeof draft === "object" &&
|
|
175
|
+
!Array.isArray(draft) &&
|
|
176
|
+
!Object.keys(draftErrors(root.props.fields, draft)).length &&
|
|
177
|
+
equal(rest, base.args.input));
|
|
178
|
+
});
|
|
179
|
+
if (!match)
|
|
180
|
+
throw new ContractError();
|
|
181
|
+
if (this.original &&
|
|
182
|
+
!equal(semanticCall(withoutProof(this.original).callAgentFunction.callFunction), semanticCall(invocation.callFunction)))
|
|
183
|
+
throw new ContractError();
|
|
184
|
+
return freeze(call);
|
|
185
|
+
}
|
|
186
|
+
/** Read-only recovery. Never submits a choice, and never infers input from an action ID. */
|
|
187
|
+
async recover(actionId = this.state.actionId) {
|
|
188
|
+
if (this.disposed ||
|
|
189
|
+
this.state.phase === "busy" ||
|
|
190
|
+
!actionId ||
|
|
191
|
+
(this.state.actionId !== undefined && this.state.actionId !== actionId) ||
|
|
192
|
+
!offered(this.state.envelope).some((choice) => choice.callFunction.args.genui_action.id === actionId))
|
|
193
|
+
return;
|
|
194
|
+
const functionCallId = this.invocationId();
|
|
195
|
+
const op = this.begin(actionId);
|
|
196
|
+
try {
|
|
197
|
+
const recovery = await this.transport.recover({ surfaceId: this.state.envelope.data.createSurface.surfaceId, actionId, functionCallId }, op.signal);
|
|
198
|
+
if (!this.current(op))
|
|
199
|
+
return;
|
|
200
|
+
const recorded = recovery.request === undefined ? undefined : this.validateRecorded(recovery.request, actionId);
|
|
201
|
+
const observation = parseResponse(recovery.response, functionCallId);
|
|
202
|
+
if (recorded)
|
|
203
|
+
this.original = recorded;
|
|
204
|
+
// Validate all evidence before adopting any newly recovered input.
|
|
205
|
+
this.receive(recovery.response, observation.functionCallId, op);
|
|
206
|
+
}
|
|
207
|
+
catch {
|
|
208
|
+
this.uncertain(op);
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
async confirm() {
|
|
212
|
+
const observation = this.state.observation;
|
|
213
|
+
if (this.disposed ||
|
|
214
|
+
!this.state.canConfirm ||
|
|
215
|
+
observation?.kind !== "known" ||
|
|
216
|
+
observation.outcome.status !== "needs_confirmation" ||
|
|
217
|
+
!this.original ||
|
|
218
|
+
!this.transport.confirm)
|
|
219
|
+
return;
|
|
220
|
+
const original = this.original;
|
|
221
|
+
const functionCallId = this.invocationId();
|
|
222
|
+
const actionId = original.callAgentFunction.callFunction.args.genui_action.id;
|
|
223
|
+
const op = this.begin(actionId);
|
|
224
|
+
try {
|
|
225
|
+
const proof = await this.transport.confirm({
|
|
226
|
+
surfaceId: original.callAgentFunction.surfaceId,
|
|
227
|
+
actionId,
|
|
228
|
+
functionCallId,
|
|
229
|
+
call: serializeCall(original),
|
|
230
|
+
challenge: observation.outcome.confirm,
|
|
231
|
+
}, op.signal);
|
|
232
|
+
if (!this.current(op))
|
|
233
|
+
return;
|
|
234
|
+
const call = {
|
|
235
|
+
...original,
|
|
236
|
+
callAgentFunction: {
|
|
237
|
+
...original.callAgentFunction,
|
|
238
|
+
functionCallId,
|
|
239
|
+
callFunction: {
|
|
240
|
+
...original.callAgentFunction.callFunction,
|
|
241
|
+
args: {
|
|
242
|
+
...original.callAgentFunction.callFunction.args,
|
|
243
|
+
genui_action: { ...original.callAgentFunction.callFunction.args.genui_action, confirmation: proof },
|
|
244
|
+
},
|
|
245
|
+
},
|
|
246
|
+
},
|
|
247
|
+
};
|
|
248
|
+
const raw = serializeCall(call);
|
|
249
|
+
this.receive(await this.transport.submit(raw, op.signal), functionCallId, op);
|
|
250
|
+
}
|
|
251
|
+
catch {
|
|
252
|
+
this.uncertain(op);
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
/** Stops this view's requests, not the host operation. Remount and recover to read durable status. */
|
|
256
|
+
dispose() {
|
|
257
|
+
this.disposed = true;
|
|
258
|
+
this.operation?.abort();
|
|
259
|
+
this.listeners.clear();
|
|
260
|
+
}
|
|
261
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { JSONValue } from "./generated.ts";
|
|
2
|
+
export declare class ContractError extends Error {
|
|
3
|
+
constructor(message?: string);
|
|
4
|
+
}
|
|
5
|
+
/** Raw-token validation happens before a JavaScript number or duplicate key can lose information. */
|
|
6
|
+
export declare function decodeJSON(input: string | Uint8Array, maxBytes: number, maxDepth?: number): JSONValue;
|
|
7
|
+
/** Immutable browser snapshots are presentation state, never an authorization proof. */
|
|
8
|
+
export declare function freeze<T>(value: T): T;
|