@pulsarinteractive/geniustasker 0.1.0-beta.13 → 0.1.0-beta.15

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.
Files changed (44) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +5 -1
  3. package/docs/CHATGPT.md +17 -0
  4. package/docs/CLI.md +46 -1
  5. package/docs/FEEDBACK.md +96 -0
  6. package/docs/INTEGRATIONS.md +4 -4
  7. package/docs/PLANNING.md +149 -10
  8. package/docs/TASK_CHECKLISTS.md +85 -0
  9. package/docs/TASK_LOCKS.md +99 -0
  10. package/docs/TASK_PAUSES.md +91 -0
  11. package/examples/codex.toml +1 -1
  12. package/examples/mcp.json +1 -1
  13. package/mcp.json +1 -1
  14. package/package.json +1 -1
  15. package/plugin.json +1 -1
  16. package/remote/tool-catalog.json +735 -2
  17. package/remote/workflows.json +62 -6
  18. package/skills/geniustasker/SKILL.md +37 -0
  19. package/skills/geniustasker/references/agent-runs.md +33 -2
  20. package/skills/geniustasker/references/collaboration.md +15 -2
  21. package/skills/geniustasker/references/host-events.md +9 -0
  22. package/skills/geniustasker/references/incremental-reads.md +11 -0
  23. package/skills/geniustasker/references/protocols.md +29 -3
  24. package/skills/geniustasker-feedback/SKILL.md +44 -0
  25. package/skills/geniustasker-feedback/agents/openai.yaml +4 -0
  26. package/skills/geniustasker-planning/SKILL.md +48 -0
  27. package/src/changes.mjs +5 -1
  28. package/src/cli.mjs +134 -7
  29. package/src/client.mjs +16 -0
  30. package/src/command-catalog.mjs +156 -1
  31. package/src/command-input-schemas.mjs +924 -0
  32. package/src/commands.mjs +250 -20
  33. package/src/feedback-contract.mjs +629 -0
  34. package/src/feedback-image.mjs +123 -0
  35. package/src/feedback-media-transfer.mjs +61 -0
  36. package/src/feedback.mjs +152 -0
  37. package/src/intents.mjs +111 -0
  38. package/src/mcp.mjs +126 -3
  39. package/src/protocols.mjs +1 -0
  40. package/src/resources.mjs +26 -3
  41. package/src/task-availability-contract.mjs +166 -0
  42. package/src/task-availability.mjs +35 -0
  43. package/src/task-state-legacy-contract.mjs +121 -0
  44. package/src/transport.mjs +10 -3
package/src/commands.mjs CHANGED
@@ -1,5 +1,14 @@
1
+ import {
2
+ feedbackDraftSchema,
3
+ prepareFeedbackCommand,
4
+ readFeedbackCapabilities,
5
+ validateFeedbackCreate,
6
+ validateFeedbackUpload,
7
+ validFeedbackReceipt,
8
+ validFeedbackMediaSession,
9
+ } from './feedback.mjs';
1
10
  import { retryAt, requireRetryReady } from './recovery.mjs';
2
- import { randomUUID } from 'node:crypto';
11
+ import { randomUUID, createHash } from 'node:crypto';
3
12
  import { constants } from 'node:fs';
4
13
  import { open } from 'node:fs/promises';
5
14
  import { join } from 'node:path';
@@ -67,20 +76,33 @@ const checked = (schema, value) => {
67
76
  }
68
77
  return parsed.data;
69
78
  };
70
- /** Validate the public envelope, generated field allowlist and resource scope. */
79
+ const dataValidators = new Map();
80
+ function validateCommandData(kind, data) {
81
+ const schema = commandInputSchemas[kind];
82
+ if (!schema) {
83
+ return;
84
+ }
85
+ if (!dataValidators.has(kind)) {
86
+ dataValidators.set(kind, z.fromJSONSchema(schema));
87
+ }
88
+ checked(dataValidators.get(kind), data);
89
+ }
90
+ /** Validate the public envelope, generated data schema and resource scope. */
71
91
  export function validateCommand(value) {
72
92
  const command = checked(commandSchema, value),
73
93
  definition = catalog.commands[command.kind];
74
94
  if (
75
95
  Buffer.byteLength(JSON.stringify(command)) > catalog.maxCommandBytes ||
76
96
  Object.keys(command.data).some((key) => !definition.fields.includes(key)) ||
77
- (definition.create ? command.expectedRevision !== null : command.expectedRevision === null)
97
+ (!definition.upsert &&
98
+ (definition.create ? command.expectedRevision !== null : command.expectedRevision === null))
78
99
  ) {
79
100
  fail(
80
101
  'invalid_arguments',
81
- 'Use the declared command fields and size limit. Creation requires a null revision; other commands require the current record revision.',
102
+ 'Use the declared command fields and size limit. Creation requires a null revision; updates require the current record revision. Declared upserts use the revision returned by their dedicated read.',
82
103
  );
83
104
  }
105
+ validateCommandData(command.kind, command.data);
84
106
  const prefix =
85
107
  command.scope.startsWith('personal:') && definition.personalModule
86
108
  ? 'personal:'
@@ -179,7 +201,7 @@ const binding = (session) => ({
179
201
  profileId: session.profile_id,
180
202
  sessionId: session.session_id,
181
203
  });
182
- function checkSavedCommand(row, input, identity) {
204
+ function checkSavedCommand(row, input, identity, protocol) {
183
205
  if (row && (row.formatVersion !== 1 || canonical(row.binding) !== canonical(identity))) {
184
206
  fail(
185
207
  'operation_identity_mismatch',
@@ -190,7 +212,7 @@ function checkSavedCommand(row, input, identity) {
190
212
  },
191
213
  );
192
214
  }
193
- if (row && canonical(row.input) !== canonical(input)) {
215
+ if (row && (row.protocol !== protocol || canonical(row.input) !== canonical(input))) {
194
216
  fail(
195
217
  'idempotency_mismatch',
196
218
  'The operation ID already belongs to a different immutable request.',
@@ -222,6 +244,21 @@ const receiptSchema = z
222
244
  })
223
245
  .strict();
224
246
 
247
+ const confirmationProtocols = {
248
+ feedback_submit: {
249
+ validate: validateFeedbackCreate,
250
+ validReceipt: validFeedbackReceipt,
251
+ operationId: (input) => input.commandId,
252
+ path: '/api/agents/v1/feedback',
253
+ },
254
+ feedback_media_open: {
255
+ validate: validateFeedbackUpload,
256
+ validReceipt: validFeedbackMediaSession,
257
+ operationId: (input) => input.id,
258
+ path: '/api/agents/v1/feedback/media/uploads',
259
+ },
260
+ };
261
+
225
262
  /** A journal is bound to one authenticated terminal identity. Persist the full
226
263
  * request before the network call, never regenerate a UUID after a timeout.
227
264
  * It contains private project text but no access/refresh tokens. A process crash
@@ -261,14 +298,184 @@ export class CommandJournal {
261
298
  return { operationId: input.operationId, state: row?.state ?? 'prepared', request: input };
262
299
  }, this.client.transport.signal);
263
300
  }
301
+ async prepareFeedback(draft) {
302
+ const value = checked(feedbackDraftSchema, draft);
303
+ const identity = binding(await this.client.session());
304
+ if (!value.expectedEpoch) {
305
+ value.expectedEpoch = (await readFeedbackCapabilities(this.client)).epoch;
306
+ }
307
+ if (canonical(binding(await this.client.session())) !== canonical(identity)) {
308
+ fail('operation_identity_mismatch', 'The connection changed while preparing feedback.');
309
+ }
310
+ const prepared = prepareFeedbackCommand(value),
311
+ store = this.store(prepared.command.commandId);
312
+ await store.locked(
313
+ () =>
314
+ store.write({
315
+ formatVersion: 1,
316
+ protocol: 'feedback_submit',
317
+ binding: identity,
318
+ input: prepared.command,
319
+ state: 'prepared',
320
+ }),
321
+ this.client.transport.signal,
322
+ );
323
+ return prepared;
324
+ }
325
+ async submitFeedback(value) {
326
+ return this.#execute(value, 'feedback_submit');
327
+ }
328
+ async openFeedbackMedia(value) {
329
+ return this.#execute(value, 'feedback_media_open');
330
+ }
331
+ async #mediaUploadRow(store, protocol = 'feedback_media_open') {
332
+ const identity = binding(await this.client.session());
333
+ const row = await store.read();
334
+ if (
335
+ !row ||
336
+ row.formatVersion !== 1 ||
337
+ row.input?.id !== store.context ||
338
+ row.protocol !== protocol ||
339
+ row.state !== 'confirmed' ||
340
+ !confirmationProtocols[protocol].validReceipt(row.receipt, row.input)
341
+ ) {
342
+ fail(
343
+ 'operation_not_found',
344
+ 'Confirm the saved upload reservation first. Recover an uncertain reservation with commands retry.',
345
+ );
346
+ }
347
+ if (canonical(row.binding) !== canonical(identity)) {
348
+ fail(
349
+ 'operation_identity_mismatch',
350
+ 'The upload belongs to another connection, profile, session or environment.',
351
+ );
352
+ }
353
+ return { identity, row };
354
+ }
355
+ #confirmedMediaReceipt(row) {
356
+ if (row.uploadState !== 'confirmed') {
357
+ return null;
358
+ }
359
+ if (
360
+ !confirmationProtocols[row.protocol].validReceipt(row.uploadReceipt, row.input) ||
361
+ row.uploadReceipt.state !== 'ready'
362
+ ) {
363
+ fail(
364
+ 'invalid_response',
365
+ 'The saved feedback image receipt is invalid. Inspect the operation before acting.',
366
+ );
367
+ }
368
+ return row.uploadReceipt;
369
+ }
370
+ #requireCurrentMediaSize(row) {
371
+ if (row.input.size > 4_000_000) {
372
+ fail('feedback_media_too_large', 'Use a screenshot no larger than 4,000,000 bytes.', {
373
+ status: 413,
374
+ });
375
+ }
376
+ }
377
+ /** A confirmed upload can be replayed without reopening the source file.
378
+ * The same identity and receipt checks still apply; no HTTP request is made. */
379
+ async confirmedFeedbackMediaUpload(id) {
380
+ return this.#confirmedMediaUpload(id, 'feedback_media_open');
381
+ }
382
+ async #confirmedMediaUpload(id, protocol) {
383
+ const store = this.store(id);
384
+ return store.locked(async () => {
385
+ const { row } = await this.#mediaUploadRow(store, protocol);
386
+ const receipt = this.#confirmedMediaReceipt(row);
387
+ if (!receipt) {
388
+ this.#requireCurrentMediaSize(row);
389
+ }
390
+ return receipt;
391
+ }, this.client.transport.signal);
392
+ }
393
+ /** Binary transfer uses the already-confirmed immutable reservation. It
394
+ * never renews an uncertain reservation or retries another request silently. */
395
+ async uploadFeedbackMediaBytes(id, bytes, sha256) {
396
+ return this.#uploadMediaBytes(id, bytes, sha256, 'feedback_media_open');
397
+ }
398
+ async #uploadMediaBytes(id, bytes, sha256, protocol) {
399
+ const store = this.store(id);
400
+ return store.locked(async () => {
401
+ const { identity, row } = await this.#mediaUploadRow(store, protocol);
402
+ const confirmed = this.#confirmedMediaReceipt(row);
403
+ if (confirmed) {
404
+ return confirmed;
405
+ }
406
+ this.#requireCurrentMediaSize(row);
407
+ const source = row.input;
408
+ if (
409
+ !Buffer.isBuffer(bytes) ||
410
+ bytes.length !== source.size ||
411
+ sha256 !== source.sha256 ||
412
+ createHash('sha256').update(bytes).digest('hex') !== source.sha256
413
+ ) {
414
+ fail(
415
+ 'idempotency_mismatch',
416
+ 'The image bytes changed after preparation. Do not reuse this reservation.',
417
+ );
418
+ }
419
+ requireRetryReady(row.uploadRetryAt);
420
+ const session = await this.client.authorizedSession();
421
+ if (canonical(binding(session)) !== canonical(identity)) {
422
+ fail('operation_identity_mismatch', 'The connection changed before upload.');
423
+ }
424
+ await store.write({ ...row, uploadState: 'uncertain' });
425
+ this.client.invalidateReads?.();
426
+ try {
427
+ const result = await this.client.transport.request(row.receipt.uploadPath, {
428
+ method: 'PUT',
429
+ token: session.access_token,
430
+ bytes,
431
+ });
432
+ if (
433
+ !confirmationProtocols[protocol].validReceipt(result, row.input) ||
434
+ result.state !== 'ready'
435
+ ) {
436
+ fail(
437
+ 'invalid_response',
438
+ 'The feedback image upload receipt is invalid. Retry the same bytes and reservation.',
439
+ { execution: 'unknown' },
440
+ );
441
+ }
442
+ await store.write({ ...row, uploadState: 'confirmed', uploadReceipt: result });
443
+ return result;
444
+ } catch (error) {
445
+ const safe = safeError(error);
446
+ await store
447
+ .write({
448
+ ...row,
449
+ uploadState: 'uncertain',
450
+ uploadRetryAt: retryAt(error),
451
+ uploadError: safe.toJSON(),
452
+ })
453
+ .catch(() => {});
454
+ throw new AgentError(safe.code, safe.message, {
455
+ status: safe.status,
456
+ retryable: safe.retryable,
457
+ ...safe.details,
458
+ execution: 'unknown',
459
+ operationId: id,
460
+ });
461
+ }
462
+ }, this.client.transport.signal);
463
+ }
264
464
  async inspect(id) {
265
465
  const row = await this.store(id).read();
266
- if (!row || row.formatVersion !== 1 || row.input?.operationId !== id) {
466
+ if (
467
+ !row ||
468
+ row.formatVersion !== 1 ||
469
+ (row.protocol
470
+ ? confirmationProtocols[row.protocol]?.operationId(row.input)
471
+ : row.input?.operationId) !== id
472
+ ) {
267
473
  fail('operation_not_found', 'This context has no valid local operation with that ID.');
268
474
  }
269
475
  return {
270
476
  operationId: id,
271
477
  source: 'local_journal',
478
+ ...(row.protocol ? { protocol: row.protocol } : {}),
272
479
  state: row.state,
273
480
  request: row.input,
274
481
  ...(row.receipt ? { receipt: row.receipt } : {}),
@@ -277,16 +484,27 @@ export class CommandJournal {
277
484
  };
278
485
  }
279
486
  async execute(value) {
280
- const input = validateCommand(value),
281
- store = this.store(input.operationId);
487
+ return this.#execute(value);
488
+ }
489
+ async #execute(value, protocol) {
490
+ const typed = protocol ? confirmationProtocols[protocol] : null;
491
+ if (protocol && !typed) {
492
+ fail('invalid_arguments', 'Unknown saved operation protocol.');
493
+ }
494
+ const input = typed ? typed.validate(value) : validateCommand(value),
495
+ operationId = typed ? typed.operationId(input) : input.operationId,
496
+ store = this.store(operationId);
282
497
  return store.locked(async () => {
283
498
  // Capture token and identity together under the refresh lock. A later
284
499
  // logout/login cannot turn this pending operation into another profile.
285
500
  const localSession = await this.client.session(),
286
501
  identity = binding(localSession);
287
502
  let row = await store.read();
288
- checkSavedCommand(row, input, identity);
503
+ checkSavedCommand(row, input, identity, protocol);
289
504
  if (row?.state === 'confirmed') {
505
+ if (typed && !typed.validReceipt(row.receipt, input)) {
506
+ fail('invalid_response', 'Invalid saved feedback receipt.');
507
+ }
290
508
  return { source: 'local_receipt', receipt: row.receipt };
291
509
  }
292
510
  requireRetryReady(row?.retryAt);
@@ -294,17 +512,28 @@ export class CommandJournal {
294
512
  if (canonical(binding(session)) !== canonical(identity)) {
295
513
  fail('operation_identity_mismatch', 'The connection changed before transmission.');
296
514
  }
297
- row = { formatVersion: 1, binding: identity, input, state: 'uncertain' };
515
+ row = {
516
+ formatVersion: 1,
517
+ ...(protocol ? { protocol } : {}),
518
+ binding: identity,
519
+ input,
520
+ state: 'uncertain',
521
+ };
298
522
  await store.write(row);
299
523
  try {
300
- const receipt = await this.client.transport.request('/api/agents/v1/commands', {
301
- method: 'POST',
302
- json: input,
303
- token: session.access_token,
304
- });
524
+ const receipt = await this.client.transport.request(
525
+ typed?.path ?? '/api/agents/v1/commands',
526
+ {
527
+ method: 'POST',
528
+ json: input,
529
+ token: session.access_token,
530
+ },
531
+ );
305
532
  if (
306
- !receiptSchema.safeParse(receipt).success ||
307
- ['operationId', 'scope', 'kind', 'epoch'].some((key) => receipt[key] !== input[key])
533
+ typed
534
+ ? !typed.validReceipt(receipt, input)
535
+ : !receiptSchema.safeParse(receipt).success ||
536
+ ['operationId', 'scope', 'kind', 'epoch'].some((key) => receipt[key] !== input[key])
308
537
  ) {
309
538
  fail(
310
539
  'invalid_response',
@@ -322,7 +551,7 @@ export class CommandJournal {
322
551
  remediation: safe.remediation,
323
552
  execution: 'unknown',
324
553
  ...safe.details,
325
- operationId: input.operationId,
554
+ operationId,
326
555
  });
327
556
  // The uncertainty marker is already durable. Preserve the useful original
328
557
  // error/operation ID even if disk pressure prevents saving diagnostics.
@@ -334,6 +563,7 @@ export class CommandJournal {
334
563
  }, this.client.transport.signal);
335
564
  }
336
565
  async retry(id) {
337
- return this.execute((await this.inspect(id)).request);
566
+ const saved = await this.inspect(id);
567
+ return this.#execute(saved.request, saved.protocol);
338
568
  }
339
569
  }