@0gfoundation/0g-agentdna 0.0.0-stage → 0.2.1
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/GUIDE.md +975 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +84 -0
- package/MIGRATION.zh.md +70 -0
- package/PROVIDERS.md +273 -0
- package/PROVIDERS.zh.md +234 -0
- package/README.md +334 -2
- package/dist/AgentClient.d.ts +312 -0
- package/dist/AgentClient.d.ts.map +1 -0
- package/dist/AgentClient.js +715 -0
- package/dist/AgentClient.js.map +1 -0
- package/dist/AgenticID.d.ts +823 -0
- package/dist/AgenticID.d.ts.map +1 -0
- package/dist/AgenticID.js +1188 -0
- package/dist/AgenticID.js.map +1 -0
- package/dist/AgenticIDClient.d.ts +68 -0
- package/dist/AgenticIDClient.d.ts.map +1 -0
- package/dist/AgenticIDClient.js +198 -0
- package/dist/AgenticIDClient.js.map +1 -0
- package/dist/AttestorClient.d.ts +465 -0
- package/dist/AttestorClient.d.ts.map +1 -0
- package/dist/AttestorClient.js +1030 -0
- package/dist/AttestorClient.js.map +1 -0
- package/dist/Providers.d.ts +72 -0
- package/dist/Providers.d.ts.map +1 -0
- package/dist/Providers.js +182 -0
- package/dist/Providers.js.map +1 -0
- package/dist/ReputationClient.d.ts +213 -0
- package/dist/ReputationClient.d.ts.map +1 -0
- package/dist/ReputationClient.js +708 -0
- package/dist/ReputationClient.js.map +1 -0
- package/dist/SandboxClient.d.ts +107 -0
- package/dist/SandboxClient.d.ts.map +1 -0
- package/dist/SandboxClient.js +200 -0
- package/dist/SandboxClient.js.map +1 -0
- package/dist/ServeProof.d.ts +161 -0
- package/dist/ServeProof.d.ts.map +1 -0
- package/dist/ServeProof.js +230 -0
- package/dist/ServeProof.js.map +1 -0
- package/dist/ServeSession.d.ts +180 -0
- package/dist/ServeSession.d.ts.map +1 -0
- package/dist/ServeSession.js +336 -0
- package/dist/ServeSession.js.map +1 -0
- package/dist/Settings.d.ts +179 -0
- package/dist/Settings.d.ts.map +1 -0
- package/dist/Settings.js +247 -0
- package/dist/Settings.js.map +1 -0
- package/dist/abi.d.ts +2216 -0
- package/dist/abi.d.ts.map +1 -0
- package/dist/abi.js +1248 -0
- package/dist/abi.js.map +1 -0
- package/dist/cli/commands/cells.d.ts +62 -0
- package/dist/cli/commands/cells.d.ts.map +1 -0
- package/dist/cli/commands/cells.js +113 -0
- package/dist/cli/commands/cells.js.map +1 -0
- package/dist/cli/commands/doctor.d.ts +15 -0
- package/dist/cli/commands/doctor.d.ts.map +1 -0
- package/dist/cli/commands/doctor.js +236 -0
- package/dist/cli/commands/doctor.js.map +1 -0
- package/dist/cli/commands/interactive.d.ts +115 -0
- package/dist/cli/commands/interactive.d.ts.map +1 -0
- package/dist/cli/commands/interactive.js +3052 -0
- package/dist/cli/commands/interactive.js.map +1 -0
- package/dist/cli/commands/list.d.ts +31 -0
- package/dist/cli/commands/list.d.ts.map +1 -0
- package/dist/cli/commands/list.js +91 -0
- package/dist/cli/commands/list.js.map +1 -0
- package/dist/cli/commands/providers.d.ts +3 -0
- package/dist/cli/commands/providers.d.ts.map +1 -0
- package/dist/cli/commands/providers.js +21 -0
- package/dist/cli/commands/providers.js.map +1 -0
- package/dist/cli/commands/settings.d.ts +22 -0
- package/dist/cli/commands/settings.d.ts.map +1 -0
- package/dist/cli/commands/settings.js +188 -0
- package/dist/cli/commands/settings.js.map +1 -0
- package/dist/cli/commands/status.d.ts +16 -0
- package/dist/cli/commands/status.d.ts.map +1 -0
- package/dist/cli/commands/status.js +148 -0
- package/dist/cli/commands/status.js.map +1 -0
- package/dist/cli/commands/update.d.ts +21 -0
- package/dist/cli/commands/update.d.ts.map +1 -0
- package/dist/cli/commands/update.js +95 -0
- package/dist/cli/commands/update.js.map +1 -0
- package/dist/cli/config.d.ts +73 -0
- package/dist/cli/config.d.ts.map +1 -0
- package/dist/cli/config.js +239 -0
- package/dist/cli/config.js.map +1 -0
- package/dist/cli/env.d.ts +36 -0
- package/dist/cli/env.d.ts.map +1 -0
- package/dist/cli/env.js +74 -0
- package/dist/cli/env.js.map +1 -0
- package/dist/cli/envelope.d.ts +33 -0
- package/dist/cli/envelope.d.ts.map +1 -0
- package/dist/cli/envelope.js +62 -0
- package/dist/cli/envelope.js.map +1 -0
- package/dist/cli/errors.d.ts +48 -0
- package/dist/cli/errors.d.ts.map +1 -0
- package/dist/cli/errors.js +81 -0
- package/dist/cli/errors.js.map +1 -0
- package/dist/cli/inference.d.ts +21 -0
- package/dist/cli/inference.d.ts.map +1 -0
- package/dist/cli/inference.js +60 -0
- package/dist/cli/inference.js.map +1 -0
- package/dist/cli/logo.d.ts +21 -0
- package/dist/cli/logo.d.ts.map +1 -0
- package/dist/cli/logo.js +131 -0
- package/dist/cli/logo.js.map +1 -0
- package/dist/cli/main.d.ts +14 -0
- package/dist/cli/main.d.ts.map +1 -0
- package/dist/cli/main.js +223 -0
- package/dist/cli/main.js.map +1 -0
- package/dist/cli/proofs.d.ts +67 -0
- package/dist/cli/proofs.d.ts.map +1 -0
- package/dist/cli/proofs.js +133 -0
- package/dist/cli/proofs.js.map +1 -0
- package/dist/cli/ref.d.ts +39 -0
- package/dist/cli/ref.d.ts.map +1 -0
- package/dist/cli/ref.js +48 -0
- package/dist/cli/ref.js.map +1 -0
- package/dist/cli/sdk.d.ts +24 -0
- package/dist/cli/sdk.d.ts.map +1 -0
- package/dist/cli/sdk.js +65 -0
- package/dist/cli/sdk.js.map +1 -0
- package/dist/cli/settings.d.ts +66 -0
- package/dist/cli/settings.d.ts.map +1 -0
- package/dist/cli/settings.js +137 -0
- package/dist/cli/settings.js.map +1 -0
- package/dist/cli/tokenize.d.ts +61 -0
- package/dist/cli/tokenize.d.ts.map +1 -0
- package/dist/cli/tokenize.js +157 -0
- package/dist/cli/tokenize.js.map +1 -0
- package/dist/cli/types.d.ts +25 -0
- package/dist/cli/types.d.ts.map +1 -0
- package/dist/cli/types.js +8 -0
- package/dist/cli/types.js.map +1 -0
- package/dist/constants.d.ts +107 -0
- package/dist/constants.d.ts.map +1 -0
- package/dist/constants.js +74 -0
- package/dist/constants.js.map +1 -0
- package/dist/context.d.ts +108 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +64 -0
- package/dist/context.js.map +1 -0
- package/dist/index.d.ts +45 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +118 -0
- package/dist/index.js.map +1 -0
- package/dist/provider-catalog.json +23 -0
- package/dist/seal.d.ts +47 -0
- package/dist/seal.d.ts.map +1 -0
- package/dist/seal.js +145 -0
- package/dist/seal.js.map +1 -0
- package/dist/secretEnv.d.ts +119 -0
- package/dist/secretEnv.d.ts.map +1 -0
- package/dist/secretEnv.js +199 -0
- package/dist/secretEnv.js.map +1 -0
- package/dist/taskHash.d.ts +39 -0
- package/dist/taskHash.d.ts.map +1 -0
- package/dist/taskHash.js +119 -0
- package/dist/taskHash.js.map +1 -0
- package/dist/types.d.ts +336 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +19 -0
- package/dist/types.js.map +1 -0
- package/package.json +75 -4
- package/scripts/sync-providers.cjs +8 -0
- package/src/AgentClient.ts +897 -0
- package/src/AgenticID.ts +1382 -0
- package/src/AgenticIDClient.ts +238 -0
- package/src/AttestorClient.ts +1306 -0
- package/src/Providers.ts +176 -0
- package/src/ReputationClient.ts +821 -0
- package/src/SandboxClient.ts +227 -0
- package/src/ServeProof.ts +290 -0
- package/src/ServeSession.ts +421 -0
- package/src/Settings.ts +296 -0
- package/src/abi.ts +1282 -0
- package/src/cli/commands/cells.ts +107 -0
- package/src/cli/commands/doctor.ts +235 -0
- package/src/cli/commands/interactive.ts +2738 -0
- package/src/cli/commands/list.ts +95 -0
- package/src/cli/commands/providers.ts +16 -0
- package/src/cli/commands/settings.ts +197 -0
- package/src/cli/commands/status.ts +170 -0
- package/src/cli/commands/update.ts +86 -0
- package/src/cli/config.ts +225 -0
- package/src/cli/env.ts +90 -0
- package/src/cli/envelope.ts +57 -0
- package/src/cli/errors.ts +114 -0
- package/src/cli/inference.ts +57 -0
- package/src/cli/logo.ts +125 -0
- package/src/cli/main.ts +235 -0
- package/src/cli/proofs.ts +160 -0
- package/src/cli/ref.ts +58 -0
- package/src/cli/sdk.ts +65 -0
- package/src/cli/settings.ts +153 -0
- package/src/cli/tokenize.ts +131 -0
- package/src/cli/types.ts +27 -0
- package/src/constants.ts +106 -0
- package/src/context.ts +161 -0
- package/src/index.ts +129 -0
- package/src/provider-catalog.json +23 -0
- package/src/seal.ts +163 -0
- package/src/secretEnv.ts +250 -0
- package/src/taskHash.ts +100 -0
- package/src/types.ts +357 -0
|
@@ -0,0 +1,336 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* @file ServeSession.ts
|
|
4
|
+
* @description Consumer-side transport for reputation: call an agent's serve
|
|
5
|
+
* endpoint (any framework, any path) and capture the TEE-signed ServeProof the
|
|
6
|
+
* sealed proxy stamps on every response as the `X-Agent-Proof` header.
|
|
7
|
+
*
|
|
8
|
+
* Each agent runs its own serve endpoint — whatever HTTP API it needs; the
|
|
9
|
+
* protocol doesn't prescribe one, so it differs per agent. The one invariant is
|
|
10
|
+
* the sealed proxy in front of it, which stamps `X-Agent-Proof` on every
|
|
11
|
+
* response. So this layer doesn't model the call — you invoke the agent however
|
|
12
|
+
* it expects; ServeSession only extracts the proof from the response. The proof
|
|
13
|
+
* is then submittable on-chain via ReputationClient.giveFeedback (attribution is
|
|
14
|
+
* msg.sender; only the proof's `submitter` may redeem it).
|
|
15
|
+
*
|
|
16
|
+
* Header format (from sealed/internal/proxy):
|
|
17
|
+
* X-Agent-Proof: 0x<65-byte sig hex>.<base64url(envelope JSON)>
|
|
18
|
+
* envelope JSON = { agent_id, submitter, timestamp, deadline, task_hash,
|
|
19
|
+
* data_hashes[], framework_hash, validator }
|
|
20
|
+
* `validator` (the VerifiedFeedbackRegistry the signature is bound to) is
|
|
21
|
+
* diagnostics only — not part of the on-chain ServeProof tuple — and absent on
|
|
22
|
+
* images that predate it.
|
|
23
|
+
*/
|
|
24
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
25
|
+
exports.ServeSession = exports.SERVE_PROOF_HEADER = void 0;
|
|
26
|
+
exports.parseServeProofHeader = parseServeProofHeader;
|
|
27
|
+
exports.proofFromResponse = proofFromResponse;
|
|
28
|
+
exports.normalizedMethod = normalizedMethod;
|
|
29
|
+
exports.requestBytesOf = requestBytesOf;
|
|
30
|
+
exports.proofRecordingFetch = proofRecordingFetch;
|
|
31
|
+
exports.taskRevealOf = taskRevealOf;
|
|
32
|
+
exports.captureProof = captureProof;
|
|
33
|
+
const viem_1 = require("viem");
|
|
34
|
+
const abi_1 = require("./abi");
|
|
35
|
+
const ServeProof_1 = require("./ServeProof");
|
|
36
|
+
const taskHash_1 = require("./taskHash");
|
|
37
|
+
exports.SERVE_PROOF_HEADER = 'X-Agent-Proof';
|
|
38
|
+
const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
|
|
39
|
+
function b64urlDecode(s) {
|
|
40
|
+
const b64 = s.replace(/-/g, '+').replace(/_/g, '/');
|
|
41
|
+
const g = globalThis;
|
|
42
|
+
if (typeof g.atob === 'function')
|
|
43
|
+
return g.atob(b64);
|
|
44
|
+
// Node fallback (envelope is ASCII, so binary === utf8 here).
|
|
45
|
+
return Buffer.from(b64, 'base64').toString('binary');
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Parse an `X-Agent-Proof` header value into a ServeProof ready for
|
|
49
|
+
* ReputationClient.giveFeedback.
|
|
50
|
+
*/
|
|
51
|
+
function parseServeProofHeader(value) {
|
|
52
|
+
const dot = value.indexOf('.');
|
|
53
|
+
if (dot < 0)
|
|
54
|
+
throw new Error('malformed X-Agent-Proof header (missing ".")');
|
|
55
|
+
const signature = value.slice(0, dot);
|
|
56
|
+
const env = JSON.parse(b64urlDecode(value.slice(dot + 1)));
|
|
57
|
+
return {
|
|
58
|
+
agentId: BigInt(env.agent_id),
|
|
59
|
+
submitter: env.submitter ?? ZERO_ADDRESS,
|
|
60
|
+
timestamp: BigInt(env.timestamp),
|
|
61
|
+
deadline: BigInt(env.deadline),
|
|
62
|
+
taskHash: env.task_hash,
|
|
63
|
+
dataHashes: env.data_hashes ?? [],
|
|
64
|
+
frameworkHash: env.framework_hash,
|
|
65
|
+
signature,
|
|
66
|
+
// Unsigned diagnostics from an untrusted header: keep only a string.
|
|
67
|
+
...(typeof env.validator === 'string' && env.validator ? { validator: env.validator } : {}),
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Extract the ServeProof from a fetch Response, or null if the agent did not
|
|
72
|
+
* stamp one (e.g. an unminted agent / dev mode).
|
|
73
|
+
*/
|
|
74
|
+
function proofFromResponse(res) {
|
|
75
|
+
const header = res.headers.get(exports.SERVE_PROOF_HEADER);
|
|
76
|
+
return header ? parseServeProofHeader(header) : null;
|
|
77
|
+
}
|
|
78
|
+
/** The methods undici/fetch normalize to uppercase themselves (measured:
|
|
79
|
+
* get→GET … options→OPTIONS; anything else, e.g. `patch`, travels as
|
|
80
|
+
* written and the proxy hashes r.Method as received). Recording must
|
|
81
|
+
* uppercase exactly these six — more would hash a method the proxy never
|
|
82
|
+
* saw, fewer would record 'get' where the wire said 'GET'. */
|
|
83
|
+
const FETCH_NORMALIZED_METHODS = new Set(['get', 'head', 'post', 'put', 'delete', 'options']);
|
|
84
|
+
/** The HTTP method as it travels on the wire (see the set above). */
|
|
85
|
+
function normalizedMethod(m) {
|
|
86
|
+
const s = m ?? 'GET';
|
|
87
|
+
return FETCH_NORMALIZED_METHODS.has(s.toLowerCase()) ? s.toUpperCase() : s;
|
|
88
|
+
}
|
|
89
|
+
/** The request body bytes as they traveled, for the taskHash preimage —
|
|
90
|
+
* or null when the shape cannot be captured faithfully (Blob/FormData
|
|
91
|
+
* are async, ReadableStream would block): the caller must treat the
|
|
92
|
+
* whole task as unrecorded, never hash a wrong '' stand-in. */
|
|
93
|
+
function requestBytesOf(body) {
|
|
94
|
+
if (body == null)
|
|
95
|
+
return '';
|
|
96
|
+
if (typeof body === 'string')
|
|
97
|
+
return body;
|
|
98
|
+
if (body instanceof Uint8Array)
|
|
99
|
+
return body;
|
|
100
|
+
if (body instanceof ArrayBuffer)
|
|
101
|
+
return new Uint8Array(body);
|
|
102
|
+
if (body instanceof URLSearchParams)
|
|
103
|
+
return body.toString(); // undici sends exactly this
|
|
104
|
+
if (body instanceof DataView) {
|
|
105
|
+
return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
|
|
106
|
+
}
|
|
107
|
+
return null; // Blob, FormData, ReadableStream, … — unrecordable, not wrong
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* A fetch-compatible wrapper for generic MCP clients: every SIGNED exchange
|
|
111
|
+
* it performs is recorded (proof + task) into `log`, and the Response is
|
|
112
|
+
* returned untouched, so an MCP SDK's streamable-HTTP transport accepts it
|
|
113
|
+
* as its custom fetch (the transport is passed to `client.connect()`).
|
|
114
|
+
* Unsigned responses are logged with `task: null` and their body is never
|
|
115
|
+
* read — a long-lived SSE listener would otherwise never resolve. After the
|
|
116
|
+
* session, verify each entry with `session.verifyProof(entry.proof, { task:
|
|
117
|
+
* entry.task })` — note `task: null` yields `ok: false` (fail closed), so
|
|
118
|
+
* skip entries whose task is null only when you know why it is.
|
|
119
|
+
*
|
|
120
|
+
* @example
|
|
121
|
+
* const log: Array<{ proof: ServeProof | null; task: TaskExchange | null }> = [];
|
|
122
|
+
* const client = new Client({ name: 'consumer', version: '1' });
|
|
123
|
+
* await client.connect(new StreamableHTTPClientTransport(url, {
|
|
124
|
+
* fetch: proofRecordingFetch(log),
|
|
125
|
+
* }));
|
|
126
|
+
* // … run the MCP session …
|
|
127
|
+
* for (const e of log) if (e.proof) {
|
|
128
|
+
* const v = await session.verifyProof(e.proof, { task: e.task });
|
|
129
|
+
* if (!v.ok || !v.taskMatches) throw new Error('unverified MCP exchange');
|
|
130
|
+
* }
|
|
131
|
+
*/
|
|
132
|
+
function proofRecordingFetch(log) {
|
|
133
|
+
return (async (input, init) => {
|
|
134
|
+
// A Request as input: clone it BEFORE fetch consumes its body, so the
|
|
135
|
+
// request bytes stay recoverable if the response turns out signed.
|
|
136
|
+
// init.body (when set) overrides the Request's own body on the wire —
|
|
137
|
+
// clone only when the Request's body is what will actually be sent.
|
|
138
|
+
// Per the Fetch spec, `init.body: null` falls back to the Request's
|
|
139
|
+
// body too, so only a non-null override defeats the clone.
|
|
140
|
+
const reqClone = input instanceof Request && input.body && init?.body == null ? input.clone() : null;
|
|
141
|
+
const response = await fetch(input, init);
|
|
142
|
+
// Record the task only when the response carries X-Agent-Proof: a
|
|
143
|
+
// signed response is always finite (the proxy buffers it whole), so
|
|
144
|
+
// awaiting the clone cannot hang; an unsigned/SSE response is returned
|
|
145
|
+
// immediately — awaiting its body would block the caller's stream.
|
|
146
|
+
const proof = proofFromResponse(response);
|
|
147
|
+
let task = null;
|
|
148
|
+
if (proof) {
|
|
149
|
+
try {
|
|
150
|
+
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
|
|
151
|
+
const method = input instanceof Request && !init?.method ? input.method : normalizedMethod(init?.method);
|
|
152
|
+
let reqBytes;
|
|
153
|
+
if (reqClone) {
|
|
154
|
+
reqBytes = await reqClone.arrayBuffer().then((b) => new Uint8Array(b));
|
|
155
|
+
}
|
|
156
|
+
else {
|
|
157
|
+
reqBytes = requestBytesOf(init?.body);
|
|
158
|
+
}
|
|
159
|
+
if (reqBytes !== null) {
|
|
160
|
+
const cloned = response.clone();
|
|
161
|
+
const respBytes = await cloned.arrayBuffer().then((b) => new Uint8Array(b));
|
|
162
|
+
task = { method, url, requestBytes: reqBytes, responseBytes: respBytes, status: response.status };
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
catch {
|
|
166
|
+
task = null;
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
log.push({ proof, task });
|
|
170
|
+
return response;
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Build the TaskReveal(s) for an exchange you actually sent and received —
|
|
175
|
+
* the input to `verifyProof(proof, { task })`'s per-exchange binding. The
|
|
176
|
+
* proxy hashed one specific URI form; undici (Node fetch) and browsers
|
|
177
|
+
* differ on a bare trailing '?', so one reveal per requestUriCandidates
|
|
178
|
+
* form is returned and the comparison tries each.
|
|
179
|
+
*
|
|
180
|
+
* The bytes are hashed exactly as they traveled: pass the raw request body
|
|
181
|
+
* string/bytes and the raw response body (NOT a re-serialized JSON —
|
|
182
|
+
* key order and whitespace change the hash).
|
|
183
|
+
*/
|
|
184
|
+
function taskRevealOf(exchange) {
|
|
185
|
+
const reqBytes = exchange.requestBytes ?? '';
|
|
186
|
+
const reqBodyHash = (0, viem_1.keccak256)(typeof reqBytes === 'string' ? (0, viem_1.stringToBytes)(reqBytes) : reqBytes);
|
|
187
|
+
const respBodyHash = (0, viem_1.keccak256)(typeof exchange.responseBytes === 'string'
|
|
188
|
+
? (0, viem_1.stringToBytes)(exchange.responseBytes)
|
|
189
|
+
: exchange.responseBytes);
|
|
190
|
+
return (0, taskHash_1.requestUriCandidates)(exchange.url).map((uri) => ({
|
|
191
|
+
method: exchange.method,
|
|
192
|
+
uri,
|
|
193
|
+
reqBodyHash,
|
|
194
|
+
respBodyHash,
|
|
195
|
+
statusCode: exchange.status,
|
|
196
|
+
}));
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Run an agent call (yielding a Response) and capture its ServeProof.
|
|
200
|
+
* You still consume the body yourself (`response.json()` etc.).
|
|
201
|
+
*
|
|
202
|
+
* @example
|
|
203
|
+
* const { response, proof } = await captureProof(() =>
|
|
204
|
+
* fetch(`${agentUrl}/chat`, { method: 'POST', body }));
|
|
205
|
+
* const data = await response.json();
|
|
206
|
+
* if (proof) await rep.giveFeedback({ ...feedback, serveProof: proof });
|
|
207
|
+
*/
|
|
208
|
+
async function captureProof(call) {
|
|
209
|
+
const response = await call();
|
|
210
|
+
return { response, proof: proofFromResponse(response) };
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* Chain-aware helper to validate a captured ServeProof before submitting — so a
|
|
214
|
+
* stale or mismatched proof is caught locally rather than by an on-chain revert.
|
|
215
|
+
*/
|
|
216
|
+
class ServeSession {
|
|
217
|
+
constructor(ctx, options = {}) {
|
|
218
|
+
this.agenticID = ctx.addresses.agenticID;
|
|
219
|
+
this.verifiedFeedback = ctx.addresses.verifiedFeedback ?? ZERO_ADDRESS;
|
|
220
|
+
this.publicClient = ctx.publicClient;
|
|
221
|
+
this.clockSkew = options.clockSkew ?? 0;
|
|
222
|
+
this.now = options.now ?? (() => Math.floor(Date.now() / 1000));
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* Verify a proof against chain state: signer == on-chain agentSeal (over the
|
|
226
|
+
* digest bound to the configured VerifiedFeedbackRegistry), deadline not
|
|
227
|
+
* passed, and every declared dataHash is present in the agent's on-chain
|
|
228
|
+
* iData (so the buyer knows what the agent was running).
|
|
229
|
+
*
|
|
230
|
+
* Needs `addresses.verifiedFeedback` (fromAttestor fills it): without it
|
|
231
|
+
* nothing can be verified and `signerMatches` / `registryMatches` are false.
|
|
232
|
+
*/
|
|
233
|
+
/**
|
|
234
|
+
* Verify a proof against chain state. Without `opts.task` the verdict is
|
|
235
|
+
* signer attribution: the proof was signed by this agent's on-chain
|
|
236
|
+
* agentSeal, in time, over data the chain knows. With `opts.task` (a
|
|
237
|
+
* TaskReveal, or the TaskExchange you actually sent/received) the verdict
|
|
238
|
+
* additionally binds the proof to THAT exchange: `taskMatches` recomputes
|
|
239
|
+
* taskHash = keccak(method ‖ uri ‖ keccak(reqBody) ‖ keccak(respBody) ‖
|
|
240
|
+
* status) from your bytes and compares it to the proof's commitment — a
|
|
241
|
+
* genuine proof attached to a different response body yields
|
|
242
|
+
* `taskMatches: false` and `ok: false`. An explicit `task: null` (what
|
|
243
|
+
* the recorders return when the exchange wasn't captured) fails closed:
|
|
244
|
+
* `ok: false`, never a silent fall-back to signer-only.
|
|
245
|
+
*/
|
|
246
|
+
async verifyProof(proof, opts) {
|
|
247
|
+
const reasons = [];
|
|
248
|
+
const notExpired = proof.deadline > BigInt(this.now() - this.clockSkew);
|
|
249
|
+
if (!notExpired)
|
|
250
|
+
reasons.push('proof deadline has passed');
|
|
251
|
+
// The signature is bound to the registry that redeems it (EIP-191 v0x00
|
|
252
|
+
// intended validator). Without one there is nothing to verify against;
|
|
253
|
+
// when the envelope names another one, the signature cannot match ours.
|
|
254
|
+
const registry = this.verifiedFeedback;
|
|
255
|
+
const registryConfigured = (0, viem_1.isAddress)(registry, { strict: false }) && registry.toLowerCase() !== ZERO_ADDRESS;
|
|
256
|
+
let registryMatches = registryConfigured;
|
|
257
|
+
let signerMatches = false;
|
|
258
|
+
if (!registryConfigured) {
|
|
259
|
+
reasons.push('no VerifiedFeedbackRegistry configured — cannot verify serve-proof');
|
|
260
|
+
}
|
|
261
|
+
else if (proof.validator && proof.validator.toLowerCase() !== registry.toLowerCase()) {
|
|
262
|
+
registryMatches = false;
|
|
263
|
+
reasons.push(`proof signed for a different VerifiedFeedbackRegistry (proof: ${proof.validator}, configured: ${registry})`);
|
|
264
|
+
}
|
|
265
|
+
else {
|
|
266
|
+
const agentSeal = (await this.publicClient.readContract({
|
|
267
|
+
address: this.agenticID,
|
|
268
|
+
abi: abi_1.agenticIDAbi,
|
|
269
|
+
functionName: 'getAgentSeal',
|
|
270
|
+
args: [proof.agentId],
|
|
271
|
+
}));
|
|
272
|
+
// The digest is domain-bound: the proof was signed against this chain,
|
|
273
|
+
// the identity registry the reputation contract is anchored to, and the
|
|
274
|
+
// reputation contract itself.
|
|
275
|
+
const chainId = BigInt(await this.publicClient.getChainId());
|
|
276
|
+
signerMatches =
|
|
277
|
+
agentSeal !== ZERO_ADDRESS &&
|
|
278
|
+
(await (0, ServeProof_1.verifyServeProofSignature)(proof, agentSeal, {
|
|
279
|
+
chainId,
|
|
280
|
+
verifyingContract: this.agenticID,
|
|
281
|
+
validator: registry,
|
|
282
|
+
}));
|
|
283
|
+
if (!signerMatches) {
|
|
284
|
+
reasons.push(proof.validator
|
|
285
|
+
? 'signature does not match the on-chain agentSeal'
|
|
286
|
+
: 'signature does not match the on-chain agentSeal (the proof names no validator — likely a pre-upgrade sealed image)');
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
// dataHashes ⊆ intelligentDatasOf(agentId)
|
|
290
|
+
let dataOnChain = true;
|
|
291
|
+
if (proof.dataHashes.length > 0) {
|
|
292
|
+
const idatas = (await this.publicClient.readContract({
|
|
293
|
+
address: this.agenticID,
|
|
294
|
+
abi: abi_1.agenticIDAbi,
|
|
295
|
+
functionName: 'intelligentDatasOf',
|
|
296
|
+
args: [proof.agentId],
|
|
297
|
+
}));
|
|
298
|
+
const onChain = new Set(idatas.map((d) => d.dataHash.toLowerCase()));
|
|
299
|
+
dataOnChain = proof.dataHashes.every((h) => onChain.has(h.toLowerCase()));
|
|
300
|
+
if (!dataOnChain)
|
|
301
|
+
reasons.push('a declared dataHash is not on chain for this agent');
|
|
302
|
+
}
|
|
303
|
+
// Optional per-exchange binding: recompute the taskHash from the
|
|
304
|
+
// caller's own bytes and compare against the proof's commitment. With a
|
|
305
|
+
// TaskExchange every URI candidate gets a reveal (undici drops a bare
|
|
306
|
+
// trailing '?', browsers keep it — the proxy hashed one of the two).
|
|
307
|
+
// An EXPLICIT null is not "no task": the caller passed
|
|
308
|
+
// fetchWithProof's task and it wasn't recorded — fail closed rather
|
|
309
|
+
// than silently degrade to the signer-only verdict.
|
|
310
|
+
let taskMatches = null;
|
|
311
|
+
if (opts && 'task' in opts) {
|
|
312
|
+
if (opts.task == null) {
|
|
313
|
+
taskMatches = false;
|
|
314
|
+
reasons.push('task was passed but not recorded — cannot bind this exchange');
|
|
315
|
+
}
|
|
316
|
+
else {
|
|
317
|
+
const reveals = 'responseBytes' in opts.task ? taskRevealOf(opts.task) : [opts.task];
|
|
318
|
+
taskMatches = reveals.some((r) => (0, taskHash_1.taskHashOf)(r) === proof.taskHash);
|
|
319
|
+
if (!taskMatches) {
|
|
320
|
+
reasons.push('taskHash does not match this exchange (method/uri/bodies/status)');
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
}
|
|
324
|
+
return {
|
|
325
|
+
ok: signerMatches && notExpired && dataOnChain && taskMatches !== false,
|
|
326
|
+
signerMatches,
|
|
327
|
+
notExpired,
|
|
328
|
+
dataOnChain,
|
|
329
|
+
registryMatches,
|
|
330
|
+
taskMatches,
|
|
331
|
+
reasons,
|
|
332
|
+
};
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
exports.ServeSession = ServeSession;
|
|
336
|
+
//# sourceMappingURL=ServeSession.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ServeSession.js","sourceRoot":"","sources":["../src/ServeSession.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
import { type InferenceProvider } from './Providers';
|
|
2
|
+
/**
|
|
3
|
+
* @file Settings.ts
|
|
4
|
+
* @description The owner's configuration document — the one blob that says
|
|
5
|
+
* which model an agent thinks with, and how hard.
|
|
6
|
+
*
|
|
7
|
+
* Where it lives and who understands it:
|
|
8
|
+
* - the OWNER authors it (this file's {@link SettingsDoc});
|
|
9
|
+
* - the ATTESTOR stores it opaquely: it never parses the contents, never
|
|
10
|
+
* validates them, and gains no knowledge of what a setting means. Its
|
|
11
|
+
* only jobs are store / serve to the container / refuse a write that is
|
|
12
|
+
* not signed by the agent's current on-chain owner;
|
|
13
|
+
* - the CONTAINER (`sealed/internal/settings`) is where all meaning lives
|
|
14
|
+
* and is the real gate.
|
|
15
|
+
*
|
|
16
|
+
* That layering is the point: widening the vocabulary — a new field, a new
|
|
17
|
+
* framework knob — is a container change only. Nothing here or in the
|
|
18
|
+
* attestor has to learn about it. {@link SettingsDoc} therefore mirrors the
|
|
19
|
+
* Go `settings.Doc` exactly, and `others` stays deliberately opaque.
|
|
20
|
+
*
|
|
21
|
+
* It is NOT on chain. Configuration is re-suppliable (an owner re-picks a
|
|
22
|
+
* model in ten seconds); memory is not, and only memory earns chain storage.
|
|
23
|
+
*
|
|
24
|
+
* THE SIGNATURE COVERS A DIGEST, NOT THE DOCUMENT. `POST /settings` carries
|
|
25
|
+
* the signed statement in an HTTP header, which must stay short and ASCII,
|
|
26
|
+
* while the document is large and may be non-ASCII. So the owner signs
|
|
27
|
+
* `AgenticID.Settings.v1:<sealId>:<ts>:<base_version>:<sha256 of the bytes sent>`
|
|
28
|
+
* and the bytes themselves ride the body. For that to mean anything, the
|
|
29
|
+
* digest and the body must come from ONE serialization — see
|
|
30
|
+
* {@link canonicalSettings}, whose output is BOTH hashed and spliced
|
|
31
|
+
* verbatim into the request body.
|
|
32
|
+
*
|
|
33
|
+
* EVERY WRITE IS A COMPARE-AND-SWAP. `base_version` is the version the writer
|
|
34
|
+
* read before editing (0 = "I believe there is no document yet"); the attestor
|
|
35
|
+
* refuses with HTTP 409 when it no longer matches the stored one. Three holes
|
|
36
|
+
* close at once: a captured request cannot be replayed to roll the document
|
|
37
|
+
* back to a superseded one, two clients editing the same agent cannot silently
|
|
38
|
+
* overwrite each other, and a client that never read cannot blind-write over a
|
|
39
|
+
* document it has not seen. {@link SettingsConflictError} is what the SDK
|
|
40
|
+
* raises for that 409 — re-read, re-apply the edit, write again. Never retry
|
|
41
|
+
* the same bytes in a loop: the point of the refusal is that a human decides
|
|
42
|
+
* what survives.
|
|
43
|
+
*
|
|
44
|
+
* READS ARE OWNER-GATED TOO. The document is the owner's, so `GET /settings`
|
|
45
|
+
* carries the same owner signature, minus the digest (there is no body): the
|
|
46
|
+
* message ends at `base_version`, which a reader sends as 0. It is NOT on the
|
|
47
|
+
* public deployment row or in any listing.
|
|
48
|
+
*/
|
|
49
|
+
/** The reasoning-depth vocabulary (Go: `settings.Levels`). */
|
|
50
|
+
export declare const THINKING_LEVELS: readonly ["low", "high", "max"];
|
|
51
|
+
export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
|
|
52
|
+
/** Signed-message domain for `POST /settings`. */
|
|
53
|
+
export declare const SETTINGS_DOMAIN = "AgenticID.Settings.v1";
|
|
54
|
+
/** The 0G router's public model catalog — no auth. */
|
|
55
|
+
export declare const ROUTER_MODELS_URL: string;
|
|
56
|
+
/**
|
|
57
|
+
* The owner's settings document — the exact shape of Go's `settings.Doc`
|
|
58
|
+
* (`sealed/internal/settings/settings.go`). Field names, field order and
|
|
59
|
+
* omit-when-empty semantics all match, so what this SDK stores is what Go
|
|
60
|
+
* parses back, field for field. (The encoded BYTES can differ — see
|
|
61
|
+
* {@link canonicalSettings} — and nothing depends on them not doing so.)
|
|
62
|
+
*/
|
|
63
|
+
export interface SettingsDoc {
|
|
64
|
+
/**
|
|
65
|
+
* Who serves the model. `'0g-compute'` means the PLATFORM supplies the
|
|
66
|
+
* endpoint. Other registered managed providers supply their own endpoint;
|
|
67
|
+
* registered native providers use the framework's built-in wiring.
|
|
68
|
+
*/
|
|
69
|
+
provider?: string;
|
|
70
|
+
/** The model id, spelled the way the provider spells it. */
|
|
71
|
+
model?: string;
|
|
72
|
+
/** Reasoning-depth preference — one of {@link THINKING_LEVELS}. */
|
|
73
|
+
thinking?: ThinkingLevel;
|
|
74
|
+
/**
|
|
75
|
+
* Everything beyond the three named settings: the running framework's OWN
|
|
76
|
+
* knobs, passed through opaquely. Named `others` and not `framework`
|
|
77
|
+
* because a live drill showed the obvious reading of that word — choosing
|
|
78
|
+
* WHICH framework runs — is exactly what this field cannot do (the
|
|
79
|
+
* framework binding is minted identity). The platform neither parses nor
|
|
80
|
+
* validates the contents, nor promises they survive a framework upgrade. Any
|
|
81
|
+
* JSON value. `undefined`/`null` omits the section entirely.
|
|
82
|
+
*/
|
|
83
|
+
others?: unknown;
|
|
84
|
+
/**
|
|
85
|
+
* The document is EXTENSIBLE by design: the container defines the
|
|
86
|
+
* vocabulary, so a field newer than this SDK is legitimate. It is carried
|
|
87
|
+
* through {@link canonicalSettings} untouched, which is what keeps an
|
|
88
|
+
* older client from erasing a newer setting on a read-modify-write.
|
|
89
|
+
*/
|
|
90
|
+
[key: string]: unknown;
|
|
91
|
+
}
|
|
92
|
+
/** `'0g-compute'` — the provider for which the platform routes the model. */
|
|
93
|
+
export declare const ZG_COMPUTE_PROVIDER = "0g-compute";
|
|
94
|
+
/** The fields the PLATFORM names and guarantees, in Go declaration order.
|
|
95
|
+
* Everything else in a document belongs to the container. */
|
|
96
|
+
export declare const SETTINGS_FIELDS: readonly ["provider", "model", "thinking", "others"];
|
|
97
|
+
/**
|
|
98
|
+
* THE serialization. Its output is what gets hashed into the signed header
|
|
99
|
+
* AND what is spliced verbatim into the request body, so the two can never
|
|
100
|
+
* disagree — two independent `JSON.stringify` calls would be one refactor
|
|
101
|
+
* away from a bogus "signer mismatch".
|
|
102
|
+
*
|
|
103
|
+
* Field order follows the Go struct's declaration order and empty fields are
|
|
104
|
+
* dropped, matching `encoding/json` + `omitempty`. `others` is passed
|
|
105
|
+
* through as raw JSON — the platform does not interpret it.
|
|
106
|
+
*
|
|
107
|
+
* It is NOT byte-identical to Go's `settings.Doc.Marshal`, and does not have
|
|
108
|
+
* to be: Go's encoder escapes `<`, `>`, `&` (and U+2028/U+2029) by default,
|
|
109
|
+
* where `JSON.stringify` emits them literally — so any document containing
|
|
110
|
+
* one of those serializes differently on the two sides. Nothing rests on the
|
|
111
|
+
* two agreeing byte-for-byte. The digest covers the bytes ACTUALLY SENT, the
|
|
112
|
+
* attestor stores those bytes, and the container parses the document rather
|
|
113
|
+
* than re-hashing it. What must match across the two is the VALUE: same
|
|
114
|
+
* fields, same types, same omissions.
|
|
115
|
+
*/
|
|
116
|
+
export declare function canonicalSettings(doc: SettingsDoc): string;
|
|
117
|
+
/** sha256 of a string's UTF-8 bytes, lowercase hex, no `0x`. */
|
|
118
|
+
export declare function sha256Hex(s: string): Promise<string>;
|
|
119
|
+
/**
|
|
120
|
+
* The exact statement the owner signs. ASCII and short by construction — it
|
|
121
|
+
* travels in `X-Auth-Message`. Two forms, one grammar:
|
|
122
|
+
*
|
|
123
|
+
* write `AgenticID.Settings.v1:0x<sealId>:<unix seconds>:<base_version>:<sha256-hex>`
|
|
124
|
+
* read `AgenticID.Settings.v1:0x<sealId>:<unix seconds>:<base_version>`
|
|
125
|
+
*
|
|
126
|
+
* `baseVersion` is the version the writer read before editing — the
|
|
127
|
+
* compare-and-swap term. A read has no body and therefore no digest, and
|
|
128
|
+
* nothing to swap against, so it ends at `baseVersion` and sends 0.
|
|
129
|
+
*/
|
|
130
|
+
export declare function settingsAuthMessage(sealId: string, unixSeconds: number, baseVersion: number, digestHex?: string): string;
|
|
131
|
+
/**
|
|
132
|
+
* A write whose `base_version` no longer matches what the attestor holds
|
|
133
|
+
* (HTTP 409): somebody else changed the document between the read and the
|
|
134
|
+
* write, or the request is a replay of a superseded one.
|
|
135
|
+
*
|
|
136
|
+
* The SDK re-reads before throwing, so {@link current} / {@link currentVersion}
|
|
137
|
+
* are the live document — enough for a caller to show what it would have
|
|
138
|
+
* overwritten. It deliberately does NOT retry: re-applying the same edit
|
|
139
|
+
* blindly is how the other writer's change disappears, which is the whole
|
|
140
|
+
* thing the version guard exists to prevent. Re-apply the edit onto
|
|
141
|
+
* {@link current} and write again against {@link currentVersion} — as a human
|
|
142
|
+
* decision, not a loop.
|
|
143
|
+
*/
|
|
144
|
+
export declare class SettingsConflictError extends Error {
|
|
145
|
+
readonly name = "SettingsConflictError";
|
|
146
|
+
/** The agent whose document was contested. */
|
|
147
|
+
readonly sealId: string;
|
|
148
|
+
/** The version this write was made against. */
|
|
149
|
+
readonly baseVersion: number;
|
|
150
|
+
/** The version the attestor holds now (0 when it could not be re-read). */
|
|
151
|
+
readonly currentVersion: number;
|
|
152
|
+
/** The document the attestor holds now; null when unset or unreadable. */
|
|
153
|
+
readonly current: SettingsDoc | null;
|
|
154
|
+
constructor(args: {
|
|
155
|
+
sealId: string;
|
|
156
|
+
baseVersion: number;
|
|
157
|
+
currentVersion: number;
|
|
158
|
+
current: SettingsDoc | null;
|
|
159
|
+
detail?: string;
|
|
160
|
+
});
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* The advisory model check: is `model` in the 0G router's public catalog?
|
|
164
|
+
*
|
|
165
|
+
* ADVISORY ONLY, in both directions. A framework built-in
|
|
166
|
+
* (`anthropic/claude-…`) is legitimately absent from a catalog that covers
|
|
167
|
+
* the 0G router alone, and the container is the real gate — so an absence is
|
|
168
|
+
* a warning, never a refusal. An unreachable catalog produces no warning at
|
|
169
|
+
* all rather than a false one.
|
|
170
|
+
*
|
|
171
|
+
* Never throws.
|
|
172
|
+
*
|
|
173
|
+
* @returns human-readable warnings; empty when everything looked fine, the
|
|
174
|
+
* catalog was unreachable, or there was nothing to check.
|
|
175
|
+
*/
|
|
176
|
+
export declare function modelAdvisory(doc: SettingsDoc, resolvedProvider?: InferenceProvider): Promise<string[]>;
|
|
177
|
+
/** The router catalog's model ids, or null when it could not be read. */
|
|
178
|
+
export declare function fetchRouterModelIds(provider?: string): Promise<string[] | null>;
|
|
179
|
+
//# sourceMappingURL=Settings.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"Settings.d.ts","sourceRoot":"","sources":["../src/Settings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyD,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC5G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,eAAe,iCAAkC,CAAC;AAC/D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,kDAAkD;AAClD,eAAO,MAAM,eAAe,0BAA0B,CAAC;AAEvD,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,QAAgD,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD;8DAC8D;AAC9D,eAAO,MAAM,eAAe,sDAAuD,CAAC;AAEpF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAyB1D;AAqBD,gEAAgE;AAChE,wBAAsB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAGR;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,2BAA2B;IACxC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;gBAEzB,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;QAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;CAYF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,gBAAgB,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoC7G;AAED,yEAAyE;AACzE,wBAAsB,mBAAmB,CAAC,QAAQ,SAAsB,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAGlG"}
|