@cueai/omni-reader-mcp 1.5.5 → 1.7.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.
Files changed (42) hide show
  1. package/README.md +106 -46
  2. package/dist/artifact-store.d.ts +2 -0
  3. package/dist/artifact-store.js +45 -10
  4. package/dist/capabilities.d.ts +129 -2
  5. package/dist/capabilities.js +122 -19
  6. package/dist/cli/agent-config.js +2 -2
  7. package/dist/cli/arguments.d.ts +8 -4
  8. package/dist/cli/arguments.js +62 -7
  9. package/dist/cli/config-inspection.d.ts +59 -0
  10. package/dist/cli/config-inspection.js +307 -0
  11. package/dist/cli/doctor.d.ts +7 -0
  12. package/dist/cli/doctor.js +37 -2
  13. package/dist/cli/setup.js +13 -2
  14. package/dist/constants.d.ts +6 -1
  15. package/dist/constants.js +9 -4
  16. package/dist/cube-client.d.ts +4 -1
  17. package/dist/cube-client.js +286 -32
  18. package/dist/cursor.d.ts +4 -0
  19. package/dist/cursor.js +11 -13
  20. package/dist/errors.d.ts +1 -0
  21. package/dist/errors.js +15 -0
  22. package/dist/iiis-client.d.ts +33 -2
  23. package/dist/iiis-client.js +368 -40
  24. package/dist/index.js +10 -1
  25. package/dist/operation-journal.d.ts +17 -1
  26. package/dist/operation-journal.js +260 -15
  27. package/dist/operation-manager.d.ts +6 -2
  28. package/dist/operation-manager.js +448 -89
  29. package/dist/path-normalization.d.ts +5 -0
  30. package/dist/path-normalization.js +25 -0
  31. package/dist/path-security.d.ts +2 -1
  32. package/dist/path-security.js +49 -28
  33. package/dist/protocol.d.ts +10 -2
  34. package/dist/protocol.js +23 -7
  35. package/dist/remote-client.js +3 -13
  36. package/dist/result-contract.d.ts +76 -32
  37. package/dist/result-contract.js +121 -5
  38. package/dist/task-runtime.d.ts +3 -2
  39. package/dist/task-runtime.js +2 -2
  40. package/dist/tools.d.ts +4 -0
  41. package/dist/tools.js +41 -31
  42. package/package.json +1 -1
@@ -2,6 +2,7 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
2
2
  import { z } from "zod";
3
3
  import type { LocalResult } from "./artifact-store.js";
4
4
  import { type OmniBridgeErrorPayload } from "./errors.js";
5
+ import { type ResultDelivery } from "./protocol.js";
5
6
  export interface DataHandling {
6
7
  processing_copy: "in_use" | "pending" | "deleted";
7
8
  temporary_data: "in_use" | "pending" | "deleted";
@@ -11,6 +12,25 @@ export interface DataHandling {
11
12
  original_source: "unchanged";
12
13
  remote_content_retained?: false;
13
14
  }
15
+ export declare const FLAT_RESULT_ACTIONS: readonly ["read_result", "read_outline", "save_result", "discard_result"];
16
+ export declare const LOCAL_ARTIFACT_RETENTION_WARNING: "LOCAL_ARTIFACT_RETENTION_FAILED";
17
+ export interface FlatLocalResultCache {
18
+ readonly result_id: string;
19
+ readonly result_bytes: number;
20
+ readonly expires_at: string;
21
+ readonly available_actions: typeof FLAT_RESULT_ACTIONS;
22
+ readonly discard_action: "discard_result";
23
+ }
24
+ export interface LegacyBundleLocalResultCache {
25
+ readonly expires_at: string;
26
+ readonly discard_action: "discard_result";
27
+ }
28
+ export type LocalResultCache = FlatLocalResultCache | LegacyBundleLocalResultCache;
29
+ export declare function createFlatLocalResultCache(input: {
30
+ readonly resultId: string;
31
+ readonly resultBytes: number;
32
+ readonly expiresAt: string;
33
+ }): FlatLocalResultCache;
14
34
  export type ParseResult = {
15
35
  status: "processing";
16
36
  operation_id: string;
@@ -44,10 +64,8 @@ export type ParseResult = {
44
64
  credits_remaining: number;
45
65
  };
46
66
  data_handling: DataHandling;
47
- local_result_cache?: {
48
- expires_at: string;
49
- discard_action: "discard_result";
50
- };
67
+ local_result_cache?: LocalResultCache;
68
+ delivery_warning?: typeof LOCAL_ARTIFACT_RETENTION_WARNING;
51
69
  } | {
52
70
  status: "cleanup_pending";
53
71
  operation_id: string;
@@ -62,8 +80,14 @@ export type ParseResult = {
62
80
  preview: string;
63
81
  next_cursor: string;
64
82
  };
83
+ billing?: {
84
+ credits_charged: number;
85
+ credits_remaining: number;
86
+ };
65
87
  cleanup_deadline: string;
66
88
  data_handling: DataHandling;
89
+ local_result_cache?: LocalResultCache;
90
+ delivery_warning?: typeof LOCAL_ARTIFACT_RETENTION_WARNING;
67
91
  } | {
68
92
  status: "failed";
69
93
  error: OmniBridgeErrorPayload;
@@ -126,13 +150,13 @@ export declare const stableErrorSchema: z.ZodObject<{
126
150
  message: string;
127
151
  billed: boolean;
128
152
  retryable: boolean;
153
+ parser_started: boolean;
129
154
  file_uploaded: boolean;
130
155
  content_released: boolean;
131
- parser_started: boolean;
132
156
  ok: false;
133
157
  operation_created: boolean;
134
158
  failure_scope?: "source" | "local_capability" | "authentication" | "billing" | "service" | "parser" | "operation" | "cleanup" | "bridge" | undefined;
135
- source_kind?: "local" | "url" | undefined;
159
+ source_kind?: "url" | "local" | undefined;
136
160
  user_action?: string | undefined;
137
161
  request_id?: string | undefined;
138
162
  retry_after?: number | undefined;
@@ -145,13 +169,13 @@ export declare const stableErrorSchema: z.ZodObject<{
145
169
  message: string;
146
170
  billed: boolean;
147
171
  retryable: boolean;
172
+ parser_started: boolean;
148
173
  file_uploaded: boolean;
149
174
  content_released: boolean;
150
- parser_started: boolean;
151
175
  ok: false;
152
176
  operation_created: boolean;
153
177
  failure_scope?: "source" | "local_capability" | "authentication" | "billing" | "service" | "parser" | "operation" | "cleanup" | "bridge" | undefined;
154
- source_kind?: "local" | "url" | undefined;
178
+ source_kind?: "url" | "local" | undefined;
155
179
  user_action?: string | undefined;
156
180
  request_id?: string | undefined;
157
181
  retry_after?: number | undefined;
@@ -249,8 +273,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
249
273
  }, "strict", z.ZodTypeAny, {
250
274
  part: "content";
251
275
  result_bytes: number;
252
- media_type: "text/markdown; charset=utf-8";
253
276
  digest: string;
277
+ media_type: "text/markdown; charset=utf-8";
254
278
  storage: {
255
279
  text: string;
256
280
  kind: "inline";
@@ -262,8 +286,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
262
286
  }, {
263
287
  part: "content";
264
288
  result_bytes: number;
265
- media_type: "text/markdown; charset=utf-8";
266
289
  digest: string;
290
+ media_type: "text/markdown; charset=utf-8";
267
291
  storage: {
268
292
  text: string;
269
293
  kind: "inline";
@@ -300,8 +324,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
300
324
  }, "strict", z.ZodTypeAny, {
301
325
  part: "grounding";
302
326
  result_bytes: number;
303
- media_type: "application/vnd.cue.omni-grounding+json; version=1";
304
327
  digest: string;
328
+ media_type: "application/vnd.cue.omni-grounding+json; version=1";
305
329
  storage: {
306
330
  kind: "inline";
307
331
  value?: unknown;
@@ -312,8 +336,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
312
336
  }, {
313
337
  part: "grounding";
314
338
  result_bytes: number;
315
- media_type: "application/vnd.cue.omni-grounding+json; version=1";
316
339
  digest: string;
340
+ media_type: "application/vnd.cue.omni-grounding+json; version=1";
317
341
  storage: {
318
342
  kind: "inline";
319
343
  value?: unknown;
@@ -326,8 +350,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
326
350
  content: {
327
351
  part: "content";
328
352
  result_bytes: number;
329
- media_type: "text/markdown; charset=utf-8";
330
353
  digest: string;
354
+ media_type: "text/markdown; charset=utf-8";
331
355
  storage: {
332
356
  text: string;
333
357
  kind: "inline";
@@ -340,8 +364,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
340
364
  grounding: {
341
365
  part: "grounding";
342
366
  result_bytes: number;
343
- media_type: "application/vnd.cue.omni-grounding+json; version=1";
344
367
  digest: string;
368
+ media_type: "application/vnd.cue.omni-grounding+json; version=1";
345
369
  storage: {
346
370
  kind: "inline";
347
371
  value?: unknown;
@@ -354,8 +378,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
354
378
  content: {
355
379
  part: "content";
356
380
  result_bytes: number;
357
- media_type: "text/markdown; charset=utf-8";
358
381
  digest: string;
382
+ media_type: "text/markdown; charset=utf-8";
359
383
  storage: {
360
384
  text: string;
361
385
  kind: "inline";
@@ -368,8 +392,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
368
392
  grounding: {
369
393
  part: "grounding";
370
394
  result_bytes: number;
371
- media_type: "application/vnd.cue.omni-grounding+json; version=1";
372
395
  digest: string;
396
+ media_type: "application/vnd.cue.omni-grounding+json; version=1";
373
397
  storage: {
374
398
  kind: "inline";
375
399
  value?: unknown;
@@ -391,8 +415,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
391
415
  content: {
392
416
  part: "content";
393
417
  result_bytes: number;
394
- media_type: "text/markdown; charset=utf-8";
395
418
  digest: string;
419
+ media_type: "text/markdown; charset=utf-8";
396
420
  storage: {
397
421
  text: string;
398
422
  kind: "inline";
@@ -405,8 +429,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
405
429
  grounding: {
406
430
  part: "grounding";
407
431
  result_bytes: number;
408
- media_type: "application/vnd.cue.omni-grounding+json; version=1";
409
432
  digest: string;
433
+ media_type: "application/vnd.cue.omni-grounding+json; version=1";
410
434
  storage: {
411
435
  kind: "inline";
412
436
  value?: unknown;
@@ -428,8 +452,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
428
452
  content: {
429
453
  part: "content";
430
454
  result_bytes: number;
431
- media_type: "text/markdown; charset=utf-8";
432
455
  digest: string;
456
+ media_type: "text/markdown; charset=utf-8";
433
457
  storage: {
434
458
  text: string;
435
459
  kind: "inline";
@@ -442,8 +466,8 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
442
466
  grounding: {
443
467
  part: "grounding";
444
468
  result_bytes: number;
445
- media_type: "application/vnd.cue.omni-grounding+json; version=1";
446
469
  digest: string;
470
+ media_type: "application/vnd.cue.omni-grounding+json; version=1";
447
471
  storage: {
448
472
  kind: "inline";
449
473
  value?: unknown;
@@ -454,6 +478,25 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
454
478
  };
455
479
  };
456
480
  }>;
481
+ export declare const flatLocalResultCacheSchema: z.ZodObject<{
482
+ result_id: z.ZodString;
483
+ result_bytes: z.ZodNumber;
484
+ expires_at: z.ZodString;
485
+ available_actions: z.ZodTuple<[z.ZodLiteral<"read_result">, z.ZodLiteral<"read_outline">, z.ZodLiteral<"save_result">, z.ZodLiteral<"discard_result">], null>;
486
+ discard_action: z.ZodLiteral<"discard_result">;
487
+ }, "strict", z.ZodTypeAny, {
488
+ result_id: string;
489
+ expires_at: string;
490
+ result_bytes: number;
491
+ available_actions: ["read_result", "read_outline", "save_result", "discard_result"];
492
+ discard_action: "discard_result";
493
+ }, {
494
+ result_id: string;
495
+ expires_at: string;
496
+ result_bytes: number;
497
+ available_actions: ["read_result", "read_outline", "save_result", "discard_result"];
498
+ discard_action: "discard_result";
499
+ }>;
457
500
  export declare const parseResultSchema: z.ZodTypeAny;
458
501
  export declare const bundlePartReadSchema: z.ZodObject<{
459
502
  status: z.ZodLiteral<"completed">;
@@ -473,9 +516,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
473
516
  offset: number;
474
517
  part: "content";
475
518
  expires_at: string;
519
+ decoded_bytes: number;
476
520
  result_bytes: number;
477
521
  media_type: "text/markdown; charset=utf-8";
478
- decoded_bytes: number;
479
522
  next_cursor?: string | undefined;
480
523
  }, {
481
524
  text: string;
@@ -483,9 +526,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
483
526
  offset: number;
484
527
  part: "content";
485
528
  expires_at: string;
529
+ decoded_bytes: number;
486
530
  result_bytes: number;
487
531
  media_type: "text/markdown; charset=utf-8";
488
- decoded_bytes: number;
489
532
  next_cursor?: string | undefined;
490
533
  }>, z.ZodObject<{
491
534
  part: z.ZodLiteral<"grounding">;
@@ -503,9 +546,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
503
546
  offset: number;
504
547
  part: "grounding";
505
548
  expires_at: string;
549
+ decoded_bytes: number;
506
550
  result_bytes: number;
507
551
  media_type: "application/vnd.cue.omni-grounding+json; version=1";
508
- decoded_bytes: number;
509
552
  next_cursor?: string | undefined;
510
553
  }, {
511
554
  text: string;
@@ -513,9 +556,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
513
556
  offset: number;
514
557
  part: "grounding";
515
558
  expires_at: string;
559
+ decoded_bytes: number;
516
560
  result_bytes: number;
517
561
  media_type: "application/vnd.cue.omni-grounding+json; version=1";
518
- decoded_bytes: number;
519
562
  next_cursor?: string | undefined;
520
563
  }>]>, {
521
564
  text: string;
@@ -523,9 +566,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
523
566
  offset: number;
524
567
  part: "content";
525
568
  expires_at: string;
569
+ decoded_bytes: number;
526
570
  result_bytes: number;
527
571
  media_type: "text/markdown; charset=utf-8";
528
- decoded_bytes: number;
529
572
  next_cursor?: string | undefined;
530
573
  } | {
531
574
  text: string;
@@ -533,9 +576,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
533
576
  offset: number;
534
577
  part: "grounding";
535
578
  expires_at: string;
579
+ decoded_bytes: number;
536
580
  result_bytes: number;
537
581
  media_type: "application/vnd.cue.omni-grounding+json; version=1";
538
- decoded_bytes: number;
539
582
  next_cursor?: string | undefined;
540
583
  }, {
541
584
  text: string;
@@ -543,9 +586,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
543
586
  offset: number;
544
587
  part: "content";
545
588
  expires_at: string;
589
+ decoded_bytes: number;
546
590
  result_bytes: number;
547
591
  media_type: "text/markdown; charset=utf-8";
548
- decoded_bytes: number;
549
592
  next_cursor?: string | undefined;
550
593
  } | {
551
594
  text: string;
@@ -553,9 +596,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
553
596
  offset: number;
554
597
  part: "grounding";
555
598
  expires_at: string;
599
+ decoded_bytes: number;
556
600
  result_bytes: number;
557
601
  media_type: "application/vnd.cue.omni-grounding+json; version=1";
558
- decoded_bytes: number;
559
602
  next_cursor?: string | undefined;
560
603
  }>;
561
604
  }, "strict", z.ZodTypeAny, {
@@ -566,9 +609,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
566
609
  offset: number;
567
610
  part: "content";
568
611
  expires_at: string;
612
+ decoded_bytes: number;
569
613
  result_bytes: number;
570
614
  media_type: "text/markdown; charset=utf-8";
571
- decoded_bytes: number;
572
615
  next_cursor?: string | undefined;
573
616
  } | {
574
617
  text: string;
@@ -576,9 +619,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
576
619
  offset: number;
577
620
  part: "grounding";
578
621
  expires_at: string;
622
+ decoded_bytes: number;
579
623
  result_bytes: number;
580
624
  media_type: "application/vnd.cue.omni-grounding+json; version=1";
581
- decoded_bytes: number;
582
625
  next_cursor?: string | undefined;
583
626
  };
584
627
  }, {
@@ -589,9 +632,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
589
632
  offset: number;
590
633
  part: "content";
591
634
  expires_at: string;
635
+ decoded_bytes: number;
592
636
  result_bytes: number;
593
637
  media_type: "text/markdown; charset=utf-8";
594
- decoded_bytes: number;
595
638
  next_cursor?: string | undefined;
596
639
  } | {
597
640
  text: string;
@@ -599,9 +642,9 @@ export declare const bundlePartReadSchema: z.ZodObject<{
599
642
  offset: number;
600
643
  part: "grounding";
601
644
  expires_at: string;
645
+ decoded_bytes: number;
602
646
  result_bytes: number;
603
647
  media_type: "application/vnd.cue.omni-grounding+json; version=1";
604
- decoded_bytes: number;
605
648
  next_cursor?: string | undefined;
606
649
  };
607
650
  }>;
@@ -614,4 +657,5 @@ export declare const parseToolOutputSchema: z.ZodTypeAny;
614
657
  export declare const readResultToolOutputSchema: z.ZodTypeAny;
615
658
  export declare const discardResultToolOutputSchema: z.ZodTypeAny;
616
659
  export declare const saveResultToolOutputSchema: z.ZodTypeAny;
660
+ export declare function presentRetainedResult(result: ParseResult, resultDelivery: ResultDelivery, mintReadCursor: (resultId: string, byteOffset: number) => Promise<string>): Promise<ParseResult>;
617
661
  export declare function structuredResult(schema: z.ZodTypeAny, value: unknown): CallToolResult;
@@ -1,6 +1,22 @@
1
1
  import { z } from "zod";
2
2
  import { OmniBridgeError } from "./errors.js";
3
- import { RESULT_BUNDLE_PROTOCOL_VERSION } from "./protocol.js";
3
+ import { RESULT_BUNDLE_PROTOCOL_VERSION, } from "./protocol.js";
4
+ export const FLAT_RESULT_ACTIONS = [
5
+ "read_result",
6
+ "read_outline",
7
+ "save_result",
8
+ "discard_result",
9
+ ];
10
+ export const LOCAL_ARTIFACT_RETENTION_WARNING = "LOCAL_ARTIFACT_RETENTION_FAILED";
11
+ export function createFlatLocalResultCache(input) {
12
+ return {
13
+ result_id: input.resultId,
14
+ result_bytes: input.resultBytes,
15
+ expires_at: input.expiresAt,
16
+ available_actions: FLAT_RESULT_ACTIONS,
17
+ discard_action: "discard_result",
18
+ };
19
+ }
4
20
  // Maps a retained LocalResult (ArtifactStore's own representation) into the
5
21
  // wire ParseResult["result"] shape. Used both for local-file parses
6
22
  // (tools.ts's completedLocalResult, which additionally sets its own
@@ -119,8 +135,8 @@ const artifactResultSchema = z
119
135
  .strict();
120
136
  const billingSchema = z
121
137
  .object({
122
- credits_charged: z.number().nonnegative(),
123
- credits_remaining: z.number().nonnegative(),
138
+ credits_charged: z.number().finite().nonnegative(),
139
+ credits_remaining: z.number().finite().nonnegative(),
124
140
  })
125
141
  .strict();
126
142
  // v3 bundle descriptor (D2-D item 7): closed keyed-parts object. Top-level and
@@ -197,19 +213,38 @@ export const bundleDescriptorSchema = z
197
213
  .strict(),
198
214
  })
199
215
  .strict();
200
- const localResultCacheSchema = z
216
+ export const flatLocalResultCacheSchema = z
217
+ .object({
218
+ result_id: resultIdSchema,
219
+ result_bytes: z.number().int().nonnegative(),
220
+ expires_at: z.string().datetime({ offset: true }),
221
+ available_actions: z.tuple([
222
+ z.literal("read_result"),
223
+ z.literal("read_outline"),
224
+ z.literal("save_result"),
225
+ z.literal("discard_result"),
226
+ ]),
227
+ discard_action: z.literal("discard_result"),
228
+ })
229
+ .strict();
230
+ const legacyBundleLocalResultCacheSchema = z
201
231
  .object({
202
232
  expires_at: z.string().datetime({ offset: true }),
203
233
  discard_action: z.literal("discard_result"),
204
234
  })
205
235
  .strict();
236
+ const localResultCacheSchema = z.union([
237
+ flatLocalResultCacheSchema,
238
+ legacyBundleLocalResultCacheSchema,
239
+ ]);
240
+ const deliveryWarningSchema = z.literal(LOCAL_ARTIFACT_RETENTION_WARNING);
206
241
  const failedResultSchema = z
207
242
  .object({
208
243
  status: z.literal("failed"),
209
244
  error: stableErrorSchema,
210
245
  })
211
246
  .strict();
212
- export const parseResultSchema = z.discriminatedUnion("status", [
247
+ const parseResultDiscriminatedSchema = z.discriminatedUnion("status", [
213
248
  z
214
249
  .object({
215
250
  status: z.literal("processing"),
@@ -235,6 +270,7 @@ export const parseResultSchema = z.discriminatedUnion("status", [
235
270
  billing: billingSchema.optional(),
236
271
  data_handling: dataHandlingSchema,
237
272
  local_result_cache: localResultCacheSchema.optional(),
273
+ delivery_warning: deliveryWarningSchema.optional(),
238
274
  })
239
275
  .strict(),
240
276
  z
@@ -246,8 +282,11 @@ export const parseResultSchema = z.discriminatedUnion("status", [
246
282
  artifactResultSchema,
247
283
  bundleDescriptorSchema,
248
284
  ]).optional(),
285
+ billing: billingSchema.optional(),
249
286
  cleanup_deadline: z.string().datetime({ offset: true }),
250
287
  data_handling: dataHandlingSchema,
288
+ local_result_cache: localResultCacheSchema.optional(),
289
+ delivery_warning: deliveryWarningSchema.optional(),
251
290
  })
252
291
  .strict(),
253
292
  failedResultSchema,
@@ -269,6 +308,41 @@ export const parseResultSchema = z.discriminatedUnion("status", [
269
308
  })
270
309
  .strict(),
271
310
  ]);
311
+ export const parseResultSchema = parseResultDiscriminatedSchema
312
+ .superRefine((value, context) => {
313
+ if (value.status !== "completed" && value.status !== "cleanup_pending")
314
+ return;
315
+ const result = value.result;
316
+ const cache = value.local_result_cache;
317
+ if (cache !== undefined) {
318
+ const cacheMatches = result !== undefined && (result.kind === "bundle"
319
+ ? legacyBundleLocalResultCacheSchema.safeParse(cache).success
320
+ : flatLocalResultCacheSchema.safeParse(cache).success);
321
+ if (!cacheMatches) {
322
+ context.addIssue({
323
+ code: z.ZodIssueCode.custom,
324
+ path: ["local_result_cache"],
325
+ message: "the local result cache does not match the result shape",
326
+ });
327
+ }
328
+ }
329
+ if (value.delivery_warning !== undefined) {
330
+ if (cache !== undefined) {
331
+ context.addIssue({
332
+ code: z.ZodIssueCode.custom,
333
+ path: ["local_result_cache"],
334
+ message: "a retention warning cannot advertise a local result cache",
335
+ });
336
+ }
337
+ if (result === undefined || result.kind !== "inline") {
338
+ context.addIssue({
339
+ code: z.ZodIssueCode.custom,
340
+ path: ["delivery_warning"],
341
+ message: "a retention warning requires delivered inline content",
342
+ });
343
+ }
344
+ }
345
+ });
272
346
  const resultChunkSchema = z
273
347
  .object({
274
348
  result_id: resultIdSchema,
@@ -419,6 +493,7 @@ export const parseToolOutputSchema = z
419
493
  billing: billingSchema.optional(),
420
494
  data_handling: dataHandlingSchema.optional(),
421
495
  local_result_cache: localResultCacheSchema.optional(),
496
+ delivery_warning: deliveryWarningSchema.optional(),
422
497
  cleanup_deadline: z.string().datetime({ offset: true }).optional(),
423
498
  error: stableErrorSchema.optional(),
424
499
  requires_user_confirmation: z.literal(true).optional(),
@@ -449,6 +524,47 @@ export const saveResultToolOutputSchema = z
449
524
  error: stableErrorSchema.optional(),
450
525
  })
451
526
  .strict();
527
+ export async function presentRetainedResult(result, resultDelivery, mintReadCursor) {
528
+ if (resultDelivery === "auto" ||
529
+ (result.status !== "completed" && result.status !== "cleanup_pending") ||
530
+ result.result === undefined) {
531
+ return result;
532
+ }
533
+ const current = result.result;
534
+ if (current.kind === "bundle" || current.kind === "artifact")
535
+ return result;
536
+ if (current.kind !== "inline")
537
+ return result;
538
+ const parsedCache = flatLocalResultCacheSchema.safeParse(result.local_result_cache);
539
+ if (!parsedCache.success) {
540
+ if (result.delivery_warning === LOCAL_ARTIFACT_RETENTION_WARNING)
541
+ return result;
542
+ throw new OmniBridgeError({
543
+ code: "LOCAL_RESULT_INTEGRITY_FAILED",
544
+ failureScope: "bridge",
545
+ message: "The retained inline result descriptor is unavailable.",
546
+ operationCreated: false,
547
+ fileUploaded: false,
548
+ parserStarted: false,
549
+ billed: false,
550
+ contentReleased: false,
551
+ retryable: false,
552
+ });
553
+ }
554
+ const cache = parsedCache.data;
555
+ const nextCursor = await mintReadCursor(cache.result_id, 0);
556
+ return {
557
+ ...result,
558
+ result: {
559
+ kind: "artifact",
560
+ result_id: cache.result_id,
561
+ result_bytes: cache.result_bytes,
562
+ expires_at: cache.expires_at,
563
+ preview: "",
564
+ next_cursor: nextCursor,
565
+ },
566
+ };
567
+ }
452
568
  function storageText(result) {
453
569
  const parts = result.parts;
454
570
  if (parts === null || typeof parts !== "object" || Array.isArray(parts)) {
@@ -1,13 +1,14 @@
1
1
  import type { RequestTaskStore } from "@modelcontextprotocol/sdk/shared/protocol.js";
2
+ import type { NormalizedParseArguments } from "./protocol.js";
2
3
  import { type ParseResult } from "./result-contract.js";
3
4
  export interface TaskRuntimeOperations {
4
- parse(source: string, signal: AbortSignal): Promise<ParseResult>;
5
+ parse(args: NormalizedParseArguments, signal: AbortSignal): Promise<ParseResult>;
5
6
  status(operationId: string, waitMs: number, signal: AbortSignal): Promise<ParseResult>;
6
7
  cancel(operationId: string, signal: AbortSignal): Promise<ParseResult>;
7
8
  }
8
9
  export declare class TaskRuntime {
9
10
  #private;
10
11
  constructor(operations: TaskRuntimeOperations);
11
- start(taskId: string, source: string, store: RequestTaskStore): Promise<void>;
12
+ start(taskId: string, args: NormalizedParseArguments, store: RequestTaskStore): Promise<void>;
12
13
  cancel(taskId: string): Promise<void>;
13
14
  }
@@ -39,7 +39,7 @@ export class TaskRuntime {
39
39
  constructor(operations) {
40
40
  this.#operations = operations;
41
41
  }
42
- async start(taskId, source, store) {
42
+ async start(taskId, args, store) {
43
43
  if (this.#running.has(taskId)) {
44
44
  throw new Error(`Task ${taskId} is already running.`);
45
45
  }
@@ -48,7 +48,7 @@ export class TaskRuntime {
48
48
  };
49
49
  this.#running.set(taskId, running);
50
50
  try {
51
- let result = await this.#operations.parse(source, running.controller.signal);
51
+ let result = await this.#operations.parse(args, running.controller.signal);
52
52
  while (result.status === "processing") {
53
53
  running.operationId = result.operation_id;
54
54
  if (await isCancelled(store, taskId)) {
package/dist/tools.d.ts CHANGED
@@ -6,6 +6,7 @@ import { type CubeGrantClient } from "./cube-client.js";
6
6
  import type { IiisClient, ResultRetentionSink } from "./iiis-client.js";
7
7
  import { type OpenAllowedFileOptions, type OpenedAllowedFile } from "./path-security.js";
8
8
  import type { OutlineResult } from "./outline.js";
9
+ import { type NormalizedParseArguments } from "./protocol.js";
9
10
  import type { RemoteOmniClient } from "./remote-client.js";
10
11
  import { type ParseResult } from "./result-contract.js";
11
12
  interface ToolRetention extends ResultRetentionSink {
@@ -13,7 +14,9 @@ interface ToolRetention extends ResultRetentionSink {
13
14
  }
14
15
  interface ToolArtifactStore {
15
16
  createRetention(): ToolRetention;
17
+ preflightWrite?(): Promise<void>;
16
18
  read(resultId: string, cursor?: string, maxBytes?: number): Promise<ArtifactReadResult>;
19
+ mintReadCursor?(resultId: string, byteOffset: number): Promise<string>;
17
20
  readBundlePart?(resultId: string, cursor: string, maxBytes?: number): Promise<BundlePartReadChunk>;
18
21
  readOutline?(resultId: string): Promise<OutlineResult>;
19
22
  mintOutlineCursor?(resultId: string, byteOffset: number): Promise<string>;
@@ -29,6 +32,7 @@ export interface ParseOperationController {
29
32
  sourceFacts: Readonly<Record<string, unknown>>;
30
33
  clientRequestId: string;
31
34
  signal: AbortSignal;
35
+ resultDelivery: NormalizedParseArguments["resultDelivery"];
32
36
  context: unknown;
33
37
  }): Promise<ParseResult>;
34
38
  statusResult(operationId: string, waitMs: number | undefined, signal: AbortSignal): Promise<ParseResult>;