@finalai/agent-provider 0.1.0

package/dist/modules/channel.d.mts

@@ -0,0 +1,382 @@
+import type { ContentBlock, SessionUpdate } from '@agentclientprotocol/sdk/experimental/v2';
+import * as z from 'zod';
+import type { ChannelSessionOperationsIface } from "./channel-context.mjs";
+import { type JsonObject, type JsonValue } from "./json.mjs";
+import type { ProviderRef } from "./provider-ref.mjs";
+import type { SemanticChannelEventKind } from "./semantic-events.mjs";
+export declare enum ConversationKind {
+    Direct = "direct",
+    Group = "group"
+}
+export declare enum ParticipantKind {
+    User = "user",
+    Agent = "agent",
+    System = "system"
+}
+export declare enum SystemParticipantKind {
+    Schedule = "schedule",
+    Webhook = "webhook",
+    Goal = "goal",
+    Tool = "tool",
+    ApiKey = "api-key"
+}
+export declare enum RoutingMode {
+    Mention = "mention",
+    All = "all",
+    Default = "default"
+}
+export declare enum TurnPolicy {
+    Steer = "steer",
+    Queue = "queue"
+}
+export declare enum Delivery {
+    Prompt = "prompt",
+    Observe = "observe"
+}
+export declare enum MessageKind {
+    Message = "message",
+    System = "system",
+    Card = "card"
+}
+export declare enum CardKind {
+    Elicitation = "elicitation",
+    Permission = "permission",
+    Notice = "notice"
+}
+export interface ParticipantIface {
+    id: string;
+    kind: ParticipantKind;
+    displayName: string;
+    userId: string | null;
+    servicePrincipalId?: string | null;
+    definitionId: string | null;
+    systemKind: SystemParticipantKind | null;
+    routingMode: RoutingMode | null;
+    sessionId: string | null;
+    supportsObserve: boolean | null;
+    rendersAuthorMeta: boolean | null;
+    left: boolean;
+}
+export declare const channelReceiveResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+    conversationId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strip>, z.ZodNull]>;
+export type ChannelReceiveResult = z.infer<typeof channelReceiveResultSchema>;
+export interface ConversationRefIface {
+    conversationId: string;
+}
+export interface ConversationIface extends ConversationRefIface {
+    organizationId: string;
+    kind: ConversationKind;
+    title: string | null;
+    isHome: boolean;
+    turnPolicy: TurnPolicy;
+}
+export interface MessageRefIface {
+    messageId: string;
+    seq: number;
+}
+export interface ConversationMessageIface extends MessageRefIface {
+    conversationId: string;
+    authorParticipantId: string;
+    kind: MessageKind;
+    body: string;
+    content: ContentBlock[];
+    replyToMessageId: string | null;
+    threadRootId: string | null;
+    quotedMessageIds: string[];
+    mentionedParticipantIds: string[];
+    hopDepth: number;
+    agentAuthorDefinitionId?: string | null;
+    createdAt: string;
+}
+export interface RouteArgsIface {
+    conversation: ConversationIface;
+    message: ConversationMessageIface;
+    participants: ParticipantIface[];
+    agentParticipantId?: string;
+}
+export interface RouteDecisionIface {
+    participantId: string;
+    delivery: Delivery;
+}
+export interface PostMessageArgsIface {
+    conversationId: string;
+    authorParticipantId: string;
+    kind?: MessageKind;
+    content: ContentBlock[];
+    replyToMessageId?: string | null;
+    threadRootId?: string | null;
+    quotedMessageIds?: string[];
+    clientMessageId?: string | null;
+    mentionedParticipantIds?: string[];
+    attachmentIds?: string[];
+    hopDepth?: number;
+    originTurnId?: string | null;
+    source?: {
+        turnId: string;
+        fromSeq: number;
+        toSeq: number;
+    } | null;
+}
+export declare const channelMessageInputSchema: z.ZodObject<{
+    conversationId: z.ZodString;
+    authorParticipantId: z.ZodString;
+    kind: z.ZodDefault<z.ZodEnum<typeof MessageKind>>;
+    content: z.ZodArray<z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
+    clientMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    replyToMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    threadRootId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    quotedMessageIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    mentionedParticipantIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export interface CardArgsIface {
+    conversationId: string;
+    authorParticipantId: string;
+    kind: CardKind;
+    pendingRequestId: string | null;
+    state: JsonObject;
+    entityLinks: {
+        kind: string;
+        id: string;
+        title?: string;
+        url?: string;
+        description?: string;
+        imageUrl?: string;
+    }[];
+}
+export interface PromptArgsIface {
+    waitForAcceptance?: boolean;
+    channelBinding?: {
+        id: string;
+        revisionId: string;
+    };
+    auth?: JsonObject | null;
+    title?: string;
+    participantId: string;
+    content: ContentBlock[];
+    turnPolicy: TurnPolicy;
+    replyExpected: boolean;
+    idempotencyKey: string;
+    authorParticipantId: string;
+    audienceParticipantIds: string[];
+    sourceMessageId: string;
+}
+export interface ObserveArgsIface {
+    participantId: string;
+    content: ContentBlock[];
+    idempotencyKey: string;
+}
+export interface ChannelPlatformIface {
+    channelSessions?: ChannelSessionOperationsIface;
+    conversations: {
+        get(conversationId: string): Promise<ConversationIface | null>;
+        createAttachmentUpload?(args: {
+            conversationId: string;
+            name: string;
+            contentType: string;
+            sizeBytes: number;
+        }): Promise<{
+            attachmentId: string;
+            uploadUrl: string;
+            method: string;
+            headers: Record<string, string>;
+            expiresAt: string;
+        }>;
+        getAttachmentUrl?(args: {
+            conversationId: string;
+            attachmentId: string;
+        }): Promise<{
+            attachmentId: string;
+            url: string;
+            expiresAt: string;
+        }>;
+        dispatchMessage?(args: {
+            conversationId: string;
+            messageId: string;
+            participantId?: string;
+            requestedDelivery?: Delivery;
+        }): Promise<void>;
+        findOrCreateDirect(args: {
+            organizationId: string;
+            userId: string;
+            definitionId: string;
+        }): Promise<ConversationIface>;
+        boundTo(bindingId: string): Promise<ConversationIface | null>;
+        participants(conversationId: string): Promise<ParticipantIface[]>;
+        systemParticipant(args: {
+            conversationId: string;
+            systemKind: SystemParticipantKind;
+            displayName: string;
+            sourceRef: string;
+        }): Promise<ParticipantIface>;
+        postMessage(args: PostMessageArgsIface): Promise<ConversationMessageIface>;
+        updateMessage(args: {
+            messageId: string;
+            content: ContentBlock[];
+            final: boolean;
+        }): Promise<void>;
+        postCard(args: CardArgsIface): Promise<ConversationMessageIface>;
+        updateCard(args: {
+            messageId: string;
+            state: JsonObject;
+        }): Promise<void>;
+        recentMessages(args: {
+            conversationId: string;
+            limit: number;
+            beforeSeq?: number;
+            afterSeq?: number;
+        }): Promise<ConversationMessageIface[]>;
+        getMessages(args: {
+            conversationId: string;
+            messageIds: string[];
+        }): Promise<ConversationMessageIface[]>;
+    };
+    sessions: {
+        prompt(args: PromptArgsIface): Promise<{
+            messageId: string;
+            sessionId?: string;
+            turnId?: string;
+        }>;
+        observe(args: ObserveArgsIface): Promise<void>;
+        cancel(args: {
+            participantId: string;
+            reason?: string;
+            throughMessageSeq?: number;
+        }): Promise<void>;
+        respond?(args: ChannelInputResponseIface): Promise<{
+            resolved: boolean;
+        }>;
+    };
+    log(message: string, details?: Record<string, JsonValue>): void;
+}
+export interface ChannelInputResponseIface {
+    channelBinding?: {
+        id: string;
+        revisionId: string;
+    };
+    auth?: JsonObject | null;
+    participantId: string;
+    pendingId: string;
+    outcome: JsonValue;
+    actorParticipantId: string;
+    userId: string | null;
+    apiKeyId: string | null;
+}
+export interface ChannelReceiveContextIface {
+    platform: ChannelPlatformIface;
+    organizationId: string;
+    definitionId: string | null;
+    bindingId: string | null;
+    config: JsonObject;
+    secrets: {
+        get(name: string): Promise<string | null>;
+    };
+    agentParticipantId?: string;
+    message?: ConversationMessageIface;
+    conversation?: ConversationIface;
+    participants?: readonly ParticipantIface[];
+    response?: ChannelInputResponseIface;
+    conversationId?: string;
+    cancelReason?: string;
+    cancelThroughMessageSeq?: number;
+    requestedDelivery?: Delivery;
+}
+export interface ChannelRouteContextIface {
+    request: Request;
+    secrets: {
+        get(name: string): Promise<string | null>;
+    };
+    receive: (input: JsonValue) => Promise<ChannelReceiveResult>;
+}
+export interface ChannelSocketIface {
+    readonly signal: AbortSignal;
+    readonly messages: AsyncIterable<string | Uint8Array>;
+    accept(options?: {
+        protocol?: string;
+    }): void;
+    send(data: string | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+}
+export interface HttpChannelRouteDefinitionIface {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    path: string;
+    handler: (args: ChannelRouteContextIface) => Promise<Response>;
+}
+export interface WebSocketChannelRouteDefinitionIface {
+    method: 'WS';
+    path: string;
+    handler: (args: ChannelRouteContextIface & {
+        socket: ChannelSocketIface;
+    }) => Promise<Response | void>;
+}
+export type RouteDefinitionIface = HttpChannelRouteDefinitionIface | WebSocketChannelRouteDefinitionIface;
+export interface ChannelTurnStateIface<State> {
+    get(): State | null;
+    set(state: State | null): void;
+}
+export interface ProjectionContextIface<State = JsonValue> {
+    sessionId?: string;
+    platform: ChannelPlatformIface;
+    conversation: ConversationIface | null;
+    agentParticipant: ParticipantIface | null;
+    turn: {
+        id: string;
+        promptMessageId: string | null;
+        authorParticipantId: string | null;
+    };
+    seq: number;
+    state: ChannelTurnStateIface<State>;
+}
+export declare enum PendingEventKind {
+    Created = "pending.created",
+    Resolved = "pending.resolved"
+}
+export type AcpUpdateKind = SessionUpdate['sessionUpdate'];
+export type ChannelEventKind = AcpUpdateKind | `${PendingEventKind}` | `${SemanticChannelEventKind}`;
+export interface ChannelEventIface {
+    type: string;
+    data: JsonValue;
+    seq: number;
+}
+export type ChannelEventHandler<State = JsonValue> = (event: ChannelEventIface, ctx: ProjectionContextIface<State>) => Promise<void>;
+export declare enum PendingKind {
+    Permission = "permission",
+    Elicitation = "elicitation"
+}
+export declare const pendingCreatedDataSchema: z.ZodObject<{
+    pendingRequestId: z.ZodString;
+    kind: z.ZodEnum<typeof PendingKind>;
+    audienceParticipantIds: z.ZodArray<z.ZodString>;
+    request: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
+}, z.core.$strip>;
+export type PendingCreatedDataIface = z.infer<typeof pendingCreatedDataSchema>;
+export declare const pendingResolvedDataSchema: z.ZodObject<{
+    pendingRequestId: z.ZodString;
+    outcome: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
+}, z.core.$strip>;
+export type PendingResolvedDataIface = z.infer<typeof pendingResolvedDataSchema>;
+export declare const PROJECTED_UPDATE_KINDS: ReadonlySet<AcpUpdateKind>;
+export declare const turnEndOf: (update: SessionUpdate) => {
+    stopReason: string | null;
+} | null;
+export declare const turnEndUpdate: (stopReason: string | null) => SessionUpdate;
+export interface ChannelDefinitionIface<Inbound, State = undefined> {
+    config?: JsonObject;
+    installed?: ProviderRef;
+    configure?: (config: JsonObject) => ChannelDefinitionIface<Inbound, State>;
+    routes?: RouteDefinitionIface[];
+    respond?(input: ChannelInputResponseIface, ctx: ChannelReceiveContextIface): Promise<{
+        resolved: boolean;
+    }>;
+    cancel?(ctx: ChannelReceiveContextIface): Promise<{
+        accepted: boolean;
+    }>;
+    receive(input: Inbound, ctx: ChannelReceiveContextIface): Promise<ChannelReceiveResult>;
+    route(args: RouteArgsIface): RouteDecisionIface[] | Promise<RouteDecisionIface[]>;
+    turnPolicy: TurnPolicy;
+    project(update: SessionUpdate, ctx: ProjectionContextIface<State>): Promise<void>;
+    events?: Partial<Record<ChannelEventKind, ChannelEventHandler<State>>>;
+}
+export declare const defineChannel: <Inbound, State = undefined>(definition: ChannelDefinitionIface<Inbound, State>) => ChannelDefinitionIface<Inbound, State>;

package/dist/modules/channel.mjs

@@ -0,0 +1,146 @@
+import * as z from "zod";
+import { jsonObjectSchema, jsonValueSchema } from "./json.mjs";
+var ConversationKind = /* @__PURE__ */ ((ConversationKind2) => {
+  ConversationKind2["Direct"] = "direct";
+  ConversationKind2["Group"] = "group";
+  return ConversationKind2;
+})(ConversationKind || {});
+var ParticipantKind = /* @__PURE__ */ ((ParticipantKind2) => {
+  ParticipantKind2["User"] = "user";
+  ParticipantKind2["Agent"] = "agent";
+  ParticipantKind2["System"] = "system";
+  return ParticipantKind2;
+})(ParticipantKind || {});
+var SystemParticipantKind = /* @__PURE__ */ ((SystemParticipantKind2) => {
+  SystemParticipantKind2["Schedule"] = "schedule";
+  SystemParticipantKind2["Webhook"] = "webhook";
+  SystemParticipantKind2["Goal"] = "goal";
+  SystemParticipantKind2["Tool"] = "tool";
+  SystemParticipantKind2["ApiKey"] = "api-key";
+  return SystemParticipantKind2;
+})(SystemParticipantKind || {});
+var RoutingMode = /* @__PURE__ */ ((RoutingMode2) => {
+  RoutingMode2["Mention"] = "mention";
+  RoutingMode2["All"] = "all";
+  RoutingMode2["Default"] = "default";
+  return RoutingMode2;
+})(RoutingMode || {});
+var TurnPolicy = /* @__PURE__ */ ((TurnPolicy2) => {
+  TurnPolicy2["Steer"] = "steer";
+  TurnPolicy2["Queue"] = "queue";
+  return TurnPolicy2;
+})(TurnPolicy || {});
+var Delivery = /* @__PURE__ */ ((Delivery2) => {
+  Delivery2["Prompt"] = "prompt";
+  Delivery2["Observe"] = "observe";
+  return Delivery2;
+})(Delivery || {});
+var MessageKind = /* @__PURE__ */ ((MessageKind2) => {
+  MessageKind2["Message"] = "message";
+  MessageKind2["System"] = "system";
+  MessageKind2["Card"] = "card";
+  return MessageKind2;
+})(MessageKind || {});
+var CardKind = /* @__PURE__ */ ((CardKind2) => {
+  CardKind2["Elicitation"] = "elicitation";
+  CardKind2["Permission"] = "permission";
+  CardKind2["Notice"] = "notice";
+  return CardKind2;
+})(CardKind || {});
+const channelReceiveResultSchema = z.union([
+  z.object({ conversationId: z.string().min(1) }),
+  z.object({ sessionId: z.string().min(1) }),
+  z.null()
+]);
+const channelMessageInputSchema = z.object({
+  conversationId: z.string().min(1),
+  authorParticipantId: z.string().min(1),
+  kind: z.nativeEnum(MessageKind).default("message" /* Message */),
+  content: z.array(jsonObjectSchema).min(1),
+  clientMessageId: z.string().min(1).nullish(),
+  replyToMessageId: z.string().min(1).nullish(),
+  threadRootId: z.string().min(1).nullish(),
+  quotedMessageIds: z.array(z.string().min(1)).default([]),
+  mentionedParticipantIds: z.array(z.string().min(1)).default([])
+});
+var PendingEventKind = /* @__PURE__ */ ((PendingEventKind2) => {
+  PendingEventKind2["Created"] = "pending.created";
+  PendingEventKind2["Resolved"] = "pending.resolved";
+  return PendingEventKind2;
+})(PendingEventKind || {});
+var PendingKind = /* @__PURE__ */ ((PendingKind2) => {
+  PendingKind2["Permission"] = "permission";
+  PendingKind2["Elicitation"] = "elicitation";
+  return PendingKind2;
+})(PendingKind || {});
+const pendingCreatedDataSchema = z.object({
+  pendingRequestId: z.string().min(1),
+  kind: z.nativeEnum(PendingKind),
+  audienceParticipantIds: z.array(z.string()),
+  request: jsonValueSchema
+});
+const pendingResolvedDataSchema = z.object({
+  pendingRequestId: z.string().min(1),
+  outcome: jsonValueSchema
+});
+const PROJECTED_UPDATE_KINDS = /* @__PURE__ */ new Set([
+  "agent_message_chunk",
+  "agent_message"
+]);
+const turnEndSchema = z.looseObject({
+  sessionUpdate: z.literal("state_update"),
+  state: z.literal("idle"),
+  stopReason: z.string().nullish(),
+  _meta: z.looseObject({ "final.ai": z.looseObject({ stopReason: z.string().nullish() }).nullish() }).nullish()
+});
+const turnEndOf = (update) => {
+  const parsed = turnEndSchema.safeParse(update);
+  if (!parsed.success) return null;
+  return {
+    stopReason: parsed.data.stopReason ?? parsed.data._meta?.["final.ai"]?.stopReason ?? null
+  };
+};
+const turnEndUpdate = (stopReason) => {
+  switch (stopReason) {
+    case null:
+      return { sessionUpdate: "state_update", state: "idle" };
+    case "end_turn":
+      return { sessionUpdate: "state_update", state: "idle", stopReason: "end_turn" };
+    case "max_tokens":
+      return { sessionUpdate: "state_update", state: "idle", stopReason: "max_tokens" };
+    case "max_turn_requests":
+      return { sessionUpdate: "state_update", state: "idle", stopReason: "max_turn_requests" };
+    case "refusal":
+      return { sessionUpdate: "state_update", state: "idle", stopReason: "refusal" };
+    case "cancelled":
+      return { sessionUpdate: "state_update", state: "idle", stopReason: "cancelled" };
+    default:
+      return {
+        sessionUpdate: "state_update",
+        state: "idle",
+        _meta: { "final.ai": { stopReason } }
+      };
+  }
+};
+const defineChannel = (definition) => definition;
+export {
+  CardKind,
+  ConversationKind,
+  Delivery,
+  MessageKind,
+  PROJECTED_UPDATE_KINDS,
+  ParticipantKind,
+  PendingEventKind,
+  PendingKind,
+  RoutingMode,
+  SystemParticipantKind,
+  TurnPolicy,
+  channelMessageInputSchema,
+  channelReceiveResultSchema,
+  defineChannel,
+  pendingCreatedDataSchema,
+  pendingResolvedDataSchema,
+  turnEndOf,
+  turnEndUpdate
+};
+//# sourceMappingURL=channel.mjs.map

package/dist/modules/channel.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/channel.ts"],
+  "sourcesContent": ["import type { ContentBlock, SessionUpdate } from '@agentclientprotocol/sdk/experimental/v2';\nimport * as z from 'zod';\nimport type { ChannelSessionOperationsIface } from \"./channel-context.mjs\";\nimport { jsonObjectSchema, jsonValueSchema, type JsonObject, type JsonValue } from \"./json.mjs\";\nimport type { ProviderRef } from \"./provider-ref.mjs\";\nimport type { SemanticChannelEventKind } from \"./semantic-events.mjs\";\n\n// Channels. Messaging has no orchestrator: a channel\n// receives input, inserts it into the conversation, routes it to agent\n// participants as ACP prompt or observe, and projects ACP updates back into\n// visible messages and cards. The built-in messaging channels implement this\n// contract with no private hooks into the session service; the session\n// service hands every channel the same ChannelPlatformIface.\n\nexport enum ConversationKind {\n  Direct = 'direct',\n  Group = 'group',\n}\n\nexport enum ParticipantKind {\n  User = 'user',\n  Agent = 'agent',\n  System = 'system',\n}\n\nexport enum SystemParticipantKind {\n  Schedule = 'schedule',\n  Webhook = 'webhook',\n  Goal = 'goal',\n  Tool = 'tool',\n  ApiKey = 'api-key',\n}\n\nexport enum RoutingMode {\n  Mention = 'mention',\n  All = 'all',\n  Default = 'default',\n}\n\nexport enum TurnPolicy {\n  Steer = 'steer',\n  Queue = 'queue',\n}\n\nexport enum Delivery {\n  Prompt = 'prompt',\n  Observe = 'observe',\n}\n\nexport enum MessageKind {\n  Message = 'message',\n  System = 'system',\n  Card = 'card',\n}\n\nexport enum CardKind {\n  Elicitation = 'elicitation',\n  Permission = 'permission',\n  Notice = 'notice',\n}\n\nexport interface ParticipantIface {\n  id: string;\n  kind: ParticipantKind;\n  displayName: string;\n  userId: string | null;\n  servicePrincipalId?: string | null;\n  definitionId: string | null;\n  systemKind: SystemParticipantKind | null;\n  routingMode: RoutingMode | null;\n  sessionId: string | null;\n  // Whether the agent's harness supports _final/session/observe and renders\n  // _meta[\"final.ai\"].author; null for non-agents.\n  supportsObserve: boolean | null;\n  rendersAuthorMeta: boolean | null;\n  left: boolean;\n}\n\nexport const channelReceiveResultSchema = z.union([\n  z.object({ conversationId: z.string().min(1) }),\n  z.object({ sessionId: z.string().min(1) }),\n  z.null(),\n]);\nexport type ChannelReceiveResult = z.infer<typeof channelReceiveResultSchema>;\n\nexport interface ConversationRefIface {\n  conversationId: string;\n}\n\nexport interface ConversationIface extends ConversationRefIface {\n  organizationId: string;\n  kind: ConversationKind;\n  title: string | null;\n  isHome: boolean;\n  turnPolicy: TurnPolicy;\n}\n\nexport interface MessageRefIface {\n  messageId: string;\n  seq: number;\n}\n\nexport interface ConversationMessageIface extends MessageRefIface {\n  conversationId: string;\n  authorParticipantId: string;\n  kind: MessageKind;\n  body: string;\n  content: ContentBlock[];\n  replyToMessageId: string | null;\n  threadRootId: string | null;\n  // Earlier messages of the conversation the author quoted, in order.\n  quotedMessageIds: string[];\n  // Agent participant ids explicitly mentioned in the message.\n  mentionedParticipantIds: string[];\n  // Number of agent-authored hops that led to this message (0 for humans).\n  hopDepth: number;\n  // The originating agent for a tool-posted message, including linked conversations.\n  agentAuthorDefinitionId?: string | null;\n  createdAt: string;\n}\n\nexport interface RouteArgsIface {\n  conversation: ConversationIface;\n  message: ConversationMessageIface;\n  participants: ParticipantIface[];\n  agentParticipantId?: string;\n}\n\nexport interface RouteDecisionIface {\n  participantId: string;\n  delivery: Delivery;\n}\n\nexport interface PostMessageArgsIface {\n  conversationId: string;\n  authorParticipantId: string;\n  kind?: MessageKind;\n  content: ContentBlock[];\n  replyToMessageId?: string | null;\n  threadRootId?: string | null;\n  quotedMessageIds?: string[];\n  clientMessageId?: string | null;\n  mentionedParticipantIds?: string[];\n  attachmentIds?: string[];\n  hopDepth?: number;\n  // A tool or linked-conversation event carries the turn that produced it.\n  originTurnId?: string | null;\n  // Projection provenance for agent replies.\n  source?: { turnId: string; fromSeq: number; toSeq: number } | null;\n}\n\nexport const channelMessageInputSchema = z.object({\n  conversationId: z.string().min(1),\n  authorParticipantId: z.string().min(1),\n  kind: z.nativeEnum(MessageKind).default(MessageKind.Message),\n  content: z.array(jsonObjectSchema).min(1),\n  clientMessageId: z.string().min(1).nullish(),\n  replyToMessageId: z.string().min(1).nullish(),\n  threadRootId: z.string().min(1).nullish(),\n  quotedMessageIds: z.array(z.string().min(1)).default([]),\n  mentionedParticipantIds: z.array(z.string().min(1)).default([]),\n});\n\nexport interface CardArgsIface {\n  conversationId: string;\n  authorParticipantId: string;\n  kind: CardKind;\n  pendingRequestId: string | null;\n  // Generic cards only: a title, body, options, and entity links (a Goal is an\n  // entity link, not a card kind).\n  state: JsonObject;\n  entityLinks: {\n    kind: string;\n    id: string;\n    title?: string;\n    url?: string;\n    description?: string;\n    imageUrl?: string;\n  }[];\n}\n\nexport interface PromptArgsIface {\n  waitForAcceptance?: boolean;\n  channelBinding?: { id: string; revisionId: string };\n  auth?: JsonObject | null;\n  title?: string;\n  participantId: string;\n  content: ContentBlock[];\n  turnPolicy: TurnPolicy;\n  replyExpected: boolean;\n  idempotencyKey: string;\n  // Who prompted (for payer resolution and pending-request audience).\n  authorParticipantId: string;\n  audienceParticipantIds: string[];\n  sourceMessageId: string;\n}\n\nexport interface ObserveArgsIface {\n  participantId: string;\n  content: ContentBlock[];\n  idempotencyKey: string;\n}\n\n// What the session service lets a channel do. Implemented once, handed to\n// built-in and custom channels alike.\nexport interface ChannelPlatformIface {\n  channelSessions?: ChannelSessionOperationsIface;\n  conversations: {\n    get(conversationId: string): Promise<ConversationIface | null>;\n    createAttachmentUpload?(args: {\n      conversationId: string;\n      name: string;\n      contentType: string;\n      sizeBytes: number;\n    }): Promise<{\n      attachmentId: string;\n      uploadUrl: string;\n      method: string;\n      headers: Record<string, string>;\n      expiresAt: string;\n    }>;\n    getAttachmentUrl?(args: {\n      conversationId: string;\n      attachmentId: string;\n    }): Promise<{ attachmentId: string; url: string; expiresAt: string }>;\n    // Dispatch a stored reply to each recipient's binding; each channel owns routing.\n    dispatchMessage?(args: {\n      conversationId: string;\n      messageId: string;\n      participantId?: string;\n      requestedDelivery?: Delivery;\n    }): Promise<void>;\n    findOrCreateDirect(args: {\n      organizationId: string;\n      userId: string;\n      definitionId: string;\n    }): Promise<ConversationIface>;\n    // The conversation a channel binding is attached to.\n    boundTo(bindingId: string): Promise<ConversationIface | null>;\n    participants(conversationId: string): Promise<ParticipantIface[]>;\n    systemParticipant(args: {\n      conversationId: string;\n      systemKind: SystemParticipantKind;\n      displayName: string;\n      sourceRef: string;\n    }): Promise<ParticipantIface>;\n    postMessage(args: PostMessageArgsIface): Promise<ConversationMessageIface>;\n    updateMessage(args: {\n      messageId: string;\n      content: ContentBlock[];\n      final: boolean;\n    }): Promise<void>;\n    postCard(args: CardArgsIface): Promise<ConversationMessageIface>;\n    updateCard(args: { messageId: string; state: JsonObject }): Promise<void>;\n    recentMessages(args: {\n      conversationId: string;\n      limit: number;\n      beforeSeq?: number;\n      afterSeq?: number;\n    }): Promise<ConversationMessageIface[]>;\n    // Messages of the conversation by id, however old (reply, thread and quote\n    // context outside the recent window); unknown and deleted ones are absent.\n    getMessages(args: {\n      conversationId: string;\n      messageIds: string[];\n    }): Promise<ConversationMessageIface[]>;\n  };\n  sessions: {\n    prompt(\n      args: PromptArgsIface,\n    ): Promise<{ messageId: string; sessionId?: string; turnId?: string }>;\n    observe(args: ObserveArgsIface): Promise<void>;\n    cancel(args: {\n      participantId: string;\n      reason?: string;\n      throughMessageSeq?: number;\n    }): Promise<void>;\n    respond?(args: ChannelInputResponseIface): Promise<{ resolved: boolean }>;\n  };\n  log(message: string, details?: Record<string, JsonValue>): void;\n}\n\nexport interface ChannelInputResponseIface {\n  channelBinding?: { id: string; revisionId: string };\n  auth?: JsonObject | null;\n  participantId: string;\n  pendingId: string;\n  outcome: JsonValue;\n  actorParticipantId: string;\n  userId: string | null;\n  apiKeyId: string | null;\n}\n\nexport interface ChannelReceiveContextIface {\n  platform: ChannelPlatformIface;\n  organizationId: string;\n  definitionId: string | null;\n  bindingId: string | null;\n  config: JsonObject;\n  secrets: { get(name: string): Promise<string | null> };\n  // A stored, authenticated delivery to one agent in a shared conversation.\n  agentParticipantId?: string;\n  message?: ConversationMessageIface;\n  conversation?: ConversationIface;\n  participants?: readonly ParticipantIface[];\n  response?: ChannelInputResponseIface;\n  conversationId?: string;\n  cancelReason?: string;\n  // Preserve this boundary when forwarding a retryable conversation Stop.\n  cancelThroughMessageSeq?: number;\n  requestedDelivery?: Delivery;\n}\n\n// An HTTP route a channel serves (webhooks), mounted by the front door at\n// /api/events/webhooks/:bindingId<path> and the per-agent aliases.\nexport interface ChannelRouteContextIface {\n  request: Request;\n  secrets: { get(name: string): Promise<string | null> };\n  receive: (input: JsonValue) => Promise<ChannelReceiveResult>;\n}\n\nexport interface ChannelSocketIface {\n  readonly signal: AbortSignal;\n  readonly messages: AsyncIterable<string | Uint8Array>;\n  // Authenticate the request before accepting. The selected protocol must have been offered.\n  accept(options?: { protocol?: string }): void;\n  send(data: string | Uint8Array): void;\n  close(code?: number, reason?: string): void;\n}\n\nexport interface HttpChannelRouteDefinitionIface {\n  method: 'GET' | 'POST' | 'PUT' | 'DELETE';\n  path: string;\n  handler: (args: ChannelRouteContextIface) => Promise<Response>;\n}\n\nexport interface WebSocketChannelRouteDefinitionIface {\n  method: 'WS';\n  path: string;\n  // Returning an HTTP response before accept rejects the handshake. The handler lives until close.\n  handler: (\n    args: ChannelRouteContextIface & { socket: ChannelSocketIface },\n  ) => Promise<Response | void>;\n}\n\nexport type RouteDefinitionIface =\n  | HttpChannelRouteDefinitionIface\n  | WebSocketChannelRouteDefinitionIface;\n\n// The per-turn value a channel keeps between its project and event calls of\n// one turn (the definition's `State`). The platform holds it, so a channel\n// running in a Worker isolate keeps nothing in memory; it starts null each turn\n// and is discarded when the turn's projection finishes.\nexport interface ChannelTurnStateIface<State> {\n  get(): State | null;\n  set(state: State | null): void;\n}\n\nexport interface ProjectionContextIface<State = JsonValue> {\n  sessionId?: string;\n  platform: ChannelPlatformIface;\n  conversation: ConversationIface | null;\n  agentParticipant: ParticipantIface | null;\n  turn: { id: string; promptMessageId: string | null; authorParticipantId: string | null };\n  seq: number;\n  state: ChannelTurnStateIface<State>;\n}\n\nexport enum PendingEventKind {\n  Created = 'pending.created',\n  Resolved = 'pending.resolved',\n}\n\nexport type AcpUpdateKind = SessionUpdate['sessionUpdate'];\n\nexport type ChannelEventKind =\n  | AcpUpdateKind\n  | `${PendingEventKind}`\n  | `${SemanticChannelEventKind}`;\n\nexport interface ChannelEventIface {\n  type: string;\n  data: JsonValue;\n  seq: number;\n}\n\nexport type ChannelEventHandler<State = JsonValue> = (\n  event: ChannelEventIface,\n  ctx: ProjectionContextIface<State>,\n) => Promise<void>;\n\nexport enum PendingKind {\n  Permission = 'permission',\n  Elicitation = 'elicitation',\n}\n\n// `data` of a pending.created event: an ACP session/request_permission or\n// elicitation/create request awaiting its audience.\nexport const pendingCreatedDataSchema = z.object({\n  pendingRequestId: z.string().min(1),\n  kind: z.nativeEnum(PendingKind),\n  audienceParticipantIds: z.array(z.string()),\n  request: jsonValueSchema,\n});\n\nexport type PendingCreatedDataIface = z.infer<typeof pendingCreatedDataSchema>;\n\n// `data` of a pending.resolved event: the answer (or cancellation) as recorded.\nexport const pendingResolvedDataSchema = z.object({\n  pendingRequestId: z.string().min(1),\n  outcome: jsonValueSchema,\n});\n\nexport type PendingResolvedDataIface = z.infer<typeof pendingResolvedDataSchema>;\n\n// The visible-output updates `project` receives. After them, the\n// turn's projection ends with one ACP v2 idle `state_update` (turnEndUpdate).\n// Thought, tool, plan and every other update, other state updates included,\n// reach a channel only through an `events` handler for its kind.\nexport const PROJECTED_UPDATE_KINDS: ReadonlySet<AcpUpdateKind> = new Set<AcpUpdateKind>([\n  'agent_message_chunk',\n  'agent_message',\n]);\n\nconst turnEndSchema = z.looseObject({\n  sessionUpdate: z.literal('state_update'),\n  state: z.literal('idle'),\n  stopReason: z.string().nullish(),\n  _meta: z\n    .looseObject({ 'final.ai': z.looseObject({ stopReason: z.string().nullish() }).nullish() })\n    .nullish(),\n});\n\n// The stop reason when the update ends the turn (an idle state_update); null otherwise.\nexport const turnEndOf = (update: SessionUpdate): { stopReason: string | null } | null => {\n  const parsed = turnEndSchema.safeParse(update);\n  if (!parsed.success) return null;\n  return {\n    stopReason: parsed.data.stopReason ?? parsed.data._meta?.['final.ai']?.stopReason ?? null,\n  };\n};\n\n// The idle state_update that ends a turn, as `project` receives it. A stop\n// reason outside ACP's known set rides in `_meta[\"final.ai\"]` (the SDK types\n// only received values as unknown variants).\nexport const turnEndUpdate = (stopReason: string | null): SessionUpdate => {\n  switch (stopReason) {\n    case null:\n      return { sessionUpdate: 'state_update', state: 'idle' };\n    case 'end_turn':\n      return { sessionUpdate: 'state_update', state: 'idle', stopReason: 'end_turn' };\n    case 'max_tokens':\n      return { sessionUpdate: 'state_update', state: 'idle', stopReason: 'max_tokens' };\n    case 'max_turn_requests':\n      return { sessionUpdate: 'state_update', state: 'idle', stopReason: 'max_turn_requests' };\n    case 'refusal':\n      return { sessionUpdate: 'state_update', state: 'idle', stopReason: 'refusal' };\n    case 'cancelled':\n      return { sessionUpdate: 'state_update', state: 'idle', stopReason: 'cancelled' };\n    default:\n      return {\n        sessionUpdate: 'state_update',\n        state: 'idle',\n        _meta: { 'final.ai': { stopReason } },\n      };\n  }\n};\n\n// Built-in and custom (bundle) channels implement exactly this; the\n// session service calls nothing else on a channel.\nexport interface ChannelDefinitionIface<Inbound, State = undefined> {\n  config?: JsonObject;\n  // Installed execution is an optimization for an uncustomized definition.\n  installed?: ProviderRef;\n  configure?: (config: JsonObject) => ChannelDefinitionIface<Inbound, State>;\n  routes?: RouteDefinitionIface[];\n  respond?(\n    input: ChannelInputResponseIface,\n    ctx: ChannelReceiveContextIface,\n  ): Promise<{ resolved: boolean }>;\n  cancel?(ctx: ChannelReceiveContextIface): Promise<{ accepted: boolean }>;\n  // Inserts the input into its conversation and routes it. Returns where it went.\n  receive(input: Inbound, ctx: ChannelReceiveContextIface): Promise<ChannelReceiveResult>;\n  // Pure: who gets this message, and how. The channel applies it\n  // to what it posts, from receive and project.\n  route(args: RouteArgsIface): RouteDecisionIface[] | Promise<RouteDecisionIface[]>;\n  turnPolicy: TurnPolicy;\n  // ACP update \u2192 visible message / card. Called with a turn's\n  // PROJECTED_UPDATE_KINDS updates in seq order, then its idle state_update.\n  project(update: SessionUpdate, ctx: ProjectionContextIface<State>): Promise<void>;\n  events?: Partial<Record<ChannelEventKind, ChannelEventHandler<State>>>;\n}\n\nexport const defineChannel = <Inbound, State = undefined>(\n  definition: ChannelDefinitionIface<Inbound, State>,\n): ChannelDefinitionIface<Inbound, State> => definition;\n"],
+  "mappings": "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",
+  "names": ["ConversationKind", "ParticipantKind", "SystemParticipantKind", "RoutingMode", "TurnPolicy", "Delivery", "MessageKind", "CardKind", "PendingEventKind", "PendingKind"]
+}

package/dist/modules/conformance/agent.d.mts

@@ -0,0 +1,20 @@
+import { type AgentApp, type AgentConnection, type Stream } from '@agentclientprotocol/sdk/experimental/v2';
+import { type FrameAttachmentStoreIface } from '@finalai/acp-session';
+import { type FetchLike } from '@modelcontextprotocol/client';
+import { PromptWhileRunning } from "../harness.mjs";
+export interface ConformanceAgentOptionsIface {
+    extensions?: boolean;
+    fetch?: FetchLike;
+    slowTurnMs?: number;
+    privateMethods?: string[];
+    promptWhileRunning?: PromptWhileRunning;
+    survivesDisconnect?: boolean;
+    attachments?: FrameAttachmentStoreIface;
+}
+export interface ConformanceAgentIface {
+    app: AgentApp;
+    connect(stream: Stream): AgentConnection;
+    sessions(): string[];
+    nativeId(sessionId: string): string | null;
+}
+export declare const createConformanceAgent: (options?: ConformanceAgentOptionsIface) => ConformanceAgentIface;