@theoremjs/agents 0.3.5-next.948.g1059790 → 0.3.5-next.949.gac4d2f6

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.
@@ -11,6 +11,12 @@ declare function isTurnMediaRef(item: TurnBlob | TurnMediaRef): item is TurnMedi
11
11
  declare function requireMediaLimits(profile: Profile): MediaLimits;
12
12
  /** CSV formula injection: formula-like cells get an apostrophe before they reach a model. */
13
13
  declare function sanitizeCsvText(text: string): string;
14
+ /** Whether a file of this type is text the detectors read once decoded. */
15
+ declare function isTextFile(mimeType: string): boolean;
16
+ /** A text file's base64 bytes as the model reads them: decoded, and a CSV's formula cells escaped. */
17
+ declare function textFileText(mimeType: string, data: string): string;
18
+ /** Text as a text file's base64 bytes. */
19
+ declare function textFileData(text: string): string;
14
20
  /** `sizeBytes` is absent for provider references, which carry no bytes. */
15
21
  export interface AttachmentFacts {
16
22
  name?: string;
@@ -43,4 +49,4 @@ declare function sanitizeTurnBlobs(profile: Profile, attachments: Array<TurnBlob
43
49
  attachments?: Array<TurnBlob | TurnMediaRef>;
44
50
  voice?: TurnBlob[];
45
51
  };
46
- export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, base64Bytes, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, };
52
+ export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, base64Bytes, isTextFile, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, textFileData, textFileText, };
@@ -77,12 +77,18 @@ function sanitizeCsvText(text) {
77
77
  return `${a}${b}${c}'${d ?? ''}${e ?? ''}`;
78
78
  });
79
79
  }
80
- function sanitizeTextBytes(mime, bytes, reader) {
81
- let text = decodeText(bytes);
82
- if (mime === 'text/csv') {
83
- text = sanitizeCsvText(text);
84
- }
85
- return new TextEncoder().encode(reader.read(text));
80
+ /** Whether a file of this type is text the detectors read once decoded. */
81
+ function isTextFile(mimeType) {
82
+ return TEXT_MIMES.has(mimeEssence(mimeType));
83
+ }
84
+ /** A text file's base64 bytes as the model reads them: decoded, and a CSV's formula cells escaped. */
85
+ function textFileText(mimeType, data) {
86
+ const text = decodeText(base64ToBytes(data));
87
+ return mimeEssence(mimeType) === 'text/csv' ? sanitizeCsvText(text) : text;
88
+ }
89
+ /** Text as a text file's base64 bytes. */
90
+ function textFileData(text) {
91
+ return bytesToBase64(new TextEncoder().encode(text));
86
92
  }
87
93
  function named(issue, name) {
88
94
  return name ? { ...issue, fileName: name } : issue;
@@ -198,11 +204,10 @@ function sanitizeAttachment(blob, reader) {
198
204
  return blob;
199
205
  }
200
206
  const { mimeType, data } = blob;
201
- if (!TEXT_MIMES.has(mimeEssence(mimeType))) {
207
+ if (!isTextFile(mimeType)) {
202
208
  return blob;
203
209
  }
204
- const bytes = sanitizeTextBytes(mimeType, base64ToBytes(data), reader);
205
- return { ...blob, data: bytesToBase64(bytes) };
210
+ return { ...blob, data: textFileData(reader.read(textFileText(mimeType, data))) };
206
211
  }
207
212
  function hasTurnBlobs(attachments, voice) {
208
213
  return (attachments?.length ?? 0) > 0 || (voice?.length ?? 0) > 0;
@@ -217,4 +222,4 @@ function sanitizeTurnBlobs(profile, attachments, voice, at) {
217
222
  voice: voice?.length ? voice.map((blob) => sanitizeAttachment(blob, at.voice)) : voice,
218
223
  };
219
224
  }
220
- export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, base64Bytes, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, };
225
+ export { assertTurnAttachments, attachmentIssueCopy, attachmentIssues, attachmentIssueText, attachmentsRefused, base64Bytes, isTextFile, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, textFileData, textFileText, };
@@ -9,6 +9,7 @@ import { checkTaintGate, guardToolFailureText, guardToolResult, guardToolValue,
9
9
  import { recordToolCheck, startToolTrace, } from '../engine/tool-trace.js';
10
10
  import { sumTurnTokens } from '../engine/usage.js';
11
11
  import { jsonObjectSchema } from '../json.js';
12
+ import { isTextFile, textFileData, textFileText } from '../registry/attachments.js';
12
13
  import { isAwaitingUserInput, toolOutputPartRecord, } from '../turn-events.js';
13
14
  import { isRecord } from '../util/record.js';
14
15
  import { fillActivityLabel } from './activity-label.js';
@@ -285,7 +286,7 @@ async function* settleToolCall(args) {
285
286
  }, formatToolResult(modelResult))
286
287
  : completeEvent(base, {
287
288
  input,
288
- outputRaw: yield* guard.shown(outputRaw),
289
+ outputRaw: shownFiles(yield* guard.shown(withFileTexts(outputRaw)), outputRaw),
289
290
  modelResult,
290
291
  parts: yield* guard.shownParts(modelResult.media ?? []),
291
292
  labels: args.labels,
@@ -1293,9 +1294,9 @@ function* guardResult(result, guard) {
1293
1294
  */
1294
1295
  function* readTextParts(result, guard, boundary) {
1295
1296
  const media = result.media;
1296
- if (!media?.some((part) => part.type === 'text'))
1297
+ const texts = media?.map(partText) ?? [];
1298
+ if (!media || texts.every((text) => text === null))
1297
1299
  return result;
1298
- const texts = media.map((part) => (part.type === 'text' ? part.text : null));
1299
1300
  const read = guardToolValue(texts, guard.provenance, guard.policy, boundary, {
1300
1301
  callable: guard.callableTools,
1301
1302
  });
@@ -1310,23 +1311,37 @@ function* readTextParts(result, guard, boundary) {
1310
1311
  const { media: _media, parts: _parts, ...rest } = result;
1311
1312
  return withMedia(rest, media.map((part, index) => {
1312
1313
  const text = kept.data[index];
1313
- return part.type === 'text' && typeof text === 'string' ? { ...part, text } : part;
1314
+ if (typeof text !== 'string')
1315
+ return part;
1316
+ return part.type === 'text' ? { ...part, text } : { ...part, data: textFileData(text) };
1314
1317
  }));
1315
1318
  }
1319
+ /** The text the detectors read in a part: a text part's words, or a text file's decoded bytes. */
1320
+ function partText(part) {
1321
+ if (part.type === 'text')
1322
+ return part.text;
1323
+ return 'data' in part && isTextFile(part.mimeType)
1324
+ ? textFileText(part.mimeType, part.data)
1325
+ : null;
1326
+ }
1316
1327
  const keptTexts = z.array(z.string().nullable());
1317
- /** The parts the person is shown, each read without its bytes at `tool_shown_<kind>`; a blocked one is left out. */
1328
+ /** The parts the person is shown, each read at `tool_shown_<kind>` with a text file's bytes decoded; a blocked one is left out. */
1318
1329
  function* showParts(parts, guard) {
1319
1330
  const boundary = guard.kind && toolBoundary('tool_shown', guard.kind);
1320
1331
  const shown = [];
1321
1332
  for (const part of parts) {
1322
- // why: bytes are not text the detectors read; every other field of the part is read as it is shown.
1323
- const { data, ...read } = 'data' in part ? part : { ...part, data: undefined };
1333
+ // why: a text file's bytes are read decoded; other bytes are not text the detectors read. Every other field of the part is read as it is shown.
1334
+ const { data, ...fields } = 'data' in part ? part : { ...part, data: undefined };
1335
+ const text = data === undefined ? null : partText(part);
1336
+ const read = text === null ? fields : { ...fields, data: text };
1324
1337
  const checked = guardToolValue(read, guard.provenance, guard.policy, boundary);
1325
1338
  if (checked.event)
1326
1339
  yield { type: 'guardrail', guardrail: checked.event };
1327
1340
  if (!('value' in checked))
1328
1341
  continue;
1329
- const kept = toolOutputPartRecord.safeParse(data === undefined || !isRecord(checked.value) ? checked.value : { ...checked.value, data });
1342
+ const kept = toolOutputPartRecord.safeParse(data === undefined || !isRecord(checked.value)
1343
+ ? checked.value
1344
+ : { ...checked.value, data: shownData(checked.value.data, text, data) });
1330
1345
  if (!kept.success) {
1331
1346
  throw new TheoremError('internal', 'A guard changed the shape of a part it read'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
1332
1347
  }
@@ -1334,6 +1349,44 @@ function* showParts(parts, guard) {
1334
1349
  }
1335
1350
  return shown;
1336
1351
  }
1352
+ /** The output with each text file in its `parts` decoded, so the person's view of it is read as its parts are. */
1353
+ function withFileTexts(output) {
1354
+ if (!isRecord(output) || !Array.isArray(output.parts))
1355
+ return output;
1356
+ return {
1357
+ ...output,
1358
+ parts: output.parts.map((part) => {
1359
+ const text = isFilePart(part) ? partText(part) : null;
1360
+ return text === null ? part : { ...part, data: text };
1361
+ }),
1362
+ };
1363
+ }
1364
+ /** The read output with each text file's text encoded again, at the parts `output` held as files. */
1365
+ function shownFiles(read, output) {
1366
+ if (!isRecord(read) || !Array.isArray(read.parts) || !isRecord(output))
1367
+ return read;
1368
+ const given = Array.isArray(output.parts) ? output.parts : [];
1369
+ return {
1370
+ ...read,
1371
+ parts: read.parts.map((part, index) => {
1372
+ const file = given[index];
1373
+ if (!isFilePart(file) || partText(file) === null || !isRecord(part))
1374
+ return part;
1375
+ return typeof part.data === 'string' ? { ...part, data: textFileData(part.data) } : part;
1376
+ }),
1377
+ };
1378
+ }
1379
+ /** Whether `value` is a part that carries bytes. */
1380
+ function isFilePart(value) {
1381
+ return (isRecord(value) &&
1382
+ value.type !== 'text' &&
1383
+ typeof value.data === 'string' &&
1384
+ typeof value.mimeType === 'string');
1385
+ }
1386
+ /** A shown part's bytes after its read: a text file's read text encoded again, any other part's bytes as they were. */
1387
+ function shownData(read, text, data) {
1388
+ return text === null ? data : typeof read === 'string' ? textFileData(read) : read;
1389
+ }
1337
1390
  /** What the person is shown of `value`, read at `tool_shown_<kind>`; a blocked one is the labels' words. */
1338
1391
  function* showValue(value, guard) {
1339
1392
  const boundary = guard.kind && toolBoundary('tool_shown', guard.kind);
@@ -1,18 +1,35 @@
1
1
  import { z } from 'zod';
2
2
  import { TheoremError } from '../../guardrails/error.js';
3
+ import { isTextFile } from '../registry/attachments.js';
3
4
  import { MEDIA_INPUT_KIND_VALUES } from '../schema.js';
4
5
  import { toolOutputPartRecord } from '../turn-events.js';
6
+ import { base64ToBytes } from '../util/base64.js';
5
7
  import { isRecord } from '../util/record.js';
6
8
  const mimeType = z.string().regex(/\S/);
7
9
  const metadata = z.record(z.string(), z.unknown()).optional();
8
10
  const textPart = z.strictObject({ type: z.literal('text'), text: z.string() });
9
- const mediaPart = z.strictObject({
11
+ const mediaPart = z
12
+ .strictObject({
10
13
  type: z.enum(MEDIA_INPUT_KIND_VALUES),
11
14
  mimeType,
12
15
  data: z.string().min(1),
13
16
  sent: z.literal(true).optional(),
14
17
  metadata,
18
+ })
19
+ .refine((part) => !isTextFile(part.mimeType) || isBase64(part.data), {
20
+ path: ['data'],
21
+ message: 'A text file must be base64, so it can be decoded and read', // labels-exempt: developer contract error
15
22
  });
23
+ /** Whether `data` decodes as base64. */
24
+ function isBase64(data) {
25
+ try {
26
+ base64ToBytes(data);
27
+ return true;
28
+ }
29
+ catch {
30
+ return false;
31
+ }
32
+ }
16
33
  /** A reference part: the person is shown it through the app's own resolver. */
17
34
  export const toolOutputRefPartSchema = z.strictObject({
18
35
  type: z.enum(MEDIA_INPUT_KIND_VALUES),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.948.g1059790",
3
+ "version": "0.3.5-next.949.gac4d2f6",
4
4
  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
5
5
  "keywords": [
6
6
  "agent",