eve 0.83.3 → 0.84.1

package/dist/src/protocol/session-events/families/delivery.d.ts

@@ -0,0 +1,86 @@
+import { z } from "#compiled/zod/index.js";
+import type { Envelope, Principal, UserPart } from "../envelope.js";
+/**
+ * Where a delivery came from: a channel (with the schedule that sent it), a control, or a
+ * sign-in callback. The set is open. A parent session records which of its calls sent a child's
+ * delivery on its own `child.sent`.
+ */
+export type DeliverySource = {
+    readonly channel: string;
+    readonly scheduleId?: string;
+} | {
+    readonly control: string;
+} | {
+    readonly callback: string;
+};
+export interface DeliveryAdmittedData {
+    readonly deliveryId: string;
+    /** Absent for deliveries without auth, such as a sign-in callback. */
+    readonly principal?: Principal;
+    readonly source?: DeliverySource;
+}
+/**
+ * A message from conversation eve did not run, such as a transcript an app stored. It is text
+ * only: it names no turn or call, and records nothing eve did.
+ */
+export interface ImportedMessage {
+    /** The app's own id for the message, when it gave one. eve never reads it. */
+    readonly id?: string;
+    readonly role: "user" | "assistant";
+    readonly text: string;
+}
+export interface DeliveryConsumedData {
+    readonly deliveryId: string;
+    readonly turnId: string;
+    /** What the person sent. Empty for a delivery that only adds context. */
+    readonly parts: readonly UserPart[];
+    /**
+     * Earlier conversation the delivery brought, oldest first. The model reads the history of the
+     * deliveries a line consumes before what they sent.
+     */
+    readonly history?: readonly ImportedMessage[];
+}
+export type DeliveryOutcome = "handled" | "awaiting-input" | "applied" | "ignored" | "refused" | "failed";
+export interface DeliverySettledData {
+    readonly deliveryId: string;
+    readonly outcome: DeliveryOutcome;
+    /** The turn whose reply answers the delivery, when it started or joined one. */
+    readonly turnId?: string;
+    readonly reason?: string;
+}
+export type DeliveryAdmitted = Envelope<"delivery.admitted", DeliveryAdmittedData>;
+export type DeliveryConsumed = Envelope<"delivery.consumed", DeliveryConsumedData>;
+export type DeliverySettled = Envelope<"delivery.settled", DeliverySettledData>;
+export type DeliveryFact = DeliveryAdmitted | DeliveryConsumed | DeliverySettled;
+export declare const deliverySchemas: {
+    "delivery.admitted": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"delivery.admitted">;
+    }, z.core.$strip>;
+    "delivery.consumed": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"delivery.consumed">;
+    }, z.core.$strip>;
+    "delivery.settled": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"delivery.settled">;
+    }, z.core.$strip>;
+};

package/dist/src/protocol/session-events/families/delivery.js

@@ -0,0 +1 @@
+import{conforming,envelopeOf,id,known,principal,userPart}from"../common.js";import{z}from"#compiled/zod/index.js";const deliverySource=conforming()(z.union([z.object({channel:z.string(),scheduleId:z.string().optional()}),z.object({control:z.string()}),z.object({callback:z.string()})])),importedMessage=conforming()(z.object({id:z.string().optional(),role:z.enum([`user`,`assistant`]),text:z.string()})),deliverySchemas={"delivery.admitted":envelopeOf(`delivery.admitted`,conforming()(z.object({deliveryId:id,principal:principal.optional(),source:deliverySource.optional()}))),"delivery.consumed":envelopeOf(`delivery.consumed`,conforming()(z.object({deliveryId:id,history:z.array(importedMessage).optional(),parts:z.array(userPart),turnId:id}))),"delivery.settled":envelopeOf(`delivery.settled`,conforming()(z.object({deliveryId:id,outcome:known(),reason:z.string().optional(),turnId:id.optional()})))};export{deliverySchemas};

package/dist/src/protocol/session-events/families/interaction.d.ts

@@ -0,0 +1,163 @@
+import { z } from "#compiled/zod/index.js";
+import type { Cause, Envelope, JsonValue } from "../envelope.js";
+/** What an interaction is about. */
+export type InteractionSubject = {
+    readonly callId: string;
+} | {
+    readonly turnId: string;
+} | {
+    readonly taskId: string;
+} | {
+    readonly responseId: string;
+};
+/**
+ * What kind of thing a person is asked. A newer eve can add a kind: a reader shows one it doesn't
+ * know from the common fields, so its switch keeps a default branch.
+ */
+export type InteractionKind = "approval" | "question" | "sign-in" | "budget";
+/** How a request suggests showing its choices. A hint: a newer eve can add one. */
+export type InteractionDisplay = "confirmation" | "select" | "text";
+/** How an option suggests looking. A hint: a newer eve can add one. */
+export type InteractionOptionStyle = "primary" | "danger" | "default";
+export interface InteractionOption {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly style?: InteractionOptionStyle;
+}
+/**
+ * What a person is asked. Every request renders from the common fields, so a reader that doesn't
+ * know a kind can still show it and answer through options, free text, or the link.
+ */
+export interface InteractionRequest {
+    readonly kind: InteractionKind;
+    readonly prompt: string;
+    readonly title?: string;
+    readonly options?: readonly InteractionOption[];
+    readonly allowFreeform?: boolean;
+    readonly display?: InteractionDisplay;
+    readonly link?: {
+        readonly url: string;
+        readonly label?: string;
+    };
+    /** A sign-in's challenge. */
+    readonly signIn?: SignInChallenge;
+}
+/** What a sign-in asks the person to do, visible to the same readers as today. */
+export interface SignInChallenge {
+    /** The connection or tool that needs the sign-in. */
+    readonly name: string;
+    readonly displayName?: string;
+    readonly url?: string;
+    readonly userCode?: string;
+    readonly expiresAt?: string;
+    readonly instructions?: string;
+    readonly callbackUrl?: string;
+    /** The credential the sign-in grants, shared by every connection or tool that uses it. */
+    readonly grant?: string;
+    /**
+     * The connection principal the sign-in is for, without its attributes. `type` is open:
+     * `"user"`, which has an `id`, and `"app"` today.
+     */
+    readonly principal?: {
+        readonly type: string;
+        readonly id?: string;
+        readonly issuer?: string;
+    };
+}
+/** Where a relayed request was asked: the child session's request, and the call it asks about. */
+export interface InteractionOrigin {
+    readonly sessionId: string;
+    readonly interactionId: string;
+    /**
+     * The asker's call, when it asks about one, such as the tool a child wants approved. This
+     * session's tables hold only the call that delegated to the child.
+     */
+    readonly call?: {
+        readonly callId: string;
+        readonly name: string;
+        readonly input?: JsonValue;
+    };
+}
+export interface InteractionOpenedData {
+    readonly interactionId: string;
+    readonly subject: InteractionSubject;
+    readonly request: InteractionRequest;
+    /** The child session's request this one relays. */
+    readonly origin?: InteractionOrigin;
+    /** Who the request is for, such as the principal that started a sign-in. */
+    readonly audience?: {
+        readonly principalIds: readonly string[];
+    };
+}
+export type InteractionOutcome = "accepted" | "declined" | "invalid" | "failed" | "withdrawn" | "interrupted" | "abandoned" | "expired";
+export interface InteractionSettledData {
+    readonly interactionId: string;
+    readonly outcome: InteractionOutcome;
+    /** Open, such as `superseded-by-message` for a withdrawal. */
+    readonly reason?: string;
+    /** The response that decided it, or what else settled it. */
+    readonly cause?: Cause;
+    /** Kind-specific detail of the outcome, such as the chosen option. */
+    readonly response?: {
+        readonly [key: string]: JsonValue;
+    };
+}
+export type InteractionOpened = Envelope<"interaction.opened", InteractionOpenedData>;
+export type InteractionSettled = Envelope<"interaction.settled", InteractionSettledData>;
+export type InteractionFact = InteractionOpened | InteractionSettled;
+/** Zod schema for what a person is asked. */
+export declare const interactionRequestSchema: z.ZodObject<{
+    allowFreeform: z.ZodOptional<z.ZodBoolean>;
+    display: z.ZodOptional<z.ZodType<InteractionDisplay, unknown, z.core.$ZodTypeInternals<InteractionDisplay, unknown>>>;
+    kind: z.ZodType<InteractionKind, unknown, z.core.$ZodTypeInternals<InteractionKind, unknown>>;
+    link: z.ZodOptional<z.ZodObject<{
+        label: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+    }, z.core.$strip>>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        label: z.ZodString;
+        style: z.ZodOptional<z.ZodType<InteractionOptionStyle, unknown, z.core.$ZodTypeInternals<InteractionOptionStyle, unknown>>>;
+    }, z.core.$strip>>>;
+    prompt: z.ZodString;
+    signIn: z.ZodOptional<z.ZodObject<{
+        callbackUrl: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodOptional<z.ZodString>;
+        grant: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
+        name: z.ZodString;
+        principal: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            issuer: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+        }, z.core.$strip>>;
+        url: z.ZodOptional<z.ZodString>;
+        userCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const interactionSchemas: {
+    "interaction.opened": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"interaction.opened">;
+    }, z.core.$strip>;
+    "interaction.settled": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"interaction.settled">;
+    }, z.core.$strip>;
+};

package/dist/src/protocol/session-events/families/interaction.js

@@ -0,0 +1 @@
+import{cause,conforming,envelopeOf,id,jsonValue,known}from"../common.js";import{z}from"#compiled/zod/index.js";const subject=conforming()(z.union([z.object({callId:id}),z.object({turnId:id}),z.object({taskId:id}),z.object({responseId:id})])),interactionRequestSchema=conforming()(z.object({allowFreeform:z.boolean().optional(),display:known().optional(),kind:known(),link:z.object({label:z.string().optional(),url:z.string()}).optional(),options:z.array(z.object({description:z.string().optional(),id:z.string(),label:z.string(),style:known().optional()})).optional(),prompt:z.string(),signIn:z.object({callbackUrl:z.string().optional(),displayName:z.string().optional(),expiresAt:z.string().optional(),grant:z.string().optional(),instructions:z.string().optional(),name:z.string(),principal:z.object({id:z.string().optional(),issuer:z.string().optional(),type:z.string()}).optional(),url:z.string().optional(),userCode:z.string().optional()}).optional(),title:z.string().optional()})),interactionSchemas={"interaction.opened":envelopeOf(`interaction.opened`,conforming()(z.object({audience:z.object({principalIds:z.array(z.string())}).optional(),interactionId:id,origin:z.object({call:z.object({callId:id,input:jsonValue.optional(),name:z.string()}).optional(),interactionId:id,sessionId:id}).optional(),request:interactionRequestSchema,subject}))),"interaction.settled":envelopeOf(`interaction.settled`,conforming()(z.object({cause:cause.optional(),interactionId:id,outcome:known(),reason:z.string().optional(),response:z.record(z.string(),jsonValue).optional()})))};export{interactionRequestSchema,interactionSchemas};

package/dist/src/protocol/session-events/families/model.d.ts

@@ -0,0 +1,88 @@
+import { z } from "#compiled/zod/index.js";
+import type { Envelope, ErrorInfo } from "../envelope.js";
+/** What a model run belongs to: a turn, or a context change's summary. */
+export type ModelOwner = {
+    readonly turnId: string;
+} | {
+    readonly changeId: string;
+};
+export interface ModelRequestedData {
+    readonly runId: string;
+    readonly owner: ModelOwner;
+}
+/**
+ * An attempt at the run's provider call begins. Repeats while the run is open, once per attempt.
+ */
+export interface ModelStartedData {
+    readonly runId: string;
+    /** The model the run's participants chose. */
+    readonly modelId: string;
+    /**
+     * Which try at this model step this is: 0 for the first. A run that replaces one a retry gave
+     * up (after it published output) continues the count, so a run's first attempt can be above 0.
+     */
+    readonly attempt: number;
+}
+/** An attempt failed, and the same run tries again. The run's status doesn't change. */
+export interface ModelRetriedData {
+    readonly runId: string;
+    /** The attempt that failed. */
+    readonly attempt: number;
+    readonly error: ErrorInfo;
+}
+export type ModelOutcome = "completed" | "failed" | "interrupted" | "abandoned";
+export interface ModelSettledData {
+    readonly runId: string;
+    readonly outcome: ModelOutcome;
+    /** The provider's finish reason, as an open string: `stop`, `tool-calls`, `length`, …. */
+    readonly finishReason?: string;
+    readonly generationId?: string;
+    readonly error?: ErrorInfo;
+}
+export type ModelRequested = Envelope<"model.requested", ModelRequestedData>;
+export type ModelStarted = Envelope<"model.started", ModelStartedData>;
+export type ModelRetried = Envelope<"model.retried", ModelRetriedData>;
+export type ModelSettled = Envelope<"model.settled", ModelSettledData>;
+export type ModelFact = ModelRequested | ModelStarted | ModelRetried | ModelSettled;
+export declare const modelSchemas: {
+    "model.requested": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"model.requested">;
+    }, z.core.$strip>;
+    "model.retried": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"model.retried">;
+    }, z.core.$strip>;
+    "model.settled": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"model.settled">;
+    }, z.core.$strip>;
+    "model.started": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"model.started">;
+    }, z.core.$strip>;
+};

package/dist/src/protocol/session-events/families/model.js

@@ -0,0 +1 @@
+import{conforming,envelopeOf,errorInfo,id,known}from"../common.js";import{z}from"#compiled/zod/index.js";const attempt=z.number().int().nonnegative(),owner=conforming()(z.union([z.object({turnId:id}),z.object({changeId:id})])),modelSchemas={"model.requested":envelopeOf(`model.requested`,conforming()(z.object({owner,runId:id}))),"model.retried":envelopeOf(`model.retried`,conforming()(z.object({attempt,error:errorInfo,runId:id}))),"model.settled":envelopeOf(`model.settled`,conforming()(z.object({error:errorInfo.optional(),finishReason:z.string().optional(),generationId:z.string().optional(),outcome:known(),runId:id}))),"model.started":envelopeOf(`model.started`,conforming()(z.object({attempt,modelId:z.string(),runId:id})))};export{modelSchemas};

package/dist/src/protocol/session-events/families/response.d.ts

@@ -0,0 +1,66 @@
+import { z } from "#compiled/zod/index.js";
+import type { Envelope } from "../envelope.js";
+/** A person's answer. A sign-in callback's response carries none: its payload stays private. */
+export interface ResponseValue {
+    readonly optionId?: string;
+    readonly text?: string;
+}
+/**
+ * A person's answer to an interaction: the option they chose, what they wrote, or both. It's
+ * what a client submits and what `response.submitted` records as the response's value.
+ */
+export interface Answer extends ResponseValue {
+    readonly interactionId: string;
+}
+export interface ResponseSubmittedData {
+    readonly responseId: string;
+    readonly interactionId: string;
+    /** The delivery the answer arrived in; its principal is who answered. */
+    readonly deliveryId: string;
+    readonly value?: ResponseValue;
+}
+export interface ResponseAdmittedData {
+    readonly responseId: string;
+}
+export type ResponseOutcome = "applied" | "refused" | "failed" | "withdrawn" | "abandoned" | "expired";
+export interface ResponseSettledData {
+    readonly responseId: string;
+    readonly outcome: ResponseOutcome;
+    readonly reason?: string;
+}
+export type ResponseSubmitted = Envelope<"response.submitted", ResponseSubmittedData>;
+export type ResponseAdmitted = Envelope<"response.admitted", ResponseAdmittedData>;
+export type ResponseSettled = Envelope<"response.settled", ResponseSettledData>;
+export type ResponseFact = ResponseSubmitted | ResponseAdmitted | ResponseSettled;
+export declare const responseSchemas: {
+    "response.admitted": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"response.admitted">;
+    }, z.core.$strip>;
+    "response.settled": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"response.settled">;
+    }, z.core.$strip>;
+    "response.submitted": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"response.submitted">;
+    }, z.core.$strip>;
+};

package/dist/src/protocol/session-events/families/response.js

@@ -0,0 +1 @@
+import{conforming,envelopeOf,id,known}from"../common.js";import{z}from"#compiled/zod/index.js";const responseSchemas={"response.admitted":envelopeOf(`response.admitted`,conforming()(z.object({responseId:id}))),"response.settled":envelopeOf(`response.settled`,conforming()(z.object({outcome:known(),reason:z.string().optional(),responseId:id}))),"response.submitted":envelopeOf(`response.submitted`,conforming()(z.object({deliveryId:id,interactionId:id,responseId:id,value:z.object({optionId:z.string().optional(),text:z.string().optional()}).optional()})))};export{responseSchemas};

package/dist/src/protocol/session-events/families/session.d.ts

@@ -0,0 +1,73 @@
+import { z } from "#compiled/zod/index.js";
+import type { Cause, Envelope, ErrorInfo } from "../envelope.js";
+/** The eve instance serving a session, for eval reporters. */
+export interface RuntimeIdentity {
+    readonly agentId: string;
+    readonly agentName?: string;
+    readonly eveVersion: string;
+    readonly build?: {
+        readonly deployedAt?: string;
+        readonly gitBranch?: string;
+        readonly gitSha?: string;
+    };
+}
+/** W3C trace coordinates, for correlating a session with an observability backend. */
+export interface TraceContext {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly traceFlags: number;
+}
+/** The retired session replaced by this one; its recorded history stays readable. */
+export interface SessionPredecessor {
+    readonly sessionId: string;
+}
+export interface SessionStartedData {
+    /** The call whose agent opened this session, for a child session. */
+    readonly parent?: {
+        readonly sessionId: string;
+        readonly callId: string;
+    };
+    /**
+     * The session this one replaced, when eve started it in place of one whose deployment was
+     * retired. Its recorded stream stays readable.
+     */
+    readonly predecessor?: SessionPredecessor;
+    readonly runtime?: RuntimeIdentity;
+    readonly trace?: TraceContext;
+}
+export type SessionOutcome = "completed" | "failed";
+export interface SessionEndedData {
+    readonly outcome: SessionOutcome;
+    /**
+     * What failed, for a failed session, such as the `{turnId}` it failed in. The error is
+     * {@link SessionEndedData.error}: the turn settles `cancelled` without one of its own, and
+     * `failure(view, turnId)` reads this one for it.
+     */
+    readonly cause?: Cause;
+    readonly error?: ErrorInfo;
+}
+export type SessionStarted = Envelope<"session.started", SessionStartedData>;
+export type SessionEnded = Envelope<"session.ended", SessionEndedData>;
+export type SessionFact = SessionStarted | SessionEnded;
+export declare const sessionSchemas: {
+    "session.ended": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"session.ended">;
+    }, z.core.$strip>;
+    "session.started": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"session.started">;
+    }, z.core.$strip>;
+};

package/dist/src/protocol/session-events/families/session.js

@@ -0,0 +1 @@
+import{cause,conforming,envelopeOf,errorInfo,id,known}from"../common.js";import{z}from"#compiled/zod/index.js";const sessionStartedData=conforming()(z.object({parent:z.object({callId:id,sessionId:id}).optional(),predecessor:z.object({sessionId:id}).optional(),runtime:z.object({agentId:z.string(),agentName:z.string().optional(),build:z.object({deployedAt:z.string().optional(),gitBranch:z.string().optional(),gitSha:z.string().optional()}).optional(),eveVersion:z.string()}).optional(),trace:z.object({spanId:z.string(),traceFlags:z.number().int(),traceId:z.string()}).optional()})),sessionEndedData=conforming()(z.object({cause:cause.optional(),error:errorInfo.optional(),outcome:known()})),sessionSchemas={"session.ended":envelopeOf(`session.ended`,sessionEndedData),"session.started":envelopeOf(`session.started`,sessionStartedData)};export{sessionSchemas};

package/dist/src/protocol/session-events/families/task.d.ts

@@ -0,0 +1,46 @@
+import { z } from "#compiled/zod/index.js";
+import type { Envelope, ErrorInfo } from "../envelope.js";
+export interface TaskStartedData {
+    readonly taskId: string;
+    /** The call that started the task; it also gets `call.started {taskId}`. */
+    readonly startedBy: {
+        readonly callId: string;
+    };
+    /** `agent` for a subagent, `tool` for an authored tool. Open. */
+    readonly kind: "agent" | "tool" | (string & {});
+    readonly name: string;
+}
+export type TaskOutcome = "completed" | "failed" | "cancelled";
+export interface TaskEndedData {
+    readonly taskId: string;
+    readonly outcome: TaskOutcome;
+    /** Open: why a task was cancelled, such as `task-cancel`, `turn-cancelled`, or `session-ended`. */
+    readonly reason?: string;
+    readonly error?: ErrorInfo;
+}
+export type TaskStarted = Envelope<"task.started", TaskStartedData>;
+/** A task ends once; individual calls it serves settle separately with `call.settled`. */
+export type TaskEnded = Envelope<"task.ended", TaskEndedData>;
+export type TaskFact = TaskStarted | TaskEnded;
+export declare const taskSchemas: {
+    "task.ended": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"task.ended">;
+    }, z.core.$strip>;
+    "task.started": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"task.started">;
+    }, z.core.$strip>;
+};

package/dist/src/protocol/session-events/families/task.js

@@ -0,0 +1 @@
+import{conforming,envelopeOf,errorInfo,id,known}from"../common.js";import{z}from"#compiled/zod/index.js";const taskSchemas={"task.ended":envelopeOf(`task.ended`,conforming()(z.object({error:errorInfo.optional(),outcome:known(),reason:z.string().optional(),taskId:id}))),"task.started":envelopeOf(`task.started`,conforming()(z.object({kind:z.string(),name:z.string(),startedBy:z.object({callId:id}),taskId:id})))};export{taskSchemas};

package/dist/src/protocol/session-events/families/turn.d.ts

@@ -0,0 +1,68 @@
+import { z } from "#compiled/zod/index.js";
+import type { Cause, Envelope, ErrorInfo } from "../envelope.js";
+import type { TraceContext } from "./session.js";
+export interface TurnStartedData {
+    readonly turnId: string;
+    readonly cause: Cause;
+    /** The turn whose context this one continues; `null` after a clear, or for the first turn. */
+    readonly follows: string | null;
+    readonly trace?: TraceContext;
+}
+/**
+ * The turn waits on interactions: answers, approvals, or sign-ins that resume its work.
+ * The session announces it in the commit that leaves the turn so, and again when someone new
+ * is asked. A reader following the stream from a cursor stops here without folding what came
+ * before; one that folds reads the same from `waiting(view, turnId)`. Nothing announces the turn
+ * going on: its next model run or consumed delivery shows it.
+ */
+export interface TurnPausedData {
+    readonly turnId: string;
+    readonly awaiting: readonly {
+        readonly interactionId: string;
+    }[];
+}
+export type TurnOutcome = "completed" | "failed" | "cancelled";
+export interface TurnSettledData {
+    readonly turnId: string;
+    readonly outcome: TurnOutcome;
+    /** The content parts that answer the turn: its reply text, structured result, or files. */
+    readonly reply?: readonly string[];
+    readonly cause?: Cause;
+    readonly error?: ErrorInfo;
+}
+export type TurnStarted = Envelope<"turn.started", TurnStartedData>;
+export type TurnSettled = Envelope<"turn.settled", TurnSettledData>;
+export type TurnPaused = Envelope<"turn.paused", TurnPausedData>;
+export type TurnFact = TurnStarted | TurnPaused | TurnSettled;
+export declare const turnSchemas: {
+    "turn.paused": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"turn.paused">;
+    }, z.core.$strip>;
+    "turn.settled": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"turn.settled">;
+    }, z.core.$strip>;
+    "turn.started": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"turn.started">;
+    }, z.core.$strip>;
+};

package/dist/src/protocol/session-events/families/turn.js

@@ -0,0 +1 @@
+import{cause,conforming,envelopeOf,errorInfo,id,known}from"../common.js";import{z}from"#compiled/zod/index.js";const turnSchemas={"turn.paused":envelopeOf(`turn.paused`,conforming()(z.object({awaiting:z.array(z.object({interactionId:id})),turnId:id}))),"turn.settled":envelopeOf(`turn.settled`,conforming()(z.object({cause:cause.optional(),error:errorInfo.optional(),outcome:known(),reply:z.array(id).optional(),turnId:id}))),"turn.started":envelopeOf(`turn.started`,conforming()(z.object({cause,follows:id.nullable(),trace:z.object({spanId:z.string(),traceFlags:z.number().int(),traceId:z.string()}).optional(),turnId:id})))};export{turnSchemas};

package/dist/src/protocol/session-events/families/usage.d.ts

@@ -0,0 +1,30 @@
+import { z } from "#compiled/zod/index.js";
+import type { Envelope, Usage } from "../envelope.js";
+/** What spent the usage. Absent for usage nothing owns, such as cache warming. */
+export type UsageOwner = {
+    readonly runId: string;
+} | {
+    readonly callId: string;
+} | {
+    readonly changeId: string;
+};
+export interface UsageRecordedData {
+    readonly owner?: UsageOwner;
+    /** Open: `model` today. */
+    readonly kind: "model" | (string & {});
+    readonly usage: Usage;
+}
+export type UsageRecorded = Envelope<"usage.recorded", UsageRecordedData>;
+export type UsageFact = UsageRecorded;
+export declare const usageSchemas: {
+    "usage.recorded": z.ZodObject<{
+        data: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+        scope: z.ZodOptional<z.ZodObject<{
+            changeId: z.ZodOptional<z.ZodString>;
+            runId: z.ZodOptional<z.ZodString>;
+            taskId: z.ZodOptional<z.ZodString>;
+            turnId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        type: z.ZodLiteral<"usage.recorded">;
+    }, z.core.$strip>;
+};

package/dist/src/protocol/session-events/families/usage.js

@@ -0,0 +1 @@
+import{conforming,envelopeOf,id,usage}from"../common.js";import{z}from"#compiled/zod/index.js";const usageSchemas={"usage.recorded":envelopeOf(`usage.recorded`,conforming()(z.object({kind:z.string(),owner:z.union([z.object({runId:id}),z.object({callId:id}),z.object({changeId:id})]).optional(),usage})))};export{usageSchemas};