@pinecall/protocol 0.1.0

package/dist/generated/state.js

@@ -0,0 +1,179 @@
+// Generated from schema/state.json: what a log reduces to. Never edited by hand.
+import { z } from "zod";
+import { AgentStateSchema, ChannelSchema, ContactSchema, CostSchema, DirectionSchema, DocSourceSchema, EndReasonSchema, EventSourceSchema, MemoryOpSchema, ParticipantKindSchema, RouteSchema, SupervisorSchema, TransferModeSchema, UserStateSchema, } from "./defs.js";
+import { AgentTurnMetricsSchema, AvatarMetricsSchema, EOTInferenceMetricsSchema, EOUMetricsSchema, InterruptionMetricsSchema, LLMMetricsSchema, ModelUsageSchema, RealtimeModelMetricsSchema, STTMetricsSchema, TTSMetricsSchema, UserTurnMetricsSchema, VADMetricsSchema, } from "./metrics.js";
+/**
+ * Where the call is in its life. idle before any call.* entry, which is what an agent's own log
+ * looks like.
+ */
+export const CallStatusSchema = z.enum(["idle", "ringing", "dialing", "active", "ended"]);
+/** One finished turn of the caller, with what the session measured about it. */
+export const UserTurnSchema = z.strictObject({
+    role: z.literal("user"),
+    speech_id: z.string(),
+    item_id: z.string().nullish(),
+    text: z.string(),
+    language: z.string().nullish(),
+    transcript_confidence: z.number().nullish(),
+    metrics: UserTurnMetricsSchema,
+});
+/** One finished reply of the agent, with what the session measured about it. */
+export const AgentTurnSchema = z.strictObject({
+    role: z.literal("agent"),
+    speech_id: z.string(),
+    item_id: z.string().nullish(),
+    text: z.string(),
+    interrupted: z.boolean(),
+    metrics: AgentTurnMetricsSchema,
+});
+/** One turn of either side, told apart by role. */
+export const TurnSchema = z.discriminatedUnion("role", [UserTurnSchema, AgentTurnSchema]);
+/**
+ * Every raw metric block of the call, by kind, in the order it arrived. The turns hold the join;
+ * this holds the measurements.
+ */
+export const CollectedMetricsSchema = z.strictObject({
+    llm: z.array(LLMMetricsSchema),
+    stt: z.array(STTMetricsSchema),
+    tts: z.array(TTSMetricsSchema),
+    vad: z.array(VADMetricsSchema),
+    eou: z.array(EOUMetricsSchema),
+    eot: z.array(EOTInferenceMetricsSchema),
+    interruption: z.array(InterruptionMetricsSchema),
+    realtime: z.array(RealtimeModelMetricsSchema),
+    avatar: z.array(AvatarMetricsSchema),
+});
+/** One tool call and, once the app answered, its result. */
+export const ToolRunSchema = z.strictObject({
+    call_id: z.string(),
+    name: z.string(),
+    arguments: z.record(z.string(), z.unknown()),
+    speech_id: z.string().nullish(),
+    status: z.enum(["running", "done", "failed"]),
+    output: z.unknown().nullish(),
+    error: z.string().nullish(),
+    summary: z.string().nullish(),
+    duration_s: z.number().nullish(),
+    seq: z.int(),
+});
+/** What is known about one block of the prompt without storing its text. */
+export const PromptBlockStateSchema = z.strictObject({
+    hash: z.string(),
+    chars: z.int(),
+    seq: z.int(),
+});
+/**
+ * Every block the app has written, by name, without its text. The history between the static and
+ * the dynamic blocks is the turns.
+ */
+export const PromptStateSchema = z.record(z.string(), PromptBlockStateSchema);
+/** One confirmation the platform asked for, and how it went. */
+export const ConfirmSchema = z.strictObject({
+    tool: z.string(),
+    call_id: z.string(),
+    audience: z.string(),
+    phrase: z.string(),
+    status: z.enum(["pending", "granted", "declined"]),
+    said: z.string().nullish(),
+    reason: z.string().nullish(),
+});
+/** Whether a supervisor holds the line right now. */
+export const HandoffSchema = z.strictObject({
+    active: z.boolean(),
+    by: SupervisorSchema.nullable(),
+});
+/** The transfer in flight or the one that happened. */
+export const TransferStateSchema = z.strictObject({
+    to: z.string(),
+    mode: TransferModeSchema,
+    status: z.enum(["requested", "done", "failed"]),
+    by: z.enum(["agent", "supervisor"]),
+});
+/** The words on screen right now: interim transcripts that a finished turn clears. */
+export const LiveTranscriptSchema = z.strictObject({
+    user: z.string().nullable(),
+    agent: z.string().nullable(),
+});
+/** A stretch of seqs this reader never saw. */
+export const GapSchema = z.strictObject({
+    from_seq: z.int(),
+    to_seq: z.int(),
+});
+/** An error entry, kept so the console can show what went wrong and when. */
+export const LoggedErrorSchema = z.strictObject({
+    seq: z.int(),
+    code: z.string(),
+    message: z.string(),
+});
+/** One participant in the room right now, as the room reported them when they joined. */
+export const ParticipantSchema = z.strictObject({
+    identity: z.string(),
+    kind: ParticipantKindSchema,
+    name: z.string().nullish(),
+    joined_at: z.number(),
+    speaking: z.boolean(),
+    attributes: z.record(z.string(), z.unknown()),
+});
+/** The LiveKit room the call lives in, and who is in it right now. */
+export const RoomSchema = z.strictObject({
+    name: z.string(),
+    sid: z.string(),
+    participants: z.array(ParticipantSchema),
+    caller: z.string().nullable(),
+});
+/**
+ * One fact that reached the agent from outside the conversation, kept by name and origin. Its data
+ * is in the log at that seq.
+ */
+export const ReceivedEventSchema = z.strictObject({
+    seq: z.int(),
+    name: z.string(),
+    source: EventSourceSchema,
+    identity: z.string().nullish(),
+});
+/** A line the app wrote into the log with call.log. */
+export const CustomNoteSchema = z.strictObject({
+    seq: z.int(),
+    name: z.string(),
+    data: z.record(z.string(), z.unknown()),
+});
+/** The whole of what a log says, at the seq it was read to. */
+export const StateSchema = z.strictObject({
+    seq: z.int(),
+    agent: z.string(),
+    call: z.string().nullable(),
+    status: CallStatusSchema,
+    channel: ChannelSchema.nullable(),
+    direction: DirectionSchema.nullable(),
+    from: z.string().nullable(),
+    to: z.string().nullable(),
+    caller: ContactSchema.nullable(),
+    room: RoomSchema.nullable(),
+    started_at: z.number().nullable(),
+    ended_at: z.number().nullable(),
+    end_reason: EndReasonSchema.nullable(),
+    outcome: z.string().nullable(),
+    user_state: UserStateSchema.nullable(),
+    agent_state: AgentStateSchema.nullable(),
+    live: LiveTranscriptSchema,
+    turns: z.array(TurnSchema),
+    metrics: CollectedMetricsSchema,
+    tools: z.array(ToolRunSchema),
+    app_state: z.record(z.string(), z.unknown()),
+    events: z.array(ReceivedEventSchema),
+    prompt: PromptStateSchema,
+    tools_visible: z.array(z.string()),
+    confirms: z.array(ConfirmSchema),
+    memory: z.array(MemoryOpSchema),
+    sources: z.array(DocSourceSchema),
+    handoff: HandoffSchema,
+    held: z.boolean(),
+    muted: z.boolean(),
+    transfer: TransferStateSchema.nullable(),
+    usage: z.array(ModelUsageSchema),
+    cost: CostSchema.nullable(),
+    routes: z.array(RouteSchema),
+    gaps: z.array(GapSchema),
+    errors: z.array(LoggedErrorSchema),
+    custom: z.array(CustomNoteSchema),
+});

package/dist/generated/units.d.ts

@@ -0,0 +1,2 @@
+/** What one field is measured in, by the name the wire uses: `UNITS.ttft` is `"s"`. */
+export declare const UNITS: Readonly<Record<string, string>>;

package/dist/generated/units.js

@@ -0,0 +1,80 @@
+// Generated from schema: the unit each measured field is written in. Never edited by hand.
+/** What one field is measured in, by the name the wire uses: `UNITS.ttft` is `"s"`. */
+export const UNITS = {
+    acquire_time: "s",
+    audio_duration: "s",
+    audio_tokens: "tokens",
+    avatar_joined_time: "unix s",
+    cache_creation_tokens: "tokens",
+    cached_tokens: "tokens",
+    cached_tokens_details: "object",
+    cancelled: "flag",
+    characters_count: "chars",
+    completion_tokens: "tokens",
+    connection_reused: "flag",
+    detection_delay: "s",
+    duration: "s",
+    e2e_latency: "s",
+    end_of_turn_delay: "s",
+    end_of_utterance_delay: "s",
+    idle_time: "s",
+    image_tokens: "tokens",
+    inference_count: "count",
+    inference_duration_total: "s",
+    input_audio_tokens: "tokens",
+    input_cache_creation_tokens: "tokens",
+    input_cached_audio_tokens: "tokens",
+    input_cached_image_tokens: "tokens",
+    input_cached_text_tokens: "tokens",
+    input_cached_tokens: "tokens",
+    input_image_tokens: "tokens",
+    input_text_tokens: "tokens",
+    input_token_details: "object",
+    input_tokens: "tokens",
+    label: "name",
+    llm_metadata: "object",
+    llm_node_tps: "tokens/s",
+    llm_node_ttfs: "s",
+    llm_node_ttft: "s",
+    metadata: "object",
+    model: "name",
+    model_name: "name",
+    model_provider: "name",
+    num_backchannels: "count",
+    num_interruptions: "count",
+    num_requests: "count",
+    on_user_turn_completed_delay: "s",
+    output_audio_tokens: "tokens",
+    output_reasoning_tokens: "tokens",
+    output_text_tokens: "tokens",
+    output_token_details: "object",
+    output_tokens: "tokens",
+    playback_latency: "s",
+    prediction_duration: "s",
+    prompt_cached_tokens: "tokens",
+    prompt_tokens: "tokens",
+    provider: "name",
+    provider_request_ids: "ids",
+    reasoning_tokens: "tokens",
+    request_id: "id",
+    segment_id: "id",
+    session_duration: "s",
+    session_started_time: "unix s",
+    speech_id: "id",
+    started_speaking_at: "unix s",
+    stopped_speaking_at: "unix s",
+    streamed: "flag",
+    stt_metadata: "object",
+    text_tokens: "tokens",
+    timestamp: "unix s",
+    tokens_per_second: "tokens/s",
+    total_duration: "s",
+    total_requests: "count",
+    total_tokens: "tokens",
+    transcription_delay: "s",
+    ttfb: "s",
+    ttft: "s",
+    tts_metadata: "object",
+    tts_node_ttfb: "s",
+    type: "tag",
+};

package/dist/generated/verbs.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+/** Make the agent say this, verbatim, to the caller. Logged as supervisor.said. */
+export declare const SayVerbSchema: z.ZodObject<{
+    verb: z.ZodLiteral<"say">;
+    text: z.ZodString;
+}, z.core.$strict>;
+export type SayVerb = z.infer<typeof SayVerbSchema>;
+/**
+ * Tell the agent something the caller never hears. It reaches the agent as an instruction for its
+ * next reply; logged as supervisor.whispered.
+ */
+export declare const WhisperVerbSchema: z.ZodObject<{
+    verb: z.ZodLiteral<"whisper">;
+    text: z.ZodString;
+}, z.core.$strict>;
+export type WhisperVerb = z.infer<typeof WhisperVerbSchema>;
+/**
+ * The supervisor takes the line: the agent goes quiet and the supervisor's audio replaces it.
+ * Logged as supervisor.took_over.
+ */
+export declare const TakeoverVerbSchema: z.ZodObject<{
+    verb: z.ZodLiteral<"takeover">;
+}, z.core.$strict>;
+export type TakeoverVerb = z.infer<typeof TakeoverVerbSchema>;
+/**
+ * The supervisor hands the line back to the agent, which resumes with the history intact. Logged
+ * as supervisor.released.
+ */
+export declare const ReleaseVerbSchema: z.ZodObject<{
+    verb: z.ZodLiteral<"release">;
+}, z.core.$strict>;
+export type ReleaseVerb = z.infer<typeof ReleaseVerbSchema>;
+/**
+ * Send the caller to another number. Logged as supervisor.transferred, then call.transferred says
+ * whether it worked.
+ */
+export declare const TransferVerbSchema: z.ZodObject<{
+    verb: z.ZodLiteral<"transfer">;
+    to: z.ZodString;
+    mode: z.ZodEnum<{
+        cold: "cold";
+        warm: "warm";
+    }>;
+}, z.core.$strict>;
+export type TransferVerb = z.infer<typeof TransferVerbSchema>;
+/**
+ * Hang up on the caller's behalf. Logged as supervisor.ended, then call.ended with reason
+ * supervisor_ended.
+ */
+export declare const EndVerbSchema: z.ZodObject<{
+    verb: z.ZodLiteral<"end">;
+    reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type EndVerb = z.infer<typeof EndVerbSchema>;
+/** One supervise verb, told apart by its verb field. */
+export declare const VerbSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    verb: z.ZodLiteral<"say">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    verb: z.ZodLiteral<"whisper">;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    verb: z.ZodLiteral<"takeover">;
+}, z.core.$strict>, z.ZodObject<{
+    verb: z.ZodLiteral<"release">;
+}, z.core.$strict>, z.ZodObject<{
+    verb: z.ZodLiteral<"transfer">;
+    to: z.ZodString;
+    mode: z.ZodEnum<{
+        cold: "cold";
+        warm: "warm";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    verb: z.ZodLiteral<"end">;
+    reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>], "verb">;
+export type Verb = z.infer<typeof VerbSchema>;

package/dist/generated/verbs.js

@@ -0,0 +1,49 @@
+// Generated from schema/verbs.json: the supervise verbs. Never edited by hand.
+import { z } from "zod";
+import { TransferModeSchema } from "./defs.js";
+/** Make the agent say this, verbatim, to the caller. Logged as supervisor.said. */
+export const SayVerbSchema = z.strictObject({
+    verb: z.literal("say"),
+    text: z.string(),
+});
+/**
+ * Tell the agent something the caller never hears. It reaches the agent as an instruction for its
+ * next reply; logged as supervisor.whispered.
+ */
+export const WhisperVerbSchema = z.strictObject({
+    verb: z.literal("whisper"),
+    text: z.string(),
+});
+/**
+ * The supervisor takes the line: the agent goes quiet and the supervisor's audio replaces it.
+ * Logged as supervisor.took_over.
+ */
+export const TakeoverVerbSchema = z.strictObject({
+    verb: z.literal("takeover"),
+});
+/**
+ * The supervisor hands the line back to the agent, which resumes with the history intact. Logged
+ * as supervisor.released.
+ */
+export const ReleaseVerbSchema = z.strictObject({
+    verb: z.literal("release"),
+});
+/**
+ * Send the caller to another number. Logged as supervisor.transferred, then call.transferred says
+ * whether it worked.
+ */
+export const TransferVerbSchema = z.strictObject({
+    verb: z.literal("transfer"),
+    to: z.string(),
+    mode: TransferModeSchema,
+});
+/**
+ * Hang up on the caller's behalf. Logged as supervisor.ended, then call.ended with reason
+ * supervisor_ended.
+ */
+export const EndVerbSchema = z.strictObject({
+    verb: z.literal("end"),
+    reason: z.string().nullish(),
+});
+/** One supervise verb, told apart by its verb field. */
+export const VerbSchema = z.discriminatedUnion("verb", [SayVerbSchema, WhisperVerbSchema, TakeoverVerbSchema, ReleaseVerbSchema, TransferVerbSchema, EndVerbSchema]);

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./generated/index.js";
+export { apply, initialState, reduce } from "./reduce.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+// @pinecall/protocol: the wire as zod schemas and types, generated from protocol/schema, and the reducer.
+export * from "./generated/index.js";
+export { apply, initialState, reduce } from "./reduce.js";

package/dist/reduce.d.ts

@@ -0,0 +1,10 @@
+import type { Entry } from "./generated/envelope.js";
+import type { State } from "./generated/state.js";
+/** Fold every entry, in the order given, into the state an empty log starts from. */
+export declare function reduce(entries: Iterable<Entry>): State;
+/** What an empty log is: nothing known, every list empty, status idle. */
+export declare function initialState(): State;
+/** What a reader says about an entry it cannot read, in the log's own errors list. */
+export declare const UNREADABLE = "unreadable";
+/** One entry folded in. Returns the state to keep going with. */
+export declare function apply(state: State, entry: Entry): State;