@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/guardrails/types.d.ts

@@ -0,0 +1,250 @@
+import type { DetectSpec, ResolvedAllow, ResolvedDetect } from './detectors.js';
+import type { GivenUrls } from './egress-urls.js';
+import type { GuardrailEvent, GuardrailHit, Provenance } from './event-schemas.js';
+import type { LabelOverrides } from './labels.js';
+import type { OwnTools } from './tool-leak.js';
+export type { GuardrailEvent, GuardrailHit, Provenance };
+/**
+ * - `trusted` — author-time profile text (`identity.system`). Left verbatim: no
+ *   injection or sensitive redaction, which would mangle the host's own instructions.
+ * - `assembled` — host-built per turn (`req.system`). Interpolates retrieval and
+ *   user data, so it is permeable and takes full detection.
+ * - `untrusted` — user input, tool results, attachments, delegated agents.
+ */
+export declare const TRUST_LEVELS: readonly ["trusted", "assembled", "untrusted"];
+/** One of {@linkcode TRUST_LEVELS}. */
+export type TrustLevel = (typeof TRUST_LEVELS)[number];
+/** The points a guardrail can run: input, history, system, attachments, tool calls, and results, output, thoughts, network, live audio, and traces. */
+export declare const GUARDRAIL_STAGES: readonly ["input", "history", "system", "attachment", "tool_call", "tool_result", "output_delta", "output_final", "thought", "network", "live_inbound", "live_outbound", "trace"];
+/** One of {@linkcode GUARDRAIL_STAGES}. */
+export type GuardrailStage = (typeof GUARDRAIL_STAGES)[number];
+/** Does not decide what happens next; that is `blockedReply`. */
+export declare const SEVERITIES: readonly ["info", "low", "medium", "high"];
+/** One of {@linkcode SEVERITIES}. */
+export type Severity = (typeof SEVERITIES)[number];
+/** What follows a blocked reply: the model rewrites it, or the user reads a refusal. */
+export declare const BLOCKED_REPLY_ON_BLOCK: readonly ["retry", "refuse"];
+/** One of {@linkcode BLOCKED_REPLY_ON_BLOCK}. */
+export type BlockedReplyOnBlock = (typeof BLOCKED_REPLY_ON_BLOCK)[number];
+/** What happens once a detector blocks a reply. */
+export interface BlockedReplySpec {
+    /**
+     * `retry` (the default) tells the model what blocked the reply and has it write another;
+     * `refuse` sends the user the labels' `egress.refusal` in its place, or ends the part
+     * they already have with `egress.refusal_cut`.
+     */
+    onBlock?: BlockedReplyOnBlock;
+    /**
+     * Under `retry`, how many times the model may rewrite a blocked reply (default 1). Once they
+     * are spent the reply is withheld and the turn ends in a `safety` error.
+     */
+    maxRetries?: number;
+}
+/** {@linkcode BlockedReplySpec} with its defaults applied. */
+export type ResolvedBlockedReply = Required<BlockedReplySpec>;
+/**
+ * A discriminated union so a new variant fails every unhandled `switch` at
+ * compile time rather than falling through at runtime.
+ */
+export type Verdict = {
+    action: 'allow';
+} | {
+    action: 'redact';
+    text: string;
+    hits: GuardrailHit[];
+} | {
+    action: 'flag';
+    hits: GuardrailHit[];
+} | {
+    action: 'block';
+    hits: GuardrailHit[];
+    /**
+     * Sent to the model on a repair turn when `blockedReply.onBlock` is `retry`.
+     * With `refuse` the user reads the labels' `egress.refusal`.
+     */
+    rejection: string;
+    /**
+     * Why the check blocked, for the builder only: it reaches the host and the
+     * trace (content-gated), never the model or a client (`forClient`).
+     */
+    errorInternal?: string;
+};
+export declare const GUARDRAIL_ACTIONS: readonly ["allow", "redact", "flag", "block"];
+/** One of {@linkcode GUARDRAIL_ACTIONS}. */
+export type GuardrailAction = (typeof GUARDRAIL_ACTIONS)[number];
+/**
+ * `local` is host TypeScript the profile registered; `http` and `mcp` are remote
+ * services whose bytes the host does not control. `delegated` is another agent
+ * answering through the tool boundary — its output is model-generated prose that
+ * reads as authoritative, which is why depth is tracked separately.
+ */
+export declare const TOOL_ORIGINS: readonly ["local", "builtin", "http", "mcp", "delegated"];
+/** One of {@linkcode TOOL_ORIGINS}. */
+export type ToolOrigin = (typeof TOOL_ORIGINS)[number];
+/**
+ * Once a turn has read attacker-influenceable bytes, a later tool call is a
+ * confused-deputy risk: the content can ask the agent to act, and the agent has
+ * authority the content does not. Sources are kept in order so a policy can reason
+ * about depth as well as presence.
+ */
+export interface TurnTaint {
+    sources: Provenance[];
+    /**
+     * Separates "read something remote" from "read something that tried to steer
+     * me". The second is far rarer, so a gate keyed on it refuses far less
+     * legitimate work.
+     */
+    suspicious: GuardrailHit[];
+}
+/**
+ * Not a probability: there is no calibrated model behind it. `elevated` means one
+ * directive signal alongside an external destination; `high` means the content
+ * named a tool the model can call, or several signals agreed.
+ */
+export declare const ADVISORY_LEVELS: readonly ["none", "elevated", "high"];
+/** One of {@linkcode ADVISORY_LEVELS}. */
+export type AdvisoryLevel = (typeof ADVISORY_LEVELS)[number];
+/** Which tool access levels refuse to run once a turn has read untrusted content. */
+export declare const TAINT_GATES: readonly ["off", "destructive", "write"];
+/** One of {@linkcode TAINT_GATES}. */
+export type TaintGate = (typeof TAINT_GATES)[number];
+/** What happens to a tool call that sends to a destination only remote content named. */
+export declare const DESTINATION_GATES: readonly ["off", "confirm", "block"];
+/** One of {@linkcode DESTINATION_GATES}. */
+export type DestinationGate = (typeof DESTINATION_GATES)[number];
+/**
+ * Enforcement is opt-in: every remote read is reported, but refusing tool calls
+ * changes what working agents may do, so the host declares which access levels
+ * to gate rather than having the kernel guess.
+ *
+ * Only structural facts gate tool calls. Content signals from `tool-directives.ts` deliberately have no gate here. They
+ * are pattern matches with no measured precision, and refusing a tool call on an
+ * unpredictable signal makes an agent unreliable rather than safe — the failure is
+ * invisible to the user and looks like the agent being stupid. Those signals
+ * annotate the fence and raise telemetry; the model still gets to decide, and the
+ * host still gets to see.
+ */
+export interface TaintGuardrailSpec {
+    /**
+     * Stated as a capability threshold rather than a list of tool `access` values so
+     * the guardrail vocabulary stays independent of the tool registry; the kernel
+     * maps a tool's declared access onto it.
+     */
+    afterRemoteRead?: TaintGate;
+    remoteDestination?: DestinationGate;
+}
+/** Facts a check may read. Deliberately excludes the full profile. */
+export interface GuardrailContext {
+    stage: GuardrailStage;
+    trust: TrustLevel;
+    profileId: string;
+    canary?: string;
+    /**
+     * The canary was in what the model was given besides the system prompt (its
+     * input, the user's and tools' history): a reply repeating it is not a
+     * leak. It still binds prompt echo.
+     */
+    canaryGiven?: boolean;
+    /**
+     * The private stretches of the system prompt as sent (`BoundSystem.private`),
+     * while the `prompt_leak` detector reads somewhere: text repeating one is a
+     * leak.
+     */
+    privateSystem?: readonly string[];
+    role?: string;
+    slots?: Record<string, string>;
+    /** Set on tool-shaped stages; absent for user and system text. */
+    provenance?: Provenance;
+    /**
+     * Canonical absolute URLs in what the model was given this turn or session:
+     * the system prompt, the user's input and history, and apart, tool results.
+     * An image or link in the reply to any other URL can carry data to its
+     * server. The kernel adds to them as the model is given more. Unset: none.
+     */
+    givenUrls?: GivenUrls;
+    /** The names of the profile's tools and of their parameters, for `tool_leak`. Unset: none. */
+    ownTools?: OwnTools;
+    /** The profile's labels, so a rejection reads in the host's wording. */
+    labels?: LabelOverrides;
+}
+/**
+ * Structured output travels alongside text so a profile with `outputs.structured`
+ * has it read by the detectors too.
+ */
+export interface OutboundPayload {
+    /** Concatenated user-visible text for this attempt. */
+    text: string;
+    structured?: unknown;
+}
+/** Which hosts and networks a tool's requests may reach. */
+export interface NetworkGuardrailSpec {
+    /** Allows localhost, loopback, and private subnets (local dev and testing). Default false. */
+    allowPrivateNetworks?: boolean;
+    /** Hostnames or IP addresses permitted regardless of private subnet status. */
+    allowedHosts?: string[];
+    /**
+     * Allowed URL schemes. Defaults to `['https']`, or `['http', 'https']` when
+     * `allowPrivateNetworks` is set.
+     */
+    allowedSchemes?: string[];
+}
+/** Optional daily turn quota consumed by host HTTP middleware. */
+export interface QuotaGuardrailSpec {
+    perDay: number;
+}
+/** The guardrails a profile turns on, each with its own settings. */
+export interface ProfileGuardrailsSpec {
+    /** Omitted means quota enforcement is not configured. */
+    quota?: QuotaGuardrailSpec;
+    /**
+     * What the kernel does when a detector finds a match, per boundary: one action
+     * for everything, or a rule for the detectors it names. Anything left out keeps
+     * its default (`DETECT_DEFAULTS`). A canary is bound into the system prompt
+     * while `canary_leak` is above `ignore` somewhere; the note that binds it is
+     * the labels' `canary.bind_note` (the profile's `labels` may replace it).
+     */
+    detect?: DetectSpec;
+    /** What happens once a reply is blocked. Left out, the model rewrites it once. */
+    blockedReply?: BlockedReplySpec;
+    network?: NetworkGuardrailSpec;
+    taint?: TaintGuardrailSpec;
+}
+/** Pre-dispatch policy for structured state leaving a decision profile. */
+export type DecisionDisclosureVerdict = Extract<Verdict, {
+    action: 'allow' | 'block';
+}>;
+export type DecisionDisclosureEnforcer = (state: unknown, context: {
+    destination: string;
+    profileId: string;
+    model: string;
+    questionIds: string[];
+    /** The images the call sends with the state, by reference. Absent: none. */
+    assets?: Record<string, {
+        mimeType: 'image/png' | 'image/jpeg';
+        data: string;
+    }>;
+}) => DecisionDisclosureVerdict | Promise<DecisionDisclosureVerdict>;
+/**
+ * Keeps the shared guardrail vocabulary structurally compatible while the
+ * decision registry rejects every inherited field as inert in this release.
+ */
+export interface DecisionGuardrailsSpec extends Partial<ProfileGuardrailsSpec> {
+    disclosure?: {
+        enforce: DecisionDisclosureEnforcer;
+    };
+}
+/** The guardrail field names a `host` profile may set. */
+export declare const HOST_GUARDRAIL_FIELDS: readonly ["detect", "network"];
+/** The guardrails that fire on the `invokeTool` path; the rest guard a model turn. */
+export type HostGuardrailsSpec = Pick<ProfileGuardrailsSpec, (typeof HOST_GUARDRAIL_FIELDS)[number]>;
+/** A profile's guardrails after defaults are applied. */
+export interface ResolvedGuardrailPolicy {
+    /** Every detector's action at every boundary. */
+    detect: ResolvedDetect;
+    /** What `ungiven_images` and `ungiven_links` let through besides the given URLs. */
+    allow: ResolvedAllow;
+    blockedReply: ResolvedBlockedReply;
+    network?: NetworkGuardrailSpec;
+    quota?: QuotaGuardrailSpec;
+    taint?: TaintGuardrailSpec;
+}

package/esm/src/guardrails/types.js

@@ -0,0 +1,58 @@
+// invariant: Must not import from `src/kernel/`: the kernel type-imports `ProfileGuardrailsSpec`, and that edge
+// stays one-directional. Other modules under `src/guardrails/` may import kernel types.
+/**
+ * - `trusted` — author-time profile text (`identity.system`). Left verbatim: no
+ *   injection or sensitive redaction, which would mangle the host's own instructions.
+ * - `assembled` — host-built per turn (`req.system`). Interpolates retrieval and
+ *   user data, so it is permeable and takes full detection.
+ * - `untrusted` — user input, tool results, attachments, delegated agents.
+ */
+export const TRUST_LEVELS = ['trusted', 'assembled', 'untrusted'];
+/** The points a guardrail can run: input, history, system, attachments, tool calls, and results, output, thoughts, network, live audio, and traces. */
+export const GUARDRAIL_STAGES = [
+    'input',
+    'history',
+    'system',
+    'attachment',
+    'tool_call',
+    'tool_result',
+    'output_delta',
+    'output_final',
+    'thought',
+    'network',
+    'live_inbound',
+    'live_outbound',
+    'trace',
+];
+/** Does not decide what happens next; that is `blockedReply`. */
+export const SEVERITIES = ['info', 'low', 'medium', 'high'];
+/** What follows a blocked reply: the model rewrites it, or the user reads a refusal. */
+export const BLOCKED_REPLY_ON_BLOCK = ['retry', 'refuse'];
+export const GUARDRAIL_ACTIONS = [
+    'allow',
+    'redact',
+    'flag',
+    'block',
+];
+/**
+ * `local` is host TypeScript the profile registered; `http` and `mcp` are remote
+ * services whose bytes the host does not control. `delegated` is another agent
+ * answering through the tool boundary — its output is model-generated prose that
+ * reads as authoritative, which is why depth is tracked separately.
+ */
+export const TOOL_ORIGINS = ['local', 'builtin', 'http', 'mcp', 'delegated'];
+/**
+ * Not a probability: there is no calibrated model behind it. `elevated` means one
+ * directive signal alongside an external destination; `high` means the content
+ * named a tool the model can call, or several signals agreed.
+ */
+export const ADVISORY_LEVELS = ['none', 'elevated', 'high'];
+/** Which tool access levels refuse to run once a turn has read untrusted content. */
+export const TAINT_GATES = ['off', 'destructive', 'write'];
+/** What happens to a tool call that sends to a destination only remote content named. */
+export const DESTINATION_GATES = ['off', 'confirm', 'block'];
+/** The guardrail field names a `host` profile may set. */
+export const HOST_GUARDRAIL_FIELDS = [
+    'detect',
+    'network',
+];

package/esm/src/host/client-turn.d.ts

@@ -0,0 +1,36 @@
+import { type ErrorCopies, type ErrorKind } from '../guardrails/error.js';
+import type { LabelOverrides } from '../guardrails/labels.js';
+import type { TurnEvent } from '../kernel/types.js';
+/** Options for `forClient` and `clientError`: who reads the copy, and whether evidence keeps its provider-native payload. */
+export interface ClientTurnOptions {
+    /** Keep provider-native payloads on `evidence` events. Default: false; parsed fields remain. */
+    includeEvidenceRaw?: boolean;
+    /**
+     * Who reads the copy. A `'visitor'` (the default) reads the profile's wording, and every
+     * builder-only diagnostic is stripped. A `'builder'` is whoever builds the app, on their own
+     * machine and keys, as in a local development tool: a failed turn, an ended session, and a tool
+     * call's failure read their raw reason in place of the profile's wording, and builder-only
+     * diagnostics stay. Never for a page visitors reach.
+     */
+    reader?: 'visitor' | 'builder';
+}
+/**
+ * The copy of an event its reader may have. For a visitor (the default) host-only diagnostics are
+ * stripped, so the copy is safe to forward to browsers or end-user SSE.
+ */
+declare function forClient(event: TurnEvent, options?: ClientTurnOptions): TurnEvent;
+/** `forClient` over a list of events. */
+declare function forClientEvents(events: TurnEvent[], options?: ClientTurnOptions): TurnEvent[];
+/** A failure's wording and kind as a client reads them: the body of an error reply or line. */
+type ClientError = {
+    error: string;
+    errorKind: ErrorKind;
+    errorCopy?: ErrorCopies;
+};
+/**
+ * A caught failure as its reader may have it, by the same rule as `forClient`: the profile's
+ * wording (pass its `labels`) for a visitor, the raw diagnostic for a builder.
+ */
+declare function clientError(err: unknown, labels?: LabelOverrides, options?: ClientTurnOptions): ClientError;
+export type { ClientError };
+export { clientError, forClient, forClientEvents };

package/esm/src/host/client-turn.js

@@ -0,0 +1,80 @@
+import { toErrorEvent, withPublicLabels, } from '../guardrails/error.js';
+import { projectGuardrailTurnEvent } from '../guardrails/events.js';
+/**
+ * For the builder, the wording of a failure is its raw reason, wherever a visitor's wording
+ * stands: a failed turn, an ended session, a tool call's failure.
+ */
+function builderWording(event) {
+    if (event.type === 'error' && event.errorInternal !== undefined) {
+        // why: `errorCopy` stays: worded raw or not, its key still names what failed for the page.
+        const { errorInternal, ...rest } = event;
+        return { ...rest, error: errorInternal };
+    }
+    if (event.type === 'session' &&
+        event.session.kind === 'ended' &&
+        event.errorInternal !== undefined) {
+        const { errorInternal, ...rest } = event;
+        return { ...rest, session: { ...event.session, message: errorInternal } };
+    }
+    if (event.type === 'tool' &&
+        event.tool.phase === 'error' &&
+        event.tool.failure.error !== undefined) {
+        const { failure } = event.tool;
+        return { ...event, tool: { ...event.tool, failure: { ...failure, error: failure.message } } };
+    }
+    return event;
+}
+/** Raw diagnostics ride on error events, an ended session's close, and a tool call's failure. */
+function stripErrorInternal(event) {
+    if ((event.type !== 'error' && event.type !== 'session' && event.type !== 'tool') ||
+        event.errorInternal === undefined) {
+        return event;
+    }
+    const { errorInternal: _internal, ...rest } = event;
+    return rest;
+}
+function stripGuardrailInternal(event) {
+    if (event.type !== 'guardrail' || !event.guardrail?.errorInternal) {
+        return event;
+    }
+    const { errorInternal: _internal, ...guardrail } = event.guardrail;
+    return { ...event, guardrail };
+}
+function stripEvidenceRaw(event) {
+    if (event.type !== 'evidence' || !event.evidence?.raw) {
+        return event;
+    }
+    const { raw: _raw, ...evidence } = event.evidence;
+    return { ...event, evidence };
+}
+/**
+ * The copy of an event its reader may have. For a visitor (the default) host-only diagnostics are
+ * stripped, so the copy is safe to forward to browsers or end-user SSE.
+ */
+function forClient(event, options) {
+    let out = options?.reader === 'builder'
+        ? builderWording(event)
+        : stripGuardrailInternal(stripErrorInternal(event));
+    if (!options?.includeEvidenceRaw) {
+        out = stripEvidenceRaw(out);
+    }
+    // invariant: Clients never receive matched substrings, even if the host opted into guardrailMatchPreview.
+    out = projectGuardrailTurnEvent(out, false);
+    return out;
+}
+/** `forClient` over a list of events. */
+function forClientEvents(events, options) {
+    return events.map((event) => forClient(event, options));
+}
+/**
+ * A caught failure as its reader may have it, by the same rule as `forClient`: the profile's
+ * wording (pass its `labels`) for a visitor, the raw diagnostic for a builder.
+ */
+function clientError(err, labels, options) {
+    const event = forClient(withPublicLabels(toErrorEvent(err), labels), options);
+    // why: An error event stays one through `withPublicLabels` and `forClient`, worded by the first.
+    const { error = '', errorKind, errorCopy } = event;
+    // why: The key tells the page what failed (a conversation the host lost), which `errorKind` cannot.
+    return { error, errorKind, ...(errorCopy ? { errorCopy } : {}) };
+}
+export { clientError, forClient, forClientEvents };

package/esm/src/host/mint-trace.d.ts

@@ -0,0 +1,29 @@
+import type { Profile } from '../kernel/types.js';
+import { type TraceRecord } from '../observability/trace-record.js';
+import type { TraceSink } from '../observability/trace-sink.js';
+/** The record of a cutout call kept on the trace: whether it succeeded, how long it took, its URL, the hashes of its input, and output, the upstream exchange and any error. */
+interface CutoutTape {
+    ok: boolean;
+    /** How long the cutout took; the span ends now and starts this long before. */
+    ms: number;
+    url?: string;
+    inSha256?: string;
+    outSha256?: string;
+    /** The upstream exchange, recorded as a `theorem.upstream.row` event. */
+    http?: unknown;
+    error?: string;
+}
+/**
+ * Writes the held turn record, then one `cutout` span parented on its root, so both read as one
+ * trace. Without a `sink` nothing is written.
+ */
+declare function flushMintTrace(args: {
+    /** The profile the held turn ran on; its observability governs both writes. */
+    profile: Profile;
+    held: TraceRecord[];
+    app: Record<string, unknown>;
+    cutout: CutoutTape;
+    sink?: TraceSink;
+}): Promise<void>;
+export type { CutoutTape };
+export { flushMintTrace };

package/esm/src/host/mint-trace.js

@@ -0,0 +1,60 @@
+import { TheoremError } from '../guardrails/error.js';
+import { urlAttributes } from '../kernel/engine/turn-trace.js';
+import { resolveTraceWriter } from '../observability/policy.js';
+import { writeTrace } from '../observability/trace.js';
+import { buildRecord } from '../observability/trace-record.js';
+import { formatTraceparent, startTrace, traceContent, traceJson, } from '../observability/trace-span.js';
+const NANOS_PER_MS = 1_000_000;
+const AGENT_NAME = 'gen_ai.agent.name';
+function cutoutAttributes(cutout) {
+    return {
+        ...urlAttributes(cutout.url),
+        ...(cutout.inSha256 ? { 'theorem.cutout.input.sha256': cutout.inSha256 } : {}),
+        ...(cutout.outSha256 ? { 'theorem.cutout.output.sha256': cutout.outSha256 } : {}),
+    };
+}
+/**
+ * Writes the held turn record, then one `cutout` span parented on its root, so both read as one
+ * trace. Without a `sink` nothing is written.
+ */
+async function flushMintTrace(args) {
+    const [record] = args.held;
+    const root = record?.spans[0];
+    if (!record || !root || !args.sink) {
+        return;
+    }
+    const ranOn = root.attributes[AGENT_NAME];
+    if (ranOn !== args.profile.id) {
+        throw new TheoremError('config', `flushMintTrace: the held turn ran on '${String(ranOn)}', not '${args.profile.id}'`);
+    }
+    const { sink, policy } = resolveTraceWriter({
+        override: args.sink,
+        observability: args.profile.observability,
+        guardrails: args.profile.guardrails,
+    });
+    await writeTrace(sink, Promise.resolve(record), policy);
+    const { cutout } = args;
+    // why: One instant: the cutout was reported done now and ran for `ms` before it.
+    const now = BigInt(Date.now()) * BigInt(NANOS_PER_MS);
+    const tree = startTrace('cutout', {
+        clock: { nowUnixNano: () => now },
+        kind: 'CLIENT',
+        traceparent: formatTraceparent(root.traceId, root.spanId),
+        startTimeUnixNano: String(now - BigInt(Math.round(cutout.ms * NANOS_PER_MS))),
+        attributes: cutoutAttributes(cutout),
+    });
+    if (cutout.http !== undefined) {
+        tree.root.event('theorem.upstream.row', { row: traceJson(cutout.http) });
+    }
+    // why: The host's error text is free text: stored by hash under the scrub, like any exception.
+    if (cutout.error) {
+        tree.root.event('exception', { 'exception.message': traceContent(cutout.error) });
+    }
+    tree.root.end({ code: cutout.ok ? 'OK' : 'ERROR' });
+    await writeTrace(sink, buildRecord({
+        spans: tree.collect(),
+        policy,
+        metadata: { ...record.metadata, app: args.app },
+    }), policy);
+}
+export { flushMintTrace };

package/esm/src/host/mod.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Optional host-application helpers, not part of the turn kernel: HTTP reply status, cutout-trace
+ * flush, and live structured-output preview.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { ClientError, ClientTurnOptions } from './client-turn.js';
+export { clientError, forClient, forClientEvents } from './client-turn.js';
+export type { CutoutTape } from './mint-trace.js';
+export { flushMintTrace } from './mint-trace.js';
+export { readStreamingJsonStringField } from './readStreamingJsonStringField.js';
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json, } from './reply.js';

package/esm/src/host/mod.js

@@ -0,0 +1,11 @@
+/**
+ * Optional host-application helpers, not part of the turn kernel: HTTP reply status, cutout-trace
+ * flush, and live structured-output preview.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { clientError, forClient, forClientEvents } from './client-turn.js';
+export { flushMintTrace } from './mint-trace.js';
+export { readStreamingJsonStringField } from './readStreamingJsonStringField.js';
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json, } from './reply.js';

package/esm/src/host/readStreamingJsonStringField.d.ts

@@ -0,0 +1,2 @@
+/** The buffer may lack a closing quote; any decoded prefix is returned for live preview. */
+export declare function readStreamingJsonStringField(jsonText: string, key: string): string | null;

package/esm/src/host/readStreamingJsonStringField.js

@@ -0,0 +1,27 @@
+import { readJsonString } from '../kernel/util/partial-json.js';
+/** The buffer may lack a closing quote; any decoded prefix is returned for live preview. */
+export function readStreamingJsonStringField(jsonText, key) {
+    const keyLiteral = JSON.stringify(key);
+    let keyAt = jsonText.indexOf(keyLiteral);
+    let i = -1;
+    while (keyAt >= 0) {
+        i = keyAt + keyLiteral.length;
+        while (/\s/.test(jsonText[i] ?? '')) {
+            i += 1;
+        }
+        if (jsonText[i] === ':') {
+            i += 1;
+            while (/\s/.test(jsonText[i] ?? '')) {
+                i += 1;
+            }
+            if (jsonText[i] === '"') {
+                break;
+            }
+        }
+        keyAt = jsonText.indexOf(keyLiteral, keyAt + keyLiteral.length);
+    }
+    if (keyAt < 0 || jsonText[i] !== '"') {
+        return null;
+    }
+    return readJsonString(jsonText, i).text;
+}

package/esm/src/host/reply.d.ts

@@ -0,0 +1,13 @@
+/** HTTP status for a success. */
+declare const HTTP_OK = 200;
+/** HTTP status for an unknown route. */
+declare const HTTP_NOT_FOUND = 404;
+/** HTTP status for a method the route does not take. */
+declare const HTTP_METHOD = 405;
+/** HTTP status for a request refused because the host is busy. */
+declare const HTTP_BUSY = 429;
+/** A JSON response with the status and the CORS headers. */
+declare function json(status: number, body: unknown, cors: Record<string, string>): Response;
+/** The HTTP status for a caught error, by its kind. */
+declare function caughtStatus(err: unknown): number;
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json };

package/esm/src/host/reply.js

@@ -0,0 +1,41 @@
+import { errorKind } from '../guardrails/error.js';
+/** HTTP status for a success. */
+const HTTP_OK = 200;
+/** HTTP status for an unknown route. */
+const HTTP_NOT_FOUND = 404;
+/** HTTP status for a method the route does not take. */
+const HTTP_METHOD = 405;
+/** HTTP status for a request refused because the host is busy. */
+const HTTP_BUSY = 429;
+const STATUS_BY_KIND = {
+    config: 500,
+    request: 400,
+    input: 422,
+    action: 403,
+    auth: 401,
+    rate_limit: HTTP_BUSY,
+    unsupported: 422,
+    unavailable: 503,
+    bad_response: 502,
+    network: 502,
+    timeout: 504,
+    safety: 422,
+    blocked: 403,
+    declined: 409,
+    failed: 502,
+    // why: Client closed request (nginx convention): the caller went away.
+    cancelled: 499,
+    internal: 500,
+};
+/** A JSON response with the status and the CORS headers. */
+function json(status, body, cors) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { ...cors, 'Content-Type': 'application/json' },
+    });
+}
+/** The HTTP status for a caught error, by its kind. */
+function caughtStatus(err) {
+    return STATUS_BY_KIND[errorKind(err)];
+}
+export { caughtStatus, HTTP_BUSY, HTTP_METHOD, HTTP_NOT_FOUND, HTTP_OK, json };

package/esm/src/interface/blocks.d.ts

@@ -0,0 +1,11 @@
+import type { TurnEvent } from '../kernel/types.js';
+import type { FoldTurnEventsOptions, TranscriptBlock, UserTurnDraft } from './types.js';
+/** Restarts block id numbering at zero. */
+declare function resetBlockIds(): void;
+/** Turns a user draft into transcript blocks: a `user-text` block for the trimmed text, then one block per attachment and per voice clip. */
+declare function buildUserTurnBlocks(draft: UserTurnDraft, idPrefix?: string): TranscriptBlock[];
+/** Resets only the turn id sequence, so streaming refolds keep stable `turn-*` keys. */
+declare function foldTurnEvents(events: readonly TurnEvent[], options?: FoldTurnEventsOptions): TranscriptBlock[];
+/** One conversation turn as blocks: the user draft's blocks followed by the assistant events folded into blocks. */
+declare function foldConversationTurn(draft: UserTurnDraft, assistantEvents: readonly TurnEvent[], options?: FoldTurnEventsOptions): TranscriptBlock[];
+export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds };