@evomap/evolver-adapter-public 2.0.36 → 2.0.37

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);
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.37",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "engines": {
@@ -17,7 +17,7 @@
17
17
  },
18
18
  "dependencies": {
19
19
  "@evomap/atp-sdk": "^0.1.0",
20
- "@evomap/evolver-core": "2.0.36",
20
+ "@evomap/evolver-core": "2.0.37",
21
21
  "undici": "^6.27.0"
22
22
  },
23
23
  "optionalDependencies": {