@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/kernel/stop.d.ts

@@ -0,0 +1,116 @@
+import { type ContinueStopKind, type ProfileType, type StepLimitMode } from './schema.js';
+import type { TurnStop } from './turn-events.js';
+export type { TurnStop };
+/**
+ * Profile types whose continue turn sends the continue instruction. Image and
+ * speech continue by re-sending the host's request unchanged.
+ */
+export declare const CONTINUE_INSTRUCTION_TYPES: readonly ProfileType[];
+/** The stop kinds that offer Continue when a profile names none. */
+export declare const DEFAULT_ALLOW_CONTINUE: readonly ContinueStopKind[];
+/** Hosts wait briefly, then continue once on their own. */
+export declare const DEFAULT_AUTO_CONTINUE: readonly ContinueStopKind[];
+/** Pause before an auto-continue, the host's or the turn's own, so a flaky tunnel can settle. */
+export declare const AUTO_CONTINUE_DELAY_MS = 1500;
+/** Which stops a profile offers Continue for, and which the host continues on its own. */
+export interface ProfileTurnResumptionSpec {
+    /**
+     * The host's UI policy for offering Continue: the kernel does not refuse a `continueFrom`
+     * outside it, since a continue is one more turn the host could send as plain text anyway.
+     * Omit → length / stream_incomplete / provider_error; `[]` = none.
+     */
+    allowContinue?: ContinueStopKind[];
+    /**
+     * Omit → length / stream_incomplete; `[]` = none. Apart from `allowContinue`: a stop can be
+     * continued without Continue being offered for it. The host sends the `continueFrom` turn
+     * with `continuation`. A text turn also sends a failed model call (`provider_error`,
+     * `stream_incomplete`) again itself when this list is set and names that stop, and the
+     * call gave no reply and no tool call: the turn keeps its history, its step count and
+     * what it has read. A failure the same call would meet again (the provider refused the
+     * request) is not sent again. Omitted, a turn sends nothing again.
+     */
+    autoContinue?: ContinueStopKind[];
+    /**
+     * Compared against `TurnRequest.continuation`; omit → no count cap. Also how many model
+     * calls one text turn sends again itself; omit → one.
+     */
+    maxContinues?: number;
+}
+/** True when the stop kind can be continued. */
+export declare function isContinueStopKind(kind: string): kind is ContinueStopKind;
+/**
+ * `allowSteering` is text / live only; image and speech omit it. Stop is not a profile knob:
+ * interfaces always project `canStop: true` because `TurnRequest.signal` is always wired.
+ */
+export interface ProfileTurnBehaviourSpec {
+    resumption?: ProfileTurnResumptionSpec;
+    /** Default true on text / live. Gates injects only; stage events still emit. */
+    allowSteering?: boolean;
+    /**
+     * Text only. What the last model call under `maxSteps` may do. Omit = `'stop'`: it may call
+     * tools, and if it does the turn stops as `step_limit`. `'answer'` sends it without tools.
+     */
+    atStepLimit?: StepLimitMode;
+}
+/**
+ * Image / speech turn behaviour: resumption only. A continue re-sends the
+ * host's request unchanged, so there is no continue instruction, and there is
+ * no mid-turn inject to steer.
+ */
+export interface MediaTurnBehaviourSpec {
+    resumption?: ProfileTurnResumptionSpec;
+}
+/**
+ * The stop a continue turn resumes. The partial reply is not carried here: a
+ * text continue reads it as the last assistant message in `input.history`, and
+ * an image or speech continue re-sends the original request.
+ */
+export interface TurnContinueFrom {
+    stop: TurnStop;
+}
+/** True when the stop can be continued under the allowed kinds. */
+export declare function isResumeableStop(stop: TurnStop | undefined, allowContinue?: readonly ContinueStopKind[]): boolean;
+/** True for a stop where the model call failed; the rest either finished or were stopped on purpose. */
+export declare function isFailedStopKind(kind: TurnStop['kind']): boolean;
+export declare function stageAbortStop(abort: true | {
+    reason?: string;
+}): TurnStop & {
+    kind: 'cancelled';
+};
+/** True when the user cancelled the turn. */
+export declare function isUserCancelledStop(stop: TurnStop | undefined): boolean;
+/** `policy` is the profile's `profileTurnResumption(profile)`. */
+export declare function shouldAutoContinue(stop: TurnStop | undefined, policy?: Pick<ProfileTurnResumptionSpec, 'autoContinue'>): boolean;
+/** The profile's resumption policy, or `undefined` for a live profile. */
+export declare function profileTurnResumption(profile: {
+    type: string;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
+}): ProfileTurnResumptionSpec | undefined;
+/** Text-only, for the interface `allowSteering` projection; `profileAllowsInject` adds live. */
+export declare function profileAllowsSteering(profile: {
+    type: string;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
+}): boolean;
+/** Gates injects only, never stage emission. */
+export declare function profileAllowsInject(profile: {
+    type: string;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
+}): boolean;
+/** OpenAI-compatible normalized `finish_reason` (+ optional `native_finish_reason`). */
+export declare function turnStopFromOpenAiFinishReason(finishReason: string | null | undefined, nativeFinishReason?: string | null): TurnStop;
+/** Gemini Interactions terminal `status`. */
+export declare function turnStopFromInteractionStatus(status: string | null | undefined): TurnStop;
+/** `null` when `sawTerminal`, so the host keeps the provider's stop. */
+export declare function turnStopFromClientStreamEnd(opts: {
+    abortedByUser: boolean;
+    sawTerminal: boolean;
+    hadPartial?: boolean;
+}): TurnStop | null;
+/** Thrown when a model call stops before it finishes, carrying the stop. */
+export declare class GenerationStopError extends Error {
+    readonly name = "GenerationStopError";
+    readonly stop: TurnStop;
+    constructor(stop: TurnStop, message?: string);
+}
+/** True when the error is a `GenerationStopError`. */
+export declare function isGenerationStopError(err: unknown): err is GenerationStopError;

package/esm/src/kernel/stop.js

@@ -0,0 +1,137 @@
+import { CONTINUE_STOP_KINDS, } from './schema.js';
+/**
+ * Profile types whose continue turn sends the continue instruction. Image and
+ * speech continue by re-sending the host's request unchanged.
+ */
+export const CONTINUE_INSTRUCTION_TYPES = ['text'];
+/** The stop kinds that offer Continue when a profile names none. */
+export const DEFAULT_ALLOW_CONTINUE = CONTINUE_STOP_KINDS;
+/** Hosts wait briefly, then continue once on their own. */
+export const DEFAULT_AUTO_CONTINUE = ['length', 'stream_incomplete'];
+/** Pause before an auto-continue, the host's or the turn's own, so a flaky tunnel can settle. */
+export const AUTO_CONTINUE_DELAY_MS = 1_500;
+const CONTINUE_KIND_SET = new Set(CONTINUE_STOP_KINDS);
+/** True when the stop kind can be continued. */
+export function isContinueStopKind(kind) {
+    return CONTINUE_KIND_SET.has(kind);
+}
+const RESUMEABLE_DEFAULT = new Set(DEFAULT_ALLOW_CONTINUE);
+/** True when the stop can be continued under the allowed kinds. */
+export function isResumeableStop(stop, allowContinue) {
+    if (!stop)
+        return false;
+    if (!isContinueStopKind(stop.kind))
+        return false;
+    const allow = allowContinue ? new Set(allowContinue) : RESUMEABLE_DEFAULT;
+    return allow.has(stop.kind);
+}
+const FAILED_STOP_KINDS = new Set(['provider_error', 'stream_incomplete']);
+/** True for a stop where the model call failed; the rest either finished or were stopped on purpose. */
+export function isFailedStopKind(kind) {
+    return FAILED_STOP_KINDS.has(kind);
+}
+export function stageAbortStop(abort) {
+    return typeof abort === 'object' && abort.reason
+        ? { kind: 'cancelled', native: abort.reason }
+        : { kind: 'cancelled' };
+}
+/** True when the user cancelled the turn. */
+export function isUserCancelledStop(stop) {
+    return stop?.kind === 'cancelled';
+}
+/** `policy` is the profile's `profileTurnResumption(profile)`. */
+export function shouldAutoContinue(stop, policy) {
+    if (!stop || !isContinueStopKind(stop.kind))
+        return false;
+    // why: Offering Continue (`allowContinue`) is the host's own choice, apart from this one.
+    return (policy?.autoContinue ?? DEFAULT_AUTO_CONTINUE).includes(stop.kind);
+}
+/** The profile's resumption policy, or `undefined` for a live profile. */
+export function profileTurnResumption(profile) {
+    if (profile.type === 'live')
+        return undefined;
+    return profile.turnBehaviour?.resumption;
+}
+/** Text-only, for the interface `allowSteering` projection; `profileAllowsInject` adds live. */
+export function profileAllowsSteering(profile) {
+    if (profile.type !== 'text')
+        return false;
+    return profile.turnBehaviour?.allowSteering !== false;
+}
+/** Gates injects only, never stage emission. */
+export function profileAllowsInject(profile) {
+    if (profile.type === 'text' || profile.type === 'live') {
+        return profile.turnBehaviour?.allowSteering !== false;
+    }
+    return false;
+}
+/** OpenAI-compatible normalized `finish_reason` (+ optional `native_finish_reason`). */
+export function turnStopFromOpenAiFinishReason(finishReason, nativeFinishReason) {
+    const native = nativeFinishReason?.trim() || finishReason?.trim() || undefined;
+    const effective = (nativeFinishReason || finishReason || '').toLowerCase();
+    if (!effective)
+        return { kind: 'stream_incomplete', native };
+    if (effective === 'network_error' || effective.includes('network')) {
+        return { kind: 'provider_error', native };
+    }
+    return openAiFinishKind((finishReason || '').toLowerCase(), effective, native);
+}
+function openAiFinishKind(finish, effective, native) {
+    if (finish === 'stop') {
+        return /error|fail/.test(effective)
+            ? { kind: 'provider_error', native }
+            : { kind: 'completed', native };
+    }
+    if (finish === 'length')
+        return { kind: 'length', native };
+    if (finish === 'tool_calls' || finish === 'tool-calls')
+        return { kind: 'tool', native };
+    if (finish === 'content_filter' || finish === 'content-filter') {
+        return { kind: 'filtered', native };
+    }
+    return { kind: 'provider_error', native };
+}
+/** Gemini Interactions terminal `status`. */
+export function turnStopFromInteractionStatus(status) {
+    const s = (status || '').toLowerCase();
+    const native = status || undefined;
+    switch (s) {
+        case 'completed':
+            return { kind: 'completed', native };
+        case 'incomplete':
+        case 'budget_exceeded':
+            return { kind: 'length', native };
+        case 'requires_action':
+            return { kind: 'tool', native };
+        case 'cancelled':
+            return { kind: 'cancelled', native };
+        case 'failed':
+            return { kind: 'provider_error', native };
+        case 'in_progress':
+        case 'queued':
+            return { kind: 'stream_incomplete', native };
+        default:
+            return { kind: 'stream_incomplete', native };
+    }
+}
+/** `null` when `sawTerminal`, so the host keeps the provider's stop. */
+export function turnStopFromClientStreamEnd(opts) {
+    if (opts.sawTerminal)
+        return null;
+    if (opts.abortedByUser)
+        return { kind: 'cancelled' };
+    return { kind: 'stream_incomplete' };
+}
+/** Thrown when a model call stops before it finishes, carrying the stop. */
+export class GenerationStopError extends Error {
+    name = 'GenerationStopError';
+    stop;
+    constructor(stop, message) {
+        super(message || `Generation stopped: ${stop.kind}`);
+        this.stop = stop;
+    }
+}
+/** True when the error is a `GenerationStopError`. */
+export function isGenerationStopError(err) {
+    return err instanceof GenerationStopError;
+}

package/esm/src/kernel/system-parts.d.ts

@@ -0,0 +1,26 @@
+import type { SystemPiece, SystemPrompt } from './types.js';
+/** The system prompt as sent, and the private stretches of it no reply may repeat. */
+interface BoundSystem {
+    text: string;
+    private: readonly string[];
+}
+/** What is wrong with `prompt` as a system prompt, `where` naming it, or undefined. */
+declare function systemPromptProblem(prompt: unknown, where: string): string | undefined;
+/** `where` names the prompt in the error, e.g. `Profile sol identity.system`. */
+declare function assertSystemPrompt(prompt: unknown, where: string): asserts prompt is SystemPrompt;
+/** Rewrites each part's text with `rewrite`, keeping its mark. */
+declare function mapSystemPrompt(prompt: SystemPrompt, where: string, rewrite: (text: string) => string): SystemPrompt;
+/** One prompt's pieces: all private unless some part is `{ private }`. */
+declare function systemPieces(prompt: SystemPrompt): SystemPiece[];
+/** Joins prompts from different sources a blank line apart, leaving out empty ones. */
+declare function joinSystemPieces(sources: readonly (readonly SystemPiece[])[]): SystemPiece[];
+declare function systemText(pieces: readonly SystemPiece[]): string;
+/**
+ * The wire text and its private stretches: private pieces next to each other
+ * read as one stretch, since a reply repeating across them repeats private text.
+ */
+declare function boundSystem(pieces: readonly SystemPiece[]): BoundSystem;
+/** `pieces` with Theorem's notes after them, each note private whatever the host marked. */
+declare function bindSystem(pieces: readonly SystemPiece[], notes: readonly string[]): BoundSystem;
+export type { BoundSystem };
+export { assertSystemPrompt, bindSystem, boundSystem, joinSystemPieces, mapSystemPrompt, systemPieces, systemPromptProblem, systemText, };

package/esm/src/kernel/system-parts.js

@@ -0,0 +1,98 @@
+import { TheoremError } from '../guardrails/error.js';
+const SOURCE_SEPARATOR = '\n\n';
+function partProblem(part) {
+    if (typeof part === 'string')
+        return undefined;
+    if (typeof part !== 'object' || part === null || Array.isArray(part)) {
+        return 'must be a string or { private: string }'; // labels-exempt: developer contract error
+    }
+    const keys = Object.keys(part);
+    if (keys.length !== 1 || keys[0] !== 'private') {
+        return 'must have exactly one key, private'; // labels-exempt: developer contract error
+    }
+    const text = part.private;
+    if (typeof text !== 'string')
+        return 'must be a string'; // labels-exempt: developer contract error
+    if (text === '')
+        return 'must not be empty'; // labels-exempt: developer contract error
+    return undefined;
+}
+/** What is wrong with `prompt` as a system prompt, `where` naming it, or undefined. */
+function systemPromptProblem(prompt, where) {
+    if (typeof prompt === 'string')
+        return undefined;
+    if (!Array.isArray(prompt))
+        return `${where} must be a string or an array of parts`; // labels-exempt: developer contract error
+    if (prompt.length === 0)
+        return `${where} must not be an empty array`; // labels-exempt: developer contract error
+    for (const [at, part] of prompt.entries()) {
+        const problem = partProblem(part);
+        if (!problem)
+            continue;
+        const path = typeof part === 'object' && part !== null && 'private' in part ? '.private' : '';
+        return `${where}[${at}]${path} ${problem}`;
+    }
+    return undefined;
+}
+/** `where` names the prompt in the error, e.g. `Profile sol identity.system`. */
+function assertSystemPrompt(prompt, where) {
+    const problem = systemPromptProblem(prompt, where);
+    if (problem)
+        throw new TheoremError('config', problem);
+}
+/** Rewrites each part's text with `rewrite`, keeping its mark. */
+function mapSystemPrompt(prompt, where, rewrite) {
+    assertSystemPrompt(prompt, where);
+    if (typeof prompt === 'string')
+        return rewrite(prompt);
+    return prompt.map((part) => typeof part === 'string' ? rewrite(part) : { private: rewrite(part.private) });
+}
+/** One prompt's pieces: all private unless some part is `{ private }`. */
+function systemPieces(prompt) {
+    if (typeof prompt === 'string')
+        return [{ text: prompt, private: true }];
+    const marked = prompt.some((part) => typeof part !== 'string');
+    return prompt.map((part) => typeof part === 'string'
+        ? { text: part, private: !marked }
+        : { text: part.private, private: true });
+}
+/** Joins prompts from different sources a blank line apart, leaving out empty ones. */
+function joinSystemPieces(sources) {
+    const joined = [];
+    for (const pieces of sources) {
+        if (!pieces.some((piece) => piece.text))
+            continue;
+        if (joined.length > 0)
+            joined.push({ text: SOURCE_SEPARATOR, private: true });
+        joined.push(...pieces);
+    }
+    return joined;
+}
+function systemText(pieces) {
+    return pieces.map((piece) => piece.text).join('');
+}
+/**
+ * The wire text and its private stretches: private pieces next to each other
+ * read as one stretch, since a reply repeating across them repeats private text.
+ */
+function boundSystem(pieces) {
+    const stretches = [];
+    let open = '';
+    for (const piece of pieces) {
+        if (piece.private) {
+            open += piece.text;
+            continue;
+        }
+        if (open.trim())
+            stretches.push(open);
+        open = '';
+    }
+    if (open.trim())
+        stretches.push(open);
+    return { text: systemText(pieces), private: stretches };
+}
+/** `pieces` with Theorem's notes after them, each note private whatever the host marked. */
+function bindSystem(pieces, notes) {
+    return boundSystem(joinSystemPieces([pieces, ...notes.map((text) => (text ? [{ text, private: true }] : []))]));
+}
+export { assertSystemPrompt, bindSystem, boundSystem, joinSystemPieces, mapSystemPrompt, systemPieces, systemPromptProblem, systemText, };

package/esm/src/kernel/tools/activity-label.d.ts

@@ -0,0 +1,22 @@
+/** One line of wording, or a list of lines read top to bottom: the first that fits is shown. */
+export type LabelTemplate = string | readonly string[];
+/** A tool's name as a label shows it: `manage_alert` reads "manage alert". */
+export declare function toolNameInWords(name: string): string;
+/**
+ * Fills each `{path}` or `{path|fallback}` from the call. Only text and numbers fill; a line fits
+ * when every placeholder has a value or a fallback and its `when` holds. A list shows its first
+ * line that fits, and a run of `+` lines shows every member that fits, joined in words. When no
+ * line fits the label is `undefined`, and the transcript names the tool.
+ */
+export declare function fillActivityLabel(template: LabelTemplate | undefined, values: {
+    input: unknown;
+    output?: unknown;
+}): string | undefined;
+/**
+ * Why a label can't be used with these JSON schemas, as a sentence for its author, or `undefined`
+ * when it can. Pass `output` for a Done label. A list must end on a line that always fits.
+ */
+export declare function activityLabelProblem(template: LabelTemplate, schemas: {
+    input: unknown;
+    output?: unknown;
+}): string | undefined;