@deadair/plugin-sdk 0.2.0

package/dist/capabilities/llm.d.ts

@@ -0,0 +1,318 @@
+/**
+ * The `llm` capability. A language-model plugin takes a conversation and answers
+ * with words: the line a DJ says, the running order a set generator asked for,
+ * the copy for a sponsor read.
+ *
+ * ## This is a transport, not a writer
+ *
+ * Nothing here knows what a break is. That is deliberate and it is the one
+ * constraint worth defending: the previous station had five things that produced
+ * a script (a talk break, a sign-on, a news bulletin, a DJ set, a two-voice
+ * dialogue) and every one of them was messages in and text out. A capability
+ * shaped around any single one of them has to be reshaped for the next.
+ *
+ * So: {@link LlmMessage}s in, text out, and everything about WHAT to say lives
+ * on the station's side of the fence.
+ *
+ * ## The words come back as a stream
+ *
+ * {@link LlmPluginInstance.generate} answers with a handle carrying a stream, the
+ * way `speak()` does, and for a stronger reason than memory. The host serializes
+ * generations through a single slot, and it holds that slot until the words stop
+ * arriving rather than until the call resolves. On a local model, releasing early
+ * lets two generations overlap and both of them get slower.
+ *
+ * Read {@link LlmHandle.text} to the end, or `cancel()` it. Then await
+ * {@link LlmHandle.result}, which is where the tool calls, the usage and the
+ * reason it stopped are. {@link collectGeneration} does both for a caller that
+ * only wants the answer.
+ *
+ * ## The model is chosen per call
+ *
+ * {@link LlmRequest.model} overrides whatever the plugin has configured, because
+ * a station wants a big model for a show and a small one for a station ident, and
+ * one plugin holds exactly one config row (`plugin_configs.plugin_id` is a
+ * primary key). Absent means "whatever you are set up with", which is the
+ * ordinary case.
+ *
+ * ## Tools are declared here and executed by the host
+ *
+ * A request may carry {@link LlmToolDeclaration}s. What comes back is
+ * {@link LlmToolCall}s: data, not invocations. The host runs the tool and sends
+ * the result back as another message.
+ *
+ * That split is not ceremony. A callback crossing this boundary would be a
+ * function in a payload, and it would put station code inside a plugin, which is
+ * the wrong side of the fence for deciding what the station is allowed to do.
+ * Every shape in this file except {@link LlmHandle} is JSON-safe, and the one
+ * exception carries a stream on purpose.
+ */
+import type { PluginLifecycle } from '../plugin.lifecycle.js';
+/**
+ * How hard a reasoning model should think before answering.
+ *
+ * Sent as `reasoning_effort`, and **only when the caller asked for it** — which is
+ * a hint, not a guarantee it reaches the server. A plugin may hold its own
+ * setting that overrides this, forwards it unchanged, or refuses to send it at
+ * all, and a plugin that has seen a 400 naming the field drops it for its own
+ * lifetime regardless of what a caller asks for afterward. Leave it unset for
+ * anything that is not a reasoning model: the field means nothing to a plain
+ * model and a strict OpenAI-compatible server answers 400 rather than ignoring
+ * it.
+ */
+export type LlmReasoningEffort = 'low' | 'medium' | 'high';
+/** Why a generation stopped. `tool-calls` is the one the host's loop acts on. */
+export type LlmFinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'other';
+/** One turn of the conversation. */
+export interface LlmMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /**
+     * The words. Empty is legitimate on an `assistant` turn that did nothing but
+     * ask for a tool.
+     */
+    content: string;
+    /**
+     * What this `assistant` turn asked for, when it asked for tools.
+     *
+     * The host replays it verbatim on the next call, because a model that cannot
+     * see its own tool call has no idea what the `tool` message after it is
+     * answering.
+     */
+    toolCalls?: LlmToolCall[];
+    /** Which call this `tool` turn answers. Absent on every other role. */
+    toolCallId?: string;
+    /**
+     * What the provider signed on this `assistant` turn, quoted back verbatim.
+     * Absent on every other role, and absent from a provider that signs nothing.
+     *
+     * Opaque to the host, which is the point: it is the plugin's own
+     * {@link LlmResult.providerState} handed straight back, so a provider that
+     * refuses a turn missing its own signature gets one that has it. See
+     * {@link LlmResult.providerState} for what puts it there.
+     */
+    providerState?: Record<string, unknown>;
+}
+/** A tool the model may ask for. */
+export interface LlmToolDeclaration {
+    /** How the model names it when calling. */
+    name: string;
+    /**
+     * What it does, written for the model rather than for a developer. This is
+     * the entire basis on which it decides whether to call the thing, so "current
+     * conditions and today's high and low for a place" beats "weather lookup".
+     */
+    description: string;
+    /**
+     * JSON Schema for the arguments, as a plain object.
+     *
+     * Not a zod schema: this is a payload that is sent, and a schema instance is
+     * a class. Convert on the way in if that is what you hold.
+     */
+    parameters: Record<string, unknown>;
+}
+/** The model asking for a tool. Data, not an invocation. */
+export interface LlmToolCall {
+    /** The model's own id for this call, quoted back on {@link LlmMessage.toolCallId}. */
+    id: string;
+    /** Which declaration it wants, by {@link LlmToolDeclaration.name}. */
+    name: string;
+    /**
+     * The arguments, already parsed out of the JSON the model produced.
+     *
+     * Unvalidated against the declared schema: the model is perfectly capable of
+     * inventing a field or omitting a required one, and the host checks before
+     * running anything.
+     */
+    arguments: Record<string, unknown>;
+}
+/** What one generation cost. Absent fields are ones the provider did not report. */
+export interface LlmUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    /**
+     * How much of {@link outputTokens} went on thinking rather than on the answer.
+     *
+     * Separate because the two failures underneath one `outputTokens` figure are
+     * opposite: a model that wrote a long answer and one that spent its whole
+     * allowance reasoning and emitted nothing both finish on `length` at the same
+     * total, and only this tells them apart. A caller that logs a token count
+     * without it cannot answer "where did the allowance go" after the fact, which
+     * is the question a zero-pick run actually raises.
+     *
+     * Reported by the provider, so absent on plenty of them — see
+     * {@link reasoningChars} for what to fall back on.
+     */
+    reasoningTokens?: number;
+    /**
+     * The length of the reasoning text, in characters.
+     *
+     * MEASURED rather than reported, and here for one reason: an
+     * OpenAI-compatible server that streams reasoning without counting it leaves
+     * {@link reasoningTokens} undefined, and a station running against one would
+     * otherwise learn nothing from either field. Characters are a poor unit and
+     * an honest one — roughly four to the token — so this answers the shape of
+     * the question ("all of it" versus "none of it") where the exact figure is
+     * not on offer.
+     */
+    reasoningChars?: number;
+}
+/** One conversation to continue. */
+export interface LlmRequest {
+    /**
+     * The conversation so far, oldest first, with the system prompt as the first
+     * turn where there is one.
+     */
+    messages: LlmMessage[];
+    /** Which model, or absent for the plugin's configured one. */
+    model?: string;
+    /** Sampling temperature, or absent for the plugin's configured one. */
+    temperature?: number;
+    /** A ceiling on the answer, in tokens. Absent means the provider's own. */
+    maxOutputTokens?: number;
+    /** See {@link LlmReasoningEffort}. Absent means send nothing at all. */
+    reasoningEffort?: LlmReasoningEffort;
+    /**
+     * What the model may call.
+     *
+     * Only sent to a model that says it can (see {@link LlmModelInfo.tools}), so
+     * a plugin receiving this has already been told the model supports it. If it
+     * does not, answer `unsupported` rather than dropping them silently: a break
+     * written without the facts a tool would have supplied is worse than one that
+     * fell back to the deterministic writer.
+     */
+    tools?: LlmToolDeclaration[];
+}
+/** Everything about a finished generation except the words as they arrived. */
+export interface LlmResult {
+    /** The whole answer, accumulated. Empty when the model only asked for tools. */
+    text: string;
+    /** What it asked for. Empty on an ordinary answer. */
+    toolCalls: LlmToolCall[];
+    /** What it cost, where the provider said. */
+    usage?: LlmUsage;
+    finishReason: LlmFinishReason;
+    /**
+     * Whatever this provider SIGNED on this turn, in the plugin's own shape, for
+     * the host to hand back on the `assistant` message it builds out of this
+     * result. Absent when the provider signed nothing, which is every
+     * OpenAI-compatible server.
+     *
+     * The host never reads it. It exists because two providers refuse a tool
+     * round trip whose earlier turns arrive stripped: Anthropic will not accept a
+     * turn whose thinking block and its signature are missing, and Gemini wants
+     * its thought signatures back on the function calls it made. Both are facts
+     * about a wire protocol rather than about a conversation, so the station's
+     * boundary carries them without describing them.
+     *
+     * JSON-safe like everything else here: it is stored in a transcript and sent
+     * back across the boundary, so no class instances and no functions.
+     */
+    providerState?: Record<string, unknown>;
+}
+/**
+ * A generation in flight.
+ *
+ * Carries a live stream, which is why it is classified as a live-object type in
+ * `boundary.json.safe.ts` rather than as a payload. {@link LlmResult} is the
+ * payload, and it is JSON-safe.
+ */
+export interface LlmHandle {
+    /**
+     * The answer as it arrives.
+     *
+     * The host reads it to the end or cancels it, and either one releases what is
+     * underneath. **Cancelling has to actually stop the generation**, which is a
+     * requirement on the PLUGIN rather than something the platform can arrange:
+     * the host has no other handle on the work once `generate` has returned.
+     *
+     * The trap that makes this worth spelling out is that forwarding a provider's
+     * stream does NOT satisfy it by itself. A plugin that hands over one branch of
+     * a tee, or whose {@link result} keeps reading the source, has given the host
+     * a stream it can close and a generation it cannot stop — and the invocation
+     * signal is no help, because that is disposed the moment `generate` resolves
+     * and a generation legitimately outlives the call that started it. So a plugin
+     * owns an abort of its own, for as long as the words are still arriving.
+     */
+    text: ReadableStream<string>;
+    /**
+     * Settles once the generation is done.
+     *
+     * **Read {@link text} first.** A provider stream that nobody is draining
+     * applies backpressure, so awaiting this without consuming the words is how a
+     * caller waits forever. {@link collectGeneration} exists so that ordering is
+     * not something each caller has to remember.
+     */
+    result: Promise<LlmResult>;
+}
+/** One model this plugin can be asked for. */
+export interface LlmModelInfo {
+    /** The id to pass back as {@link LlmRequest.model}. */
+    id: string;
+    /** What the console calls it. Absent means show the id. */
+    label?: string;
+    /**
+     * Whether this model can be given {@link LlmRequest.tools}.
+     *
+     * Per MODEL, not per server, which is why it lives here rather than on the
+     * plugin: one endpoint commonly serves both a model that can call tools and
+     * one that cannot, and asking the wrong one is a failed generation rather
+     * than a degraded answer.
+     */
+    tools: boolean;
+    /**
+     * Whether this is the model a request with no {@link LlmRequest.model} gets.
+     *
+     * Set it if you have one. Without it the host cannot tell which of the models
+     * you listed an unnamed request will actually reach, so it has to assume the
+     * worst one and will never send tools unless a caller names a model itself —
+     * which gets steadily more likely to be wrong the more models your server has.
+     */
+    default?: boolean;
+}
+/** A plugin that can produce words. */
+export interface LlmPluginInstance extends PluginLifecycle {
+    /**
+     * Continue the conversation.
+     *
+     * May return before any words exist, because the handle carries a stream and
+     * not the text, so a model that thinks for ten seconds shows up as a slow
+     * first chunk rather than as a slow `generate`.
+     *
+     * @throws {PluginError} `config` when the plugin is not set up enough to try
+     *   (no server address, no model), `unsupported` when asked for tools the
+     *   named model cannot do, `upstream` when the provider refused, `timeout`
+     *   when it did not answer, `rate_limited` when it said to wait.
+     */
+    generate(request: LlmRequest): Promise<LlmHandle>;
+    /**
+     * The models this plugin can be asked for, for a console drawing a list and
+     * for the host deciding whether it may send tools.
+     *
+     * Optional, like `listVoices` on the speech capability. But note what absent
+     * costs: the host has no way to learn that any model here supports tools, so
+     * it sends none. A plugin that wants tool calling has to describe itself.
+     */
+    listModels?(): Promise<LlmModelInfo[]>;
+}
+/**
+ * Drain a handle and answer with the finished result.
+ *
+ * The ordinary way to use {@link LlmPluginInstance.generate} when the caller
+ * wants the answer rather than the words as they arrive. Streaming still happens
+ * underneath, so the host's slot is still released at the right moment; what this
+ * removes is the chance of awaiting {@link LlmHandle.result} without draining
+ * {@link LlmHandle.text} first.
+ *
+ * A free function rather than a method, following `jsonBody` and `tryJsonBody`:
+ * it keeps the handle the platform's own shape, and it is nothing a plugin should
+ * have to implement.
+ *
+ * Pass a `signal` to stop early. The drain is raced against it and the stream is
+ * cancelled, which — per {@link LlmHandle.text} — is what asks the plugin to stop
+ * generating. Without one this waits for the model however long it takes, which is
+ * right for a caller that has nothing better to do and wrong for one holding a
+ * slot something with a deadline is queued for.
+ */
+export declare function collectGeneration(handle: LlmHandle, signal?: AbortSignal): Promise<LlmResult>;
+//# sourceMappingURL=llm.d.ts.map

package/dist/capabilities/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/capabilities/llm.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/mixer.d.ts

@@ -0,0 +1,183 @@
+/**
+ * The `mixer` capability. A mixer plugin takes several pieces of audio and
+ * answers with one.
+ *
+ * ## Why this is not the analysis capability
+ *
+ * It was, for one commit, as an optional `joinAudio` method on
+ * {@link AnalysisProvider}. The argument was that joining and measuring are the
+ * same work seen from the other end: both need decoded PCM, which is the one
+ * thing this tree does not do in Node, so both want the same adapter over the
+ * same program. **That argument is about the ADAPTER and it is still true** —
+ * the bundled plugin declares both capabilities and serves them off one sidecar
+ * with one address.
+ *
+ * It is not an argument about the CONTRACT, because a capability here is the unit
+ * of SELECTION rather than the unit of implementation. The host picks one plugin
+ * per capability, so a joiner reached through the analysis pick is whichever
+ * plugin the operator chose to MEASURE with: install a second analyzer that
+ * measures better and cannot join, name it, and the station stops joining with
+ * one log line, and the only fix is to select a worse analyzer. Filtering the
+ * analysis candidates on the method instead would produce a second, disagreeing
+ * pick under one key, which is exactly the failure the host's plugin selection
+ * exists to prevent.
+ *
+ * So there are two keys. A station may measure with one engine and mix with
+ * another, and a plugin that only mixes — a filter-graph adapter with no detector
+ * in it — is a valid installation rather than an unexpressible one.
+ *
+ * ## The plugin is an adapter, not a mixer
+ *
+ * {@link AnalysisProvider}'s note applies here word for word and for the same
+ * reason: joining needs decoded PCM, and the expected implementation is a thin
+ * adapter over a separate program. Nothing here requires that shape.
+ *
+ * Every shape here is JSON-safe except {@link JoinedAudio}, which carries a live
+ * stream deliberately. Offsets and durations are integer milliseconds.
+ */
+import type { PluginLifecycle } from '../plugin.lifecycle.js';
+/**
+ * Several pieces of audio to be made into one.
+ *
+ * The station's own use is a production: a phone-in or a podcast is written one
+ * beat at a time, because a beat is one model call in one voice, and joining the
+ * beats once they exist is what lets the programme air as ONE item with a pause
+ * between turns that somebody chose. See {@link MixerProvider.join}.
+ */
+export interface AudioJoin {
+    /**
+     * The parts, in the order they are to be heard.
+     *
+     * Each URL is complete and fetchable exactly as an analysis `audioUrl` is,
+     * and carries whatever authentication it needs. It has to be reachable from
+     * wherever the joining happens, which is not necessarily where this plugin
+     * runs.
+     */
+    parts: Array<{
+        url: string;
+    }>;
+    /**
+     * How much silence to put BETWEEN the parts, in milliseconds.
+     *
+     * Between, and never at the ends: what comes back is one item in a running
+     * order, and padding its head or tail is dead air at a boundary somebody
+     * else already trims.
+     */
+    gapMs: number;
+    /**
+     * Take each part's own leading and trailing silence off before joining.
+     *
+     * Absent means yes, because it is what makes {@link gapMs} mean anything: a
+     * gap between two untrimmed parts is that gap plus two unknowns that move
+     * with the voice and with the line. Set it false only where the parts are
+     * known to be tight already and their exact lengths matter.
+     */
+    trim?: boolean;
+    /**
+     * Sounds mixed ON the joined parts rather than placed between them.
+     *
+     * Absent is the ordinary join, and every caller that sends none gets exactly
+     * what it got before this field existed.
+     *
+     * The difference from a part is that **nothing moves**. A part pushes
+     * everything after it later; an overlay happens at the same time as what is
+     * already there, so the words either side of a drop keep the timing they were
+     * spoken with. That is the difference between a presenter landing a joke and
+     * one waiting politely for their own sentence to finish.
+     */
+    overlays?: AudioOverlay[];
+}
+/**
+ * One sound to mix onto a join.
+ *
+ * Anchored to a JOIN rather than to a timestamp, which is the one design decision
+ * here. A caller knows which boundary it means — after the setup, before the
+ * punchline — and does not know how long the parts will come out, because that is
+ * a fact about audio it has not decoded. Naming the boundary lets whatever IS
+ * decoding resolve it in samples.
+ */
+export interface AudioOverlay {
+    /** Complete and fetchable exactly as a part's url is. */
+    url: string;
+    /**
+     * Which join this sits at: `0` is the boundary after the first part.
+     *
+     * A join that does not exist is an ERROR rather than a nudge to the nearest
+     * one. An implementation that quietly moved it would put a sound somewhere
+     * nobody asked for and say nothing about having done so.
+     */
+    afterIndex: number;
+    /**
+     * How far either side of that boundary to start it, in milliseconds.
+     *
+     * Zero is exactly on it. **Negative pulls the sound earlier**, under the tail
+     * of what came before, which is what this whole field exists for.
+     */
+    offsetMs?: number;
+    /** What to do to the sound itself, in decibels. Absent leaves it alone. */
+    gainDb?: number;
+    /**
+     * How far to pull DOWN what is underneath, in decibels, for this overlay's
+     * span alone.
+     *
+     * The span rather than the whole join, because turning the speech down for a
+     * two-second drop is not the same request as turning the break down. Applied
+     * before the sum, or the duck would pull down the very sound it made room for.
+     */
+    duckDb?: number;
+}
+/**
+ * The joined audio, and what it is.
+ *
+ * `SpeechHandle`'s shape, deliberately and for its reasons: `mime` is what the
+ * host stores and serves the bytes under, and the audio is a stream so a whole
+ * programme is never held in memory on either side of the call.
+ */
+export interface JoinedAudio {
+    /**
+     * What the bytes ARE, as a media type (`audio/flac`).
+     *
+     * Load-bearing rather than decoration, exactly as it is for speech: both
+     * consumers of station audio go by the header rather than by the bytes, so a
+     * flac announced as `audio/wav` fails as silence rather than as an error.
+     */
+    mime: string;
+    /** The audio. The host reads it to the end or cancels it. */
+    audio: ReadableStream<Uint8Array>;
+    /**
+     * How long the result runs, if the joiner can say.
+     *
+     * Worth reporting because whatever just did the joining has already seen
+     * every sample, and a host that has to learn this some other way is a second
+     * decode of something it just received. Absent is fine.
+     */
+    durationMs?: number;
+}
+/** A plugin that can make one piece of audio out of several. */
+export interface MixerProvider extends PluginLifecycle {
+    /**
+     * Join several pieces of audio into one.
+     *
+     * **Required, where it was optional as `analyzeTrack`'s neighbour.** It was
+     * optional because it was a bolt-on to a capability that meant something
+     * else, and a plugin that declared `analysis` and could not join was the
+     * ordinary case. A plugin that declares THIS capability and cannot mix is not
+     * a state worth being able to express, so the host's "declared and
+     * implemented" check covers it like any other capability's one method.
+     *
+     * A station with no mixer at all is still an ordinary state rather than a
+     * fault: a production whose beats cannot be joined airs as a block of beats,
+     * which is what it did before anything could join them.
+     *
+     * Expect minutes rather than seconds — decoding several parts is not a
+     * request, it is a job — but honour `host.signal` all the same, because a
+     * station shutting down should not wait on a programme nobody will hear.
+     *
+     * @throws {PluginError} `config` when the plugin is not set up enough to try,
+     *   `upstream` when a part could not be fetched or decoded, `unsupported`
+     *   when whatever is behind this plugin cannot join what it was given,
+     *   `timeout` when it did not answer.
+     */
+    join(request: AudioJoin): Promise<JoinedAudio>;
+}
+//# sourceMappingURL=mixer.d.ts.map

package/dist/capabilities/mixer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mixer.d.ts","sourceRoot":"","sources":["../../src/capabilities/mixer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACtB;;;;;;;OAOG;IACH,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE9B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IACzB,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IACxB;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb,6DAA6D;IAC7D,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAElC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAc,SAAQ,eAAe;IAClD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAClD"}