@evomap/evolver-adapter-public 2.0.36 → 2.0.38
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/dist/atp.d.ts +58 -0
- package/dist/atp.js +103 -0
- package/dist/hubCapability.js +43 -10
- package/package.json +3 -3
package/dist/atp.d.ts
CHANGED
|
@@ -29,6 +29,24 @@ export interface AtpListProofsOptions {
|
|
|
29
29
|
status?: AtpProofStatus | string;
|
|
30
30
|
limit?: number;
|
|
31
31
|
}
|
|
32
|
+
export interface HubTaskFetchOptions {
|
|
33
|
+
limit?: number;
|
|
34
|
+
/** Questions to piggyback on the fetch; the Hub may turn them into bounties. */
|
|
35
|
+
questions?: readonly {
|
|
36
|
+
question: string;
|
|
37
|
+
amount?: number;
|
|
38
|
+
signals?: readonly string[];
|
|
39
|
+
}[];
|
|
40
|
+
/**
|
|
41
|
+
* The envelope id the Hub dedupes on. Override it only to make two identical question
|
|
42
|
+
* sets deliberately distinct; an ordinary retry needs nothing, because a fetch carrying
|
|
43
|
+
* `questions` derives its id from the questions themselves and so repeats it.
|
|
44
|
+
*/
|
|
45
|
+
messageId?: string;
|
|
46
|
+
}
|
|
47
|
+
export interface HubTaskClaimOptions {
|
|
48
|
+
commitmentDeadline?: string;
|
|
49
|
+
}
|
|
32
50
|
export interface AtpClientOptions {
|
|
33
51
|
baseUrl: string;
|
|
34
52
|
auth: hub.AuthProvider;
|
|
@@ -39,6 +57,18 @@ export declare class AtpHubClient {
|
|
|
39
57
|
private readonly opts;
|
|
40
58
|
private readonly http;
|
|
41
59
|
constructor(opts: AtpClientOptions);
|
|
60
|
+
/**
|
|
61
|
+
* The node every call of this client speaks for. Ownership checks must read it from
|
|
62
|
+
* here rather than resolve their own: a filter that answers about a different node
|
|
63
|
+
* than the one submitting is how work gets skipped or handed to the wrong claimant.
|
|
64
|
+
*/
|
|
65
|
+
nodeId(): string | undefined;
|
|
66
|
+
/**
|
|
67
|
+
* The node id every task-protocol write is made under. These calls take and hand back
|
|
68
|
+
* work on one node's behalf, so a request that cannot name that node is not a weaker
|
|
69
|
+
* request — it is an unattributable one, and the Hub should never be asked to guess.
|
|
70
|
+
*/
|
|
71
|
+
private requireSenderId;
|
|
42
72
|
placeOrder<T = unknown>(opts: AtpOrderOptions): Promise<AtpResult<T>>;
|
|
43
73
|
submitDelivery<T = unknown>(orderId: string, proofPayload?: unknown): Promise<AtpResult<T>>;
|
|
44
74
|
verifyDelivery<T = unknown>(orderId: string, action?: AtpVerifyAction | string): Promise<AtpResult<T>>;
|
|
@@ -49,6 +79,34 @@ export declare class AtpHubClient {
|
|
|
49
79
|
listProofs<T = unknown>(opts?: AtpListProofsOptions): Promise<AtpResult<T>>;
|
|
50
80
|
getAtpPolicy<T = unknown>(): Promise<AtpResult<T>>;
|
|
51
81
|
listMyTasks<T = unknown>(limit?: number, nodeId?: string): Promise<AtpResult<T>>;
|
|
82
|
+
/**
|
|
83
|
+
* Available tasks the Hub is willing to hand this node. The Hub answers the
|
|
84
|
+
* A2A `fetch` envelope with a `tasks` array; `tasks_only` keeps it from
|
|
85
|
+
* piggybacking anything else onto the response.
|
|
86
|
+
*/
|
|
87
|
+
fetchTasks<T = unknown>(opts?: HubTaskFetchOptions): Promise<AtpResult<T>>;
|
|
88
|
+
/**
|
|
89
|
+
* The id the Hub dedupes envelopes on. A plain read has no side effect and gets a fresh
|
|
90
|
+
* id; a fetch carrying `questions` can create bounties, so its id is derived from the
|
|
91
|
+
* questions themselves — retrying the same ask after a lost response repeats the id and
|
|
92
|
+
* the Hub recognises it, instead of posting the same question a second time.
|
|
93
|
+
*/
|
|
94
|
+
private static envelopeIdFor;
|
|
95
|
+
/**
|
|
96
|
+
* Take a task. `commitmentDeadline` is the promise the node makes back: the
|
|
97
|
+
* Hub holds the task for this node until then, so a caller that cannot
|
|
98
|
+
* finish in time must not send one it cannot keep.
|
|
99
|
+
*/
|
|
100
|
+
claimTask<T = unknown>(taskId: string, opts?: HubTaskClaimOptions): Promise<AtpResult<T>>;
|
|
101
|
+
/** Hand a claimed task back to the Hub with the asset the work produced. */
|
|
102
|
+
completeTask<T = unknown>(taskId: string, assetId: string): Promise<AtpResult<T>>;
|
|
103
|
+
/**
|
|
104
|
+
* Take a deferred worker task. The Hub gates this channel separately from
|
|
105
|
+
* `/a2a/task/claim` and answers `worker_disabled` while it is closed.
|
|
106
|
+
*/
|
|
107
|
+
claimWorkerTask<T = unknown>(taskId: string): Promise<AtpResult<T>>;
|
|
108
|
+
/** Hand a worker task back with the asset it produced. */
|
|
109
|
+
completeWorkerTask<T = unknown>(taskId: string, assetId: string): Promise<AtpResult<T>>;
|
|
52
110
|
private callResult;
|
|
53
111
|
}
|
|
54
112
|
export declare function normalizeAtpResult<T = unknown>(raw: unknown): AtpResult<T>;
|
package/dist/atp.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
1
2
|
import { ATP_EXECUTION_MODES, ATP_PROOF_STATUSES, ATP_ROLES, ATP_ROUTING_MODES, ATP_VERIFY_ACTIONS, ATP_VERIFY_MODES, } from '@evomap/atp-sdk';
|
|
2
3
|
import { HubClientError, HubFetch } from './hubFetch.js';
|
|
3
4
|
export { ATP_EXECUTION_MODES, ATP_PROOF_STATUSES, ATP_ROLES, ATP_ROUTING_MODES, ATP_VERIFY_ACTIONS, ATP_VERIFY_MODES, };
|
|
@@ -8,6 +9,25 @@ export class AtpHubClient {
|
|
|
8
9
|
this.opts = opts;
|
|
9
10
|
this.http = new HubFetch({ baseUrl: opts.baseUrl, auth: opts.auth, fetchFn: opts.fetchFn, senderId: opts.senderId });
|
|
10
11
|
}
|
|
12
|
+
/**
|
|
13
|
+
* The node every call of this client speaks for. Ownership checks must read it from
|
|
14
|
+
* here rather than resolve their own: a filter that answers about a different node
|
|
15
|
+
* than the one submitting is how work gets skipped or handed to the wrong claimant.
|
|
16
|
+
*/
|
|
17
|
+
nodeId() {
|
|
18
|
+
return this.opts.senderId();
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* The node id every task-protocol write is made under. These calls take and hand back
|
|
22
|
+
* work on one node's behalf, so a request that cannot name that node is not a weaker
|
|
23
|
+
* request — it is an unattributable one, and the Hub should never be asked to guess.
|
|
24
|
+
*/
|
|
25
|
+
requireSenderId(call) {
|
|
26
|
+
const senderId = this.opts.senderId();
|
|
27
|
+
if (!senderId)
|
|
28
|
+
throw new Error(`${call} needs a node identity: this client cannot say which node it authenticates as`);
|
|
29
|
+
return senderId;
|
|
30
|
+
}
|
|
11
31
|
async placeOrder(opts) {
|
|
12
32
|
const capabilities = opts.capabilities.map((s) => String(s).trim()).filter(Boolean);
|
|
13
33
|
if (capabilities.length === 0)
|
|
@@ -74,6 +94,89 @@ export class AtpHubClient {
|
|
|
74
94
|
};
|
|
75
95
|
return this.callResult('GET', '/a2a/task/my', undefined, query);
|
|
76
96
|
}
|
|
97
|
+
/**
|
|
98
|
+
* Available tasks the Hub is willing to hand this node. The Hub answers the
|
|
99
|
+
* A2A `fetch` envelope with a `tasks` array; `tasks_only` keeps it from
|
|
100
|
+
* piggybacking anything else onto the response.
|
|
101
|
+
*/
|
|
102
|
+
async fetchTasks(opts = {}) {
|
|
103
|
+
// The node these calls speak for is the one the credentials belong to. Letting a
|
|
104
|
+
// caller name a different node_id would ask the Hub to act on someone else's behalf.
|
|
105
|
+
const nid = this.requireSenderId('fetchTasks');
|
|
106
|
+
return this.callResult('POST', '/a2a/fetch', {
|
|
107
|
+
protocol: 'gep-a2a',
|
|
108
|
+
protocol_version: '1.0.0',
|
|
109
|
+
message_type: 'fetch',
|
|
110
|
+
message_id: opts.messageId ?? AtpHubClient.envelopeIdFor(nid, opts),
|
|
111
|
+
sender_id: nid,
|
|
112
|
+
timestamp: new Date().toISOString(),
|
|
113
|
+
payload: {
|
|
114
|
+
tasks_only: true,
|
|
115
|
+
include_tasks: true,
|
|
116
|
+
...(opts.limit === undefined ? {} : { limit: clampLimit(opts.limit) }),
|
|
117
|
+
...(opts.questions && opts.questions.length > 0 ? { questions: opts.questions } : {}),
|
|
118
|
+
},
|
|
119
|
+
});
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* The id the Hub dedupes envelopes on. A plain read has no side effect and gets a fresh
|
|
123
|
+
* id; a fetch carrying `questions` can create bounties, so its id is derived from the
|
|
124
|
+
* questions themselves — retrying the same ask after a lost response repeats the id and
|
|
125
|
+
* the Hub recognises it, instead of posting the same question a second time.
|
|
126
|
+
*/
|
|
127
|
+
static envelopeIdFor(senderId, opts) {
|
|
128
|
+
const questions = opts.questions;
|
|
129
|
+
if (!questions || questions.length === 0)
|
|
130
|
+
return `msg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
|
|
131
|
+
// Canonical, or the same ask written two ways hashes two ways and the dedupe is lost:
|
|
132
|
+
// keys in a fixed order, signals in a fixed order, questions in a fixed order.
|
|
133
|
+
const canonical = questions
|
|
134
|
+
.map((q) => JSON.stringify([q.question, q.amount ?? null, [...(q.signals ?? [])].sort()]))
|
|
135
|
+
.sort();
|
|
136
|
+
// `limit` rides along, as the wire sees it: the same questions asked with a different
|
|
137
|
+
// page size is a different request, but two raw limits that clamp to the same value
|
|
138
|
+
// ARE the same request and a retry between them must keep its id.
|
|
139
|
+
const limit = opts.limit === undefined ? null : clampLimit(opts.limit);
|
|
140
|
+
return `msg_q_${createHash('sha256').update(JSON.stringify([senderId ?? '', canonical, limit])).digest('hex').slice(0, 32)}`;
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* Take a task. `commitmentDeadline` is the promise the node makes back: the
|
|
144
|
+
* Hub holds the task for this node until then, so a caller that cannot
|
|
145
|
+
* finish in time must not send one it cannot keep.
|
|
146
|
+
*/
|
|
147
|
+
async claimTask(taskId, opts = {}) {
|
|
148
|
+
return this.callResult('POST', '/a2a/task/claim', {
|
|
149
|
+
task_id: nonEmpty(taskId, 'taskId'),
|
|
150
|
+
node_id: this.requireSenderId('claimTask'),
|
|
151
|
+
...(opts.commitmentDeadline ? { commitment_deadline: opts.commitmentDeadline } : {}),
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
/** Hand a claimed task back to the Hub with the asset the work produced. */
|
|
155
|
+
async completeTask(taskId, assetId) {
|
|
156
|
+
return this.callResult('POST', '/a2a/task/complete', {
|
|
157
|
+
task_id: nonEmpty(taskId, 'taskId'),
|
|
158
|
+
asset_id: nonEmpty(assetId, 'assetId'),
|
|
159
|
+
node_id: this.requireSenderId('completeTask'),
|
|
160
|
+
});
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* Take a deferred worker task. The Hub gates this channel separately from
|
|
164
|
+
* `/a2a/task/claim` and answers `worker_disabled` while it is closed.
|
|
165
|
+
*/
|
|
166
|
+
async claimWorkerTask(taskId) {
|
|
167
|
+
return this.callResult('POST', '/a2a/work/claim', {
|
|
168
|
+
task_id: nonEmpty(taskId, 'taskId'),
|
|
169
|
+
node_id: this.requireSenderId('claimWorkerTask'),
|
|
170
|
+
});
|
|
171
|
+
}
|
|
172
|
+
/** Hand a worker task back with the asset it produced. */
|
|
173
|
+
async completeWorkerTask(taskId, assetId) {
|
|
174
|
+
return this.callResult('POST', '/a2a/work/complete', {
|
|
175
|
+
task_id: nonEmpty(taskId, 'taskId'),
|
|
176
|
+
asset_id: nonEmpty(assetId, 'assetId'),
|
|
177
|
+
node_id: this.requireSenderId('completeWorkerTask'),
|
|
178
|
+
});
|
|
179
|
+
}
|
|
77
180
|
async callResult(method, path, body, query) {
|
|
78
181
|
try {
|
|
79
182
|
const raw = await this.http.call(method, path, body, query);
|
package/dist/hubCapability.js
CHANGED
|
@@ -172,6 +172,8 @@ export class PublicHubCapability {
|
|
|
172
172
|
...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
|
|
173
173
|
};
|
|
174
174
|
}
|
|
175
|
+
if (isNodeMergedResponse(body, payload))
|
|
176
|
+
return helloResultFromBody(200, body);
|
|
175
177
|
if (payload['error'])
|
|
176
178
|
return { ok: false, error: String(payload['error']), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), ...(rateLimitUntilMs !== undefined ? { rateLimitUntilMs } : {}) };
|
|
177
179
|
const nodeId = stringField(payload, 'your_node_id')
|
|
@@ -203,8 +205,12 @@ export class PublicHubCapability {
|
|
|
203
205
|
};
|
|
204
206
|
}
|
|
205
207
|
catch (err) {
|
|
206
|
-
if (err instanceof AuthError)
|
|
207
|
-
|
|
208
|
+
if (err instanceof AuthError) {
|
|
209
|
+
const result = helloResultFromBody(err.status, asRecord(err.body) ?? {});
|
|
210
|
+
return result.error === 'node_merged'
|
|
211
|
+
? result
|
|
212
|
+
: { ok: false, authError: true, error: `hub auth error ${err.status}`, httpStatus: err.status };
|
|
213
|
+
}
|
|
208
214
|
if (err instanceof HubClientError)
|
|
209
215
|
return helloResultFromBody(err.status, asRecord(err.body) ?? {});
|
|
210
216
|
if (isHubUnreachableError(err))
|
|
@@ -229,8 +235,12 @@ export class PublicHubCapability {
|
|
|
229
235
|
return heartbeatResultFromBody(200, body);
|
|
230
236
|
}
|
|
231
237
|
catch (err) {
|
|
232
|
-
if (err instanceof AuthError)
|
|
233
|
-
|
|
238
|
+
if (err instanceof AuthError) {
|
|
239
|
+
const result = heartbeatResultFromBody(err.status, asRecord(err.body) ?? {});
|
|
240
|
+
return result.error === 'node_merged'
|
|
241
|
+
? result
|
|
242
|
+
: { ok: false, authError: true, error: `hub auth error ${err.status}` };
|
|
243
|
+
}
|
|
234
244
|
if (err instanceof HubClientError)
|
|
235
245
|
return heartbeatResultFromBody(err.status, asRecord(err.body) ?? {});
|
|
236
246
|
if (isHubUnreachableError(err))
|
|
@@ -1568,9 +1578,12 @@ function helloResultFromBody(httpStatus, body) {
|
|
|
1568
1578
|
const payload = asRecord(body['payload']) ?? body;
|
|
1569
1579
|
const retryAfterMs = numberField(payload, 'retry_after_ms') ?? numberField(payload, 'retryAfterMs');
|
|
1570
1580
|
const rateLimitUntilMs = numberField(payload, 'rate_limit_until_ms') ?? numberField(payload, 'rateLimitUntilMs');
|
|
1571
|
-
const
|
|
1572
|
-
const
|
|
1573
|
-
const
|
|
1581
|
+
const nodeMerged = isNodeMergedResponse(body, payload);
|
|
1582
|
+
const status = nodeMerged ? 'node_merged' : stringField(payload, 'status');
|
|
1583
|
+
const error = nodeMerged
|
|
1584
|
+
? 'node_merged'
|
|
1585
|
+
: stringField(payload, 'error') ?? stringField(payload, 'reason') ?? (httpStatus >= 400 ? `http_${httpStatus}` : undefined);
|
|
1586
|
+
const details = nodeMerged ? undefined : payload['details'] ?? body['details'];
|
|
1574
1587
|
const authError = httpStatus === 401 || httpStatus === 403 || status === 'auth_failed' || status === 'invalid_secret';
|
|
1575
1588
|
return {
|
|
1576
1589
|
ok: false,
|
|
@@ -1591,9 +1604,13 @@ function hubUnreachableRetryAfterMs(err) {
|
|
|
1591
1604
|
function heartbeatResultFromBody(httpStatus, body) {
|
|
1592
1605
|
const payload = asRecord(body['payload']) ?? body;
|
|
1593
1606
|
const retryAfterMs = numberField(payload, 'retry_after_ms') ?? numberField(payload, 'retryAfterMs');
|
|
1594
|
-
const
|
|
1595
|
-
const
|
|
1596
|
-
const
|
|
1607
|
+
const nodeMerged = isNodeMergedResponse(body, payload);
|
|
1608
|
+
const status = nodeMerged ? 'node_merged' : stringField(payload, 'status');
|
|
1609
|
+
const error = nodeMerged
|
|
1610
|
+
? 'node_merged'
|
|
1611
|
+
: stringField(payload, 'error') ?? (httpStatus >= 400 ? `http_${httpStatus}` : undefined);
|
|
1612
|
+
const details = nodeMerged ? undefined : payload['details'] ?? body['details'];
|
|
1613
|
+
const authError = httpStatus === 401 || httpStatus === 403;
|
|
1597
1614
|
const ack = asRecord(payload['last_update_ack']);
|
|
1598
1615
|
const forceUpdate = forceUpdateFromRecord(asRecord(payload['force_update']));
|
|
1599
1616
|
const rawCapabilityGaps = payload['capability_gaps'] ?? payload['capabilityGaps'];
|
|
@@ -1607,6 +1624,7 @@ function heartbeatResultFromBody(httpStatus, body) {
|
|
|
1607
1624
|
&& !error;
|
|
1608
1625
|
return {
|
|
1609
1626
|
ok,
|
|
1627
|
+
...(authError ? { authError: true } : {}),
|
|
1610
1628
|
...(httpStatus >= 400 ? { httpStatus } : {}),
|
|
1611
1629
|
...(error ? { error } : {}),
|
|
1612
1630
|
...(details !== undefined ? { details } : {}),
|
|
@@ -1620,6 +1638,21 @@ function heartbeatResultFromBody(httpStatus, body) {
|
|
|
1620
1638
|
...(capabilityGaps !== undefined ? { capabilityGaps } : {}),
|
|
1621
1639
|
};
|
|
1622
1640
|
}
|
|
1641
|
+
function isNodeMergedResponse(body, payload) {
|
|
1642
|
+
return [
|
|
1643
|
+
payload['error'],
|
|
1644
|
+
payload['reason'],
|
|
1645
|
+
payload['status'],
|
|
1646
|
+
body['error'],
|
|
1647
|
+
body['reason'],
|
|
1648
|
+
body['status'],
|
|
1649
|
+
].some((value) => {
|
|
1650
|
+
if (typeof value !== 'string')
|
|
1651
|
+
return false;
|
|
1652
|
+
const code = value.trim();
|
|
1653
|
+
return code === 'node_merged' || code.startsWith('node_merged:');
|
|
1654
|
+
});
|
|
1655
|
+
}
|
|
1623
1656
|
function forceUpdateFromRecord(value) {
|
|
1624
1657
|
if (!value)
|
|
1625
1658
|
return undefined;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@evomap/evolver-adapter-public",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.38",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|
|
@@ -17,8 +17,8 @@
|
|
|
17
17
|
},
|
|
18
18
|
"dependencies": {
|
|
19
19
|
"@evomap/atp-sdk": "^0.1.0",
|
|
20
|
-
"@evomap/evolver-core": "2.0.
|
|
21
|
-
"undici": "^6.
|
|
20
|
+
"@evomap/evolver-core": "2.0.38",
|
|
21
|
+
"undici": "^6.28.0"
|
|
22
22
|
},
|
|
23
23
|
"optionalDependencies": {
|
|
24
24
|
"@napi-rs/keyring": "^1.1.6"
|