@opengeni/codemode 1.2.1-canary.37222965366001 → 1.4.0

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,35 @@
1
+ export type IdPage = {
2
+ ids: readonly string[];
3
+ nextPageToken?: string | null;
4
+ };
5
+ /** Collect every page before mutation. A failed/incomplete read never returns a selection. */
6
+ export declare function collectIdPages(load: (pageToken: string | undefined, signal?: AbortSignal) => Promise<IdPage>, options?: {
7
+ maxItems?: number;
8
+ maxPages?: number;
9
+ signal?: AbortSignal;
10
+ }): Promise<readonly string[]>;
11
+ export type IdBatchPlan = {
12
+ readonly id: string;
13
+ readonly selectionDigest: string;
14
+ readonly count: number;
15
+ readonly batches: readonly {
16
+ readonly operationId: string;
17
+ readonly ids: readonly string[];
18
+ }[];
19
+ };
20
+ /** Pure chunk plan. Each chunk is a separate durable operation and review, never a fresh query. */
21
+ export declare function planIdBatches(selection: readonly string[], maxBatchSize?: number): IdBatchPlan;
22
+ export type IdBatchReceipt = {
23
+ operationId: string;
24
+ outcome: "acknowledged" | "failed_before_effect" | "unknown" | "waiting";
25
+ };
26
+ /** No per-item success is implied by a provider's batch acknowledgement. */
27
+ export declare function summarizeIdBatches(plan: IdBatchPlan, receipts: readonly IdBatchReceipt[]): {
28
+ acknowledged: number;
29
+ failed_before_effect: number;
30
+ unknown: number;
31
+ waiting: number;
32
+ unstarted: number;
33
+ selected: number;
34
+ individualStateVerified: false;
35
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@opengeni/codemode",
3
- "version": "1.2.1-canary.37222965366001",
3
+ "version": "1.4.0",
4
4
  "description": "Attempt-frozen programmatic tool catalog and execution authority for OpenGeni.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -34,9 +34,9 @@
34
34
  "prepublishOnly": "bash ../../scripts/prepublish-guard"
35
35
  },
36
36
  "dependencies": {
37
- "@opengeni/contracts": "1.2.1-canary.37222965366001",
38
- "@opengeni/sdk": "1.2.1-canary.37222965366001",
39
- "@opengeni/tool-gateway": "1.2.1-canary.37222965366001"
37
+ "@opengeni/contracts": "1.4.0",
38
+ "@opengeni/sdk": "1.4.0",
39
+ "@opengeni/tool-gateway": "1.4.0"
40
40
  },
41
41
  "engines": {
42
42
  "node": ">=18"
package/src/index.ts CHANGED
@@ -137,6 +137,23 @@ export class CodemodeOperationError extends Error {
137
137
  ) {
138
138
  super(operation.errorMessage ?? `Codemode operation ${operation.state}`);
139
139
  this.name = "CodemodeOperationError";
140
+ // Preserve the public operation property without dumping protected arguments into error logs.
141
+ Object.defineProperty(this, "operation", { value: operation, enumerable: false });
142
+ }
143
+ }
144
+
145
+ /** Compact receipt: payloads remain in the protected operation journal. */
146
+ export class CodemodeApprovalPendingError extends Error {
147
+ readonly code = "codemode_approval_pending";
148
+ readonly state = "waiting_for_approval";
149
+ constructor(
150
+ readonly operationId: string,
151
+ readonly approvalRequestId: string | undefined,
152
+ ) {
153
+ super(
154
+ `Operation ${operationId} is waiting for approval. After review, read or resume this handle; do not submit its arguments again.`,
155
+ );
156
+ this.name = "CodemodeApprovalPendingError";
140
157
  }
141
158
  }
142
159
 
@@ -334,6 +351,9 @@ export class CodemodeClient {
334
351
  } else {
335
352
  operation = await this.read(operationId, options.signal);
336
353
  }
354
+ if (operation.state === "waiting_for_approval") {
355
+ throw new CodemodeApprovalPendingError(operation.operationId, operation.approvalRequestId);
356
+ }
337
357
  if (operation.state === "completed") {
338
358
  return { result: AttemptToolResult.parse(operation.result), entry };
339
359
  }
@@ -413,11 +433,51 @@ export class CodemodeClient {
413
433
  catalogDigest,
414
434
  identity,
415
435
  arguments: argumentsValue,
436
+ durableApproval: true,
416
437
  }),
417
438
  });
418
439
  return CodemodeCallSubmission.parse(await response.json()).operation;
419
440
  }
420
441
 
442
+ /** Observe a durable handle using the current attempt, without resubmitting its payload. */
443
+ async status(operationId: string, signal?: AbortSignal) {
444
+ const operation = await this.read(operationId, signal);
445
+ return {
446
+ operationId: operation.operationId,
447
+ state: operation.state,
448
+ approvalRequestId: operation.approvalRequestId,
449
+ result: operation.result,
450
+ errorCode: operation.errorCode,
451
+ errorMessage: operation.errorMessage,
452
+ };
453
+ }
454
+
455
+ /** Observe continuation after review. Human approval wakes the worker; this never grants permission. */
456
+ async resume(
457
+ operationId: string,
458
+ options: Omit<CodemodeCallOptions, "operationId"> = {},
459
+ ): Promise<AttemptToolResultValue> {
460
+ const deadline =
461
+ Date.now() + boundedPositiveInteger(options.timeoutMs ?? this.timeoutMs, 1_000, 60 * 60_000);
462
+ while (true) {
463
+ throwIfAborted(options.signal);
464
+ const operation = await this.read(operationId, options.signal);
465
+ if (operation.state === "waiting_for_approval")
466
+ throw new CodemodeApprovalPendingError(operation.operationId, operation.approvalRequestId);
467
+ if (operation.state === "completed") return AttemptToolResult.parse(operation.result);
468
+ if (["failed", "outcome_unknown", "cancelled"].includes(operation.state))
469
+ throw new CodemodeOperationError(
470
+ operation,
471
+ operation.errorCode ?? `codemode_${operation.state}`,
472
+ );
473
+ if (Date.now() >= deadline)
474
+ throw new CodemodeTransportError(
475
+ `Codemode operation ${operationId} did not settle before the client deadline`,
476
+ );
477
+ await abortableDelay(this.pollIntervalMs, options.signal);
478
+ }
479
+ }
480
+
421
481
  private async read(operationId: string, signal?: AbortSignal): Promise<CodemodeOperationValue> {
422
482
  const response = await this.request(`/calls/${operationId}`, {
423
483
  method: "GET",
@@ -442,6 +502,7 @@ export class CodemodeClient {
442
502
  headers: {
443
503
  ...Object.fromEntries(new Headers(init.headers).entries()),
444
504
  authorization: `Bearer ${token}`,
505
+ "x-opengeni-codemode-capabilities": "durable-approval-v1",
445
506
  },
446
507
  });
447
508
  if (!response.ok && throwOnError) {
@@ -562,6 +623,10 @@ export class AttemptToolEnvironment {
562
623
  return await this.gateway.prepareCall(call, context);
563
624
  }
564
625
 
626
+ effectDigest(identity: AttemptToolIdentity): string {
627
+ return this.gateway.effectDigest(identity);
628
+ }
629
+
565
630
  async callModel(input: ModelAttemptToolCall): Promise<AttemptToolResultValue> {
566
631
  return await this.gateway.callModel(input);
567
632
  }
@@ -776,3 +841,5 @@ export * from "./artifacts";
776
841
  export * from "./structured";
777
842
  export * from "./declarations";
778
843
  export * from "./site";
844
+
845
+ export * from "./pagination";
@@ -0,0 +1,97 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+
3
+ export type IdPage = { ids: readonly string[]; nextPageToken?: string | null };
4
+ /** Collect every page before mutation. A failed/incomplete read never returns a selection. */
5
+ export async function collectIdPages(
6
+ load: (pageToken: string | undefined, signal?: AbortSignal) => Promise<IdPage>,
7
+ options: { maxItems?: number; maxPages?: number; signal?: AbortSignal } = {},
8
+ ): Promise<readonly string[]> {
9
+ const maxItems = options.maxItems ?? 10_000,
10
+ maxPages = options.maxPages ?? 200;
11
+ if (
12
+ !Number.isSafeInteger(maxItems) ||
13
+ maxItems < 1 ||
14
+ maxItems > 50_000 ||
15
+ !Number.isSafeInteger(maxPages) ||
16
+ maxPages < 1 ||
17
+ maxPages > 1000
18
+ )
19
+ throw new Error("Invalid selection limit");
20
+ const ids = new Set<string>(),
21
+ tokens = new Set<string>();
22
+ let token: string | undefined;
23
+ for (let index = 0; index < maxPages; index++) {
24
+ options.signal?.throwIfAborted();
25
+ const page = await load(token, options.signal);
26
+ options.signal?.throwIfAborted();
27
+ if (!Array.isArray(page?.ids) || page.ids.length > 50_000)
28
+ throw new Error("Invalid selection page");
29
+ for (const id of page.ids) {
30
+ if (typeof id !== "string" || !id || id.length > 256) throw new Error("Invalid selection ID");
31
+ ids.add(id);
32
+ if (ids.size > maxItems)
33
+ throw new Error("Selection exceeds item limit; no complete selection returned");
34
+ }
35
+ if (!page.nextPageToken) return Object.freeze([...ids]);
36
+ if (typeof page.nextPageToken !== "string" || page.nextPageToken.length > 4096)
37
+ throw new Error("Invalid page token");
38
+ if (!page.ids.length || tokens.has(page.nextPageToken))
39
+ throw new Error("Pagination did not progress; no complete selection returned");
40
+ tokens.add(page.nextPageToken);
41
+ token = page.nextPageToken;
42
+ }
43
+ throw new Error("Selection exceeds page limit; no complete selection returned");
44
+ }
45
+
46
+ export type IdBatchPlan = {
47
+ readonly id: string;
48
+ readonly selectionDigest: string;
49
+ readonly count: number;
50
+ readonly batches: readonly { readonly operationId: string; readonly ids: readonly string[] }[];
51
+ };
52
+ /** Pure chunk plan. Each chunk is a separate durable operation and review, never a fresh query. */
53
+ export function planIdBatches(selection: readonly string[], maxBatchSize = 1000): IdBatchPlan {
54
+ if (
55
+ !Number.isSafeInteger(maxBatchSize) ||
56
+ maxBatchSize < 1 ||
57
+ maxBatchSize > 1000 ||
58
+ selection.length > 50_000
59
+ )
60
+ throw new Error("Invalid batch limit");
61
+ if (selection.some((id) => typeof id !== "string" || !id || id.length > 256))
62
+ throw new Error("Invalid selection ID");
63
+ const ids = [...new Set(selection)];
64
+ const batches = Array.from({ length: Math.ceil(ids.length / maxBatchSize) }, (_, index) =>
65
+ Object.freeze({
66
+ operationId: randomUUID(),
67
+ ids: Object.freeze(ids.slice(index * maxBatchSize, (index + 1) * maxBatchSize)),
68
+ }),
69
+ );
70
+ return Object.freeze({
71
+ id: randomUUID(),
72
+ selectionDigest: createHash("sha256").update(JSON.stringify(ids)).digest("hex"),
73
+ count: ids.length,
74
+ batches: Object.freeze(batches),
75
+ });
76
+ }
77
+
78
+ export type IdBatchReceipt = {
79
+ operationId: string;
80
+ outcome: "acknowledged" | "failed_before_effect" | "unknown" | "waiting";
81
+ };
82
+ /** No per-item success is implied by a provider's batch acknowledgement. */
83
+ export function summarizeIdBatches(plan: IdBatchPlan, receipts: readonly IdBatchReceipt[]) {
84
+ const byId = new Map<string, IdBatchReceipt["outcome"]>();
85
+ const known = new Set(plan.batches.map((batch) => batch.operationId));
86
+ for (const receipt of receipts) {
87
+ if (!["acknowledged", "failed_before_effect", "unknown", "waiting"].includes(receipt.outcome))
88
+ throw new Error("Invalid batch outcome");
89
+ if (!known.has(receipt.operationId) || byId.has(receipt.operationId))
90
+ throw new Error("Receipt does not uniquely identify a planned batch");
91
+ byId.set(receipt.operationId, receipt.outcome);
92
+ }
93
+ const counts = { acknowledged: 0, failed_before_effect: 0, unknown: 0, waiting: 0, unstarted: 0 };
94
+ for (const batch of plan.batches)
95
+ counts[byId.get(batch.operationId) ?? "unstarted"] += batch.ids.length;
96
+ return { selected: plan.count, ...counts, individualStateVerified: false as const };
97
+ }