@squidcloud/jira-jsm-client 1.0.496 → 1.0.498

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 (64) hide show
  1. package/dist/connectors/jira_jsm/common/src/jira-jsm-types.d.ts +1 -28
  2. package/dist/internal-common/src/ai/system-openai-compatible.d.ts +35 -0
  3. package/dist/internal-common/src/public-types/ai-agent-integrations.public-types.d.ts +71 -0
  4. package/dist/internal-common/src/public-types/ai-agent.public-types.d.ts +1594 -0
  5. package/dist/internal-common/src/public-types/ai-common.public-types.d.ts +303 -0
  6. package/dist/internal-common/src/public-types/ai-function.public-types.d.ts +114 -0
  7. package/dist/internal-common/src/public-types/ai-knowledge-base.public-types.d.ts +2378 -0
  8. package/dist/internal-common/src/public-types/ai-query.public-types.d.ts +266 -0
  9. package/dist/internal-common/src/public-types/api-client.public-types.d.ts +9 -0
  10. package/dist/internal-common/src/public-types/api.public-types.d.ts +99 -0
  11. package/dist/internal-common/src/public-types/backend.public-types.d.ts +61 -0
  12. package/dist/internal-common/src/public-types/connector.public-types.d.ts +12 -0
  13. package/dist/internal-common/src/public-types/context.public-types.d.ts +83 -0
  14. package/dist/internal-common/src/public-types/document.public-types.d.ts +71 -0
  15. package/dist/internal-common/src/public-types/event.public-types.d.ts +18 -0
  16. package/dist/internal-common/src/public-types/extraction.public-types.d.ts +405 -0
  17. package/dist/internal-common/src/public-types/http-status.public-types.d.ts +415 -0
  18. package/dist/internal-common/src/public-types/integration.public-types.d.ts +65 -0
  19. package/dist/internal-common/src/public-types/job.public-types.d.ts +101 -0
  20. package/dist/internal-common/src/public-types/langgraph.public-types.d.ts +50 -0
  21. package/dist/internal-common/src/public-types/metadata-filter.public-types.d.ts +106 -0
  22. package/dist/internal-common/src/public-types/query.public-types.d.ts +149 -0
  23. package/dist/internal-common/src/public-types/scheduler.public-types.d.ts +43 -0
  24. package/dist/internal-common/src/public-types/schema.public-types.d.ts +88 -0
  25. package/dist/internal-common/src/public-types/secret.public-types.d.ts +82 -0
  26. package/dist/internal-common/src/public-types/socket.public-types.d.ts +4 -0
  27. package/dist/internal-common/src/public-types/source-code.public-types.d.ts +208 -0
  28. package/dist/internal-common/src/public-types/typescript.public-types.d.ts +20 -0
  29. package/dist/internal-common/src/public-types-backend/ai-agent.public-context.d.ts +101 -0
  30. package/dist/internal-common/src/public-types-backend/api-call.public-context.d.ts +30 -0
  31. package/dist/internal-common/src/public-types-backend/application.public-types.d.ts +94 -0
  32. package/dist/internal-common/src/public-types-backend/bundle-api.public-types.d.ts +199 -0
  33. package/dist/internal-common/src/public-types-backend/bundle-data.public-types.d.ts +18 -0
  34. package/dist/internal-common/src/public-types-backend/distributed-lock.public-context.d.ts +4 -0
  35. package/dist/internal-common/src/public-types-backend/graphql.public-context.d.ts +7 -0
  36. package/dist/internal-common/src/public-types-backend/langgraph.public-context.d.ts +16 -0
  37. package/dist/internal-common/src/public-types-backend/mcp.public-types.d.ts +55 -0
  38. package/dist/internal-common/src/public-types-backend/metric.public-context.d.ts +12 -0
  39. package/dist/internal-common/src/public-types-backend/mutation.public-context.d.ts +161 -0
  40. package/dist/internal-common/src/public-types-backend/native-query.public-context.d.ts +75 -0
  41. package/dist/internal-common/src/public-types-backend/query.public-context.d.ts +193 -0
  42. package/dist/internal-common/src/public-types-backend/storage.public-types.d.ts +15 -0
  43. package/dist/internal-common/src/public-types-backend/topic.public-context.d.ts +17 -0
  44. package/dist/internal-common/src/types/application.types.d.ts +98 -0
  45. package/dist/internal-common/src/types/backend-run.types.d.ts +55 -0
  46. package/dist/internal-common/src/types/bundle-data.types.d.ts +18 -0
  47. package/dist/internal-common/src/types/connector.types.d.ts +77 -0
  48. package/dist/internal-common/src/types/integrations/ai.types.d.ts +1 -0
  49. package/dist/internal-common/src/types/integrations/api.types.d.ts +76 -0
  50. package/dist/internal-common/src/types/integrations/auth.types.d.ts +1 -0
  51. package/dist/internal-common/src/types/integrations/database.types.d.ts +44 -0
  52. package/dist/internal-common/src/types/integrations/observability.types.d.ts +1 -0
  53. package/dist/internal-common/src/types/integrations/queue-types.d.ts +1 -0
  54. package/dist/internal-common/src/types/integrations/schemas.d.ts +6 -0
  55. package/dist/internal-common/src/types/integrations/storage-types.d.ts +22 -0
  56. package/dist/internal-common/src/types/langgraph.types.d.ts +1 -0
  57. package/dist/internal-common/src/types/openapi.types.d.ts +1 -0
  58. package/dist/internal-common/src/types/query.types.d.ts +21 -0
  59. package/dist/internal-common/src/types/secret.types.d.ts +7 -0
  60. package/dist/internal-common/src/types/time-units.d.ts +1 -0
  61. package/dist/internal-common/src/utils/object.d.ts +88 -0
  62. package/dist/internal-common/src/utils/serialization.d.ts +30 -0
  63. package/dist/internal-common/src/utils/worker-manager-utils.d.ts +2 -0
  64. package/package.json +2 -2
@@ -0,0 +1,1594 @@
1
+ import { JSONSchema } from 'json-schema-typed';
2
+ import { AiAudioCreateSpeechModelName, AiAudioTranscriptionModelName, AiChatModelName, AiImageModelName, AiProviderType, AiRerankProvider, AnthropicChatModelName, CanonicalReasoningEffort, EmbeddingModelIdSpec, GeminiChatModelName, GrokChatModelName, ModelIdSpec, OpenAiAudioCreateSpeechModelName, OpenAiAudioTranscriptionModelName, OpenAiChatModelName, OpenAiCreateSpeechFormat, OpenAiImageModelName, VendorAiChatModelName } from './ai-common.public-types';
3
+ import { AiContextMetadata, AiContextMetadataFilter, AiKnowledgeBaseContextType, AiRagType } from './ai-knowledge-base.public-types';
4
+ import { AiFunctionId, AiFunctionIdWithContext, UserAiChatModelName } from './backend.public-types';
5
+ import { AiAgentId, AiContextId, AiKnowledgeBaseId, AppId, IntegrationId } from './communication.public-types';
6
+ import { DocumentExtractionMethod } from './extraction.public-types';
7
+ import { IntegrationType } from './integration.public-types';
8
+ import { JobId } from './job.public-types';
9
+ import { SecretKey } from './secret.public-types';
10
+ /**
11
+ * @category AI
12
+ */
13
+ export type AiGenerateImageOptions = GptImageOptions | StableDiffusionCoreOptions | FluxOptions;
14
+ /**
15
+ * @category AI
16
+ */
17
+ export type OpenAiAudioTranscribeOptions = WhisperTranscribeOptions | Gpt4oTranscribeOptions;
18
+ /**
19
+ * @category AI
20
+ */
21
+ export type AiAudioTranscribeOptions = OpenAiAudioTranscribeOptions;
22
+ /**
23
+ * @category AI
24
+ */
25
+ export type AiAudioCreateSpeechOptions = OpenAiCreateSpeechOptions;
26
+ /**
27
+ * Base options for generating images with an AI model.
28
+ * @category AI
29
+ */
30
+ export interface BaseAiGenerateImageOptions {
31
+ /** The name of the AI model to use for image generation. */
32
+ modelName: AiImageModelName;
33
+ }
34
+ /**
35
+ * Base options for transcribing audio with an AI model.
36
+ * @category AI
37
+ */
38
+ export interface BaseAiAudioTranscribeOptions {
39
+ /** The name of the AI model to use for audio transcription. */
40
+ modelName: AiAudioTranscriptionModelName;
41
+ }
42
+ /**
43
+ * Base options for creating speech with an AI model.
44
+ * @category AI
45
+ */
46
+ export interface BaseAiAudioCreateSpeechOptions {
47
+ /** The name of the AI model to use for speech creation. */
48
+ modelName: AiAudioCreateSpeechModelName;
49
+ }
50
+ /**
51
+ * Options for generating images using OpenAI's gpt-image-* family of models.
52
+ * @category AI
53
+ */
54
+ export interface GptImageOptions extends BaseAiGenerateImageOptions {
55
+ /** Specifies the OpenAI image model to use. */
56
+ modelName: OpenAiImageModelName;
57
+ /** The quality of the generated image; defaults to 'auto'. */
58
+ quality?: 'auto' | 'high' | 'medium' | 'low';
59
+ /** The size of the generated image; defaults to '1024x1024'. */
60
+ size?: '1024x1024' | '1024x1536' | '1536x1024' | 'auto';
61
+ /** The number of images to generate; defaults to 1. */
62
+ numberOfImagesToGenerate?: number;
63
+ }
64
+ /**
65
+ * Base options shared by all OpenAI audio transcription models.
66
+ * @category AI
67
+ */
68
+ export interface BaseOpenAiAudioTranscribeOptions extends BaseAiAudioTranscribeOptions {
69
+ /** Specifies the model for audio transcription. */
70
+ modelName: OpenAiAudioTranscriptionModelName;
71
+ /** The temperature for sampling during transcription; defaults to model-specific value. */
72
+ temperature?: number;
73
+ /** An optional prompt to guide the transcription process. */
74
+ prompt?: string;
75
+ }
76
+ /**
77
+ * Options for transcribing audio using the Whisper model.
78
+ * @category AI
79
+ */
80
+ export interface WhisperTranscribeOptions extends BaseOpenAiAudioTranscribeOptions {
81
+ /** Specifies the Whisper-1 model for audio transcription. */
82
+ modelName: 'whisper-1';
83
+ /** The format of the transcription response; defaults to 'json'. */
84
+ responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt';
85
+ }
86
+ /**
87
+ * Options for transcribing audio using the GPT-4o model.
88
+ * @category AI
89
+ */
90
+ export interface Gpt4oTranscribeOptions extends BaseOpenAiAudioTranscribeOptions {
91
+ /** Specifies the Whisper-1 model for audio transcription. */
92
+ modelName: 'gpt-4o-transcribe' | 'gpt-4o-mini-transcribe';
93
+ /** The format of the transcription response; defaults to 'json'. */
94
+ responseFormat?: 'json';
95
+ }
96
+ /**
97
+ * Options for creating speech using OpenAI's text-to-speech models.
98
+ * @category AI
99
+ */
100
+ export interface OpenAiCreateSpeechOptions extends BaseAiAudioCreateSpeechOptions {
101
+ /** The OpenAI model to use for speech creation (e.g., 'tts-1' or 'tts-1-hd'). */
102
+ modelName: OpenAiAudioCreateSpeechModelName;
103
+ /** The voice to use for speech synthesis; defaults to model-specific value. */
104
+ voice?: 'alloy' | 'ash' | 'ballad' | 'coral' | 'echo' | 'fable' | 'onyx' | 'nova' | 'sage' | 'shimmer' | 'verse';
105
+ /** The format of the audio output; defaults to 'mp3'. */
106
+ responseFormat?: OpenAiCreateSpeechFormat;
107
+ /** An optional prompt to guide the speech synthesis process. */
108
+ instructions?: string;
109
+ /** The speed of the speech; defaults to 1.0. */
110
+ speed?: number;
111
+ }
112
+ /**
113
+ * Options for generating images using the Flux model.
114
+ * @category AI
115
+ */
116
+ export interface FluxOptions extends BaseAiGenerateImageOptions {
117
+ /** Specifies the Flux Pro 1.1 model for image generation. */
118
+ modelName: 'flux-pro-1.1' | 'flux-kontext-pro';
119
+ /** The width of the generated image, must be a multiple of 32, min 256, max 1440; defaults to 1024. */
120
+ width?: number;
121
+ /** The height of the generated image, must be a multiple of 32, min 256, max 1440; defaults to 768. */
122
+ height?: number;
123
+ /** Whether to enhance the prompt for more creative output; defaults to false. */
124
+ prompt_upsampling?: boolean;
125
+ /** A random seed for reproducible generation, if specified. */
126
+ seed?: number;
127
+ /** The safety tolerance level, from 1 (strict) to 5 (permissive). */
128
+ safety_tolerance?: number;
129
+ }
130
+ /**
131
+ * Options for generating images using the Stable Diffusion Core model.
132
+ * @category AI
133
+ */
134
+ export interface StableDiffusionCoreOptions extends BaseAiGenerateImageOptions {
135
+ /** Specifies the Stable Diffusion Core model for image generation. */
136
+ modelName: 'stable-diffusion-core';
137
+ /** The aspect ratio of the generated image; defaults to '1:1'. */
138
+ aspectRatio?: '16:9' | '1:1' | '21:9' | '2:3' | '3:2' | '4:5' | '5:4' | '9:16' | '9:21';
139
+ /** An optional negative prompt to guide what to exclude from the image. */
140
+ negativePrompt?: string;
141
+ /** A random seed for reproducible generation, if specified. */
142
+ seed?: number;
143
+ /** A style preset to apply to the generated image, if specified. */
144
+ stylePreset?: 'analog-film' | 'anime' | 'cinematic' | 'comic-book' | 'digital-art' | 'enhance' | 'fantasy-art' | 'isometric' | 'line-art' | 'low-poly' | 'modeling-compound' | 'neon-punk' | 'origami' | 'photographic' | 'pixel-art' | 'tile-texture';
145
+ /** The format of the output image; defaults to 'png'. */
146
+ outputFormat?: 'jpeg' | 'png' | 'webp';
147
+ }
148
+ /**
149
+ * The possible sources for the LLM provider API key.
150
+ * @category AI
151
+ */
152
+ export type ApiKeySource = 'user' | 'system';
153
+ /**
154
+ * Structured output format configuration for AI models that support schema-constrained responses.
155
+ *
156
+ * The schema is sent to the model's provider, which constrains decoding to it - the model cannot
157
+ * generate tokens that violate the schema, so the response conforms to it exactly.
158
+ *
159
+ * A schema the provider rejects is reported as a `400` carrying its diagnostic, and a model whose
160
+ * protocol cannot carry a schema at all refuses the request with `STRUCTURED_OUTPUT_NOT_SUPPORTED`
161
+ * rather than answering without the shape that was asked for.
162
+ * **Example:**
163
+ * ```typescript
164
+ * {
165
+ * type: 'json_schema',
166
+ * schema: {
167
+ * type: 'object',
168
+ * properties: {
169
+ * name: { type: 'string' },
170
+ * age: { type: 'number' }
171
+ * },
172
+ * required: ['name', 'age'],
173
+ * additionalProperties: false
174
+ * }
175
+ * }
176
+ * ```
177
+ *
178
+ * @see https://docs.anthropic.com/en/docs/build-with-claude/structured-outputs
179
+ * @see https://platform.openai.com/docs/guides/structured-outputs
180
+ * @see https://ai.google.dev/gemini-api/docs/structured-output
181
+ * @see https://docs.x.ai/docs/guides/structured-outputs
182
+ * @category AI
183
+ */
184
+ export interface AiStructuredOutputFormat {
185
+ /** The type of structured output. 'json_schema' is the only one. */
186
+ type: 'json_schema';
187
+ /**
188
+ * The JSON schema that the AI response must strictly conform to.
189
+ * Uses constrained decoding to guarantee schema compliance.
190
+ */
191
+ schema: JSONSchema;
192
+ }
193
+ /**
194
+ * Response format for AI agent responses.
195
+ *
196
+ * **Available formats:**
197
+ * - `'text'`: Plain text response (default) - standard conversational output
198
+ * - `'json_object'`: JSON response - model attempts to return valid JSON, but without strict schema validation
199
+ * - `AiStructuredOutputFormat`: Structured output with schema - guarantees JSON conforms exactly to provided schema
200
+ *
201
+ * **Structured outputs:**
202
+ * Pass an object with `type: 'json_schema'` and a JSON schema. The schema travels to the model's
203
+ * provider, which constrains decoding to it, so the response matches the schema perfectly and
204
+ * parsing or validating it again is unnecessary. A schema the provider rejects comes back as a
205
+ * `400` carrying its diagnostic.
206
+ *
207
+ * Every vendor model carries a schema. The exception is a model whose protocol has no field for
208
+ * one — the CLI agents (`claude-code`, `codex`) and models a customer serves through
209
+ * `@llmService` — where such a request is refused with `STRUCTURED_OUTPUT_NOT_SUPPORTED` rather
210
+ * than answered without the shape it asked for. Use `'json_object'` and state the shape in the
211
+ * prompt for those.
212
+ *
213
+ * **Example with structured output:**
214
+ * ```typescript
215
+ * {
216
+ * responseFormat: {
217
+ * type: 'json_schema',
218
+ * schema: {
219
+ * type: 'object',
220
+ * properties: {
221
+ * sentiment: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
222
+ * confidence: { type: 'number', minimum: 0, maximum: 1 }
223
+ * },
224
+ * required: ['sentiment', 'confidence']
225
+ * }
226
+ * }
227
+ * }
228
+ * ```
229
+ *
230
+ * @category AI
231
+ */
232
+ export type AiAgentResponseFormat = 'text' | 'json_object' | AiStructuredOutputFormat;
233
+ /**
234
+ * @category AI
235
+ */
236
+ export type AiFileUrlType = 'image' | 'document';
237
+ /**
238
+ * Represents a URL reference to an AI-processed file, such as an image.
239
+ * @category AI
240
+ */
241
+ export interface AiFileUrl {
242
+ /** The unique identifier for the file URL for the current request. */
243
+ id: string;
244
+ /** The type of file referenced by the URL (e.g., 'image'). */
245
+ type: AiFileUrlType;
246
+ /** The purpose of the file, indicating how it will be used in AI processing. */
247
+ purpose: AiFilePurpose;
248
+ /** The URL pointing to the file. */
249
+ url: string;
250
+ /** An optional description of the file's content or purpose - sent to the AI. */
251
+ description?: string;
252
+ /** The file name, can be used in the prompt to reference the file. */
253
+ fileName?: string;
254
+ }
255
+ /**
256
+ * The purpose of the AI file, used to determine how the file should be processed or utilized.
257
+ *
258
+ * - `'context'` - The file is included directly in the AI prompt as contextual content (e.g., images, PDFs).
259
+ * Use this for files that the AI should reference when generating a response.
260
+ * - `'tools'` - The file is returned as part of a tool/function call result (e.g., query results, generated documents).
261
+ * Use this for files produced by AI tools or integrations that should be delivered to the caller alongside the response.
262
+ */
263
+ export type AiFilePurpose = 'context' | 'tools';
264
+ /**
265
+ * Metadata for an AI agent connected to an integration.
266
+ * @category AI
267
+ */
268
+ export interface AiConnectedIntegrationMetadata<AiConnectedIntegrationOptionsType = unknown> {
269
+ /** The ID of the connected integration. */
270
+ integrationId: IntegrationId;
271
+ /** The type of the connected integration (e.g., API, database). */
272
+ integrationType: IntegrationType;
273
+ /** An optional description of the integration for the parent agent context, used as AI function description. */
274
+ description?: string;
275
+ /** Optional instructions for the connected integration agent, overriding the default if provided. */
276
+ instructions?: string;
277
+ /**
278
+ * A list of AI function IDs that the AI agent can use from this integration.
279
+ *
280
+ * - When `undefined` (not provided), the AI agent has access to all AI functions for this integration type.
281
+ * - When an empty array `[]`, the AI agent has access to no AI functions.
282
+ * - When an array with function IDs, the AI agent only has access to those specific functions.
283
+ *
284
+ * Example function IDs: 'jiraService__searchJiraIssues', 'confluenceService__searchInConfluence'
285
+ */
286
+ functionsToUse?: AiFunctionId[];
287
+ /**
288
+ * Additional options for the connected integration.
289
+ * Squid Core or AI functions in connector packages may use these options to adjust behavior of the integration agent.
290
+ */
291
+ options?: AiConnectedIntegrationOptionsType;
292
+ /**
293
+ * Indicates that this integration should be treated as an MCP server.
294
+ * When true, API integrations with exposeAsMcpServer will be handled through the MCP protocol.
295
+ */
296
+ connectedAsMcp?: boolean;
297
+ }
298
+ /**
299
+ * Metadata for a connected AI agent callable by the current agent.
300
+ * @category AI
301
+ */
302
+ export interface AiConnectedAgentMetadata {
303
+ /** The ID of the connected AI agent. */
304
+ agentId: AiAgentId;
305
+ /** A description of the connected agent for the parent agent context, used as AI function description. */
306
+ description: string;
307
+ }
308
+ /**
309
+ * Metadata for a connected AI Knowledge Base callable by the current agent.
310
+ * @category AI
311
+ */
312
+ export interface AiConnectedKnowledgeBaseMetadata {
313
+ /** The ID of the connected AI KnowledgeBase */
314
+ knowledgeBaseId: AiKnowledgeBaseId;
315
+ /** A description of when to use this AiKnowledgeBase */
316
+ description: string;
317
+ /**
318
+ * Whether to include document metadata when providing this KB's results to the agent — both chunk
319
+ * search results and literal-scan matches. Defaults to false.
320
+ */
321
+ includeMetadata?: boolean;
322
+ /**
323
+ * When true, the chat agent gets a tool to enumerate/search this KB's metadata field values on
324
+ * demand. Off by default. (Chat surface only for now; MCP/CLI is not wired.)
325
+ */
326
+ enableMetadataInspection?: boolean;
327
+ }
328
+ /**
329
+ * Quotas for a single AI chat prompt (`ask()` method call).
330
+ * @category AI
331
+ */
332
+ export interface AiChatPromptQuotas {
333
+ /**
334
+ * Maximum depth of AI call recursion allowed.
335
+ * Recursion occurs when one AI agent calls another.
336
+ * Note that, for simplicity of implementation, this option guarantees only the maximum recursion depth,
337
+ * not the total number of nested AI calls.
338
+ * Default: 5.
339
+ */
340
+ maxAiCallStackSize: number;
341
+ /**
342
+ * Maximum wall-clock runtime, in seconds, of a single prompt for CLI-agent models
343
+ * (Claude Code, Codex). Optional override of the per-call self-kill deadline — mainly to
344
+ * tighten it for stricter runaway protection — clamped to [30, 1800]. Ignored for
345
+ * non-CLI-agent models. Default: the platform maximum (30 minutes).
346
+ */
347
+ maxRuntimeSeconds?: number;
348
+ }
349
+ /**
350
+ * Options for AI agent execution plan, allowing the agent to plan what functionality to use (connected agents,
351
+ * connected, integrations, or functions).
352
+ */
353
+ export interface AiAgentExecutionPlanOptions {
354
+ /** Whether to enable an execution plan for the agent. */
355
+ enabled: boolean;
356
+ /** The model to use for the execution plan - defaults to the model used by the agent. */
357
+ model?: AiChatModelSelection;
358
+ /** In case the model supports reasoning, this will control the level of effort - defaults to `high`. */
359
+ reasoningEffort?: AiReasoningEffort;
360
+ /**
361
+ * Whether the agent is allowed to ask follow-up or clarification questions.
362
+ * If true, the agent can respond with questions to gather more information before completing the task.
363
+ * Defaults to false.
364
+ */
365
+ allowClarificationQuestions?: boolean;
366
+ }
367
+ /**
368
+ * The memory mode for an AI agent:
369
+ * - 'none': No memory is used, the agent does not remember past interactions.
370
+ * - 'read-only': The agent can read from memory but cannot write to it.
371
+ * - 'read-write': The agent can both read from and write to memory.
372
+ * @category AI
373
+ */
374
+ export type AiAgentMemoryMode = 'none' | 'read-only' | 'read-write';
375
+ /**
376
+ * Options for AI agent memory management.
377
+ * @category AI
378
+ */
379
+ export interface AiAgentMemoryOptions {
380
+ /**
381
+ * The memory mode for an AI agent.
382
+ *
383
+ * Note: Squid persists chat history in its own store only for models whose provider does NOT manage memory
384
+ * itself. For provider-managed-memory models (e.g. Claude Code, which keeps its own CLI session), this mode
385
+ * still controls whether the conversation resumes, but Squid never reads or writes its own history DB.
386
+ */
387
+ memoryMode: AiAgentMemoryMode;
388
+ /**
389
+ * A unique ID to store the chat memory.
390
+ *
391
+ * The full chat memory key is constructed as a combination of 'appId', 'agentId', and 'memoryId'.
392
+ * If not provided the Squid client instance ID used as a memoryId.
393
+ *
394
+ * Important: the memory ID should be treated with the same security measures as Access Token because it unblocks
395
+ * direct access to the agent chat history. A good practice is to use a non-trivial and a unique value.
396
+ */
397
+ memoryId?: string;
398
+ /**
399
+ * Overrides the expiration for the whole chat history.
400
+ * If not provided, the expiration will not be changed.
401
+ *
402
+ * Default: the last provided expiration by user or 1 day if
403
+ * the user didn't provide any expiration.
404
+ */
405
+ expirationMinutes?: number;
406
+ }
407
+ /**
408
+ * Model specification for integration-based LLM providers like Ollama.
409
+ * @category AI
410
+ */
411
+ export interface IntegrationModelSpec {
412
+ /** The integration ID that provides the LLM */
413
+ integrationId: IntegrationId;
414
+ /** The model name within that integration */
415
+ model: string;
416
+ }
417
+ /**
418
+ * Type for specifying which LLM model to use.
419
+ * Can be either a vendor model name (string) or an integration-based model (object).
420
+ * @category AI
421
+ */
422
+ export type AiChatModelSelection = AiChatModelName | IntegrationModelSpec;
423
+ /**
424
+ * Lets a routing model pick which of several vendor models answers an `ask` request. The routing model
425
+ * sees the question, the agent's instructions and a card per candidate (price, tier, reasoning,
426
+ * context window) and names the one that should answer; that model then serves the request.
427
+ * @category AI
428
+ */
429
+ export interface AiModelRoutingOptions {
430
+ /** The vendor models the routing model chooses from; at least two, no duplicates. */
431
+ models: VendorAiChatModelName[];
432
+ /** The vendor model that makes the choice. */
433
+ routingModel: VendorAiChatModelName;
434
+ }
435
+ /**
436
+ * The model of an `ask` request: a concrete model, or a set of models a routing model chooses from.
437
+ * @category AI
438
+ */
439
+ export type AiAskModelSelection = AiChatModelSelection | AiModelRoutingOptions;
440
+ /**
441
+ * How an `ask` request whose `model` was an {@link AiModelRoutingOptions} was routed.
442
+ * @category AI
443
+ */
444
+ export interface AiModelRoutingResult {
445
+ /** The model the routing model chose and the request was sent to. A `backupModel` may still have served it. */
446
+ model: VendorAiChatModelName;
447
+ /** The model that made the choice. */
448
+ routingModel: VendorAiChatModelName;
449
+ /** Input tokens the routing call consumed. */
450
+ inputTokens: number;
451
+ /** Output tokens the routing call generated. */
452
+ outputTokens: number;
453
+ /** Best-effort USD cost of the routing call; undefined when the routing model is unpriced. */
454
+ costUsd?: number;
455
+ }
456
+ /**
457
+ * A backup model together with the sampling settings to run it with. Use this form instead of a
458
+ * bare {@link AiChatModelSelection} when the backup needs settings of its own; anything left unset
459
+ * takes the backup model's own default rather than the primary model's value.
460
+ * @category AI
461
+ */
462
+ export interface BackupModelOptions {
463
+ /** The model to fall back to. */
464
+ model: AiChatModelSelection;
465
+ /** The temperature to use when sampling from the backup model. */
466
+ temperature?: number;
467
+ /** The level of reasoning effort to apply; effective only for models with reasoning. */
468
+ reasoningEffort?: AiReasoningEffort;
469
+ /** The maximum number of input tokens Squid may send to the backup model. */
470
+ maxTokens?: number;
471
+ /** The maximum number of tokens the backup model should output. */
472
+ maxOutputTokens?: number;
473
+ /** Response length and detail level; supported by OpenAI models only. */
474
+ verbosity?: AiVerbosityLevel;
475
+ }
476
+ /**
477
+ * The base AI agent chat options, should not be used directly.
478
+ * @category AI
479
+ */
480
+ export interface BaseAiChatOptions {
481
+ /**
482
+ * The maximum number of input tokens that Squid can use when making the request to the AI model.
483
+ * Defaults to the max tokens the model can accept.
484
+ */
485
+ maxTokens?: number;
486
+ /**
487
+ * The maximum number of tokens the model should output.
488
+ * Passed directly to the AI model. Can be used to control the output verbosity.
489
+ */
490
+ maxOutputTokens?: number;
491
+ /** The context ID to use for the request. If not provided, the agent's default context will be used. */
492
+ memoryOptions?: AiAgentMemoryOptions;
493
+ /**
494
+ * Names a persistent working directory for CLI-backed agents (`claude-code`, `codex`). When set, the
495
+ * agent runs in a directory keyed by this id, synced across pod replicas via the shared workspace
496
+ * server, so files created in one ask persist and are visible to later asks reusing the same id —
497
+ * including across providers.
498
+ *
499
+ * Pass the same id consistently for a conversation; changing it points the agent at a different
500
+ * directory (and, for Claude Code, starts a fresh transcript). Must match `[A-Za-z0-9_-]` (1-200 chars).
501
+ * Ignored by non-CLI agents and when the workspace server is unconfigured (falls back to a pod-local,
502
+ * non-synced, ephemeral dir).
503
+ */
504
+ workspaceId?: string;
505
+ /** Whether to disable the whole context for the request. Default to false. */
506
+ disableContext?: boolean;
507
+ /**
508
+ * Whether to use the legacy knowledge base context mode, where KB results are fetched upfront
509
+ * and appended directly to the prompt. When false (default), the KB is exposed as a callable
510
+ * tool that the LLM can invoke on demand.
511
+ */
512
+ legacyKnowledgeBaseContext?: boolean;
513
+ /** Rewrite prompt for RAG - defaults to false */
514
+ enablePromptRewriteForRag?: boolean;
515
+ /**
516
+ * Whether to include references from the source context in the response. Default to false.
517
+ * @deprecated Use citation instead. Kept for compatibility; renders the legacy Quote/Source format
518
+ * on the legacy upfront-RAG path only.
519
+ */
520
+ includeReference?: boolean;
521
+ /**
522
+ * When true, the agent cites the sources behind its statements: source name, plus a download link
523
+ * when the agent's stored options set `allowSourceDownloads`. Takes precedence over the deprecated
524
+ * `includeReference`. Default to false.
525
+ */
526
+ citation?: boolean;
527
+ /**
528
+ * Allows citation links to the original source files (presigned, 1h expiry). Honored ONLY from the
529
+ * agent's stored options — the per-request value is ignored, so callers of public agents can never
530
+ * enable downloads. Default to false (citations render source names only).
531
+ */
532
+ allowSourceDownloads?: boolean;
533
+ /**
534
+ * The format of the response from the AI model. Defaults to 'text'. A `json_schema` format is
535
+ * refused for a model whose provider has no way to carry a schema — see
536
+ * {@link AiAgentResponseFormat}.
537
+ */
538
+ responseFormat?: AiAgentResponseFormat;
539
+ /** Whether to response in a "smooth typing" way, beneficial when the chat result is displayed in a UI. Default to true. */
540
+ smoothTyping?: boolean;
541
+ /**
542
+ * Global context passed to the agent and all AI functions of the agent. A request's value also reaches the AI
543
+ * functions of its connected agents, merged over each one's stored `agentContext`. Its keys are caller input and
544
+ * win over stored ones: only the root agent's `@secureAiAgent` rules can vet them, and none run for a public agent.
545
+ */
546
+ agentContext?: Record<string, unknown>;
547
+ /**
548
+ * Functions to expose to the AI.
549
+ * Either a function name or a name with an extra function context passed only to this function.
550
+ * The parameter values must be valid serializable JSON values.
551
+ * Overrides the stored value.
552
+ */
553
+ functions?: Array<AiFunctionId | AiFunctionIdWithContext>;
554
+ /** Instructions to include with the prompt. */
555
+ instructions?: string;
556
+ /** A set of filters that will limit the context the AI can access.
557
+ * @deprecated use `contextMetadataFilterForKnowledgeBase` instead.
558
+ */
559
+ contextMetadataFilter?: AiContextMetadataFilter;
560
+ /** A set of filters that will limit the context the AI can access. */
561
+ contextMetadataFilterForKnowledgeBase?: Record<AiKnowledgeBaseId, AiContextMetadataFilter>;
562
+ /** The options to use for the response in voice. */
563
+ voiceOptions?: AiAudioCreateSpeechOptions;
564
+ /** List of connected AI agents can be called by the current agent. Overrides the stored value. */
565
+ connectedAgents?: Array<AiConnectedAgentMetadata>;
566
+ /** List of connected AI agents can be called by the current agent. Overrides the stored value. */
567
+ connectedIntegrations?: Array<AiConnectedIntegrationMetadata>;
568
+ /** List of connected AiKnowlegeBases that can be called by the current agent */
569
+ connectedKnowledgeBases?: Array<AiConnectedKnowledgeBaseMetadata>;
570
+ /** Current budget for nested or recursive AI chat calls per single prompt. */
571
+ quotas?: AiChatPromptQuotas;
572
+ /**
573
+ * Include metadata in the context.
574
+ * @deprecated Use `includeMetadata` on individual `AiConnectedKnowledgeBaseMetadata` entries in `connectedKnowledgeBases` instead.
575
+ */
576
+ includeMetadata?: boolean;
577
+ /** The temperature to use when sampling from the model. Default to 0.5. */
578
+ temperature?: number;
579
+ /** Preset instruction options that can be toggled on */
580
+ guardrails?: GuardrailsOptions;
581
+ /**
582
+ * Refuses prompts that carry PII before they reach the model. Read from the stored agent only —
583
+ * a value passed with a chat request is ignored, so a caller cannot switch off its own screening.
584
+ */
585
+ pii?: AiPiiOptions;
586
+ /** The LLM model to use. Can be a vendor model name (string) or an integration-based model (object). */
587
+ model?: AiChatModelSelection;
588
+ /**
589
+ * The model to use when `model` cannot serve the conversation's very first request because its
590
+ * provider is unavailable — a rate limit, a capacity outage, or any other failure on the
591
+ * provider's side. A request that fails for its own reasons (an invalid prompt, a rejected
592
+ * schema, an exhausted Squid quota) is never retried on the backup, nor is any request after the
593
+ * first one, nor one that already produced output or ran a tool.
594
+ *
595
+ * A conversation that fell back then STAYS on that backup for the rest of its life, so an outage
596
+ * costs the primary's retry budget once rather than once per turn, and the model does not change
597
+ * mid-dialogue. The pin outlives the option that created it: changing or removing `backupModel`,
598
+ * changing the agent's own `model`, and the primary recovering all leave a pinned conversation
599
+ * where it is, and a pinned model that no longer resolves fails the request rather than moving the
600
+ * conversation. This is deliberate — a conversation accumulates provider-native file ids and a
601
+ * transcript in that provider's dialect, none of which survive a move. Pinning needs Squid-managed
602
+ * memory to have somewhere to record it; without memory every request is a first request anyway.
603
+ *
604
+ * A request carrying `fileIds` follows from the same reasoning, and the two cases differ. A first
605
+ * request does not fall back where that would cost it the attachments — to a model that cannot read
606
+ * ids the primary could, or that reads them without owning them — since answering from a model that
607
+ * never saw them is worse than reporting the outage. Where neither model reads file ids they are
608
+ * inert either way and the fallback proceeds. A
609
+ * conversation already pinned is held to less: it keeps running on its model, and if that model
610
+ * reads no file ids the ids are ignored there as they are anywhere else, because the alternative is
611
+ * a conversation that can never run again.
612
+ *
613
+ * Pass a model name for the model's own defaults, or a {@link BackupModelOptions} object to give
614
+ * the backup its own sampling settings. Everything else — instructions, functions, knowledge
615
+ * bases, connected agents, response format, memory — always comes from the primary configuration.
616
+ *
617
+ * On a turn the backup serves, the sampling settings are ITS settings alone: `temperature`,
618
+ * `reasoningEffort`, `maxTokens`, `maxOutputTokens` and `verbosity` are read from `backupModel`
619
+ * and nowhere else, so a value left unset there takes the backup model's own default even when
620
+ * the agent's profile or the request itself carries one. This holds for every turn of a pinned
621
+ * conversation, not only the one that fell back — tuning meant for one model is not evidence of
622
+ * what another should use.
623
+ *
624
+ * Applies to models served through Squid's own provider SDKs — the vendor models and
625
+ * `openai_compatible`, Bedrock and Vertex integrations. A model you serve yourself from backend
626
+ * code reports its failures as plain errors that carry no provider status, so a turn on one is
627
+ * never diagnosed as a provider outage and never falls back.
628
+ *
629
+ * The backup resolves its API key exactly as it would as the primary model, and is skipped
630
+ * silently when it cannot be resolved, when it reaches the same model as the primary, or when
631
+ * either model is a CLI-backed agent. Leave unset to keep a provider outage surfacing as an error.
632
+ */
633
+ backupModel?: AiChatModelSelection | BackupModelOptions;
634
+ /** Which provider's reranker to use for reranking the context. Defaults to 'cohere'. */
635
+ rerankProvider?: AiRerankProvider;
636
+ /**
637
+ * Options for AI agent execution plan, allowing the agent to perform an execution plan before invoking
638
+ * connected agents, connected integrations, or functions.
639
+ */
640
+ executionPlanOptions?: AiAgentExecutionPlanOptions;
641
+ /** An array of file URLs to include in the chat context. */
642
+ fileUrls?: Array<AiFileUrl>;
643
+ /**
644
+ * Arbitrary client-defined annotations attached to this AI call for usage tracking.
645
+ * Reported as `annotation.<key>` tags on Squid AI usage metrics, so token usage can later be
646
+ * filtered and grouped by these values (e.g. `{ feature: 'support-bot', requestSource: 'mobile' }`).
647
+ * Inherited by nested calls to connected agents made while serving this call.
648
+ * Limits: at most 10 entries, keys up to 64 characters, values up to 256 characters;
649
+ * entries beyond the limits are dropped or truncated.
650
+ */
651
+ metricAnnotations?: Record<string, string>;
652
+ /**
653
+ * The level of reasoning effort to apply; defaults to model-specific value.
654
+ * Effective only for models with reasoning.
655
+ */
656
+ reasoningEffort?: AiReasoningEffort;
657
+ /**
658
+ * Controls response length and detail level.
659
+ * Use `low` for brief responses, `medium` for balanced detail, or `high` for comprehensive explanations.
660
+ * Default: 'medium'.
661
+ *
662
+ * Note: this parameter is only supported by OpenAI and is ignored for others. It applies to every
663
+ * response format, including `json_object` and `json_schema`.
664
+ * For other providers ask about verbosity in prompt and using `maxOutputTokens`.
665
+ */
666
+ verbosity?: AiVerbosityLevel;
667
+ /**
668
+ * Enable LLMs built-in code interpreter for executing Python code.
669
+ * - 'none': Code interpreter is disabled (default).
670
+ * - 'llm': Use LLM's native code interpreter to run Python code.
671
+ *
672
+ * Note: Only supported by OpenAI, Anthropic and Gemini models. Ignored for other providers.
673
+ */
674
+ useCodeInterpreter?: 'none' | 'llm';
675
+ /**
676
+ * File IDs to include in the chat context.
677
+ * These are IDs returned from the AI provider's Files API after uploading files.
678
+ * Files are attached to the conversation and can be read/analyzed by the AI.
679
+ */
680
+ fileIds?: string[];
681
+ /**
682
+ * Timeout in milliseconds for one model-call attempt of the chat (a single provider call,
683
+ * covering that call's tool loop). An attempt that produced nothing by this deadline is treated
684
+ * as a stalled provider connection and retried per `retriesOnStall`, each retry getting this
685
+ * full budget again — so the provider phase of a chat may take up to
686
+ * `(1 + retriesOnStall) * timeoutMs` in the worst case. Defaults to 240,000 (4 minutes).
687
+ */
688
+ timeoutMs?: number;
689
+ /**
690
+ * How many times a stalled model-call attempt is reissued. A retry happens only when the
691
+ * attempt hit `timeoutMs` having produced nothing AND no AI function has executed in the turn,
692
+ * so a retry can never repeat a side effect; aborting the stalled attempt destroys its
693
+ * connection, so the retry cannot reuse it. `0` disables stall retries. Defaults to 1.
694
+ */
695
+ retriesOnStall?: number;
696
+ /** Maximum number of tool-call iterations the model may perform in a single chat turn. Defaults to 50. */
697
+ maxToolIterations?: number;
698
+ }
699
+ /**
700
+ * Chat options specific to Gemini models, extending base options.
701
+ * @category AI
702
+ */
703
+ export interface GeminiChatOptions extends BaseAiChatOptions {
704
+ /** The Gemini model to use for the chat. */
705
+ model?: GeminiChatModelName;
706
+ /** Enables grounding with web search for more informed responses; defaults to false. */
707
+ groundingWithWebSearch?: boolean;
708
+ }
709
+ /**
710
+ * Chat options specific to Grok models, extending base options.
711
+ * @category AI
712
+ */
713
+ export interface GrokChatOptions extends BaseAiChatOptions {
714
+ /** The Grok model to use for the chat. */
715
+ model?: GrokChatModelName;
716
+ }
717
+ /**
718
+ * Chat options specific to OpenAI models, extending base options.
719
+ * @category AI
720
+ */
721
+ export interface OpenAiChatOptions extends BaseAiChatOptions {
722
+ /** The OpenAI model to use for the chat. */
723
+ model?: OpenAiChatModelName;
724
+ }
725
+ /**
726
+ * Canonical reasoning-effort levels, ordered from least to most effort. These are the values that
727
+ * have a defined position on the effort axis and therefore participate in clamping when a model does
728
+ * not support the exact requested level.
729
+ * @category AI
730
+ */
731
+ export type { CanonicalReasoningEffort } from './ai-common.public-types';
732
+ /**
733
+ * AI reasoning effort. Pass one of the canonical levels for portable, autocomplete-friendly usage, or
734
+ * a raw provider-native string when a model exposes a level outside the canonical set.
735
+ *
736
+ * Resolution against the selected model (see {@link ReasoningCapability}):
737
+ * - exact match with the model's capability -> used as-is (1:1);
738
+ * - canonical level the model lacks -> clamped to the nearest supported level (ties resolve downward);
739
+ * - unknown string the model cannot place on the axis -> dropped, so the model's own default applies,
740
+ * with a warning;
741
+ * - model without a reasoning knob -> ignored, with a warning.
742
+ *
743
+ * A model served through an `openai_compatible` integration is the exception: the value is sent to
744
+ * that endpoint exactly as written, with none of the resolution above, since the endpoint's model is
745
+ * the app's own choice and this registry cannot describe it. That is also how to reach a level the
746
+ * canonical set has no name for.
747
+ * @category AI
748
+ */
749
+ export type AiReasoningEffort = CanonicalReasoningEffort | (string & {});
750
+ /**
751
+ * Declares how a model exposes reasoning effort. Used as the single source of truth for resolving a
752
+ * requested {@link AiReasoningEffort} onto what the model natively accepts. When a request cannot be
753
+ * matched or clamped, no reasoning parameter is emitted and the model applies its own native default.
754
+ *
755
+ * - `none`: the model has no reasoning knob (e.g. it always reasons).
756
+ * - `levels`: the model accepts a fixed set of named levels (emitted as a string).
757
+ * - `budget`: the model accepts a token budget; each canonical level maps to a concrete integer.
758
+ * @category AI
759
+ */
760
+ export type ReasoningCapability = {
761
+ kind: 'none';
762
+ } | {
763
+ kind: 'levels';
764
+ supported: AiReasoningEffort[];
765
+ } | {
766
+ kind: 'budget';
767
+ perLevel: Partial<Record<CanonicalReasoningEffort, number>>;
768
+ };
769
+ /**
770
+ * Controls response length and detail level.
771
+ * Use `low` for brief responses,`medium` for balanced detail, or `high` for comprehensive explanations.
772
+ * Default: 'medium'.
773
+ */
774
+ export type AiVerbosityLevel = 'low' | 'medium' | 'high';
775
+ /**
776
+ * Chat options specific to Anthropic models, extending base options.
777
+ *
778
+ * **Structured Outputs:**
779
+ * Anthropic models support structured outputs
780
+ * through the `responseFormat` field. Pass an object with `type: 'json_schema'` and a JSON schema
781
+ * to guarantee the response conforms exactly to your schema.
782
+ *
783
+ * **Example:**
784
+ * ```typescript
785
+ * {
786
+ * model: 'claude-sonnet-5',
787
+ * responseFormat: {
788
+ * type: 'json_schema',
789
+ * schema: {
790
+ * type: 'object',
791
+ * properties: {
792
+ * name: { type: 'string' },
793
+ * age: { type: 'number' }
794
+ * },
795
+ * required: ['name', 'age'],
796
+ * additionalProperties: false
797
+ * }
798
+ * }
799
+ * }
800
+ * ```
801
+ *
802
+ * @see https://docs.anthropic.com/en/docs/build-with-claude/structured-outputs
803
+ * @category AI
804
+ */
805
+ export interface AnthropicChatOptions extends BaseAiChatOptions {
806
+ /** The Anthropic model to use for the chat. */
807
+ model?: AnthropicChatModelName;
808
+ }
809
+ /**
810
+ * The generic options type. When no generic is provided,
811
+ * the type is inferred from the provided overrideModel (or falls back to BaseAiAgentChatOptions).
812
+ * @category AI
813
+ */
814
+ export type AiChatOptions<T extends AiChatModelSelection | undefined = undefined> = T extends undefined ? BaseAiChatOptions | GeminiChatOptions | OpenAiChatOptions | AnthropicChatOptions : T extends GeminiChatModelName ? GeminiChatOptions : T extends OpenAiChatModelName ? OpenAiChatOptions : T extends AnthropicChatModelName ? AnthropicChatOptions : T extends GrokChatModelName ? GrokChatOptions : BaseAiChatOptions;
815
+ /**
816
+ * @category AI
817
+ */
818
+ export type AllAiAgentChatOptions = {
819
+ [K in keyof BaseAiChatOptions | keyof GeminiChatOptions | keyof GrokChatOptions | keyof OpenAiChatOptions | keyof AnthropicChatOptions]?: (K extends keyof BaseAiChatOptions ? BaseAiChatOptions[K] : never) | (K extends keyof GeminiChatOptions ? GeminiChatOptions[K] : never) | (K extends keyof GrokChatOptions ? GrokChatOptions[K] : never) | (K extends keyof OpenAiChatOptions ? OpenAiChatOptions[K] : never) | (K extends keyof AnthropicChatOptions ? AnthropicChatOptions[K] : never);
820
+ };
821
+ /**
822
+ * Credentials a caller sends with one chat request. The client sends them in the `x-squid-integration-access-tokens`
823
+ * request header rather than with the options, so they reach only the tools that run with them and are never stored
824
+ * with the agent.
825
+ * @category AI
826
+ */
827
+ export interface AiChatRequestCredentials {
828
+ /**
829
+ * Access tokens keyed by integration ID. The integration's tools run with its token for this request when the
830
+ * integration type supports it; other types ignore it.
831
+ */
832
+ integrationAccessTokens?: Record<IntegrationId, string>;
833
+ }
834
+ /**
835
+ * Configuration for exposing an AI agent as an MCP server at `/mcp/<agentId>`.
836
+ * @category AI
837
+ */
838
+ export interface AiAgentMcpServerConfig {
839
+ /** Whether the agent is exposed as an MCP server. */
840
+ enabled: boolean;
841
+ /**
842
+ * Description of the MCP server, served as the `instructions` field of the MCP initialize
843
+ * result. Defaults to the agent description when not provided.
844
+ */
845
+ description?: string;
846
+ /**
847
+ * Description of the MCP `ask` tool, exposed in the tools manifest.
848
+ * Defaults to a generic ask-the-agent description when not provided.
849
+ */
850
+ toolDescription?: string;
851
+ /**
852
+ * ID of an auth integration used to OAuth-protect the MCP server. When set, MCP requests must
853
+ * include a valid bearer token from this integration. Without this and `requireApiKey`, the
854
+ * MCP endpoint is public.
855
+ */
856
+ oauthIntegrationId?: IntegrationId;
857
+ /**
858
+ * When true, MCP requests must present the agent's API key as a bearer token
859
+ * (`Authorization: Bearer <agent API key>` or the `x-squid-agent-api-key` header). Can be
860
+ * combined with `oauthIntegrationId`, in which case either credential is accepted.
861
+ */
862
+ requireApiKey?: boolean;
863
+ }
864
+ /**
865
+ * Request to AI-generate the MCP server and tool descriptions for an agent based on its
866
+ * instructions and connected resources.
867
+ * @category AI
868
+ */
869
+ export interface GenerateAgentMcpDescriptionsRequest {
870
+ /** The ID of the agent to generate MCP descriptions for. */
871
+ agentId: AiAgentId;
872
+ }
873
+ /**
874
+ * AI-generated MCP descriptions for an agent. Returned without persisting — the caller saves them
875
+ * onto the agent's MCP server configuration.
876
+ * @category AI
877
+ */
878
+ export interface GenerateAgentMcpDescriptionsResponse {
879
+ /** Generated description of the MCP server. */
880
+ description: string;
881
+ /** Generated description of the MCP `ask` tool. */
882
+ toolDescription: string;
883
+ }
884
+ /**
885
+ * A definition of an AI agent with its properties and default chat options.
886
+ * @category AI
887
+ */
888
+ export interface AiAgent<T extends AiChatModelSelection | undefined = undefined> {
889
+ /** The unique identifier of the AI agent. */
890
+ id: AiAgentId;
891
+ /** The date and time the agent was created. */
892
+ createdAt: Date;
893
+ /** The date and time the agent was last updated. */
894
+ updatedAt: Date;
895
+ /** An optional description of the agent's purpose or capabilities. */
896
+ description?: string;
897
+ /** Indicates whether the agent is publicly accessible; defaults to false. */
898
+ isPublic?: boolean;
899
+ /** Enables audit logging for the agent's activities if true; defaults to false. */
900
+ auditLog?: boolean;
901
+ /** Records the full agent context in the audit log — assembled system instructions on the chat-start entry and retrieved knowledge-base content in KB tool-call updates; requires auditLog; defaults to false. */
902
+ auditLogFullContext?: boolean;
903
+ /** The default chat options for the agent, overridable by the user during use. */
904
+ options: AiChatOptions<T>;
905
+ /** Optional api key used specifically for operations on this agent */
906
+ apiKey?: string;
907
+ /** Optional configuration for exposing the agent as an MCP server. */
908
+ mcpServer?: AiAgentMcpServerConfig;
909
+ }
910
+ /**
911
+ * @category AI
912
+ */
913
+ export type UpsertAgentRequest = Omit<AiAgent, 'createdAt' | 'updatedAt' | 'options'> & {
914
+ options?: AiChatOptions;
915
+ };
916
+ /**
917
+ * Status update title broadcast when the agent finishes producing a response,
918
+ * either successfully or with an error. Emitted exactly once per `ask` job and
919
+ * is the last status event for that job.
920
+ * @category AI
921
+ */
922
+ export declare const AGENT_STATUS_TITLE_AGENT_RESPONSE = "Agent Response";
923
+ /**
924
+ * Status update title broadcast when the agent invokes a knowledge-base
925
+ * callable. A matching invocation produces a single event with this title.
926
+ * @category AI
927
+ */
928
+ export declare const AGENT_STATUS_TITLE_ACCESSING_KB = "Accessing Knowledge Base";
929
+ /**
930
+ * Status update title broadcast when the agent invokes an AI function callable
931
+ * (a backend `@aiFunction`). Lets a caller detect that a function was actually
932
+ * called, independent of how the model renders the result in its final answer.
933
+ * @category AI
934
+ */
935
+ export declare const AGENT_STATUS_TITLE_CALLING_AI_FUNCTION = "Calling AI Function";
936
+ /**
937
+ * Status update title broadcast when an AI function callable returns, carrying the function's raw
938
+ * result in the body. Nested under the matching {@link AGENT_STATUS_TITLE_CALLING_AI_FUNCTION} event.
939
+ * @category AI
940
+ */
941
+ export declare const AGENT_STATUS_TITLE_AI_FUNCTION_RESULT = "AI Function Result";
942
+ /**
943
+ * Status update title broadcast when the agent invokes a knowledge-base metadata-inspection callable
944
+ * (the opt-in `enableMetadataInspection` tool). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB}
945
+ * so a caller can tell a metadata-value inspection apart from an ordinary KB search.
946
+ * @category AI
947
+ */
948
+ export declare const AGENT_STATUS_TITLE_INSPECTING_KB_METADATA = "Inspecting Knowledge Base Metadata";
949
+ /**
950
+ * Status update title broadcast when the agent invokes the knowledge-graph query callable (offered
951
+ * automatically for graph-enabled KBs). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB} so a
952
+ * caller can tell graph navigation apart from an ordinary KB search.
953
+ * @category AI
954
+ */
955
+ export declare const AGENT_STATUS_TITLE_QUERYING_KB_GRAPH = "Querying Knowledge Base Graph";
956
+ /**
957
+ * Status update title emitted when the agent runs the `grepKnowledgeBase` tool (a literal/regex scan over
958
+ * the knowledge base's raw extracted text). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB} so a
959
+ * caller can tell an exact-match scan apart from ranked retrieval.
960
+ * @category AI
961
+ */
962
+ export declare const AGENT_STATUS_TITLE_GREPPING_KB = "Searching Knowledge Base Text";
963
+ /**
964
+ * Status update title broadcast when the agent queries a spreadsheet file callable.
965
+ * @category AI
966
+ */
967
+ export declare const AGENT_STATUS_TITLE_QUERYING_SPREADSHEET = "Querying Spreadsheet";
968
+ /**
969
+ * A status message from an AI agent operation.
970
+ * @category AI
971
+ */
972
+ export interface AiStatusMessage {
973
+ /** ID of the status update message. */
974
+ messageId: string;
975
+ /** The ID of the agent generating the status message. */
976
+ agentId?: AiAgentId;
977
+ /** An optional chat ID associated with the status message. */
978
+ chatId?: string;
979
+ /** The title or summary of the status message. */
980
+ title: string;
981
+ /** Markdown body content for the status update. */
982
+ body: string;
983
+ /** ID of the parent status update for nested display. */
984
+ parentStatusUpdateId?: string;
985
+ /** The Job ID associated with the status message. */
986
+ jobId: JobId;
987
+ /** Optional tags providing additional metadata about the status. */
988
+ tags?: Record<string, any>;
989
+ }
990
+ /**
991
+ * `errorType` on a failed chat/ask job when the AI provider itself failed (a stall, timeout, or
992
+ * unrecognized 5xx) rather than Squid or the caller's request.
993
+ * @category AI
994
+ */
995
+ export declare const AI_PROVIDER_ERROR_TYPE = "AI_PROVIDER_ERROR";
996
+ /** List of all chat history (memory) sources. */
997
+ export declare const AI_CHAT_MESSAGE_SOURCE: readonly ["user", "ai"];
998
+ /** Source of the chat history entry: either an AI response or a user. */
999
+ export type AiChatMessageSource = (typeof AI_CHAT_MESSAGE_SOURCE)[number];
1000
+ /** A history entry for a chat. */
1001
+ export interface AiChatMessage {
1002
+ /** ID of the entry. Unique per agent. */
1003
+ id: string;
1004
+ /** Agent's application. */
1005
+ appId: AppId;
1006
+ /** The ID of the agent that owns the history. */
1007
+ agentId: AiAgentId;
1008
+ /** A memory (history) ID associated with the chat conversation. */
1009
+ memoryId: string;
1010
+ /** The source of the message: a user or an AI. */
1011
+ source: AiChatMessageSource;
1012
+ /** The text of the entry: a user's prompt or an AI-generated response. */
1013
+ message: string;
1014
+ /** Time the entry is created. Unix time millis. */
1015
+ timestamp: number;
1016
+ }
1017
+ /**
1018
+ * A single chunk of data returned from an AI search operation.
1019
+ * @category AI
1020
+ */
1021
+ export interface AiSearchResultChunk {
1022
+ /** The data content of the search result chunk. */
1023
+ data: string;
1024
+ /** Optional metadata associated with the chunk. */
1025
+ metadata?: AiContextMetadata;
1026
+ /** The relevance score of the chunk, indicating match quality. */
1027
+ score: number;
1028
+ }
1029
+ /**
1030
+ * Represents an AI agent's context entry with metadata and content.
1031
+ * @category AI
1032
+ */
1033
+ export interface AiAgentContext {
1034
+ /** The unique identifier of the context entry. */
1035
+ id: AiContextId;
1036
+ /** The date and time the context was created. */
1037
+ createdAt: Date;
1038
+ /** The date and time the context was last updated. */
1039
+ updatedAt: Date;
1040
+ /** The ID of the agent owning this context. */
1041
+ agentId: AiAgentId;
1042
+ /** The type of context (e.g., 'text' or 'file'). */
1043
+ type: AiKnowledgeBaseContextType;
1044
+ /** A title describing the context content. */
1045
+ title: string;
1046
+ /** The text content of the context. */
1047
+ text: string;
1048
+ /** Indicates whether the context is a preview; defaults to false. */
1049
+ preview: boolean;
1050
+ /** The size of the context content in bytes. */
1051
+ sizeBytes: number;
1052
+ /** Metadata associated with the context. */
1053
+ metadata: AiContextMetadata;
1054
+ }
1055
+ /**
1056
+ * @category AI
1057
+ */
1058
+ export type AgentContextRequest = TextContextRequest | FileContextRequest;
1059
+ /**
1060
+ * Base fields shared by all agent context requests.
1061
+ * @category AI
1062
+ */
1063
+ export interface BaseContextRequest {
1064
+ /** The unique identifier of the context item. */
1065
+ contextId: string;
1066
+ /** The type of the context content. */
1067
+ type: AiKnowledgeBaseContextType;
1068
+ /** Optional metadata associated with the context item. */
1069
+ metadata?: AiContextMetadata;
1070
+ }
1071
+ /**
1072
+ * Status of an individual context item after successfully upserting it.
1073
+ * @category AI
1074
+ */
1075
+ export interface BaseUpsertContextStatus {
1076
+ /** Whether the context upsert was successful, otherwise, what occurred. */
1077
+ status: 'success' | 'error';
1078
+ /** The unique identifier of the context item. */
1079
+ contextId: string;
1080
+ /** The name of the context item, typically the title or filename. */
1081
+ name: string;
1082
+ }
1083
+ /**
1084
+ * An image whose description failed during ingestion: the context is stored without that image's chunk.
1085
+ * @category AI
1086
+ */
1087
+ export interface ContextImageFailure {
1088
+ /** Zero-based index of the page carrying the image. */
1089
+ pageIndex: number;
1090
+ /** Extraction-assigned id of the image within the document. */
1091
+ imageId: string;
1092
+ /** Why describing the image failed. */
1093
+ errorMessage: string;
1094
+ }
1095
+ /**
1096
+ * Status of an individual context item after successfully upserting it.
1097
+ * @category AI
1098
+ */
1099
+ export interface UpsertContextStatusSuccess extends BaseUpsertContextStatus {
1100
+ /** Whether the context upsert was successful or got an error. */
1101
+ status: 'success';
1102
+ /**
1103
+ * Set when the context was stored and is fully searchable (vector/keyword), but was NOT graph-indexed
1104
+ * because the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent;
1105
+ * surfaced so bulk operations can report which contexts fell outside the graph.
1106
+ */
1107
+ graphIndexingSkipped?: boolean;
1108
+ /** First failed images (capped); absent when every image succeeded. `imageFailureCount` is the total. */
1109
+ imageFailures?: Array<ContextImageFailure>;
1110
+ /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
1111
+ imageFailureCount?: number;
1112
+ }
1113
+ /**
1114
+ * Names an upsert failure; `DUPLICATE_CONTENT` identifies existing content when contextId is omitted.
1115
+ * `EMBEDDING_FAILED`, `EXTRACTION_TIMED_OUT`, `PROVIDER_ACCESS_DENIED`, and `SOURCE_UNREACHABLE` may
1116
+ * succeed on retry. Document faults carry `retryable: false` because the same bytes fail again.
1117
+ * @category AI
1118
+ */
1119
+ export type UpsertContextErrorCode = 'CONTENT_TOO_LARGE' | 'DUPLICATE_CONTENT' | 'EMBEDDING_FAILED' | 'ENCRYPTED_DOCUMENT' | 'EXTRACTION_TIMED_OUT' | 'IMAGE_OVER_PROVIDER_LIMIT' | 'NO_EMBEDDABLE_CONTENT' | 'PROVIDER_ACCESS_DENIED' | 'SOURCE_OVER_PROVIDER_LIMIT' | 'SOURCE_UNREACHABLE' | 'UNREADABLE_DOCUMENT' | 'UNREADABLE_WORKBOOK' | 'UNSUPPORTED_FILE_TYPE';
1120
+ /**
1121
+ * The existing context a `DUPLICATE_CONTENT` rejection points at — where the byte-identical original
1122
+ * already lives.
1123
+ * @category AI
1124
+ */
1125
+ export interface UpsertContextDuplicateOf {
1126
+ /** The id of the already-stored context whose content is byte-identical to the rejected request. */
1127
+ contextId: string;
1128
+ /** The existing context's source reference (file name / URL), when it has one. */
1129
+ reference?: string;
1130
+ /** The existing context's `folderPath` metadata, when it was ingested with a folder path. */
1131
+ folderPath?: string;
1132
+ }
1133
+ /**
1134
+ * Status of an individual context item after it failed to upsert.
1135
+ *
1136
+ * Contains the error message for why the upsert failed.
1137
+ * @category AI
1138
+ */
1139
+ export interface UpsertContextStatusError extends BaseUpsertContextStatus {
1140
+ /** Whether the context upsert was successful or got an error. */
1141
+ status: 'error';
1142
+ /** Reason the upsert failed. */
1143
+ errorMessage: string;
1144
+ /** Machine-readable code for the failure, when one applies. */
1145
+ errorCode?: UpsertContextErrorCode;
1146
+ /**
1147
+ * Present only when the same bytes fail the same way again, so a caller must not retry the request
1148
+ * as-is. Absence means the failure may be transient.
1149
+ */
1150
+ retryable?: false;
1151
+ /**
1152
+ * The existing context this request duplicated, when `errorCode` is `DUPLICATE_CONTENT`. Lets a caller
1153
+ * point the user at where the original already lives (e.g. its folder) instead of only reporting the
1154
+ * rejection. `reference`/`folderPath` are present when the existing context carries them.
1155
+ */
1156
+ duplicateOf?: UpsertContextDuplicateOf;
1157
+ /** First failed images (capped) when every image failed and the document had no text; otherwise absent. */
1158
+ imageFailures?: Array<ContextImageFailure>;
1159
+ /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
1160
+ imageFailureCount?: number;
1161
+ }
1162
+ /**
1163
+ * Status of an individual context item after attempting to upsert it.
1164
+ * @category AI
1165
+ */
1166
+ export type UpsertContextStatus = UpsertContextStatusSuccess | UpsertContextStatusError;
1167
+ /**
1168
+ * Response structure for upserting context.
1169
+ * @category AI
1170
+ */
1171
+ export interface UpsertAgentContextResponse {
1172
+ /** Upsert failure that occurred for the items sent in the request. */
1173
+ failure?: UpsertContextStatusError;
1174
+ }
1175
+ /**
1176
+ * Response structure for upserting contexts.
1177
+ * @category AI
1178
+ */
1179
+ export interface UpsertAgentContextsResponse {
1180
+ /** List of the upsert failures that occurred for the items sent in the request. */
1181
+ failures: Array<UpsertContextStatusError>;
1182
+ }
1183
+ /**
1184
+ * Base options for upserting text content into the AI agent's context.
1185
+ * @category AI
1186
+ */
1187
+ export interface AiContextTextOptions extends BaseAiContextOptions {
1188
+ }
1189
+ /**
1190
+ * Base options for upserting file content into the AI agent's context.
1191
+ * @category AI
1192
+ */
1193
+ export interface AiContextFileOptions extends BaseAiContextOptions {
1194
+ }
1195
+ /**
1196
+ * Request structure for adding text-based context to an AI agent.
1197
+ * @category AI
1198
+ */
1199
+ export interface TextContextRequest extends BaseContextRequest {
1200
+ /** Specifies the context type as 'text'. */
1201
+ type: 'text';
1202
+ /** A title for the text context. */
1203
+ title: string;
1204
+ /** The text content to add to the context. */
1205
+ text: string;
1206
+ /** General options for how to process the text. */
1207
+ options?: AiContextTextOptions;
1208
+ }
1209
+ /**
1210
+ * Request structure for adding file-based context to an AI agent.
1211
+ * @category AI
1212
+ */
1213
+ export interface FileContextRequest extends BaseContextRequest {
1214
+ /** Specifies the context type as 'file'. */
1215
+ type: 'file';
1216
+ /**
1217
+ * Whether to extract images from the file, describe them with a vision model, and index those
1218
+ * descriptions alongside the text. Defaults to true — a document's charts, diagrams and scanned pages
1219
+ * carry content the text layer does not. Note that the text context request has no such option:
1220
+ * inline images in a text payload are extracted only for a knowledge-base text context, and default
1221
+ * to OFF there.
1222
+ */
1223
+ extractImages?: boolean;
1224
+ /** The minimum size for extracted images, if applicable. */
1225
+ imageMinSizePixels?: number;
1226
+ /** The AI model to use for extraction, if specified. */
1227
+ extractionModel?: AiChatModelSelection;
1228
+ /** General options for how to process the file. */
1229
+ options?: AiContextFileOptions;
1230
+ /** The preferred method for extracting data from the document. */
1231
+ preferredExtractionMethod?: DocumentExtractionMethod;
1232
+ /**
1233
+ * Whether Squid keeps or discards the original file.
1234
+ *
1235
+ * Keeping the original file allows reprocessing and the ability for the user to download it later.
1236
+ *
1237
+ * Defaults to false.
1238
+ */
1239
+ discardOriginalFile?: boolean;
1240
+ }
1241
+ /**
1242
+ * Base options for how to deal with the content being upserted.
1243
+ * @category AI
1244
+ */
1245
+ export type BaseAiContextOptions = {
1246
+ /** The type of RAG to use for the content. */
1247
+ ragType?: AiRagType;
1248
+ /** Amount of chunk overlap, in characters. */
1249
+ chunkOverlap?: number;
1250
+ };
1251
+ /**
1252
+ * @category AI
1253
+ */
1254
+ export type GuardrailKeysType = 'disableProfanity' | 'offTopicAnswers' | 'professionalTone' | 'disablePii';
1255
+ /**
1256
+ * Options for applying guardrails to AI responses to enforce specific constraints.
1257
+ * @category AI
1258
+ */
1259
+ export type GuardrailsOptions = {
1260
+ /** Disables profanity in the AI response if true; defaults to false. */
1261
+ disableProfanity?: boolean;
1262
+ /** Prevents off-topic answers if true; defaults to false. */
1263
+ offTopicAnswers?: boolean;
1264
+ /** Enforces a professional tone in the response if true; defaults to false. */
1265
+ professionalTone?: boolean;
1266
+ /** Disables inclusion of personally identifiable information if true; defaults to false. */
1267
+ disablePii?: boolean;
1268
+ /** A custom guardrail instruction, if specified. */
1269
+ custom?: string;
1270
+ };
1271
+ /**
1272
+ * PII kinds a prompt can be screened for. Each one is judged in context by the screening model, so
1273
+ * a value is classified by what the prompt says it is rather than by which format it happens to fit.
1274
+ * @category AI
1275
+ */
1276
+ export type AiPiiEntityType = 'email' | 'phoneNumber' | 'creditCard' | 'ssn' | 'iban' | 'passport';
1277
+ /** Entity kinds screened when {@link AiPiiOptions.entities} is omitted. */
1278
+ export declare const DEFAULT_PII_ENTITY_TYPES: ReadonlyArray<AiPiiEntityType>;
1279
+ /** Model that screens prompts unless overridden. Small and fast: it runs on every prompt. */
1280
+ export declare const DEFAULT_PII_CLASSIFIER_MODEL = "gpt-6-luna";
1281
+ /**
1282
+ * Rejects a prompt before it reaches the agent's model when it carries PII, so the prompt is never
1283
+ * sent to the model provider, never answered, and never written to chat memory.
1284
+ *
1285
+ * Screening is one {@link classifierModel} call per prompt, covering {@link entities} and
1286
+ * {@link customRules} together. Because a model does the reading rather than a pattern, a value is
1287
+ * judged by what the prompt says it is, and app-specific identifiers can be described in plain
1288
+ * language instead of expressed as a format.
1289
+ *
1290
+ * This is the inverse of {@link GuardrailsOptions.disablePii}, which asks the agent's own model not
1291
+ * to *emit* PII in its answer.
1292
+ * @category AI
1293
+ */
1294
+ export type AiPiiOptions = {
1295
+ /** `reject` refuses a prompt carrying PII; `off` (default) disables screening entirely. */
1296
+ onDetect: 'off' | 'reject';
1297
+ /** Entity kinds to screen for. Defaults to {@link DEFAULT_PII_ENTITY_TYPES}. */
1298
+ entities?: Array<AiPiiEntityType>;
1299
+ /** App-specific PII in plain language, e.g. `'internal case numbers like CASE-12345'`. */
1300
+ customRules?: Array<string>;
1301
+ /**
1302
+ * Model performing the screening. Defaults to {@link DEFAULT_PII_CLASSIFIER_MODEL}. Each attempt is
1303
+ * bounded at a minute, so an override has to answer within it.
1304
+ */
1305
+ classifierModel?: AiChatModelSelection;
1306
+ /** Literal values that never count as PII, e.g. a shared support address. */
1307
+ allowList?: Array<string>;
1308
+ };
1309
+ /**
1310
+ * Outcome of screening one prompt. On a detection the prompt is replaced by {@link redactedPrompt}
1311
+ * everywhere it would otherwise be stored, so the audit trail records that a request was refused
1312
+ * and why without restating the values that caused it.
1313
+ * @category AI
1314
+ */
1315
+ export type AiPiiScanResult = {
1316
+ detected: false;
1317
+ } | {
1318
+ detected: true;
1319
+ /** Entity kinds and custom-rule names that matched. Never the matched values. */
1320
+ matchedTypes: Array<string>;
1321
+ /** The prompt with every match replaced by a `[REDACTED:<type>]` placeholder. */
1322
+ redactedPrompt: string;
1323
+ };
1324
+ /**
1325
+ * Response structure for transcribing audio and asking an AI agent a question.
1326
+ * @category AI
1327
+ */
1328
+ export interface AiTranscribeAndAskResponse {
1329
+ /** The AI agent's response to the transcribed prompt. */
1330
+ responseString: string;
1331
+ /** The transcribed text from the audio input. */
1332
+ transcribedPrompt: string;
1333
+ /** The annotations associated with the AI response, if any. */
1334
+ annotations?: Record<string, AiAnnotation>;
1335
+ }
1336
+ /** Per application AI settings. */
1337
+ export interface ApplicationAiSettings {
1338
+ /** Maps AI provider name to API key secret name that must be used for any request made by the application. */
1339
+ apiKeys: Partial<Record<AiProviderType, SecretKey>>;
1340
+ }
1341
+ /**
1342
+ * Options for user-provided LLM models.
1343
+ * @category AI
1344
+ */
1345
+ export interface UserAiChatOptions extends BaseAiChatOptions {
1346
+ /** LLM Model to use for the chat query. */
1347
+ model: UserAiChatModelName;
1348
+ }
1349
+ /**
1350
+ * Response structure for asking a user LLM a question.
1351
+ * @category AI
1352
+ */
1353
+ export interface UserAiAskResponse {
1354
+ /** The response from the AI agent. */
1355
+ response?: string;
1356
+ /** Prompt tokens used by the request, including any the prompt cache served. */
1357
+ inputTokens?: number;
1358
+ /** The number of output tokens generated by the AI agent. */
1359
+ outputTokens?: number;
1360
+ /** Cached input tokens read from the prompt cache. Only set by providers that report it (e.g. claude-code). */
1361
+ cacheReadInputTokens?: number;
1362
+ /** Input tokens written to the prompt cache. Only set by providers that report it (e.g. claude-code). */
1363
+ cacheWriteInputTokens?: number;
1364
+ /** Total request cost in USD as reported by the provider. Only set by providers that compute it (e.g. claude-code). */
1365
+ totalCostUsd?: number;
1366
+ /**
1367
+ * True when the run succeeded but persisting its workspace (push) failed, so the working-directory
1368
+ * changes made during this ask may not survive to the next one. Only ever set for workspace-backed CLI
1369
+ * agents; absent otherwise.
1370
+ */
1371
+ workspacePushFailed?: boolean;
1372
+ }
1373
+ /** Represents an annotation in the AI response. */
1374
+ export type AiAnnotation = AiFileAnnotation;
1375
+ /** Represents an annotation for a file in the AI response. */
1376
+ export interface AiFileAnnotation {
1377
+ /** The type of the annotation, always 'file'. */
1378
+ type: 'file';
1379
+ /** The AI file with the URL to the file */
1380
+ aiFileUrl: AiFileUrl;
1381
+ }
1382
+ /**
1383
+ * Context for an AI session
1384
+ */
1385
+ export type AiSessionContext = {
1386
+ /** The ID of the client initiating the session. */
1387
+ clientId: string;
1388
+ /** The ID of the AI agent involved in the session. */
1389
+ agentId: string;
1390
+ /** The ID of the job associated with the session. */
1391
+ jobId: JobId;
1392
+ /**
1393
+ * The conversation this call belongs to, as the caller named it (`memoryOptions.memoryId`).
1394
+ * Stable across the turns of one chat and different for two chats, including
1395
+ * two chats of the same client, which `clientId` is not: a client id belongs to a connection, and
1396
+ * one connection can carry several conversations. Not the id chat history is keyed by — that one
1397
+ * falls back to `clientId` — so do not read it as one. Absent for callers that named no conversation
1398
+ * (a direct function call, security rules).
1399
+ */
1400
+ conversationId?: string;
1401
+ /**
1402
+ * ID of the status update that triggered this session (e.g. the agent's "Calling AI Function"
1403
+ * event). Status updates emitted on behalf of this session nest under it in the status feed.
1404
+ */
1405
+ parentStatusUpdateId?: string;
1406
+ /**
1407
+ * Whether the invoking agent has audit logging enabled. Sub-agents working on behalf of this
1408
+ * session gate their own audit-log writes on it, keeping one job's audit trail consistent.
1409
+ */
1410
+ auditLog?: boolean;
1411
+ /**
1412
+ * The chat timeout (in milliseconds) the root chat request explicitly set. Present only when
1413
+ * the root request passed `timeoutMs`. Nested AI operations (e.g. AI-query stages spawned by a
1414
+ * tool call) budget against it so a long-running parent chat is not silently capped by the
1415
+ * nested defaults; explicitly configured per-stage `aiOptions.timeoutMs` is more specific and
1416
+ * takes precedence over it.
1417
+ */
1418
+ timeoutMs?: number;
1419
+ };
1420
+ /**
1421
+ * API request to delete an AI agent
1422
+ * @category AI
1423
+ */
1424
+ export interface DeleteAgentRequest {
1425
+ /** The ID of the agent to delete */
1426
+ agentId: string;
1427
+ }
1428
+ /**
1429
+ * API response from agent ask methods
1430
+ * @category AI
1431
+ */
1432
+ export interface AiAskResponse {
1433
+ /** The response string from the agent */
1434
+ responseString: string;
1435
+ /** Optional annotations (e.g., file references) in the response */
1436
+ annotations?: Record<string, AiAnnotation>;
1437
+ /** Set when `model` was an {@link AiModelRoutingOptions}: which model answered and what routing cost. */
1438
+ routing?: AiModelRoutingResult;
1439
+ }
1440
+ /**
1441
+ * API request to create speech from text
1442
+ * @category AI
1443
+ */
1444
+ export interface AiAudioCreateSpeechRequest {
1445
+ /** The text input to convert to speech */
1446
+ input: string;
1447
+ /** Options for speech generation */
1448
+ options: AiAudioCreateSpeechOptions;
1449
+ }
1450
+ /**
1451
+ * API request to generate an image
1452
+ * @category AI
1453
+ */
1454
+ export interface AiGenerateImageRequest {
1455
+ /** The prompt describing the image to generate */
1456
+ prompt: string;
1457
+ /** Options for image generation */
1458
+ options?: AiGenerateImageOptions;
1459
+ }
1460
+ /**
1461
+ * Revision action types for agent history tracking.
1462
+ * @category AI
1463
+ */
1464
+ export type AiAgentRevisionAction = 'created' | 'updated' | 'deleted';
1465
+ /**
1466
+ * Represents a single agent revision entry.
1467
+ * @category AI
1468
+ */
1469
+ export interface AiAgentRevision {
1470
+ /** The ID of the agent this revision belongs to. */
1471
+ agentId: AiAgentId;
1472
+ /** The revision number, incremented for each change to the agent. */
1473
+ revisionNumber: number;
1474
+ /** The action that triggered this revision (created, updated, or deleted). */
1475
+ action: AiAgentRevisionAction;
1476
+ /** Timestamp when this revision was created. */
1477
+ createdAt: Date;
1478
+ /** Snapshot of the agent data at the time of the revision. */
1479
+ agentSnapshot: AiAgent;
1480
+ }
1481
+ /**
1482
+ * Request to list all revisions for an agent.
1483
+ * @category AI
1484
+ */
1485
+ export interface ListAgentRevisionsRequest {
1486
+ /** The ID of the agent to list revisions for. */
1487
+ agentId: AiAgentId;
1488
+ }
1489
+ /**
1490
+ * Response containing the list of agent revisions.
1491
+ * @category AI
1492
+ */
1493
+ export interface ListAgentRevisionsResponse {
1494
+ /** The list of revisions for the agent, sorted by revision number descending. */
1495
+ revisions: Array<AiAgentRevision>;
1496
+ }
1497
+ /**
1498
+ * Request to get a specific agent revision.
1499
+ * @category AI
1500
+ */
1501
+ export interface GetAgentRevisionRequest {
1502
+ /** The ID of the agent to get the revision for. */
1503
+ agentId: AiAgentId;
1504
+ /** The revision number to retrieve. */
1505
+ revisionNumber: number;
1506
+ }
1507
+ /**
1508
+ * Response containing a specific agent revision.
1509
+ * @category AI
1510
+ */
1511
+ export interface GetAgentRevisionResponse {
1512
+ /** The requested revision, or undefined if not found. */
1513
+ revision: AiAgentRevision | undefined;
1514
+ }
1515
+ /**
1516
+ * Request to restore an agent to a specific revision.
1517
+ * @category AI
1518
+ */
1519
+ export interface RestoreAgentRevisionRequest {
1520
+ /** The ID of the agent to restore. */
1521
+ agentId: AiAgentId;
1522
+ /** The revision number to restore the agent to. */
1523
+ revisionNumber: number;
1524
+ }
1525
+ /**
1526
+ * Request to delete a specific agent revision.
1527
+ * @category AI
1528
+ */
1529
+ export interface DeleteAgentRevisionRequest {
1530
+ /** The ID of the agent whose revision should be deleted. */
1531
+ agentId: AiAgentId;
1532
+ /** The revision number to delete. */
1533
+ revisionNumber: number;
1534
+ }
1535
+ /**
1536
+ * Options for the agent builder.
1537
+ * @category AI
1538
+ */
1539
+ export interface BuildAgentOptions {
1540
+ /** Whether the caller has permission to create or update integrations. Defaults to false. */
1541
+ canManageIntegrations?: boolean;
1542
+ }
1543
+ /**
1544
+ * Response containing the list of AI agents in an application.
1545
+ * @category AI
1546
+ */
1547
+ export interface ListAgentsResponse {
1548
+ /** All AI agents defined for the application. */
1549
+ agents: Array<AiAgent>;
1550
+ }
1551
+ /**
1552
+ * Request options for listing the chat models available to an application.
1553
+ * @category AI
1554
+ */
1555
+ export interface ListChatModelsRequest {
1556
+ /**
1557
+ * When true, deprecated vendor models (those with `replacedBy`) are included.
1558
+ * Defaults to false (only active models are returned).
1559
+ */
1560
+ includeDeprecated?: boolean;
1561
+ }
1562
+ /**
1563
+ * Response containing the list of chat models available to an application.
1564
+ * Includes both Squid-provided vendor models and any custom integration models.
1565
+ * Vendor models carry a human-readable `description`. Deprecated vendor models are
1566
+ * included only when requested via `includeDeprecated` and are marked with `replacedBy`.
1567
+ * @category AI
1568
+ */
1569
+ export interface ListChatModelsResponse {
1570
+ /** All chat models available to the application. */
1571
+ models: Array<ModelIdSpec>;
1572
+ }
1573
+ /**
1574
+ * Request options for listing the embedding models a new knowledge base can be created on.
1575
+ * @category AI
1576
+ */
1577
+ export interface ListEmbeddingModelsRequest {
1578
+ /**
1579
+ * When true, deprecated vendor models (those with `replacedBy`) are included.
1580
+ * Defaults to false (only active models are returned).
1581
+ */
1582
+ includeDeprecated?: boolean;
1583
+ }
1584
+ /**
1585
+ * Response containing the embedding models a new knowledge base can be created on: Squid-provided
1586
+ * vendor models and the application's custom integration models. Exactly one entry carries `isDefault`.
1587
+ * Deprecated vendor models are included only when requested via `includeDeprecated` and are marked
1588
+ * with `replacedBy`; an existing knowledge base keeps its model regardless.
1589
+ * @category AI
1590
+ */
1591
+ export interface ListEmbeddingModelsResponse {
1592
+ /** All embedding models available to the application. */
1593
+ models: Array<EmbeddingModelIdSpec>;
1594
+ }