@retinue/agentkit 0.2.0 → 0.3.1

package/dist/agents/engine.js

@@ -18,6 +18,7 @@
  *    on a refusal the model cannot resolve.
  */
 import { AgentPlatformError, isAgentPlatformError } from "../core/errors.js";
+import { connectionNeedOf } from "../connections/pause.js";
 import { asId } from "../core/ids.js";
 import { applyInputGuardrails, applyOutputGuardrails } from "../guardrails/index.js";
 import { streamModelTurn, turnText } from "../models/index.js";
@@ -118,9 +119,48 @@ export const createDefaultEngine = (deps) => {
     const now = deps.now ?? Date.now;
     const streamTurn = deps.streamTurn ?? streamModelTurn;
     return {
-        async *run({ run, context, signal }) {
-            const manifest = await deps.loadManifest({ agentId: run.agentId, version: run.agentVersion, context });
+        async *run({ run, context: hostContext, signal }) {
+            const manifest = await deps.loadManifest({
+                agentId: run.agentId,
+                version: run.agentVersion,
+                context: hostContext,
+            });
+            /**
+             * The agent's tool policy, put on the context for everything downstream — task #244.
+             *
+             * The engine is the only layer that holds both halves: the manifest (per agent) and the registry (per
+             * deployment). Rather than threading the policy through `buildTools`, tool execution, `execute_tool` and
+             * every delegating tool, it travels on the context — which a model cannot write to, so `excluded` cannot
+             * be widened from inside a turn. `ExecutionContext.shadow` is the precedent and the same argument.
+             *
+             * Scoped **once, here**, and used everywhere below. A host-supplied context that already carried a policy
+             * is overridden by the manifest's: the manifest is what the run's `agentVersion` pins, so a stored
+             * definition — not the caller — decides what this agent may reach.
+             */
+            const context = { ...hostContext, agentToolPolicy: manifest.toolPolicy };
             const resolved = deps.resolveModel(manifest, context);
+            /**
+             * A structured agent needs a model that can do it — task #243 AC-3.
+             *
+             * Checked at resolution, before a token is spent, and here rather than only in the host's `resolveModel`
+             * because that callback is the host's: a host that has not been updated would resolve a text-only model
+             * and the agent would silently get prose, which is the defect being fixed rather than a new one.
+             *
+             * Skipped when the host returned no `definition`, following the same rule `modelModalities` already uses
+             * (#185): a caller that did not say what the model can do has not said it cannot do this, and refusing
+             * every structured agent from every host that has not been updated would be an outage dressed as a check.
+             */
+            if (manifest.responseFormat?.kind === "structured" && resolved.definition !== undefined) {
+                if (resolved.definition.capabilities?.structuredOutput !== true)
+                    throw new AgentPlatformError({
+                        code: "capability_unavailable",
+                        message: `agent "${manifest.id}" asks for a structured response format and the resolved model ` +
+                            `${resolved.modelId} does not declare the \`structuredOutput\` capability. Add ` +
+                            "`requiredCapabilities: { structuredOutput: true }` to the agent's model policy so resolution " +
+                            "picks a model that can, rather than discovering it mid-turn.",
+                        retryable: false,
+                    });
+            }
             const system = (await (deps.systemPrompt?.(manifest, context) ?? manifest.instructions)) || undefined;
             const history = await deps.loadHistory(context, run);
             const built = deps.buildTools ? await deps.buildTools(context, manifest) : [];
@@ -142,7 +182,22 @@ export const createDefaultEngine = (deps) => {
                     budget: deps.catalogBudget,
                     tokensOf: turnToolTokens,
                     nameOf: (tool) => tool.name,
-                    protect: (tool) => META_TOOLS.includes(tool.name),
+                    /**
+                     * Protected: meta-tools, and whatever the agent declared preloaded — task #244.
+                     *
+                     * `toolPolicy.preloaded` and `toolPolicy.categories` say "these are loaded up front; everything
+                     * else is discovered lazily". In this architecture *resident* is what "loaded up front" means, so
+                     * the honest interpretation of both fields is that a budget may not drop them. With no budget
+                     * configured every tool is resident anyway and the fields are a no-op — correct, and the reason
+                     * they cannot be enforced anywhere else.
+                     *
+                     * Note this cannot make a tool appear: an excluded tool never reaches `built` (the registry
+                     * removed it), and naming an excluded tool as preloaded does not resurrect it. Exclusion is a
+                     * permission and residency is a budget; the permission wins.
+                     */
+                    protect: (tool) => META_TOOLS.includes(tool.name) ||
+                        (manifest.toolPolicy?.preloaded ?? []).includes(tool.name) ||
+                        (tool.category !== undefined && (manifest.toolPolicy?.categories ?? []).includes(tool.category)),
                 });
             const declared = budgetOutcome?.resident ?? built;
             if (budgetOutcome !== undefined && (budgetOutcome.dropped.length > 0 || budgetOutcome.overBudget)) {
@@ -232,6 +287,58 @@ export const createDefaultEngine = (deps) => {
              * carried on and completed. The person's answer arrived for a run that was already over.
              */
             let pendingQuestion = null;
+            /**
+             * A connection a tool needed and the tenant does not have — task #264.
+             *
+             * Tracked exactly like `pendingApproval` and `pendingQuestion`, and for the same reason: the run has to
+             * stop on an *event* the worker understands rather than on an error the model would try to work around.
+             */
+            /**
+             * Turns a marked connection failure into a pause, or leaves it to fail — task #264.
+             *
+             * Three ways to end up failing rather than pausing, and each is deliberate:
+             *
+             * - the failure is not a connection gap at all
+             * - no `connectionConsent` is wired, so this deployment has no flow to send anybody to
+             * - the callback returns `null`, meaning *this provider* is token-only and there is no login URL
+             *
+             * All three fail, because the alternative is a run parked for ever on a consent screen nobody can reach.
+             */
+            const consentMarker = async (thrown, toolName) => {
+                const need = connectionNeedOf(thrown);
+                if (need === null || deps.connectionConsent === undefined)
+                    return null;
+                const offer = await deps.connectionConsent({ context, need: { ...need, toolName } });
+                if (offer === null)
+                    return null;
+                return {
+                    event: {
+                        type: "connection.requested",
+                        provider: need.provider,
+                        loginUrl: offer.loginUrl,
+                        scopes: offer.scopes,
+                        toolName,
+                        expiresAt: offer.expiresAt,
+                    },
+                    // Returned to the model, not thrown — the same choice the approval path makes. The tool call stays a
+                    // real part of the record with a real result, and the run pauses on the event rather than on an error
+                    // the model would try to work around.
+                    marker: {
+                        status: "connection_required",
+                        provider: need.provider,
+                        message: `${toolName} needs a ${need.provider} connection. The run is paused; do not retry.`,
+                    },
+                };
+            };
+            /**
+             * The formed event, not the parts.
+             *
+             * Storing the pieces and building the event at the check site fought control-flow analysis: the
+             * assignment happens inside a tool's `execute` closure, so the outer `let` narrows to `never` at the
+             * check and every property access errors. Holding the event itself needs no property access there, and
+             * reads more like `pendingApproval` — a value the emit site simply yields.
+             */
+            let pendingConnection = null;
             /**
              * Citation candidates a tool handed back this turn, waiting for the claims they ground — #165.
              *
@@ -328,10 +435,15 @@ export const createDefaultEngine = (deps) => {
                         }
                         catch (thrown) {
                             const parked = questionMarker(thrown, t.name);
-                            if (parked === null)
+                            if (parked !== null) {
+                                pendingQuestion = parked.interactionId;
+                                return parked.marker;
+                            }
+                            const consent = await consentMarker(thrown, t.name);
+                            if (consent === null)
                                 throw thrown;
-                            pendingQuestion = parked.interactionId;
-                            return parked.marker;
+                            pendingConnection = consent.event;
+                            return consent.marker;
                         }
                     }
                     const outcome = await approvals.runTool(context, run.id, { name: t.name, input });
@@ -365,6 +477,8 @@ export const createDefaultEngine = (deps) => {
             let attempt = 1;
             for (;;) {
                 let emitted = 0;
+                // Whether this turn produced the structured answer a structured agent promises — #243.
+                let sawStructured = false;
                 const textParts = new Map();
                 const controller = new AbortController();
                 try {
@@ -402,6 +516,15 @@ export const createDefaultEngine = (deps) => {
                         ...(resolved.definition === undefined
                             ? {}
                             : { modelModalities: resolved.definition.inputModalities }),
+                        // Mapped from the manifest here, so the model layer stays free of any dependency on `agents/`.
+                        ...(manifest.responseFormat?.kind === "structured"
+                            ? { structuredOutput: { schema: manifest.responseFormat.schema } }
+                            : {}),
+                        // From the resolved model's own declaration — #247. Absent definition means send nothing, the same
+                        // rule `modelModalities` follows: a host that has not said what its model does has not said it caches.
+                        ...(resolved.definition?.capabilities?.promptCaching === undefined
+                            ? {}
+                            : { promptCaching: resolved.definition.capabilities.promptCaching }),
                         tools,
                         maxSteps,
                         abortSignal: controller.signal,
@@ -415,6 +538,8 @@ export const createDefaultEngine = (deps) => {
                         }
                         for (const event of mapChunk(chunk, messageId, resolved, textParts, ranByCall)) {
                             emitted += 1;
+                            if (event.type === "part.added" && event.part.type === "structured")
+                                sawStructured = true;
                             yield event;
                         }
                         // Raised by a tool call this turn. Stop here rather than letting the model keep going: the
@@ -432,6 +557,13 @@ export const createDefaultEngine = (deps) => {
                             yield { type: "question.requested", interactionId: asId(pendingQuestion) };
                             return;
                         }
+                        // The third stop — #264. The event carries the provider, the scopes and the URL, and **no secret**:
+                        // it is rendered in a UI and clicked by a person, so it goes wherever a screenshot goes.
+                        if (pendingConnection !== null) {
+                            controller.abort();
+                            yield pendingConnection;
+                            return;
+                        }
                     }
                     /**
                      * Citations last, grounding the claims that were actually written — #165.
@@ -445,6 +577,23 @@ export const createDefaultEngine = (deps) => {
                      * After the stream, so a citation cannot appear above text the reader is already looking at — the
                      * append-only property `citationViewModel` depends on.
                      */
+                    /**
+                     * A structured agent must have produced a structured answer — task #243 AC-2.
+                     *
+                     * `streamModelTurn` already validates and fails, so in the normal path this never fires. It fires for
+                     * a host that supplied its own `streamTurn`, and that is the case worth guarding: the guarantee a
+                     * consumer bought is "structured or an error", and if it depended solely on the shipped model layer
+                     * then any host replacing that layer would silently get prose again — the original defect, reachable
+                     * through a documented extension point.
+                     */
+                    if (manifest.responseFormat?.kind === "structured" && !sawStructured)
+                        throw new AgentPlatformError({
+                            code: "provider_error",
+                            message: `agent "${manifest.id}" asks for a structured response format and the turn produced none. ` +
+                                "The run fails rather than returning the turn's text, which would be prose presented as a " +
+                                "validated object.",
+                            retryable: true,
+                        });
                     for (const record of pendingVerdicts.splice(0))
                         yield verdictEvent(record);
                     if (deps.citations !== undefined && pendingCitations.length > 0) {
@@ -631,6 +780,9 @@ ranByCall = new Map()) {
                 inputTokens: chunk.usage.inputTokens,
                 outputTokens: chunk.usage.outputTokens,
                 cachedInputTokens: chunk.usage.cachedInputTokens,
+                // Carried only when the provider reported it, so a turn with no breakdown is distinguishable from a
+                // turn that wrote nothing — the same rule `imageCount` follows two lines down.
+                ...(chunk.usage.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: chunk.usage.cacheWriteTokens }),
                 ...(chunk.usage.reasoningTokens !== undefined ? { reasoningTokens: chunk.usage.reasoningTokens } : {}),
                 // Counted at the send site (`nonTextCounts`), carried through so the ledger records it (#185).
                 ...(chunk.usage.imageCount !== undefined ? { imageCount: chunk.usage.imageCount } : {}),
@@ -641,6 +793,25 @@ ranByCall = new Map()) {
             };
             return;
         }
+        case "structured-output": {
+            /**
+             * The validated answer of a structured agent — task #243.
+             *
+             * Emitted once, complete. `streamModelTurn` has already validated it against the schema and fails the turn
+             * if it does not conform, so reaching here means the value satisfies what the caller asked for. Nothing
+             * partial is ever emitted: a half-built object does not satisfy a schema, so streaming one would publish
+             * values that violate the contract.
+             */
+            const part = {
+                id: `${messageId}:structured`,
+                type: "structured",
+                schemaVersion: 1,
+                createdAt: new Date(0).toISOString(),
+                value: chunk.value,
+            };
+            yield { type: "part.added", messageId, part };
+            return;
+        }
         case "error":
             throw chunk.error instanceof Error ? chunk.error : new Error(String(chunk.error));
     }

package/dist/audio/index.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Hearing and speaking — REQ-062 (#257), task #258, Part 2.
+ *
+ * Two ports, because the two acts are genuinely separate and a deployment will often want one and not the
+ * other: transcription turns audio into text so a text-only model can read it, and speech turns text into
+ * audio so an interface can play it.
+ *
+ * ## Why ports rather than tools that call an API
+ *
+ * The same reason `tools-search` supplies providers instead of tools. Whisper, Deepgram, AssemblyAI and a
+ * self-hosted `whisper.cpp` are four *values*, not four sets of tools — and which one a deployment uses is a
+ * decision about cost, residency and latency that a model should never spend a tool call discovering.
+ *
+ * It also keeps AC-2's real case honest: *"so a deployment can use a model that does not accept audio
+ * natively"*. Most models do not. Transcribing first and sending text is how audio reaches them at all, and
+ * that path has to exist independently of any one provider.
+ *
+ * ## Bounds are enforced before the upload, not after
+ *
+ * AC-4 says so and it is the part most easily got wrong: the natural implementation reads the file, stores it,
+ * and then checks. A rejected 200MB recording must not be stored first — it costs the blob write, the
+ * retention obligation and the deletion, all for something that was never going to be accepted.
+ *
+ * So the check takes a *declared* size and media type and answers before any bytes move. `assertWithinBounds`
+ * is the function a caller runs at the boundary; nothing here reads a file to find out whether it may.
+ *
+ * ## Duration is bounded too, and it cannot be checked from the size
+ *
+ * A byte ceiling is not a duration ceiling: an hour of 8kbps speech is smaller than a minute of uncompressed
+ * WAV. Both matter for different reasons — bytes bound the storage and the upload, seconds bound the *cost*,
+ * because audio is billed per second. A deployment that bounded only bytes would have an unbounded bill.
+ *
+ * Duration is therefore checked where it becomes known: declared by the caller if it knows, and reported by
+ * the provider afterwards. `assertWithinBounds` refuses a declared duration over the ceiling before the call;
+ * `TranscriptionResult.durationSeconds` is what usage is charged on.
+ */
+import { type PlatformError } from "../core/errors.js";
+/**
+ * The media types accepted, and it is a list rather than `audio/*` on purpose.
+ *
+ * A provider rejects an unknown container with a message about the request, not about the format, so the
+ * useful refusal happens here. Every entry is one that the shipped adapters actually accept.
+ */
+export declare const AUDIO_MEDIA_TYPES: readonly ["audio/mpeg", "audio/mp4", "audio/wav", "audio/webm", "audio/ogg", "audio/flac", "audio/x-m4a"];
+export type AudioMediaType = (typeof AUDIO_MEDIA_TYPES)[number];
+export declare const isAudioMediaType: (mediaType: string) => mediaType is AudioMediaType;
+/**
+ * 25MB, which is where every hosted transcription API this could target draws its own line.
+ *
+ * Matching the provider's limit rather than inventing a smaller one: a deployment that wants less sets its
+ * own, and a ceiling *above* the provider's would just move the failure later and make it theirs to explain.
+ */
+export declare const MAX_AUDIO_BYTES: number;
+/**
+ * One hour.
+ *
+ * The number is about cost rather than capability. At a typical per-second rate an hour is already a
+ * noticeable charge for a single tool call, and a run that transcribes a six-hour recording by accident is the
+ * kind of bill nobody notices until the invoice.
+ */
+export declare const MAX_AUDIO_SECONDS = 3600;
+/**
+ * The transcript ceiling — AC-5.
+ *
+ * An hour of speech is roughly 9,000 words, which fits. This bounds the *pathological* case: a provider that
+ * returns a repeated hallucination on silence, which is a known Whisper failure mode and produces megabytes of
+ * one phrase. Truncation is reported, never silent — a shortened transcript that claimed to be complete would
+ * make the model summarise a fragment as if it were the whole recording.
+ */
+export declare const MAX_TRANSCRIPT_CHARS = 100000;
+/** What speech generation may be asked to say. Bounds the cost the same way the audio ceiling does. */
+export declare const MAX_SPEECH_CHARS = 4000;
+export type AudioBounds = {
+    readonly maxBytes?: number;
+    readonly maxSeconds?: number;
+};
+export declare class AudioRejected extends Error {
+    readonly code: "invalid_input";
+}
+/**
+ * Refuses before anything is stored or sent — AC-4.
+ *
+ * Takes what a caller knows *without reading the file*: the declared byte length and media type from the
+ * upload, and a duration if the client measured one. Deliberately not given the bytes: a function that
+ * received them would invite reading them, and the whole point is to answer before they move.
+ */
+export declare const assertWithinBounds: (input: {
+    readonly byteSize: number;
+    readonly mediaType: string;
+    readonly durationSeconds?: number;
+}, bounds?: AudioBounds) => void;
+/** A transcript, bounded, with the truncation reported rather than hidden. */
+export type TranscriptionResult = {
+    readonly text: string;
+    /**
+     * What usage is charged on — AC-8. Reported by the provider, because only it knows.
+     *
+     * A provider that does not report it leaves this absent rather than guessing, and the recorder then charges
+     * nothing for the audio. That under-bills, which is why the shipped adapter asks for a response format that
+     * includes it.
+     */
+    readonly durationSeconds?: number;
+    readonly truncated: boolean;
+    /** The provider's own language detection, when it offers one. Not a translation — see the REQ's scope. */
+    readonly language?: string;
+};
+export type TranscriptionRequest = {
+    readonly audio: Uint8Array;
+    readonly mediaType: string;
+    readonly filename?: string;
+    /** A hint, not an instruction. A provider free to detect is usually better at it than a caller guessing. */
+    readonly languageHint?: string;
+    readonly maxTranscriptChars?: number;
+};
+export interface TranscriptionProvider {
+    readonly id: string;
+    transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+}
+export type SpeechRequest = {
+    readonly text: string;
+    /** The provider's own voice identifier. Opaque here: naming a fixed set would date immediately. */
+    readonly voice?: string;
+    readonly format?: "mp3" | "wav" | "opus" | "flac";
+};
+export type SpeechResult = {
+    readonly audio: Uint8Array;
+    readonly mediaType: string;
+    /** Absent when the provider does not report it. Charged on when present. */
+    readonly durationSeconds?: number;
+};
+export interface SpeechProvider {
+    readonly id: string;
+    speak(request: SpeechRequest): Promise<SpeechResult>;
+}
+/** Bounds a transcript and says whether it had to. */
+export declare const boundTranscript: (text: string, maxChars?: number) => {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * A provider failure, in the platform's vocabulary — AC-5.
+ *
+ * Deliberately the same shape and the same distinctions as `describeFetchFailure`: 429 and 5xx retryable,
+ * unreachable `provider_unavailable`, everything else terminal. A second vocabulary for audio would mean the
+ * runtime's retry logic treated a transcription rate limit differently from a scrape rate limit for no reason
+ * anybody chose.
+ */
+export declare const describeAudioFailure: (error: unknown, provider: string) => PlatformError;
+/** Throws the classified failure, for a caller that would rather not branch. */
+export declare const failAudio: (error: unknown, provider: string) => never;
+//# sourceMappingURL=index.d.ts.map

package/dist/audio/index.js

@@ -0,0 +1,183 @@
+/**
+ * Hearing and speaking — REQ-062 (#257), task #258, Part 2.
+ *
+ * Two ports, because the two acts are genuinely separate and a deployment will often want one and not the
+ * other: transcription turns audio into text so a text-only model can read it, and speech turns text into
+ * audio so an interface can play it.
+ *
+ * ## Why ports rather than tools that call an API
+ *
+ * The same reason `tools-search` supplies providers instead of tools. Whisper, Deepgram, AssemblyAI and a
+ * self-hosted `whisper.cpp` are four *values*, not four sets of tools — and which one a deployment uses is a
+ * decision about cost, residency and latency that a model should never spend a tool call discovering.
+ *
+ * It also keeps AC-2's real case honest: *"so a deployment can use a model that does not accept audio
+ * natively"*. Most models do not. Transcribing first and sending text is how audio reaches them at all, and
+ * that path has to exist independently of any one provider.
+ *
+ * ## Bounds are enforced before the upload, not after
+ *
+ * AC-4 says so and it is the part most easily got wrong: the natural implementation reads the file, stores it,
+ * and then checks. A rejected 200MB recording must not be stored first — it costs the blob write, the
+ * retention obligation and the deletion, all for something that was never going to be accepted.
+ *
+ * So the check takes a *declared* size and media type and answers before any bytes move. `assertWithinBounds`
+ * is the function a caller runs at the boundary; nothing here reads a file to find out whether it may.
+ *
+ * ## Duration is bounded too, and it cannot be checked from the size
+ *
+ * A byte ceiling is not a duration ceiling: an hour of 8kbps speech is smaller than a minute of uncompressed
+ * WAV. Both matter for different reasons — bytes bound the storage and the upload, seconds bound the *cost*,
+ * because audio is billed per second. A deployment that bounded only bytes would have an unbounded bill.
+ *
+ * Duration is therefore checked where it becomes known: declared by the caller if it knows, and reported by
+ * the provider afterwards. `assertWithinBounds` refuses a declared duration over the ceiling before the call;
+ * `TranscriptionResult.durationSeconds` is what usage is charged on.
+ */
+import { AgentPlatformError } from "../core/errors.js";
+/**
+ * The media types accepted, and it is a list rather than `audio/*` on purpose.
+ *
+ * A provider rejects an unknown container with a message about the request, not about the format, so the
+ * useful refusal happens here. Every entry is one that the shipped adapters actually accept.
+ */
+export const AUDIO_MEDIA_TYPES = [
+    "audio/mpeg",
+    "audio/mp4",
+    "audio/wav",
+    "audio/webm",
+    "audio/ogg",
+    "audio/flac",
+    "audio/x-m4a",
+];
+export const isAudioMediaType = (mediaType) => AUDIO_MEDIA_TYPES.includes(mediaType.split(";")[0]?.trim().toLowerCase() ?? "");
+/**
+ * 25MB, which is where every hosted transcription API this could target draws its own line.
+ *
+ * Matching the provider's limit rather than inventing a smaller one: a deployment that wants less sets its
+ * own, and a ceiling *above* the provider's would just move the failure later and make it theirs to explain.
+ */
+export const MAX_AUDIO_BYTES = 25 * 1024 * 1024;
+/**
+ * One hour.
+ *
+ * The number is about cost rather than capability. At a typical per-second rate an hour is already a
+ * noticeable charge for a single tool call, and a run that transcribes a six-hour recording by accident is the
+ * kind of bill nobody notices until the invoice.
+ */
+export const MAX_AUDIO_SECONDS = 3_600;
+/**
+ * The transcript ceiling — AC-5.
+ *
+ * An hour of speech is roughly 9,000 words, which fits. This bounds the *pathological* case: a provider that
+ * returns a repeated hallucination on silence, which is a known Whisper failure mode and produces megabytes of
+ * one phrase. Truncation is reported, never silent — a shortened transcript that claimed to be complete would
+ * make the model summarise a fragment as if it were the whole recording.
+ */
+export const MAX_TRANSCRIPT_CHARS = 100_000;
+/** What speech generation may be asked to say. Bounds the cost the same way the audio ceiling does. */
+export const MAX_SPEECH_CHARS = 4_000;
+export class AudioRejected extends Error {
+    code = "invalid_input";
+}
+/**
+ * Refuses before anything is stored or sent — AC-4.
+ *
+ * Takes what a caller knows *without reading the file*: the declared byte length and media type from the
+ * upload, and a duration if the client measured one. Deliberately not given the bytes: a function that
+ * received them would invite reading them, and the whole point is to answer before they move.
+ */
+export const assertWithinBounds = (input, bounds = {}) => {
+    const maxBytes = bounds.maxBytes ?? MAX_AUDIO_BYTES;
+    const maxSeconds = bounds.maxSeconds ?? MAX_AUDIO_SECONDS;
+    if (!isAudioMediaType(input.mediaType)) {
+        throw new AudioRejected(`${input.mediaType} is not an audio format this deployment accepts. Accepted: ` +
+            `${AUDIO_MEDIA_TYPES.join(", ")}.`);
+    }
+    if (!Number.isFinite(input.byteSize) || input.byteSize <= 0) {
+        throw new AudioRejected("An audio attachment needs a declared size, and it must be greater than zero.");
+    }
+    if (input.byteSize > maxBytes) {
+        throw new AudioRejected(`That recording is ${Math.round(input.byteSize / 1024 / 1024)}MB and the limit is ` +
+            `${Math.round(maxBytes / 1024 / 1024)}MB. Refused before upload — nothing was stored.`);
+    }
+    /**
+     * Duration only when the caller declared one.
+     *
+     * Absent is not an error: a browser knows the duration of a recording it just made and a server receiving a
+     * file often does not, and demanding it would mean either refusing legitimate uploads or reading the file to
+     * find out — which is the thing this function exists to avoid.
+     */
+    if (input.durationSeconds !== undefined && input.durationSeconds > maxSeconds) {
+        throw new AudioRejected(`That recording is ${Math.round(input.durationSeconds / 60)} minutes and the limit is ` +
+            `${Math.round(maxSeconds / 60)}. Refused before upload — nothing was stored.`);
+    }
+};
+/** Bounds a transcript and says whether it had to. */
+export const boundTranscript = (text, maxChars = MAX_TRANSCRIPT_CHARS) => {
+    if (text.length <= maxChars)
+        return { text, truncated: false };
+    /**
+     * Cut at a word boundary when there is one nearby.
+     *
+     * A transcript sliced mid-word reads as a transcription error rather than as a truncation, and a model
+     * summarising it will occasionally treat the fragment as a real word. The 200-character window is small
+     * enough that the ceiling still means what it says.
+     */
+    const hard = text.slice(0, maxChars);
+    const lastSpace = hard.lastIndexOf(" ");
+    /**
+     * `lastSpace > 0` matters, and its absence was a bug the tests caught.
+     *
+     * `lastIndexOf` returns `-1` when there is no space at all — and `-1 > maxChars - 200` is *true* for any
+     * ceiling under 200, so the original condition sliced to `-1` and silently dropped the final character of
+     * every space-free transcript. A one-character loss that no assertion about truncation would notice.
+     */
+    const useBoundary = lastSpace > 0 && lastSpace > maxChars - 200;
+    return { text: useBoundary ? hard.slice(0, lastSpace) : hard, truncated: true };
+};
+/**
+ * A provider failure, in the platform's vocabulary — AC-5.
+ *
+ * Deliberately the same shape and the same distinctions as `describeFetchFailure`: 429 and 5xx retryable,
+ * unreachable `provider_unavailable`, everything else terminal. A second vocabulary for audio would mean the
+ * runtime's retry logic treated a transcription rate limit differently from a scrape rate limit for no reason
+ * anybody chose.
+ */
+export const describeAudioFailure = (error, provider) => {
+    if (error instanceof AudioRejected) {
+        return { code: "invalid_input", message: error.message, retryable: false };
+    }
+    const status = error.status;
+    const message = error instanceof Error ? error.message : String(error);
+    if (status === 429) {
+        return { code: "rate_limited", message: `${provider} is rate limiting: ${message}`, retryable: true };
+    }
+    if (status === 413) {
+        // Not retryable, and worth its own arm: the file is too large and will be next time too.
+        return {
+            code: "invalid_input",
+            message: `${provider} refused the recording as too large: ${message}`,
+            retryable: false,
+        };
+    }
+    if (status === 401 || status === 403) {
+        return {
+            code: "unauthorized",
+            message: `${provider} refused the credential: ${message}. Retrying will not help.`,
+            retryable: false,
+        };
+    }
+    if (status !== undefined && status >= 500) {
+        return { code: "provider_unavailable", message: `${provider} returned ${status}: ${message}`, retryable: true };
+    }
+    if (/timed out|etimedout|abort|fetch failed|econnrefused|enotfound/i.test(message)) {
+        return { code: "provider_unavailable", message: `${provider} could not be reached: ${message}`, retryable: true };
+    }
+    return { code: "provider_error", message: `${provider} could not process the audio: ${message}`, retryable: false };
+};
+/** Throws the classified failure, for a caller that would rather not branch. */
+export const failAudio = (error, provider) => {
+    throw new AgentPlatformError(describeAudioFailure(error, provider));
+};
+//# sourceMappingURL=index.js.map