eve 0.83.3 → 0.84.0

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

@@ -0,0 +1,24 @@
+import type { CallFact, CallProgressRecord } from "./families/call.js";
+import type { ChildFact } from "./families/child.js";
+import type { ContentFact, ContentProgress } from "./families/content.js";
+import type { ContextFact } from "./families/context.js";
+import type { DeliveryFact } from "./families/delivery.js";
+import type { InteractionFact } from "./families/interaction.js";
+import type { ModelFact } from "./families/model.js";
+import type { ResponseFact } from "./families/response.js";
+import type { SessionFact } from "./families/session.js";
+import type { TaskFact } from "./families/task.js";
+import type { TurnFact } from "./families/turn.js";
+import type { UsageFact } from "./families/usage.js";
+/** A decision the machine made, or an observation it accepted. Facts are grouped by commit. */
+export type Fact = SessionFact | DeliveryFact | TurnFact | ModelFact | ContentFact | CallFact | TaskFact | InteractionFact | ResponseFact | ChildFact | ContextFact | UsageFact;
+/** A preview of a value a fact will complete. Never folded into the lifecycle tables. */
+export type Progress = ContentProgress | CallProgressRecord;
+/** The fact of one type. */
+export type FactOf<TType extends Fact["type"]> = Extract<Fact, {
+    readonly type: TType;
+}>;
+/** The progress record of one type. */
+export type ProgressOf<TType extends Progress["type"]> = Extract<Progress, {
+    readonly type: TType;
+}>;

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

@@ -0,0 +1 @@
+export{};

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

@@ -0,0 +1,142 @@
+import { z } from "#compiled/zod/index.js";
+import type { Cause, Envelope, ErrorInfo, JsonValue, ValueReference } from "../envelope.js";
+/** What a call belongs to: the model run that made it, or the call it runs inside. */
+export type CallOwner = {
+    readonly runId: string;
+} | {
+    readonly callId: string;
+};
+/**
+ * What a call can invoke: a tool, an agent, a skill to load, or `control`, the model managing its
+ * own tasks (waiting on or cancelling them), which readers showing activity usually leave out. A
+ * newer eve can add one: a reader's switch keeps a default branch.
+ */
+export type CapabilityKind = "tool" | "agent" | "skill" | "control";
+/** What a call invokes. */
+export interface Capability {
+    readonly kind: CapabilityKind;
+    readonly name: string;
+    readonly label?: string;
+    /** An `agent` another deployment serves: a remote agent, not a subagent of this one. */
+    readonly remote?: true;
+}
+/** A preview of a call's input as the model writes it. The first record announces the call. */
+export interface CallInputData {
+    readonly callId: string;
+    /** On the announcing record only: the entry the model calls, and what it invokes. */
+    readonly name?: string;
+    readonly kind?: CapabilityKind;
+    readonly delta: string;
+}
+export interface CallRequestedData {
+    readonly callId: string;
+    readonly owner: CallOwner;
+    readonly capability: Capability;
+    readonly input?: JsonValue;
+    readonly inputRef?: ValueReference;
+    /** The model's input didn't validate; the call settles `failed` and never runs. */
+    readonly inputError?: ErrorInfo;
+}
+/** What cleared a call to run. Absent when it needed no approval. */
+export type ClearedBy = {
+    readonly policy: string;
+} | {
+    readonly interactionId: string;
+};
+export interface CallStartedData {
+    readonly callId: string;
+    readonly clearedBy?: ClearedBy;
+    /** The task that serves the call. */
+    readonly taskId?: string;
+}
+/** A bounded snapshot of a call's output so far; the latest replaces earlier ones. */
+export interface CallProgressData {
+    readonly callId: string;
+    readonly output: JsonValue;
+    /** The call's label for this output, from the tool. */
+    readonly label?: string;
+}
+export type CallOutcome = "completed" | "failed" | "rejected" | "interrupted" | "abandoned";
+export interface CallSettledData {
+    readonly callId: string;
+    readonly outcome: CallOutcome;
+    readonly output?: JsonValue;
+    readonly outputRef?: ValueReference;
+    /** The call whose `call.settled` carries this call's output, for calls a reply settled together. */
+    readonly outputOf?: {
+        readonly callId: string;
+    };
+    readonly error?: ErrorInfo;
+    /** Open: `turn-cancelled` and `authorization-required` for interrupted calls, among others. */
+    readonly reason?: string;
+    /** Who rejected the call: `{interactionId}` or `{policy}`. */
+    readonly cause?: Cause;
+    /** The call's label once it settled, from the tool. */
+    readonly label?: string;
+}
+export type CallInput = Envelope<"call.input", CallInputData>;
+export type CallRequested = Envelope<"call.requested", CallRequestedData>;
+export type CallStarted = Envelope<"call.started", CallStartedData>;
+export type CallProgress = Envelope<"call.progress", CallProgressData>;
+export type CallSettled = Envelope<"call.settled", CallSettledData>;
+export type CallFact = CallRequested | CallStarted | CallSettled;
+export type CallProgressRecord = CallInput | CallProgress;
+export declare const clearedBySchema: z.ZodUnion<readonly [z.ZodObject<{
+    policy: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    interactionId: z.ZodString;
+}, z.core.$strip>]>;
+export declare const callSchemas: {
+    "call.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<"call.requested">;
+    }, z.core.$strip>;
+    "call.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<"call.settled">;
+    }, z.core.$strip>;
+    "call.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<"call.started">;
+    }, z.core.$strip>;
+};
+export declare const callProgressSchemas: {
+    "call.input": 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<"call.input">;
+    }, z.core.$strip>;
+    "call.progress": 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<"call.progress">;
+    }, z.core.$strip>;
+};

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

@@ -0,0 +1 @@
+import{cause,conforming,envelopeOf,errorInfo,id,jsonValue,known,valueReference}from"../common.js";import{z}from"#compiled/zod/index.js";const owner=conforming()(z.union([z.object({runId:id}),z.object({callId:id})])),clearedBySchema=conforming()(z.union([z.object({policy:z.string()}),z.object({interactionId:id})])),callSchemas={"call.requested":envelopeOf(`call.requested`,conforming()(z.object({callId:id,capability:z.object({kind:known(),name:z.string(),remote:z.literal(!0).optional(),label:z.string().optional()}),input:jsonValue.optional(),inputError:errorInfo.optional(),inputRef:valueReference.optional(),owner}))),"call.settled":envelopeOf(`call.settled`,conforming()(z.object({callId:id,cause:cause.optional(),error:errorInfo.optional(),outcome:known(),output:jsonValue.optional(),outputOf:z.object({callId:id}).optional(),outputRef:valueReference.optional(),reason:z.string().optional(),label:z.string().optional()}))),"call.started":envelopeOf(`call.started`,conforming()(z.object({callId:id,clearedBy:clearedBySchema.optional(),taskId:id.optional()})))},callProgressSchemas={"call.input":envelopeOf(`call.input`,conforming()(z.object({callId:id,delta:z.string(),kind:known().optional(),name:z.string().optional()}))),"call.progress":envelopeOf(`call.progress`,conforming()(z.object({callId:id,output:jsonValue,label:z.string().optional()})))};export{callProgressSchemas,callSchemas,clearedBySchema};

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

@@ -0,0 +1,51 @@
+import { z } from "#compiled/zod/index.js";
+import type { Envelope } from "../envelope.js";
+export interface ChildOpenedData {
+    /** The child session; its own lifecycle lives in its own stream. */
+    readonly sessionId: string;
+    readonly owner: {
+        readonly callId: string;
+    } | {
+        readonly taskId: string;
+    };
+    readonly name: string;
+    /** The route that serves the child's stream: its own, or the parent-origin proxy for a remote child. */
+    readonly stream: string;
+}
+/**
+ * A delivery a child session accepted for one of this session's calls. The child's own stream
+ * records the delivery's lifecycle as its `deliveryId`.
+ */
+export interface ChildSentData {
+    /** The child session that accepted the delivery. */
+    readonly sessionId: string;
+    /** The delivery's id in the child's stream, not one of this session's deliveries. */
+    readonly childDeliveryId: string;
+    /** The call the delivery was sent for. */
+    readonly callId: string;
+}
+export type ChildOpened = Envelope<"child.opened", ChildOpenedData>;
+export type ChildSent = Envelope<"child.sent", ChildSentData>;
+export type ChildFact = ChildOpened | ChildSent;
+export declare const childSchemas: {
+    "child.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<"child.opened">;
+    }, z.core.$strip>;
+    "child.sent": 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<"child.sent">;
+    }, z.core.$strip>;
+};

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

@@ -0,0 +1 @@
+import{conforming,envelopeOf,id}from"../common.js";import{z}from"#compiled/zod/index.js";const childSchemas={"child.opened":envelopeOf(`child.opened`,conforming()(z.object({name:z.string(),owner:z.union([z.object({callId:id}),z.object({taskId:id})]),sessionId:id,stream:z.string()}))),"child.sent":envelopeOf(`child.sent`,conforming()(z.object({callId:id,childDeliveryId:id,sessionId:id})))};export{childSchemas};

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

@@ -0,0 +1,56 @@
+import { z } from "#compiled/zod/index.js";
+import type { Envelope, JsonValue, ValueReference } from "../envelope.js";
+/** Wire parts use `kind`: `type` names the event. Authoring and UI parts use `type`. */
+/** A content part's kind. Open: `text`, `reasoning`, `result`, and `file` today. */
+export type ContentKind = "text" | "reasoning" | "result" | "file" | (string & {});
+/** Whether a part narrates work the turn continues with, or replies. Open; unknown reads as narration. */
+export type ContentPhase = "narration" | "reply" | (string & {});
+/** A preview of a part's value. The first record for a part announces it with its kind. */
+export interface ContentDeltaData {
+    readonly partId: string;
+    /** On the announcing record only. */
+    readonly kind?: ContentKind;
+    readonly delta: string;
+}
+export interface ContentCompletedData {
+    readonly partId: string;
+    readonly runId: string;
+    readonly kind: ContentKind;
+    /** The part's whole value: text for text and reasoning, JSON for a result, a file's metadata. */
+    readonly value?: JsonValue;
+    readonly valueRef?: ValueReference;
+    readonly phase: ContentPhase;
+    /** A cancel stopped the part; its value is what streamed. */
+    readonly interrupted?: true;
+    /** For kinds a reader doesn't know. */
+    readonly mediaType?: string;
+    readonly fallbackText?: string;
+}
+export type ContentDelta = Envelope<"content.delta", ContentDeltaData>;
+export type ContentCompleted = Envelope<"content.completed", ContentCompletedData>;
+export type ContentFact = ContentCompleted;
+export type ContentProgress = ContentDelta;
+export declare const contentSchemas: {
+    "content.completed": 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<"content.completed">;
+    }, z.core.$strip>;
+};
+export declare const contentProgressSchemas: {
+    "content.delta": 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<"content.delta">;
+    }, z.core.$strip>;
+};

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

@@ -0,0 +1 @@
+import{conforming,envelopeOf,id,jsonValue,valueReference}from"../common.js";import{z}from"#compiled/zod/index.js";const contentSchemas={"content.completed":envelopeOf(`content.completed`,conforming()(z.object({fallbackText:z.string().optional(),interrupted:z.literal(!0).optional(),kind:z.string(),mediaType:z.string().optional(),partId:id,phase:z.string(),runId:id,value:jsonValue.optional(),valueRef:valueReference.optional()})))},contentProgressSchemas={"content.delta":envelopeOf(`content.delta`,conforming()(z.object({delta:z.string(),kind:z.string().optional(),partId:id})))};export{contentProgressSchemas,contentSchemas};

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

@@ -0,0 +1,55 @@
+import { z } from "#compiled/zod/index.js";
+import type { Cause, Envelope, ErrorInfo } from "../envelope.js";
+/** A context change's kind. Open: `compaction` and `clear` today. */
+export type ContextKind = "compaction" | "clear" | (string & {});
+export interface ContextStartedData {
+    readonly changeId: string;
+    readonly kind: ContextKind;
+    /** The turn a threshold compaction ran in. */
+    readonly turnId?: string;
+    /** The control delivery for a manual change. */
+    readonly cause?: Cause;
+    /** What started a threshold compaction. */
+    readonly trigger?: {
+        readonly inputTokens: number;
+    };
+}
+export type ContextOutcome = "completed" | "failed" | "cancelled" | "interrupted";
+export interface ContextSettledData {
+    readonly changeId: string;
+    readonly kind: ContextKind;
+    readonly outcome: ContextOutcome;
+    /**
+     * The change's effect on the conversation: `null` empties it until the next turn, a turn
+     * selects that turn. Absent when the conversation is unchanged, as for a compaction.
+     */
+    readonly selects?: null | {
+        readonly turnId: string;
+    };
+    readonly error?: ErrorInfo;
+}
+export type ContextStarted = Envelope<"context.started", ContextStartedData>;
+export type ContextSettled = Envelope<"context.settled", ContextSettledData>;
+export type ContextFact = ContextStarted | ContextSettled;
+export declare const contextSchemas: {
+    "context.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<"context.settled">;
+    }, z.core.$strip>;
+    "context.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<"context.started">;
+    }, z.core.$strip>;
+};

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

@@ -0,0 +1 @@
+import{cause,conforming,envelopeOf,errorInfo,id,known}from"../common.js";import{z}from"#compiled/zod/index.js";const contextSchemas={"context.settled":envelopeOf(`context.settled`,conforming()(z.object({changeId:id,error:errorInfo.optional(),kind:z.string(),outcome:known(),selects:z.object({turnId:id}).nullable().optional()}))),"context.started":envelopeOf(`context.started`,conforming()(z.object({cause:cause.optional(),changeId:id,kind:z.string(),trigger:z.object({inputTokens:z.number().int().nonnegative()}).optional(),turnId:id.optional()})))};export{contextSchemas};

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};