pinecall 0.1.0

package/dist/cli/knowledge.js

@@ -0,0 +1,174 @@
+/** `pinecall knowledge push | list | drop | eval`: the base the agent answers from, and what a golden says of it. */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { slugOf } from "../runtime/connect.js";
+import { theDoor } from "./env.js";
+import { load } from "./load.js";
+import { asked } from "./testing/gateway.js";
+import { refusal } from "./whoami.js";
+const USAGE = `usage: pinecall knowledge push [dir] [--base <name>] [--file agent.tsx]
+       pinecall knowledge list
+       pinecall knowledge drop <base>
+       pinecall knowledge eval [golden.json] [--base <name>] [--k <n>] [--file agent.tsx]`;
+/** Where a base is refused before a byte is sent: the three sentences both doors say. */
+export const NO_DIRECTORY = (directory) => `no knowledge directory at ${directory}`;
+export const NO_MARKDOWN = (directory) => `no *.md under ${directory}: nothing to push`;
+export const NO_GOLDEN = (golden) => `no golden at ${golden}: a JSON list of {asks, expects}`;
+export const AN_EMPTY_GOLDEN = (golden) => `${golden} holds no questions: a golden is a JSON list of {asks, expects}`;
+// The golden beside the documents it asks about: the questions the base is held to, and the chunk
+// each should have found. `knowledge/golden.json` is where `eval` looks when nobody says.
+export const DEFAULT_GOLDEN = "knowledge/golden.json";
+// Where a tenant keeps what is retrieved per turn, beside the agent file: the layout every
+// example has, and the one `docs = "<base>"` on the class was pushed from.
+export const DEFAULT_DIR = "knowledge/docs";
+export const group = {
+    purpose: "push | list | drop the knowledge base the agent answers from",
+    usage: `${USAGE}
+
+  push reads every *.md under the directory (./knowledge/docs beside the agent file when none
+  is named) and sends the folder whole to PUT /v1/knowledge/<base>: the base is replaced, never
+  merged. The base is the agent's slug unless --base says otherwise, and the class names it with
+  \`docs = "<base>"\`. list prints every base this org has pushed; drop removes one.
+
+  eval asks the base every question of a golden — a JSON list of {asks, expects}, where expects is
+  the heading path the answer should carry — and prints recall@k and nDCG@10, computed by code with
+  no model in the loop, plus every question it missed and what came back instead. A golden is fixed
+  and the index is the variable: never soften a question so a change can pass.`,
+    run,
+};
+/** Read the sub-verb and do it: the folder to the gateway, the list off it, or one base gone. */
+export async function run(argv, how = {}) {
+    const out = how.out ?? process.stdout;
+    const err = how.err ?? process.stderr;
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { base: { type: "string" }, file: { type: "string" }, k: { type: "string" } },
+    });
+    const [verb, ...rest] = positionals;
+    const door = theDoor(how.env ?? process.env, err);
+    if (door === undefined)
+        return 2;
+    try {
+        if (verb === "push")
+            return await push(door, rest[0], values.base, values.file, out, err);
+        if (verb === "list")
+            return await list(door, out);
+        if (verb === "drop" && rest[0] !== undefined)
+            return await drop(door, rest[0], out);
+        if (verb === "eval")
+            return await evaluate(door, rest[0], values.base, values.k, values.file, out, err);
+    }
+    catch (refused) {
+        // The gateway's own sentence, as it was said: "this gateway keeps no knowledge: it runs on
+        // a dev key" names the fix, and nothing here knows better.
+        err.write(`${refusal(refused)}\n`);
+        return 1;
+    }
+    err.write(`${USAGE}\n`);
+    return 2;
+}
+// The folder as of now, whole. The directory and the base default to what the agent file says —
+// `./knowledge/docs` beside it and its slug — and the class is loaded only when one of the two is
+// missing, so a push that names both costs no TypeScript loader.
+async function push(door, dir, base, agent, out, err) {
+    const loaded = dir === undefined || base === undefined ? await load(agent) : undefined;
+    const directory = resolve(dir ?? join(dirname(loaded.file), DEFAULT_DIR));
+    const name = base ?? slugOf(loaded.ctor);
+    if (!existsSync(directory) || !statSync(directory).isDirectory()) {
+        err.write(`${NO_DIRECTORY(directory)}\n`);
+        return 2;
+    }
+    const files = markdownUnder(directory);
+    if (files.length === 0) {
+        err.write(`${NO_MARKDOWN(directory)}\n`);
+        return 2;
+    }
+    out.write(`${pushedLine(await pushedTo(door, name, files), files.length)}\n`);
+    return 0;
+}
+async function list(door, out) {
+    const answered = await asked(door, "/v1/knowledge");
+    if (answered.bases.length === 0) {
+        out.write(`no knowledge base pushed yet: pinecall knowledge push ./knowledge/docs --base <slug>\n`);
+        return 0;
+    }
+    for (const base of answered.bases) {
+        out.write(`${base.base} · ${base.chunks} chunks · pushed ${dayAndTime(base.pushed_at)}\n`);
+    }
+    return 0;
+}
+async function drop(door, base, out) {
+    await asked(door, `/v1/knowledge/${encodeURIComponent(base)}`, { method: "DELETE" });
+    out.write(`dropped ${base}\n`);
+    return 0;
+}
+// A golden is run when somebody changed the documents, the embedder or a knob — never on a
+// caller's clock — so it reads its questions off the disk and asks them one at a time.
+async function evaluate(door, file, base, k, agent, out, err) {
+    const loaded = file === undefined || base === undefined ? await load(agent) : undefined;
+    const golden = resolve(file ?? join(dirname(loaded.file), DEFAULT_GOLDEN));
+    const name = base ?? slugOf(loaded.ctor);
+    if (!existsSync(golden)) {
+        err.write(`${NO_GOLDEN(golden)}\n`);
+        return 2;
+    }
+    const questions = theQuestionsIn(golden);
+    if (questions === null) {
+        err.write(`${AN_EMPTY_GOLDEN(golden)}\n`);
+        return 2;
+    }
+    const score = await scoredOn(door, name, questions, k === undefined ? undefined : Number(k));
+    out.write(`${scoreLines(score).join("\n")}\n`);
+    return score.misses.length === 0 ? 0 : 1;
+}
+/** The folder, sent whole: the base is replaced and never merged. Both doors push through here. */
+export async function pushedTo(door, base, files) {
+    return await asked(door, `/v1/knowledge/${encodeURIComponent(base)}`, {
+        method: "PUT",
+        body: { files },
+    });
+}
+/** Every question of a golden asked of the base, and the two figures code computed from it. */
+export async function scoredOn(door, base, questions, k) {
+    return await asked(door, `/v1/knowledge/${encodeURIComponent(base)}/eval`, {
+        method: "POST",
+        body: { questions, ...(k === undefined ? {} : { k }) },
+    });
+}
+/** The questions a golden file holds, or nothing at all when it holds none. */
+export function theQuestionsIn(golden) {
+    const questions = JSON.parse(readFileSync(golden, "utf8"));
+    return Array.isArray(questions) && questions.length > 0 ? questions : null;
+}
+/** What a golden prints: the two figures on one line, then a line per question the base missed. */
+export function scoreLines(score) {
+    const figures = `${score.base} · ${score.model} · ${score.questions} questions · ` +
+        `recall@${score.k} ${score.recall_at_k.toFixed(2)} · nDCG@10 ${score.ndcg_at_10.toFixed(2)} · ` +
+        `${Math.round(score.took_ms)} ms`;
+    return [
+        figures,
+        ...score.misses.map((missed) => `  missed: ${missed.asks} → wanted ${missed.expects}, got ${missed.found[0] ?? "nothing"}`),
+    ];
+}
+/** The one line a push prints: the base, what was sent, what it became, and how long it took. */
+export function pushedLine(pushed, files) {
+    return `${pushed.base} · ${files} files · ${pushed.chunks} chunks · ${Math.round(pushed.took_ms)} ms`;
+}
+/** Every *.md under a directory, its subdirectories included, as the wire carries a file: its path relative to the directory, and its text. */
+export function markdownUnder(directory) {
+    const found = [];
+    for (const entry of readdirSync(directory, { recursive: true, withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        const path = join(entry.parentPath, entry.name);
+        found.push({ path: relative(directory, path).split(sep).join("/"), text: readFileSync(path, "utf8") });
+    }
+    return found.sort((one, other) => (one.path < other.path ? -1 : 1));
+}
+/** Unix seconds as a person reads them: the day and the minute, in UTC, no fractions. */
+export function dayAndTime(seconds) {
+    return new Date(seconds * 1000).toISOString().slice(0, 16).replace("T", " ");
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/cli/knowledge.js.map

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

package/dist/cli/line.d.ts

@@ -0,0 +1,33 @@
+/** `pinecall line`: whose terminal a call at this agent's number rings in, and the claim that takes it. */
+import type { TheLine } from "@pinecall/protocol";
+import type { Group } from "./groups.js";
+import { type Door } from "./testing/gateway.js";
+export declare const group: Group;
+export declare function run(argv: string[], out?: NodeJS.WritableStream): Promise<number>;
+/** Say which phone is yours: every call it makes reaches your own agent, in whatever you hold. */
+export declare function callsFrom(door: Door, number: string): Promise<{
+    calling: string[];
+}>;
+/** Stop answering your own calls: they fall back to whoever holds the line. */
+export declare function forgetCallsFrom(door: Door): Promise<{
+    forgot: string[];
+}>;
+/** What the terminal says back once a number is yours. */
+export declare function calling(numbers: string[]): string;
+/** And when they stop. A `forget` that forgot nothing says so rather than looking like it worked. */
+export declare function forgotten(numbers: string[]): string;
+/** Who is answering this agent's ringing doors right now. */
+export declare function theLine(door: Door, slug: string): Promise<TheLine>;
+/** Take it for this terminal, whoever had it. */
+export declare function claimed(door: Door, slug: string): Promise<TheLine>;
+/** Give it up: whoever else is still running the agent picks it up. */
+export declare function released(door: Door, slug: string): Promise<TheLine>;
+/**
+ * The line as a person reads it: where the ring lands, and the move that changes it.
+ *
+ * It never prints a member id. A person recognises a colleague by their email and nothing else,
+ * and a corner nobody is named in — the org's own key, CI's — is said as what it is rather than
+ * as a null.
+ */
+export declare function describing(said: TheLine): string;
+//# sourceMappingURL=line.d.ts.map

package/dist/cli/line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line.d.ts","sourceRoot":"","sources":["../../src/cli/line.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAE3G,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAIlD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAS,KAAK,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAQxD,eAAO,MAAM,KAAK,EAAE,KAkBnB,CAAC;AAIF,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAM,CAAC,cAA+B,GAAG,OAAO,CAAC,MAAM,CAAC,CAkCtG;AAED,kGAAkG;AAClG,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAE1F;AAED,+EAA+E;AAC/E,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAE/E;AAED,0DAA0D;AAC1D,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAIjD;AAED,qGAAqG;AACrG,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAInD;AAED,6DAA6D;AAC7D,wBAAsB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExE;AAED,iDAAiD;AACjD,wBAAsB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExE;AAED,uEAAuE;AACvE,wBAAsB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzE;AAUD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAWhD"}

package/dist/cli/line.js

@@ -0,0 +1,134 @@
+/** `pinecall line`: whose terminal a call at this agent's number rings in, and the claim that takes it. */
+import { callsFrom as keptOnTheProfile } from "./profiles.js";
+import { theDoor } from "./env.js";
+import { load } from "./load.js";
+import { slugOf } from "../runtime/connect.js";
+import { asked } from "./testing/gateway.js";
+const USAGE = "usage: pinecall line [from <+number> | forget | claim | release] [agent.tsx]";
+// A number exists once in a world, so it rings in one place. In production that place is the box
+// and there is nothing to decide; in the sandbox an org shares ONE number and three developers
+// may be running the same agent, so which terminal it rings in is claimed out loud. Alone nobody
+// claims anything — the first `pinecall run` takes it. See the runtime's docs/protocol/gateway-api.md.
+export const group = {
+    purpose: "whose terminal the sandbox number rings in",
+    usage: `${USAGE}
+
+  With nothing after it: who is answering this agent's number right now, and who else is running
+  it and could take it.
+
+  \`from <+number>\` is the one you want. Say which phone is YOURS, once, and every call you make
+  to a sandbox number reaches your own agent — no claim, no coordination, and three of you
+  testing at the same time. It is remembered for this gateway and re-sent by every
+  \`pinecall run\`. \`forget\` undoes it.
+
+  \`claim\` and \`release\` are the fallback, for a call from a number nobody said was theirs — a
+  customer, a colleague's phone. The first terminal to hold the agent has it; alone, you never
+  need either word.
+
+  The agent is the one in this directory, so nothing has to be named.`,
+    run,
+};
+const VERBS = new Set(["from", "forget", "claim", "release"]);
+export async function run(argv, out = process.stdout) {
+    const [verb, ...rest] = VERBS.has(argv[0] ?? "") ? argv : ["show", ...argv];
+    const door = theDoor();
+    if (door === undefined)
+        return 2;
+    // `from` and `forget` are about the PERSON and not about one agent, so neither loads a class:
+    // a phone is yours in whatever directory you are standing in.
+    if (verb === "from") {
+        const number = rest[0];
+        if (number === undefined) {
+            process.stderr.write(`${USAGE}\n`);
+            return 2;
+        }
+        const said = await callsFrom(door, number);
+        keptOnTheProfile(number);
+        out.write(`${calling(said.calling)}\n`);
+        return 0;
+    }
+    if (verb === "forget") {
+        const said = await forgetCallsFrom(door);
+        keptOnTheProfile(undefined);
+        out.write(`${forgotten(said.forgot)}\n`);
+        return 0;
+    }
+    const slug = slugOf((await load(rest[0])).ctor);
+    const said = verb === "claim"
+        ? await claimed(door, slug)
+        : verb === "release"
+            ? await released(door, slug)
+            : await theLine(door, slug);
+    out.write(`${describing(said)}\n`);
+    return 0;
+}
+/** Say which phone is yours: every call it makes reaches your own agent, in whatever you hold. */
+export async function callsFrom(door, number) {
+    return await asked(door, FROM, { method: "PUT", body: { number } });
+}
+/** Stop answering your own calls: they fall back to whoever holds the line. */
+export async function forgetCallsFrom(door) {
+    return await asked(door, FROM, { method: "DELETE" });
+}
+/** What the terminal says back once a number is yours. */
+export function calling(numbers) {
+    return numbers.length === 1
+        ? `calls from ${numbers[0]} reach this terminal`
+        : `calls from ${numbers.join(", ")} reach this terminal`;
+}
+/** And when they stop. A `forget` that forgot nothing says so rather than looking like it worked. */
+export function forgotten(numbers) {
+    return numbers.length === 0
+        ? "no number was reaching this terminal"
+        : `calls from ${numbers.join(", ")} no longer reach this terminal`;
+}
+/** Who is answering this agent's ringing doors right now. */
+export async function theLine(door, slug) {
+    return await asked(door, path(slug));
+}
+/** Take it for this terminal, whoever had it. */
+export async function claimed(door, slug) {
+    return await asked(door, path(slug), { method: "POST" });
+}
+/** Give it up: whoever else is still running the agent picks it up. */
+export async function released(door, slug) {
+    return await asked(door, path(slug), { method: "DELETE" });
+}
+function path(slug) {
+    return `/v1/agents/${encodeURIComponent(slug)}/line`;
+}
+// A phone is a PERSON's and not an agent's, so this door sits above the agents: say it once and
+// it works on every agent you hold.
+const FROM = "/v1/line/from";
+/**
+ * The line as a person reads it: where the ring lands, and the move that changes it.
+ *
+ * It never prints a member id. A person recognises a colleague by their email and nothing else,
+ * and a corner nobody is named in — the org's own key, CI's — is said as what it is rather than
+ * as a null.
+ */
+export function describing(said) {
+    if (!said.held)
+        return `nobody is answering ${said.agent}: start \`pinecall run\``;
+    // Yours by number beats yours by line, and is said first: it is the one that needs no upkeep.
+    const mine = said.calling.length > 0 ? `your calls from ${said.calling.join(", ")}` : undefined;
+    if (said.yours) {
+        const also = [mine, whoElse(said)].filter((part) => part !== undefined);
+        return ["rings in this terminal", ...also].join(" · ");
+    }
+    const theirs = `rings in ${whose(said)}`;
+    if (mine !== undefined)
+        return `${theirs}, but not ${mine}`;
+    return `${theirs} · \`pinecall line from <+your-number>\` routes yours, or \`claim\` takes it`;
+}
+/** Whose terminal it rings in, for somebody reading a sentence about a colleague. */
+function whose(said) {
+    const name = said.holding?.name;
+    return name === null || name === undefined ? "the terminal running the org's own key" : name;
+}
+/** Who else is running this agent and could take it, or nothing when nobody is. */
+function whoElse(said) {
+    const names = said.waiting.map((one) => one.name ?? "the org's own key");
+    return names.length === 0 ? undefined : `also running: ${names.join(", ")}`;
+}
+//# sourceMappingURL=line.js.map

package/dist/cli/line.js.map

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

package/dist/cli/listening.d.ts

@@ -0,0 +1,38 @@
+/** `--listen`: one live call on this machine's speakers, from the terminal that opened it. */
+import { type Door } from "./testing/gateway.js";
+/** What a seat in a room is: LiveKit's two fields, and who this terminal is in that room. */
+interface Seat {
+    server_url: string;
+    participant_token: string;
+    identity: string;
+}
+/** One ear in one call, and the way to take it out again. */
+export interface Ear {
+    /** Who this terminal is in the room, for the line it prints. */
+    identity: string;
+    leave(): Promise<void>;
+}
+/** What to say when this machine has no way to play raw audio, and what installs one. */
+export declare const NO_PLAYER: string;
+/** What to say when the room library is not installed: it is optional, and this is what wants it. */
+export declare const NO_ROOM_LIBRARY: string;
+/**
+ * A hidden, silent seat in one live call, with both tracks mixed onto this machine's speakers.
+ * It is the same seat the console's listen button takes — `POST /v1/calls/{call}/listen`, scope
+ * `observe` — and the caller is never told anybody joined. Nothing is recorded here: the runtime
+ * writes the recording, and this is only the ear.
+ *
+ * The room is joined in a process of its own (cli/ear.ts), because the room library is a native
+ * build with a logger this process cannot turn down and threads that would hold it open after the
+ * call. This side mints the seat, starts the player, and pipes the one into the other.
+ */
+export declare function anEarIn(door: Door, call: string, out: NodeJS.WritableStream): Promise<Ear>;
+/**
+ * The seat, knocked for until the room opens. The gateway mints it off the call's snapshot and a
+ * simulation asks the moment it has an id — before the worker has joined — so asking once would
+ * be asking too early, and joining late is joining after the greeting.
+ */
+export declare function aSeatIn(door: Door, call: string): Promise<Seat>;
+export declare const EAR: string;
+export {};
+//# sourceMappingURL=listening.d.ts.map

package/dist/cli/listening.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listening.d.ts","sourceRoot":"","sources":["../../src/cli/listening.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAQ9F,OAAO,EAAS,KAAK,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAExD,6FAA6F;AAC7F,UAAU,IAAI;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,6DAA6D;AAC7D,MAAM,WAAW,GAAG;IAClB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA6BD,yFAAyF;AACzF,eAAO,MAAM,SAAS,QAE8D,CAAC;AAErF,qGAAqG;AACrG,eAAO,MAAM,eAAe,QAEqD,CAAC;AAElF;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,CAoBhG;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUrE;AAID,eAAO,MAAM,GAAG,QAA2F,CAAC"}

package/dist/cli/listening.js

@@ -0,0 +1,124 @@
+/** `--listen`: one live call on this machine's speakers, from the terminal that opened it. */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { asked } from "./testing/gateway.js";
+// The room's own rate and shape. Everything that reaches a room is 48 kHz mono — the caller's
+// track is published at that rate (runtime evals/speech.py) — so the ear and the player agree on
+// one number rather than each guessing.
+const SAMPLE_RATE = 48_000;
+const CHANNELS = 1;
+// The seat is minted off the call's snapshot, which the gateway writes when the room opens. A
+// simulation asks for its ear the moment it has an id, which is before the worker has joined, so
+// the door is knocked at until it answers rather than once.
+const A_ROOM_OPENS_WITHIN_MS = 30_000;
+const A_KNOCK_EVERY_MS = 500;
+// How long the ear is given to leave the room on its own before it is made to.
+const LEAVING_TAKES_MS = 2_000;
+// The ear's PCM comes out of its fd 3, never its stdout: the room library's own logger writes to
+// stdout at debug and is exported nowhere, so stdout is the one place the samples could not go.
+const PCM = 3;
+/** The players this machine might have, in the order they are tried, each with its raw-audio flags. */
+const PLAYERS = [
+    { name: "ffplay", args: ["-hide_banner", "-loglevel", "error", "-nodisp", "-autoexit", "-f", "s16le", "-ar", String(SAMPLE_RATE), "-ac", String(CHANNELS), "-i", "-"] },
+    { name: "play", args: ["-q", "-t", "raw", "-r", String(SAMPLE_RATE), "-e", "signed", "-b", "16", "-c", String(CHANNELS), "-"] },
+    { name: "aplay", args: ["-q", "-f", "S16_LE", "-r", String(SAMPLE_RATE), "-c", String(CHANNELS), "-"] },
+    { name: "pw-play", args: [`--format=s16`, `--rate=${SAMPLE_RATE}`, `--channels=${CHANNELS}`, "-"] },
+];
+/** What to say when this machine has no way to play raw audio, and what installs one. */
+export const NO_PLAYER = `no player on this machine: --listen writes ${SAMPLE_RATE} Hz mono to one of ` +
+    `${PLAYERS.map((one) => one.name).join(", ")} — install ffmpeg, sox or alsa-utils`;
+/** What to say when the room library is not installed: it is optional, and this is what wants it. */
+export const NO_ROOM_LIBRARY = "--listen joins the call's room from this terminal and needs @livekit/rtc-node, which is an " +
+    "optional dependency: install it (pnpm add @livekit/rtc-node) and listen again";
+/**
+ * A hidden, silent seat in one live call, with both tracks mixed onto this machine's speakers.
+ * It is the same seat the console's listen button takes — `POST /v1/calls/{call}/listen`, scope
+ * `observe` — and the caller is never told anybody joined. Nothing is recorded here: the runtime
+ * writes the recording, and this is only the ear.
+ *
+ * The room is joined in a process of its own (cli/ear.ts), because the room library is a native
+ * build with a logger this process cannot turn down and threads that would hold it open after the
+ * call. This side mints the seat, starts the player, and pipes the one into the other.
+ */
+export async function anEarIn(door, call, out) {
+    const player = aPlayer();
+    if (player === null)
+        throw new Error(NO_PLAYER);
+    theRoomLibrary();
+    const seat = await aSeatIn(door, call);
+    const ear = spawn(process.execPath, [...theLoaderFor(EAR), EAR, String(SAMPLE_RATE), String(CHANNELS)], {
+        stdio: ["pipe", "ignore", "ignore", "pipe"],
+    });
+    ear.stdio[PCM].pipe(player.stdin);
+    ear.stdin.write(`${JSON.stringify({ server_url: seat.server_url, participant_token: seat.participant_token })}\n`);
+    out.write(`  listening as ${seat.identity} · ${player.spawnfile}\n`);
+    return {
+        identity: seat.identity,
+        async leave() {
+            // Closing its stdin is how the ear is told to leave; a moment later it is made to.
+            ear.stdin.end();
+            await gone(ear);
+            player.stdin.end();
+        },
+    };
+}
+/**
+ * The seat, knocked for until the room opens. The gateway mints it off the call's snapshot and a
+ * simulation asks the moment it has an id — before the worker has joined — so asking once would
+ * be asking too early, and joining late is joining after the greeting.
+ */
+export async function aSeatIn(door, call) {
+    const deadline = Date.now() + A_ROOM_OPENS_WITHIN_MS;
+    for (;;) {
+        try {
+            return await asked(door, `/v1/calls/${call}/listen`, { method: "POST", body: {} });
+        }
+        catch (refused) {
+            if (Date.now() >= deadline)
+                throw refused;
+            await new Promise((wake) => setTimeout(wake, A_KNOCK_EVERY_MS));
+        }
+    }
+}
+// The ear beside this file, whatever this file is: `ear.ts` under the loader in a checkout, `ear.js`
+// in the published dist. Which one is read off this module's own name.
+export const EAR = fileURLToPath(new URL(`ear${extname(fileURLToPath(import.meta.url))}`, import.meta.url));
+/** How node runs the ear: through tsx when it is TypeScript, and on its own when it is not. */
+function theLoaderFor(entry) {
+    return extname(entry) === ".ts" ? ["--import", "tsx"] : [];
+}
+/** Whether the ear's one dependency is installed here, asked without loading it. */
+function theRoomLibrary() {
+    try {
+        import.meta.resolve("@livekit/rtc-node");
+    }
+    catch {
+        throw new Error(NO_ROOM_LIBRARY);
+    }
+}
+/** The ear's exit, or the ear killed when it took too long about it. */
+function gone(ear) {
+    return new Promise((left) => {
+        const kill = setTimeout(() => ear.kill("SIGKILL"), LEAVING_TAKES_MS);
+        ear.once("exit", () => {
+            clearTimeout(kill);
+            left();
+        });
+    });
+}
+/** The first player this machine has on its PATH, started and waiting for samples. */
+function aPlayer() {
+    for (const { name, args } of PLAYERS) {
+        if (!onThePath(name))
+            continue;
+        return spawn(name, args, { stdio: ["pipe", "ignore", "ignore"] });
+    }
+    return null;
+}
+/** Is this program on this shell's PATH? Asked without starting anything to find out. */
+function onThePath(name) {
+    return (process.env["PATH"] ?? "").split(delimiter).some((where) => where !== "" && existsSync(join(where, name)));
+}
+//# sourceMappingURL=listening.js.map

package/dist/cli/listening.js.map

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

package/dist/cli/load.d.ts

@@ -0,0 +1,38 @@
+/** Loading a tenant's agent file from the CLI: the TypeScript loader, the class, and its own source. */
+import { Agent } from "../agent/agent.js";
+import { type MountOptions } from "../runtime/connect.js";
+/** What the CLI needs to mount or render an agent: the class, and the file it came from. */
+export interface Loaded {
+    ctor: new () => Agent;
+    file: string;
+    source: string;
+}
+/**
+ * Where an agent lives when nobody said. A class whose `render()` returns JSX is written in
+ * `agent.tsx`, which is what every example and every generator writes; `agent.ts` still loads, for
+ * a class that renders nothing. The first that is there wins, and a usage line names the first.
+ */
+export declare const DEFAULT_AGENTS: readonly ["agent.tsx", "agent.ts"];
+/** Register tsx, once per process: the tenant writes .ts and .tsx and never a build step. */
+export declare function useTypeScript(): Promise<void>;
+/**
+ * Load an agent file: import its default export and hand the class its own source.
+ *
+ * The source is not a nicety. A class docstring sits ABOVE the class, where `Ctor.toString()`
+ * cannot see it, and the parameter types are gone by the time the file is a module — so the identity
+ * block would open without its first line and the tools would carry untyped arguments. `describe`
+ * is the one call that puts both back, and this is the only place that has the text to give it.
+ */
+export declare function load(file?: string): Promise<Loaded>;
+/**
+ * One instance of the loaded class with a line to answer on: what the pages that print a prompt
+ * render. A `render()` may read `this.call`, and a page that could not answer that question would
+ * be a page about a call that cannot happen.
+ */
+export declare function instanceFor(loaded: Loaded, channel?: string): Agent;
+/** What `mount` is given for a loaded agent: the client, the source and the file it came from. */
+export declare function mountOptions(loaded: Loaded, pc: MountOptions["pc"]): MountOptions;
+/** The refusal for a file typed where a slug is taken, or undefined when it is a slug. */
+export declare function notASlug(said: string | undefined): string | undefined;
+export declare function agentOfThisDirectory(): Promise<string | null>;
+//# sourceMappingURL=load.d.ts.map

package/dist/cli/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/cli/load.ts"],"names":[],"mappings":"AAAA,wGAAwG;AAMxG,OAAO,EAAE,KAAK,EAAW,MAAM,mBAAmB,CAAC;AAGnD,OAAO,EAAE,KAAK,YAAY,EAAU,MAAM,uBAAuB,CAAC;AAGlE,4FAA4F;AAC5F,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,UAAU,KAAK,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,YAAI,WAAW,EAAE,UAAU,CAAU,CAAC;AAIjE,6FAA6F;AAI7F,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAKnD;AAED;;;;;;;GAOG;AACH,wBAAsB,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAczD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAAQ,GAAG,KAAK,CAIlE;AAED,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,YAAY,CAEjF;AAoBD,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGrE;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOnE"}