@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 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);
@@ -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
- return { ok: false, authError: true, error: `hub auth error ${err.status}`, httpStatus: err.status };
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
- return { ok: false, authError: true, error: `hub auth error ${err.status}` };
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 status = stringField(payload, 'status');
1572
- const error = stringField(payload, 'error') ?? stringField(payload, 'reason') ?? (httpStatus >= 400 ? `http_${httpStatus}` : undefined);
1573
- const details = payload['details'] ?? body['details'];
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 status = stringField(payload, 'status');
1595
- const error = stringField(payload, 'error') ?? (httpStatus >= 400 ? `http_${httpStatus}` : undefined);
1596
- const details = payload['details'] ?? body['details'];
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.36",
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.36",
21
- "undici": "^6.27.0"
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"