@finalai/agent-provider 0.5.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/HOSTING.md +4 -4
  2. package/README.md +85 -0
  3. package/dist/modules/channel-socket.d.mts +8 -4
  4. package/dist/modules/channel-socket.mjs +39 -2
  5. package/dist/modules/channel-socket.mjs.map +2 -2
  6. package/dist/modules/channel.d.mts +323 -363
  7. package/dist/modules/channel.mjs +60 -145
  8. package/dist/modules/channel.mjs.map +3 -3
  9. package/dist/modules/conformance/sandbox-kit.d.mts +1 -0
  10. package/dist/modules/conformance/sandbox-kit.mjs +174 -0
  11. package/dist/modules/conformance/sandbox-kit.mjs.map +3 -3
  12. package/dist/modules/credentials.mjs.map +2 -2
  13. package/dist/modules/index.d.mts +0 -1
  14. package/dist/modules/index.mjs +0 -1
  15. package/dist/modules/index.mjs.map +2 -2
  16. package/dist/modules/local-channel-context.d.mts +10 -0
  17. package/dist/modules/local-channel-context.mjs +55 -0
  18. package/dist/modules/local-channel-context.mjs.map +7 -0
  19. package/dist/modules/local-channel-socket.d.mts +8 -4
  20. package/dist/modules/local-channel-socket.mjs +1 -13
  21. package/dist/modules/local-channel-socket.mjs.map +2 -2
  22. package/dist/modules/manifest.d.mts +88 -4
  23. package/dist/modules/manifest.mjs +23 -6
  24. package/dist/modules/manifest.mjs.map +2 -2
  25. package/dist/modules/room-surface.d.mts +370 -0
  26. package/dist/modules/room-surface.mjs +156 -0
  27. package/dist/modules/room-surface.mjs.map +7 -0
  28. package/dist/modules/sandbox/client.mjs +108 -27
  29. package/dist/modules/sandbox/client.mjs.map +3 -3
  30. package/dist/modules/sandbox/convenience.mjs +1 -1
  31. package/dist/modules/sandbox/convenience.mjs.map +2 -2
  32. package/dist/modules/sandbox/execution-guard.d.mts +1 -0
  33. package/dist/modules/sandbox/execution-guard.mjs +9 -0
  34. package/dist/modules/sandbox/execution-guard.mjs.map +2 -2
  35. package/dist/modules/sandbox/memory-sandbox.mjs +8 -0
  36. package/dist/modules/sandbox/memory-sandbox.mjs.map +2 -2
  37. package/dist/modules/sandbox/server.mjs +87 -14
  38. package/dist/modules/sandbox/server.mjs.map +3 -3
  39. package/dist/modules/sandbox/types.d.mts +21 -1
  40. package/dist/modules/sandbox/types.mjs +1 -0
  41. package/dist/modules/sandbox/types.mjs.map +2 -2
  42. package/dist/modules/sandbox/wire.d.mts +40 -0
  43. package/dist/modules/sandbox/wire.mjs +32 -2
  44. package/dist/modules/sandbox/wire.mjs.map +2 -2
  45. package/dist/modules/semantic-events.d.mts +69 -1
  46. package/dist/modules/semantic-events.mjs +14 -1
  47. package/dist/modules/semantic-events.mjs.map +2 -2
  48. package/package.json +14 -9
  49. package/dist/modules/channel-context.d.mts +0 -106
  50. package/dist/modules/channel-context.mjs +0 -45
  51. package/dist/modules/channel-context.mjs.map +0 -7
@@ -1,156 +1,71 @@
1
1
  import * as z from "zod";
2
- import { jsonObjectSchema, jsonValueSchema } from "./json.mjs";
3
- var ChannelPrincipalType = /* @__PURE__ */ ((ChannelPrincipalType2) => {
4
- ChannelPrincipalType2["User"] = "user";
5
- ChannelPrincipalType2["Service"] = "service";
6
- return ChannelPrincipalType2;
7
- })(ChannelPrincipalType || {});
8
- const channelAuthSchema = z.object({
9
- principalId: z.string().min(1),
10
- principalType: z.nativeEnum(ChannelPrincipalType),
11
- authenticator: z.string().min(1),
12
- // How the agent and the people reading its reply name the principal.
13
- displayName: z.string().min(1).max(200).optional(),
14
- attributes: jsonObjectSchema.default({})
2
+ import { jsonObjectSchema } from "./json.mjs";
3
+ export * from "./room-surface.mjs";
4
+ const personHandleSchema = z.string().min(1).brand();
5
+ const conversationHandleSchema = z.string().min(1).brand();
6
+ const principalRefSchema = z.object({
7
+ id: z.string().min(1),
8
+ tenant: z.string().min(1).optional(),
9
+ displayName: z.string().optional()
15
10
  });
16
- const principalDisplayName = (auth) => {
17
- const name = auth["displayName"];
18
- return typeof name === "string" && name.length > 0 ? name : auth.principalId;
19
- };
20
- var ConversationKind = /* @__PURE__ */ ((ConversationKind2) => {
21
- ConversationKind2["Direct"] = "direct";
22
- ConversationKind2["Group"] = "group";
23
- return ConversationKind2;
24
- })(ConversationKind || {});
25
- var ParticipantKind = /* @__PURE__ */ ((ParticipantKind2) => {
26
- ParticipantKind2["User"] = "user";
27
- ParticipantKind2["Agent"] = "agent";
28
- return ParticipantKind2;
29
- })(ParticipantKind || {});
30
- var RoutingMode = /* @__PURE__ */ ((RoutingMode2) => {
31
- RoutingMode2["Mention"] = "mention";
32
- RoutingMode2["All"] = "all";
33
- RoutingMode2["Default"] = "default";
34
- return RoutingMode2;
35
- })(RoutingMode || {});
36
- var TurnPolicy = /* @__PURE__ */ ((TurnPolicy2) => {
37
- TurnPolicy2["Steer"] = "steer";
38
- TurnPolicy2["Queue"] = "queue";
39
- return TurnPolicy2;
40
- })(TurnPolicy || {});
41
- var Delivery = /* @__PURE__ */ ((Delivery2) => {
42
- Delivery2["Prompt"] = "prompt";
43
- Delivery2["Observe"] = "observe";
44
- return Delivery2;
45
- })(Delivery || {});
46
- var MessageKind = /* @__PURE__ */ ((MessageKind2) => {
47
- MessageKind2["Message"] = "message";
48
- MessageKind2["Card"] = "card";
49
- return MessageKind2;
50
- })(MessageKind || {});
51
- var CardKind = /* @__PURE__ */ ((CardKind2) => {
52
- CardKind2["Elicitation"] = "elicitation";
53
- CardKind2["Permission"] = "permission";
54
- CardKind2["Notice"] = "notice";
55
- return CardKind2;
56
- })(CardKind || {});
57
- const channelReceiveResultSchema = z.union([
58
- z.object({ conversationId: z.string().min(1) }),
59
- z.object({ sessionId: z.string().min(1) }),
60
- z.null()
61
- ]);
62
- const channelMessageInputSchema = z.object({
63
- conversationId: z.string().min(1),
64
- authorParticipantId: z.string().min(1),
65
- kind: z.nativeEnum(MessageKind).default("message" /* Message */),
66
- content: z.array(jsonObjectSchema).min(1),
67
- clientMessageId: z.string().min(1).nullish(),
68
- replyToMessageId: z.string().min(1).nullish(),
69
- threadRootId: z.string().min(1).nullish(),
70
- quotedMessageIds: z.array(z.string().min(1)).default([]),
71
- mentionedParticipantIds: z.array(z.string().min(1)).default([])
72
- });
73
- var DecisionEventKind = /* @__PURE__ */ ((DecisionEventKind2) => {
74
- DecisionEventKind2["Created"] = "decision.created";
75
- DecisionEventKind2["Resolved"] = "decision.resolved";
76
- return DecisionEventKind2;
77
- })(DecisionEventKind || {});
78
- var DecisionKind = /* @__PURE__ */ ((DecisionKind2) => {
79
- DecisionKind2["Permission"] = "permission";
80
- DecisionKind2["Elicitation"] = "elicitation";
81
- return DecisionKind2;
82
- })(DecisionKind || {});
83
- const decisionCreatedDataSchema = z.object({
84
- decisionId: z.string().min(1),
85
- kind: z.nativeEnum(DecisionKind),
86
- audienceParticipantIds: z.array(z.string()),
87
- request: jsonValueSchema
11
+ const placeRefSchema = z.lazy(
12
+ () => z.object({
13
+ kind: z.string().min(1),
14
+ id: z.string().min(1),
15
+ tenant: z.string().min(1).optional(),
16
+ parent: placeRefSchema.optional(),
17
+ title: z.string().optional()
18
+ })
19
+ );
20
+ const originSchema = z.object({ place: placeRefSchema, ref: jsonObjectSchema.optional() });
21
+ var ChannelReplies = /* @__PURE__ */ ((ChannelReplies2) => {
22
+ ChannelReplies2["Origin"] = "origin";
23
+ ChannelReplies2["All"] = "all";
24
+ return ChannelReplies2;
25
+ })(ChannelReplies || {});
26
+ var ChannelAudience = /* @__PURE__ */ ((ChannelAudience2) => {
27
+ ChannelAudience2["Members"] = "members";
28
+ ChannelAudience2["Anyone"] = "anyone";
29
+ return ChannelAudience2;
30
+ })(ChannelAudience || {});
31
+ var ChannelCreate = /* @__PURE__ */ ((ChannelCreate2) => {
32
+ ChannelCreate2["DirectWithAgent"] = "direct-with-agent";
33
+ ChannelCreate2["Group"] = "group";
34
+ return ChannelCreate2;
35
+ })(ChannelCreate || {});
36
+ const placePolicySchema = z.object({
37
+ replies: z.nativeEnum(ChannelReplies),
38
+ audience: z.nativeEnum(ChannelAudience)
88
39
  });
89
- const decisionResolvedDataSchema = z.object({
90
- decisionId: z.string().min(1),
91
- outcome: jsonValueSchema,
92
- respondedBy: channelAuthSchema.nullable().default(null)
40
+ const refusalSchema = z.object({
41
+ refused: z.union([
42
+ z.literal("unlinked"),
43
+ z.literal("no-access"),
44
+ z.literal("unconnected"),
45
+ z.literal("not-audience")
46
+ ]),
47
+ linkUrl: z.string().optional(),
48
+ connectUrl: z.string().optional(),
49
+ message: z.string()
93
50
  });
94
- const PROJECTED_UPDATE_KINDS = /* @__PURE__ */ new Set([
95
- "agent_message_chunk",
96
- "agent_message"
51
+ const channelReceiveResultSchema = z.union([
52
+ z.object({ accepted: z.literal(true) }),
53
+ z.object({ accepted: z.literal(false), refusal: refusalSchema }),
54
+ z.object({ ignored: z.literal(true), reason: z.string() })
97
55
  ]);
98
- const turnEndSchema = z.looseObject({
99
- sessionUpdate: z.literal("state_update"),
100
- state: z.literal("idle"),
101
- stopReason: z.string().nullish(),
102
- _meta: z.looseObject({ "final.ai": z.looseObject({ stopReason: z.string().nullish() }).nullish() }).nullish()
103
- });
104
- const turnEndOf = (update) => {
105
- const parsed = turnEndSchema.safeParse(update);
106
- if (!parsed.success) return null;
107
- return {
108
- stopReason: parsed.data.stopReason ?? parsed.data._meta?.["final.ai"]?.stopReason ?? null
109
- };
110
- };
111
- const turnEndUpdate = (stopReason) => {
112
- switch (stopReason) {
113
- case null:
114
- return { sessionUpdate: "state_update", state: "idle" };
115
- case "end_turn":
116
- return { sessionUpdate: "state_update", state: "idle", stopReason: "end_turn" };
117
- case "max_tokens":
118
- return { sessionUpdate: "state_update", state: "idle", stopReason: "max_tokens" };
119
- case "max_turn_requests":
120
- return { sessionUpdate: "state_update", state: "idle", stopReason: "max_turn_requests" };
121
- case "refusal":
122
- return { sessionUpdate: "state_update", state: "idle", stopReason: "refusal" };
123
- case "cancelled":
124
- return { sessionUpdate: "state_update", state: "idle", stopReason: "cancelled" };
125
- default:
126
- return {
127
- sessionUpdate: "state_update",
128
- state: "idle",
129
- _meta: { "final.ai": { stopReason } }
130
- };
131
- }
132
- };
133
56
  const defineChannel = (definition) => definition;
134
57
  export {
135
- CardKind,
136
- ChannelPrincipalType,
137
- ConversationKind,
138
- DecisionEventKind,
139
- DecisionKind,
140
- Delivery,
141
- MessageKind,
142
- PROJECTED_UPDATE_KINDS,
143
- ParticipantKind,
144
- RoutingMode,
145
- TurnPolicy,
146
- channelAuthSchema,
147
- channelMessageInputSchema,
58
+ ChannelAudience,
59
+ ChannelCreate,
60
+ ChannelReplies,
148
61
  channelReceiveResultSchema,
149
- decisionCreatedDataSchema,
150
- decisionResolvedDataSchema,
62
+ conversationHandleSchema,
151
63
  defineChannel,
152
- principalDisplayName,
153
- turnEndOf,
154
- turnEndUpdate
64
+ originSchema,
65
+ personHandleSchema,
66
+ placePolicySchema,
67
+ placeRefSchema,
68
+ principalRefSchema,
69
+ refusalSchema
155
70
  };
156
71
  //# sourceMappingURL=channel.mjs.map
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "version": 3,
3
3
  "sources": ["../../../../src/channel.ts"],
4
- "sourcesContent": ["import type { HostedBindingsIface } from \"./hosted-bindings.mjs\";\nimport type { ContentBlock, SessionUpdate } from '@agentclientprotocol/sdk/experimental/v2';\nimport type { SessionUpdateKind } from '@finalai/acp-session';\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//\n// Members of a conversation are people and agents. Everything else an agent\n// hears (a schedule, a webhook, a Goal, another agent or channel) is channel\n// input from a principal (`ChannelAuthIface`), sent with\n// `channelSessions.send`; it is never a message.\n\nexport enum ChannelPrincipalType {\n User = 'user',\n Service = 'service',\n}\n\n// Who a channel authenticated for an input or a response. Channels vouch for\n// their principals; one principal per authenticator (`slack:<user>`), so\n// the same person on two surfaces is two principals.\nexport interface ChannelAuthIface extends JsonObject {\n principalId: string;\n principalType: ChannelPrincipalType | `${ChannelPrincipalType}`;\n authenticator: string;\n // `displayName` (a string) when the channel names the principal; see principalDisplayName.\n attributes: JsonObject;\n}\n\nexport const channelAuthSchema = z.object({\n principalId: z.string().min(1),\n principalType: z.nativeEnum(ChannelPrincipalType),\n authenticator: z.string().min(1),\n // How the agent and the people reading its reply name the principal.\n displayName: z.string().min(1).max(200).optional(),\n attributes: jsonObjectSchema.default({}),\n});\n\n// How a principal is named to the agent and in captions: its `displayName`, else its id.\nexport const principalDisplayName = (auth: ChannelAuthIface): string => {\n const name = auth['displayName'];\n return typeof name === 'string' && name.length > 0 ? name : auth.principalId;\n};\n\nexport enum ConversationKind {\n Direct = 'direct',\n Group = 'group',\n}\n\nexport enum ParticipantKind {\n User = 'user',\n Agent = 'agent',\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 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 definitionId: string | 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 decisionId: 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?: ChannelAuthIface | 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 decision audience).\n authorParticipantId: string;\n // The person a prompt from no person acts for (payer and audience).\n actingUserId?: string | null;\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 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?: ChannelAuthIface | null;\n participantId: string;\n decisionId: string;\n outcome: JsonValue;\n actorParticipantId: string;\n userId: string | null;\n}\n\nexport interface ChannelReceiveContextIface {\n bindings?: HostedBindingsIface;\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 bindings?: HostedBindingsIface;\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 bindings?: HostedBindingsIface;\n sessionId?: string;\n platform: ChannelPlatformIface;\n // The binding's config and the agent's secrets (manifest.secrets), as receive gets them:\n // a channel posts its replies back to its own service with them.\n config: JsonObject;\n secrets: { get(name: string): Promise<string | null> };\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 DecisionEventKind {\n Created = 'decision.created',\n Resolved = 'decision.resolved',\n}\n\nexport type AcpUpdateKind = SessionUpdate['sessionUpdate'];\n// The update kinds ACP v2 names; AcpUpdateKind also admits any other string.\nexport type KnownAcpUpdateKind = `${SessionUpdateKind}`;\n\nexport type ChannelEventKind =\n | AcpUpdateKind\n | `${DecisionEventKind}`\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 DecisionKind {\n Permission = 'permission',\n Elicitation = 'elicitation',\n}\n\n// `data` of a decision.created event: an ACP session/request_permission or\n// elicitation/create request awaiting its audience.\nexport const decisionCreatedDataSchema = z.object({\n decisionId: z.string().min(1),\n kind: z.nativeEnum(DecisionKind),\n audienceParticipantIds: z.array(z.string()),\n request: jsonValueSchema,\n});\n\nexport type DecisionCreatedDataIface = z.infer<typeof decisionCreatedDataSchema>;\n\n// `data` of a decision.resolved event: the answer (or cancellation) as recorded,\n// and the principal a channel answered as (null for Final rooms and expiries).\nexport const decisionResolvedDataSchema = z.object({\n decisionId: z.string().min(1),\n outcome: jsonValueSchema,\n respondedBy: channelAuthSchema.nullable().default(null),\n});\n\nexport type DecisionResolvedDataIface = z.infer<typeof decisionResolvedDataSchema>;\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"],
5
- "mappings": "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",
6
- "names": ["ChannelPrincipalType", "ConversationKind", "ParticipantKind", "RoutingMode", "TurnPolicy", "Delivery", "MessageKind", "CardKind", "DecisionEventKind", "DecisionKind"]
4
+ "sourcesContent": ["import type { ContentBlock } from '@agentclientprotocol/sdk/experimental/v2';\nimport * as z from 'zod';\nimport { jsonObjectSchema, type JsonObject, type JsonValue } from \"./json.mjs\";\nimport type { ProviderRef } from \"./provider-ref.mjs\";\nimport type { ChannelSocketIface, ChannelTurnStateIface } from \"./room-surface.mjs\";\nimport type { ChannelSemanticDataByKindIface } from \"./semantic-events.mjs\";\n\nexport * from \"./room-surface.mjs\";\n\n// Handles carry no authority until the platform validates their binding and invocation signature.\nexport const personHandleSchema = z.string().min(1).brand<'ChannelPerson'>();\nexport const conversationHandleSchema = z.string().min(1).brand<'ChannelConversation'>();\nexport type PersonHandle = z.infer<typeof personHandleSchema>;\nexport type ConversationHandle = z.infer<typeof conversationHandleSchema>;\n\nexport const principalRefSchema = z.object({\n id: z.string().min(1),\n tenant: z.string().min(1).optional(),\n displayName: z.string().optional(),\n});\nexport type PrincipalRef = z.infer<typeof principalRefSchema>;\nexport interface PlaceRef {\n kind: string;\n id: string;\n tenant?: string;\n parent?: PlaceRef;\n title?: string;\n}\nexport const placeRefSchema: z.ZodType<PlaceRef> = z.lazy(() =>\n z.object({\n kind: z.string().min(1),\n id: z.string().min(1),\n tenant: z.string().min(1).optional(),\n parent: placeRefSchema.optional(),\n title: z.string().optional(),\n }),\n);\nexport interface OriginIface {\n place: PlaceRef;\n ref?: JsonObject;\n}\nexport const originSchema = z.object({ place: placeRefSchema, ref: jsonObjectSchema.optional() });\n\nexport type PersonResolution =\n | { kind: 'member'; person: PersonHandle; displayName: string }\n | { kind: 'unlinked'; linkUrl: string }\n | { kind: 'blocked'; reason: 'not-in-organization' | 'suspended' };\nexport enum ChannelReplies {\n Origin = 'origin',\n All = 'all',\n}\nexport enum ChannelAudience {\n Members = 'members',\n Anyone = 'anyone',\n}\nexport enum ChannelCreate {\n DirectWithAgent = 'direct-with-agent',\n Group = 'group',\n}\nexport const placePolicySchema = z.object({\n replies: z.nativeEnum(ChannelReplies),\n audience: z.nativeEnum(ChannelAudience),\n});\nexport interface PlacePolicy {\n replies: ChannelReplies | `${ChannelReplies}`;\n audience: ChannelAudience | `${ChannelAudience}`;\n}\nexport interface PlaceDefaultsIface extends PlacePolicy {\n create: ChannelCreate | `${ChannelCreate}`;\n}\nexport type PlaceResolution =\n | { kind: 'connected'; conversation: ConversationHandle; policy: PlacePolicy }\n | { kind: 'unconnected'; connectUrl: string; defaults: PlaceDefaultsIface | null };\nexport interface Refusal {\n refused: 'unlinked' | 'no-access' | 'unconnected' | 'not-audience';\n linkUrl?: string;\n connectUrl?: string;\n message: string;\n}\nexport type ChannelReceiveResult =\n | { accepted: true }\n | { accepted: false; refusal: Refusal }\n | { ignored: true; reason: string };\nexport const refusalSchema = z.object({\n refused: z.union([\n z.literal('unlinked'),\n z.literal('no-access'),\n z.literal('unconnected'),\n z.literal('not-audience'),\n ]),\n linkUrl: z.string().optional(),\n connectUrl: z.string().optional(),\n message: z.string(),\n});\nexport const channelReceiveResultSchema = z.union([\n z.object({ accepted: z.literal(true) }),\n z.object({ accepted: z.literal(false), refusal: refusalSchema }),\n z.object({ ignored: z.literal(true), reason: z.string() }),\n]);\nexport interface InstalledAppInfoIface {\n clientId: string;\n clientSecret: string;\n signingSecret?: string;\n}\nexport interface InstalledAppCredential extends InstalledAppInfoIface {\n accessToken: string;\n tenantId?: string;\n externalId?: string;\n expiresAt?: string | null;\n customHeaders?: Record<string, string>;\n}\nexport interface ChannelCredentialsIface {\n // Installed app credentials and metadata are package-only; isolates use token-injecting fetch.\n appInfo(): Promise<InstalledAppInfoIface>;\n app(options?: { tenant?: string }): Promise<InstalledAppCredential>;\n // Explicitly declared project secrets are available in both execution modes.\n secret(name: string): Promise<string | null>;\n fetch: typeof fetch;\n}\nexport interface ChannelPostArgsIface {\n from: PersonHandle;\n content: ContentBlock[];\n context?: string[];\n origin: OriginIface;\n idempotencyKey: string;\n waitForAcceptance?: boolean;\n}\nexport interface ChannelConversationIface {\n post(args: ChannelPostArgsIface): Promise<{ messageId: string; turnId?: string } | Refusal>;\n input(args: {\n label: string;\n principal?: PrincipalRef;\n content: ContentBlock[];\n context?: string[];\n origin: OriginIface;\n idempotencyKey: string;\n waitForAcceptance?: boolean;\n }): Promise<{ inputId: string; turnId?: string } | Refusal>;\n attach(args: {\n origin: OriginIface;\n content: ContentBlock[];\n label: string;\n idempotencyKey: string;\n from?: PersonHandle;\n }): Promise<{ messageId: string } | Refusal>;\n edit(args: {\n externalKey: string;\n by: PersonHandle;\n content: ContentBlock[];\n }): Promise<{ messageId: string } | Refusal>;\n remove(args: { externalKey: string; by: PersonHandle }): Promise<{ removed: boolean } | Refusal>;\n react(args: {\n target: { externalKey: string } | { replyOf: { externalKey: string; turnId: string } };\n emoji: string;\n by: PersonHandle;\n op: 'add' | 'remove';\n }): Promise<{ ok: true } | Refusal>;\n}\nexport type SemanticEvent = {\n [Kind in keyof ChannelSemanticDataByKindIface]: {\n type: Kind;\n data: ChannelSemanticDataByKindIface[Kind];\n seq: number;\n };\n}[keyof ChannelSemanticDataByKindIface];\nexport interface ChannelReceiveContextIface<Config = JsonObject> {\n binding: {\n id: string;\n owner: { kind: 'agent'; definitionId: string } | { kind: 'install'; installId: string };\n };\n config: Config;\n credentials: ChannelCredentialsIface;\n people: {\n resolve(principal: PrincipalRef): Promise<PersonResolution>;\n identify(person: PersonHandle): Promise<PrincipalRef | null>;\n // Tenant-wide uninstall/revocation also disconnects that tenant's places.\n revoke(args: {\n principal?: PrincipalRef;\n tenant?: string;\n reason: 'deactivated' | 'uninstalled' | 'provider-revoked';\n }): Promise<void>;\n confirm(args: { ticket: string; principal: PrincipalRef }): Promise<{ linked: true } | Refusal>;\n };\n places: {\n // Explicit anyone/group defaults may create a Shared chat while resolving a new place.\n resolve(place: PlaceRef): Promise<PlaceResolution>;\n observers(place: PlaceRef): Promise<ConversationHandle[]>;\n connect(\n place: PlaceRef,\n to: {\n by: PersonHandle;\n conversation?: ConversationHandle;\n create?: ChannelCreate | `${ChannelCreate}`;\n },\n ): Promise<ConversationHandle>;\n disconnect(place: PlaceRef, by: PersonHandle): Promise<void>;\n };\n conversation(handle: ConversationHandle): ChannelConversationIface;\n observe(\n handle: ConversationHandle,\n args?: { turnId?: string; signal?: AbortSignal },\n ): AsyncIterable<SemanticEvent>;\n media: {\n transcribe(\n audio: AsyncIterable<Uint8Array>,\n options: {\n encoding: string;\n sampleRate: number;\n language?: string;\n endpointing?: boolean;\n signal?: AbortSignal;\n },\n ): AsyncIterable<{ text: string; final: boolean }>;\n synthesize(\n text: AsyncIterable<string>,\n options: { voice?: string; encoding: string; sampleRate: number; signal?: AbortSignal },\n ): AsyncIterable<Uint8Array>;\n };\n decisions: {\n resolve(args: {\n decisionId: string;\n outcome: JsonValue;\n by: PersonHandle;\n }): Promise<{ resolved: boolean } | Refusal>;\n };\n turns: {\n cancel(args: {\n conversation: ConversationHandle;\n by?: PersonHandle;\n turnId?: string;\n }): Promise<{ accepted: boolean } | Refusal>;\n };\n store: {\n get(key: string): Promise<JsonValue | null>;\n set(key: string, value: JsonValue | null, options?: { ttlSeconds?: number }): Promise<void>;\n };\n log(message: string, details?: JsonObject): void;\n}\nexport interface ChannelEventContextIface<Config = JsonObject, State = JsonValue> extends Pick<\n ChannelReceiveContextIface<Config>,\n 'binding' | 'config' | 'credentials' | 'store' | 'log'\n> {\n origin: OriginIface;\n conversation: ConversationHandle;\n turn: { id: string; agent: { displayName: string } };\n state: ChannelTurnStateIface<State>;\n}\nexport interface ChannelRouteContextIface<\n Config = JsonObject,\n> extends ChannelReceiveContextIface<Config> {\n request: Request;\n authenticatedPrincipal?: PrincipalRef;\n receive(input: JsonValue): Promise<ChannelReceiveResult>;\n}\nexport interface HttpChannelRouteDefinitionIface<Config = JsonObject> {\n method: 'GET' | 'POST' | 'PUT' | 'DELETE';\n path: string;\n handler(args: ChannelRouteContextIface<Config>): Promise<Response>;\n}\nexport interface WebSocketChannelRouteDefinitionIface<Config = JsonObject> {\n method: 'WS';\n path: string;\n handler(\n args: ChannelRouteContextIface<Config> & { socket: ChannelSocketIface },\n ): Promise<Response | void>;\n}\nexport type RouteDefinitionIface<Config = JsonObject> =\n | HttpChannelRouteDefinitionIface<Config>\n | WebSocketChannelRouteDefinitionIface<Config>;\nexport type ChannelEventHandlersIface<Config, State> = {\n [Kind in keyof ChannelSemanticDataByKindIface]?: (\n data: ChannelSemanticDataByKindIface[Kind],\n ctx: ChannelEventContextIface<Config, State>,\n ) => Promise<void>;\n};\nexport type ChannelEventKind = keyof ChannelSemanticDataByKindIface;\nexport interface ChannelDefinitionIface<\n Config = JsonObject,\n Inbound = JsonValue,\n State = JsonValue,\n> {\n name: string;\n config?: Config;\n installed?: ProviderRef;\n configure?(config: Config): ChannelDefinitionIface<Config, Inbound, State>;\n credentials: { app: string | null; secrets?: string[] };\n identity:\n | {\n kind: 'redirect';\n start(\n args: { ticket: string; principal: PrincipalRef },\n ctx: ChannelReceiveContextIface<Config>,\n ): Promise<URL>;\n }\n | {\n kind: 'challenge';\n deliver(\n args: { principal: PrincipalRef; code: string },\n ctx: ChannelReceiveContextIface<Config>,\n ): Promise<void>;\n }\n | { kind: 'none' };\n places: { kinds: readonly string[]; defaults?(place: PlaceRef): PlaceDefaultsIface | null };\n routes?: RouteDefinitionIface<Config>[];\n listeners?: {\n key: string;\n run(ctx: ChannelReceiveContextIface<Config> & { signal: AbortSignal }): Promise<void>;\n }[];\n receive(input: Inbound, ctx: ChannelReceiveContextIface<Config>): Promise<ChannelReceiveResult>;\n events?: ChannelEventHandlersIface<Config, State>;\n}\nexport const defineChannel = <Config = JsonObject, Inbound = JsonValue, State = JsonValue>(\n definition: ChannelDefinitionIface<Config, Inbound, State>,\n): ChannelDefinitionIface<Config, Inbound, State> => definition;\n"],
5
+ "mappings": "AACA,YAAY,OAAO;AACnB,SAAS,wBAAyD;AAKlE,cAAc;AAGP,MAAM,qBAAqB,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAuB;AACpE,MAAM,2BAA2B,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAA6B;AAIhF,MAAM,qBAAqB,EAAE,OAAO;AAAA,EACzC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,EACpB,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,EACnC,aAAa,EAAE,OAAO,EAAE,SAAS;AACnC,CAAC;AASM,MAAM,iBAAsC,EAAE;AAAA,EAAK,MACxD,EAAE,OAAO;AAAA,IACP,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IACtB,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IACpB,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,IACnC,QAAQ,eAAe,SAAS;AAAA,IAChC,OAAO,EAAE,OAAO,EAAE,SAAS;AAAA,EAC7B,CAAC;AACH;AAKO,MAAM,eAAe,EAAE,OAAO,EAAE,OAAO,gBAAgB,KAAK,iBAAiB,SAAS,EAAE,CAAC;AAMzF,IAAK,iBAAL,kBAAKA,oBAAL;AACL,EAAAA,gBAAA,YAAS;AACT,EAAAA,gBAAA,SAAM;AAFI,SAAAA;AAAA,GAAA;AAIL,IAAK,kBAAL,kBAAKC,qBAAL;AACL,EAAAA,iBAAA,aAAU;AACV,EAAAA,iBAAA,YAAS;AAFC,SAAAA;AAAA,GAAA;AAIL,IAAK,gBAAL,kBAAKC,mBAAL;AACL,EAAAA,eAAA,qBAAkB;AAClB,EAAAA,eAAA,WAAQ;AAFE,SAAAA;AAAA,GAAA;AAIL,MAAM,oBAAoB,EAAE,OAAO;AAAA,EACxC,SAAS,EAAE,WAAW,cAAc;AAAA,EACpC,UAAU,EAAE,WAAW,eAAe;AACxC,CAAC;AAqBM,MAAM,gBAAgB,EAAE,OAAO;AAAA,EACpC,SAAS,EAAE,MAAM;AAAA,IACf,EAAE,QAAQ,UAAU;AAAA,IACpB,EAAE,QAAQ,WAAW;AAAA,IACrB,EAAE,QAAQ,aAAa;AAAA,IACvB,EAAE,QAAQ,cAAc;AAAA,EAC1B,CAAC;AAAA,EACD,SAAS,EAAE,OAAO,EAAE,SAAS;AAAA,EAC7B,YAAY,EAAE,OAAO,EAAE,SAAS;AAAA,EAChC,SAAS,EAAE,OAAO;AACpB,CAAC;AACM,MAAM,6BAA6B,EAAE,MAAM;AAAA,EAChD,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,IAAI,EAAE,CAAC;AAAA,EACtC,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,KAAK,GAAG,SAAS,cAAc,CAAC;AAAA,EAC/D,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,IAAI,GAAG,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC3D,CAAC;AAqNM,MAAM,gBAAgB,CAC3B,eACmD;",
6
+ "names": ["ChannelReplies", "ChannelAudience", "ChannelCreate"]
7
7
  }
@@ -24,4 +24,5 @@ export interface SandboxConformanceReportIface {
24
24
  passed: boolean;
25
25
  cases: ConformanceCaseResultIface[];
26
26
  }
27
+ export declare const DURABLE_CONFORMANCE_SCRIPT = "echo one; echo err-one >&2; sleep 2; echo two; echo err-two >&2; exit 7";
27
28
  export declare const runSandboxConformance: (args: RunSandboxConformanceArgsIface) => Promise<SandboxConformanceReportIface>;
@@ -183,6 +183,136 @@ const sandboxCases = (largeFileBytes) => [
183
183
  }
184
184
  }
185
185
  ];
186
+ const DURABLE_CONFORMANCE_SCRIPT = "echo one; echo err-one >&2; sleep 2; echo two; echo err-two >&2; exit 7";
187
+ const textOf = (chunks) => new TextDecoder().decode(concatChunks(chunks));
188
+ const concatChunks = (chunks) => {
189
+ const out = new Uint8Array(chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0));
190
+ let offset = 0;
191
+ for (const chunk of chunks) {
192
+ out.set(chunk, offset);
193
+ offset += chunk.byteLength;
194
+ }
195
+ return out;
196
+ };
197
+ const readThrough = async (stream, text) => {
198
+ const reader = stream.getReader();
199
+ const chunks = [];
200
+ while (!textOf(chunks).includes(text)) {
201
+ const next = await reader.read();
202
+ if (next.done) throw new Error(`stream ended before ${JSON.stringify(text)}`);
203
+ chunks.push(next.value);
204
+ }
205
+ return concatChunks(chunks);
206
+ };
207
+ const DURABLE_STDOUT = "one\ntwo\n";
208
+ const DURABLE_STDERR = "err-one\nerr-two\n";
209
+ const after = (text, offset) => text.slice(offset);
210
+ const attachOrFail = async (sandbox, options) => {
211
+ check(sandbox.attachProcess != null, "attachProcess is missing");
212
+ const attached = await sandbox.attachProcess?.(options);
213
+ if (attached == null) throw new Error("attachProcess found no process for a durable ref");
214
+ return attached;
215
+ };
216
+ const durableCases = async (targets, record, prefix) => {
217
+ const state = {
218
+ spawned: null
219
+ };
220
+ await record(
221
+ `${prefix}durable processes: re-attach resumes at the delivered offsets`,
222
+ async () => {
223
+ const controller = new AbortController();
224
+ const sandbox = await targets.spawnOn();
225
+ const process = await sandbox.spawn({
226
+ command: DURABLE_CONFORMANCE_SCRIPT,
227
+ shell: true,
228
+ durable: true,
229
+ abortSignal: controller.signal
230
+ });
231
+ const ref = process.ref;
232
+ check(typeof ref === "string" && ref.length > 0, "a durable process has no ref");
233
+ if (ref == null) return;
234
+ const [stdout, stderr] = await Promise.all([
235
+ readThrough(process.stdout, "one\n"),
236
+ readThrough(process.stderr, "err-one\n")
237
+ ]);
238
+ targets.drop({ controller, sandbox });
239
+ const options = { ref, stdoutOffset: stdout.byteLength, stderrOffset: stderr.byteLength };
240
+ const attached = await attachOrFail(await targets.attachOn(), options);
241
+ check(
242
+ attached.stdoutOffset === options.stdoutOffset && attached.stderrOffset === options.stderrOffset,
243
+ `attached at ${attached.stdoutOffset}/${attached.stderrOffset}, asked ${options.stdoutOffset}/${options.stderrOffset}`
244
+ );
245
+ const [restOut, restErr, exit] = await Promise.all([
246
+ streamToString(attached.stdout),
247
+ streamToString(attached.stderr),
248
+ attached.wait()
249
+ ]);
250
+ const out = textOf([stdout]) + restOut;
251
+ const err = textOf([stderr]) + restErr;
252
+ check(out === DURABLE_STDOUT, `stdout across the re-attach: ${JSON.stringify(out)}`);
253
+ check(err === DURABLE_STDERR, `stderr across the re-attach: ${JSON.stringify(err)}`);
254
+ check(exit.exitCode === 7, `exit code ${exit.exitCode}`);
255
+ state.spawned = options;
256
+ }
257
+ );
258
+ await record(
259
+ `${prefix}durable processes: attach after exit keeps output and exit code`,
260
+ async () => {
261
+ const options = state.spawned;
262
+ if (options == null) throw new Error("the re-attach case failed");
263
+ const attached = await attachOrFail(await targets.attachOn(), options);
264
+ const [out, err, exit] = await Promise.all([
265
+ streamToString(attached.stdout),
266
+ streamToString(attached.stderr),
267
+ attached.wait()
268
+ ]);
269
+ check(
270
+ out === after(DURABLE_STDOUT, options.stdoutOffset) && err === after(DURABLE_STDERR, options.stderrOffset),
271
+ `after exit: ${JSON.stringify([out, err])}`
272
+ );
273
+ check(exit.exitCode === 7, `exit code after exit ${exit.exitCode}`);
274
+ }
275
+ );
276
+ await record(`${prefix}durable processes: kill through an attached handle`, async () => {
277
+ const controller = new AbortController();
278
+ const sandbox = await targets.spawnOn();
279
+ const process = await sandbox.spawn({
280
+ command: "sleep 30",
281
+ shell: true,
282
+ durable: true,
283
+ abortSignal: controller.signal
284
+ });
285
+ const ref = process.ref;
286
+ if (ref == null) throw new Error("a durable process has no ref");
287
+ targets.drop({ controller, sandbox });
288
+ const attached = await attachOrFail(await targets.attachOn(), {
289
+ ref,
290
+ stdoutOffset: 0,
291
+ stderrOffset: 0
292
+ });
293
+ void streamToString(attached.stdout).catch(() => void 0);
294
+ void streamToString(attached.stderr).catch(() => void 0);
295
+ await attached.kill();
296
+ const result = await withTimeout(attached.wait(), 1e4, "wait after kill");
297
+ check(result.exitCode !== 0, "killed process exited 0");
298
+ });
299
+ await record(`${prefix}durable processes: unknown refs and ordinary processes`, async () => {
300
+ const sandbox = await targets.attachOn();
301
+ const unknown = await sandbox.attachProcess?.({
302
+ ref: "conformance-unknown-ref",
303
+ stdoutOffset: 0,
304
+ stderrOffset: 0
305
+ });
306
+ check(unknown === null, "an unknown ref attached to a process");
307
+ const ordinary = await (await targets.spawnOn()).spawn({ command: "echo", args: ["ordinary"] });
308
+ check(ordinary.ref == null, "an ordinary process has a ref");
309
+ await Promise.all([
310
+ streamToString(ordinary.stdout),
311
+ streamToString(ordinary.stderr),
312
+ ordinary.wait()
313
+ ]);
314
+ });
315
+ };
186
316
  const startFromProvider = async (args, provider, overrides = {}) => {
187
317
  const implementation = provider.definition.environment(
188
318
  overrides.environmentOptions ?? args.environmentOptions
@@ -461,6 +591,25 @@ const runSandboxConformance = async (args) => {
461
591
  const root = target.resolvePath(`conformance-${crypto.randomUUID().slice(0, 8)}`);
462
592
  const list = sandboxCases(args.largeFileBytes ?? 5 * 1024 * 1024);
463
593
  for (const entry of list) await record(entry.name, () => entry.run(target, root));
594
+ const durable = target.attachProcess != null;
595
+ if (durable)
596
+ await durableCases(
597
+ {
598
+ spawnOn: async () => target,
599
+ attachOn: async () => target,
600
+ drop: ({ controller }) => controller.abort()
601
+ },
602
+ record,
603
+ ""
604
+ );
605
+ else
606
+ cases.push({
607
+ name: "durable processes",
608
+ status: ConformanceCaseStatus.Skipped,
609
+ durationMs: 0,
610
+ error: null,
611
+ detail: "the sandbox has no attachProcess"
612
+ });
464
613
  if (args.viaWire !== false) {
465
614
  const network = createInMemoryHandleNetwork();
466
615
  network.serve({ url: "mem://conformance", sandbox: target });
@@ -512,6 +661,30 @@ const runSandboxConformance = async (args) => {
512
661
  readOnly.close();
513
662
  }
514
663
  });
664
+ if (durable) {
665
+ const connections = [];
666
+ const open = async () => {
667
+ const connection = await network.connect({
668
+ url: "mem://conformance",
669
+ token: "conformance"
670
+ });
671
+ connections.push(connection);
672
+ return connection;
673
+ };
674
+ try {
675
+ await durableCases(
676
+ {
677
+ spawnOn: open,
678
+ attachOn: open,
679
+ drop: ({ sandbox: sandbox2 }) => connections.find((entry) => entry === sandbox2)?.close()
680
+ },
681
+ record,
682
+ "handle rpc: "
683
+ );
684
+ } finally {
685
+ for (const connection of connections) connection.close();
686
+ }
687
+ }
515
688
  } finally {
516
689
  client.close();
517
690
  await target.removePath({ path: `${root}-wire`, recursive: true, force: true }).catch(() => void 0);
@@ -537,6 +710,7 @@ const runSandboxConformance = async (args) => {
537
710
  return { passed: cases.every((entry) => entry.status !== ConformanceCaseStatus.Failed), cases };
538
711
  };
539
712
  export {
713
+ DURABLE_CONFORMANCE_SCRIPT,
540
714
  runSandboxConformance
541
715
  };
542
716
  //# sourceMappingURL=sandbox-kit.mjs.map