@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,400 +1,360 @@
1
- import type { HostedBindingsIface } from "./hosted-bindings.mjs";
2
- import type { ContentBlock, SessionUpdate } from '@agentclientprotocol/sdk/experimental/v2';
3
- import type { SessionUpdateKind } from '@finalai/acp-session';
1
+ import type { ContentBlock } from '@agentclientprotocol/sdk/experimental/v2';
4
2
  import * as z from 'zod';
5
- import type { ChannelSessionOperationsIface } from "./channel-context.mjs";
6
3
  import { type JsonObject, type JsonValue } from "./json.mjs";
7
4
  import type { ProviderRef } from "./provider-ref.mjs";
8
- import type { SemanticChannelEventKind } from "./semantic-events.mjs";
9
- export declare enum ChannelPrincipalType {
10
- User = "user",
11
- Service = "service"
12
- }
13
- export interface ChannelAuthIface extends JsonObject {
14
- principalId: string;
15
- principalType: ChannelPrincipalType | `${ChannelPrincipalType}`;
16
- authenticator: string;
17
- attributes: JsonObject;
18
- }
19
- export declare const channelAuthSchema: z.ZodObject<{
20
- principalId: z.ZodString;
21
- principalType: z.ZodEnum<typeof ChannelPrincipalType>;
22
- authenticator: z.ZodString;
5
+ import type { ChannelSocketIface, ChannelTurnStateIface } from "./room-surface.mjs";
6
+ import type { ChannelSemanticDataByKindIface } from "./semantic-events.mjs";
7
+ export * from "./room-surface.mjs";
8
+ export declare const personHandleSchema: z.core.$ZodBranded<z.ZodString, "ChannelPerson", "out">;
9
+ export declare const conversationHandleSchema: z.core.$ZodBranded<z.ZodString, "ChannelConversation", "out">;
10
+ export type PersonHandle = z.infer<typeof personHandleSchema>;
11
+ export type ConversationHandle = z.infer<typeof conversationHandleSchema>;
12
+ export declare const principalRefSchema: z.ZodObject<{
13
+ id: z.ZodString;
14
+ tenant: z.ZodOptional<z.ZodString>;
23
15
  displayName: z.ZodOptional<z.ZodString>;
24
- attributes: z.ZodDefault<z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
25
16
  }, z.core.$strip>;
26
- export declare const principalDisplayName: (auth: ChannelAuthIface) => string;
27
- export declare enum ConversationKind {
28
- Direct = "direct",
29
- Group = "group"
30
- }
31
- export declare enum ParticipantKind {
32
- User = "user",
33
- Agent = "agent"
34
- }
35
- export declare enum RoutingMode {
36
- Mention = "mention",
37
- All = "all",
38
- Default = "default"
39
- }
40
- export declare enum TurnPolicy {
41
- Steer = "steer",
42
- Queue = "queue"
43
- }
44
- export declare enum Delivery {
45
- Prompt = "prompt",
46
- Observe = "observe"
47
- }
48
- export declare enum MessageKind {
49
- Message = "message",
50
- Card = "card"
17
+ export type PrincipalRef = z.infer<typeof principalRefSchema>;
18
+ export interface PlaceRef {
19
+ kind: string;
20
+ id: string;
21
+ tenant?: string;
22
+ parent?: PlaceRef;
23
+ title?: string;
51
24
  }
52
- export declare enum CardKind {
53
- Elicitation = "elicitation",
54
- Permission = "permission",
55
- Notice = "notice"
25
+ export declare const placeRefSchema: z.ZodType<PlaceRef>;
26
+ export interface OriginIface {
27
+ place: PlaceRef;
28
+ ref?: JsonObject;
56
29
  }
57
- export interface ParticipantIface {
58
- id: string;
59
- kind: ParticipantKind;
30
+ export declare const originSchema: z.ZodObject<{
31
+ place: z.ZodType<PlaceRef, unknown, z.core.$ZodTypeInternals<PlaceRef, unknown>>;
32
+ ref: z.ZodOptional<z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
33
+ }, z.core.$strip>;
34
+ export type PersonResolution = {
35
+ kind: 'member';
36
+ person: PersonHandle;
60
37
  displayName: string;
61
- userId: string | null;
62
- definitionId: string | null;
63
- routingMode: RoutingMode | null;
64
- sessionId: string | null;
65
- supportsObserve: boolean | null;
66
- rendersAuthorMeta: boolean | null;
67
- left: boolean;
38
+ } | {
39
+ kind: 'unlinked';
40
+ linkUrl: string;
41
+ } | {
42
+ kind: 'blocked';
43
+ reason: 'not-in-organization' | 'suspended';
44
+ };
45
+ export declare enum ChannelReplies {
46
+ Origin = "origin",
47
+ All = "all"
48
+ }
49
+ export declare enum ChannelAudience {
50
+ Members = "members",
51
+ Anyone = "anyone"
52
+ }
53
+ export declare enum ChannelCreate {
54
+ DirectWithAgent = "direct-with-agent",
55
+ Group = "group"
68
56
  }
57
+ export declare const placePolicySchema: z.ZodObject<{
58
+ replies: z.ZodEnum<typeof ChannelReplies>;
59
+ audience: z.ZodEnum<typeof ChannelAudience>;
60
+ }, z.core.$strip>;
61
+ export interface PlacePolicy {
62
+ replies: ChannelReplies | `${ChannelReplies}`;
63
+ audience: ChannelAudience | `${ChannelAudience}`;
64
+ }
65
+ export interface PlaceDefaultsIface extends PlacePolicy {
66
+ create: ChannelCreate | `${ChannelCreate}`;
67
+ }
68
+ export type PlaceResolution = {
69
+ kind: 'connected';
70
+ conversation: ConversationHandle;
71
+ policy: PlacePolicy;
72
+ } | {
73
+ kind: 'unconnected';
74
+ connectUrl: string;
75
+ defaults: PlaceDefaultsIface | null;
76
+ };
77
+ export interface Refusal {
78
+ refused: 'unlinked' | 'no-access' | 'unconnected' | 'not-audience';
79
+ linkUrl?: string;
80
+ connectUrl?: string;
81
+ message: string;
82
+ }
83
+ export type ChannelReceiveResult = {
84
+ accepted: true;
85
+ } | {
86
+ accepted: false;
87
+ refusal: Refusal;
88
+ } | {
89
+ ignored: true;
90
+ reason: string;
91
+ };
92
+ export declare const refusalSchema: z.ZodObject<{
93
+ refused: z.ZodUnion<readonly [z.ZodLiteral<"unlinked">, z.ZodLiteral<"no-access">, z.ZodLiteral<"unconnected">, z.ZodLiteral<"not-audience">]>;
94
+ linkUrl: z.ZodOptional<z.ZodString>;
95
+ connectUrl: z.ZodOptional<z.ZodString>;
96
+ message: z.ZodString;
97
+ }, z.core.$strip>;
69
98
  export declare const channelReceiveResultSchema: z.ZodUnion<readonly [z.ZodObject<{
70
- conversationId: z.ZodString;
99
+ accepted: z.ZodLiteral<true>;
71
100
  }, z.core.$strip>, z.ZodObject<{
72
- sessionId: z.ZodString;
73
- }, z.core.$strip>, z.ZodNull]>;
74
- export type ChannelReceiveResult = z.infer<typeof channelReceiveResultSchema>;
75
- export interface ConversationRefIface {
76
- conversationId: string;
77
- }
78
- export interface ConversationIface extends ConversationRefIface {
79
- organizationId: string;
80
- kind: ConversationKind;
81
- title: string | null;
82
- isHome: boolean;
83
- turnPolicy: TurnPolicy;
84
- }
85
- export interface MessageRefIface {
86
- messageId: string;
87
- seq: number;
88
- }
89
- export interface ConversationMessageIface extends MessageRefIface {
90
- conversationId: string;
91
- authorParticipantId: string;
92
- kind: MessageKind;
93
- body: string;
94
- content: ContentBlock[];
95
- replyToMessageId: string | null;
96
- threadRootId: string | null;
97
- quotedMessageIds: string[];
98
- mentionedParticipantIds: string[];
99
- hopDepth: number;
100
- agentAuthorDefinitionId?: string | null;
101
- createdAt: string;
102
- }
103
- export interface RouteArgsIface {
104
- conversation: ConversationIface;
105
- message: ConversationMessageIface;
106
- participants: ParticipantIface[];
107
- agentParticipantId?: string;
108
- }
109
- export interface RouteDecisionIface {
110
- participantId: string;
111
- delivery: Delivery;
112
- }
113
- export interface PostMessageArgsIface {
114
- conversationId: string;
115
- authorParticipantId: string;
116
- kind?: MessageKind;
101
+ accepted: z.ZodLiteral<false>;
102
+ refusal: z.ZodObject<{
103
+ refused: z.ZodUnion<readonly [z.ZodLiteral<"unlinked">, z.ZodLiteral<"no-access">, z.ZodLiteral<"unconnected">, z.ZodLiteral<"not-audience">]>;
104
+ linkUrl: z.ZodOptional<z.ZodString>;
105
+ connectUrl: z.ZodOptional<z.ZodString>;
106
+ message: z.ZodString;
107
+ }, z.core.$strip>;
108
+ }, z.core.$strip>, z.ZodObject<{
109
+ ignored: z.ZodLiteral<true>;
110
+ reason: z.ZodString;
111
+ }, z.core.$strip>]>;
112
+ export interface InstalledAppInfoIface {
113
+ clientId: string;
114
+ clientSecret: string;
115
+ signingSecret?: string;
116
+ }
117
+ export interface InstalledAppCredential extends InstalledAppInfoIface {
118
+ accessToken: string;
119
+ tenantId?: string;
120
+ externalId?: string;
121
+ expiresAt?: string | null;
122
+ customHeaders?: Record<string, string>;
123
+ }
124
+ export interface ChannelCredentialsIface {
125
+ appInfo(): Promise<InstalledAppInfoIface>;
126
+ app(options?: {
127
+ tenant?: string;
128
+ }): Promise<InstalledAppCredential>;
129
+ secret(name: string): Promise<string | null>;
130
+ fetch: typeof fetch;
131
+ }
132
+ export interface ChannelPostArgsIface {
133
+ from: PersonHandle;
117
134
  content: ContentBlock[];
118
- replyToMessageId?: string | null;
119
- threadRootId?: string | null;
120
- quotedMessageIds?: string[];
121
- clientMessageId?: string | null;
122
- mentionedParticipantIds?: string[];
123
- attachmentIds?: string[];
124
- hopDepth?: number;
125
- originTurnId?: string | null;
126
- source?: {
127
- turnId: string;
128
- fromSeq: number;
129
- toSeq: number;
130
- } | null;
131
- }
132
- export declare const channelMessageInputSchema: z.ZodObject<{
133
- conversationId: z.ZodString;
134
- authorParticipantId: z.ZodString;
135
- kind: z.ZodDefault<z.ZodEnum<typeof MessageKind>>;
136
- content: z.ZodArray<z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
137
- clientMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
138
- replyToMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
139
- threadRootId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
140
- quotedMessageIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
141
- mentionedParticipantIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
142
- }, z.core.$strip>;
143
- export interface CardArgsIface {
144
- conversationId: string;
145
- authorParticipantId: string;
146
- kind: CardKind;
147
- decisionId: string | null;
148
- state: JsonObject;
149
- entityLinks: {
150
- kind: string;
151
- id: string;
152
- title?: string;
153
- url?: string;
154
- description?: string;
155
- imageUrl?: string;
156
- }[];
157
- }
158
- export interface PromptArgsIface {
135
+ context?: string[];
136
+ origin: OriginIface;
137
+ idempotencyKey: string;
159
138
  waitForAcceptance?: boolean;
160
- channelBinding?: {
139
+ }
140
+ export interface ChannelConversationIface {
141
+ post(args: ChannelPostArgsIface): Promise<{
142
+ messageId: string;
143
+ turnId?: string;
144
+ } | Refusal>;
145
+ input(args: {
146
+ label: string;
147
+ principal?: PrincipalRef;
148
+ content: ContentBlock[];
149
+ context?: string[];
150
+ origin: OriginIface;
151
+ idempotencyKey: string;
152
+ waitForAcceptance?: boolean;
153
+ }): Promise<{
154
+ inputId: string;
155
+ turnId?: string;
156
+ } | Refusal>;
157
+ attach(args: {
158
+ origin: OriginIface;
159
+ content: ContentBlock[];
160
+ label: string;
161
+ idempotencyKey: string;
162
+ from?: PersonHandle;
163
+ }): Promise<{
164
+ messageId: string;
165
+ } | Refusal>;
166
+ edit(args: {
167
+ externalKey: string;
168
+ by: PersonHandle;
169
+ content: ContentBlock[];
170
+ }): Promise<{
171
+ messageId: string;
172
+ } | Refusal>;
173
+ remove(args: {
174
+ externalKey: string;
175
+ by: PersonHandle;
176
+ }): Promise<{
177
+ removed: boolean;
178
+ } | Refusal>;
179
+ react(args: {
180
+ target: {
181
+ externalKey: string;
182
+ } | {
183
+ replyOf: {
184
+ externalKey: string;
185
+ turnId: string;
186
+ };
187
+ };
188
+ emoji: string;
189
+ by: PersonHandle;
190
+ op: 'add' | 'remove';
191
+ }): Promise<{
192
+ ok: true;
193
+ } | Refusal>;
194
+ }
195
+ export type SemanticEvent = {
196
+ [Kind in keyof ChannelSemanticDataByKindIface]: {
197
+ type: Kind;
198
+ data: ChannelSemanticDataByKindIface[Kind];
199
+ seq: number;
200
+ };
201
+ }[keyof ChannelSemanticDataByKindIface];
202
+ export interface ChannelReceiveContextIface<Config = JsonObject> {
203
+ binding: {
161
204
  id: string;
162
- revisionId: string;
205
+ owner: {
206
+ kind: 'agent';
207
+ definitionId: string;
208
+ } | {
209
+ kind: 'install';
210
+ installId: string;
211
+ };
163
212
  };
164
- auth?: ChannelAuthIface | null;
165
- title?: string;
166
- participantId: string;
167
- content: ContentBlock[];
168
- turnPolicy: TurnPolicy;
169
- replyExpected: boolean;
170
- idempotencyKey: string;
171
- authorParticipantId: string;
172
- actingUserId?: string | null;
173
- audienceParticipantIds: string[];
174
- sourceMessageId: string;
175
- }
176
- export interface ObserveArgsIface {
177
- participantId: string;
178
- content: ContentBlock[];
179
- idempotencyKey: string;
180
- }
181
- export interface ChannelPlatformIface {
182
- channelSessions?: ChannelSessionOperationsIface;
183
- conversations: {
184
- get(conversationId: string): Promise<ConversationIface | null>;
185
- createAttachmentUpload?(args: {
186
- conversationId: string;
187
- name: string;
188
- contentType: string;
189
- sizeBytes: number;
213
+ config: Config;
214
+ credentials: ChannelCredentialsIface;
215
+ people: {
216
+ resolve(principal: PrincipalRef): Promise<PersonResolution>;
217
+ identify(person: PersonHandle): Promise<PrincipalRef | null>;
218
+ revoke(args: {
219
+ principal?: PrincipalRef;
220
+ tenant?: string;
221
+ reason: 'deactivated' | 'uninstalled' | 'provider-revoked';
222
+ }): Promise<void>;
223
+ confirm(args: {
224
+ ticket: string;
225
+ principal: PrincipalRef;
190
226
  }): Promise<{
191
- attachmentId: string;
192
- uploadUrl: string;
193
- method: string;
194
- headers: Record<string, string>;
195
- expiresAt: string;
227
+ linked: true;
228
+ } | Refusal>;
229
+ };
230
+ places: {
231
+ resolve(place: PlaceRef): Promise<PlaceResolution>;
232
+ observers(place: PlaceRef): Promise<ConversationHandle[]>;
233
+ connect(place: PlaceRef, to: {
234
+ by: PersonHandle;
235
+ conversation?: ConversationHandle;
236
+ create?: ChannelCreate | `${ChannelCreate}`;
237
+ }): Promise<ConversationHandle>;
238
+ disconnect(place: PlaceRef, by: PersonHandle): Promise<void>;
239
+ };
240
+ conversation(handle: ConversationHandle): ChannelConversationIface;
241
+ observe(handle: ConversationHandle, args?: {
242
+ turnId?: string;
243
+ signal?: AbortSignal;
244
+ }): AsyncIterable<SemanticEvent>;
245
+ media: {
246
+ transcribe(audio: AsyncIterable<Uint8Array>, options: {
247
+ encoding: string;
248
+ sampleRate: number;
249
+ language?: string;
250
+ endpointing?: boolean;
251
+ signal?: AbortSignal;
252
+ }): AsyncIterable<{
253
+ text: string;
254
+ final: boolean;
196
255
  }>;
197
- getAttachmentUrl?(args: {
198
- conversationId: string;
199
- attachmentId: string;
256
+ synthesize(text: AsyncIterable<string>, options: {
257
+ voice?: string;
258
+ encoding: string;
259
+ sampleRate: number;
260
+ signal?: AbortSignal;
261
+ }): AsyncIterable<Uint8Array>;
262
+ };
263
+ decisions: {
264
+ resolve(args: {
265
+ decisionId: string;
266
+ outcome: JsonValue;
267
+ by: PersonHandle;
200
268
  }): Promise<{
201
- attachmentId: string;
202
- url: string;
203
- expiresAt: string;
204
- }>;
205
- dispatchMessage?(args: {
206
- conversationId: string;
207
- messageId: string;
208
- participantId?: string;
209
- requestedDelivery?: Delivery;
210
- }): Promise<void>;
211
- findOrCreateDirect(args: {
212
- organizationId: string;
213
- userId: string;
214
- definitionId: string;
215
- }): Promise<ConversationIface>;
216
- boundTo(bindingId: string): Promise<ConversationIface | null>;
217
- participants(conversationId: string): Promise<ParticipantIface[]>;
218
- postMessage(args: PostMessageArgsIface): Promise<ConversationMessageIface>;
219
- updateMessage(args: {
220
- messageId: string;
221
- content: ContentBlock[];
222
- final: boolean;
223
- }): Promise<void>;
224
- postCard(args: CardArgsIface): Promise<ConversationMessageIface>;
225
- updateCard(args: {
226
- messageId: string;
227
- state: JsonObject;
228
- }): Promise<void>;
229
- recentMessages(args: {
230
- conversationId: string;
231
- limit: number;
232
- beforeSeq?: number;
233
- afterSeq?: number;
234
- }): Promise<ConversationMessageIface[]>;
235
- getMessages(args: {
236
- conversationId: string;
237
- messageIds: string[];
238
- }): Promise<ConversationMessageIface[]>;
269
+ resolved: boolean;
270
+ } | Refusal>;
239
271
  };
240
- sessions: {
241
- prompt(args: PromptArgsIface): Promise<{
242
- messageId: string;
243
- sessionId?: string;
244
- turnId?: string;
245
- }>;
246
- observe(args: ObserveArgsIface): Promise<void>;
272
+ turns: {
247
273
  cancel(args: {
248
- participantId: string;
249
- reason?: string;
250
- throughMessageSeq?: number;
274
+ conversation: ConversationHandle;
275
+ by?: PersonHandle;
276
+ turnId?: string;
277
+ }): Promise<{
278
+ accepted: boolean;
279
+ } | Refusal>;
280
+ };
281
+ store: {
282
+ get(key: string): Promise<JsonValue | null>;
283
+ set(key: string, value: JsonValue | null, options?: {
284
+ ttlSeconds?: number;
251
285
  }): Promise<void>;
252
- respond?(args: ChannelInputResponseIface): Promise<{
253
- resolved: boolean;
254
- }>;
255
286
  };
256
- log(message: string, details?: Record<string, JsonValue>): void;
287
+ log(message: string, details?: JsonObject): void;
257
288
  }
258
- export interface ChannelInputResponseIface {
259
- channelBinding?: {
289
+ export interface ChannelEventContextIface<Config = JsonObject, State = JsonValue> extends Pick<ChannelReceiveContextIface<Config>, 'binding' | 'config' | 'credentials' | 'store' | 'log'> {
290
+ origin: OriginIface;
291
+ conversation: ConversationHandle;
292
+ turn: {
260
293
  id: string;
261
- revisionId: string;
262
- };
263
- auth?: ChannelAuthIface | null;
264
- participantId: string;
265
- decisionId: string;
266
- outcome: JsonValue;
267
- actorParticipantId: string;
268
- userId: string | null;
269
- }
270
- export interface ChannelReceiveContextIface {
271
- bindings?: HostedBindingsIface;
272
- platform: ChannelPlatformIface;
273
- organizationId: string;
274
- definitionId: string | null;
275
- bindingId: string | null;
276
- config: JsonObject;
277
- secrets: {
278
- get(name: string): Promise<string | null>;
294
+ agent: {
295
+ displayName: string;
296
+ };
279
297
  };
280
- agentParticipantId?: string;
281
- message?: ConversationMessageIface;
282
- conversation?: ConversationIface;
283
- participants?: readonly ParticipantIface[];
284
- response?: ChannelInputResponseIface;
285
- conversationId?: string;
286
- cancelReason?: string;
287
- cancelThroughMessageSeq?: number;
288
- requestedDelivery?: Delivery;
298
+ state: ChannelTurnStateIface<State>;
289
299
  }
290
- export interface ChannelRouteContextIface {
291
- bindings?: HostedBindingsIface;
300
+ export interface ChannelRouteContextIface<Config = JsonObject> extends ChannelReceiveContextIface<Config> {
292
301
  request: Request;
293
- secrets: {
294
- get(name: string): Promise<string | null>;
295
- };
296
- receive: (input: JsonValue) => Promise<ChannelReceiveResult>;
302
+ authenticatedPrincipal?: PrincipalRef;
303
+ receive(input: JsonValue): Promise<ChannelReceiveResult>;
297
304
  }
298
- export interface ChannelSocketIface {
299
- readonly signal: AbortSignal;
300
- readonly messages: AsyncIterable<string | Uint8Array>;
301
- accept(options?: {
302
- protocol?: string;
303
- }): void;
304
- send(data: string | Uint8Array): void;
305
- close(code?: number, reason?: string): void;
306
- }
307
- export interface HttpChannelRouteDefinitionIface {
305
+ export interface HttpChannelRouteDefinitionIface<Config = JsonObject> {
308
306
  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
309
307
  path: string;
310
- handler: (args: ChannelRouteContextIface) => Promise<Response>;
308
+ handler(args: ChannelRouteContextIface<Config>): Promise<Response>;
311
309
  }
312
- export interface WebSocketChannelRouteDefinitionIface {
310
+ export interface WebSocketChannelRouteDefinitionIface<Config = JsonObject> {
313
311
  method: 'WS';
314
312
  path: string;
315
- handler: (args: ChannelRouteContextIface & {
313
+ handler(args: ChannelRouteContextIface<Config> & {
316
314
  socket: ChannelSocketIface;
317
- }) => Promise<Response | void>;
318
- }
319
- export type RouteDefinitionIface = HttpChannelRouteDefinitionIface | WebSocketChannelRouteDefinitionIface;
320
- export interface ChannelTurnStateIface<State> {
321
- get(): State | null;
322
- set(state: State | null): void;
323
- }
324
- export interface ProjectionContextIface<State = JsonValue> {
325
- bindings?: HostedBindingsIface;
326
- sessionId?: string;
327
- platform: ChannelPlatformIface;
328
- config: JsonObject;
329
- secrets: {
330
- get(name: string): Promise<string | null>;
315
+ }): Promise<Response | void>;
316
+ }
317
+ export type RouteDefinitionIface<Config = JsonObject> = HttpChannelRouteDefinitionIface<Config> | WebSocketChannelRouteDefinitionIface<Config>;
318
+ export type ChannelEventHandlersIface<Config, State> = {
319
+ [Kind in keyof ChannelSemanticDataByKindIface]?: (data: ChannelSemanticDataByKindIface[Kind], ctx: ChannelEventContextIface<Config, State>) => Promise<void>;
320
+ };
321
+ export type ChannelEventKind = keyof ChannelSemanticDataByKindIface;
322
+ export interface ChannelDefinitionIface<Config = JsonObject, Inbound = JsonValue, State = JsonValue> {
323
+ name: string;
324
+ config?: Config;
325
+ installed?: ProviderRef;
326
+ configure?(config: Config): ChannelDefinitionIface<Config, Inbound, State>;
327
+ credentials: {
328
+ app: string | null;
329
+ secrets?: string[];
331
330
  };
332
- conversation: ConversationIface | null;
333
- agentParticipant: ParticipantIface | null;
334
- turn: {
335
- id: string;
336
- promptMessageId: string | null;
337
- authorParticipantId: string | null;
331
+ identity: {
332
+ kind: 'redirect';
333
+ start(args: {
334
+ ticket: string;
335
+ principal: PrincipalRef;
336
+ }, ctx: ChannelReceiveContextIface<Config>): Promise<URL>;
337
+ } | {
338
+ kind: 'challenge';
339
+ deliver(args: {
340
+ principal: PrincipalRef;
341
+ code: string;
342
+ }, ctx: ChannelReceiveContextIface<Config>): Promise<void>;
343
+ } | {
344
+ kind: 'none';
338
345
  };
339
- seq: number;
340
- state: ChannelTurnStateIface<State>;
341
- }
342
- export declare enum DecisionEventKind {
343
- Created = "decision.created",
344
- Resolved = "decision.resolved"
345
- }
346
- export type AcpUpdateKind = SessionUpdate['sessionUpdate'];
347
- export type KnownAcpUpdateKind = `${SessionUpdateKind}`;
348
- export type ChannelEventKind = AcpUpdateKind | `${DecisionEventKind}` | `${SemanticChannelEventKind}`;
349
- export interface ChannelEventIface {
350
- type: string;
351
- data: JsonValue;
352
- seq: number;
353
- }
354
- export type ChannelEventHandler<State = JsonValue> = (event: ChannelEventIface, ctx: ProjectionContextIface<State>) => Promise<void>;
355
- export declare enum DecisionKind {
356
- Permission = "permission",
357
- Elicitation = "elicitation"
358
- }
359
- export declare const decisionCreatedDataSchema: z.ZodObject<{
360
- decisionId: z.ZodString;
361
- kind: z.ZodEnum<typeof DecisionKind>;
362
- audienceParticipantIds: z.ZodArray<z.ZodString>;
363
- request: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
364
- }, z.core.$strip>;
365
- export type DecisionCreatedDataIface = z.infer<typeof decisionCreatedDataSchema>;
366
- export declare const decisionResolvedDataSchema: z.ZodObject<{
367
- decisionId: z.ZodString;
368
- outcome: z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>;
369
- respondedBy: z.ZodDefault<z.ZodNullable<z.ZodObject<{
370
- principalId: z.ZodString;
371
- principalType: z.ZodEnum<typeof ChannelPrincipalType>;
372
- authenticator: z.ZodString;
373
- displayName: z.ZodOptional<z.ZodString>;
374
- attributes: z.ZodDefault<z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
375
- }, z.core.$strip>>>;
376
- }, z.core.$strip>;
377
- export type DecisionResolvedDataIface = z.infer<typeof decisionResolvedDataSchema>;
378
- export declare const PROJECTED_UPDATE_KINDS: ReadonlySet<AcpUpdateKind>;
379
- export declare const turnEndOf: (update: SessionUpdate) => {
380
- stopReason: string | null;
381
- } | null;
382
- export declare const turnEndUpdate: (stopReason: string | null) => SessionUpdate;
383
- export interface ChannelDefinitionIface<Inbound, State = undefined> {
384
- config?: JsonObject;
385
- installed?: ProviderRef;
386
- configure?: (config: JsonObject) => ChannelDefinitionIface<Inbound, State>;
387
- routes?: RouteDefinitionIface[];
388
- respond?(input: ChannelInputResponseIface, ctx: ChannelReceiveContextIface): Promise<{
389
- resolved: boolean;
390
- }>;
391
- cancel?(ctx: ChannelReceiveContextIface): Promise<{
392
- accepted: boolean;
393
- }>;
394
- receive(input: Inbound, ctx: ChannelReceiveContextIface): Promise<ChannelReceiveResult>;
395
- route(args: RouteArgsIface): RouteDecisionIface[] | Promise<RouteDecisionIface[]>;
396
- turnPolicy: TurnPolicy;
397
- project(update: SessionUpdate, ctx: ProjectionContextIface<State>): Promise<void>;
398
- events?: Partial<Record<ChannelEventKind, ChannelEventHandler<State>>>;
346
+ places: {
347
+ kinds: readonly string[];
348
+ defaults?(place: PlaceRef): PlaceDefaultsIface | null;
349
+ };
350
+ routes?: RouteDefinitionIface<Config>[];
351
+ listeners?: {
352
+ key: string;
353
+ run(ctx: ChannelReceiveContextIface<Config> & {
354
+ signal: AbortSignal;
355
+ }): Promise<void>;
356
+ }[];
357
+ receive(input: Inbound, ctx: ChannelReceiveContextIface<Config>): Promise<ChannelReceiveResult>;
358
+ events?: ChannelEventHandlersIface<Config, State>;
399
359
  }
400
- export declare const defineChannel: <Inbound, State = undefined>(definition: ChannelDefinitionIface<Inbound, State>) => ChannelDefinitionIface<Inbound, State>;
360
+ export declare const defineChannel: <Config = JsonObject, Inbound = JsonValue, State = JsonValue>(definition: ChannelDefinitionIface<Config, Inbound, State>) => ChannelDefinitionIface<Config, Inbound, State>;