@squidcloud/jira-client 1.0.497 → 1.0.499

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/common/src/jira-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 +1609 -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 +2379 -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 +57 -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 +105 -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 +20 -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 +93 -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,1609 @@
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` or `chat` 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` or `chat` 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
+ * What a `chat` job resolves to once its stream has ended; read it with `squid.jobs().awaitJob(jobId)`.
442
+ * @category AI
443
+ */
444
+ export interface AiChatJobResult {
445
+ /** Set when `model` was an {@link AiModelRoutingOptions}: which model answered and what routing cost. */
446
+ routing?: AiModelRoutingResult;
447
+ }
448
+ /**
449
+ * Chat options as a request carries them: the model may also be a routing choice between several models.
450
+ * @category AI
451
+ */
452
+ export type AiChatRequestOptions = Omit<AllAiAgentChatOptions, 'model'> & {
453
+ model?: AiAskModelSelection;
454
+ };
455
+ /**
456
+ * How a request whose `model` was an {@link AiModelRoutingOptions} was routed.
457
+ * @category AI
458
+ */
459
+ export interface AiModelRoutingResult {
460
+ /** The model the routing model chose and the request was sent to. A `backupModel` may still have served it. */
461
+ model: VendorAiChatModelName;
462
+ /** The model that made the choice. */
463
+ routingModel: VendorAiChatModelName;
464
+ /** Input tokens the routing call consumed. */
465
+ inputTokens: number;
466
+ /** Output tokens the routing call generated. */
467
+ outputTokens: number;
468
+ /** Best-effort USD cost of the routing call; undefined when the routing model is unpriced. */
469
+ costUsd?: number;
470
+ }
471
+ /**
472
+ * A backup model together with the sampling settings to run it with. Use this form instead of a
473
+ * bare {@link AiChatModelSelection} when the backup needs settings of its own; anything left unset
474
+ * takes the backup model's own default rather than the primary model's value.
475
+ * @category AI
476
+ */
477
+ export interface BackupModelOptions {
478
+ /** The model to fall back to. */
479
+ model: AiChatModelSelection;
480
+ /** The temperature to use when sampling from the backup model. */
481
+ temperature?: number;
482
+ /** The level of reasoning effort to apply; effective only for models with reasoning. */
483
+ reasoningEffort?: AiReasoningEffort;
484
+ /** The maximum number of input tokens Squid may send to the backup model. */
485
+ maxTokens?: number;
486
+ /** The maximum number of tokens the backup model should output. */
487
+ maxOutputTokens?: number;
488
+ /** Response length and detail level; supported by OpenAI models only. */
489
+ verbosity?: AiVerbosityLevel;
490
+ }
491
+ /**
492
+ * The base AI agent chat options, should not be used directly.
493
+ * @category AI
494
+ */
495
+ export interface BaseAiChatOptions {
496
+ /**
497
+ * The maximum number of input tokens that Squid can use when making the request to the AI model.
498
+ * Defaults to the max tokens the model can accept.
499
+ */
500
+ maxTokens?: number;
501
+ /**
502
+ * The maximum number of tokens the model should output.
503
+ * Passed directly to the AI model. Can be used to control the output verbosity.
504
+ */
505
+ maxOutputTokens?: number;
506
+ /** The context ID to use for the request. If not provided, the agent's default context will be used. */
507
+ memoryOptions?: AiAgentMemoryOptions;
508
+ /**
509
+ * Names a persistent working directory for CLI-backed agents (`claude-code`, `codex`). When set, the
510
+ * agent runs in a directory keyed by this id, synced across pod replicas via the shared workspace
511
+ * server, so files created in one ask persist and are visible to later asks reusing the same id —
512
+ * including across providers.
513
+ *
514
+ * Pass the same id consistently for a conversation; changing it points the agent at a different
515
+ * directory (and, for Claude Code, starts a fresh transcript). Must match `[A-Za-z0-9_-]` (1-200 chars).
516
+ * Ignored by non-CLI agents and when the workspace server is unconfigured (falls back to a pod-local,
517
+ * non-synced, ephemeral dir).
518
+ */
519
+ workspaceId?: string;
520
+ /** Whether to disable the whole context for the request. Default to false. */
521
+ disableContext?: boolean;
522
+ /**
523
+ * Whether to use the legacy knowledge base context mode, where KB results are fetched upfront
524
+ * and appended directly to the prompt. When false (default), the KB is exposed as a callable
525
+ * tool that the LLM can invoke on demand.
526
+ */
527
+ legacyKnowledgeBaseContext?: boolean;
528
+ /** Rewrite prompt for RAG - defaults to false */
529
+ enablePromptRewriteForRag?: boolean;
530
+ /**
531
+ * Whether to include references from the source context in the response. Default to false.
532
+ * @deprecated Use citation instead. Kept for compatibility; renders the legacy Quote/Source format
533
+ * on the legacy upfront-RAG path only.
534
+ */
535
+ includeReference?: boolean;
536
+ /**
537
+ * When true, the agent cites the sources behind its statements: source name, plus a download link
538
+ * when the agent's stored options set `allowSourceDownloads`. Takes precedence over the deprecated
539
+ * `includeReference`. Default to false.
540
+ */
541
+ citation?: boolean;
542
+ /**
543
+ * Allows citation links to the original source files (presigned, 1h expiry). Honored ONLY from the
544
+ * agent's stored options — the per-request value is ignored, so callers of public agents can never
545
+ * enable downloads. Default to false (citations render source names only).
546
+ */
547
+ allowSourceDownloads?: boolean;
548
+ /**
549
+ * The format of the response from the AI model. Defaults to 'text'. A `json_schema` format is
550
+ * refused for a model whose provider has no way to carry a schema — see
551
+ * {@link AiAgentResponseFormat}.
552
+ */
553
+ responseFormat?: AiAgentResponseFormat;
554
+ /** Whether to response in a "smooth typing" way, beneficial when the chat result is displayed in a UI. Default to true. */
555
+ smoothTyping?: boolean;
556
+ /**
557
+ * Global context passed to the agent and all AI functions of the agent. A request's value also reaches the AI
558
+ * functions of its connected agents, merged over each one's stored `agentContext`. Its keys are caller input and
559
+ * win over stored ones: only the root agent's `@secureAiAgent` rules can vet them, and none run for a public agent.
560
+ */
561
+ agentContext?: Record<string, unknown>;
562
+ /**
563
+ * Functions to expose to the AI.
564
+ * Either a function name or a name with an extra function context passed only to this function.
565
+ * The parameter values must be valid serializable JSON values.
566
+ * Overrides the stored value.
567
+ */
568
+ functions?: Array<AiFunctionId | AiFunctionIdWithContext>;
569
+ /** Instructions to include with the prompt. */
570
+ instructions?: string;
571
+ /** A set of filters that will limit the context the AI can access.
572
+ * @deprecated use `contextMetadataFilterForKnowledgeBase` instead.
573
+ */
574
+ contextMetadataFilter?: AiContextMetadataFilter;
575
+ /** A set of filters that will limit the context the AI can access. */
576
+ contextMetadataFilterForKnowledgeBase?: Record<AiKnowledgeBaseId, AiContextMetadataFilter>;
577
+ /** The options to use for the response in voice. */
578
+ voiceOptions?: AiAudioCreateSpeechOptions;
579
+ /** List of connected AI agents can be called by the current agent. Overrides the stored value. */
580
+ connectedAgents?: Array<AiConnectedAgentMetadata>;
581
+ /** List of connected AI agents can be called by the current agent. Overrides the stored value. */
582
+ connectedIntegrations?: Array<AiConnectedIntegrationMetadata>;
583
+ /** List of connected AiKnowlegeBases that can be called by the current agent */
584
+ connectedKnowledgeBases?: Array<AiConnectedKnowledgeBaseMetadata>;
585
+ /** Current budget for nested or recursive AI chat calls per single prompt. */
586
+ quotas?: AiChatPromptQuotas;
587
+ /**
588
+ * Include metadata in the context.
589
+ * @deprecated Use `includeMetadata` on individual `AiConnectedKnowledgeBaseMetadata` entries in `connectedKnowledgeBases` instead.
590
+ */
591
+ includeMetadata?: boolean;
592
+ /** The temperature to use when sampling from the model. Default to 0.5. */
593
+ temperature?: number;
594
+ /** Preset instruction options that can be toggled on */
595
+ guardrails?: GuardrailsOptions;
596
+ /**
597
+ * Refuses prompts that carry PII before they reach the model. Read from the stored agent only —
598
+ * a value passed with a chat request is ignored, so a caller cannot switch off its own screening.
599
+ */
600
+ pii?: AiPiiOptions;
601
+ /** The LLM model to use. Can be a vendor model name (string) or an integration-based model (object). */
602
+ model?: AiChatModelSelection;
603
+ /**
604
+ * The model to use when `model` cannot serve the conversation's very first request because its
605
+ * provider is unavailable — a rate limit, a capacity outage, or any other failure on the
606
+ * provider's side. A request that fails for its own reasons (an invalid prompt, a rejected
607
+ * schema, an exhausted Squid quota) is never retried on the backup, nor is any request after the
608
+ * first one, nor one that already produced output or ran a tool.
609
+ *
610
+ * A conversation that fell back then STAYS on that backup for the rest of its life, so an outage
611
+ * costs the primary's retry budget once rather than once per turn, and the model does not change
612
+ * mid-dialogue. The pin outlives the option that created it: changing or removing `backupModel`,
613
+ * changing the agent's own `model`, and the primary recovering all leave a pinned conversation
614
+ * where it is, and a pinned model that no longer resolves fails the request rather than moving the
615
+ * conversation. This is deliberate — a conversation accumulates provider-native file ids and a
616
+ * transcript in that provider's dialect, none of which survive a move. Pinning needs Squid-managed
617
+ * memory to have somewhere to record it; without memory every request is a first request anyway.
618
+ *
619
+ * A request carrying `fileIds` follows from the same reasoning, and the two cases differ. A first
620
+ * request does not fall back where that would cost it the attachments — to a model that cannot read
621
+ * ids the primary could, or that reads them without owning them — since answering from a model that
622
+ * never saw them is worse than reporting the outage. Where neither model reads file ids they are
623
+ * inert either way and the fallback proceeds. A
624
+ * conversation already pinned is held to less: it keeps running on its model, and if that model
625
+ * reads no file ids the ids are ignored there as they are anywhere else, because the alternative is
626
+ * a conversation that can never run again.
627
+ *
628
+ * Pass a model name for the model's own defaults, or a {@link BackupModelOptions} object to give
629
+ * the backup its own sampling settings. Everything else — instructions, functions, knowledge
630
+ * bases, connected agents, response format, memory — always comes from the primary configuration.
631
+ *
632
+ * On a turn the backup serves, the sampling settings are ITS settings alone: `temperature`,
633
+ * `reasoningEffort`, `maxTokens`, `maxOutputTokens` and `verbosity` are read from `backupModel`
634
+ * and nowhere else, so a value left unset there takes the backup model's own default even when
635
+ * the agent's profile or the request itself carries one. This holds for every turn of a pinned
636
+ * conversation, not only the one that fell back — tuning meant for one model is not evidence of
637
+ * what another should use.
638
+ *
639
+ * Applies to models served through Squid's own provider SDKs — the vendor models and
640
+ * `openai_compatible`, Bedrock and Vertex integrations. A model you serve yourself from backend
641
+ * code reports its failures as plain errors that carry no provider status, so a turn on one is
642
+ * never diagnosed as a provider outage and never falls back.
643
+ *
644
+ * The backup resolves its API key exactly as it would as the primary model, and is skipped
645
+ * silently when it cannot be resolved, when it reaches the same model as the primary, or when
646
+ * either model is a CLI-backed agent. Leave unset to keep a provider outage surfacing as an error.
647
+ */
648
+ backupModel?: AiChatModelSelection | BackupModelOptions;
649
+ /** Which provider's reranker to use for reranking the context. Defaults to 'cohere'. */
650
+ rerankProvider?: AiRerankProvider;
651
+ /**
652
+ * Options for AI agent execution plan, allowing the agent to perform an execution plan before invoking
653
+ * connected agents, connected integrations, or functions.
654
+ */
655
+ executionPlanOptions?: AiAgentExecutionPlanOptions;
656
+ /** An array of file URLs to include in the chat context. */
657
+ fileUrls?: Array<AiFileUrl>;
658
+ /**
659
+ * Arbitrary client-defined annotations attached to this AI call for usage tracking.
660
+ * Reported as `annotation.<key>` tags on Squid AI usage metrics, so token usage can later be
661
+ * filtered and grouped by these values (e.g. `{ feature: 'support-bot', requestSource: 'mobile' }`).
662
+ * Inherited by nested calls to connected agents made while serving this call.
663
+ * Limits: at most 10 entries, keys up to 64 characters, values up to 256 characters;
664
+ * entries beyond the limits are dropped or truncated.
665
+ */
666
+ metricAnnotations?: Record<string, string>;
667
+ /**
668
+ * The level of reasoning effort to apply; defaults to model-specific value.
669
+ * Effective only for models with reasoning.
670
+ */
671
+ reasoningEffort?: AiReasoningEffort;
672
+ /**
673
+ * Controls response length and detail level.
674
+ * Use `low` for brief responses, `medium` for balanced detail, or `high` for comprehensive explanations.
675
+ * Default: 'medium'.
676
+ *
677
+ * Note: this parameter is only supported by OpenAI and is ignored for others. It applies to every
678
+ * response format, including `json_object` and `json_schema`.
679
+ * For other providers ask about verbosity in prompt and using `maxOutputTokens`.
680
+ */
681
+ verbosity?: AiVerbosityLevel;
682
+ /**
683
+ * Enable LLMs built-in code interpreter for executing Python code.
684
+ * - 'none': Code interpreter is disabled (default).
685
+ * - 'llm': Use LLM's native code interpreter to run Python code.
686
+ *
687
+ * Note: Only supported by OpenAI, Anthropic and Gemini models. Ignored for other providers.
688
+ */
689
+ useCodeInterpreter?: 'none' | 'llm';
690
+ /**
691
+ * File IDs to include in the chat context.
692
+ * These are IDs returned from the AI provider's Files API after uploading files.
693
+ * Files are attached to the conversation and can be read/analyzed by the AI.
694
+ */
695
+ fileIds?: string[];
696
+ /**
697
+ * Timeout in milliseconds for one model-call attempt of the chat (a single provider call,
698
+ * covering that call's tool loop). An attempt that produced nothing by this deadline is treated
699
+ * as a stalled provider connection and retried per `retriesOnStall`, each retry getting this
700
+ * full budget again — so the provider phase of a chat may take up to
701
+ * `(1 + retriesOnStall) * timeoutMs` in the worst case. Defaults to 240,000 (4 minutes).
702
+ */
703
+ timeoutMs?: number;
704
+ /**
705
+ * How many times a stalled model-call attempt is reissued. A retry happens only when the
706
+ * attempt hit `timeoutMs` having produced nothing AND no AI function has executed in the turn,
707
+ * so a retry can never repeat a side effect; aborting the stalled attempt destroys its
708
+ * connection, so the retry cannot reuse it. `0` disables stall retries. Defaults to 1.
709
+ */
710
+ retriesOnStall?: number;
711
+ /** Maximum number of tool-call iterations the model may perform in a single chat turn. Defaults to 50. */
712
+ maxToolIterations?: number;
713
+ }
714
+ /**
715
+ * Chat options specific to Gemini models, extending base options.
716
+ * @category AI
717
+ */
718
+ export interface GeminiChatOptions extends BaseAiChatOptions {
719
+ /** The Gemini model to use for the chat. */
720
+ model?: GeminiChatModelName;
721
+ /** Enables grounding with web search for more informed responses; defaults to false. */
722
+ groundingWithWebSearch?: boolean;
723
+ }
724
+ /**
725
+ * Chat options specific to Grok models, extending base options.
726
+ * @category AI
727
+ */
728
+ export interface GrokChatOptions extends BaseAiChatOptions {
729
+ /** The Grok model to use for the chat. */
730
+ model?: GrokChatModelName;
731
+ }
732
+ /**
733
+ * Chat options specific to OpenAI models, extending base options.
734
+ * @category AI
735
+ */
736
+ export interface OpenAiChatOptions extends BaseAiChatOptions {
737
+ /** The OpenAI model to use for the chat. */
738
+ model?: OpenAiChatModelName;
739
+ }
740
+ /**
741
+ * Canonical reasoning-effort levels, ordered from least to most effort. These are the values that
742
+ * have a defined position on the effort axis and therefore participate in clamping when a model does
743
+ * not support the exact requested level.
744
+ * @category AI
745
+ */
746
+ export type { CanonicalReasoningEffort } from './ai-common.public-types';
747
+ /**
748
+ * AI reasoning effort. Pass one of the canonical levels for portable, autocomplete-friendly usage, or
749
+ * a raw provider-native string when a model exposes a level outside the canonical set.
750
+ *
751
+ * Resolution against the selected model (see {@link ReasoningCapability}):
752
+ * - exact match with the model's capability -> used as-is (1:1);
753
+ * - canonical level the model lacks -> clamped to the nearest supported level (ties resolve downward);
754
+ * - unknown string the model cannot place on the axis -> dropped, so the model's own default applies,
755
+ * with a warning;
756
+ * - model without a reasoning knob -> ignored, with a warning.
757
+ *
758
+ * A model served through an `openai_compatible` integration is the exception: the value is sent to
759
+ * that endpoint exactly as written, with none of the resolution above, since the endpoint's model is
760
+ * the app's own choice and this registry cannot describe it. That is also how to reach a level the
761
+ * canonical set has no name for.
762
+ * @category AI
763
+ */
764
+ export type AiReasoningEffort = CanonicalReasoningEffort | (string & {});
765
+ /**
766
+ * Declares how a model exposes reasoning effort. Used as the single source of truth for resolving a
767
+ * requested {@link AiReasoningEffort} onto what the model natively accepts. When a request cannot be
768
+ * matched or clamped, no reasoning parameter is emitted and the model applies its own native default.
769
+ *
770
+ * - `none`: the model has no reasoning knob (e.g. it always reasons).
771
+ * - `levels`: the model accepts a fixed set of named levels (emitted as a string).
772
+ * - `budget`: the model accepts a token budget; each canonical level maps to a concrete integer.
773
+ * @category AI
774
+ */
775
+ export type ReasoningCapability = {
776
+ kind: 'none';
777
+ } | {
778
+ kind: 'levels';
779
+ supported: AiReasoningEffort[];
780
+ } | {
781
+ kind: 'budget';
782
+ perLevel: Partial<Record<CanonicalReasoningEffort, number>>;
783
+ };
784
+ /**
785
+ * Controls response length and detail level.
786
+ * Use `low` for brief responses,`medium` for balanced detail, or `high` for comprehensive explanations.
787
+ * Default: 'medium'.
788
+ */
789
+ export type AiVerbosityLevel = 'low' | 'medium' | 'high';
790
+ /**
791
+ * Chat options specific to Anthropic models, extending base options.
792
+ *
793
+ * **Structured Outputs:**
794
+ * Anthropic models support structured outputs
795
+ * through the `responseFormat` field. Pass an object with `type: 'json_schema'` and a JSON schema
796
+ * to guarantee the response conforms exactly to your schema.
797
+ *
798
+ * **Example:**
799
+ * ```typescript
800
+ * {
801
+ * model: 'claude-sonnet-5-5',
802
+ * responseFormat: {
803
+ * type: 'json_schema',
804
+ * schema: {
805
+ * type: 'object',
806
+ * properties: {
807
+ * name: { type: 'string' },
808
+ * age: { type: 'number' }
809
+ * },
810
+ * required: ['name', 'age'],
811
+ * additionalProperties: false
812
+ * }
813
+ * }
814
+ * }
815
+ * ```
816
+ *
817
+ * @see https://docs.anthropic.com/en/docs/build-with-claude/structured-outputs
818
+ * @category AI
819
+ */
820
+ export interface AnthropicChatOptions extends BaseAiChatOptions {
821
+ /** The Anthropic model to use for the chat. */
822
+ model?: AnthropicChatModelName;
823
+ }
824
+ /**
825
+ * The generic options type. When no generic is provided,
826
+ * the type is inferred from the provided overrideModel (or falls back to BaseAiAgentChatOptions).
827
+ * @category AI
828
+ */
829
+ 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;
830
+ /**
831
+ * @category AI
832
+ */
833
+ export type AllAiAgentChatOptions = {
834
+ [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);
835
+ };
836
+ /**
837
+ * Credentials a caller sends with one chat request. The client sends them in the `x-squid-integration-access-tokens`
838
+ * request header rather than with the options, so they reach only the tools that run with them and are never stored
839
+ * with the agent.
840
+ * @category AI
841
+ */
842
+ export interface AiChatRequestCredentials {
843
+ /**
844
+ * Access tokens keyed by integration ID. The integration's tools run with its token for this request when the
845
+ * integration type supports it; other types ignore it.
846
+ */
847
+ integrationAccessTokens?: Record<IntegrationId, string>;
848
+ }
849
+ /**
850
+ * Configuration for exposing an AI agent as an MCP server at `/mcp/<agentId>`.
851
+ * @category AI
852
+ */
853
+ export interface AiAgentMcpServerConfig {
854
+ /** Whether the agent is exposed as an MCP server. */
855
+ enabled: boolean;
856
+ /**
857
+ * Description of the MCP server, served as the `instructions` field of the MCP initialize
858
+ * result. Defaults to the agent description when not provided.
859
+ */
860
+ description?: string;
861
+ /**
862
+ * Description of the MCP `ask` tool, exposed in the tools manifest.
863
+ * Defaults to a generic ask-the-agent description when not provided.
864
+ */
865
+ toolDescription?: string;
866
+ /**
867
+ * ID of an auth integration used to OAuth-protect the MCP server. When set, MCP requests must
868
+ * include a valid bearer token from this integration. Without this and `requireApiKey`, the
869
+ * MCP endpoint is public.
870
+ */
871
+ oauthIntegrationId?: IntegrationId;
872
+ /**
873
+ * When true, MCP requests must present the agent's API key as a bearer token
874
+ * (`Authorization: Bearer <agent API key>` or the `x-squid-agent-api-key` header). Can be
875
+ * combined with `oauthIntegrationId`, in which case either credential is accepted.
876
+ */
877
+ requireApiKey?: boolean;
878
+ }
879
+ /**
880
+ * Request to AI-generate the MCP server and tool descriptions for an agent based on its
881
+ * instructions and connected resources.
882
+ * @category AI
883
+ */
884
+ export interface GenerateAgentMcpDescriptionsRequest {
885
+ /** The ID of the agent to generate MCP descriptions for. */
886
+ agentId: AiAgentId;
887
+ }
888
+ /**
889
+ * AI-generated MCP descriptions for an agent. Returned without persisting — the caller saves them
890
+ * onto the agent's MCP server configuration.
891
+ * @category AI
892
+ */
893
+ export interface GenerateAgentMcpDescriptionsResponse {
894
+ /** Generated description of the MCP server. */
895
+ description: string;
896
+ /** Generated description of the MCP `ask` tool. */
897
+ toolDescription: string;
898
+ }
899
+ /**
900
+ * A definition of an AI agent with its properties and default chat options.
901
+ * @category AI
902
+ */
903
+ export interface AiAgent<T extends AiChatModelSelection | undefined = undefined> {
904
+ /** The unique identifier of the AI agent. */
905
+ id: AiAgentId;
906
+ /** The date and time the agent was created. */
907
+ createdAt: Date;
908
+ /** The date and time the agent was last updated. */
909
+ updatedAt: Date;
910
+ /** An optional description of the agent's purpose or capabilities. */
911
+ description?: string;
912
+ /** Indicates whether the agent is publicly accessible; defaults to false. */
913
+ isPublic?: boolean;
914
+ /** Enables audit logging for the agent's activities if true; defaults to false. */
915
+ auditLog?: boolean;
916
+ /** 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. */
917
+ auditLogFullContext?: boolean;
918
+ /** The default chat options for the agent, overridable by the user during use. */
919
+ options: AiChatOptions<T>;
920
+ /** Optional api key used specifically for operations on this agent */
921
+ apiKey?: string;
922
+ /** Optional configuration for exposing the agent as an MCP server. */
923
+ mcpServer?: AiAgentMcpServerConfig;
924
+ }
925
+ /**
926
+ * @category AI
927
+ */
928
+ export type UpsertAgentRequest = Omit<AiAgent, 'createdAt' | 'updatedAt' | 'options'> & {
929
+ options?: AiChatOptions;
930
+ };
931
+ /**
932
+ * Status update title broadcast when the agent finishes producing a response,
933
+ * either successfully or with an error. Emitted exactly once per `ask` job and
934
+ * is the last status event for that job.
935
+ * @category AI
936
+ */
937
+ export declare const AGENT_STATUS_TITLE_AGENT_RESPONSE = "Agent Response";
938
+ /**
939
+ * Status update title broadcast when the agent invokes a knowledge-base
940
+ * callable. A matching invocation produces a single event with this title.
941
+ * @category AI
942
+ */
943
+ export declare const AGENT_STATUS_TITLE_ACCESSING_KB = "Accessing Knowledge Base";
944
+ /**
945
+ * Status update title broadcast when the agent invokes an AI function callable
946
+ * (a backend `@aiFunction`). Lets a caller detect that a function was actually
947
+ * called, independent of how the model renders the result in its final answer.
948
+ * @category AI
949
+ */
950
+ export declare const AGENT_STATUS_TITLE_CALLING_AI_FUNCTION = "Calling AI Function";
951
+ /**
952
+ * Status update title broadcast when an AI function callable returns, carrying the function's raw
953
+ * result in the body. Nested under the matching {@link AGENT_STATUS_TITLE_CALLING_AI_FUNCTION} event.
954
+ * @category AI
955
+ */
956
+ export declare const AGENT_STATUS_TITLE_AI_FUNCTION_RESULT = "AI Function Result";
957
+ /**
958
+ * Status update title broadcast when the agent invokes a knowledge-base metadata-inspection callable
959
+ * (the opt-in `enableMetadataInspection` tool). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB}
960
+ * so a caller can tell a metadata-value inspection apart from an ordinary KB search.
961
+ * @category AI
962
+ */
963
+ export declare const AGENT_STATUS_TITLE_INSPECTING_KB_METADATA = "Inspecting Knowledge Base Metadata";
964
+ /**
965
+ * Status update title broadcast when the agent invokes the knowledge-graph query callable (offered
966
+ * automatically for graph-enabled KBs). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB} so a
967
+ * caller can tell graph navigation apart from an ordinary KB search.
968
+ * @category AI
969
+ */
970
+ export declare const AGENT_STATUS_TITLE_QUERYING_KB_GRAPH = "Querying Knowledge Base Graph";
971
+ /**
972
+ * Status update title emitted when the agent runs the `grepKnowledgeBase` tool (a literal/regex scan over
973
+ * the knowledge base's raw extracted text). Distinct from {@link AGENT_STATUS_TITLE_ACCESSING_KB} so a
974
+ * caller can tell an exact-match scan apart from ranked retrieval.
975
+ * @category AI
976
+ */
977
+ export declare const AGENT_STATUS_TITLE_GREPPING_KB = "Searching Knowledge Base Text";
978
+ /**
979
+ * Status update title broadcast when the agent queries a spreadsheet file callable.
980
+ * @category AI
981
+ */
982
+ export declare const AGENT_STATUS_TITLE_QUERYING_SPREADSHEET = "Querying Spreadsheet";
983
+ /**
984
+ * A status message from an AI agent operation.
985
+ * @category AI
986
+ */
987
+ export interface AiStatusMessage {
988
+ /** ID of the status update message. */
989
+ messageId: string;
990
+ /** The ID of the agent generating the status message. */
991
+ agentId?: AiAgentId;
992
+ /** An optional chat ID associated with the status message. */
993
+ chatId?: string;
994
+ /** The title or summary of the status message. */
995
+ title: string;
996
+ /** Markdown body content for the status update. */
997
+ body: string;
998
+ /** ID of the parent status update for nested display. */
999
+ parentStatusUpdateId?: string;
1000
+ /** The Job ID associated with the status message. */
1001
+ jobId: JobId;
1002
+ /** Optional tags providing additional metadata about the status. */
1003
+ tags?: Record<string, any>;
1004
+ }
1005
+ /**
1006
+ * `errorType` on a failed chat/ask job when the AI provider itself failed (a stall, timeout, or
1007
+ * unrecognized 5xx) rather than Squid or the caller's request.
1008
+ * @category AI
1009
+ */
1010
+ export declare const AI_PROVIDER_ERROR_TYPE = "AI_PROVIDER_ERROR";
1011
+ /** List of all chat history (memory) sources. */
1012
+ export declare const AI_CHAT_MESSAGE_SOURCE: readonly ["user", "ai"];
1013
+ /** Source of the chat history entry: either an AI response or a user. */
1014
+ export type AiChatMessageSource = (typeof AI_CHAT_MESSAGE_SOURCE)[number];
1015
+ /** A history entry for a chat. */
1016
+ export interface AiChatMessage {
1017
+ /** ID of the entry. Unique per agent. */
1018
+ id: string;
1019
+ /** Agent's application. */
1020
+ appId: AppId;
1021
+ /** The ID of the agent that owns the history. */
1022
+ agentId: AiAgentId;
1023
+ /** A memory (history) ID associated with the chat conversation. */
1024
+ memoryId: string;
1025
+ /** The source of the message: a user or an AI. */
1026
+ source: AiChatMessageSource;
1027
+ /** The text of the entry: a user's prompt or an AI-generated response. */
1028
+ message: string;
1029
+ /** Time the entry is created. Unix time millis. */
1030
+ timestamp: number;
1031
+ }
1032
+ /**
1033
+ * A single chunk of data returned from an AI search operation.
1034
+ * @category AI
1035
+ */
1036
+ export interface AiSearchResultChunk {
1037
+ /** The data content of the search result chunk. */
1038
+ data: string;
1039
+ /** Optional metadata associated with the chunk. */
1040
+ metadata?: AiContextMetadata;
1041
+ /** The relevance score of the chunk, indicating match quality. */
1042
+ score: number;
1043
+ }
1044
+ /**
1045
+ * Represents an AI agent's context entry with metadata and content.
1046
+ * @category AI
1047
+ */
1048
+ export interface AiAgentContext {
1049
+ /** The unique identifier of the context entry. */
1050
+ id: AiContextId;
1051
+ /** The date and time the context was created. */
1052
+ createdAt: Date;
1053
+ /** The date and time the context was last updated. */
1054
+ updatedAt: Date;
1055
+ /** The ID of the agent owning this context. */
1056
+ agentId: AiAgentId;
1057
+ /** The type of context (e.g., 'text' or 'file'). */
1058
+ type: AiKnowledgeBaseContextType;
1059
+ /** A title describing the context content. */
1060
+ title: string;
1061
+ /** The text content of the context. */
1062
+ text: string;
1063
+ /** Indicates whether the context is a preview; defaults to false. */
1064
+ preview: boolean;
1065
+ /** The size of the context content in bytes. */
1066
+ sizeBytes: number;
1067
+ /** Metadata associated with the context. */
1068
+ metadata: AiContextMetadata;
1069
+ }
1070
+ /**
1071
+ * @category AI
1072
+ */
1073
+ export type AgentContextRequest = TextContextRequest | FileContextRequest;
1074
+ /**
1075
+ * Base fields shared by all agent context requests.
1076
+ * @category AI
1077
+ */
1078
+ export interface BaseContextRequest {
1079
+ /** The unique identifier of the context item. */
1080
+ contextId: string;
1081
+ /** The type of the context content. */
1082
+ type: AiKnowledgeBaseContextType;
1083
+ /** Optional metadata associated with the context item. */
1084
+ metadata?: AiContextMetadata;
1085
+ }
1086
+ /**
1087
+ * Status of an individual context item after successfully upserting it.
1088
+ * @category AI
1089
+ */
1090
+ export interface BaseUpsertContextStatus {
1091
+ /** Whether the context upsert was successful, otherwise, what occurred. */
1092
+ status: 'success' | 'error';
1093
+ /** The unique identifier of the context item. */
1094
+ contextId: string;
1095
+ /** The name of the context item, typically the title or filename. */
1096
+ name: string;
1097
+ }
1098
+ /**
1099
+ * An image whose description failed during ingestion: the context is stored without that image's chunk.
1100
+ * @category AI
1101
+ */
1102
+ export interface ContextImageFailure {
1103
+ /** Zero-based index of the page carrying the image. */
1104
+ pageIndex: number;
1105
+ /** Extraction-assigned id of the image within the document. */
1106
+ imageId: string;
1107
+ /** Why describing the image failed. */
1108
+ errorMessage: string;
1109
+ }
1110
+ /**
1111
+ * Status of an individual context item after successfully upserting it.
1112
+ * @category AI
1113
+ */
1114
+ export interface UpsertContextStatusSuccess extends BaseUpsertContextStatus {
1115
+ /** Whether the context upsert was successful or got an error. */
1116
+ status: 'success';
1117
+ /**
1118
+ * Set when the context was stored and is fully searchable (vector/keyword), but was NOT graph-indexed
1119
+ * because the knowledge base is over its per-KB graph chunk cap. Only GraphRAG coverage is absent;
1120
+ * surfaced so bulk operations can report which contexts fell outside the graph.
1121
+ */
1122
+ graphIndexingSkipped?: boolean;
1123
+ /** First failed images (capped); absent when every image succeeded. `imageFailureCount` is the total. */
1124
+ imageFailures?: Array<ContextImageFailure>;
1125
+ /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
1126
+ imageFailureCount?: number;
1127
+ }
1128
+ /**
1129
+ * Names an upsert failure; `DUPLICATE_CONTENT` identifies existing content when contextId is omitted.
1130
+ * `EMBEDDING_FAILED`, `EXTRACTION_TIMED_OUT`, `PROVIDER_ACCESS_DENIED`, and `SOURCE_UNREACHABLE` may
1131
+ * succeed on retry. Document faults carry `retryable: false` because the same bytes fail again.
1132
+ * @category AI
1133
+ */
1134
+ 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';
1135
+ /**
1136
+ * The existing context a `DUPLICATE_CONTENT` rejection points at — where the byte-identical original
1137
+ * already lives.
1138
+ * @category AI
1139
+ */
1140
+ export interface UpsertContextDuplicateOf {
1141
+ /** The id of the already-stored context whose content is byte-identical to the rejected request. */
1142
+ contextId: string;
1143
+ /** The existing context's source reference (file name / URL), when it has one. */
1144
+ reference?: string;
1145
+ /** The existing context's `folderPath` metadata, when it was ingested with a folder path. */
1146
+ folderPath?: string;
1147
+ }
1148
+ /**
1149
+ * Status of an individual context item after it failed to upsert.
1150
+ *
1151
+ * Contains the error message for why the upsert failed.
1152
+ * @category AI
1153
+ */
1154
+ export interface UpsertContextStatusError extends BaseUpsertContextStatus {
1155
+ /** Whether the context upsert was successful or got an error. */
1156
+ status: 'error';
1157
+ /** Reason the upsert failed. */
1158
+ errorMessage: string;
1159
+ /** Machine-readable code for the failure, when one applies. */
1160
+ errorCode?: UpsertContextErrorCode;
1161
+ /**
1162
+ * Present only when the same bytes fail the same way again, so a caller must not retry the request
1163
+ * as-is. Absence means the failure may be transient.
1164
+ */
1165
+ retryable?: false;
1166
+ /**
1167
+ * The existing context this request duplicated, when `errorCode` is `DUPLICATE_CONTENT`. Lets a caller
1168
+ * point the user at where the original already lives (e.g. its folder) instead of only reporting the
1169
+ * rejection. `reference`/`folderPath` are present when the existing context carries them.
1170
+ */
1171
+ duplicateOf?: UpsertContextDuplicateOf;
1172
+ /** First failed images (capped) when every image failed and the document had no text; otherwise absent. */
1173
+ imageFailures?: Array<ContextImageFailure>;
1174
+ /** Total number of failed images, which exceeds `imageFailures.length` when the list was capped. */
1175
+ imageFailureCount?: number;
1176
+ }
1177
+ /**
1178
+ * Status of an individual context item after attempting to upsert it.
1179
+ * @category AI
1180
+ */
1181
+ export type UpsertContextStatus = UpsertContextStatusSuccess | UpsertContextStatusError;
1182
+ /**
1183
+ * Response structure for upserting context.
1184
+ * @category AI
1185
+ */
1186
+ export interface UpsertAgentContextResponse {
1187
+ /** Upsert failure that occurred for the items sent in the request. */
1188
+ failure?: UpsertContextStatusError;
1189
+ }
1190
+ /**
1191
+ * Response structure for upserting contexts.
1192
+ * @category AI
1193
+ */
1194
+ export interface UpsertAgentContextsResponse {
1195
+ /** List of the upsert failures that occurred for the items sent in the request. */
1196
+ failures: Array<UpsertContextStatusError>;
1197
+ }
1198
+ /**
1199
+ * Base options for upserting text content into the AI agent's context.
1200
+ * @category AI
1201
+ */
1202
+ export interface AiContextTextOptions extends BaseAiContextOptions {
1203
+ }
1204
+ /**
1205
+ * Base options for upserting file content into the AI agent's context.
1206
+ * @category AI
1207
+ */
1208
+ export interface AiContextFileOptions extends BaseAiContextOptions {
1209
+ }
1210
+ /**
1211
+ * Request structure for adding text-based context to an AI agent.
1212
+ * @category AI
1213
+ */
1214
+ export interface TextContextRequest extends BaseContextRequest {
1215
+ /** Specifies the context type as 'text'. */
1216
+ type: 'text';
1217
+ /** A title for the text context. */
1218
+ title: string;
1219
+ /** The text content to add to the context. */
1220
+ text: string;
1221
+ /** General options for how to process the text. */
1222
+ options?: AiContextTextOptions;
1223
+ }
1224
+ /**
1225
+ * Request structure for adding file-based context to an AI agent.
1226
+ * @category AI
1227
+ */
1228
+ export interface FileContextRequest extends BaseContextRequest {
1229
+ /** Specifies the context type as 'file'. */
1230
+ type: 'file';
1231
+ /**
1232
+ * Whether to extract images from the file, describe them with a vision model, and index those
1233
+ * descriptions alongside the text. Defaults to true — a document's charts, diagrams and scanned pages
1234
+ * carry content the text layer does not. Note that the text context request has no such option:
1235
+ * inline images in a text payload are extracted only for a knowledge-base text context, and default
1236
+ * to OFF there.
1237
+ */
1238
+ extractImages?: boolean;
1239
+ /** The minimum size for extracted images, if applicable. */
1240
+ imageMinSizePixels?: number;
1241
+ /** The AI model to use for extraction, if specified. */
1242
+ extractionModel?: AiChatModelSelection;
1243
+ /** General options for how to process the file. */
1244
+ options?: AiContextFileOptions;
1245
+ /** The preferred method for extracting data from the document. */
1246
+ preferredExtractionMethod?: DocumentExtractionMethod;
1247
+ /**
1248
+ * Whether Squid keeps or discards the original file.
1249
+ *
1250
+ * Keeping the original file allows reprocessing and the ability for the user to download it later.
1251
+ *
1252
+ * Defaults to false.
1253
+ */
1254
+ discardOriginalFile?: boolean;
1255
+ }
1256
+ /**
1257
+ * Base options for how to deal with the content being upserted.
1258
+ * @category AI
1259
+ */
1260
+ export type BaseAiContextOptions = {
1261
+ /** The type of RAG to use for the content. */
1262
+ ragType?: AiRagType;
1263
+ /** Amount of chunk overlap, in characters. */
1264
+ chunkOverlap?: number;
1265
+ };
1266
+ /**
1267
+ * @category AI
1268
+ */
1269
+ export type GuardrailKeysType = 'disableProfanity' | 'offTopicAnswers' | 'professionalTone' | 'disablePii';
1270
+ /**
1271
+ * Options for applying guardrails to AI responses to enforce specific constraints.
1272
+ * @category AI
1273
+ */
1274
+ export type GuardrailsOptions = {
1275
+ /** Disables profanity in the AI response if true; defaults to false. */
1276
+ disableProfanity?: boolean;
1277
+ /** Prevents off-topic answers if true; defaults to false. */
1278
+ offTopicAnswers?: boolean;
1279
+ /** Enforces a professional tone in the response if true; defaults to false. */
1280
+ professionalTone?: boolean;
1281
+ /** Disables inclusion of personally identifiable information if true; defaults to false. */
1282
+ disablePii?: boolean;
1283
+ /** A custom guardrail instruction, if specified. */
1284
+ custom?: string;
1285
+ };
1286
+ /**
1287
+ * PII kinds a prompt can be screened for. Each one is judged in context by the screening model, so
1288
+ * a value is classified by what the prompt says it is rather than by which format it happens to fit.
1289
+ * @category AI
1290
+ */
1291
+ export type AiPiiEntityType = 'email' | 'phoneNumber' | 'creditCard' | 'ssn' | 'iban' | 'passport';
1292
+ /** Entity kinds screened when {@link AiPiiOptions.entities} is omitted. */
1293
+ export declare const DEFAULT_PII_ENTITY_TYPES: ReadonlyArray<AiPiiEntityType>;
1294
+ /** Model that screens prompts unless overridden. Small and fast: it runs on every prompt. */
1295
+ export declare const DEFAULT_PII_CLASSIFIER_MODEL = "gpt-6-luna";
1296
+ /**
1297
+ * Rejects a prompt before it reaches the agent's model when it carries PII, so the prompt is never
1298
+ * sent to the model provider, never answered, and never written to chat memory.
1299
+ *
1300
+ * Screening is one {@link classifierModel} call per prompt, covering {@link entities} and
1301
+ * {@link customRules} together. Because a model does the reading rather than a pattern, a value is
1302
+ * judged by what the prompt says it is, and app-specific identifiers can be described in plain
1303
+ * language instead of expressed as a format.
1304
+ *
1305
+ * This is the inverse of {@link GuardrailsOptions.disablePii}, which asks the agent's own model not
1306
+ * to *emit* PII in its answer.
1307
+ * @category AI
1308
+ */
1309
+ export type AiPiiOptions = {
1310
+ /** `reject` refuses a prompt carrying PII; `off` (default) disables screening entirely. */
1311
+ onDetect: 'off' | 'reject';
1312
+ /** Entity kinds to screen for. Defaults to {@link DEFAULT_PII_ENTITY_TYPES}. */
1313
+ entities?: Array<AiPiiEntityType>;
1314
+ /** App-specific PII in plain language, e.g. `'internal case numbers like CASE-12345'`. */
1315
+ customRules?: Array<string>;
1316
+ /**
1317
+ * Model performing the screening. Defaults to {@link DEFAULT_PII_CLASSIFIER_MODEL}. Each attempt is
1318
+ * bounded at a minute, so an override has to answer within it.
1319
+ */
1320
+ classifierModel?: AiChatModelSelection;
1321
+ /** Literal values that never count as PII, e.g. a shared support address. */
1322
+ allowList?: Array<string>;
1323
+ };
1324
+ /**
1325
+ * Outcome of screening one prompt. On a detection the prompt is replaced by {@link redactedPrompt}
1326
+ * everywhere it would otherwise be stored, so the audit trail records that a request was refused
1327
+ * and why without restating the values that caused it.
1328
+ * @category AI
1329
+ */
1330
+ export type AiPiiScanResult = {
1331
+ detected: false;
1332
+ } | {
1333
+ detected: true;
1334
+ /** Entity kinds and custom-rule names that matched. Never the matched values. */
1335
+ matchedTypes: Array<string>;
1336
+ /** The prompt with every match replaced by a `[REDACTED:<type>]` placeholder. */
1337
+ redactedPrompt: string;
1338
+ };
1339
+ /**
1340
+ * Response structure for transcribing audio and asking an AI agent a question.
1341
+ * @category AI
1342
+ */
1343
+ export interface AiTranscribeAndAskResponse {
1344
+ /** The AI agent's response to the transcribed prompt. */
1345
+ responseString: string;
1346
+ /** The transcribed text from the audio input. */
1347
+ transcribedPrompt: string;
1348
+ /** The annotations associated with the AI response, if any. */
1349
+ annotations?: Record<string, AiAnnotation>;
1350
+ }
1351
+ /** Per application AI settings. */
1352
+ export interface ApplicationAiSettings {
1353
+ /** Maps AI provider name to API key secret name that must be used for any request made by the application. */
1354
+ apiKeys: Partial<Record<AiProviderType, SecretKey>>;
1355
+ }
1356
+ /**
1357
+ * Options for user-provided LLM models.
1358
+ * @category AI
1359
+ */
1360
+ export interface UserAiChatOptions extends BaseAiChatOptions {
1361
+ /** LLM Model to use for the chat query. */
1362
+ model: UserAiChatModelName;
1363
+ }
1364
+ /**
1365
+ * Response structure for asking a user LLM a question.
1366
+ * @category AI
1367
+ */
1368
+ export interface UserAiAskResponse {
1369
+ /** The response from the AI agent. */
1370
+ response?: string;
1371
+ /** Prompt tokens used by the request, including any the prompt cache served. */
1372
+ inputTokens?: number;
1373
+ /** The number of output tokens generated by the AI agent. */
1374
+ outputTokens?: number;
1375
+ /** Cached input tokens read from the prompt cache. Only set by providers that report it (e.g. claude-code). */
1376
+ cacheReadInputTokens?: number;
1377
+ /** Input tokens written to the prompt cache. Only set by providers that report it (e.g. claude-code). */
1378
+ cacheWriteInputTokens?: number;
1379
+ /** Total request cost in USD as reported by the provider. Only set by providers that compute it (e.g. claude-code). */
1380
+ totalCostUsd?: number;
1381
+ /**
1382
+ * True when the run succeeded but persisting its workspace (push) failed, so the working-directory
1383
+ * changes made during this ask may not survive to the next one. Only ever set for workspace-backed CLI
1384
+ * agents; absent otherwise.
1385
+ */
1386
+ workspacePushFailed?: boolean;
1387
+ }
1388
+ /** Represents an annotation in the AI response. */
1389
+ export type AiAnnotation = AiFileAnnotation;
1390
+ /** Represents an annotation for a file in the AI response. */
1391
+ export interface AiFileAnnotation {
1392
+ /** The type of the annotation, always 'file'. */
1393
+ type: 'file';
1394
+ /** The AI file with the URL to the file */
1395
+ aiFileUrl: AiFileUrl;
1396
+ }
1397
+ /**
1398
+ * Context for an AI session
1399
+ */
1400
+ export type AiSessionContext = {
1401
+ /** The ID of the client initiating the session. */
1402
+ clientId: string;
1403
+ /** The ID of the AI agent involved in the session. */
1404
+ agentId: string;
1405
+ /** The ID of the job associated with the session. */
1406
+ jobId: JobId;
1407
+ /**
1408
+ * The conversation this call belongs to, as the caller named it (`memoryOptions.memoryId`).
1409
+ * Stable across the turns of one chat and different for two chats, including
1410
+ * two chats of the same client, which `clientId` is not: a client id belongs to a connection, and
1411
+ * one connection can carry several conversations. Not the id chat history is keyed by — that one
1412
+ * falls back to `clientId` — so do not read it as one. Absent for callers that named no conversation
1413
+ * (a direct function call, security rules).
1414
+ */
1415
+ conversationId?: string;
1416
+ /**
1417
+ * ID of the status update that triggered this session (e.g. the agent's "Calling AI Function"
1418
+ * event). Status updates emitted on behalf of this session nest under it in the status feed.
1419
+ */
1420
+ parentStatusUpdateId?: string;
1421
+ /**
1422
+ * Whether the invoking agent has audit logging enabled. Sub-agents working on behalf of this
1423
+ * session gate their own audit-log writes on it, keeping one job's audit trail consistent.
1424
+ */
1425
+ auditLog?: boolean;
1426
+ /**
1427
+ * The chat timeout (in milliseconds) the root chat request explicitly set. Present only when
1428
+ * the root request passed `timeoutMs`. Nested AI operations (e.g. AI-query stages spawned by a
1429
+ * tool call) budget against it so a long-running parent chat is not silently capped by the
1430
+ * nested defaults; explicitly configured per-stage `aiOptions.timeoutMs` is more specific and
1431
+ * takes precedence over it.
1432
+ */
1433
+ timeoutMs?: number;
1434
+ };
1435
+ /**
1436
+ * API request to delete an AI agent
1437
+ * @category AI
1438
+ */
1439
+ export interface DeleteAgentRequest {
1440
+ /** The ID of the agent to delete */
1441
+ agentId: string;
1442
+ }
1443
+ /**
1444
+ * API response from agent ask methods
1445
+ * @category AI
1446
+ */
1447
+ export interface AiAskResponse {
1448
+ /** The response string from the agent */
1449
+ responseString: string;
1450
+ /** Optional annotations (e.g., file references) in the response */
1451
+ annotations?: Record<string, AiAnnotation>;
1452
+ /** Set when `model` was an {@link AiModelRoutingOptions}: which model answered and what routing cost. */
1453
+ routing?: AiModelRoutingResult;
1454
+ }
1455
+ /**
1456
+ * API request to create speech from text
1457
+ * @category AI
1458
+ */
1459
+ export interface AiAudioCreateSpeechRequest {
1460
+ /** The text input to convert to speech */
1461
+ input: string;
1462
+ /** Options for speech generation */
1463
+ options: AiAudioCreateSpeechOptions;
1464
+ }
1465
+ /**
1466
+ * API request to generate an image
1467
+ * @category AI
1468
+ */
1469
+ export interface AiGenerateImageRequest {
1470
+ /** The prompt describing the image to generate */
1471
+ prompt: string;
1472
+ /** Options for image generation */
1473
+ options?: AiGenerateImageOptions;
1474
+ }
1475
+ /**
1476
+ * Revision action types for agent history tracking.
1477
+ * @category AI
1478
+ */
1479
+ export type AiAgentRevisionAction = 'created' | 'updated' | 'deleted';
1480
+ /**
1481
+ * Represents a single agent revision entry.
1482
+ * @category AI
1483
+ */
1484
+ export interface AiAgentRevision {
1485
+ /** The ID of the agent this revision belongs to. */
1486
+ agentId: AiAgentId;
1487
+ /** The revision number, incremented for each change to the agent. */
1488
+ revisionNumber: number;
1489
+ /** The action that triggered this revision (created, updated, or deleted). */
1490
+ action: AiAgentRevisionAction;
1491
+ /** Timestamp when this revision was created. */
1492
+ createdAt: Date;
1493
+ /** Snapshot of the agent data at the time of the revision. */
1494
+ agentSnapshot: AiAgent;
1495
+ }
1496
+ /**
1497
+ * Request to list all revisions for an agent.
1498
+ * @category AI
1499
+ */
1500
+ export interface ListAgentRevisionsRequest {
1501
+ /** The ID of the agent to list revisions for. */
1502
+ agentId: AiAgentId;
1503
+ }
1504
+ /**
1505
+ * Response containing the list of agent revisions.
1506
+ * @category AI
1507
+ */
1508
+ export interface ListAgentRevisionsResponse {
1509
+ /** The list of revisions for the agent, sorted by revision number descending. */
1510
+ revisions: Array<AiAgentRevision>;
1511
+ }
1512
+ /**
1513
+ * Request to get a specific agent revision.
1514
+ * @category AI
1515
+ */
1516
+ export interface GetAgentRevisionRequest {
1517
+ /** The ID of the agent to get the revision for. */
1518
+ agentId: AiAgentId;
1519
+ /** The revision number to retrieve. */
1520
+ revisionNumber: number;
1521
+ }
1522
+ /**
1523
+ * Response containing a specific agent revision.
1524
+ * @category AI
1525
+ */
1526
+ export interface GetAgentRevisionResponse {
1527
+ /** The requested revision, or undefined if not found. */
1528
+ revision: AiAgentRevision | undefined;
1529
+ }
1530
+ /**
1531
+ * Request to restore an agent to a specific revision.
1532
+ * @category AI
1533
+ */
1534
+ export interface RestoreAgentRevisionRequest {
1535
+ /** The ID of the agent to restore. */
1536
+ agentId: AiAgentId;
1537
+ /** The revision number to restore the agent to. */
1538
+ revisionNumber: number;
1539
+ }
1540
+ /**
1541
+ * Request to delete a specific agent revision.
1542
+ * @category AI
1543
+ */
1544
+ export interface DeleteAgentRevisionRequest {
1545
+ /** The ID of the agent whose revision should be deleted. */
1546
+ agentId: AiAgentId;
1547
+ /** The revision number to delete. */
1548
+ revisionNumber: number;
1549
+ }
1550
+ /**
1551
+ * Options for the agent builder.
1552
+ * @category AI
1553
+ */
1554
+ export interface BuildAgentOptions {
1555
+ /** Whether the caller has permission to create or update integrations. Defaults to false. */
1556
+ canManageIntegrations?: boolean;
1557
+ }
1558
+ /**
1559
+ * Response containing the list of AI agents in an application.
1560
+ * @category AI
1561
+ */
1562
+ export interface ListAgentsResponse {
1563
+ /** All AI agents defined for the application. */
1564
+ agents: Array<AiAgent>;
1565
+ }
1566
+ /**
1567
+ * Request options for listing the chat models available to an application.
1568
+ * @category AI
1569
+ */
1570
+ export interface ListChatModelsRequest {
1571
+ /**
1572
+ * When true, deprecated vendor models (those with `replacedBy`) are included.
1573
+ * Defaults to false (only active models are returned).
1574
+ */
1575
+ includeDeprecated?: boolean;
1576
+ }
1577
+ /**
1578
+ * Response containing the list of chat models available to an application.
1579
+ * Includes both Squid-provided vendor models and any custom integration models.
1580
+ * Vendor models carry a human-readable `description`. Deprecated vendor models are
1581
+ * included only when requested via `includeDeprecated` and are marked with `replacedBy`.
1582
+ * @category AI
1583
+ */
1584
+ export interface ListChatModelsResponse {
1585
+ /** All chat models available to the application. */
1586
+ models: Array<ModelIdSpec>;
1587
+ }
1588
+ /**
1589
+ * Request options for listing the embedding models a new knowledge base can be created on.
1590
+ * @category AI
1591
+ */
1592
+ export interface ListEmbeddingModelsRequest {
1593
+ /**
1594
+ * When true, deprecated vendor models (those with `replacedBy`) are included.
1595
+ * Defaults to false (only active models are returned).
1596
+ */
1597
+ includeDeprecated?: boolean;
1598
+ }
1599
+ /**
1600
+ * Response containing the embedding models a new knowledge base can be created on: Squid-provided
1601
+ * vendor models and the application's custom integration models. Exactly one entry carries `isDefault`.
1602
+ * Deprecated vendor models are included only when requested via `includeDeprecated` and are marked
1603
+ * with `replacedBy`; an existing knowledge base keeps its model regardless.
1604
+ * @category AI
1605
+ */
1606
+ export interface ListEmbeddingModelsResponse {
1607
+ /** All embedding models available to the application. */
1608
+ models: Array<EmbeddingModelIdSpec>;
1609
+ }