@pulsarinteractive/geniustasker 0.1.0-beta.10 → 0.1.0-beta.12

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.
@@ -0,0 +1,8 @@
1
+ interface CommandInputDataSchema {
2
+ type: 'object';
3
+ required: string[];
4
+ properties: Record<string, unknown>;
5
+ additionalProperties: false;
6
+ }
7
+ declare const schemas: Record<string, CommandInputDataSchema>;
8
+ export default schemas;
@@ -0,0 +1,470 @@
1
+ // Generated public command data schemas. Do not edit by hand.
2
+ export default {
3
+ "protocol.apply": {
4
+ "type": "object",
5
+ "required": [
6
+ "count",
7
+ "digest",
8
+ "from"
9
+ ],
10
+ "properties": {
11
+ "digest": {
12
+ "type": "string",
13
+ "maxLength": 64,
14
+ "pattern": "^[a-f0-9]{64}$"
15
+ },
16
+ "from": {
17
+ "type": "integer",
18
+ "minimum": 0,
19
+ "maximum": 199
20
+ },
21
+ "count": {
22
+ "type": "integer",
23
+ "minimum": 1,
24
+ "maximum": 20
25
+ }
26
+ },
27
+ "additionalProperties": false
28
+ },
29
+ "protocol.cancel": {
30
+ "type": "object",
31
+ "required": [],
32
+ "properties": {},
33
+ "additionalProperties": false
34
+ },
35
+ "protocol.publish": {
36
+ "type": "object",
37
+ "required": [
38
+ "definition",
39
+ "previousVersionId"
40
+ ],
41
+ "properties": {
42
+ "definition": {
43
+ "type": "object",
44
+ "required": [
45
+ "description",
46
+ "formatVersion",
47
+ "name",
48
+ "steps",
49
+ "variables"
50
+ ],
51
+ "properties": {
52
+ "description": {
53
+ "type": "string",
54
+ "maxLength": 1000
55
+ },
56
+ "formatVersion": {
57
+ "type": "integer",
58
+ "minimum": 1,
59
+ "maximum": 1
60
+ },
61
+ "name": {
62
+ "type": "string",
63
+ "minLength": 1,
64
+ "maxLength": 160
65
+ },
66
+ "steps": {
67
+ "type": "array",
68
+ "minItems": 1,
69
+ "maxItems": 200,
70
+ "items": {
71
+ "type": "object",
72
+ "required": [
73
+ "acceptance",
74
+ "delivery",
75
+ "dependencies",
76
+ "description",
77
+ "dueAfterDays",
78
+ "importance",
79
+ "importanceReason",
80
+ "key",
81
+ "kind",
82
+ "ownerVariable",
83
+ "parent",
84
+ "title"
85
+ ],
86
+ "properties": {
87
+ "acceptance": {
88
+ "type": "array",
89
+ "minItems": 1,
90
+ "maxItems": 10,
91
+ "items": {
92
+ "type": "string"
93
+ }
94
+ },
95
+ "delivery": {
96
+ "type": "object",
97
+ "required": [
98
+ "animation",
99
+ "push",
100
+ "recap"
101
+ ],
102
+ "properties": {
103
+ "animation": {
104
+ "type": "string",
105
+ "enum": [
106
+ "inherit",
107
+ "silent",
108
+ "request"
109
+ ]
110
+ },
111
+ "push": {
112
+ "type": "string",
113
+ "enum": [
114
+ "inherit",
115
+ "silent",
116
+ "request"
117
+ ]
118
+ },
119
+ "recap": {
120
+ "type": "boolean"
121
+ }
122
+ },
123
+ "additionalProperties": false
124
+ },
125
+ "dependencies": {
126
+ "type": "array",
127
+ "maxItems": 20,
128
+ "uniqueItems": true,
129
+ "items": {
130
+ "type": "string"
131
+ }
132
+ },
133
+ "description": {
134
+ "type": "string",
135
+ "maxLength": 600
136
+ },
137
+ "dueAfterDays": {
138
+ "anyOf": [
139
+ {
140
+ "type": "integer",
141
+ "minimum": 0,
142
+ "maximum": 3650
143
+ },
144
+ {
145
+ "type": "null"
146
+ }
147
+ ]
148
+ },
149
+ "importance": {
150
+ "type": "string",
151
+ "enum": [
152
+ "Minor",
153
+ "Normal",
154
+ "Important",
155
+ "Critical"
156
+ ]
157
+ },
158
+ "importanceReason": {
159
+ "type": "string",
160
+ "maxLength": 400
161
+ },
162
+ "key": {
163
+ "type": "string",
164
+ "maxLength": 48,
165
+ "pattern": "^[a-z][a-z0-9_-]{0,47}$"
166
+ },
167
+ "kind": {
168
+ "type": "string",
169
+ "enum": [
170
+ "Ticket",
171
+ "Epic",
172
+ "Subtask"
173
+ ]
174
+ },
175
+ "ownerVariable": {
176
+ "anyOf": [
177
+ {
178
+ "type": "string",
179
+ "maxLength": 48
180
+ },
181
+ {
182
+ "type": "null"
183
+ }
184
+ ]
185
+ },
186
+ "parent": {
187
+ "anyOf": [
188
+ {
189
+ "type": "string",
190
+ "maxLength": 48
191
+ },
192
+ {
193
+ "type": "null"
194
+ }
195
+ ]
196
+ },
197
+ "title": {
198
+ "type": "string",
199
+ "minLength": 3,
200
+ "maxLength": 200
201
+ }
202
+ },
203
+ "additionalProperties": false
204
+ }
205
+ },
206
+ "variables": {
207
+ "type": "array",
208
+ "maxItems": 24,
209
+ "items": {
210
+ "type": "object",
211
+ "required": [
212
+ "key",
213
+ "kind",
214
+ "label",
215
+ "required"
216
+ ],
217
+ "properties": {
218
+ "defaultValue": {},
219
+ "key": {
220
+ "type": "string",
221
+ "maxLength": 48,
222
+ "pattern": "^[a-z][a-z0-9_-]{0,47}$"
223
+ },
224
+ "kind": {
225
+ "type": "string",
226
+ "enum": [
227
+ "text",
228
+ "number",
229
+ "boolean",
230
+ "user",
231
+ "date"
232
+ ]
233
+ },
234
+ "label": {
235
+ "type": "string",
236
+ "minLength": 1,
237
+ "maxLength": 120
238
+ },
239
+ "required": {
240
+ "type": "boolean"
241
+ }
242
+ },
243
+ "additionalProperties": false
244
+ }
245
+ }
246
+ },
247
+ "additionalProperties": false
248
+ },
249
+ "previousVersionId": {
250
+ "anyOf": [
251
+ {
252
+ "type": "string",
253
+ "maxLength": 36
254
+ },
255
+ {
256
+ "type": "null"
257
+ }
258
+ ]
259
+ }
260
+ },
261
+ "additionalProperties": false
262
+ },
263
+ "protocol.start": {
264
+ "type": "object",
265
+ "required": [
266
+ "bindings",
267
+ "protocolVersionId"
268
+ ],
269
+ "properties": {
270
+ "protocolVersionId": {
271
+ "type": "string",
272
+ "maxLength": 36
273
+ },
274
+ "bindings": {
275
+ "type": "object",
276
+ "required": [
277
+ "anchor",
278
+ "epoch",
279
+ "instanceId",
280
+ "scope",
281
+ "values"
282
+ ],
283
+ "properties": {
284
+ "anchor": {
285
+ "type": "string"
286
+ },
287
+ "epoch": {
288
+ "type": "string",
289
+ "minLength": 1,
290
+ "maxLength": 128
291
+ },
292
+ "instanceId": {
293
+ "type": "string",
294
+ "maxLength": 36,
295
+ "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
296
+ },
297
+ "scope": {
298
+ "type": "string",
299
+ "maxLength": 128,
300
+ "pattern": "^project:[A-Za-z0-9_-]+$"
301
+ },
302
+ "values": {
303
+ "type": "object",
304
+ "maxProperties": 24,
305
+ "additionalProperties": {}
306
+ }
307
+ },
308
+ "additionalProperties": false
309
+ }
310
+ },
311
+ "additionalProperties": false
312
+ },
313
+ "run.checkpoint": {
314
+ "type": "object",
315
+ "required": [
316
+ "state",
317
+ "summary"
318
+ ],
319
+ "properties": {
320
+ "state": {
321
+ "type": "string",
322
+ "enum": [
323
+ "Working",
324
+ "Waiting",
325
+ "NeedsReview"
326
+ ]
327
+ },
328
+ "summary": {
329
+ "type": "string",
330
+ "minLength": 1,
331
+ "maxLength": 2000
332
+ },
333
+ "nextSteps": {
334
+ "type": "string",
335
+ "maxLength": 4000
336
+ },
337
+ "evidence": {
338
+ "type": "array",
339
+ "maxItems": 8,
340
+ "items": {
341
+ "type": "object",
342
+ "required": [
343
+ "label",
344
+ "url"
345
+ ],
346
+ "properties": {
347
+ "label": {
348
+ "type": "string",
349
+ "minLength": 1,
350
+ "maxLength": 120
351
+ },
352
+ "url": {
353
+ "type": "string",
354
+ "minLength": 1,
355
+ "maxLength": 2048
356
+ }
357
+ },
358
+ "additionalProperties": false
359
+ }
360
+ },
361
+ "leaseSeconds": {
362
+ "type": "integer",
363
+ "minimum": 60,
364
+ "maximum": 900
365
+ }
366
+ },
367
+ "additionalProperties": false
368
+ },
369
+ "run.claim": {
370
+ "type": "object",
371
+ "required": [
372
+ "summary",
373
+ "task",
374
+ "taskRevision"
375
+ ],
376
+ "properties": {
377
+ "task": {
378
+ "type": "string",
379
+ "minLength": 1,
380
+ "maxLength": 128
381
+ },
382
+ "taskRevision": {
383
+ "type": "string",
384
+ "minLength": 1,
385
+ "maxLength": 40
386
+ },
387
+ "summary": {
388
+ "type": "string",
389
+ "minLength": 1,
390
+ "maxLength": 2000
391
+ },
392
+ "leaseSeconds": {
393
+ "type": "integer",
394
+ "minimum": 60,
395
+ "maximum": 900
396
+ }
397
+ },
398
+ "additionalProperties": false
399
+ },
400
+ "run.finish": {
401
+ "type": "object",
402
+ "required": [
403
+ "state",
404
+ "summary"
405
+ ],
406
+ "properties": {
407
+ "state": {
408
+ "type": "string",
409
+ "enum": [
410
+ "Completed",
411
+ "Failed",
412
+ "Cancelled"
413
+ ]
414
+ },
415
+ "summary": {
416
+ "type": "string",
417
+ "minLength": 1,
418
+ "maxLength": 2000
419
+ },
420
+ "nextSteps": {
421
+ "type": "string",
422
+ "maxLength": 4000
423
+ },
424
+ "evidence": {
425
+ "type": "array",
426
+ "maxItems": 8,
427
+ "items": {
428
+ "type": "object",
429
+ "required": [
430
+ "label",
431
+ "url"
432
+ ],
433
+ "properties": {
434
+ "label": {
435
+ "type": "string",
436
+ "minLength": 1,
437
+ "maxLength": 120
438
+ },
439
+ "url": {
440
+ "type": "string",
441
+ "minLength": 1,
442
+ "maxLength": 2048
443
+ }
444
+ },
445
+ "additionalProperties": false
446
+ }
447
+ }
448
+ },
449
+ "additionalProperties": false
450
+ },
451
+ "run.patch": {
452
+ "type": "object",
453
+ "required": [
454
+ "patch",
455
+ "taskRevision"
456
+ ],
457
+ "properties": {
458
+ "taskRevision": {
459
+ "type": "string",
460
+ "minLength": 1,
461
+ "maxLength": 40
462
+ },
463
+ "patch": {
464
+ "type": "object",
465
+ "additionalProperties": {}
466
+ }
467
+ },
468
+ "additionalProperties": false
469
+ }
470
+ };
package/src/commands.mjs CHANGED
@@ -1,9 +1,11 @@
1
+ import { retryAt, requireRetryReady } from './recovery.mjs';
1
2
  import { randomUUID } from 'node:crypto';
2
3
  import { constants } from 'node:fs';
3
4
  import { open } from 'node:fs/promises';
4
5
  import { join } from 'node:path';
5
6
  import * as z from 'zod/v4';
6
7
  import catalog from './command-catalog.mjs';
8
+ import commandInputSchemas from './command-input-schemas.mjs';
7
9
  import { CredentialStore } from './store.mjs';
8
10
  import { AgentError, fail, safeError } from './errors.mjs';
9
11
 
@@ -95,9 +97,29 @@ export function validateCommand(value) {
95
97
  }
96
98
  return command;
97
99
  }
100
+ export const commandHelpSchema = z.object({ kind: z.enum(Object.keys(catalog.commands)) }).strict();
101
+ export function commandHelp(input) {
102
+ const { kind } = checked(commandHelpSchema, input);
103
+ const definition = catalog.commands[kind];
104
+ const schema = commandInputSchemas[kind];
105
+ return {
106
+ kind,
107
+ ...definition,
108
+ ...(schema
109
+ ? {
110
+ requiredFields: schema.required,
111
+ properties: schema.properties,
112
+ dataSchema: schema,
113
+ }
114
+ : {}),
115
+ };
116
+ }
98
117
  export function describeCommands() {
99
118
  return {
100
119
  ...catalog,
120
+ commands: Object.fromEntries(
121
+ Object.keys(catalog.commands).map((kind) => [kind, commandHelp({ kind })]),
122
+ ),
101
123
  envelope: z.toJSONSchema(commandSchema),
102
124
  draft: z.toJSONSchema(draftSchema),
103
125
  recovery:
@@ -140,6 +162,28 @@ const binding = (session) => ({
140
162
  profileId: session.profile_id,
141
163
  sessionId: session.session_id,
142
164
  });
165
+ function checkSavedCommand(row, input, identity) {
166
+ if (row && (row.formatVersion !== 1 || canonical(row.binding) !== canonical(identity))) {
167
+ fail(
168
+ 'operation_identity_mismatch',
169
+ 'This operation belongs to another connection, profile, session or environment.',
170
+ {
171
+ remediation:
172
+ 'Inspect it locally and reread current records. Do not replay it through a replacement login.',
173
+ },
174
+ );
175
+ }
176
+ if (row && canonical(row.input) !== canonical(input)) {
177
+ fail(
178
+ 'idempotency_mismatch',
179
+ 'The operation ID already belongs to a different immutable request.',
180
+ {
181
+ status: 409,
182
+ remediation: 'Use commands inspect, then retry the saved operation.',
183
+ },
184
+ );
185
+ }
186
+ }
143
187
  const receiptSchema = z
144
188
  .object({
145
189
  operationId: operationIdSchema,
@@ -183,13 +227,22 @@ export class CommandJournal {
183
227
  operationId: randomUUID(),
184
228
  issuedAt: Date.now(),
185
229
  });
230
+ return this.prepareExact(input);
231
+ }
232
+ /** Hosts already have stable event IDs/times. Preserve their exact command,
233
+ * including an existing uncertain or confirmed journal, without sending it. */
234
+ async prepareExact(value) {
235
+ const input = validateCommand(value);
186
236
  const identity = binding(await this.client.session()),
187
237
  store = this.store(input.operationId);
188
- await store.locked(
189
- () => store.write({ formatVersion: 1, binding: identity, input, state: 'prepared' }),
190
- this.client.transport.signal,
191
- );
192
- return { operationId: input.operationId, state: 'prepared', request: input };
238
+ return store.locked(async () => {
239
+ const row = await store.read();
240
+ checkSavedCommand(row, input, identity);
241
+ if (!row) {
242
+ await store.write({ formatVersion: 1, binding: identity, input, state: 'prepared' });
243
+ }
244
+ return { operationId: input.operationId, state: row?.state ?? 'prepared', request: input };
245
+ }, this.client.transport.signal);
193
246
  }
194
247
  async inspect(id) {
195
248
  const row = await this.store(id).read();
@@ -203,6 +256,7 @@ export class CommandJournal {
203
256
  request: row.input,
204
257
  ...(row.receipt ? { receipt: row.receipt } : {}),
205
258
  ...(row.error ? { error: row.error } : {}),
259
+ ...(row.retryAt ? { retryAt: row.retryAt } : {}),
206
260
  };
207
261
  }
208
262
  async execute(value) {
@@ -211,29 +265,18 @@ export class CommandJournal {
211
265
  return store.locked(async () => {
212
266
  // Capture token and identity together under the refresh lock. A later
213
267
  // logout/login cannot turn this pending operation into another profile.
214
- const session = await this.client.authorizedSession(),
215
- identity = binding(session);
268
+ const localSession = await this.client.session(),
269
+ identity = binding(localSession);
216
270
  let row = await store.read();
217
- if (row && (row.formatVersion !== 1 || canonical(row.binding) !== canonical(identity))) {
218
- fail(
219
- 'operation_identity_mismatch',
220
- 'This operation belongs to another connection, profile, session or environment.',
221
- {
222
- remediation:
223
- 'Inspect it locally and reread current records. Do not replay it through a replacement login.',
224
- },
225
- );
226
- }
227
- if (row && canonical(row.input) !== canonical(input)) {
228
- fail(
229
- 'idempotency_mismatch',
230
- 'The operation ID already belongs to a different immutable request.',
231
- { status: 409, remediation: 'Use commands inspect, then retry the saved operation.' },
232
- );
233
- }
271
+ checkSavedCommand(row, input, identity);
234
272
  if (row?.state === 'confirmed') {
235
273
  return { source: 'local_receipt', receipt: row.receipt };
236
274
  }
275
+ requireRetryReady(row?.retryAt);
276
+ const session = await this.client.authorizedSession();
277
+ if (canonical(binding(session)) !== canonical(identity)) {
278
+ fail('operation_identity_mismatch', 'The connection changed before transmission.');
279
+ }
237
280
  row = { formatVersion: 1, binding: identity, input, state: 'uncertain' };
238
281
  await store.write(row);
239
282
  try {
@@ -266,7 +309,9 @@ export class CommandJournal {
266
309
  });
267
310
  // The uncertainty marker is already durable. Preserve the useful original
268
311
  // error/operation ID even if disk pressure prevents saving diagnostics.
269
- await store.write({ ...row, error: result.toJSON() }).catch(() => {});
312
+ await store
313
+ .write({ ...row, retryAt: retryAt(result), error: result.toJSON() })
314
+ .catch(() => {});
270
315
  throw result;
271
316
  }
272
317
  }, this.client.transport.signal);