@komaa/standin-sdk 0.1.0

package/dist/protocol.js

@@ -0,0 +1,77 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+// GENERATED from protocol/schema.yaml; do not hand-edit.
+// Schema SHA-256: 9157d78287022cc97566640007ea61c5336cb11c731ba5fcb15b0833b8048d5b
+// Regenerate with: python3 protocol/generate.py
+import { clean, normalizePongTimestamp } from "./protocolRuntime.js";
+export { contextSentences, decodePcm, parseMessage } from "./protocolRuntime.js";
+export const SAMPLE_RATE_HZ = 16_000;
+export const NUM_CHANNELS = 1;
+export const TYPE_SESSION_START = "session.start";
+export const TYPE_SESSION_END = "session.end";
+export const TYPE_RECORDING_STATUS = "recording.status";
+export const TYPE_AUDIO_FRAME = "audio.frame";
+export const TYPE_VIDEO_FRAME = "video.frame";
+export const TYPE_PARTICIPANTS = "participants";
+export const TYPE_DTMF = "dtmf";
+export const TYPE_PING = "ping";
+export const TYPE_ASSISTANT_SAY = "assistant.say";
+export const TYPE_ASSISTANT_CANCEL = "assistant.cancel";
+export const TYPE_EXPRESSION = "expression";
+export const TYPE_SPEECH_MARKS = "speech.marks";
+export const TYPE_DISPLAY_IMAGE = "display.image";
+export const TYPE_DISPLAY_FRAME = "display.frame";
+export const TYPE_PONG = "pong";
+/** Read call context; only callId lacks a safe default. */
+export function parseSessionStart(msg) {
+    const callId = clean(msg.callId);
+    if (!callId)
+        throw new Error("session.start is missing callId");
+    const rawCaller = msg.caller;
+    const callerObj = typeof rawCaller === "object" && rawCaller !== null && !Array.isArray(rawCaller)
+        ? rawCaller : {};
+    const direction = clean(msg.direction) ?? "inbound";
+    return {
+        callId: callId,
+        threadId: clean(msg.threadId) ?? "",
+        caller: {
+            aadId: clean(callerObj.aadId),
+            displayName: clean(callerObj.displayName),
+            tenantId: clean(callerObj.tenantId),
+        },
+        direction: direction === "inbound" || direction === "outbound" ? direction : "inbound",
+        recordingStatus: clean(msg.recordingStatus),
+        tenantId: clean(msg.tenantId),
+    };
+}
+/** Build an outbound `audio.frame` JSON frame. */
+export function audioFrame(seq, timestampMs, pcm) {
+    return JSON.stringify({
+        type: TYPE_AUDIO_FRAME,
+        seq: seq,
+        timestampMs: timestampMs,
+        payloadBase64: pcm.toString("base64"),
+    });
+}
+/** Build an outbound `pong` JSON frame. */
+export function pong(ts) {
+    return JSON.stringify({
+        type: TYPE_PONG,
+        ts: normalizePongTimestamp(ts),
+    });
+}
+/** Build an outbound `assistant.cancel` JSON frame. */
+export function assistantCancel(turnId) {
+    return JSON.stringify({
+        type: TYPE_ASSISTANT_CANCEL,
+        turnId: turnId,
+    });
+}
+/** Build an outbound `session.end` JSON frame. */
+export function sessionEnd(reason) {
+    return JSON.stringify({
+        type: TYPE_SESSION_END,
+        reason: reason,
+    });
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

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

package/dist/protocolRuntime.d.ts

@@ -0,0 +1,19 @@
+/** Read blank strings and non-string identity fields as absent. */
+export declare function clean(value: unknown): string | undefined;
+/** Drop malformed JSON while preserving unknown message types for the receive loop. */
+export declare function parseMessage(raw: string | Buffer): Record<string, unknown> | undefined;
+/** Decode canonical standard base64 containing complete, nonempty PCM16 samples. */
+export declare function decodePcm(payloadBase64: unknown): Buffer;
+/** Encode raw PCM bytes using canonical standard base64. */
+export declare function encodePcm(pcm: Buffer): string;
+/** Serialize an outbound message as compact JSON. */
+export declare function encode(message: Record<string, unknown>): string;
+/** Echo safe integer timestamps, using zero for malformed or imprecise values. */
+export declare function normalizePongTimestamp(value: unknown): number;
+/** The exact context sentences presented to agents by both SDKs. */
+export declare const contextSentences: {
+    readonly participants: (count: number) => string;
+    readonly dtmf: (digit: string) => string;
+    readonly recording: (status: string) => string;
+};
+//# sourceMappingURL=protocolRuntime.d.ts.map

package/dist/protocolRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocolRuntime.d.ts","sourceRoot":"","sources":["../src/protocolRuntime.ts"],"names":[],"mappings":"AAQA,mEAAmE;AACnE,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGxD;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,GAAG,MAAM,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAkBrC;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,aAAa,EAAE,OAAO,GAAG,MAAM,CAiBxD;AAED,4DAA4D;AAC5D,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,qDAAqD;AACrD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAE/D;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7D;AAED,oEAAoE;AACpE,eAAO,MAAM,gBAAgB;mCACP,MAAM,KAAG,MAAM;2BAMvB,MAAM,KAAG,MAAM;iCAGT,MAAM,KAAG,MAAM;CAKzB,CAAC"}

package/dist/protocolRuntime.js

@@ -0,0 +1,78 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+/** Runtime helpers shared by the generated StandIn call protocol bindings. */
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/** Read blank strings and non-string identity fields as absent. */
+export function clean(value) {
+    if (typeof value !== "string")
+        return undefined;
+    return value.trim() || undefined;
+}
+/** Drop malformed JSON while preserving unknown message types for the receive loop. */
+export function parseMessage(raw) {
+    let obj;
+    try {
+        const text = typeof raw === "string"
+            ? raw
+            : new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw);
+        obj = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof obj !== "object" || obj === null || Array.isArray(obj))
+        return undefined;
+    const rec = obj;
+    if (typeof rec.type !== "string")
+        return undefined;
+    return rec;
+}
+/** Decode canonical standard base64 containing complete, nonempty PCM16 samples. */
+export function decodePcm(payloadBase64) {
+    if (typeof payloadBase64 !== "string" || payloadBase64 === "") {
+        throw new Error("audio.frame carries no payloadBase64");
+    }
+    if (!BASE64.test(payloadBase64)) {
+        throw new Error("audio.frame payloadBase64 is not valid base64");
+    }
+    const pcm = Buffer.from(payloadBase64, "base64");
+    // Buffer's decoder tolerates invalid padding and nonzero padding bits.
+    // Require the same canonical representation as the Python runtime.
+    if (encodePcm(pcm) !== payloadBase64) {
+        throw new Error("audio.frame payloadBase64 is not valid base64");
+    }
+    if (pcm.length < 2 || pcm.length % 2 !== 0) {
+        throw new Error(`malformed PCM16 payload (${pcm.length} bytes)`);
+    }
+    return pcm;
+}
+/** Encode raw PCM bytes using canonical standard base64. */
+export function encodePcm(pcm) {
+    return pcm.toString("base64");
+}
+/** Serialize an outbound message as compact JSON. */
+export function encode(message) {
+    return JSON.stringify(message);
+}
+/** Echo safe integer timestamps, using zero for malformed or imprecise values. */
+export function normalizePongTimestamp(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) ? value : 0;
+}
+/** The exact context sentences presented to agents by both SDKs. */
+export const contextSentences = {
+    participants(count) {
+        return count <= 1
+            ? "This is a 1:1 call with a single human caller."
+            : `There are ${count} human participants on this call. ` +
+                "Stay quiet unless directly addressed.";
+    },
+    dtmf(digit) {
+        return `The caller pressed the "${digit}" key on their keypad.`;
+    },
+    recording(status) {
+        return status === "active"
+            ? "The Microsoft Teams call recording is now ACTIVE."
+            : "The Microsoft Teams call recording is not active.";
+    },
+};
+//# sourceMappingURL=protocolRuntime.js.map

package/dist/protocolRuntime.js.map

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

package/dist/smoke.d.ts

@@ -0,0 +1,65 @@
+import type { HandlerFactory } from "./handler.js";
+/** PCM16 mono at 16 kHz for 20 ms. The cadence a real call arrives at. */
+export declare const FRAME_MS = 20;
+export declare const FRAME_BYTES: number;
+/**
+ * How long the whole run may take before it is a recorded failure rather than a
+ * hang. A listener that accepts and then stops talking would otherwise hang CI,
+ * and hang a status tool call for ever.
+ */
+export declare const RUN_TIMEOUT_MS = 15000;
+export declare const CONNECT_TIMEOUT_MS = 5000;
+/** One thing that either works here or does not. */
+export interface SmokeCheck {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly detail?: string;
+    /**
+     * What stops working when this fails. A report that names the missing surface
+     * without naming the consequence sends the operator to the source.
+     */
+    readonly cost?: string;
+    /**
+     * Whether `ok` depends on it. Counted by default, so a check a plugin adds
+     * counts unless it passes `required: false`.
+     */
+    readonly required?: boolean;
+}
+/** What the run found. */
+export interface SmokeResult {
+    readonly checks: SmokeCheck[];
+    readonly echoFrames: number;
+    readonly error?: string;
+    /**
+     * True only when every mandatory check passed.
+     *
+     * Never true when nothing echoed: the point of the run is that audio made the
+     * round trip, and a run that proves nothing must not read as a pass.
+     */
+    readonly ok: boolean;
+}
+/**
+ * A client that speaks the call wire, for one call that nobody is on.
+ *
+ * Used by {@link runSmoke}. Exported because a plugin with its own listener may
+ * want to point one at it.
+ */
+export declare class SyntheticCall {
+    #private;
+    echoFrames: number;
+    constructor(url: string, secret: string, callId: string, frames?: number, connectTimeoutMs?: number);
+    /** Connect, greet, stream, hang up. Rejects on anything that fails. */
+    run(): Promise<void>;
+}
+/** Extra checks a plugin runs after the call. */
+export type ExtraChecks = () => Promise<SmokeCheck[]>;
+/**
+ * Ring this worker's own handler and report what worked.
+ *
+ * `extra` is a plugin's own checks, run after the call. Each one counts
+ * towards `ok` unless it says `required: false`.
+ */
+export declare function runSmoke(handlerFactory: HandlerFactory, frames?: number, extra?: ExtraChecks, timeoutMs?: number): Promise<SmokeResult>;
+/** The result as something to print. */
+export declare function report(result: SmokeResult): string;
+//# sourceMappingURL=smoke.d.ts.map

package/dist/smoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smoke.d.ts","sourceRoot":"","sources":["../src/smoke.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AASnD,0EAA0E;AAC1E,eAAO,MAAM,QAAQ,KAAK,CAAC;AAC3B,eAAO,MAAM,WAAW,QAAmC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAS,CAAC;AACrC,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AAExC,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,0BAA0B;AAC1B,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,qBAAa,aAAa;;IACxB,UAAU,SAAK;gBAQb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,SAAK,EACX,gBAAgB,SAAqB;IASvC,uEAAuE;IACjE,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CAmF3B;AAED,iDAAiD;AACjD,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,cAAc,EAAE,cAAc,EAC9B,MAAM,SAAK,EACX,KAAK,CAAC,EAAE,WAAW,EACnB,SAAS,SAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAwGtB;AAED,wCAAwC;AACxC,wBAAgB,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAWlD"}

package/dist/smoke.js

@@ -0,0 +1,293 @@
+// Copyright (c) 2026 Komaa DigiTech
+// SPDX-License-Identifier: MIT
+/**
+ * Proving an install works, without a bill, a tunnel or a Microsoft tenant.
+ *
+ * The question every plugin has to answer before anybody trusts it with a real
+ * call is "does this actually work here?", and until now the only way to find
+ * out was to place a real call: a provider bill, a public tunnel, a Teams
+ * tenant and somebody's afternoon.
+ *
+ * So this rings the worker itself. It binds an ephemeral listener on loopback,
+ * connects a real client that speaks the real call wire, streams a few frames
+ * of silence, and reports what came back. Everything it exercises is the thing
+ * that breaks in the field: the secret, the bind, the handshake, the session,
+ * and whether audio makes the round trip.
+ *
+ * The client lives next to the wire it speaks, deliberately. A copy of it kept
+ * in a plugin drifts, and the copy that used to exist kept passing against a
+ * path that no longer existed, which is exactly the failure a smoke check is
+ * for.
+ *
+ * **Nothing that delivers is started.** No pending-message sweep, no no-answer
+ * reaper, no outbound caller, no chat lane. A verification command that quietly
+ * resumed durable jobs would place real calls and post real messages as a side
+ * effect of somebody typing `smoke`, which is the single worst thing this could
+ * possibly do.
+ *
+ * Identical in shape to the Python SDK's `standin.smoke`.
+ */
+import { randomBytes } from "node:crypto";
+import WebSocket from "ws";
+import { CallServer } from "./callServer.js";
+import { SIGNATURE_HEADER, TIMESTAMP_HEADER, nowMs, signHandshake, } from "./hmac.js";
+import { logger } from "./log.js";
+/** PCM16 mono at 16 kHz for 20 ms. The cadence a real call arrives at. */
+export const FRAME_MS = 20;
+export const FRAME_BYTES = ((16_000 * FRAME_MS) / 1000) * 2;
+/**
+ * How long the whole run may take before it is a recorded failure rather than a
+ * hang. A listener that accepts and then stops talking would otherwise hang CI,
+ * and hang a status tool call for ever.
+ */
+export const RUN_TIMEOUT_MS = 15_000;
+export const CONNECT_TIMEOUT_MS = 5_000;
+/**
+ * A client that speaks the call wire, for one call that nobody is on.
+ *
+ * Used by {@link runSmoke}. Exported because a plugin with its own listener may
+ * want to point one at it.
+ */
+export class SyntheticCall {
+    echoFrames = 0;
+    #url;
+    #secret;
+    #callId;
+    #frames;
+    #connectTimeoutMs;
+    constructor(url, secret, callId, frames = 10, connectTimeoutMs = CONNECT_TIMEOUT_MS) {
+        this.#url = url;
+        this.#secret = secret;
+        this.#callId = callId;
+        this.#frames = Math.max(1, frames);
+        this.#connectTimeoutMs = connectTimeoutMs;
+    }
+    /** Connect, greet, stream, hang up. Rejects on anything that fails. */
+    async run() {
+        // Signed freshly for this connect. The listener enforces single use inside
+        // the freshness window, so a retry that reused these headers would loop on
+        // 401 and read as a wrong secret.
+        const stamp = nowMs();
+        const ws = new WebSocket(this.#url, {
+            headers: {
+                [TIMESTAMP_HEADER]: String(stamp),
+                [SIGNATURE_HEADER]: signHandshake(this.#secret, stamp, this.#callId),
+            },
+            handshakeTimeout: this.#connectTimeoutMs,
+        });
+        ws.on("message", (data) => {
+            try {
+                if (JSON.parse(String(data)).type === "audio.frame")
+                    this.echoFrames += 1;
+            }
+            catch {
+                // Not ours to interpret. A frame this cannot read is not an echo.
+            }
+        });
+        try {
+            await new Promise((resolve, reject) => {
+                ws.once("open", resolve);
+                ws.once("error", reject);
+                ws.once("close", (code) => reject(new Error(`the socket closed with ${code}`)));
+            });
+            ws.removeAllListeners("close");
+            ws.removeAllListeners("error");
+            let closed = "";
+            ws.on("close", (code) => {
+                closed = `the socket closed with ${code}`;
+            });
+            ws.on("error", (err) => {
+                closed = String(err);
+            });
+            ws.send(JSON.stringify({
+                type: "session.start",
+                // Identical to the id in the path. The listener refuses a start that
+                // disagrees with the authenticated path, and the refusal would read
+                // as a wire fault.
+                callId: this.#callId,
+                threadId: "",
+                direction: "inbound",
+                caller: { displayName: "StandIn smoke check" },
+            }));
+            // Handlers commonly gate output on the call being recorded, so without
+            // this a recording-gated handler stays silent and the run reports a false
+            // negative.
+            ws.send(JSON.stringify({ type: "recording.status", status: "active" }));
+            const silence = Buffer.alloc(FRAME_BYTES).toString("base64");
+            for (let seq = 0; seq < this.#frames; seq += 1) {
+                if (closed !== "")
+                    throw new Error(closed);
+                ws.send(JSON.stringify({
+                    type: "audio.frame",
+                    seq,
+                    timestampMs: seq * FRAME_MS,
+                    payloadBase64: silence,
+                }));
+                await new Promise((resolve) => setTimeout(resolve, FRAME_MS));
+            }
+            ws.send(JSON.stringify({ type: "session.end", reason: "smoke-done" }));
+            // One cadence beat for whatever the handler said last to arrive.
+            await new Promise((resolve) => setTimeout(resolve, FRAME_MS * 2));
+        }
+        finally {
+            // On every path. An error path that skipped this leaks a socket per run
+            // inside a long-lived host that exposes the check.
+            try {
+                ws.close();
+            }
+            catch {
+                // Never connected, or already gone.
+            }
+        }
+    }
+}
+/**
+ * Ring this worker's own handler and report what worked.
+ *
+ * `extra` is a plugin's own checks, run after the call. Each one counts
+ * towards `ok` unless it says `required: false`.
+ */
+export async function runSmoke(handlerFactory, frames = 10, extra, timeoutMs = RUN_TIMEOUT_MS) {
+    const checks = [];
+    let error = "";
+    let echoFrames = 0;
+    // Its own credential, never the operator's. A fixed string would be a
+    // predictable one on a live listener, and borrowing the operator's makes the
+    // run pass or fail for reasons that have nothing to do with the wire. It also
+    // makes the check runnable before the secret is configured, which is exactly
+    // when people run it.
+    const secret = randomBytes(16).toString("hex");
+    checks.push({
+        name: "secret",
+        ok: true,
+        detail: "generated for this run",
+        cost: "nothing could authenticate",
+    });
+    const server = new CallServer({
+        handlerFactory,
+        secret,
+        host: "127.0.0.1",
+        port: 0,
+        staleCallReaperMs: 0,
+    });
+    try {
+        await server.start();
+    }
+    catch (err) {
+        return finish(checks, 0, String(err), [
+            {
+                name: "listener",
+                ok: false,
+                detail: String(err),
+                cost: "no call could ever reach this worker",
+            },
+        ]);
+    }
+    checks.push({
+        name: "listener",
+        ok: true,
+        detail: `127.0.0.1:${server.port}${server.wsPath}`,
+        cost: "no call could ever reach this worker",
+    });
+    const callId = `smoke-${randomBytes(4).toString("hex")}`;
+    const url = `ws://127.0.0.1:${server.port}${server.wsPath}/${callId}`;
+    const call = new SyntheticCall(url, secret, callId, frames);
+    const started = Date.now();
+    try {
+        await withTimeout(call.run(), timeoutMs);
+        checks.push({
+            name: "call",
+            ok: true,
+            detail: `${frames} frames in ${Date.now() - started} ms`,
+            cost: "calls do not connect",
+        });
+    }
+    catch (err) {
+        const timedOut = err === TIMED_OUT;
+        error = timedOut
+            ? `the call did not finish within ${timeoutMs} ms`
+            : String(err);
+        checks.push({
+            name: "call",
+            ok: false,
+            detail: error,
+            // A hang and a refusal are different things to go and look at, so they
+            // are told apart here rather than both reading as "it did not work".
+            cost: timedOut
+                ? "a real call would hang the same way"
+                : "a real call would fail the same way",
+        });
+    }
+    finally {
+        try {
+            await server.aclose();
+        }
+        catch {
+            // Already down. Nothing to report about a teardown nobody waited on.
+        }
+    }
+    echoFrames = call.echoFrames;
+    checks.push({
+        name: "audio",
+        ok: echoFrames > 0,
+        detail: `${echoFrames} frames came back`,
+        cost: "the caller would hear nothing",
+    });
+    if (extra !== undefined) {
+        try {
+            checks.push(...(await extra()));
+        }
+        catch (err) {
+            logger.debug(`standin: a plugin smoke check failed: ${String(err)}`);
+            // Advisory: the plugin's own checks failing to RUN says nothing about
+            // whether a call works, which is what this command answers.
+            checks.push({
+                name: "plugin checks",
+                ok: false,
+                detail: String(err),
+                cost: "this plugin's own checks did not run",
+                required: false,
+            });
+        }
+    }
+    return finish(checks, echoFrames, error);
+}
+/** The result as something to print. */
+export function report(result) {
+    const lines = [`standin: ${result.ok ? "ok" : "NOT ok"}`];
+    for (const check of result.checks) {
+        const mark = check.ok ? "ok  " : "FAIL";
+        lines.push(`  ${mark} ${check.name}${check.detail ? ` (${check.detail})` : ""}`);
+        if (!check.ok && check.cost)
+            lines.push(`       without it: ${check.cost}`);
+    }
+    if (result.error)
+        lines.push(`  error: ${result.error}`);
+    return lines.join("\n");
+}
+function finish(checks, echoFrames, error, extra = []) {
+    const all = [...checks, ...extra];
+    return {
+        checks: all,
+        echoFrames,
+        error: error || undefined,
+        ok: all.every((check) => check.required === false || check.ok),
+    };
+}
+const TIMED_OUT = Symbol("standin.smokeTimeout");
+async function withTimeout(work, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(TIMED_OUT), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=smoke.js.map

package/dist/smoke.js.map

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

package/dist/startup.d.ts

@@ -0,0 +1,74 @@
+/**
+ * What arrived before your agent was ready to hear it.
+ *
+ * A call starts the moment StandIn dials. Your agent starts a little later: a
+ * socket has to open, a room has to be joined, a session has to be configured.
+ * Everything the caller does in that gap still arrives, and if nothing holds it,
+ * it is gone.
+ *
+ * Two things arrive in that gap and both matter:
+ *
+ * **The caller's first words.** People start talking the instant the call
+ * connects, and often the first thing they say is the reason they called. Drop
+ * it and the agent opens by asking a question that was already answered.
+ *
+ * **The first context.** The "there are three people here, stay quiet unless
+ * addressed" sentence and the recording-status change both land within the first
+ * moment of a meeting. Drop those and a group-call gate never engages and a
+ * recording gate never opens.
+ *
+ * This exists because every plugin was solving half of it. Of the nine plugins
+ * in this SDK, two held both, and five held one and silently lost the other.
+ *
+ * Bounded on purpose. A socket that never opens must not grow a buffer for the
+ * length of the call, so the oldest entries are dropped rather than the newest.
+ *
+ * Identical in shape to the Python SDK's `standin.startup`.
+ */
+/**
+ * About four seconds of speech at the wire's frame size. Enough to hold an
+ * opening sentence, far short of enough to hide a socket that never opened.
+ */
+export declare const MAX_PENDING_AUDIO = 200;
+/** Context sentences are rare and each one is small. This is generous. */
+export declare const MAX_PENDING_CONTEXT = 20;
+/**
+ * Holds caller audio and call context until the agent can take them.
+ *
+ * Order is preserved within each lane, and audio is released before context,
+ * because the provider needs the caller's words in the order they were said and
+ * the context is a note about the call rather than part of the conversation.
+ */
+export declare class StartupBuffer {
+    #private;
+    constructor(maxAudio?: number, maxContext?: number);
+    /** Whether the agent is still being set up. */
+    get holding(): boolean;
+    /**
+     * How much was lost to the bounds.
+     *
+     * Worth logging when it is not zero: it means the agent took long enough to
+     * start that the caller outran it.
+     */
+    get dropped(): {
+        audio: number;
+        context: number;
+    };
+    /** Hold one frame of the caller's voice. */
+    audio(pcm: Buffer): void;
+    /** Hold one line of call context. */
+    context(text: string): void;
+    /**
+     * Hand everything over, in order, and stop holding.
+     *
+     * Both callbacks may be sync or async, because a provider's send is often
+     * fire-and-forget. Safe to call twice: the second call releases nothing.
+     */
+    release(sendAudio?: (pcm: Buffer) => void | Promise<void>, sendContext?: (text: string) => void | Promise<void>): Promise<{
+        audio: number;
+        context: number;
+    }>;
+    /** Throw it away. For a call that ended before the agent was ready. */
+    discard(): void;
+}
+//# sourceMappingURL=startup.d.ts.map

package/dist/startup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup.d.ts","sourceRoot":"","sources":["../src/startup.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;GAMG;AACH,qBAAa,aAAa;;gBASZ,QAAQ,SAAoB,EAAE,UAAU,SAAsB;IAK1E,+CAA+C;IAC/C,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;OAKG;IACH,IAAI,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAEhD;IAED,4CAA4C;IAC5C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IASxB,qCAAqC;IACrC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAS3B;;;;;OAKG;IACG,OAAO,CACX,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EACjD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACnD,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAS9C,uEAAuE;IACvE,OAAO,IAAI,IAAI;CAKhB"}