@theoremjs/agents 0.3.5-next.894.gdec8f15 → 0.3.5-next.896.g0fa6df9

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.
package/README.md CHANGED
@@ -457,7 +457,7 @@ Named exports from the root barrel (same symbols hosts get from `@theoremjs/agen
457
457
  | Canary / egress | `mintCanary`, `bindCanary`, `wrapUserData`, `scanTextForCanaryLeak`, `scanTextForPromptEcho`, `PROMPT_ECHO_WORDS`, `redactCanary`, `OMIT_CANARY`, `createCanaryStreamGate`, `eventHasCanary`, `createCanaryGateSession`, `filterCanaryGatedEvents`, `CanaryGateResult`, `CanaryGateSession`, `CanaryStreamGate`, `GivenUrls`, `createOutboundProgressiveGate`, `createProgressiveYieldGate`, `createLiveOutboundGateSession`, `processLiveOutboundBatch`, `finalizeLiveOutboundTurn`, `abortLiveOutboundTurn`, `LiveHeldOutput`, `LiveOutboundBatchResult`, `LiveOutboundGateSession`, `ProgressiveYieldGate`, `ProgressiveYieldGateOptions`, `ProgressiveYieldResult` |
458
458
  | Compaction | `compactHistory`, `CompactionSplit`, `CompactionTokens`, `compactionMeter`, `compactionNeeded`, `resolveCompactionTokens`, `resolveHistoryTokens`, `shouldCompact`, `splitForCompaction` |
459
459
  | Token estimate | `loadTokenEstimator`, `TOKEN_TEXT_ENCODING`, `TokenCount`, `TokenEstimator`, `sumTokens` |
460
- | Runner | `runTurn`, `runSession`, `runDecision`, `runEmbedding`, `validateDecisionRequest`, `RunSessionOptions`, `SignInGatePolicy`, `RunDecisionOptions`, `DecisionError`, `prepareLiveInboundText`, `liveIngressEnabled`, `liveIngressEnabledFromSpec`, `liveIngressChannelDefault`, `hasAnyLiveIngress`, `assertLiveIngress`, `assertLiveIngressConfigured`, `LiveIngressChannel` |
460
+ | Runner | `runTurn`, `runSession`, `runDecision`, `runEmbedding`, `validateDecisionRequest`, `RunSessionOptions`, `SignInGatePolicy`, `LiveLines`, `LiveLine`, `LiveLineRole`, `RunDecisionOptions`, `DecisionError`, `prepareLiveInboundText`, `liveIngressEnabled`, `liveIngressEnabledFromSpec`, `liveIngressChannelDefault`, `hasAnyLiveIngress`, `assertLiveIngress`, `assertLiveIngressConfigured`, `LiveIngressChannel` |
461
461
  | Attachments | `attachmentIssues`, `attachmentIssueCopy`, `attachmentIssueText`, `attachmentsRefused`, `assertTurnAttachments`, `base64Bytes`, `maxBytesForMime`, `requireMediaLimits`, `resolveMediaLimits`, `sanitizeCsvText`, `sanitizeTurnBlobs`, `embeddingMediaIssues`, `embeddingRules`, `AttachmentFacts`, `AttachmentRules`, `EmbeddingRules` |
462
462
  | Catalog | `clampThinkingLevel`, `clampThinkingLevelForApiId`, `mediaChannelForMime`, `MediaInputChannel`, `mediaKindForMime`, `mimeAllowed`, `mimeEssence`, `modelEntryByApiId`, `requireModelBinding` |
463
463
  | Schema | `PROFILE_FIELDS`, `PROFILE_GRAPH`, `PROFILE_TYPES`, `PROFILE_ID_MAX_CHARS`, `PROFILE_HANDLE_MAX_CHARS`, `EXTRA_FIELDS`, `REQUEST_FIELDS`, `API_EXPORTS`, `fieldMeta`, `catalogPathFor`, `DYNAMIC_FIELD_PARENTS`, `spineFacetsForProfileType`, `profileGraphFacet`, `ProfileGraphFacet`, `ProfileGraphFacetId`, `ProfileGraphEditor`, `ProfileGraphRole`, `THINKING_LEVELS`, `KEY_SLOT_NAME`, `isKeySlotName`, `MEDIA_INPUT_KINDS`, `MEDIA_INPUT_KIND_VALUES`, `MEDIA_WILDCARDS`, `ATTACHMENT_ACCEPT_MIMES`, `IMAGE_ATTACHMENT_ACCEPT_MIMES`, `VOICE_ACCEPT_MIMES`, `SUMMARY_MODES`, `STREAM_MODES`, `SPEECH_AUDIO_FORMATS`, `COMPACTION_METERS`, `COMPACTION_OUTCOMES`, `COMPACTION_TIMINGS`, `CACHE_MODES`, `CACHE_TTLS`, `TURN_STAGES`, `TURN_INJECT_STAGES`, `TURN_STOP_KINDS`, `CONTINUE_STOP_KINDS`, `TOOL_GATE_KINDS`, `AWAITING_USER_INPUT_KINDS`, `AWAITING_USER_INPUT_STATUS`, `TOOL_LOAD_TIERS`, `TOOL_ACCESS`, `TOOL_PERMISSION`, `TOOL_TYPES`, `AUTH_UNAUTHENTICATED_POLICIES`, `HTTP_METHODS`, `STUDIO_AUTH_TYPES`, `TOOL_AUTH_TYPES`, `AuthUnauthenticatedPolicy`, `CustomToolType`, `HttpMethod`, `StudioAuthType`, `ToolAccess`, `ToolAuthType`, `ToolPermission`, `ToolType`, `LIVE_ACTIVITY_HANDLINGS`, `LIVE_START_SENSITIVITIES`, `LIVE_END_SENSITIVITIES` |
package/esm/mod.d.ts CHANGED
@@ -31,7 +31,7 @@ export { validateDecisionRequest } from './src/kernel/engine/decision.js';
31
31
  export { prepareLiveInboundText } from './src/kernel/engine/live-inbound.js';
32
32
  export type { LiveIngressChannel } from './src/kernel/engine/live-ingress.js';
33
33
  export { assertLiveIngress, assertLiveIngressConfigured, hasAnyLiveIngress, liveIngressChannelDefault, liveIngressEnabled, liveIngressEnabledFromSpec, } from './src/kernel/engine/live-ingress.js';
34
- export type { RunSessionOptions, SignInGatePolicy } from './src/kernel/engine/session/mod.js';
34
+ export type { LiveLine, LiveLineRole, LiveLines, RunSessionOptions, SignInGatePolicy, } from './src/kernel/engine/session/mod.js';
35
35
  export type { TokenCount, TokenEstimator, } from './src/kernel/engine/token-estimate.js';
36
36
  export { loadTokenEstimator, TOKEN_TEXT_ENCODING, } from './src/kernel/engine/token-estimate.js';
37
37
  export { sumTokens } from './src/kernel/engine/usage.js';
@@ -21,9 +21,42 @@ export interface RunSessionOptions extends ProviderHostOptions {
21
21
  * the call's next result; unanswered by then, the model reads that the sign-in expired.
22
22
  */
23
23
  signInGate?: SignInGatePolicy;
24
+ /**
25
+ * Give each line of the call an id the model can cite, and hand each finished line to the
26
+ * host. Unset, lines get no ids and the host reads them from `events()`.
27
+ */
28
+ lines?: LiveLines;
24
29
  }
25
30
  /** How a sign-in gate behaves in a live session: `hold` waits for the decision, `answer` tells the model the sign-in is pending and releases the call. */
26
31
  export type SignInGatePolicy = 'hold' | 'answer';
32
+ /** Who said a line of the call. */
33
+ export type LiveLineRole = 'user' | 'assistant';
34
+ /** One finished line of the call: all the user said before the model acted on it, or all the model said in one turn. */
35
+ export type LiveLine = {
36
+ id: string;
37
+ role: LiveLineRole;
38
+ text: string;
39
+ };
40
+ /**
41
+ * The host's ids and store for the lines of a live call. The model reads a user line's note
42
+ * before the line (at the opening, then as each user line closes), so it can cite the line it
43
+ * is hearing; it reads the model's own line's note after that line is kept.
44
+ */
45
+ export interface LiveLines {
46
+ /** A new id for a line still to come. A failure fails the open, or the line that needed it. */
47
+ reserve(): Promise<string>;
48
+ /** What the model reads to learn a line's id, in the host's words. */
49
+ note(line: {
50
+ id: string;
51
+ role: LiveLineRole;
52
+ }): string;
53
+ /**
54
+ * Take a finished line. The session waits for it before the model's next tool call reaches
55
+ * the host, so resolve once the line is the host's (queued durably), not once it is stored
56
+ * far away. A failure ends the session with that error.
57
+ */
58
+ keep(line: LiveLine): Promise<void>;
59
+ }
27
60
  /**
28
61
  * The session record is written however the session ends, including when opening fails. An unknown
29
62
  * profile fails to open and is recorded under the standard observability policy.
@@ -279,22 +279,19 @@ function boundaryDoneEvents(doneBatch, turnPhase, interrupted, withheld) {
279
279
  }
280
280
  return [{ type: 'done', stop: { kind: 'completed' } }];
281
281
  }
282
- function recordLiveHistory(events, recordUserText, recordAssistantText) {
283
- for (const event of events) {
284
- if (event.type === 'text')
285
- recordAssistantText(event.text);
286
- if (event.type === 'evidence' &&
287
- event.text &&
288
- (event.evidence.kind === 'input_transcription' ||
289
- event.evidence.kind === 'output_transcription') &&
290
- !event.evidence.interim) {
291
- if (event.evidence.kind === 'input_transcription')
292
- recordUserText(event.text);
293
- if (event.evidence.kind === 'output_transcription' &&
294
- !events.some((item) => item.type === 'text'))
295
- recordAssistantText(event.text);
296
- }
297
- }
282
+ /** The model acted on what it heard: it spoke, wrote, or called a tool. */
283
+ function isModelAction(event) {
284
+ if (event.type === 'text' || event.type === 'media')
285
+ return true;
286
+ if (event.type === 'tool')
287
+ return event.tool.phase === undefined;
288
+ return event.type === 'evidence' && event.evidence.kind === 'output_transcription';
289
+ }
290
+ /** A final transcription chunk of `kind`, or `undefined`. */
291
+ function finalTranscript(event, kind) {
292
+ if (event.type !== 'evidence' || event.evidence.kind !== kind || event.evidence.interim)
293
+ return;
294
+ return event.text || undefined;
298
295
  }
299
296
  async function sealLiveCheckpoints(events, history, calls, keepsHistory) {
300
297
  const sealed = [];
@@ -347,7 +344,7 @@ function* yieldLiveNonDoneEvents(gated, includeMatch) {
347
344
  return doneBatch;
348
345
  }
349
346
  function buildLiveSession(args) {
350
- const { profile, canary, connection, gate, givenUrls, destinations, signal, onStage, host: sessionHost, resolveHost, fetch, path, snapshot, trace, gateTtlMs, signInGate, } = args;
347
+ const { profile, canary, connection, gate, givenUrls, destinations, signal, onStage, host: sessionHost, resolveHost, fetch, path, snapshot, trace, gateTtlMs, signInGate, lines, } = args;
351
348
  /** Grows as the user approves `session_consent` tools. */
352
349
  let sessionPermissions = args.sessionPermissions;
353
350
  /** Where keys typed at sign-in gates go when a call brings no source of its own. */
@@ -381,13 +378,28 @@ function buildLiveSession(args) {
381
378
  : [];
382
379
  /** Serialize stage + ingress so concurrent send* cannot interleave cycles. */
383
380
  let ingressChain = Promise.resolve();
381
+ const noteGiven = (text) => {
382
+ addSeenUrls(givenUrls.request, text);
383
+ addGivenDestinations(destinations, text);
384
+ };
385
+ /** Text the session wrote in the user's place (an inject): its own history entry, no line. */
384
386
  const recordUserText = (text) => {
385
387
  const trimmed = text.trim();
386
388
  if (!trimmed)
387
389
  return;
388
390
  history.push({ role: 'user', content: trimmed });
389
- addSeenUrls(givenUrls.request, trimmed);
390
- addGivenDestinations(destinations, trimmed);
391
+ noteGiven(trimmed);
392
+ };
393
+ /** The user's line being heard: the id its note gave the model, and the words so far. */
394
+ let userLine = {
395
+ id: args.firstLineId === undefined ? undefined : Promise.resolve(args.firstLineId),
396
+ text: '',
397
+ };
398
+ /** What the model has said this turn: one line, kept when the turn ends. */
399
+ let assistantLine = '';
400
+ const hearUser = (text, typed) => {
401
+ userLine.text = typed && userLine.text ? `${userLine.text} ${text}` : `${userLine.text}${text}`;
402
+ noteGiven(text);
391
403
  };
392
404
  const recordAssistantText = (text) => {
393
405
  if (!text)
@@ -588,13 +600,111 @@ function buildLiveSession(args) {
588
600
  connection.sendContext(text);
589
601
  }
590
602
  };
591
- const ingestPreparedLiveText = (text) => {
603
+ /** `record` takes the text as it crossed, unwrapped: the user's typed line, or an inject's own entry. */
604
+ const ingestPreparedLiveText = (text, record) => {
592
605
  const safe = readLiveText(text);
593
606
  if (safe === undefined)
594
607
  return;
595
- recordUserText(safe.slice(USER_OPEN.length + 1, -(USER_CLOSE.length + 1)));
608
+ record(safe.slice(USER_OPEN.length + 1, -(USER_CLOSE.length + 1)));
596
609
  sendInput({ type: 'text', text: safe });
597
610
  };
611
+ /** Reserve the next user line's id and tell the model, ahead of any input sent after it. */
612
+ const reserveUserLine = (host) => {
613
+ let id = '';
614
+ const noted = withIngress(async () => {
615
+ id = await host.reserve();
616
+ if (!closed)
617
+ connection.sendContext(host.note({ id, role: 'user' }));
618
+ }).then(() => id);
619
+ // why: A failure is reported where the id is needed, when its line closes; a line never
620
+ // spoken needs no id.
621
+ noted.catch(() => undefined);
622
+ return noted;
623
+ };
624
+ /** Close the user's line: one history entry, kept under the id the model was given. */
625
+ const closeUserLine = async (ending) => {
626
+ const { id: lineId, text: said } = userLine;
627
+ const text = said.trim();
628
+ if (!text)
629
+ return;
630
+ userLine = { id: lines && !ending ? reserveUserLine(lines) : undefined, text: '' };
631
+ if (!lines || !lineId) {
632
+ history.push({ role: 'user', content: text });
633
+ return;
634
+ }
635
+ const id = await lineId;
636
+ history.push({ role: 'system', content: lines.note({ id, role: 'user' }) }, { role: 'user', content: text });
637
+ await lines.keep({ id, role: 'user', text });
638
+ };
639
+ /** Close the model's line at the end of its turn: kept, then its note goes to the model. */
640
+ const closeAssistantLine = async (ending) => {
641
+ const text = assistantLine.trim();
642
+ assistantLine = '';
643
+ if (!text || !lines)
644
+ return;
645
+ const id = await lines.reserve();
646
+ await lines.keep({ id, role: 'assistant', text });
647
+ const note = lines.note({ id, role: 'assistant' });
648
+ history.push({ role: 'system', content: note });
649
+ if (ending)
650
+ return;
651
+ await withIngress(() => {
652
+ if (!closed)
653
+ connection.sendContext(note);
654
+ return Promise.resolve();
655
+ });
656
+ };
657
+ /**
658
+ * Record a batch in order. The user's line closes when the model acts on it, so a tool call
659
+ * reaches the host only once the line before it is kept.
660
+ */
661
+ const recordLines = async (events) => {
662
+ const writes = events.some((event) => event.type === 'text');
663
+ for (const event of events) {
664
+ if (isModelAction(event))
665
+ await closeUserLine(false);
666
+ const heard = finalTranscript(event, 'input_transcription');
667
+ if (heard)
668
+ hearUser(heard, false);
669
+ const said = event.type === 'text'
670
+ ? event.text
671
+ : writes
672
+ ? undefined
673
+ : finalTranscript(event, 'output_transcription');
674
+ if (said) {
675
+ recordAssistantText(said);
676
+ assistantLine += said;
677
+ }
678
+ }
679
+ };
680
+ /** The turn ended: what the user said that drew no reply, then what the model said. */
681
+ const closeTurnLines = async () => {
682
+ await closeUserLine(false);
683
+ await closeAssistantLine(false);
684
+ };
685
+ let linesEnded;
686
+ let linesEndReported = false;
687
+ /** Keep the lines still open as the session ends, once; no note follows, the model is gone. */
688
+ const startEndLines = () => {
689
+ if (!linesEnded) {
690
+ linesEnded = closeUserLine(true).then(() => closeAssistantLine(true));
691
+ // why: `endLines` reports the failure; a session no one closes has no one to tell.
692
+ linesEnded.catch(() => undefined);
693
+ }
694
+ return linesEnded;
695
+ };
696
+ const endLines = async () => {
697
+ try {
698
+ await startEndLines();
699
+ }
700
+ catch (err) {
701
+ // why: The stream and `close()` both end the session; the failure reaches the first only.
702
+ if (linesEndReported)
703
+ return;
704
+ linesEndReported = true;
705
+ throw err;
706
+ }
707
+ };
598
708
  /**
599
709
  * Write each inject whole into the open cycle (no re-entry into pre_turn),
600
710
  * then record the named ones that landed. An inject live cannot write as
@@ -619,7 +729,7 @@ function buildLiveSession(args) {
619
729
  }
620
730
  for (const text of texts) {
621
731
  assertLiveIngress(profile, 'text');
622
- ingestPreparedLiveText(text);
732
+ ingestPreparedLiveText(text, recordUserText);
623
733
  }
624
734
  landed.push(unit);
625
735
  }
@@ -912,7 +1022,7 @@ function buildLiveSession(args) {
912
1022
  if (ev.type === 'guardrail')
913
1023
  trace.outbound(ev);
914
1024
  }
915
- recordLiveHistory(gated, recordUserText, recordAssistantText);
1025
+ await recordLines(gated);
916
1026
  const sealed = await sealLiveCheckpoints(closesCutOff ? checkpointOfClose(gated) : gated, history, calls, profile.providerContinuation?.history !== 'stateless');
917
1027
  const doneBatch = yield* yieldLiveNonDoneEvents(sealed, includeMatch);
918
1028
  const tokens = await trace.settle();
@@ -932,6 +1042,7 @@ function buildLiveSession(args) {
932
1042
  // why: Boundary batches (`interactionStatus: IDLE`, or bare `turnComplete` when the
933
1043
  // provider sends no status) often have no folded `done` — still end the cycle.
934
1044
  if (completeBoundary && cycle === 'open') {
1045
+ await closeTurnLines();
935
1046
  const boundaryDone = boundaryDoneEvents(ending, item.turnPhase, interrupted, withholdClose);
936
1047
  for await (const ev of endCycleAroundDone(boundaryDone)) {
937
1048
  yield projectGuardrailTurnEvent(stampDone(ev), includeMatch);
@@ -994,6 +1105,7 @@ function buildLiveSession(args) {
994
1105
  }
995
1106
  }
996
1107
  yield* drainPendingHostEvents(pendingHostEvents);
1108
+ await endLines();
997
1109
  }
998
1110
  catch (err) {
999
1111
  thrown = err;
@@ -1008,6 +1120,9 @@ function buildLiveSession(args) {
1008
1120
  closeSocket(1000, 'session-closed', closer);
1009
1121
  // why: The socket is closed, so a batch still awaited resolves and the provider can finish.
1010
1122
  await provider.return(undefined);
1123
+ // why: A stream that failed or that the host left still keeps its open lines; `close()`
1124
+ // reports a line it could not keep.
1125
+ startEndLines();
1011
1126
  await trace.close({ thrown });
1012
1127
  }
1013
1128
  };
@@ -1047,7 +1162,7 @@ function buildLiveSession(args) {
1047
1162
  const opened = await openCycleIfNeeded();
1048
1163
  if (opened.aborted)
1049
1164
  return;
1050
- ingestPreparedLiveText(text);
1165
+ ingestPreparedLiveText(text, (typed) => hearUser(typed, true));
1051
1166
  });
1052
1167
  },
1053
1168
  sendContext(context) {
@@ -1143,9 +1258,14 @@ function buildLiveSession(args) {
1143
1258
  stopLapses();
1144
1259
  closeSocket(1000, reason, 'host');
1145
1260
  }
1146
- // why: The session record is sealed here; frames the host reads after closing are not in it.
1147
- await connection.flush?.();
1148
- return trace.close({});
1261
+ try {
1262
+ await endLines();
1263
+ }
1264
+ finally {
1265
+ // why: The session record is sealed here; frames the host reads after closing are not in it.
1266
+ await connection.flush?.();
1267
+ await trace.close({});
1268
+ }
1149
1269
  },
1150
1270
  };
1151
1271
  const { openingContext, opening } = args;
@@ -1189,6 +1309,13 @@ async function openTracedSession(registry, req, options, trace) {
1189
1309
  const { profile, generation: gen0 } = resolveTurnInRegistry(registry, safe);
1190
1310
  assertLiveProfile(profile);
1191
1311
  const openingContext = req.context ? readSessionContext(profile, req.context) : undefined;
1312
+ const { lines } = options;
1313
+ const firstLineId = lines ? await lines.reserve() : undefined;
1314
+ // why: The first user line's note rides in the opening seed, so the model has it before any input.
1315
+ const seeded = [
1316
+ ...(openingContext?.texts ?? []),
1317
+ ...(lines && firstLineId !== undefined ? [lines.note({ id: firstLineId, role: 'user' })] : []),
1318
+ ];
1192
1319
  if (req.snapshot) {
1193
1320
  gen0.tools = sessionSnapshotWithinAllow(profile, req.snapshot);
1194
1321
  }
@@ -1203,7 +1330,7 @@ async function openTracedSession(registry, req, options, trace) {
1203
1330
  ]);
1204
1331
  const completeReq = {
1205
1332
  ...providerCompleteRequest(registry.tools, generation, system.text),
1206
- ...(openingContext?.texts.length ? { context: openingContext.texts } : {}),
1333
+ ...(seeded.length ? { context: seeded } : {}),
1207
1334
  signal: safe.signal,
1208
1335
  tapUpstream: trace.sent,
1209
1336
  };
@@ -1255,5 +1382,6 @@ async function openTracedSession(registry, req, options, trace) {
1255
1382
  agents: sessionAgentCaller(registry, req, options, trace.agentCanaries),
1256
1383
  gateTtlMs,
1257
1384
  signInGate: options.signInGate ?? 'hold',
1385
+ ...(lines ? { lines, firstLineId } : {}),
1258
1386
  });
1259
1387
  }
@@ -16,7 +16,7 @@ export { DecisionError, validateDecisionRequest } from './engine/decision.js';
16
16
  export type { RunEmbeddingOptions } from './engine/embedding.js';
17
17
  export type { LiveIngressChannel } from './engine/live-ingress.js';
18
18
  export { assertLiveIngress, assertLiveIngressConfigured, hasAnyLiveIngress, liveIngressChannelDefault, liveIngressEnabled, liveIngressEnabledFromSpec, } from './engine/live-ingress.js';
19
- export type { RunSessionOptions, SignInGatePolicy } from './engine/session/mod.js';
19
+ export type { LiveLine, LiveLineRole, LiveLines, RunSessionOptions, SignInGatePolicy, } from './engine/session/mod.js';
20
20
  export type { TokenCount, TokenEstimator } from './engine/token-estimate.js';
21
21
  export { loadTokenEstimator, TOKEN_TEXT_ENCODING, } from './engine/token-estimate.js';
22
22
  export { sumTokens } from './engine/usage.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.894.gdec8f15",
3
+ "version": "0.3.5-next.896.g0fa6df9",
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",