@squidcloud/client 1.0.483 → 1.0.485

package/dist/internal-common/src/types/ai-agent.types.d.ts

@@ -0,0 +1,253 @@
+import { AgentContextRequest, AiAgent, AiAgentContext, AiAgentMcpServerConfig, AiAnnotation, AiAudioCreateSpeechOptions, AiChatMessage, AiChatOptions, AiGenerateImageOptions, AllAiAgentChatOptions, ApplicationAiSettings, BuildAgentOptions } from '../public-types/ai-agent.public-types';
+import { AiProviderType, ModelIdSpec } from '../public-types/ai-common.public-types';
+import { AiContextMetadata, AiContextMetadataFilter } from '../public-types/ai-knowledge-base.public-types';
+import { AiAgentId, AiKnowledgeBaseId, AppId, ClientRequestId } from '../public-types/communication.public-types';
+import { JobId } from '../public-types/job.public-types';
+import { SecretKey } from '../public-types/secret.public-types';
+/** Specification for an AI model, defining its operational parameters. */
+export type AiModelSpec = {
+    /** Maximum tokens the model can generate in a single response. */
+    maxOutputTokens: number;
+    /** Total context window size: input (aka prompt) + output (aka completion) tokens combined. */
+    contextWindowTokens: number;
+};
+export interface AiChatRequest {
+    agentId: AiAgentId;
+    clientRequestId: ClientRequestId;
+    prompt?: string;
+    options?: AllAiAgentChatOptions;
+    jobId: JobId;
+}
+export interface AiAskRequest {
+    agentId: AiAgentId;
+    prompt?: string;
+    options?: AllAiAgentChatOptions;
+    jobId: JobId;
+}
+export interface AiGenerateImageRequest {
+    prompt: string;
+    options: AiGenerateImageOptions;
+}
+export interface AiAskQuestionInternalRequest {
+    appId: AppId;
+    prompt: string;
+    options: AiChatOptions;
+    /**
+     * API key resolution mode (see `AiProviderFactory.getChatProviderForModel`). 'system' is
+     * required to resolve system-internal models (e.g. the 'openai-compatible' registry models)
+     * and makes the call billable to Squid, not the app. Defaults to 'auto'. The endpoint is
+     * `@Internal()`, so only internal-key callers can set this.
+     */
+    keyType?: 'auto' | 'system';
+}
+export interface AiAskQuestionInternalResponse {
+    answer: string;
+}
+export interface GetSharedAgentsInternalRequest {
+    organizationId: string;
+}
+export interface GetSharedAgentsInternalResponse {
+    sharedAgents: Array<{
+        agentId: AiAgentId;
+        appId: AppId;
+    }>;
+}
+export interface ClearSharedAgentsForOrgInternalRequest {
+    organizationId: string;
+}
+export interface AiContextSizeRequest {
+    appId: AppId;
+    agentId: AiAgentId;
+}
+export interface AiContextSizeResponse {
+    sizeBytes: number;
+}
+export interface AiAskResponse {
+    responseString: string;
+    annotations?: Record<string, AiAnnotation>;
+}
+export interface AiAskWithVoiceResponse {
+    responseString: string;
+    voiceResponse: AiAudioCreateSpeechResponse;
+    annotations?: Record<string, AiAnnotation>;
+}
+export interface AiTranscribeAndAskWithVoiceResponse {
+    transcribedPrompt: string;
+    responseString: string;
+    voiceResponse: AiAudioCreateSpeechResponse;
+    annotations?: Record<string, AiAnnotation>;
+}
+export interface AiTranscribeAndChatResponse {
+    transcribedPrompt: string;
+}
+export interface AiAudioCreateSpeechResponse {
+    mimeType: string;
+    extension: string;
+    base64File: string;
+}
+export interface AiAudioCreateSpeechRequest {
+    input: string;
+    options: AiAudioCreateSpeechOptions;
+}
+export interface GetAgentRequest {
+    agentId: AiAgentId;
+}
+export interface GetAgentResponse {
+    agent: AiAgent | undefined;
+}
+export interface GetAgentContextRequest {
+    agentId: AiAgentId;
+    contextId: string;
+}
+export interface ConnectAgentKnowledgeBaseRequest {
+    agentId: AiAgentId;
+    knowledgeBaseId: AiKnowledgeBaseId;
+    description: string;
+}
+export interface DisconnectAgentKnowledgeBaseRequest {
+    agentId: AiAgentId;
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+export interface DeleteAgentRequest {
+    agentId: AiAgentId;
+}
+export interface UnshareAgentRequest {
+    agentId: AiAgentId;
+}
+export interface SetAgentOptionInPathRequest {
+    agentId: AiAgentId;
+    path: string;
+    value: unknown;
+}
+export interface AddConnectedIntegrationRequest {
+    agentId: AiAgentId;
+    integrationId: string;
+    integrationType: string;
+    description: string;
+}
+export interface AddConnectedAgentRequest {
+    agentId: AiAgentId;
+    connectedAgentId: string;
+    description: string;
+}
+export interface AddConnectedKnowledgeBaseRequest {
+    agentId: AiAgentId;
+    knowledgeBaseId: string;
+    description: string;
+    /** Mirrors {@link AiConnectedKnowledgeBaseMetadata.includeMetadata}; forwarded so this atomic API honors it. */
+    includeMetadata?: boolean;
+}
+export interface AddFunctionRequest {
+    agentId: AiAgentId;
+    functionId: string;
+}
+export interface RemoveConnectedAgentRequest {
+    agentId: AiAgentId;
+    connectedAgentId: string;
+}
+export interface RemoveConnectedIntegrationRequest {
+    agentId: AiAgentId;
+    integrationId: string;
+}
+export interface RemoveConnectedKnowledgeBaseRequest {
+    agentId: AiAgentId;
+    knowledgeBaseId: string;
+}
+export interface RemoveFunctionRequest {
+    agentId: AiAgentId;
+    functionId: string;
+}
+export interface SetAgentDescriptionRequest {
+    agentId: AiAgentId;
+    description: string;
+}
+export interface SetAgentMcpServerRequest {
+    agentId: AiAgentId;
+    mcpServer: AiAgentMcpServerConfig;
+}
+export interface ListAgentContextsRequest {
+    agentId: AiAgentId;
+}
+export interface ListAgentContextsResponse {
+    contexts: Array<AiAgentContext>;
+}
+export interface DeleteAgentContextsRequest {
+    agentId: AiAgentId;
+    contextIds: Array<string>;
+}
+export interface UpsertAgentContextsRequest {
+    agentId: AiAgentId;
+    contextRequests: Array<AgentContextRequest>;
+}
+export interface UpsertAgentCustomGuardrailsRequest {
+    agentId: AiAgentId;
+    customGuardrail: string;
+}
+export interface DeleteAgentCustomGuardrailsRequest {
+    agentId: AiAgentId;
+}
+export interface ListAgentsResponse {
+    agents: Array<AiAgent>;
+}
+export interface GetApplicationAiSettingsResponse {
+    settings: ApplicationAiSettings;
+}
+export interface GetApplicationAiSettingsResponse {
+    settings: ApplicationAiSettings;
+}
+export interface SetApplicationAiSettingsRequest {
+    settings: ApplicationAiSettings;
+}
+export interface SetAiProviderApiKeySecretRequest {
+    providerType: AiProviderType;
+    secretKey: SecretKey | undefined;
+}
+export interface SetAiProviderApiKeySecretResponse {
+    settings: ApplicationAiSettings;
+}
+export interface ListChatModelsResponse {
+    models: ModelIdSpec[];
+}
+export interface RegenerateAgentApiKeyRequest {
+    agentId: AiAgentId;
+}
+export interface GetAgentApiKeyRequest {
+    agentId: AiAgentId;
+}
+export declare function validateAiContextMetadata(metadata: AiContextMetadata): void;
+export declare function validateAiContextMetadataFilter(filter: AiContextMetadataFilter): void;
+export declare const METADATA_SERVICE_FUNCTION_NAME = "default:metadata";
+export interface GetChatHistoryRequest {
+    agentId: AiAgentId;
+    memoryId: string;
+}
+export interface GetChatHistoryResponse {
+    messages: Array<AiChatMessage>;
+}
+export interface ProvideAgentFeedbackRequest {
+    agentId: string;
+    feedback: string;
+}
+export interface BuildAgentRequest {
+    agentId: string;
+    request: string;
+    memoryId?: string;
+    options?: BuildAgentOptions;
+}
+export interface UploadAiFileRequest {
+    /** AI provider to upload file to. */
+    provider: AiProviderType;
+    /** Optional expiration time in seconds. If provided, file will be registered for automatic cleanup. */
+    expirationInSeconds?: number;
+}
+export interface UploadAiFileResponse {
+    fileId: string;
+}
+export interface DeleteAiFileRequest {
+    fileId: string;
+    /** AI provider that owns the file. */
+    provider: AiProviderType;
+}
+export interface DeleteAiFileResponse {
+    deleted: boolean;
+}

package/dist/internal-common/src/types/ai-knowledge-base.types.d.ts

@@ -0,0 +1,306 @@
+import { AiEmbeddingsModelWithOptionalFields, AiKnowledgeBase, AiKnowledgeBaseChatOptions, AiKnowledgeBaseContext, AiKnowledgeBaseContextRequest, AiKnowledgeBaseGraphContext, AiKnowledgeBaseGraphSearchOptions, AiKnowledgeBaseSearchResultChunk } from '../public-types/ai-knowledge-base.public-types';
+import { AiContextId, AiKnowledgeBaseId, AppId } from '../public-types/communication.public-types';
+import { DocumentExtractionMethod } from '../public-types/extraction.public-types';
+/**
+ * Internal (eval-harness-only) extension of the public graph search options. `graphOnly` returns just the
+ * graph channel's chunks (measures the graph's marginal recall) instead of the public `fused` behavior;
+ * it is not exposed in public-types because production callers always fuse. The graph channel accepts
+ * this shape at runtime, so eval specs cast their options to it. Themes-level "global" answering is NOT a
+ * search mode — it moved to the `globalSummary` op of `queryKnowledgeGraph`.
+ * @category AI
+ */
+export interface AiKnowledgeBaseGraphSearchOptionsInternal extends AiKnowledgeBaseGraphSearchOptions {
+    /** Internal/eval-only: `'graphOnly'` returns only the graph channel; `'fused'` (default) RRF-merges with hybrid. */
+    mode?: 'graphOnly' | 'fused';
+}
+/**
+ * Request structure for getting an AiKnowledgeBase
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseRequest {
+    /** The id of the app */
+    appId: AppId;
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+/**
+ * Request structure for getting all AiKnowledgeBases
+ * @category AI
+ */
+export interface GetAiKnowledgeBasesRequest {
+    /** The id of the app */
+    appId: AppId;
+}
+/**
+ * Response structure for getting an AiKnowledgeBase
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseResponse {
+    /** The resulting AiKnowledgeBase, if it is found */
+    knowledgeBase: AiKnowledgeBase | undefined;
+}
+/**
+ * Request structure for deleting an AiKnowledgeBase
+ * @category AI
+ */
+export interface DeleteAiKnowledgeBaseRequest {
+    /** The id of the AiKnowledgeBase */
+    id: string;
+}
+/**
+ * Request structure for upserting an AiKnowledgeBase
+ * @category AI
+ */
+export interface UpsertAiKnowledgeBaseRequest {
+    /** The AiKnowledgeBase to upsert */
+    knowledgeBase: Omit<AiEmbeddingsModelWithOptionalFields, 'appId' | 'updatedAt'>;
+}
+/**
+ * Response structure for listing AiKnowledgeBases
+ * @category AI
+ */
+export interface ListAiKnowledgeBasesResponse {
+    /** The list of AiKnowledgeBases */
+    knowledgeBases: Array<AiKnowledgeBase>;
+}
+/**
+ * Request structure for listing AiKnowledgeBaseContexts
+ * @category AI
+ * @deprecated Fetches every context in one call with no pagination — expensive for large knowledge
+ * bases. Use {@link ListAiKnowledgeBaseContextsPageRequest} instead.
+ */
+export interface ListAiKnowledgeBaseContextsRequest {
+    /** The id of the AiKnowledgeBase */
+    id: string;
+    /** The number of characters after which text is truncated. Optional */
+    truncateTextAfter?: number;
+}
+/**
+ * Response structure to list AiKnowledgeBaseContexts
+ * @category AI
+ * @deprecated See {@link ListAiKnowledgeBaseContextsRequest}.
+ */
+export interface ListAiKnowledgeBaseContextsResponse {
+    /** The list of AiKnowledgeBaseContexts */
+    contexts: Array<AiKnowledgeBaseContext>;
+}
+/**
+ * Response structure to list contextids for an AiKnowledgeBase
+ * @category AI
+ */
+export interface ListAiKnowledgeBaseContextIdsResponse {
+    /** The list of AiContextIds */
+    contextIds: Array<AiContextId>;
+}
+/**
+ * Request structure for deleting AiKnowledgeBaseContexts
+ * @category AI
+ */
+export interface DeleteAiKnowledgeBaseContextsRequest {
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: string;
+    /** An array of AiKnowledgeBaseContext ids */
+    contextIds: Array<string>;
+}
+/**
+ * Request structure for getting an AiKnowledgeBaseContext
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseContextRequest {
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: string;
+    /** The id of the AiKnowledgeBaseContext */
+    contextId: string;
+}
+/**
+ * Request structure for getting a page of AiKnowledgeBaseContexts
+ * for a given knowledge base
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseContextsRequest {
+    /** The id of the app */
+    appId: AppId;
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** The number of characters after which text is truncated. Optional */
+    truncateTextAfter?: number;
+    /** The number of contexts to skip, for pagination. Optional */
+    offset?: number;
+    /** The maximum number of contexts to return, for pagination. Optional */
+    limit?: number;
+    /** Case-insensitive substring search across id/title only. Optional */
+    search?: string;
+}
+/**
+ * Response structure for getting a page of AiKnowledgeBaseContexts for a given knowledge base
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseContextsResponse {
+    /** The requested page of AiKnowledgeBaseContexts */
+    contexts: Array<AiKnowledgeBaseContext>;
+    /** The total number of contexts in the AiKnowledgeBase, ignoring offset/limit */
+    totalCount: number;
+}
+/**
+ * Response structure for getting an AiKnowledgeBaseContext
+ * @category AI
+ */
+export interface GetAiKnowledgeBaseContextResponse {
+    /** The resulting AiKnowledgeBaseContext, if it is found */
+    context: AiKnowledgeBaseContext | undefined;
+}
+/**
+ * Request structure for upserting context for an AiKnowledgeBase
+ * @category AI
+ */
+export interface UpsertAiKnowledgeBaseContextsRequest {
+    /** The id of the AiKnowledgeBase */
+    knowledgeBaseId: string;
+    /** The AiKnowledgeBaseContext data, which could be a file or text */
+    contextRequests: Array<AiKnowledgeBaseContextRequest>;
+    /** The job ID to use for the async upsert job */
+    jobId: string;
+}
+/**
+ * Response structure for searching an AiKnowledgeBase
+ * @category AI
+ */
+export interface AiKnowledgeBaseSearchResponse {
+    /** Array of result chunks from the search */
+    chunks: Array<AiKnowledgeBaseSearchResultChunk>;
+    /** Traversed subgraph for a `searchMode:'graph'` query with `includeGraphContext`; absent otherwise. */
+    graphContext?: AiKnowledgeBaseGraphContext;
+}
+export type { ExploreKnowledgeBaseGraphRequest, ExploreKnowledgeBaseGraphResponse, GetKnowledgeBaseGraphStatusRequest, GetKnowledgeBaseGraphStatusResponse, KnowledgeBaseGraphEdge, KnowledgeBaseGraphFacetStatus, KnowledgeBaseGraphModelUsage, KnowledgeBaseGraphNode, KnowledgeBaseGraphQueryConcepts, KnowledgeBaseGraphQueryDoc, KnowledgeBaseGraphQueryGlobalSummary, KnowledgeBaseGraphQueryMatch, KnowledgeBaseGraphQueryOp, KnowledgeBaseGraphQueryPath, KnowledgeBaseGraphQuerySubtreeNode, KnowledgeBaseGraphRebuildMode, KnowledgeBaseGraphTopic, KnowledgeBaseGraphTopicEdge, KnowledgeBaseGraphUsage, QueryKnowledgeBaseGraphRequest, QueryKnowledgeBaseGraphResponse, RebuildKnowledgeBaseGraphRequest, } from '../public-types/ai-knowledge-base.public-types';
+/**
+ * Request structure for getting the size of context
+ * for an AiKnowledgeBase
+ * @category AI
+ */
+export interface AiKnowledgeBaseContextSizeRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+/**
+ * Request structure for the internal test-only route that arms the next `count` grep scans of a
+ * knowledge base to fail at their `maxTimeMS` deadline.
+ */
+export interface AiKnowledgeBaseFailNextGrepScansRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** How many upcoming scans fail; a non-positive value disarms. */
+    count: number;
+}
+/**
+ * Request structure for identifying a knowledge base to reimport the context files (when possible).
+ */
+export interface AiKnowledgeBaseReimportAllFilesRequest {
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+}
+/**
+ * Request structure for identifying a knowledge base to reimport the context files (when possible).
+ */
+export interface AiKnowledgeBaseReimportFilesRequest {
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** The ids of the AiKnowledgeBaseContexts to reimport */
+    contextIds: Array<string>;
+}
+/** Longest context batch one `backfillFulltext` call accepts; larger work-lists are split by the caller. */
+export declare const BACKFILL_FULLTEXT_MAX_CONTEXTS_PER_CALL = 20;
+/**
+ * Request structure for rebuilding the stored raw text (`kb_fulltext`) of existing contexts from their
+ * stored source files, without re-ingesting them — no chunk, embedding or graph writes. This is how
+ * contexts ingested before literal search existed become greppable.
+ */
+export interface AiKnowledgeBaseBackfillFulltextRequest {
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /**
+     * The ids of the contexts to backfill, at most {@link BACKFILL_FULLTEXT_MAX_CONTEXTS_PER_CALL} per
+     * call. Each context's stored text is fully replaced, so re-running a context is safe.
+     */
+    contextIds: Array<AiContextId>;
+    /**
+     * The extraction method for file contexts. Defaults to the server's regular document extraction
+     * default (OCR when configured), which reproduces the text the ingest pipeline indexed — including
+     * scanned pages. `legacy` extracts in-process without any external model call, but yields nothing for
+     * scanned pages, so a caller choosing it must compare the stored part counts against expectations.
+     */
+    extractionMethod?: DocumentExtractionMethod;
+    /**
+     * A context that already has stored text is SKIPPED unless this is true. The backfill rebuilds
+     * literal text only, while ingest also stores image/OCR-description parts — so replacing a context
+     * that ingest populated would silently delete its description text from the literal index. Set this
+     * only to deliberately re-extract contexts this backfill itself populated (e.g. retrying a thin
+     * `legacy` yield with OCR).
+     */
+    overwrite?: boolean;
+}
+/**
+ * Response structure for a `backfillFulltext` call: one status per requested context, in request order.
+ */
+export interface AiKnowledgeBaseBackfillFulltextResponse {
+    statuses: Array<AiKnowledgeBaseBackfillFulltextStatus>;
+}
+/**
+ * Outcome of backfilling the raw text of one context.
+ */
+export interface AiKnowledgeBaseBackfillFulltextStatus {
+    contextId: AiContextId;
+    /** `skipped` means the context already has stored text and `overwrite` was not set; nothing changed. */
+    status: 'success' | 'error' | 'skipped';
+    /**
+     * How many parts (pages/sheets) were stored, on success. Zero means extraction yielded no text at
+     * all — for a `legacy` run over a scanned document that is the expected signal to retry with OCR.
+     */
+    storedPartCount?: number;
+    errorMessage?: string;
+}
+/**
+ * Response structure for getting size of context
+ * @category AI
+ */
+export interface AiKnowledgeBaseContextSizeResponse {
+    /** Size of context bytes, as a number */
+    sizeBytes: number;
+}
+/**
+ * Request structure for getting the values vector of
+ * a specific context
+ *
+ * @category AI
+ */
+export interface AiKnowledgeBaseValueVectorRequest {
+    /** The ID of the App */
+    appId: AppId;
+    /** The ID of the AIKnowledgeBase */
+    knowledgeBaseId: AiKnowledgeBaseId;
+    /** The ID of the context */
+    contextId: AiContextId;
+}
+/**
+ * Response structure for getting values vector of a
+ * specific context
+ * @category AI
+ */
+export interface AiKnowledgeBaseValueVectorResponse {
+    /** The vector */
+    vector: number[];
+}
+export interface AiKnowledgeBaseChatRequest {
+    knowledgeBaseId: AiKnowledgeBaseId;
+    prompt?: string;
+    options?: AiKnowledgeBaseChatOptions;
+}
+/** Emitted to the console queue when a knowledge base or its contexts change. */
+export interface KbChangeEvent {
+    appId: AppId;
+    knowledgeBaseId: AiKnowledgeBaseId;
+    changeType: 'kb' | 'context';
+}

package/dist/internal-common/src/types/ai-matchmaking.types.d.ts

@@ -0,0 +1,19 @@
+import { MmEntity, MmMatchMaker } from '../public-types/ai-matchmaking.public-types';
+/**
+ * Internal-only matchmaking request shapes. Every other request/response of the matchmaking wire
+ * contract is declared in `ai-matchmaking.public-types` and imported directly from there.
+ */
+export interface MmCreateMatchMakerRequest {
+    matchMaker: MmMatchMaker;
+}
+export interface MmGetMatchMakerRequest {
+    matchMakerId: string;
+}
+export interface MmInsertEntityRequest {
+    matchMakerId: string;
+    entity: MmEntity;
+}
+export interface MmGetEntityRequest {
+    matchMakerId: string;
+    entityId: string;
+}

package/dist/internal-common/src/types/backend-function.types.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal-common/src/types/communication.types.d.ts

@@ -0,0 +1 @@
+export type ChatId = string;

package/dist/internal-common/src/types/document.types.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal-common/src/types/file.types.d.ts

@@ -0,0 +1,6 @@
+export interface Base64File {
+    filename: string;
+    mimetype: string;
+    base64: string;
+    __isSquidBase64File__: true;
+}

package/dist/internal-common/src/types/headers.types.d.ts

@@ -0,0 +1,41 @@
+/** HTTP header names used by Squid for request metadata. */
+export declare const SquidHeaders: {
+    /** Correlates logs and spans across distributed calls. */
+    readonly TRACE_ID: "x-squid-traceid";
+    /** Shared secret header for internal authentication. */
+    readonly SECRET: "x-squid-secret";
+    /** API key provided by the calling application. */
+    readonly APP_API_KEY: "x-app-api-key";
+    /** Unique identifier of the client application. */
+    readonly APP_ID: "x-squid-appid";
+    /** Unique identifier of the end user or service client. */
+    readonly CLIENT_ID: "x-squid-clientid";
+    /** Version string of the Squid client library. */
+    readonly CLIENT_VERSION: "x-squid-client-version";
+    /** Originating IP address of the request. */
+    readonly SOURCE_IP: "x-squid-source-ip";
+    /**
+     * Response-only: IP of the tenant pod that served the request, i.e. the address to reach it at
+     * again. Core records it to route subsequent affinity-keyed calls to the same pod. Absent when the
+     * pod does not know its own IP.
+     */
+    readonly POD_IP: "x-squid-pod-ip";
+    /**
+     * Response-only: identity of the tenant process that served the request. Distinct from
+     * {@link POD_IP}, which is an address and is reused: Kubernetes hands the IP of a deleted pod to a
+     * new one, so only this value tells core whether it is still talking to the same instance.
+     */
+    readonly INSTANCE_ID: "x-squid-instance-id";
+    /**
+     * Request-only: the {@link INSTANCE_ID} core believes it is calling, sent when routing directly to a
+     * pinned pod instead of through the tenant service. The receiving instance refuses the request when
+     * the value is not its own — the pod at that address may have been replaced, possibly by a pod of a
+     * different application.
+     */
+    readonly EXPECTED_INSTANCE_ID: "x-squid-expected-instance-id";
+    /**
+     * Response-only: key of the tenant worker that served the request, reported separately from
+     * {@link POD_IP} so core alone decides whether to pin at pod or at worker granularity.
+     */
+    readonly WORKER_KEY: "x-squid-worker-key";
+};