@pinecall/protocol 0.1.0

package/dist/generated/rest.js

@@ -0,0 +1,291 @@
+// Generated from schema/rest.json: the envelopes the read doors answer in. Never edited by hand.
+import { z } from "zod";
+import { ChannelSchema, ContactSchema, CostSchema, DirectionSchema, EndReasonSchema, EnvSchema, KnowledgeFileSchema, PlatformToolSchema, } from "./defs.js";
+import { EntrySchema } from "./envelope.js";
+import { CallStatusSchema, StateSchema } from "./state.js";
+/** GET /v1/calls/{call}/state: the whole log folded, and the seq a stream resumes from. */
+export const CallStateSchema = z.strictObject({
+    state: StateSchema,
+    last_seq: z.int(),
+    live: z.boolean(),
+});
+/** One page of a log: what this reader may see, whether the log is open, and where to resume. */
+export const LogPageSchema = z.strictObject({
+    entries: z.array(EntrySchema),
+    live: z.boolean(),
+    next: z.int().nullable(),
+});
+/** One call as a list draws it: which call, how far the log got, and the state's own fields. */
+export const SessionLineSchema = z.strictObject({
+    call: z.string(),
+    agent: z.string(),
+    live: z.boolean(),
+    last_seq: z.int(),
+    status: CallStatusSchema,
+    channel: ChannelSchema.nullable(),
+    direction: DirectionSchema.nullable(),
+    from: z.string().nullable(),
+    to: z.string().nullable(),
+    caller: ContactSchema.nullable(),
+    started_at: z.number().nullable(),
+    ended_at: z.number().nullable(),
+    end_reason: EndReasonSchema.nullable(),
+    outcome: z.string().nullable(),
+    cost: CostSchema.nullable(),
+});
+/** GET /v1/agents/{slug}/sessions: which calls that agent handled, newest first. */
+export const SessionListSchema = z.strictObject({
+    calls: z.array(SessionLineSchema),
+});
+/** One corner of a world holding an agent: the member whose it is, named so a person can read it. */
+export const LineHolderSchema = z.strictObject({
+    holder: z.string().nullable(),
+    name: z.string().nullable(),
+});
+/** One agent, as somebody choosing which to open needs to see it: its name and its channels. */
+export const HeldAgentSchema = z.strictObject({
+    slug: z.string(),
+    channels: z.array(ChannelSchema),
+    holder: LineHolderSchema.nullish(),
+});
+/** GET /v1/agents: every agent this fleet is holding right now, as the front page lists them. */
+export const AgentListSchema = z.strictObject({
+    agents: z.array(HeldAgentSchema),
+});
+/**
+ * GET /v1/agents/{slug}/line: whose terminal a call that RINGS at this agent's doors lands in. An
+ * org shares one sandbox number, so it rings in one place and which one is claimed.
+ */
+export const TheLineSchema = z.strictObject({
+    agent: z.string(),
+    env: EnvSchema,
+    held: z.boolean(),
+    holding: LineHolderSchema.nullish(),
+    yours: z.boolean(),
+    waiting: z.array(LineHolderSchema),
+    calling: z.array(z.string()),
+});
+/**
+ * PUT /v1/knowledge/{base}, the body: the tenant's folder as of now, sent whole. The base is
+ * replaced, never merged.
+ */
+export const KnowledgePushSchema = z.strictObject({
+    files: z.array(KnowledgeFileSchema),
+});
+/**
+ * One question of a base's golden: what somebody asks, and the chunk that should answer it. A
+ * chunk answers when its file and heading path start with `expects`, so naming a file alone
+ * accepts any chunk of it and naming a heading accepts that section.
+ */
+export const GoldenQuestionSchema = z.strictObject({
+    asks: z.string(),
+    expects: z.string(),
+});
+/**
+ * POST /v1/knowledge/{base}/eval, the body: the questions a base is held to. A golden is fixed and
+ * the index is the variable; a question is never softened so a change can pass.
+ */
+export const KnowledgeGoldenSchema = z.strictObject({
+    questions: z.array(GoldenQuestionSchema),
+    k: z.int().nullish(),
+});
+/** One question whose expected chunk was not among the k returned, and what came back instead. */
+export const GoldenMissSchema = z.strictObject({
+    asks: z.string(),
+    expects: z.string(),
+    found: z.array(z.string()),
+});
+/**
+ * POST /v1/knowledge/{base}/eval, the answer: how the index did on its own golden. Both figures
+ * are computed by code, with no model, so two runs of the same golden over the same base answer
+ * the same numbers.
+ */
+export const KnowledgeScoreSchema = z.strictObject({
+    base: z.string(),
+    model: z.string(),
+    questions: z.int(),
+    k: z.int(),
+    recall_at_k: z.number(),
+    ndcg_at_10: z.number(),
+    took_ms: z.number(),
+    misses: z.array(GoldenMissSchema),
+});
+/**
+ * PUT /v1/knowledge/{base}, the answer: which base, how many chunks it became, and how long that
+ * took.
+ */
+export const KnowledgePushedSchema = z.strictObject({
+    base: z.string(),
+    chunks: z.int(),
+    took_ms: z.number(),
+});
+/** One knowledge base as the list draws it: its name, its size, and when it was last pushed. */
+export const KnowledgeBaseSchema = z.strictObject({
+    base: z.string(),
+    chunks: z.int(),
+    model: z.string(),
+    pushed_at: z.number(),
+});
+/** GET /v1/knowledge: every base this org has pushed. */
+export const KnowledgeListSchema = z.strictObject({
+    bases: z.array(KnowledgeBaseSchema),
+});
+/**
+ * One fact of a contact's history: a MemoryFact with the two dates that bound it. A fact is never
+ * deleted, only superseded, so the history keeps every version.
+ */
+export const ContactFactSchema = z.strictObject({
+    id: z.string().nullish(),
+    text: z.string(),
+    category: z.string().nullish(),
+    source: z.string().nullish(),
+    valid_from: z.number(),
+    invalidated_at: z.number().nullable(),
+});
+/**
+ * GET /v1/contacts/{contact}/memory: everything memory ever kept about one contact, current facts
+ * first.
+ */
+export const ContactMemorySchema = z.strictObject({
+    facts: z.array(ContactFactSchema),
+});
+/**
+ * DELETE /v1/contacts/{contact}/memory, the answer: how many facts the right to be forgotten
+ * erased.
+ */
+export const ForgottenSchema = z.strictObject({
+    forgotten: z.int(),
+});
+/**
+ * One question of a memory golden: what memory holds about the contact who asks it, the words they
+ * just said, and the fact or facts that should come back. The facts are the question's own, so a
+ * golden needs no contact in any table.
+ */
+export const MemoryQuestionSchema = z.strictObject({
+    holds: z.array(z.string()),
+    asks: z.string(),
+    expects: z.array(z.string()),
+});
+/**
+ * POST /v1/contacts/memory/eval, the body: the questions memory is held to. Each question brings
+ * its own facts, which are written to a scratch contact of this org, asked, and deleted. A golden
+ * is fixed and the ranking is the variable; a question is never softened so a change can pass.
+ */
+export const MemoryGoldenSchema = z.strictObject({
+    questions: z.array(MemoryQuestionSchema),
+    k: z.int().nullish(),
+});
+/**
+ * One question memory did not answer whole: what it wanted and did not get, and what came back
+ * instead. GoldenMiss is the knowledge base's and names the one chunk that should have won; a
+ * memory question may expect several facts and miss some of them.
+ */
+export const MemoryMissSchema = z.strictObject({
+    asks: z.string(),
+    missing: z.array(z.string()),
+    found: z.array(z.string()),
+});
+/**
+ * POST /v1/contacts/memory/eval, the answer: how memory ranked the facts its own golden asked for.
+ * Both figures are computed by code, with no model in the loop, so two runs of one golden answer
+ * the same numbers.
+ */
+export const MemoryScoreSchema = z.strictObject({
+    model: z.string(),
+    questions: z.int(),
+    k: z.int(),
+    recall_at_k: z.number(),
+    ndcg_at_10: z.number(),
+    took_ms: z.number(),
+    misses: z.array(MemoryMissSchema),
+});
+/**
+ * What must come of one call's hang-up: each field is one of the four ways a hang-up costs a
+ * business. Nothing here compares one sentence to another — a category is the class's own word, a
+ * value is a literal the caller said out loud, and a supersession is an id — because two ways of
+ * writing one fact are one fact.
+ */
+export const ExtractionExpectedSchema = z.strictObject({
+    writes: z.array(z.string()).nullish(),
+    never: z.array(z.string()).nullish(),
+    never_says: z.array(z.string()).nullish(),
+    invalidates: z.array(z.string()).nullish(),
+});
+/**
+ * One call written down and what memory must make of it: the write side of the table, judged by
+ * code. The read side is MemoryGolden and neither answers for the other — a call may extract the
+ * perfect fact and never see it again, because six is what a turn is handed and the seventh is
+ * cut.
+ */
+export const ExtractionGoldenSchema = z.strictObject({
+    name: z.string(),
+    said: z.array(z.tuple([z.string(), z.string()])),
+    holds: z.array(z.string()).nullish(),
+    plants: z.array(z.string()).nullish(),
+    channel: ChannelSchema.nullish(),
+    expect: ExtractionExpectedSchema.nullish(),
+});
+/**
+ * POST /v1/agents/{slug}/memory/extraction, the body: the goldens whole, as the tenant wrote them
+ * down. Each costs ONE model call — the very one a hang-up makes — run on the org's own model and
+ * keys against the class the caller is holding.
+ */
+export const ExtractionCasesSchema = z.strictObject({
+    cases: z.array(ExtractionGoldenSchema),
+});
+/**
+ * One thing that did not hold about a case: which of the questions, and the evidence in a sentence
+ * a person can act on.
+ */
+export const ExtractionBrokeSchema = z.strictObject({
+    check: z.string(),
+    detail: z.string(),
+});
+/** One case, run: what memory would have kept, what admission refused, and what did not hold. */
+export const ExtractionJudgedSchema = z.strictObject({
+    name: z.string(),
+    held: z.boolean(),
+    wrote: z.array(z.string()).nullish(),
+    refused: z.array(z.string()).nullish(),
+    broke: z.array(ExtractionBrokeSchema).nullish(),
+});
+/**
+ * POST /v1/agents/{slug}/memory/extraction, the answer: which model answered, how many cases held,
+ * and every one of them. A verb prints this and a pipeline exits on it.
+ */
+export const ExtractionRunSchema = z.strictObject({
+    agent: z.string(),
+    model: z.string(),
+    cases: z.int(),
+    held: z.int(),
+    took_ms: z.number(),
+    results: z.array(ExtractionJudgedSchema),
+});
+/**
+ * POST /v1/calls/{call}/lookup, the body: which platform tool to run for this turn, and what to
+ * run it with. Worker-only; the gateway runs it against its own stores and writes memory.ops or
+ * docs.sources on the call's log itself.
+ */
+export const LookupRequestSchema = z.strictObject({
+    tool: PlatformToolSchema,
+    input: z.record(z.string(), z.unknown()),
+    speech_id: z.string().nullish(),
+});
+/**
+ * POST /v1/calls/{call}/lookup, the answer: what the tool found, and how long finding it took. The
+ * output is JSON-encoded into a tool_result block, which is where everything from outside the
+ * conversation goes and the only place it goes.
+ */
+export const LookupResultSchema = z.strictObject({
+    output: z.record(z.string(), z.unknown()),
+    took_ms: z.number(),
+});
+/**
+ * POST /v1/calls/{call}/remember, the answer: what the call taught about the contact, counted.
+ * Worker-only; the body is empty, the gateway reads the turns off its own log and writes
+ * memory.ops itself.
+ */
+export const RememberedSchema = z.strictObject({
+    ops: z.int(),
+    took_ms: z.number(),
+});

package/dist/generated/room.d.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+/**
+ * The LiveKit room exists and the call lives in it. Phone and web calls have one; a text session
+ * has no room and never logs this.
+ */
+export declare const RoomOpenedSchema: z.ZodObject<{
+    name: z.ZodString;
+    sid: z.ZodString;
+    channel: z.ZodEnum<{
+        phone: "phone";
+        web: "web";
+        whatsapp: "whatsapp";
+    }>;
+}, z.core.$strict>;
+export type RoomOpened = z.infer<typeof RoomOpenedSchema>;
+/**
+ * Somebody joined the room: the caller over SIP or the widget, the agent, a supervisor, a
+ * listener, or a second SIP leg. Their attributes travel verbatim: the caller's number is a fact
+ * of the room, not a field we invent.
+ */
+export declare const ParticipantJoinedSchema: z.ZodObject<{
+    identity: z.ZodString;
+    kind: z.ZodEnum<{
+        agent: "agent";
+        caller: "caller";
+        supervisor: "supervisor";
+        listener: "listener";
+        sip: "sip";
+    }>;
+    name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export type ParticipantJoined = z.infer<typeof ParticipantJoinedSchema>;
+/** Somebody left the room. When it is the caller, call.ended follows. */
+export declare const ParticipantLeftSchema: z.ZodObject<{
+    identity: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type ParticipantLeft = z.infer<typeof ParticipantLeftSchema>;
+/**
+ * The room's own voice activity for one participant flipped. Ephemeral: it is a light for the
+ * console, and the turns say who spoke.
+ */
+export declare const ParticipantSpeakingSchema: z.ZodObject<{
+    identity: z.ZodString;
+    speaking: z.ZodBoolean;
+}, z.core.$strict>;
+export type ParticipantSpeaking = z.infer<typeof ParticipantSpeakingSchema>;
+/** A participant put a track on the room: their microphone, their camera, a screen. */
+export declare const TrackPublishedSchema: z.ZodObject<{
+    identity: z.ZodString;
+    kind: z.ZodEnum<{
+        audio: "audio";
+        video: "video";
+        screen: "screen";
+    }>;
+    source: z.ZodEnum<{
+        unknown: "unknown";
+        microphone: "microphone";
+        camera: "camera";
+        screen_share: "screen_share";
+        screen_share_audio: "screen_share_audio";
+    }>;
+}, z.core.$strict>;
+export type TrackPublished = z.infer<typeof TrackPublishedSchema>;
+/**
+ * A participant's track left the room: they stopped sharing, or a participant.mute took their
+ * audio away.
+ */
+export declare const TrackUnpublishedSchema: z.ZodObject<{
+    identity: z.ZodString;
+    kind: z.ZodEnum<{
+        audio: "audio";
+        video: "video";
+        screen: "screen";
+    }>;
+    source: z.ZodEnum<{
+        unknown: "unknown";
+        microphone: "microphone";
+        camera: "camera";
+        screen_share: "screen_share";
+        screen_share_audio: "screen_share_audio";
+    }>;
+}, z.core.$strict>;
+export type TrackUnpublished = z.infer<typeof TrackUnpublishedSchema>;
+/**
+ * A fact arrived from outside the conversation: the tenant's backend sent call.event, or a
+ * participant's browser sent pinecall.event. One event for both, told apart by source. It reached
+ * the log only because the agent declared the name in its events, from that source; anything else
+ * was refused before this.
+ */
+export declare const EventReceivedSchema: z.ZodObject<{
+    name: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    source: z.ZodEnum<{
+        app: "app";
+        participant: "participant";
+    }>;
+    identity: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type EventReceived = z.infer<typeof EventReceivedSchema>;
+/**
+ * The agent pushed a payload to a browser in the room, on the tenant's room.send. Ephemeral, and
+ * the payload stays out of the log: the tenant chose what to send and to whom.
+ */
+export declare const RoomSentSchema: z.ZodObject<{
+    topic: z.ZodString;
+    to: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    bytes: z.ZodInt;
+}, z.core.$strict>;
+export type RoomSent = z.infer<typeof RoomSentSchema>;

package/dist/generated/room.js

@@ -0,0 +1,72 @@
+// Generated from schema/room.json: the room's facts and the outside world's. Never edited by hand.
+import { z } from "zod";
+import { ChannelSchema, EventSourceSchema, ParticipantKindSchema, TrackKindSchema, TrackSourceSchema, } from "./defs.js";
+/**
+ * The LiveKit room exists and the call lives in it. Phone and web calls have one; a text session
+ * has no room and never logs this.
+ */
+export const RoomOpenedSchema = z.strictObject({
+    name: z.string(),
+    sid: z.string(),
+    channel: ChannelSchema,
+});
+/**
+ * Somebody joined the room: the caller over SIP or the widget, the agent, a supervisor, a
+ * listener, or a second SIP leg. Their attributes travel verbatim: the caller's number is a fact
+ * of the room, not a field we invent.
+ */
+export const ParticipantJoinedSchema = z.strictObject({
+    identity: z.string(),
+    kind: ParticipantKindSchema,
+    name: z.string().nullish(),
+    attributes: z.record(z.string(), z.unknown()),
+});
+/** Somebody left the room. When it is the caller, call.ended follows. */
+export const ParticipantLeftSchema = z.strictObject({
+    identity: z.string(),
+    reason: z.string(),
+});
+/**
+ * The room's own voice activity for one participant flipped. Ephemeral: it is a light for the
+ * console, and the turns say who spoke.
+ */
+export const ParticipantSpeakingSchema = z.strictObject({
+    identity: z.string(),
+    speaking: z.boolean(),
+});
+/** A participant put a track on the room: their microphone, their camera, a screen. */
+export const TrackPublishedSchema = z.strictObject({
+    identity: z.string(),
+    kind: TrackKindSchema,
+    source: TrackSourceSchema,
+});
+/**
+ * A participant's track left the room: they stopped sharing, or a participant.mute took their
+ * audio away.
+ */
+export const TrackUnpublishedSchema = z.strictObject({
+    identity: z.string(),
+    kind: TrackKindSchema,
+    source: TrackSourceSchema,
+});
+/**
+ * A fact arrived from outside the conversation: the tenant's backend sent call.event, or a
+ * participant's browser sent pinecall.event. One event for both, told apart by source. It reached
+ * the log only because the agent declared the name in its events, from that source; anything else
+ * was refused before this.
+ */
+export const EventReceivedSchema = z.strictObject({
+    name: z.string(),
+    data: z.record(z.string(), z.unknown()),
+    source: EventSourceSchema,
+    identity: z.string().nullish(),
+});
+/**
+ * The agent pushed a payload to a browser in the room, on the tenant's room.send. Ephemeral, and
+ * the payload stays out of the log: the tenant chose what to send and to whom.
+ */
+export const RoomSentSchema = z.strictObject({
+    topic: z.string(),
+    to: z.string().nullish(),
+    bytes: z.int(),
+});