Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import yaml from 'js-yaml';
import { Types } from 'mongoose';
import { Constants, ToolEndHandler } from '@librechat/agents';
import {
logger,
normalizeSkillFrontmatterKeys,
deriveStructuredFrontmatterFields,
} from '@librechat/data-schemas';
import {
AGENT_BACKGROUND_COMPLETION_RESULT_MAX_CHARS_DEFAULT,
CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES,
hasActivePiiFields,
hasActivePiiPatterns,
hasToolCallErrorPrefix,
} from 'librechat-data-provider';
import type {
LCTool,
FileRefs,
EventHandler,
LCToolRegistry,
InjectedMessage,
ToolCallRequest,
ToolExecuteResult,
ToolExecuteBatchRequest,
SubagentTaskConfig,
SubagentExecutionContext,
CallerCapabilityProjectionSnapshot,
StreamEventData,
ToolEndCallback as SdkToolEndCallback,
} from '@librechat/agents';
import type {
BackgroundToolResultClaim,
DeleteSkillResult,
ValidationIssue,
} from '@librechat/data-schemas';
import type { CodeEnvRef, CodeWorkspaceOperation, PtcToolCallEvent } from 'librechat-data-provider';
import type { StructuredToolInterface } from '@librechat/agents/langchain/tools';
import type { CodeEnvFile, CodeSessionContext } from '@librechat/agents';
import type {
WorkspaceAdmissionOptions,
WorkspaceEditResult,
WorkspaceTextEdit,
WorkspacePreviewEditResult,
WorkspaceListResult,
WorkspaceReadResult,
WorkspaceSearchResult,
WorkspaceWriteResult,
} from '~/code/workspace';
import type {
BackgroundToolDeadClaimRecovery,
BackgroundToolWakeupAdmission,
BackgroundToolWakeupRegistration,
PendingBackgroundCompletionControls,
} from './backgroundCompletion';
import type { ScheduleMCPExecution } from '~/schedules/authorization/execution';
import type { SkillFileRecord, PrimeSkillFilesResult } from './skillFiles';
import type { InterruptibleToolBatchRequest } from './steering/tools';
import type { ArtifactDeliveryFailure } from '~/files/code';
import type { BackgroundToolResultState } from './harvest';
import type { SandboxTextReader } from '~/files/code/text';
import type { WorkspaceEditMatching } from '~/code/edits';
import type { CodeExecutionContext } from './execution';
import type { TextContentFragment } from '~/protection';
import type { AuthoredSkillBinding } from './authored';
import type { RunFileSession } from './files/session';
import type { ServerRequest } from '~/types';
import type { TextEdit } from './edits';
import {
backgroundTaskRegistry,
runCheckBackgroundTask,
getBackgroundTaskSnapshot,
claimBackgroundArtifact,
restoreBackgroundArtifact,
getBackgroundCodeDelivery,
isBackgroundRequested,
hasRunInBackgroundArg,
stripRunInBackgroundArg,
buildBackgroundHandleContent,
buildBackgroundCapacityContent,
stripBackgroundFromToolDefinitions,
withBackgroundTaskTimeout,
BACKGROUND_STATUS_ATTACHMENT_TYPE,
CHECK_BACKGROUND_TASK_NAME,
RUN_IN_BACKGROUND_ARG,
} from './background';
import {
contentFilterUninspectableResponse,
extractFileContent,
extractSkillContent,
extractToolArgumentContent,
hasActiveFileFieldPolicy,
getContentTraversalFragments,
getBlockedUninspectableFileField,
inspectContent,
isContentTraversalLimitError,
isContentTraversalProtected,
} from '~/protection';
import {
CREATE_FILE_TOOL_NAME,
EDIT_FILE_TOOL_NAME,
HOST_FILE_AUTHORING_ARTIFACT_KEY,
LIST_WORKSPACE_FILES_TOOL_NAME,
SEARCH_WORKSPACE_TOOL_NAME,
isCodeFileToolName,
isCodeSessionToolName,
isFileResourceToolName,
} from './tools';
import {
resolveAttachedWorkspaceReadFileLines,
WorkspaceToolHttpError,
resolveAttachedWorkspaceAdmissionOptions,
WORKSPACE_EDIT_MAX_COUNT,
WORKSPACE_WRITE_MAX_BYTES,
} from '~/code/workspace';
import {
noteToolApprovalDispatch,
bindToolApprovalInvocation,
finishToolApprovalDispatch,
getToolApprovalExecutionScope,
} from '~/tools/approval';
import {
BACKGROUND_TASK_ABORT_GRACE_MS,
BACKGROUND_TASK_SHUTDOWN_MESSAGE,
BACKGROUND_TOOL_PRODUCER_HEARTBEAT_MS,
} from './backgroundCompletion';
import {
createCodeApiRateLimitBudget,
isAbortError,
logAxiosError,
truncateMiddle,
runOutsideTracing,
getSafeErrorMetadata,
} from '~/utils';
import {
isAttachedWorkspaceBashTool,
resolveAttachedWorkspaceQueueWaitMs,
resolveAttachedWorkspaceRequestTimeoutMs,
} from '~/code/command';
import {
ContentFilterError,
contentFilterModelBoundBlockResponse,
isContentFilterError,
} from '~/middleware/contentFilter';
import {
hasIntentArg,
stripIntentArg,
stripIntentLabelsFromToolDefinitions,
INTENT_ARG,
} from './intent';
import { editConflictExcerptText, formatEditConflict, parseEditConflict } from '~/code/edits';
import { buildSkillPrimeMessage, isSkillFilePath, SKILL_FILE_PREFIX } from './skills';
import { resolveCallerCapabilityProjectionSnapshot } from './callerCapabilities';
import { SteerToolInterrupt, interruptedToolResult } from './steering/tools';
import { BACKGROUND_TOOL_INVOCATION_CONFIG_KEY } from './invocation';
import { mergeCodeFilesIntoContext } from './codeFilesSession';
import { toolValidationFeedback } from './validationFeedback';
import { explainWorkspacePathRejection } from '~/code/paths';
import { createSkillContentDigest } from './compatibility';
import { isMissingSandboxPathError } from '~/files/code';
import { applyHostTextEdits } from './files/processing';
import { deleteSkillWithRetry } from '~/skills/cleanup';
import { resolveDownloadPath } from '~/storage/path';
import { parseFrontmatter } from '../skills/import';
import { HostEditError } from './files/matching';
import { AuthoredSkillState } from './authored';
import { cleanCodeToolOutput } from './cleanup';
import { primeSkillFiles } from './skillFiles';
import { instrumentPtcToolMap } from './ptc';
import { markSandboxReady } from './prewarm';
import { normalizeEditArgs } from './edits';
export interface ToolEndCallbackData {
/** The executed call's arguments. The stream-consumer tool-end path cannot
* reconstruct these, so the execution handler — which owns both halves —
* must supply them for consumers that fence on the input (the event-actor
* action recorder validates its declared argument subset against this). */
input?: unknown;
/** True when this callback delivers the harvested completion of a
* previously dispatched background task on a poll turn. `output.name` then
* reports the ORIGINAL tool for artifact attribution while `input` carries
* the poll call's arguments — consumers that fence on execution identity
* (the event-actor action recorder) must ignore these deliveries, or a
* name-only expected action could be impersonated by work another turn
* dispatched. */
backgroundDelivery?: boolean;
/** True when the tool executed successfully but its returned content was
* withheld by post-execution output policy. `output.content` is blank and
* no artifact rides the callback — this delivery exists solely so
* execution-identity consumers (the event-actor action recorder) can prove
* the side effect occurred; a retry of an "actionless" turn would otherwise
* repeat an external action whose output was merely filtered. */
outputFiltered?: boolean;
output: {
name: string;
tool_call_id: string;
content: string | unknown;
artifact?: unknown;
};
}
export interface EventActorDetachedActionLifecycle {
reserve(input: {
toolName: string;
toolCallId: string;
turnId: string;
arguments: unknown;
}): Promise<
| { status: 'ignored' }
| { status: 'conflict'; error?: string }
| {
status: 'terminal';
taskId: string;
idempotencyKey: string;
outcome: 'succeeded' | 'failed' | 'cancelled';
result?: string;
error?: string;
}
| {
status: 'reserved' | 'replay';
taskId: string;
idempotencyKey: string;
}
>;
markRunning(input: { taskId: string; idempotencyKey: string }): Promise<boolean>;
settle(input: {
taskId: string;
idempotencyKey: string;
status: 'succeeded' | 'failed' | 'cancelled';
result?: unknown;
error?: string;
}): Promise<boolean>;
wake(input: { taskId: string; idempotencyKey: string }): Promise<void>;
}
export interface ToolEndCallbackMetadata {
/** SDK-authored lineage for artifacts generated inside a child execution. */
executionContext?: SubagentExecutionContext;
run_id?: string;
thread_id?: string;
[key: string]: unknown;
}
/** Projects the graph-owned agent and step identifiers onto persisted tool attachments. */
export function getAttachmentOwnership(metadata?: ToolEndCallbackMetadata): {
agentId?: string;
stepId?: string;
} {
const agentId = metadata?.executingAgentId ?? metadata?.agentId ?? metadata?.agent_id;
const stepId = metadata?.stepId;
return {
...(typeof agentId === 'string' && agentId.length > 0 ? { agentId } : {}),
...(typeof stepId === 'string' && stepId.length > 0 ? { stepId } : {}),
};
}
export type ToolEndCallback = (
data: ToolEndCallbackData,
metadata: ToolEndCallbackMetadata,
) => Promise<void>;
/**
* Preserve the SDK's event-handler contract while attaching the graph-owned
* step identity to legacy artifact callbacks. `toolCallStepIds` is populated
* by ToolNode for the actual provider tool call; this wrapper never invents a
* fallback identity.
*/
export function createOwnedToolEndHandler(
callback: SdkToolEndCallback,
loggerArg: typeof logger = logger,
): EventHandler {
const toolEndHandler = new ToolEndHandler(callback, loggerArg);
return {
handle: async (event, data: StreamEventData, metadata, graph) => {
const output = data?.output;
const toolCallId =
typeof output === 'object' && output != null
? (output as { tool_call_id?: unknown }).tool_call_id
: undefined;
const stepId =
typeof toolCallId === 'string' ? graph?.toolCallStepIds?.get(toolCallId) : undefined;
const ownedMetadata =
typeof stepId === 'string' && stepId.length > 0
? { ...(metadata ?? {}), stepId }
: metadata;
return toolEndHandler.handle(event, data, ownedMetadata, graph);
},
};
}
export interface ToolExecuteOptions {
/** Host observer, called only after authoring has bound an authorized identity. */
onSkillAuthored?: (binding: Pick<AuthoredSkillBinding, 'name' | 'id' | 'primed'>) => void;
/** Host-captured authority ceiling, never runnable/model metadata. */
scheduledMCPExecution?: Pick<ScheduleMCPExecution, 'enrolled' | 'identity'>;
/**
* Host-owned signal for the foreground run. This is authoritative across
* graph reconstruction (including approval resume); the SDK event signal is
* composed with it below so circuit-breaker cancellation is preserved too.
*/
runSignal?: AbortSignal;
/** Run id owned by `runSignal`; detached child runs carry a different id. */
foregroundRunId?: string;
/** Loads tools by name, using agentId to look up agent-specific context */
loadTools: (
toolNames: string[],
agentId?: string,
/** Immutable run configuration available before deferred tools connect. */
configurable?: Record<string, unknown>,
/** SDK-owned live caller capability projection for this agent context. */
callerCapabilityProjection?: CallerCapabilityProjectionSnapshot,
/** Effective cancellation signal for this tool-execute batch. */
signal?: AbortSignal,
/** SDK-authored lineage; never derive child identity from saved agent IDs. */
executionContext?: SubagentExecutionContext,
) => Promise<{
loadedTools: StructuredToolInterface[];
/** Additional configurable properties to merge (e.g., userMCPAuthMap) */
configurable?: Record<string, unknown>;
}>;
/** Trusted detached-subagent task scope for polling and parent controls. */
subagentTasks?: SubagentTaskConfig;
/** Shared-file grants and tool contexts scoped to the executing run instance. */
runFiles?: Pick<RunFileSession, 'isActive' | 'prepareTools' | 'withCodeExecution'>;
/** Trusted deployment gate for cooperative ordinary-tool cancellation. */
ordinaryToolCancellation?: boolean;
/** Deployment-configured cap for terminal output copied into durable receipts. */
backgroundCompletionResultMaxChars?: number;
/** Callback to process tool artifacts (code output files, file citations, etc.) */
toolEndCallback?: ToolEndCallback;
/** Run steps whose call resolved to the attached-workspace `bash_tool`
* instance; the step-completed handler consumes them to stamp `executor`. */
attachedCommandStepIds?: Set<string>;
/** Durable internal-completion adapter, present only for an Event Actor invocation. */
eventActorDetachedAction?: EventActorDetachedActionLifecycle;
/** Called once per batch before tool execution to lazily provision files to tool
* environments. Resolves to the code-env refs it uploaded, which the caller folds
* into this batch's code-session context. */
provisionFiles?: (
toolNames: string[],
agentId?: string,
signal?: AbortSignal,
executionContext?: SubagentExecutionContext,
) => Promise<CodeEnvFile[] | void>;
/**
* Persists a backgrounded code-execution result onto the dispatch turn once
* the detached call settles: downloads/persists generated files, patches the
* original tool-call part's `output`, and appends the attachments to the
* dispatch turn's message row. Returns the persisted attachments so the poll
* turn can re-emit them on its live stream. With `reapply: true` it only
* re-applies the (idempotent) row patch using the provided attachments — no
* file processing — to heal a full-row save that reverted the anchor.
*/
persistBackgroundCodeResult?: (params: {
toolName: string;
toolCallId: string;
stepId?: string;
messageId?: string;
conversationId?: string;
agentId?: string;
dispatchedAt?: number;
output?: string;
artifact?: unknown;
codeExecutionContext?: CodeExecutionContext;
attachments?: unknown[];
reapply?: boolean;
backgroundTask?: BackgroundToolResultState;
resolveBackgroundTask?: () => BackgroundToolResultState;
onFilesPersisted?: (attachments: unknown[]) => void;
}) => Promise<{ attachments?: unknown[]; deliveryReady?: boolean } | null>;
/** Shared ordinary-tool completion lifecycle. The delivery is registered
* before invoke; settlement is persisted onto the original response row. */
backgroundToolCompletion?: {
preregister?: (
registration: BackgroundToolWakeupRegistration,
) => Promise<BackgroundToolWakeupAdmission | false>;
persist: (params: {
toolName: string;
toolCallId: string;
stepId?: string;
messageId?: string;
conversationId?: string;
agentId?: string;
output?: string;
backgroundTask: BackgroundToolResultState;
resolveBackgroundTask?: () => BackgroundToolResultState;
}) => Promise<boolean>;
claim: (params: {
userId: string;
conversationId: string;
messageId?: string;
taskId: string;
agentId?: string;
kind: 'manual';
claimId: string;
generationId?: string;
allowUnfinished?: boolean;
}) => Promise<BackgroundToolResultClaim>;
recoverDeadClaim?: BackgroundToolDeadClaimRecovery;
/** Durable view of undelivered completions, so a status check counts results
* dispatched in earlier turns, on other replicas, or before a restart. */
pending?: PendingBackgroundCompletionControls;
};
/** Emits an `attachment` SSE event on the current request's live stream. */
emitAttachment?: (attachment: unknown) => void;
/**
* Emits an `on_ptc_tool_call` SSE event for one inner tool invocation made
* by a programmatic tool-calling program. Absent on transports that don't
* carry the LibreChat step stream (Open Responses), which simply skips the
* instrumentation.
*/
emitPtcProgress?: (event: PtcToolCallEvent) => void;
/**
* Loads a skill by name with ACL constraint (returns full body for injection).
*
* `options.preferModelInvocable` (Phase 6): on a same-name collision,
* prefer the newest `disableModelInvocation !== true` doc. Avoids a
* newer disabled duplicate shadowing the cataloged model-invocable
* skill the model actually targeted; falls back to newest match so
* the explicit-rejection gate can still fire in the disabled-only case.
*/
getSkillByName?: (
name: string,
accessibleIds: Types.ObjectId[],
options?: { preferUserInvocable?: boolean; preferModelInvocable?: boolean },
) => Promise<{
body: string;
name: string;
description?: string;
frontmatter?: Record<string, unknown>;
_id: Types.ObjectId;
/** Monotonic counter on the skill record. Threaded into
* `codeEnvRef.version` so codeapi's sessionKey scopes the cache
* per-revision; bumping the version on edit invalidates the
* prior cache entry. */
version: number;
fileCount: number;
source?: 'inline' | 'github' | 'notion' | 'deployment';
/** True for deployment-directory skills that are loaded in memory. */
deployment?: boolean;
/**
* Set when the skill author opted out of model invocation. The handler
* rejects the call and returns an instructive error so the model knows
* it can't reach the skill via the `skill` tool — manual `$` invocation
* is still allowed and goes through `resolveManualSkills` instead.
*/
disableModelInvocation?: boolean;
} | null>;
/** Captures a successfully resolved model-invoked Skill for durable continuation context. */
onSkillResolved?: (
skill: {
id: string;
name: string;
version: number;
contentDigest: string;
},
context: { agentId?: string },
) => void;
/**
* Loads a skill by name when the current user is the author. This is a
* narrow recovery path for freshly-authored skills whose runtime catalog
* snapshot has not caught up yet; normal skill resolution still goes
* through `accessibleSkillIds`.
*/
getAuthorSkillByName?: (params: { req: ServerRequest; name: string }) => Promise<{
body: string;
name: string;
description?: string;
frontmatter?: Record<string, unknown>;
_id: Types.ObjectId;
version: number;
fileCount: number;
source?: 'inline' | 'github' | 'notion' | 'deployment';
disableModelInvocation?: boolean;
} | null>;
/** Creates a skill from a tool-authored SKILL.md body. */
createSkill?: (data: {
name: string;
description: string;
body: string;
frontmatter?: Record<string, unknown>;
author: Types.ObjectId;
authorName: string;
alwaysApply?: boolean;
tenantId?: string;
}) => Promise<{
skill: {
_id: Types.ObjectId;
name: string;
body: string;
version: number;
};
warnings: ValidationIssue[];
}>;
/** Updates a skill body and derived metadata from a tool-authored SKILL.md body. */
updateSkill?: (params: {
id: string;
expectedVersion: number;
update: {
body?: string;
description?: string;
frontmatter?: Record<string, unknown>;
alwaysApply?: boolean;
};
}) => Promise<
| {
status: 'updated';
skill: { _id: Types.ObjectId; name: string; body: string; version: number };
warnings: ValidationIssue[];
}
| { status: 'conflict'; current: { _id: Types.ObjectId; name: string; version: number } }
| { status: 'not_found' }
>;
/** Checks role-level skill creation permission for the current user. */
canCreateSkill?: (params: { req: ServerRequest }) => Promise<boolean>;
/** Checks resource-level edit permission for an existing skill. */
canEditSkill?: (params: {
req: ServerRequest;
skillId: Types.ObjectId | string;
}) => Promise<boolean>;
/** Grants SKILL_OWNER to the current user after a tool-created skill is inserted. */
grantSkillOwner?: (params: {
req: ServerRequest;
skillId: Types.ObjectId | string;
}) => Promise<void>;
/** Deletes a freshly-created skill if owner-permission setup fails. */
deleteSkill?: (id: string) => Promise<DeleteSkillResult>;
/** Saves or replaces a bundled skill file in configured storage and metadata. */
saveSkillFileContent?: (params: {
req: ServerRequest;
skillId: Types.ObjectId | string;
relativePath: string;
content: string;
mimeType: string;
expectedFileId?: string;
createOnly: boolean;
}) => Promise<{
bytes: number;
relativePath: string;
}>;
/** Lists files bundled with a skill (for code env priming) */
listSkillFiles?: (skillId: Types.ObjectId | string) => Promise<SkillFileRecord[]>;
/** Storage strategy resolver for skill file streaming */
getStrategyFunctions?: (source: string) => {
getDownloadStream?: (req: ServerRequest, filepath: string) => Promise<NodeJS.ReadableStream>;
[key: string]: unknown;
};
/** Batch uploads files to the code execution environment. `kind`/`id`/
* `version?` carry the resource identity codeapi uses to derive the
* sessionKey for the batch's storage bucket. */
batchUploadCodeEnvFiles?: (params: {
req: ServerRequest;
files: Array<{ stream: NodeJS.ReadableStream; filename: string }>;
kind: 'skill' | 'agent' | 'user';
id: string;
version?: number;
read_only?: boolean;
codeApiBaseUrl?: string;
executionProfile?: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
signal?: AbortSignal;
}) => Promise<{
storage_session_id: string;
files: Array<{ fileId: string; filename: string }>;
}>;
/** Checks if a code env file is still active. Returns lastModified or null. */
getSessionInfo?: (
ref: CodeEnvRef,
req?: ServerRequest,
route?: {
baseUrl?: string;
executionProfile?: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
},
) => Promise<string | null>;
/** 23-hour freshness check */
checkIfActive?: (dateString: string) => boolean;
/** Persists `codeEnvRef` on skill files after upload */
updateSkillFileCodeEnvIds?: (
updates: Array<{
skillId: Types.ObjectId | string;
relativePath: string;
codeEnvRef: CodeEnvRef;
}>,
) => Promise<void>;
/** Loads a skill file by path (for read_file tool) */
getSkillFileByPath?: (
skillId: Types.ObjectId | string,
relativePath: string,
) => Promise<{
file_id?: string;
content?: string;
isBinary?: boolean;
mimeType: string;
bytes: number;
filepath: string;
source: string;
relativePath: string;
} | null>;
/** Updates cached content on a skill file (lazy caching after first read) */
updateSkillFileContent?: (
skillId: Types.ObjectId | string,
relativePath: string,
update: { content?: string; isBinary?: boolean },
expectedFileId?: string,
) => Promise<void>;
/** Reads a bounded text range from an attached worker's logical workspace. */
readWorkspaceFile?: (params: {
file_path: string;
workspace_id: string;
workspace_instance_id?: string;
linked_worktrees?: boolean;
start_line: number;
max_lines: number;
codeApiBaseUrl: string;
executionProfile: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
req?: ServerRequest;
signal?: AbortSignal;
maxQueueWaitMs?: number;
maxRequestTimeoutMs?: number;
maxRunTimeoutMs?: number;
admission?: WorkspaceAdmissionOptions['admission'];
deadlineAtMs?: number;
}) => Promise<WorkspaceReadResult>;
/** Searches literal text within an attached worker's logical workspace. */
searchWorkspace?: (params: {
query: string;
workspace_id: string;
workspace_instance_id?: string;
linked_worktrees?: boolean;
path?: string;
max_results: number;
codeApiBaseUrl: string;
executionProfile: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
req?: ServerRequest;
signal?: AbortSignal;
maxQueueWaitMs?: number;
maxRequestTimeoutMs?: number;
maxRunTimeoutMs?: number;
admission?: WorkspaceAdmissionOptions['admission'];
deadlineAtMs?: number;
}) => Promise<WorkspaceSearchResult>;
/** Lists relative file paths within an attached worker's logical workspace. */
listWorkspaceFiles?: (params: {
workspace_id: string;
workspace_instance_id?: string;
linked_worktrees?: boolean;
path?: string;
after_path?: string;
max_results: number;
codeApiBaseUrl: string;
executionProfile: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
req?: ServerRequest;
signal?: AbortSignal;
maxQueueWaitMs?: number;
maxRequestTimeoutMs?: number;
maxRunTimeoutMs?: number;
admission?: WorkspaceAdmissionOptions['admission'];
deadlineAtMs?: number;
}) => Promise<WorkspaceListResult>;
/** Writes a UTF-8 file within an attached worker's logical workspace. */
writeWorkspaceFile?: (params: {
file_path: string;
content: string;
overwrite: boolean;
workspace_id: string;
workspace_instance_id?: string;
linked_worktrees?: boolean;
codeApiBaseUrl: string;
executionProfile: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
req?: ServerRequest;
signal?: AbortSignal;
maxQueueWaitMs?: number;
maxRequestTimeoutMs?: number;
maxRunTimeoutMs?: number;
admission?: WorkspaceAdmissionOptions['admission'];
deadlineAtMs?: number;
}) => Promise<WorkspaceWriteResult>;
/** Previews exact replacements without mutating an attached worker workspace. */
previewWorkspaceEdit?: (params: {
file_path: string;
edits: WorkspaceTextEdit[];
/** Sent only to workers that negotiated `tolerant_match`. */
matching?: WorkspaceEditMatching;
workspace_id: string;
workspace_instance_id?: string;
linked_worktrees?: boolean;
codeApiBaseUrl: string;
executionProfile: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
req?: ServerRequest;
signal?: AbortSignal;
maxQueueWaitMs?: number;
maxRequestTimeoutMs?: number;
maxRunTimeoutMs?: number;
admission?: WorkspaceAdmissionOptions['admission'];
deadlineAtMs?: number;
}) => Promise<WorkspacePreviewEditResult>;
/** Applies exact replacements atomically within an attached worker workspace. */
editWorkspaceFile?: (params: {
file_path: string;
edits: WorkspaceTextEdit[];
expected_base_sha256?: string;
/** Sent only to workers that negotiated `tolerant_match`. */
matching?: WorkspaceEditMatching;
workspace_id: string;
workspace_instance_id?: string;
linked_worktrees?: boolean;
codeApiBaseUrl: string;
executionProfile: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
req?: ServerRequest;
signal?: AbortSignal;
maxQueueWaitMs?: number;
maxRequestTimeoutMs?: number;
maxRunTimeoutMs?: number;
admission?: WorkspaceAdmissionOptions['admission'];
deadlineAtMs?: number;
}) => Promise<WorkspaceEditResult>;
/** Bounded reads return complete text; omitted maxBytes retains the legacy stdout path. */
readSandboxFile?: SandboxTextReader;
/**
* Reads a small image file out of the code-execution sandbox as base64 so
* `read_file` can surface it to vision-capable models. The `readSandboxFile`
* `cat` path round-trips stdout through codeapi's JSON transport, which
* lossily replaces non-UTF-8 bytes and mangles image data — this reader
* base64-encodes the bytes IN the sandbox (ASCII-safe over JSON) after an
* in-sandbox size guard so an oversize image never crosses the wire.
* Returns `null` when codeapi is unavailable; throws on transport / read
* errors so the handler can fall back to an instructive message.
*/
readSandboxImage?: (params: {
file_path: string;
session_id?: string;
files?: SandboxFileRef[];
/** @see readSandboxFile.runtime_session_hint */
runtime_session_hint?: string;
codeApiBaseUrl?: string;
executionProfile?: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
executionRouteKey?: string;
/** In-sandbox size cap; files larger than this return `tooLarge` without transferring bytes. */
maxBytes?: number;
req?: ServerRequest;
signal?: AbortSignal;
}) => Promise<
| { base64: string; bytes: number }
/** `size`: over `maxBytes`. `round_trips`: within the byte cap, but more
* windowed `/exec` reads than one call may spend on the Code API's
* per-user execution limiter. */
| { tooLarge: true; reason?: 'size' | 'round_trips'; bytes: number; inlineCeiling?: number }
| null
>;
/**
* Writes a UTF-8 text file into the code-execution sandbox via the
* sandbox `/exec` endpoint. Mirrors `readSandboxFile` session forwarding
* so host-side file-authoring tools can operate in the same sandbox
* session as `bash_tool` / `read_file`.
*/
writeSandboxFile?: (params: {
file_path: string;
content: string;
session_id?: string;
files?: SandboxFileRef[];
/** @see readSandboxFile.runtime_session_hint */
runtime_session_hint?: string;
codeApiBaseUrl?: string;
executionProfile?: CodeExecutionContext['executionProfile'];
req?: ServerRequest;
}) => Promise<{
stdout?: string;
stderr?: string;
session_id?: string;
files?: SandboxFileRef[];
artifact_delivery?: ArtifactDeliveryFailure;
} | null>;
}
const MAX_READABLE_BYTES = 262_144;
const MAX_BINARY_BYTES = 5 * 1024 * 1024;
function truncateUtf8(value: string, maxBytes: number): string {
const bytes = Buffer.from(value, 'utf8');
if (bytes.byteLength <= maxBytes) {
return value;
}
let end = maxBytes;
while (end > 0 && (bytes[end] & 0xc0) === 0x80) {
end -= 1;
}
return bytes.subarray(0, end).toString('utf8');
}
/**
* Inline ceiling for images pulled out of the code-execution sandbox —
* deliberately tighter than {@link MAX_BINARY_BYTES}, which governs the
* skill-file path. The two differ because their transports differ: skill
* files stream from storage, while sandbox bytes come back base64 over
* `/exec` stdout, which the runner caps (`SANDBOX_OUTPUT_MAX_SIZE`). The
* reader therefore windows the file, so cost scales in round-trips —
* ~32 at this limit vs ~160 at 5MB. Nothing is lost by stopping here:
* vision providers downsample to ~1.5-2k px regardless, so multi-MB
* originals buy no fidelity, and anything larger degrades to the
* `bash_tool` hint below.
*/
const MAX_SANDBOX_INLINE_IMAGE_BYTES = 1024 * 1024;
const MAX_CACHE_BYTES = 512 * 1024;
const MAX_AUTHORING_BYTES = 10 * 1024 * 1024;
const MAX_TOOL_ERROR_MESSAGE_CHARS = 12_000;
const MAX_TOOL_ERROR_STACK_CHARS = 4_000;
const SKILL_MD = 'SKILL.md';
const MAX_SKILL_AUTHORING_WARNINGS = 20;
const MAX_SKILL_WARNING_FIELD_CHARS = 120;
const MAX_SKILL_WARNING_CODE_CHARS = 64;
const MAX_SKILL_WARNING_MESSAGE_CHARS = 300;
const IMAGE_MIMES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
function getCodeExecutionContext(
configurable: Record<string, unknown>,
): CodeExecutionContext | undefined {
const context = configurable.codeExecutionContext;
if (context == null || typeof context !== 'object') {
return undefined;
}
const candidate = context as Partial<CodeExecutionContext>;
if (
typeof candidate.baseUrl !== 'string' ||
typeof candidate.codeSessionKey !== 'string' ||
(candidate.executionProfile !== 'default' && candidate.executionProfile !== 'stateful') ||
typeof candidate.statefulSessions !== 'boolean'
) {
return undefined;
}
return candidate as CodeExecutionContext;
}
function selectedWorkspaceId(
context: CodeExecutionContext,
operation: CodeWorkspaceOperation,
): string | undefined {
const workspace = context.codeWorkspace;
if (
workspace == null ||
workspace.environmentId !== context.environmentId ||
!workspace.operations.includes(operation)
) {
return undefined;
}
return workspace.workspaceId;
}
function unavailableWorkspaceOperation(
tc: ToolCallRequest,
operation: CodeWorkspaceOperation,
): ToolExecuteResult {
return errorResult(
tc,
`The selected attached workspace is unavailable or does not permit ${operation}. Choose an available workspace and retry.`,
);
}
function codeExecutionRequestParams(context?: CodeExecutionContext): {
codeApiBaseUrl?: string;
executionProfile?: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
executionRouteKey?: string;
runtime_session_hint?: string;
} {
if (!context) {
return {};
}
return {
codeApiBaseUrl: context.baseUrl,
executionProfile: context.executionProfile,
...(context.executionRouteKey ? { executionRouteKey: context.executionRouteKey } : {}),
...(context.bridgeWorkerId ? { bridgeWorkerId: context.bridgeWorkerId } : {}),
...(context.runtimeSessionHint ? { runtime_session_hint: context.runtimeSessionHint } : {}),
};
}
type ToolInputSchemaKind = {
object: boolean;
string: boolean;
};
function stringifyThrownValue(error: unknown): string {
try {
return String(error);
} catch {
return '[Thrown value could not be converted to string]';
}
}
function getThrownValueMessage(error: unknown): string {
if (error instanceof Error) {
return error.message;
}
if (error != null && typeof error === 'object') {
try {
const message = (error as { message?: unknown }).message;
if (typeof message === 'string') {
return message;
}
if (message != null) {
return stringifyThrownValue(message);
}
} catch {
// Fall through to whole-value stringification.
}
}
return stringifyThrownValue(error);
}
function getSafeToolError(
error: unknown,
feedback?: string,
): {
message: string;
logContext: Record<string, unknown>;
} {
const thrownMessage = feedback ?? getThrownValueMessage(error);
/** File text an attached edit conflict quotes goes to the model only, never to the logs. */
const rawMessage =
!feedback && error instanceof AttachedEditRejectionError ? error.modelMessage : thrownMessage;
const logMessage = truncateMiddle(thrownMessage, MAX_TOOL_ERROR_MESSAGE_CHARS);
const message = truncateMiddle(rawMessage, MAX_TOOL_ERROR_MESSAGE_CHARS);
const stack = !feedback && error instanceof Error && error.stack ? error.stack : undefined;
return {
message,
logContext: {
errorName: error instanceof Error ? error.name : typeof error,
...(error instanceof WorkspaceToolHttpError
? {
upstreamStatus: error.upstreamStatus,
upstreamBody: error.upstreamBody,
upstreamBodyTruncated: error.upstreamBodyTruncated,
}
: {}),
errorMessage: logMessage,
messageLength: rawMessage.length,
messageTruncated: message.length !== rawMessage.length,
stack: stack ? truncateMiddle(stack, MAX_TOOL_ERROR_STACK_CHARS) : undefined,
},
};
}
function mergeSchemaKind(target: ToolInputSchemaKind, source: ToolInputSchemaKind): void {
target.object ||= source.object;
target.string ||= source.string;
}
function detectToolInputSchemaKind(schema: unknown): ToolInputSchemaKind {
const kind: ToolInputSchemaKind = { object: false, string: false };
if (!schema || typeof schema !== 'object') {
return kind;
}
const jsonSchemaType = (schema as { type?: unknown }).type;
if (jsonSchemaType === 'object') {
kind.object = true;
} else if (jsonSchemaType === 'string') {
kind.string = true;
} else if (Array.isArray(jsonSchemaType)) {
kind.object = jsonSchemaType.includes('object');
kind.string = jsonSchemaType.includes('string');
}
for (const compositeKey of ['anyOf', 'oneOf', 'allOf'] as const) {
const options = (schema as Record<typeof compositeKey, unknown>)[compositeKey];
if (Array.isArray(options)) {
for (const option of options) {
mergeSchemaKind(kind, detectToolInputSchemaKind(option));
}
}
}
const zodDef = (schema as { _def?: unknown })._def;
if (!zodDef || typeof zodDef !== 'object') {
return kind;
}
const zodType = (zodDef as { type?: unknown; typeName?: unknown }).type;
const zodTypeName = (zodDef as { type?: unknown; typeName?: unknown }).typeName;
if (zodType === 'object' || zodTypeName === 'ZodObject') {
kind.object = true;
} else if (zodType === 'string' || zodTypeName === 'ZodString') {
kind.string = true;
}
const innerSchema =
(zodDef as { innerType?: unknown; schema?: unknown }).innerType ??
(zodDef as { schema?: unknown }).schema;
if (innerSchema) {
mergeSchemaKind(kind, detectToolInputSchemaKind(innerSchema));
}
const zodOptions = (zodDef as { options?: unknown }).options;
if (Array.isArray(zodOptions)) {
for (const option of zodOptions) {
mergeSchemaKind(kind, detectToolInputSchemaKind(option));
}
}
return kind;
}
function getToolInputSchemaKind(tool: StructuredToolInterface): ToolInputSchemaKind {
const constructorName = (tool as { constructor?: { name?: string } }).constructor?.name;
if (constructorName === 'DynamicTool') {
return { object: false, string: true };
}
return detectToolInputSchemaKind((tool as { schema?: unknown }).schema);
}
function normalizeToolInvokeArgs(args: unknown, tool: StructuredToolInterface): unknown {
const schemaKind = getToolInputSchemaKind(tool);
if (typeof args !== 'string') {
if (!schemaKind.string || schemaKind.object) {
return args;
}
const inputValue = (args as { input?: unknown })?.input;
return typeof inputValue === 'string' ? args : JSON.stringify(args);
}
if (!schemaKind.object || schemaKind.string) {
return args;
}
const trimmed = args.trim();
if (!trimmed.startsWith('{')) {
return args;
}
try {
const parsed = JSON.parse(trimmed) as unknown;
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
return parsed;
}
} catch {
return args;
}
return args;
}
function getValueShape(value: unknown): string {
if (value === null) {
return 'null';
}
if (Array.isArray(value)) {
return 'array';
}
return typeof value;
}
function addLineNumbers(content: string, startLine = 1): string {
const lines = content.split('\n');
const w = String(startLine + lines.length - 1).length;
return lines
.map((line, index) => `${String(startLine + index).padStart(w, ' ')} | ${line}`)
.join('\n');
}
type ReadFileRangeArguments = { start_line?: number; max_lines?: number };
type ReadFileRange = { startLine: number; maxLines: number };
const READ_FILE_RANGE_ERROR =
'start_line must be positive and max_lines must be between 1 and 500.';
function resolveReadFileRange(
args: ReadFileRangeArguments,
defaultMaxLines = CODE_ENVIRONMENT_READ_FILE_DEFAULT_LINES,
): ReadFileRange | null {
const startLine = args.start_line ?? 1;
const maxLines = args.max_lines ?? defaultMaxLines;
return Number.isSafeInteger(startLine) &&
startLine >= 1 &&
Number.isSafeInteger(maxLines) &&
maxLines >= 1 &&
maxLines <= CODE_ENVIRONMENT_READ_FILE_HARD_MAX_LINES
? { startLine, maxLines }
: null;
}
/** Full local files are sliced once; a worker page is already offset and bounded. */
function formatReadFileText(
content: string,
path: string,
range?: ReadFileRange,
page?: { startLine: number; nextStartLine?: number },
): string {
let payload = content;
const startLine = page?.startLine ?? range?.startLine ?? 1;
let nextStartLine = page?.nextStartLine;
if (range != null && page == null) {
let start = 0;
for (let line = 1; line < range.startLine; line++) {
const newline = content.indexOf('\n', start);
if (newline < 0) return '';
start = newline + 1;
}
if (start >= content.length) return '';
let end = content.length;
let cursor = start;
for (let count = 1; count <= range.maxLines; count++) {
const newline = content.indexOf('\n', cursor);
if (newline < 0) break;
if (count === range.maxLines || newline === content.length - 1) {
end = newline;
if (newline < content.length - 1) nextStartLine = startLine + count;
break;
}
cursor = newline + 1;
}
payload = content.slice(start, end);
}
let locallyTruncated = false;
let localNextStartLine: number | undefined;
if ((range != null || page != null) && Buffer.byteLength(payload, 'utf8') > MAX_READABLE_BYTES) {
payload = truncateUtf8(payload, MAX_READABLE_BYTES);
locallyTruncated = true;
const lastCompleteLine = payload.lastIndexOf('\n');
if (lastCompleteLine >= 0) {
payload = payload.slice(0, lastCompleteLine);
localNextStartLine = startLine + payload.split('\n').length;
}
}
let numbered = addLineNumbers(payload, startLine);
if (locallyTruncated) {
numbered +=
localNextStartLine != null
? `\n\n[truncated at ${MAX_READABLE_BYTES} bytes; more content is available; call read_file again with path "${path}" and start_line ${localNextStartLine}]`
: `\n\n[the line was truncated at ${MAX_READABLE_BYTES} bytes and cannot be paged by line]`;
} else if (nextStartLine != null) {
numbered += `\n\n[more content is available; call read_file again with path "${path}" and start_line ${nextStartLine}]`;
}
return numbered;
}
function localTextReadResult(
tc: ToolCallRequest,
path: string,
content: string,
header = '',
): ToolExecuteResult {
const args = tc.args as ReadFileRangeArguments;
const range =
args.start_line === undefined && args.max_lines === undefined
? undefined
: resolveReadFileRange(args);
if (range === null) return errorResult(tc, READ_FILE_RANGE_ERROR);
return successResult(tc, header + formatReadFileText(content, path, range));
}
type AuthoringSkill = NonNullable<
Awaited<ReturnType<NonNullable<ToolExecuteOptions['getSkillByName']>>>
>;
type AuthoringResult = Promise<ToolExecuteResult>;
type ParsedSkillAuthoringPath = {
skillName: string;
relativePath: string;
displayPath: string;
};
type LoadedSkillText =
| { status: 'loaded'; content: string; bytes: number; fileId?: string }
| { status: 'missing' }
| { status: 'error'; message: string };
type ExistingSkillFile =
| { status: 'present'; oldContent?: string; fileId?: string }
| { status: 'missing' }
| { status: 'error'; message: string };
type LoadedSandboxText = LoadedSkillText;
/**
* A code-session file ref as it crosses the host boundary: the SDK's wire
* shape (`kind` / `resource_id` / `version` / `inherited`) plus the legacy
* per-file `session_id` older Code API responses carry, which
* `getPreparedCodeOutputBuffer` still reads as a storage-session fallback.
* Every field is load-bearing on the wire — `version` is required for
* `kind: 'skill'` refs and `resource_id` names the resource that owns the
* file's storage session — so refs must be carried whole, never rebuilt
* from a subset.
*/
type SandboxFileRef = FileRefs[number] & { session_id?: string };
type SandboxSessionContext = {
session_id?: string;
files?: SandboxFileRef[];
};
const MIME_MAP: Readonly<Record<string, string>> = Object.freeze({
'.md': 'text/markdown',
'.txt': 'text/plain',
'.json': 'application/json',
'.js': 'application/javascript',
'.mjs': 'application/javascript',
'.cjs': 'application/javascript',
'.ts': 'application/typescript',
'.tsx': 'application/typescript',
'.jsx': 'application/javascript',
'.py': 'text/x-python',
'.sh': 'application/x-sh',
'.yaml': 'application/yaml',
'.yml': 'application/yaml',
'.css': 'text/css',
'.html': 'text/html',
'.xml': 'application/xml',
'.csv': 'text/csv',
'.toml': 'text/toml',
'.ini': 'text/ini',
'.svg': 'image/svg+xml',
});
function errorResult(tc: ToolCallRequest, errorMessage: string): ToolExecuteResult {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage,
};
}
function modelBoundContentFilterErrorMessage(
finding: Parameters<typeof contentFilterModelBoundBlockResponse>[0],
): string {
return JSON.stringify(contentFilterModelBoundBlockResponse(finding));
}
function contentFilterErrorResult(
tc: ToolCallRequest,
finding: Parameters<typeof contentFilterModelBoundBlockResponse>[0],
): ToolExecuteResult {
return errorResult(tc, modelBoundContentFilterErrorMessage(finding));
}
function filteredContentResult(
tc: ToolCallRequest,
req: ServerRequest | undefined,
fragments: Iterable<TextContentFragment>,
): ToolExecuteResult | null {
const filters = req?.config?.filters;
if (filters == null) {
return null;
}
const finding = inspectContent(fragments, { filters });
return finding == null ? null : contentFilterErrorResult(tc, finding);
}
function filteredToolArgumentsResult(
tc: ToolCallRequest,
req: ServerRequest | undefined,
args: unknown,
): ToolExecuteResult | null {
const pii = req?.config?.filters?.toolArguments?.pii;
if (!hasActivePiiFields(pii, ['name', 'arguments'])) {
return null;
}
const inspectName = pii?.fields == null || pii.fields.includes('name');
const inspectArguments = pii?.fields == null || pii.fields.includes('arguments');
try {
return filteredContentResult(
tc,
req,
extractToolArgumentContent({
...(inspectName && { name: tc.name }),
...(inspectArguments && { arguments: args }),
}),
);
} catch (error) {
if (!isContentTraversalLimitError(error)) {
throw error;
}
const filtered = filteredContentResult(tc, req, getContentTraversalFragments(error));
if (filtered != null) {
return filtered;
}
return isContentTraversalProtected({ error, filters: req?.config?.filters })
? errorResult(tc, error.body.message)
: null;
}
}
/**
* Inner tool names the `name` PII policy would block. `filteredToolArgumentsResult`
* inspects `tc.name` for direct calls, but inner calls bypass it entirely — and
* the trace event carries the name unconditionally, so without this the trace
* becomes the disclosure path the policy exists to close. The eligible map holds
* a handful of names, each inspected once per PTC call.
*/
function collectFilteredPtcToolNames(
names: Iterable<string>,
req: ServerRequest | undefined,
): ReadonlySet<string> | undefined {
const filters = req?.config?.filters;
if (filters == null || !hasActivePiiFields(filters.toolArguments?.pii, ['name'])) {
return undefined;
}
const blocked = new Set<string>();
for (const name of names) {
try {
if (inspectContent(extractToolArgumentContent({ name }), { filters }) != null) {
blocked.add(name);
}
} catch {
/* An un-inspectable name is treated as blocked: fail closed. */
blocked.add(name);
}
}
return blocked.size > 0 ? blocked : undefined;
}
function filteredToolOutputResult(
tc: ToolCallRequest,
req: ServerRequest | undefined,
output: unknown,
): ToolExecuteResult | null {
const pii = req?.config?.filters?.toolArguments?.pii;
if (!hasActivePiiFields(pii, ['output'])) {
return null;
}
try {
return filteredContentResult(tc, req, extractToolArgumentContent({ name: tc.name, output }));
} catch (error) {
if (!isContentTraversalLimitError(error)) {
throw error;
}
const filtered = filteredContentResult(tc, req, getContentTraversalFragments(error));
if (filtered != null) {
return filtered;
}
return isContentTraversalProtected({ error, filters: req?.config?.filters })
? errorResult(tc, error.body.message)
: null;
}
}
function filteredSkillResult(
tc: ToolCallRequest,
req: ServerRequest | undefined,
input: Parameters<typeof extractSkillContent>[0],
): ToolExecuteResult | null {
const pii = req?.config?.filters?.skills?.pii;
if (!hasActivePiiPatterns(pii)) {
return null;
}
const selectedFields = new Set<string>(pii?.fields ?? []);
const selected = (field: string): boolean => pii?.fields == null || selectedFields.has(field);
const projected = {
...(selected('name') && { name: input?.name }),
...(selected('display_title') && { displayTitle: input?.displayTitle }),
...(selected('description') && { description: input?.description }),
...(selected('category') && { category: input?.category }),
...(selected('instructions') && {
body: input?.body,
instructions: input?.instructions,
}),
...(selected('imported_text') && { importedText: input?.importedText }),
...(selected('frontmatter') && { frontmatter: input?.frontmatter }),
...((selected('file_name') || selected('file_text')) && {
files: input?.files?.map((file) => ({
...(selected('file_name') && { name: file?.name, filename: file?.filename }),
...(selected('file_text') && { text: file?.text, content: file?.content }),
})),
}),
};
return filteredContentResult(tc, req, extractSkillContent(projected));
}
function isFilteredSkillProjection(
tc: ToolCallRequest,
req: ServerRequest | undefined,
input: Parameters<typeof extractSkillContent>[0],
): boolean {
try {
return filteredSkillResult(tc, req, input) != null;
} catch (error) {
if (isContentTraversalLimitError(error)) {
return isContentTraversalProtected({ error, filters: req?.config?.filters });
}
throw error;
}
}
function filteredFileNameResult(
tc: ToolCallRequest,
req: ServerRequest | undefined,
filename: string,
): ToolExecuteResult | null {
if (!hasActiveFileFieldPolicy(req?.config?.filters, ['name'])) {
return null;
}
return filteredContentResult(tc, req, extractFileContent({ filename }));
}
function uninspectableFileResult(
tc: ToolCallRequest,
req: ServerRequest | undefined,
): ToolExecuteResult | null {
const field = getBlockedUninspectableFileField(req?.config?.filters, [
'content',
'extracted_text',
]);
return field == null ? null : errorResult(tc, contentFilterUninspectableResponse(field).message);
}
function filteredBinaryFileResult(
tc: ToolCallRequest,
req: ServerRequest | undefined,
filename: string,
): ToolExecuteResult | null {
return filteredFileNameResult(tc, req, filename) ?? uninspectableFileResult(tc, req);
}
function filteredFileResult(
tc: ToolCallRequest,
req: ServerRequest | undefined,
filename: string,
content: string,
): ToolExecuteResult | null {
const filters = req?.config?.filters;
if (!hasActiveFileFieldPolicy(filters, ['name', 'content', 'extracted_text'])) {
return null;
}
const filteredName = filteredFileNameResult(tc, req, filename);
if (filteredName != null) {
return filteredName;
}
const inspectRawContent = hasActiveFileFieldPolicy(filters, ['content']);
const inspectExtractedText = hasActiveFileFieldPolicy(filters, ['extracted_text']);
if (!inspectRawContent && !inspectExtractedText) {
return null;
}
if (looksBinary(content)) {
return uninspectableFileResult(tc, req);
}
return filteredContentResult(
tc,
req,
extractFileContent({
...(inspectRawContent && { content }),
...(inspectExtractedText && { extractedText: content }),
}),
);
}
function successResult(
tc: ToolCallRequest,
content: string,
artifact?: unknown,
): ToolExecuteResult {
const result: ToolExecuteResult = {
toolCallId: tc.id,
status: 'success',
content,
};
if (artifact !== undefined) {
result.artifact = artifact;
}
return result;
}
function surfaceSkillAuthoringWarnings(warnings: ValidationIssue[] | undefined): {
contentSuffix: string;
warnings: Array<ValidationIssue & { severity: 'warning' }>;
warningCount: number;
} | null {
if (!warnings?.length) {
return null;
}
const surfaced = warnings.slice(0, MAX_SKILL_AUTHORING_WARNINGS).map((warning) => ({
field: truncateMiddle(warning.field, MAX_SKILL_WARNING_FIELD_CHARS),
code: truncateMiddle(warning.code, MAX_SKILL_WARNING_CODE_CHARS),
message: truncateMiddle(warning.message, MAX_SKILL_WARNING_MESSAGE_CHARS),
severity: 'warning' as const,
}));
const omitted = warnings.length - surfaced.length;
const lines = surfaced.map(
(warning) => `- ${warning.field} [${warning.code}]: ${warning.message}`,
);
if (omitted > 0) {
lines.push(`- ${omitted} additional warning(s) omitted.`);
}
return {
contentSuffix: `\n\nWarnings:\n${lines.join('\n')}`,
warnings: surfaced,
warningCount: warnings.length,
};
}
function guessMimeType(filename: string): string {
return MIME_MAP[lowercaseExtension(filename)] ?? 'application/octet-stream';
}
function isValidSkillName(value: string): boolean {
return /^[a-z0-9][a-z0-9-]*$/.test(value);
}
function isValidSkillFileRelativePath(value: string): boolean {
if (!value || value.length > 500) {
return false;
}
if (value.startsWith('/') || value.startsWith('\\')) {
return false;
}
if (!/^[a-zA-Z0-9._\-/]+$/.test(value)) {
return false;
}
const segments = value.split('/');
if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
return false;
}
return value !== SKILL_MD && segments[0] !== SKILL_MD;
}
function parseSkillAuthoringPath(filePath: string): ParsedSkillAuthoringPath | string {
if (!filePath.startsWith(SKILL_FILE_PREFIX)) {
return `Only skill file paths are supported. Use "skills/{skillName}/SKILL.md" or "skills/{skillName}/{path}".`;
}
const rest = filePath.slice(SKILL_FILE_PREFIX.length);
const slashIdx = rest.indexOf('/');
const skillName = slashIdx === -1 ? rest : rest.slice(0, slashIdx);
const relativePath = slashIdx === -1 ? SKILL_MD : rest.slice(slashIdx + 1) || SKILL_MD;
if (!isValidSkillName(skillName)) {
return `Invalid skill name "${skillName}". Skill names must be kebab-case.`;
}
if (relativePath !== SKILL_MD && !isValidSkillFileRelativePath(relativePath)) {
return (
`Invalid skill file path "${relativePath}". ` +
'Paths must be relative and cannot contain empty, "." or ".." segments.'
);
}
return {
skillName,
relativePath,
displayPath: `${SKILL_FILE_PREFIX}${skillName}/${relativePath}`,
};
}
function deriveSkillDescription(body: string, skillName: string): string {
const fallback = `Use this skill for ${skillName.replace(/-/g, ' ')}.`;
const headingCandidates: string[] = [];
for (const line of body.split('\n')) {
const trimmed = line.trim();
if (!trimmed) {
continue;
}
const withoutMarkdown = trimmed
.replace(/^#{1,6}\s+/, '')
.replace(/^[*>-]\s+/, '')
.trim();
if (!withoutMarkdown) {
continue;
}
if (/^#{1,6}\s+/.test(trimmed)) {
headingCandidates.push(withoutMarkdown);
continue;
}
return truncateMiddle(withoutMarkdown.replace(/\s+/g, ' '), 180);
}
const heading = headingCandidates[0];
return heading ? truncateMiddle(heading.replace(/\s+/g, ' '), 180) : fallback;
}
function splitSkillFrontmatter(content: string):
| {
block: string;
body: string;
}
| { error: string }
| null {
const trimmed = content.trim();
if (!trimmed.startsWith('---')) {
return null;
}
const afterOpening = trimmed.slice(3);
const closingIdx = afterOpening.indexOf('\n---');
if (closingIdx === -1) {
return { error: `Invalid ${SKILL_MD} frontmatter: missing closing "---".` };
}
const afterClosing = afterOpening.slice(closingIdx + '\n---'.length);
return {
block: afterOpening.slice(0, closingIdx),
body: afterClosing.startsWith('\n') ? afterClosing.slice(1) : afterClosing,
};
}
function buildSkillMdContent(frontmatter: Record<string, unknown>, body: string): string {
const dumped = yaml.dump(frontmatter, { lineWidth: -1 }).trimEnd();
const normalizedBody = body.trimStart();
return `---\n${dumped}\n---\n${normalizedBody}`;
}
function skillNameMismatchError(frontmatterName: string, skillName: string): string {
return `${SKILL_MD} frontmatter name "${frontmatterName}" must match path skill name "${skillName}". edit_file cannot rename skills; keep the name unchanged or create a new skills/{newName}/SKILL.md.`;
}
function normalizeSkillMdContent(
content: string,
skillName: string,
): { status: 'success'; content: string } | { status: 'error'; error: string } {
const split = splitSkillFrontmatter(content);
if (split && 'error' in split) {
return { status: 'error', error: split.error };
}
let normalizedContent = content;
if (!split) {
normalizedContent = buildSkillMdContent(
{
name: skillName,
description: deriveSkillDescription(content, skillName),
},
content,
);
} else {
const structured = parseStructuredSkillFrontmatter(content);
if (structured.error) {
return { status: 'error', error: structured.error };
}
const frontmatter = { ...(structured.frontmatter ?? {}) };
const parsed = parseFrontmatter(content);
const frontmatterName =
typeof frontmatter.name === 'string' ? frontmatter.name : parsed.name || undefined;
if (frontmatterName && frontmatterName !== skillName) {
return {
status: 'error',
error: skillNameMismatchError(frontmatterName, skillName),
};
}
frontmatter.name = skillName;
const frontmatterDescription =
typeof frontmatter.description === 'string'
? frontmatter.description
: parsed.description || undefined;
frontmatter.description =
frontmatterDescription || deriveSkillDescription(split.body, skillName);
normalizedContent = buildSkillMdContent(frontmatter, split.body);
}
const parsed = parseFrontmatter(normalizedContent);
if (!parsed.name || !parsed.description) {
return {
status: 'error',
error: `${SKILL_MD} must include YAML frontmatter with "name" and "description".`,
};
}
if (parsed.name !== skillName) {
return {
status: 'error',
error: skillNameMismatchError(parsed.name, skillName),
};
}
if (parsed.invalidBooleans.length > 0) {
return {
status: 'error',
error: parsed.invalidBooleans
.map((key) => `"${key}" in ${SKILL_MD} frontmatter must be a boolean`)
.join('; '),
};
}
return { status: 'success', content: normalizedContent };
}
function extractSkillFrontmatterBlock(content: string): string | null {
const split = splitSkillFrontmatter(content);
if (!split || 'error' in split) {
return null;
}
return split.block;
}
function parseStructuredSkillFrontmatter(
content: string,
):
| { frontmatter?: Record<string, unknown>; error?: undefined }
| { frontmatter?: undefined; error: string } {
const block = extractSkillFrontmatterBlock(content);
if (block == null) {
return {};
}
try {
const parsed = yaml.load(block);
if (parsed == null) {
return { frontmatter: {} };
}
if (typeof parsed !== 'object' || Array.isArray(parsed)) {
return { error: `${SKILL_MD} frontmatter must be a YAML mapping.` };
}
const normalized = normalizeSkillFrontmatterKeys(parsed as Record<string, unknown>);
if ('error' in normalized) {
return { error: `Invalid ${SKILL_MD} frontmatter: ${normalized.error}` };
}
return { frontmatter: normalized.frontmatter };
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
return { error: `Invalid ${SKILL_MD} frontmatter: ${message}` };
}
}
function parseSkillMdUpdate(content: string): {
description: string;
frontmatter?: Record<string, unknown>;
alwaysApply?: boolean;
} {
const parsed = parseFrontmatter(content);
const structured = parseStructuredSkillFrontmatter(content);
const structuredDescription =
typeof structured.frontmatter?.description === 'string'
? structured.frontmatter.description
: undefined;
return {
description: structuredDescription ?? parsed.description,
...(structured.frontmatter !== undefined ? { frontmatter: structured.frontmatter } : {}),
...(parsed.alwaysApply !== undefined ? { alwaysApply: parsed.alwaysApply } : {}),
};
}
function getAuthorInfo(req: ServerRequest): {
author: Types.ObjectId;
authorName: string;
tenantId?: string;
} | null {
const user = req.user as
| {
id?: string;
_id?: Types.ObjectId | string;
name?: string;
username?: string;
tenantId?: string;
}
| undefined;
if (!user?.id) {
return null;
}
return {
author: (user._id ?? user.id) as Types.ObjectId,
authorName: user.name ?? user.username ?? 'Unknown',
...(user.tenantId ? { tenantId: user.tenantId } : {}),
};
}
function formatRange(start: number, count: number): string {
return count === 1 ? String(start) : `${start},${count}`;
}
function createUnifiedDiff(filePath: string, oldContent: string, newContent: string): string {
if (oldContent === newContent) {
return '';
}
const oldLines = oldContent.split('\n');
const newLines = newContent.split('\n');
let prefix = 0;
while (
prefix < oldLines.length &&
prefix < newLines.length &&
oldLines[prefix] === newLines[prefix]
) {
prefix += 1;
}
let oldSuffix = oldLines.length - 1;
let newSuffix = newLines.length - 1;
while (
oldSuffix >= prefix &&
newSuffix >= prefix &&
oldLines[oldSuffix] === newLines[newSuffix]
) {
oldSuffix -= 1;
newSuffix -= 1;
}
const contextStart = Math.max(0, prefix - 3);
const oldContextEnd = Math.min(oldLines.length - 1, oldSuffix + 3);
const newContextEnd = Math.min(newLines.length - 1, newSuffix + 3);
const oldCount = oldContextEnd >= contextStart ? oldContextEnd - contextStart + 1 : 0;
const newCount = newContextEnd >= contextStart ? newContextEnd - contextStart + 1 : 0;
const lines = [
`--- a/${filePath}`,
`+++ b/${filePath}`,
`@@ -${formatRange(contextStart + 1, oldCount)} +${formatRange(contextStart + 1, newCount)} @@`,
];
for (let i = contextStart; i < prefix; i++) {
lines.push(` ${oldLines[i]}`);
}
for (let i = prefix; i <= oldSuffix; i++) {
lines.push(`-${oldLines[i]}`);
}
for (let i = prefix; i <= newSuffix; i++) {
lines.push(`+${newLines[i]}`);
}
for (let i = oldSuffix + 1; i <= oldContextEnd; i++) {
lines.push(` ${oldLines[i]}`);
}
return lines.join('\n');
}
/**
* Extensions whose contents `read_file` must never serialize as text. `cat`
* on a PNG inside the sandbox returns the raw bytes as stdout, JSON-encoded
* by codeapi with lossy UTF-8 replacement and then line-numbered by us —
* the result is a multi-KB blob of mojibake that pollutes the LLM context
* and exposes the raw bytes anyway. Short-circuit before the network call.
*
* Image categories surface a "use the existing attachment" message because
* the file was already attached to the conversation as part of the
* code-execution artifact pipeline — re-attaching here would dup it.
*/
const BINARY_EXTENSIONS_NEVER_READABLE = new Set([
// Raster images (already attached as artifacts by the code-execution
// pipeline). `.svg` is intentionally NOT in this list — it's an XML
// text format with no mojibake risk, and there are legitimate reasons
// for the model to inspect or edit a generated SVG. The post-fetch
// NUL-byte sniff still catches anything that turns out to be binary
// despite a `.svg` extension.
'.png',
'.jpg',
'.jpeg',
'.gif',
'.webp',
'.bmp',
'.tiff',
'.tif',
'.ico',
'.heic',
'.heif',
'.avif',
// Documents (binary container formats)
'.pdf',
'.doc',
'.docx',
'.xls',
'.xlsx',
'.ppt',
'.pptx',
'.potx',
'.odt',
'.ods',
'.odp',
// Archives
'.zip',
'.tar',
'.gz',
'.tgz',
'.bz2',
'.xz',
'.7z',
'.rar',
'.lz4',
'.zst',
// Audio / video
'.mp3',
'.wav',
'.flac',
'.ogg',
'.m4a',
'.aac',
'.wma',
'.mp4',
'.mkv',
'.mov',
'.avi',
'.webm',
'.flv',
'.m4v',
// Executables / object files / native libs
'.exe',
'.dll',
'.so',
'.dylib',
'.o',
'.obj',
'.a',
'.lib',
'.bin',
'.class',
'.jar',
// Other byte-soup formats
'.parquet',
'.bson',
'.db',
'.sqlite',
'.sqlite3',
'.pyc',
'.pyo',
'.wasm',
'.ttf',
'.otf',
'.woff',
'.woff2',
'.eot',
]);
const IMAGE_EXTENSIONS_FOR_HINT = new Set([
'.png',
'.jpg',
'.jpeg',
'.gif',
'.webp',
'.bmp',
'.tiff',
'.tif',
'.ico',
'.heic',
'.heif',
'.avif',
]);
function lowercaseExtension(filePath: string): string {
const dot = filePath.lastIndexOf('.');
const slash = Math.max(filePath.lastIndexOf('/'), filePath.lastIndexOf('\\'));
if (dot < 0 || dot < slash) return '';
return filePath.slice(dot).toLowerCase();
}
/**
* Builds the model-visible error returned when `read_file` is invoked on
* a binary path. Phrasing is tuned for the LLM: states the fact (file is
* binary, can't be read as text), points at the correct affordance for
* each common case (image via bash bytes; bash for everything else), and
* includes the path verbatim so the model can copy-paste into its next
* call. Supported raster images take the inline-attachment path first (see
* `handleSandboxImageRead`); this image branch is only reached when that
* read is unavailable (codeapi off) or fails.
*/
function buildBinaryFileError(filePath: string, ext: string): string {
if (IMAGE_EXTENSIONS_FOR_HINT.has(ext)) {
return `"${filePath}" is an image file (${ext}) and cannot be read as text. To process it programmatically, use \`bash_tool\` (e.g. \`file ${filePath}\` for metadata, or \`python3 -c '...'\` to operate on the bytes).`;
}
return `"${filePath}" is a binary file (${ext}) and cannot be read as text by \`read_file\`. Use \`bash_tool\` to process it (e.g. \`file ${filePath}\` for metadata, or a runtime-appropriate command for the format).`;
}
/**
* Sandbox file extensions `read_file` attempts to inline as visual content.
* The extension only decides ROUTING (try the base64 image read vs the text
* / bash path); the emitted MIME comes from the magic-byte sniff so the
* declared type always matches the actual bytes. Scoped to the four raster
* formats the providers accept in tool results (`IMAGE_MIMES`); other image
* extensions (`.bmp`, `.tiff`, `.svg`, ...) stay on the text / bash path.
*/
const SANDBOX_IMAGE_EXTENSIONS = new Set<string>(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
/**
* Magic-byte sniff for the raster formats we inline. Preferred over the
* extension so a mislabelled `.png` that is really a JPEG is declared with
* the MIME the provider will actually validate the bytes against. Returns
* `undefined` when the header matches none of the supported formats.
*/
function sniffImageMime(buffer: Buffer): string | undefined {
if (buffer.length < 4) return undefined;
if (
buffer.length >= 8 &&
buffer[0] === 0x89 &&
buffer[1] === 0x50 &&
buffer[2] === 0x4e &&
buffer[3] === 0x47
) {
return 'image/png';
}
if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
return 'image/jpeg';
}
if (
buffer.length >= 6 &&
buffer[0] === 0x47 &&
buffer[1] === 0x49 &&
buffer[2] === 0x46 &&
buffer[3] === 0x38
) {
return 'image/gif';
}
if (
buffer.length >= 12 &&
buffer[0] === 0x52 &&
buffer[1] === 0x49 &&
buffer[2] === 0x46 &&
buffer[3] === 0x46 &&
buffer[8] === 0x57 &&
buffer[9] === 0x45 &&
buffer[10] === 0x42 &&
buffer[11] === 0x50
) {
return 'image/webp';
}
return undefined;
}
/**
* Cheap structural check that the image bytes are complete, not just that the
* header sniffed valid — a truncated/interrupted write can keep a valid magic
* prefix while the body is missing, which would then fail `saveBase64Image`
* resizing or the next provider request instead of the intended bash-hint
* fallback. Only png (fixed 8-byte IEND trailer) and webp (self-describing
* RIFF size) have a false-positive-free end marker; jpeg/gif can legitimately
* carry trailing metadata, so those stay at header-level sniffing rather than
* risk rejecting a valid file.
*/
function isCompleteImage(buffer: Buffer, mime: string): boolean {
if (mime === 'image/png') {
if (buffer.length < 8) return false;
const iend = buffer.subarray(buffer.length - 8);
return (
iend[0] === 0x49 &&
iend[1] === 0x45 &&
iend[2] === 0x4e &&
iend[3] === 0x44 &&
iend[4] === 0xae &&
iend[5] === 0x42 &&
iend[6] === 0x60 &&
iend[7] === 0x82
);
}
if (mime === 'image/webp') {
if (buffer.length < 12) return false;
return buffer.readUInt32LE(4) === buffer.length - 8;
}
return true;
}
/**
* Builds the `read_file` success result for an image: a short text line the
* model reads plus the `image_url` block in `artifact.content`. The SDK
* folds `artifact.content` into what the model sees (Anthropic tool_result
* or a trailing Human message for OpenAI/Google), and the host tool-end
* callback saves the same data URL as a viewable attachment. Shared by the
* skill-file and sandbox read paths so both surface images identically.
*/
function buildImageArtifactResult(
toolCallId: string,
displayPath: string,
mimeType: string,
bytes: number,
base64: string,
): ToolExecuteResult {
return {
toolCallId,
status: 'success',
content: `Image: ${displayPath} (${bytes} bytes, ${mimeType})`,
artifact: {
content: [{ type: 'image_url', image_url: { url: `data:${mimeType};base64,${base64}` } }],
},
};
}
/** True when bounded authored or fetched content contains a NUL byte. */
function looksBinary(content: string): boolean {
for (let i = 0; i < content.length; i++) {
if (content.charCodeAt(i) === 0) return true;
}
return false;
}
/**
* Model-visible error for an image the sandbox could not hand back. The
* read is a supported operation that FAILED, so the message must not reuse
* the "images cannot be read as text" phrasing — that reads as a permanent
* capability limit and stops the model from ever retrying. State the real
* cause and the affordance that matches it: a rate-limited or truncated
* read is worth retrying, a missing path is worth listing, and only a
* genuine transport dead end falls back to `bash_tool`. Classification is
* by message, matching how `isSandboxMissingFileError` already reads
* sandbox failures; the rate-limit wording is the one `readSandboxImage`
* throws when the Code API limiter turns a chunk away.
*/
function buildImageReadError(filePath: string, reason: string): string {
const detail = reason.replace(/\.$/, '');
if (isMissingSandboxPathError(reason)) {
return `"${filePath}" was not found in the code-execution sandbox (${detail}). List the directory with \`bash_tool\` (e.g. \`ls /mnt/data\`) to find the correct path.`;
}
if (/rate limit/i.test(reason)) {
return `Could not read image "${filePath}": ${detail}. Wait for the sandbox to accept requests again, then read it once more.`;
}
return `Could not read image "${filePath}" from the code-execution sandbox: ${detail}. Retry the read; if it keeps failing, inspect the file with \`bash_tool\` (e.g. \`file ${filePath}\`).`;
}
/**
* Reads a sandbox image as a viewable artifact so `read_file` can hand the
* bytes to vision-capable models instead of refusing them. Fetches the file
* base64-encoded from the sandbox (`readSandboxImage`), verifies the decoded
* length matches the size the sandbox reported (guards against codeapi
* truncating a large `/exec` stdout into a corrupt image), sniffs the real
* MIME, and returns the shared image-artifact result. Never throws: a
* mislabeled or corrupt image degrades to the binary hint, while a failed
* read reports what actually went wrong (see {@link buildImageReadError}).
*/
async function handleSandboxImageRead(
tc: ToolCallRequest,
filePath: string,
ext: string,
options: ToolExecuteOptions,
req?: ServerRequest,
codeExecutionContext?: CodeExecutionContext,
onSuccess?: () => void,
signal?: AbortSignal,
): Promise<ToolExecuteResult> {
const filtered = filteredBinaryFileResult(tc, req, filePath);
if (filtered != null) {
return filtered;
}
const { readSandboxImage } = options;
const binaryHint = (): ToolExecuteResult => ({
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: buildBinaryFileError(filePath, ext),
});
const readFailure = (reason: string): ToolExecuteResult => ({
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: buildImageReadError(filePath, reason),
});
if (!readSandboxImage) {
return binaryHint();
}
const ctx = tc.codeSessionContext as SandboxSessionContext | undefined;
let read:
| { base64: string; bytes: number }
| { tooLarge: true; reason?: 'size' | 'round_trips'; bytes: number; inlineCeiling?: number }
| null;
try {
read = await readSandboxImage({
file_path: filePath,
session_id: ctx?.session_id,
files: ctx?.files,
maxBytes: MAX_SANDBOX_INLINE_IMAGE_BYTES,
...(signal ? { signal } : {}),
...codeExecutionRequestParams(codeExecutionContext),
...(req ? { req } : {}),
});
} catch (error) {
const message = getThrownValueMessage(error);
logger.warn(`[handleReadFileCall] Sandbox image read failed for "${filePath}": ${message}`);
return readFailure(message);
}
if (!read) {
return binaryHint();
}
if ('tooLarge' in read) {
onSuccess?.();
/* Name the size that would actually work: each window costs one sandbox
* execution, so what can be inlined depends on the runner's stdout
* budget, not only on the byte cap. Without a target the model can only
* guess how far to downscale. */
const ceiling =
read.reason === 'round_trips' && read.inlineCeiling != null
? read.inlineCeiling
: MAX_SANDBOX_INLINE_IMAGE_BYTES;
const overBudget =
read.reason === 'round_trips'
? `more than this sandbox can return inline (about ${ceiling} bytes)`
: `over the ${MAX_SANDBOX_INLINE_IMAGE_BYTES}-byte inline limit`;
return {
toolCallId: tc.id,
status: 'success',
content: `Image "${filePath}" is ${read.bytes} bytes, ${overBudget}. Downscale it under ${ceiling} bytes in the sandbox with \`bash_tool\` and read the smaller copy to view it, or inspect it with \`bash_tool\` (e.g. \`file ${filePath}\` for metadata).`,
};
}
const buffer = Buffer.from(read.base64, 'base64');
if (buffer.length !== read.bytes) {
logger.warn(
`[handleReadFileCall] Sandbox image byte mismatch for "${filePath}" (decoded ${buffer.length} != reported ${read.bytes})`,
);
return readFailure(
`the sandbox returned ${buffer.length} of ${read.bytes} bytes (truncated transfer)`,
);
}
// Resolve the MIME from the actual bytes, never the extension: a file
// routed here by its `.png`/`.jpg`/... name whose header matches none of
// the supported formats is a mislabeled non-image (a renamed .txt/.pdf).
// Refuse it (and any truncated/incomplete image) with the bash hint
// instead of shipping bytes the provider would reject as a corrupt image.
const mimeType = sniffImageMime(buffer);
if (!mimeType || !isCompleteImage(buffer, mimeType)) {
return binaryHint();
}
onSuccess?.();
return buildImageArtifactResult(tc.id, filePath, mimeType, buffer.length, read.base64);
}
/**
* Routes a `read_file` call to the code-execution sandbox via the
* host-provided `readSandboxFile` callback. The sandbox session id and
* primed file refs come from `tc.codeSessionContext` (emitted by ToolNode
* for `read_file` tool calls in agents v3.1.72+) so the read lands in the
* same session that holds the agent's prior-turn artifacts. Returns a
* `ToolExecuteResult` with the file content (line-numbered) on success,
* or an instructive error pointing the model at `bash_tool` when the
* sandbox isn't reachable from this configuration.
*
* Supported raster images (`.png/.jpg/.jpeg/.gif/.webp`) take a dedicated
* base64 read path (`handleSandboxImageRead`) so the model can actually see
* them. Two binary guards then keep `cat`-on-a-PNG-style mojibake out of the
* LLM context for everything else: (1) an extension precheck that short-
* circuits known binary types BEFORE any network call, and (2) a NUL-byte
* content sniff after the read for unknown extensions. The codeapi `/exec`
* transport is JSON, which lossily down-converts non-UTF-8 `cat` stdout to
* replacement characters — text bytes are unrecoverable there, so the goal
* is to fail fast with an instructive message rather than ship garbage.
*/
async function handleSandboxFileFallback(
tc: ToolCallRequest,
filePath: string,
options: ToolExecuteOptions,
req?: ServerRequest,
codeExecutionContext?: CodeExecutionContext,
onSuccess?: () => void,
signal?: AbortSignal,
): Promise<ToolExecuteResult> {
const ext = lowercaseExtension(filePath);
if (SANDBOX_IMAGE_EXTENSIONS.has(ext)) {
return handleSandboxImageRead(
tc,
filePath,
ext,
options,
req,
codeExecutionContext,
onSuccess,
signal,
);
}
const filteredName = filteredFileNameResult(tc, req, filePath);
if (filteredName != null) {
return filteredName;
}
if (BINARY_EXTENSIONS_NEVER_READABLE.has(ext)) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: buildBinaryFileError(filePath, ext),
};
}
const { readSandboxFile } = options;
if (!readSandboxFile) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Path "${filePath}" is not a skill file. Use \`bash_tool\` to read code-execution sandbox files (e.g. \`cat ${filePath}\`).`,
};
}
const rangeArgs = tc.args as ReadFileRangeArguments;
const ranged = rangeArgs.start_line !== undefined || rangeArgs.max_lines !== undefined;
if (ranged && resolveReadFileRange(rangeArgs) == null)
return errorResult(tc, READ_FILE_RANGE_ERROR);
const ctx = tc.codeSessionContext as SandboxSessionContext | undefined;
try {
const result = await readSandboxFile({
file_path: filePath,
session_id: ctx?.session_id,
files: ctx?.files,
...codeExecutionRequestParams(codeExecutionContext),
...(req ? { req } : {}),
...(ranged ? { maxBytes: MAX_READABLE_BYTES, ...(signal ? { signal } : {}) } : {}),
});
if (result != null && 'tooLarge' in result) {
return errorResult(
tc,
`Sandbox file could not be retrieved completely within the ${MAX_READABLE_BYTES}-byte read budget. Use bash_tool to inspect it.`,
);
}
if (ranged && result != null && result.complete !== true) {
return errorResult(
tc,
'Sandbox text retrieval was incomplete. Use bash_tool to inspect the file.',
);
}
if (!result || result.content == null) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Failed to read "${filePath}" from the code-execution sandbox. Try \`bash_tool\` (e.g. \`cat ${filePath}\`).`,
};
}
const filtered = filteredFileResult(tc, req, filePath, result.content);
if (filtered != null) {
return filtered;
}
if (looksBinary(result.content)) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `"${filePath}" appears to be a binary file and cannot be read as text. Use \`bash_tool\` to process it (e.g. \`file ${filePath}\` for metadata).`,
};
}
/**
* Cap before line-numbering. `addLineNumbers` allocates a SECOND
* full-size string with per-line prefixes, so a multi-MB log read
* would materialize ~2x in memory before downstream truncation
* kicks in. Match the skill-file path's `MAX_READABLE_BYTES`
* (256KB) ceiling: truncate the raw content first, then number,
* and surface the truncation to the model so it can use
* `bash_tool head` / `tail` for the rest.
*/
if (ranged) {
const rangedResult = localTextReadResult(tc, filePath, result.content);
if (rangedResult.status === 'success') onSuccess?.();
return rangedResult;
}
let payload = result.content;
let truncated = false;
if (payload.length > MAX_READABLE_BYTES) {
payload = payload.slice(0, MAX_READABLE_BYTES);
truncated = true;
}
let numbered = formatReadFileText(payload, filePath);
if (truncated) {
numbered += `\n\n[truncated at ${MAX_READABLE_BYTES} bytes — use \`bash_tool\` (e.g. \`head -c\` / \`tail\`) to read the rest of "${filePath}"]`;
}
onSuccess?.();
return {
toolCallId: tc.id,
status: 'success',
content: numbered,
};
} catch (error) {
if (signal?.aborted === true && isAbortError(error)) throw error;
const message = error instanceof Error ? error.message : String(error);
logger.warn('[handleReadFileCall] Sandbox fallback failed', getSafeErrorMetadata(error));
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Error reading "${filePath}" from the code-execution sandbox: ${message}. Try \`bash_tool\` (e.g. \`cat ${filePath}\`).`,
};
}
}
async function handleWorkspaceFileRead(
tc: ToolCallRequest,
filePath: string,
options: ToolExecuteOptions,
req: ServerRequest | undefined,
codeExecutionContext: CodeExecutionContext,
signal?: AbortSignal,
): Promise<ToolExecuteResult> {
const { readWorkspaceFile } = options;
if (!readWorkspaceFile) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'Attached workspace reading is not configured.',
};
}
const workspaceId = selectedWorkspaceId(codeExecutionContext, 'read_file');
if (!workspaceId) return unavailableWorkspaceOperation(tc, 'read_file');
const args = tc.args as { start_line?: number; max_lines?: number };
const range = resolveReadFileRange(
args,
resolveAttachedWorkspaceReadFileLines(codeExecutionContext.codeEnvironmentConfigSchema),
);
if (filePath.length === 0) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'A relative path after workspace/ is required.',
};
}
if (range == null) return errorResult(tc, READ_FILE_RANGE_ERROR);
const filteredName = filteredFileNameResult(tc, req, filePath);
if (filteredName != null) {
return filteredName;
}
try {
const result = await readWorkspaceFile({
file_path: filePath,
workspace_id: workspaceId,
...(codeExecutionContext.codeWorkspace?.workspaceInstanceId
? { workspace_instance_id: codeExecutionContext.codeWorkspace.workspaceInstanceId }
: {}),
...(codeExecutionContext.codeWorkspace?.linkedWorktrees ? { linked_worktrees: true } : {}),
start_line: range.startLine,
max_lines: range.maxLines,
codeApiBaseUrl: codeExecutionContext.baseUrl,
...attachedWorkspaceRequestLimits(codeExecutionContext),
executionProfile: codeExecutionContext.executionProfile,
...(codeExecutionContext.bridgeWorkerId
? { bridgeWorkerId: codeExecutionContext.bridgeWorkerId }
: {}),
...(req ? { req } : {}),
...(signal ? { signal } : {}),
});
const filtered = filteredFileResult(tc, req, filePath, result.content);
if (filtered != null) {
return filtered;
}
if (looksBinary(result.content)) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `"${filePath}" appears to be a binary file and cannot be read as text.`,
};
}
return successResult(
tc,
formatReadFileText(result.content, `workspace/${filePath}`, undefined, {
startLine: result.startLine,
...(result.truncated && result.nextStartLine != null
? { nextStartLine: result.nextStartLine }
: {}),
}),
);
} catch (error) {
if (error instanceof WorkspaceToolHttpError) {
throw explainWorkspacePathRejection(error, 'read', `workspace/${filePath}`);
}
if (signal?.aborted === true && isAbortError(error)) throw error;
logger.warn(
'[handleWorkspaceFileRead] Attached workspace read failed',
getSafeErrorMetadata(error),
);
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `"${filePath}" could not be read from the attached workspace.`,
};
}
}
async function handleWorkspaceSearchCall(
tc: ToolCallRequest,
mergedConfigurable: Record<string, unknown> | undefined,
options: ToolExecuteOptions,
req: ServerRequest | undefined,
signal?: AbortSignal,
): Promise<ToolExecuteResult> {
const codeExecutionContext = getCodeExecutionContext(mergedConfigurable ?? {});
if (
mergedConfigurable?.codeEnvAvailable !== true ||
codeExecutionContext?.environmentType !== 'attached'
) {
return errorResult(tc, 'search_workspace requires an attached code environment.');
}
if (!options.searchWorkspace) {
return errorResult(tc, 'Attached workspace search is not configured.');
}
const workspaceId = selectedWorkspaceId(codeExecutionContext, 'search_text');
if (!workspaceId) return unavailableWorkspaceOperation(tc, 'search_text');
const args = tc.args as { query?: unknown; path?: unknown; max_results?: unknown };
const maxResults = args.max_results ?? 50;
if (
typeof args.query !== 'string' ||
args.query.length === 0 ||
args.query.length > 4096 ||
(args.path != null && typeof args.path !== 'string') ||
!Number.isSafeInteger(maxResults) ||
Number(maxResults) < 1 ||
Number(maxResults) > 200
) {
return errorResult(tc, 'query, path, or max_results is invalid for workspace search.');
}
try {
const result = await options.searchWorkspace({
query: args.query,
workspace_id: workspaceId,
...(codeExecutionContext.codeWorkspace?.workspaceInstanceId
? { workspace_instance_id: codeExecutionContext.codeWorkspace.workspaceInstanceId }
: {}),
...(codeExecutionContext.codeWorkspace?.linkedWorktrees ? { linked_worktrees: true } : {}),
...(typeof args.path === 'string' && args.path.length > 0 ? { path: args.path } : {}),
max_results: Number(maxResults),
codeApiBaseUrl: codeExecutionContext.baseUrl,
...attachedWorkspaceRequestLimits(codeExecutionContext),
executionProfile: codeExecutionContext.executionProfile,
...(codeExecutionContext.bridgeWorkerId
? { bridgeWorkerId: codeExecutionContext.bridgeWorkerId }
: {}),
...(req ? { req } : {}),
...(signal ? { signal } : {}),
});
for (const match of result.matches) {
const filtered = filteredFileResult(tc, req, match.path, match.text);
if (filtered != null) return filtered;
}
const unboundedContent =
result.matches.length === 0
? 'No matches found.'
: result.matches
.map((match) => `workspace/${match.path}:${match.line}:${match.column}: ${match.text}`)
.join('\n');
const truncationNotice = '\n\n[results truncated]';
const locallyTruncated = Buffer.byteLength(unboundedContent, 'utf8') > MAX_READABLE_BYTES;
const truncated = locallyTruncated || result.truncated;
const content = truncated
? truncateUtf8(
unboundedContent,
MAX_READABLE_BYTES - Buffer.byteLength(truncationNotice, 'utf8'),
)
: unboundedContent;
return {
toolCallId: tc.id,
status: 'success',
content: truncated ? `${content}${truncationNotice}` : content,
};
} catch (error) {
if (error instanceof WorkspaceToolHttpError) {
throw explainWorkspacePathRejection(
error,
'search',
`workspace/${typeof args.path === 'string' ? args.path : ''}`,
);
}
if (signal?.aborted === true && isAbortError(error)) throw error;
logger.warn(
'[handleWorkspaceSearchCall] Attached workspace search failed',
getSafeErrorMetadata(error),
);
return errorResult(tc, 'The attached workspace could not be searched.');
}
}
async function handleWorkspaceListCall(
tc: ToolCallRequest,
mergedConfigurable: Record<string, unknown> | undefined,
options: ToolExecuteOptions,
req: ServerRequest | undefined,
signal?: AbortSignal,
): Promise<ToolExecuteResult> {
const codeExecutionContext = getCodeExecutionContext(mergedConfigurable ?? {});
if (
mergedConfigurable?.codeEnvAvailable !== true ||
codeExecutionContext?.environmentType !== 'attached'
) {
return errorResult(tc, 'list_workspace_files requires an attached code environment.');
}
if (!options.listWorkspaceFiles) {
return errorResult(tc, 'Attached workspace file listing is not configured.');
}
const workspaceId = selectedWorkspaceId(codeExecutionContext, 'list_files');
if (!workspaceId) return unavailableWorkspaceOperation(tc, 'list_files');
const args = tc.args as { path?: unknown; after_path?: unknown; max_results?: unknown };
const maxResults = args.max_results ?? 100;
if (
(args.path != null && typeof args.path !== 'string') ||
(args.after_path != null && typeof args.after_path !== 'string') ||
!Number.isSafeInteger(maxResults) ||
Number(maxResults) < 1 ||
Number(maxResults) > 500
) {
return errorResult(
tc,
'path, after_path, or max_results is invalid for workspace file listing.',
);
}
try {
const result = await options.listWorkspaceFiles({
workspace_id: workspaceId,
...(codeExecutionContext.codeWorkspace?.workspaceInstanceId
? { workspace_instance_id: codeExecutionContext.codeWorkspace.workspaceInstanceId }
: {}),
...(codeExecutionContext.codeWorkspace?.linkedWorktrees ? { linked_worktrees: true } : {}),
...(typeof args.path === 'string' && args.path.length > 0 ? { path: args.path } : {}),
...(typeof args.after_path === 'string' && args.after_path.length > 0
? { after_path: args.after_path }
: {}),
max_results: Number(maxResults),
codeApiBaseUrl: codeExecutionContext.baseUrl,
...attachedWorkspaceRequestLimits(codeExecutionContext),
executionProfile: codeExecutionContext.executionProfile,
...(codeExecutionContext.bridgeWorkerId
? { bridgeWorkerId: codeExecutionContext.bridgeWorkerId }
: {}),
...(req ? { req } : {}),
...(signal ? { signal } : {}),
});
for (const path of result.paths) {
const filtered = filteredFileNameResult(tc, req, path);
if (filtered != null) return filtered;
}
if (result.paths.length === 0) {
return {
toolCallId: tc.id,
status: 'success',
content: 'The attached workspace contains no discoverable files in that path.',
};
}
const renderedPaths: string[] = [];
let content = '';
let contentBytes = 0;
for (const [index, path] of result.paths.entries()) {
const entry = `workspace/${path}`;
const separator = renderedPaths.length > 0 ? '\n' : '';
const hasMore = index < result.paths.length - 1 || result.truncated;
const notice = hasMore
? `\n\n[results truncated; continue with after_path: ${JSON.stringify(path)}]`
: '';
const entryBytes = Buffer.byteLength(`${separator}${entry}`, 'utf8');
if (contentBytes + entryBytes + Buffer.byteLength(notice, 'utf8') > MAX_READABLE_BYTES) {
break;
}
renderedPaths.push(entry);
content += `${separator}${entry}`;
contentBytes += entryBytes;
}
const locallyTruncated = renderedPaths.length < result.paths.length;
const continuationPath = locallyTruncated
? result.paths[renderedPaths.length - 1]
: result.nextAfterPath;
const truncated = locallyTruncated || result.truncated;
const truncationNotice = truncated
? `\n\n[results truncated; continue with after_path: ${JSON.stringify(continuationPath)}]`
: '';
return {
toolCallId: tc.id,
status: 'success',
content: `${content}${truncationNotice}`,
};
} catch (error) {
if (error instanceof WorkspaceToolHttpError) {
throw explainWorkspacePathRejection(
error,
'list',
`workspace/${typeof args.path === 'string' ? args.path : ''}`,
);
}
if (signal?.aborted === true && isAbortError(error)) throw error;
logger.warn(
'[handleWorkspaceListCall] Attached workspace file listing failed',
getSafeErrorMetadata(error),
);
return errorResult(tc, 'The attached workspace files could not be listed.');
}
}
function sandboxSessionContext(
tc: ToolCallRequest,
override?: SandboxSessionContext,
): SandboxSessionContext | undefined {
return override ?? (tc.codeSessionContext as SandboxSessionContext | undefined);
}
function cloneSandboxSessionContext(
context: SandboxSessionContext | undefined,
): SandboxSessionContext {
return {
...(context?.session_id ? { session_id: context.session_id } : {}),
...(context?.files ? { files: context.files.map((file) => ({ ...file })) } : {}),
};
}
/** Storage identity of a mounted ref, matching the code session's own key. */
function sandboxFileIdentity(file: SandboxFileRef): string {
return `${file.storage_session_id ?? ''}\0${file.id}`;
}
/**
* Folds a host file-authoring result's `session_id` / `files` into the
* batch-local sandbox context that the next authoring call on the same path
* reuses, matching how the graph's own code session folds the same artifact:
* incoming refs win field by field, an existing ref superseded by storage
* identity or by name is dropped, and every other mounted ref survives.
*
* Both halves are load-bearing. Rebuilding refs from a field subset dropped
* `kind`, `resource_id`, `version` and `inherited`, and a primed skill file
* stripped of its `version` is an invalid input ref — the Code API requires
* it whenever `kind === 'skill'`. Replacing the list wholesale unmounted
* every file the run had primed but this particular write did not return.
*/
function mergeSandboxSessionArtifact(
context: SandboxSessionContext,
artifact: ToolExecuteResult['artifact'],
): void {
if (!artifact || typeof artifact !== 'object') {
return;
}
const value = artifact as {
session_id?: unknown;
files?: unknown;
};
if (typeof value.session_id === 'string' && value.session_id.length > 0) {
context.session_id = value.session_id;
}
if (!Array.isArray(value.files)) {
return;
}
const execSessionId = context.session_id;
const incoming: SandboxFileRef[] = [];
const incomingByIdentity = new Map<string, number>();
const incomingNames = new Set<string>();
for (const file of value.files) {
if (!file || typeof file !== 'object') {
continue;
}
const ref = file as SandboxFileRef;
if (typeof ref.id !== 'string' || typeof ref.name !== 'string') {
continue;
}
/* Carry the ref whole: the Code API reads fields this host never
* inspects, so a copy is a downgrade. Only the storage session is
* defaulted, and it resolves exactly as `getPreparedCodeOutputBuffer`
* resolves it — the legacy per-file `session_id` outranks the execution
* session, or an older Code API response would be remounted against the
* bucket that merely produced it. */
const merged: SandboxFileRef = { ...ref };
merged.storage_session_id ??= ref.session_id ?? execSessionId;
/* One artifact can name the same stored file twice. Fold the repeat into
* the entry already collected rather than mounting it again: codeapi
* rejects an `/exec` whose files collide on a destination, taking the
* whole call down with it. */
const identity = sandboxFileIdentity(merged);
const seen = incomingByIdentity.get(identity);
if (seen !== undefined) {
incoming[seen] = { ...incoming[seen], ...merged };
continue;
}
incomingByIdentity.set(identity, incoming.length);
incomingNames.add(merged.name);
incoming.push(merged);
}
if (incoming.length === 0) {
return;
}
const retained: SandboxFileRef[] = [];
for (const existing of context.files ?? []) {
const index = incomingByIdentity.get(sandboxFileIdentity(existing));
if (index !== undefined) {
incoming[index] = { ...existing, ...incoming[index] };
continue;
}
if (!incomingNames.has(existing.name)) {
retained.push(existing);
}
}
context.files = [...retained, ...incoming];
}
/**
* Broader than {@link isMissingSandboxPathError}: the authoring flow also
* treats a bare "not found" as an absent file, because a `cat` that cannot
* start is indistinguishable from a `cat` that found nothing as far as
* "should this create or overwrite?" is concerned.
*/
function isSandboxMissingFileError(error: unknown): boolean {
const message = getThrownValueMessage(error);
return isMissingSandboxPathError(message) || message.toLowerCase().includes('not found');
}
function invalidSandboxAuthoringPath(filePath: string): string | null {
if (filePath.length === 0) {
return 'path is required';
}
if (filePath.includes('\0')) {
return 'path cannot contain NUL bytes';
}
if (filePath.endsWith('/')) {
return `File path "${filePath}" points to a directory. Provide a file path.`;
}
return null;
}
async function loadSandboxTextForAuthoring({
filePath,
tc,
options,
req,
sandboxContext,
codeExecutionContext,
}: {
filePath: string;
tc: ToolCallRequest;
options: ToolExecuteOptions;
req?: ServerRequest;
sandboxContext?: SandboxSessionContext;
codeExecutionContext?: CodeExecutionContext;
}): Promise<LoadedSandboxText> {
const ext = lowercaseExtension(filePath);
if (BINARY_EXTENSIONS_NEVER_READABLE.has(ext)) {
return { status: 'error', message: buildBinaryFileError(filePath, ext) };
}
if (!options.readSandboxFile) {
return {
status: 'error',
message: `Sandbox file reading is not configured. Use \`bash_tool\` to inspect "${filePath}".`,
};
}
const ctx = sandboxSessionContext(tc, sandboxContext);
try {
const result = await options.readSandboxFile({
file_path: filePath,
session_id: ctx?.session_id,
files: ctx?.files,
...codeExecutionRequestParams(codeExecutionContext),
...(req ? { req } : {}),
});
if (result != null && 'tooLarge' in result) {
return {
status: 'error',
message: 'Sandbox file could not be retrieved completely. Use bash_tool to inspect it.',
};
}
if (!result || result.content == null) {
return {
status: 'error',
message: `Failed to read "${filePath}" from the code-execution sandbox.`,
};
}
if (looksBinary(result.content)) {
return {
status: 'error',
message: `"${filePath}" appears to be binary and cannot be edited as text.`,
};
}
if (Buffer.byteLength(result.content, 'utf8') > MAX_AUTHORING_BYTES) {
return {
status: 'error',
message: `File "${filePath}" is too large to edit directly (${Buffer.byteLength(
result.content,
'utf8',
)} bytes, limit: ${MAX_AUTHORING_BYTES}).`,
};
}
return {
status: 'loaded',
content: result.content,
bytes: Buffer.byteLength(result.content, 'utf8'),
};
} catch (error) {
if (isSandboxMissingFileError(error)) {
return { status: 'missing' };
}
const message = getThrownValueMessage(error);
logger.warn('[file_authoring] Sandbox read failed', getSafeErrorMetadata(error));
return {
status: 'error',
message: `Error reading "${filePath}" from the code-execution sandbox: ${message}.`,
};
}
}
async function writeSandboxTextForAuthoring({
tc,
options,
req,
filePath,
content,
oldContent,
created,
sandboxContext,
codeExecutionContext,
signal,
}: {
tc: ToolCallRequest;
options: ToolExecuteOptions;
req?: ServerRequest;
filePath: string;
content: string;
oldContent?: string;
created: boolean;
sandboxContext?: SandboxSessionContext;
codeExecutionContext?: CodeExecutionContext;
signal?: AbortSignal;
}): AuthoringResult {
if (!options.writeSandboxFile) {
return errorResult(
tc,
`Sandbox file writing is not configured. Use \`bash_tool\` to write "${filePath}".`,
);
}
const filtered = filteredFileResult(tc, req, filePath, content);
if (filtered != null) {
return filtered;
}
let diff =
oldContent !== undefined ? createUnifiedDiff(filePath, oldContent, content) : undefined;
if (
diff &&
(filteredFileResult(tc, req, filePath, oldContent ?? '') != null ||
filteredFileResult(tc, req, filePath, diff) != null)
) {
diff = undefined;
}
const ctx = sandboxSessionContext(tc, sandboxContext);
let writeResult: Awaited<ReturnType<NonNullable<ToolExecuteOptions['writeSandboxFile']>>>;
signal?.throwIfAborted();
try {
writeResult = await options.writeSandboxFile({
file_path: filePath,
content,
session_id: ctx?.session_id,
files: ctx?.files,
...codeExecutionRequestParams(codeExecutionContext),
...(req ? { req } : {}),
});
} catch (error) {
if (signal?.aborted === true && isAbortError(error)) throw error;
const message = getThrownValueMessage(error);
logger.warn('[file_authoring] Sandbox write failed', getSafeErrorMetadata(error));
return errorResult(
tc,
`Error writing "${filePath}" to the code-execution sandbox: ${message}.`,
);
}
if (!writeResult) {
return errorResult(tc, `Failed to write "${filePath}" to the code-execution sandbox.`);
}
if (writeResult.artifact_delivery) {
const { attempted, failed } = writeResult.artifact_delivery;
return errorResult(
tc,
`Wrote "${filePath}" in the sandbox, but ${failed} of ${attempted} generated files could not be persisted. The file is not guaranteed to be available to later calls or downloadable. The execution may have had side effects; do not retry automatically.`,
);
}
const action = created ? 'Created' : 'Updated';
const summary = `${action} ${filePath} (${content.length} chars).`;
return successResult(tc, diff ? `${summary}\n\n${diff}` : summary, {
path: filePath,
[HOST_FILE_AUTHORING_ARTIFACT_KEY]: true,
bytes_written: Buffer.byteLength(content, 'utf8'),
created,
...(diff ? { diff } : {}),
...(writeResult.session_id ? { session_id: writeResult.session_id } : {}),
...(writeResult.files ? { files: writeResult.files } : {}),
});
}
async function resolveSkillForAuthoring(
skillName: string,
mergedConfigurable: Record<string, unknown>,
options: ToolExecuteOptions,
): Promise<AuthoringSkill | null> {
const { getSkillByName } = options;
if (!getSkillByName) {
return null;
}
const skillPrimedIdsByName =
(mergedConfigurable?.skillPrimedIdsByName as Record<string, string> | undefined) ?? {};
const pinnedIdString =
getAuthoredSkillId(skillName, mergedConfigurable) ?? skillPrimedIdsByName[skillName];
if (pinnedIdString) {
return await getSkillByName(skillName, [new Types.ObjectId(pinnedIdString)], {});
}
const accessibleIds = (mergedConfigurable?.accessibleSkillIds as Types.ObjectId[]) ?? [];
if (accessibleIds.length === 0) {
return null;
}
return await getSkillByName(skillName, accessibleIds, { preferModelInvocable: true });
}
async function resolveAuthorSkillForCurrentUser({
skillName,
mergedConfigurable,
sourceConfigurable,
options,
req,
}: {
skillName: string;
mergedConfigurable: Record<string, unknown>;
sourceConfigurable?: Record<string, unknown>;
options: ToolExecuteOptions;
req?: ServerRequest;
}): Promise<AuthoringSkill | null> {
if (!req || !options.getAuthorSkillByName) {
return null;
}
if (!isSkillKnownToCurrentRun(skillName, mergedConfigurable)) {
return null;
}
const skill = await options.getAuthorSkillByName({ req, name: skillName });
const authoredId = getAuthoredSkillId(skillName, mergedConfigurable);
if (!skill || (authoredId != null && skill._id.toString() !== authoredId)) {
return null;
}
rememberAuthoredSkill([mergedConfigurable, sourceConfigurable], skill, { prime: false });
options.onSkillAuthored?.({ name: skill.name, id: skill._id.toString(), primed: false });
return skill;
}
function isDuplicateSkillNameError(error: unknown): boolean {
const maybeError = error as { code?: string | number; message?: string } | undefined;
return (
maybeError?.code === 11000 ||
/skill with name .* already exists/i.test(maybeError?.message ?? '')
);
}
function isSkillAuthoringAvailable(mergedConfigurable: Record<string, unknown>): boolean {
return mergedConfigurable.skillAuthoringAvailable === true;
}
/**
* Tells the model that the skill it just created is a legal `skill` target.
* Creation neither loads nor activates the skill, so the run has no other
* signal that the name became invocable. Only reachable on runs that can
* author skills, which are exactly the runs where the `skill` tool is
* registered (see `isSkillToolAvailable`).
*
* Suppressed for `disable-model-invocation: true`, which
* `handleSkillToolCall` rejects — advertising it would send the model into a
* guaranteed error.
*/
function authoredSkillInvocationHint(frontmatter: Record<string, unknown> | undefined): string {
return deriveStructuredFrontmatterFields(frontmatter).disableModelInvocation === true
? ''
: ' Invoke it with the skill tool when you want its instructions loaded.';
}
function getFileAuthoringToolNames(
mergedConfigurable: Record<string, unknown>,
): Set<string> | undefined {
const names = mergedConfigurable.fileAuthoringToolNames;
return names instanceof Set ? (names as Set<string>) : undefined;
}
function isHostFileAuthoringToolCall(
toolName: string,
mergedConfigurable: Record<string, unknown>,
): boolean {
return getFileAuthoringToolNames(mergedConfigurable)?.has(toolName) === true;
}
function isCodeSessionAwareToolCall(
toolName: string,
mergedConfigurable: Record<string, unknown>,
): boolean {
return isCodeSessionToolName(toolName, getFileAuthoringToolNames(mergedConfigurable));
}
function isSkillPrimedForAuthoring(
skillName: string,
mergedConfigurable: Record<string, unknown>,
): boolean {
const skillPrimedIdsByName =
(mergedConfigurable.skillPrimedIdsByName as Record<string, string> | undefined) ?? {};
const primedId = skillPrimedIdsByName[skillName];
const authoredId = getAuthoredSkillId(skillName, mergedConfigurable);
return typeof primedId === 'string' && (authoredId == null || authoredId === primedId);
}
function isSkillKnownToCurrentRun(
skillName: string,
mergedConfigurable: Record<string, unknown>,
): boolean {
if (isSkillPrimedForAuthoring(skillName, mergedConfigurable)) {
return true;
}
const activeSkillNames = mergedConfigurable.activeSkillNames;
return activeSkillNames instanceof Set && activeSkillNames.has(skillName);
}
function hiddenSkillAuthoringDenied(
tc: ToolCallRequest,
skill: AuthoringSkill | null,
skillName: string,
mergedConfigurable: Record<string, unknown>,
): ToolExecuteResult | null {
if (
skill?.disableModelInvocation !== true ||
isSkillPrimedForAuthoring(skillName, mergedConfigurable)
) {
return null;
}
return errorResult(tc, `Skill "${skillName}" cannot be authored by the model`);
}
function mergeAccessibleSkillIds(
base: Record<string, unknown> | undefined,
loaded: Record<string, unknown> | undefined,
): Types.ObjectId[] | undefined {
const values = [
...(Array.isArray(loaded?.accessibleSkillIds)
? (loaded.accessibleSkillIds as Types.ObjectId[])
: []),
...(Array.isArray(base?.accessibleSkillIds)
? (base.accessibleSkillIds as Types.ObjectId[])
: []),
];
if (values.length === 0) {
return undefined;
}
const seen = new Set<string>();
const merged: Types.ObjectId[] = [];
for (const value of values) {
const key = value.toString();
if (seen.has(key)) {
continue;
}
seen.add(key);
merged.push(value);
}
return merged;
}
function mergeSkillPrimedIdsByName(
base: Record<string, unknown> | undefined,
loaded: Record<string, unknown> | undefined,
): Record<string, string> | undefined {
const loadedPrimed = loaded?.skillPrimedIdsByName as Record<string, string> | undefined;
const basePrimed = base?.skillPrimedIdsByName as Record<string, string> | undefined;
const merged = { ...(loadedPrimed ?? {}), ...(basePrimed ?? {}) };
return Object.keys(merged).length > 0 ? merged : undefined;
}
function mergeAuthoredSkillIdsByName(
base: Record<string, unknown> | undefined,
loaded: Record<string, unknown> | undefined,
): Record<string, string> | undefined {
const loadedAuthored = loaded?.authoredSkillIdsByName as Record<string, string> | undefined;
const baseAuthored = base?.authoredSkillIdsByName as Record<string, string> | undefined;
const merged = { ...(loadedAuthored ?? {}), ...(baseAuthored ?? {}) };
return Object.keys(merged).length > 0 ? merged : undefined;
}
/**
* The `_id` this run's authoring path bound to a skill name, when it bound one.
*
* Deliberately separate from `skillPrimedIdsByName`: that map also carries
* manual (`$`) and always-apply primes and doubles as the switch that relaxes
* the `disable-model-invocation` gate for primed bodies, so widening its
* meaning would change how those primes resolve. This map carries identity
* only, for the names this run authored.
*/
function getAuthoredSkillId(
skillName: string,
mergedConfigurable: Record<string, unknown> | undefined,
): string | undefined {
const authoredIds = mergedConfigurable?.authoredSkillIdsByName as
| Record<string, string>
| undefined;
const id = authoredIds?.[skillName];
return typeof id === 'string' && id.length > 0 ? id : undefined;
}
function mergeActiveSkillNames(
base: Record<string, unknown> | undefined,
loaded: Record<string, unknown> | undefined,
): Set<string> | undefined {
const names = new Set<string>();
const loadedNames = loaded?.activeSkillNames;
if (loadedNames instanceof Set) {
for (const name of loadedNames) {
names.add(name);
}
}
const baseNames = base?.activeSkillNames;
if (baseNames instanceof Set) {
for (const name of baseNames) {
names.add(name);
}
}
return names.size > 0 ? names : undefined;
}
/**
* True for MCP tools on an ephemeral request-scoped connection (runtime body
* placeholders), tagged in `createToolInstance`. Their connection is torn down
* at request end, so they must run in the foreground rather than be backgrounded.
*/
function toolRequiresEphemeralConnection(tool: StructuredToolInterface | undefined): boolean {
return (
(tool as (StructuredToolInterface & { mcpRequiresEphemeralConnection?: boolean }) | undefined)
?.mcpRequiresEphemeralConnection === true
);
}
const EMPTY_BACKGROUND_TOOL_SET: ReadonlySet<string> = new Set();
/**
* Authenticated user id for background-task scoping. The in-repo routes merge
* `req` into the tool-execute configurable, but external hosts of the exported
* OpenAI-compatible service inject their own `loadTools` and may not — fall
* back to the run configurable's user identity so tasks are never registered
* under an empty user id (which would collapse isolation to conversationId).
*/
function resolveBackgroundUserId(configurable: Record<string, unknown> | undefined): string {
const req = configurable?.req as ServerRequest | undefined;
if (req?.user?.id) {
return req.user.id;
}
const userId = configurable?.user_id;
if (typeof userId === 'string' && userId !== '') {
return userId;
}
const user = configurable?.user;
if (typeof user === 'string') {
return user;
}
const idFromUser = (user as { id?: string } | undefined)?.id;
return typeof idFromUser === 'string' ? idFromUser : '';
}
/**
* True when the tool's own schema declares `run_in_background` (zod shape or
* raw JSON schema), i.e. the parameter belongs to the tool rather than being
* host-injected — such a tool must receive the argument untouched.
*/
function toolDeclaresRunInBackgroundParam(tool: StructuredToolInterface): boolean {
const schema = (
tool as StructuredToolInterface & {
schema?: { shape?: Record<string, unknown>; properties?: Record<string, unknown> };
}
).schema;
if (schema == null) {
return false;
}
return (
schema.shape?.[RUN_IN_BACKGROUND_ARG] != null ||
schema.properties?.[RUN_IN_BACKGROUND_ARG] != null
);
}
/**
* True when the tool's own schema declares `intent` (zod shape or raw JSON
* schema) — SDK-native intent tools do, so they receive the argument
* untouched and handle it themselves; host-injected tools do not, so the
* arg is stripped before invocation.
*/
function toolDeclaresIntentParam(tool: StructuredToolInterface): boolean {
const schema = (
tool as StructuredToolInterface & {
schema?: { shape?: Record<string, unknown>; properties?: Record<string, unknown> };
}
).schema;
if (schema == null) {
return false;
}
return schema.shape?.[INTENT_ARG] != null || schema.properties?.[INTENT_ARG] != null;
}
/**
* Strips the host-injected `intent` label from invoke args unless the tool's
* own schema declares it. The label rides `tool_call.args` to the client
* untouched — only the tool body must never see an undeclared parameter
* (strict MCP/action schemas would reject it; zod tools would strip-or-throw).
*/
function stripIntentForInvoke(args: unknown, tool: StructuredToolInterface): unknown {
if (!hasIntentArg(args) || toolDeclaresIntentParam(tool)) {
return args;
}
return stripIntentArg(args);
}
function mergeToolConfigurables(
base: Record<string, unknown> | undefined,
loaded: Record<string, unknown> | undefined,
): Record<string, unknown> {
const merged = { ...base, ...loaded };
const accessibleSkillIds = mergeAccessibleSkillIds(base, loaded);
if (accessibleSkillIds) {
merged.accessibleSkillIds = accessibleSkillIds;
}
const skillPrimedIdsByName = mergeSkillPrimedIdsByName(base, loaded);
if (skillPrimedIdsByName) {
merged.skillPrimedIdsByName = skillPrimedIdsByName;
}
const authoredSkillIdsByName = mergeAuthoredSkillIdsByName(base, loaded);
if (authoredSkillIdsByName) {
merged.authoredSkillIdsByName = authoredSkillIdsByName;
}
const activeSkillNames = mergeActiveSkillNames(base, loaded);
if (activeSkillNames) {
merged.activeSkillNames = activeSkillNames;
}
return merged;
}
function rememberAuthoredSkill(
configurables: Array<Record<string, unknown> | undefined>,
skill: { _id: Types.ObjectId; name: string },
options: { prime?: boolean } = {},
): void {
const prime = options.prime !== false;
const idString = skill._id.toString();
for (const configurable of configurables) {
if (!configurable) {
continue;
}
const accessibleIds = Array.isArray(configurable.accessibleSkillIds)
? (configurable.accessibleSkillIds as Types.ObjectId[])
: [];
if (!Array.isArray(configurable.accessibleSkillIds)) {
configurable.accessibleSkillIds = accessibleIds;
}
if (!accessibleIds.some((id) => id.toString() === idString)) {
accessibleIds.push(skill._id);
}
if (prime) {
const primedIds =
(configurable.skillPrimedIdsByName as Record<string, string> | undefined) ?? {};
primedIds[skill.name] = idString;
configurable.skillPrimedIdsByName = primedIds;
}
/**
* Recorded for every authoring resolution, including `prime: false`
* recovery: both mean this run's authoring path bound this name to this
* doc, which is the doc invocation has to load. Unlike the primed map this
* grants no gate relaxation, so recording it during recovery cannot let a
* `disable-model-invocation: true` skill slip past its gate.
*/
const authoredIds =
(configurable.authoredSkillIdsByName as Record<string, string> | undefined) ?? {};
authoredIds[skill.name] = idString;
configurable.authoredSkillIdsByName = authoredIds;
const activeSkillNames = configurable.activeSkillNames as Set<string> | undefined;
if (activeSkillNames) {
activeSkillNames.add(skill.name);
} else {
configurable.activeSkillNames = new Set([skill.name]);
}
}
}
async function ensureCanEditSkill(
tc: ToolCallRequest,
options: ToolExecuteOptions,
req: ServerRequest | undefined,
skillId: Types.ObjectId | string,
): Promise<ToolExecuteResult | null> {
if (!req) {
return errorResult(tc, 'Skill file editing is not configured for this request.');
}
if (!options.canEditSkill) {
return errorResult(tc, 'Skill file editing is not configured.');
}
const allowed = await options.canEditSkill({ req, skillId });
return allowed ? null : errorResult(tc, 'Insufficient permissions to edit this skill.');
}
async function ensureCanCreateSkill(
tc: ToolCallRequest,
options: ToolExecuteOptions,
req: ServerRequest | undefined,
): Promise<ToolExecuteResult | null> {
if (!req) {
return errorResult(tc, 'Skill creation is not configured for this request.');
}
if (!options.canCreateSkill) {
return errorResult(tc, 'Skill creation is not configured.');
}
const allowed = await options.canCreateSkill({ req });
return allowed ? null : errorResult(tc, 'Insufficient permissions to create skills.');
}
async function loadSkillFileTextForAuthoring({
skill,
relativePath,
options,
req,
}: {
skill: AuthoringSkill;
relativePath: string;
options: ToolExecuteOptions;
req?: ServerRequest;
}): Promise<LoadedSkillText> {
if (relativePath === SKILL_MD) {
return {
status: 'loaded',
content: skill.body ?? '',
bytes: Buffer.byteLength(skill.body ?? '', 'utf8'),
};
}
const { getSkillFileByPath, getStrategyFunctions, updateSkillFileContent } = options;
if (!getSkillFileByPath) {
return { status: 'error', message: 'Skill file reading is not configured.' };
}
const file = await getSkillFileByPath(skill._id, relativePath);
if (!file) {
return { status: 'missing' };
}
if (file.isBinary === true) {
return { status: 'error', message: `File "${relativePath}" is binary and cannot be edited.` };
}
if (file.content != null && file.content !== '') {
return {
status: 'loaded',
content: file.content,
bytes: Buffer.byteLength(file.content, 'utf8'),
fileId: file.file_id,
};
}
if (file.bytes > MAX_CACHE_BYTES) {
return {
status: 'error',
message: `File "${relativePath}" is too large to edit directly (${file.bytes} bytes, limit: ${MAX_CACHE_BYTES}).`,
};
}
if (!getStrategyFunctions || !req) {
return { status: 'error', message: 'Storage access is not configured.' };
}
const strategy = getStrategyFunctions(file.source);
if (!strategy.getDownloadStream) {
return { status: 'error', message: 'Download is not supported for this storage backend.' };
}
const stream = await strategy.getDownloadStream(req, resolveDownloadPath(file));
const chunks: Uint8Array[] = [];
let streamedBytes = 0;
for await (const chunk of stream as AsyncIterable<Uint8Array>) {
streamedBytes += chunk.byteLength;
if (streamedBytes > MAX_CACHE_BYTES) {
if (
'destroy' in stream &&
typeof (stream as NodeJS.ReadableStream & { destroy?: () => void }).destroy === 'function'
) {
(stream as NodeJS.ReadableStream & { destroy: () => void }).destroy();
}
return {
status: 'error',
message: `File "${relativePath}" exceeded edit limit (${MAX_CACHE_BYTES} bytes).`,
};
}
chunks.push(chunk);
}
const buffer = Buffer.concat(chunks);
const checkLen = Math.min(buffer.length, 8192);
for (let i = 0; i < checkLen; i++) {
if (buffer[i] === 0) {
if (updateSkillFileContent) {
updateSkillFileContent(skill._id, relativePath, { isBinary: true }, file.file_id).catch(
(err: unknown) => {
logAxiosError({
message: '[loadSkillFileTextForAuthoring] cache write failed',
error: err,
});
},
);
}
return { status: 'error', message: `File "${relativePath}" is binary and cannot be edited.` };
}
}
const text = buffer.toString('utf-8');
if (updateSkillFileContent) {
updateSkillFileContent(
skill._id,
relativePath,
{ content: text, isBinary: false },
file.file_id,
).catch((err: unknown) => {
logAxiosError({
message: '[loadSkillFileTextForAuthoring] cache write failed',
error: err,
});
});
}
return { status: 'loaded', content: text, bytes: buffer.length, fileId: file.file_id };
}
async function inspectBundledSkillFileForCreate({
skill,
relativePath,
options,
req,
}: {
skill: AuthoringSkill;
relativePath: string;
options: ToolExecuteOptions;
req?: ServerRequest;
}): Promise<ExistingSkillFile> {
const { getSkillFileByPath } = options;
if (!getSkillFileByPath) {
return { status: 'error', message: 'Skill file reading is not configured.' };
}
const file = await getSkillFileByPath(skill._id, relativePath);
if (!file) {
return { status: 'missing' };
}
if (file.isBinary === true || file.bytes > MAX_CACHE_BYTES) {
return { status: 'present', fileId: file.file_id };
}
if (file.content != null && file.content !== '') {
return { status: 'present', oldContent: file.content, fileId: file.file_id };
}
if (!options.getStrategyFunctions || !req) {
return { status: 'present', fileId: file.file_id };
}
const loaded = await loadSkillFileTextForAuthoring({
skill,
relativePath,
options,
req,
});
if (loaded.status === 'missing') {
return { status: 'missing' };
}
if (loaded.status === 'error') {
return { status: 'present', fileId: file.file_id };
}
return { status: 'present', oldContent: loaded.content, fileId: loaded.fileId };
}
async function ensureBundledSkillVersionCurrent({
tc,
options,
skill,
displayPath,
}: {
tc: ToolCallRequest;
options: ToolExecuteOptions;
skill: AuthoringSkill;
displayPath: string;
}): Promise<ToolExecuteResult | null> {
if (!options.getSkillByName) {
return null;
}
const current = await options.getSkillByName(skill.name, [skill._id], {});
if (!current) {
return errorResult(tc, `Skill "${skill.name}" not found or not accessible.`);
}
if (current.version !== skill.version) {
return errorResult(
tc,
`Skill "${skill.name}" changed while editing. Re-read ${displayPath} and retry.`,
);
}
return null;
}
async function writeSkillMd({
tc,
options,
req,
mergedConfigurable,
sourceConfigurable,
skill,
skillName,
content,
signal,
}: {
tc: ToolCallRequest;
options: ToolExecuteOptions;
req?: ServerRequest;
mergedConfigurable: Record<string, unknown>;
sourceConfigurable?: Record<string, unknown>;
skill: AuthoringSkill | null;
skillName: string;
content: string;
signal?: AbortSignal;
}): AuthoringResult {
const normalized = normalizeSkillMdContent(content, skillName);
if (normalized.status === 'error') {
return errorResult(tc, normalized.error);
}
content = normalized.content;
const structured = parseStructuredSkillFrontmatter(content);
if (structured.error) {
return errorResult(tc, structured.error);
}
const parsedContent = parseSkillMdUpdate(content);
const filtered = filteredSkillResult(tc, req, {
name: skillName,
description: parsedContent.description,
body: content,
frontmatter: structured.frontmatter,
});
if (filtered != null) {
return filtered;
}
if (!skill) {
const createDenied = await ensureCanCreateSkill(tc, options, req);
if (createDenied) {
return createDenied;
}
if (!req || !options.createSkill || !options.grantSkillOwner) {
return errorResult(tc, 'Skill creation is not configured.');
}
const author = getAuthorInfo(req);
if (!author) {
return errorResult(tc, 'Authentication required to create a skill.');
}
let result: Awaited<ReturnType<NonNullable<ToolExecuteOptions['createSkill']>>>;
try {
result = await options.createSkill({
name: skillName,
description: parsedContent.description,
body: content,
...(parsedContent.frontmatter !== undefined
? { frontmatter: parsedContent.frontmatter }
: {}),
author: author.author,
authorName: author.authorName,
...(parsedContent.alwaysApply !== undefined
? { alwaysApply: parsedContent.alwaysApply }
: {}),
...(author.tenantId ? { tenantId: author.tenantId } : {}),
});
} catch (error) {
if (isDuplicateSkillNameError(error)) {
return errorResult(
tc,
`Skill "${skillName}" already exists for this author. It cannot be created again or overwritten blindly. Read or enable the existing skill, then use edit_file for targeted changes, or choose a new skill name.`,
);
}
throw error;
}
try {
await options.grantSkillOwner({ req, skillId: result.skill._id });
} catch (error) {
if (options.deleteSkill) {
await deleteSkillWithRetry(options.deleteSkill, result.skill._id.toString())
.then((deletion) => {
if (!deletion.cleanupComplete) {
logger.error('[create_file] Skill rollback left dependent cleanup incomplete', {
skillId: result.skill._id.toString(),
failedCleanupSteps: deletion.failedCleanupSteps,
});
}
})
.catch((rollbackError: unknown) => {
logger.error('[create_file] Failed to roll back skill after permission error', {
rollbackError,
});
});
}
throw error;
}
rememberAuthoredSkill([mergedConfigurable, sourceConfigurable], result.skill);
options.onSkillAuthored?.({
name: result.skill.name,
id: result.skill._id.toString(),
primed: true,
});
const surfacedWarnings = surfaceSkillAuthoringWarnings(result.warnings);
const invocationHint = authoredSkillInvocationHint(structured.frontmatter);
return successResult(
tc,
`Created ${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD} (${content.length} chars).${surfacedWarnings?.contentSuffix ?? ''}${invocationHint}`,
{
path: `${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD}`,
bytes_written: Buffer.byteLength(content, 'utf8'),
created: true,
...(surfacedWarnings
? {
warnings: surfacedWarnings.warnings,
warning_count: surfacedWarnings.warningCount,
}
: {}),
},
);
}
const editDenied = await ensureCanEditSkill(tc, options, req, skill._id);
if (editDenied) {
return editDenied;
}
if (!options.updateSkill) {
return errorResult(tc, 'Skill updating is not configured.');
}
let diff = createUnifiedDiff(`${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD}`, skill.body, content);
if (
diff &&
(isFilteredSkillProjection(tc, req, {
name: skill.name,
description: skill.description,
body: skill.body,
frontmatter: skill.frontmatter,
}) ||
isFilteredSkillProjection(tc, req, { body: diff }))
) {
diff = '';
}
signal?.throwIfAborted();
const result = await options.updateSkill({
id: skill._id.toString(),
expectedVersion: skill.version,
update: {
body: content,
description: parsedContent.description,
...(parsedContent.frontmatter !== undefined
? { frontmatter: parsedContent.frontmatter }
: {}),
...(parsedContent.alwaysApply !== undefined
? { alwaysApply: parsedContent.alwaysApply }
: {}),
},
});
if (result.status === 'conflict') {
return errorResult(
tc,
`Skill "${skillName}" changed while editing. Re-read ${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD} and retry.`,
);
}
if (result.status === 'not_found') {
return errorResult(tc, `Skill "${skillName}" not found or not accessible.`);
}
const summary = `Updated ${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD} (${content.length} chars).`;
const surfacedWarnings = surfaceSkillAuthoringWarnings(result.warnings);
const summaryWithWarnings = `${summary}${surfacedWarnings?.contentSuffix ?? ''}`;
return successResult(tc, diff ? `${summaryWithWarnings}\n\n${diff}` : summaryWithWarnings, {
path: `${SKILL_FILE_PREFIX}${skillName}/${SKILL_MD}`,
bytes_written: Buffer.byteLength(content, 'utf8'),
created: false,
...(diff ? { diff } : {}),
...(surfacedWarnings
? {
warnings: surfacedWarnings.warnings,
warning_count: surfacedWarnings.warningCount,
}
: {}),
});
}
async function writeBundledSkillFile({
tc,
options,
req,
skill,
relativePath,
displayPath,
content,
oldContent,
fileId,
created,
signal,
}: {
tc: ToolCallRequest;
options: ToolExecuteOptions;
req?: ServerRequest;
skill: AuthoringSkill;
relativePath: string;
displayPath: string;
content: string;
oldContent?: string;
fileId?: string;
created: boolean;
signal?: AbortSignal;
}): AuthoringResult {
const editDenied = await ensureCanEditSkill(tc, options, req, skill._id);
if (editDenied) {
return editDenied;
}
if (!req || !options.saveSkillFileContent) {
return errorResult(tc, 'Skill file writing is not configured.');
}
if (skill.source != null && skill.source !== 'inline') {
return errorResult(tc, 'Externally managed skill files are read-only.');
}
if (!created && !fileId) {
return errorResult(
tc,
`File revision unavailable for ${displayPath}. Re-read the file and retry.`,
);
}
const staleDenied = await ensureBundledSkillVersionCurrent({
tc,
options,
skill,
displayPath,
});
if (staleDenied) {
return staleDenied;
}
const skillFiltered = filteredSkillResult(tc, req, {
files: [{ filename: displayPath, content }],
});
if (skillFiltered != null) {
return skillFiltered;
}
const fileFiltered = filteredFileResult(tc, req, displayPath, content);
if (fileFiltered != null) {
return fileFiltered;
}
let diff =
oldContent !== undefined ? createUnifiedDiff(displayPath, oldContent, content) : undefined;
if (
diff &&
(isFilteredSkillProjection(tc, req, {
files: [{ filename: displayPath, content: oldContent }],
}) ||
filteredFileResult(tc, req, displayPath, oldContent ?? '') != null ||
isFilteredSkillProjection(tc, req, {
files: [{ filename: displayPath, content: diff }],
}) ||
filteredFileResult(tc, req, displayPath, diff) != null)
) {
diff = undefined;
}
try {
signal?.throwIfAborted();
await options.saveSkillFileContent({
req,
skillId: skill._id,
relativePath,
content,
mimeType: guessMimeType(relativePath),
expectedFileId: fileId,
createOnly: created,
});
} catch (error) {
if (error instanceof Error && 'code' in error && error.code === 'SKILL_FILE_CONFLICT') {
return errorResult(
tc,
created
? `File already exists: ${displayPath}. Re-read it and pass overwrite: true to replace.`
: `Skill file changed while editing. Re-read ${displayPath} and retry.`,
);
}
if (error instanceof Error && 'code' in error && error.code === 'SKILL_DELETING') {
return errorResult(tc, `Skill is being deleted. Re-read ${displayPath} before retrying.`);
}
throw error;
}
const action = created ? 'Created' : 'Updated';
const summary = `${action} ${displayPath} (${content.length} chars).`;
return successResult(tc, diff ? `${summary}\n\n${diff}` : summary, {
path: displayPath,
bytes_written: Buffer.byteLength(content, 'utf8'),
created,
...(diff ? { diff } : {}),
});
}
function attachedWorkspaceAuthoringPath(
tc: ToolCallRequest,
filePath: string,
): { filePath: string } | ToolExecuteResult {
if (!filePath.startsWith('workspace/')) {
return errorResult(tc, 'Attached environment file paths must use "workspace/{relativePath}".');
}
const relativePath = filePath.slice('workspace/'.length);
const pathError = invalidSandboxAuthoringPath(relativePath);
return pathError ? errorResult(tc, pathError) : { filePath: relativePath };
}
function attachedWorkspaceRequestLimits(codeExecutionContext: CodeExecutionContext): {
maxQueueWaitMs: number;
maxRequestTimeoutMs?: number;
} & WorkspaceAdmissionOptions {
const config = codeExecutionContext.codeEnvironmentConfigSchema;
const maxRequestTimeoutMs = resolveAttachedWorkspaceRequestTimeoutMs(config);
return {
...resolveAttachedWorkspaceAdmissionOptions(config),
maxQueueWaitMs: resolveAttachedWorkspaceQueueWaitMs(config),
...(maxRequestTimeoutMs == null ? {} : { maxRequestTimeoutMs }),
};
}
function attachedWorkspaceMutationParams(
codeExecutionContext: CodeExecutionContext,
workspaceId: string,
req: ServerRequest | undefined,
signal: AbortSignal | undefined,
): {
workspace_id: string;
workspace_instance_id?: string;
linked_worktrees?: boolean;
codeApiBaseUrl: string;
executionProfile: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
req?: ServerRequest;
signal?: AbortSignal;
maxQueueWaitMs: number;
maxRequestTimeoutMs?: number;
deadlineAtMs?: number;
} & WorkspaceAdmissionOptions {
const limits = attachedWorkspaceRequestLimits(codeExecutionContext);
const runTimeoutMs = limits.maxRunTimeoutMs ?? limits.maxRequestTimeoutMs;
return {
workspace_id: workspaceId,
...(codeExecutionContext.codeWorkspace?.workspaceInstanceId
? { workspace_instance_id: codeExecutionContext.codeWorkspace.workspaceInstanceId }
: {}),
...(codeExecutionContext.codeWorkspace?.linkedWorktrees ? { linked_worktrees: true } : {}),
codeApiBaseUrl: codeExecutionContext.baseUrl,
...limits,
...(runTimeoutMs == null ? {} : { deadlineAtMs: Date.now() + runTimeoutMs }),
executionProfile: codeExecutionContext.executionProfile,
...(codeExecutionContext.bridgeWorkerId
? { bridgeWorkerId: codeExecutionContext.bridgeWorkerId }
: {}),
...(req ? { req } : {}),
...(signal ? { signal } : {}),
};
}
async function handleAttachedWorkspaceCreateFileCall({
tc,
options,
req,
filePath,
content,
overwrite,
codeExecutionContext,
signal,
}: {
tc: ToolCallRequest;
options: ToolExecuteOptions;
req?: ServerRequest;
filePath: string;
content: string;
overwrite: boolean;
codeExecutionContext: CodeExecutionContext;
signal?: AbortSignal;
}): AuthoringResult {
if (!options.writeWorkspaceFile) {
return errorResult(tc, 'Attached workspace file writing is not configured.');
}
const path = attachedWorkspaceAuthoringPath(tc, filePath);
if ('status' in path) return path;
if (new TextEncoder().encode(content).byteLength > WORKSPACE_WRITE_MAX_BYTES) {
return errorResult(tc, 'Attached workspace files are limited to 1 MiB per write.');
}
const filtered = filteredFileResult(tc, req, path.filePath, content);
if (filtered != null) return filtered;
const workspaceId = selectedWorkspaceId(codeExecutionContext, 'write_file');
if (!workspaceId) return unavailableWorkspaceOperation(tc, 'write_file');
try {
const result = await options.writeWorkspaceFile({
file_path: path.filePath,
content,
overwrite,
...attachedWorkspaceMutationParams(codeExecutionContext, workspaceId, req, signal),
});
const action = result.created ? 'Created' : 'Updated';
return successResult(tc, `${action} workspace/${path.filePath} (${content.length} chars).`, {
path: `workspace/${path.filePath}`,
[HOST_FILE_AUTHORING_ARTIFACT_KEY]: true,
bytes_written: result.bytesWritten,
created: result.created,
});
} catch (error) {
if (error instanceof WorkspaceToolHttpError) {
if (error.upstreamStatus === 409 && !overwrite) {
error.message += '. File already exists. Pass overwrite: true to replace.';
}
throw explainWorkspacePathRejection(error, 'write', `workspace/${path.filePath}`);
}
if (signal?.aborted === true && isAbortError(error)) throw error;
logger.warn('[file_authoring] Attached workspace write failed', getSafeErrorMetadata(error));
return errorResult(tc, `Failed to write "workspace/${path.filePath}".`);
}
}
/** One sentence per edit that did not match exactly once, so the model can verify it. */
function describeAttachedEdit(filePath: string, result: WorkspaceEditResult): string {
const count = result.replacements;
const notes = (result.matches ?? []).flatMap((match, index) => {
const edit = count === 1 ? 'the edit' : `edit ${index + 1}`;
const found = match.strategy === 'exact' ? [] : [`${edit} matched with ${match.strategy}`];
return match.occurrences > 1
? [...found, `${edit} replaced ${match.occurrences} locations`]
: found;
});
if (notes.length === 0) {
return `Updated workspace/${filePath} with ${count} exact replacement${count === 1 ? '' : 's'}.`;
}
return `Updated workspace/${filePath} with ${count} replacement${count === 1 ? '' : 's'} (${notes.join('; ')}).`;
}
/**
* A rejected attached edit that keeps its status and code but none of its body, so logs never
* retain upstream text. `message` is what logs keep; `modelMessage` may add the current file text
* a worker quoted, which the model sees just as it would see a read_file result.
*/
class AttachedEditRejectionError extends WorkspaceToolHttpError {
constructor(
reason: WorkspaceToolHttpError['reason'],
message: string,
public readonly modelMessage: string,
code = 'EDIT_CONFLICT',
) {
super(reason, 409, JSON.stringify({ code }));
this.message = message;
}
}
/**
* Any other 409, such as a quarantined workspace, is not a text mismatch the model can fix by
* re-reading. Only its validated code is kept, in host words.
*/
function attachedEditRejection(
filePath: string,
error: WorkspaceToolHttpError,
code: string,
): AttachedEditRejectionError {
const guidance =
code === 'WORKSPACE_QUARANTINED'
? ' The workspace is quarantined after an earlier operation did not finish; it must be reset on its machine before edits can apply, so retrying will not help.'
: '';
const message = `The edit to "workspace/${filePath}" was rejected by the code environment (${code}), so nothing was written.${guidance}`;
return new AttachedEditRejectionError(error.reason, message, message, code);
}
/**
* A worker is outside LibreChat's trust boundary, so its conflict text is never forwarded: only the
* facts a strict parse recovers from it (which edits failed, how, and on which lines) reach the
* model, in LibreChat's own words. The one exception is a well-formed excerpt of the edited file's
* current text, which is file content like any read_file result: it is quoted only when the selected
* workspace allows read_file, and only after it passes the same file-content policy. Anything else
* gets the generic retry guidance.
*/
function attachedEditConflict(
tc: ToolCallRequest,
req: ServerRequest | undefined,
filePath: string,
error: WorkspaceToolHttpError,
canRead: boolean,
): AttachedEditRejectionError {
const conflict = error.editConflict;
const settle = (message: string, modelMessage = message) =>
new AttachedEditRejectionError(error.reason, message, modelMessage);
if (conflict?.startsWith('Workspace file changed')) {
return settle(
`"workspace/${filePath}" changed while this edit was being applied, so nothing was written. Re-read the file and retry.`,
);
}
const report = conflict == null ? undefined : parseEditConflict(conflict);
if (!report) {
return settle(
`The edit to "workspace/${filePath}" did not apply, so nothing was written. The requested text did not match exactly once; re-read the file and retry.`,
);
}
const path = `workspace/${filePath}`;
const message = formatEditConflict(path, report);
const excerpts = editConflictExcerptText(report);
if (!canRead || !excerpts || filteredFileResult(tc, req, filePath, excerpts) != null) {
return settle(message);
}
return settle(message, formatEditConflict(path, report, true));
}
async function handleAttachedWorkspaceEditFileCall({
tc,
options,
req,
filePath,
edits,
codeExecutionContext,
signal,
}: {
tc: ToolCallRequest;
options: ToolExecuteOptions;
req?: ServerRequest;
filePath: string;
edits: TextEdit[];
codeExecutionContext: CodeExecutionContext;
signal?: AbortSignal;
}): AuthoringResult {
if (!options.editWorkspaceFile) {
return errorResult(tc, 'Attached workspace file editing is not configured.');
}
const path = attachedWorkspaceAuthoringPath(tc, filePath);
if ('status' in path) return path;
if (edits.length > WORKSPACE_EDIT_MAX_COUNT) {
return errorResult(
tc,
`Attached workspace edits are limited to ${WORKSPACE_EDIT_MAX_COUNT} replacements per call.`,
);
}
const editBytes = edits.reduce(
(bytes, edit) =>
bytes +
new TextEncoder().encode(edit.old_text).byteLength +
new TextEncoder().encode(edit.new_text).byteLength,
0,
);
if (editBytes > WORKSPACE_WRITE_MAX_BYTES) {
return errorResult(tc, 'Attached workspace edit text is limited to 1 MiB per call.');
}
const filteredName = filteredFileNameResult(tc, req, path.filePath);
if (filteredName != null) return filteredName;
const workspaceId = selectedWorkspaceId(codeExecutionContext, 'edit_file');
if (!workspaceId) return unavailableWorkspaceOperation(tc, 'edit_file');
const editFeatures = codeExecutionContext.codeWorkspace?.editFileFeatures ?? [];
if (edits.some((edit) => edit.replace_all === true) && !editFeatures.includes('replace_all')) {
return errorResult(
tc,
'replace_all needs a newer LibreChat Code worker on this machine. Make each old_text unique instead.',
);
}
/** Tolerant by default, like every other edit_file variant; operators can require exact. */
const matching: WorkspaceEditMatching | undefined =
codeExecutionContext.codeEnvironmentConfigSchema?.edits?.tolerantMatching !== false &&
editFeatures.includes('tolerant_match')
? 'tolerant'
: undefined;
try {
const workspaceEdits: WorkspaceTextEdit[] = edits.map((edit) => ({
oldText: edit.old_text,
newText: edit.new_text,
...(edit.replace_all === true ? { replaceAll: true } : {}),
}));
const workspaceParams = attachedWorkspaceMutationParams(
codeExecutionContext,
workspaceId,
req,
signal,
);
const queueDeadlineAt = Date.now() + workspaceParams.maxQueueWaitMs;
let expectedBaseSha256: string | undefined;
if (hasActiveFileFieldPolicy(req?.config?.filters, ['content', 'extracted_text'])) {
if (!options.previewWorkspaceEdit) {
return errorResult(
tc,
'Attached workspace editing requires an updated BYOM worker while file-content protections are enabled.',
);
}
if (!selectedWorkspaceId(codeExecutionContext, 'preview_edit')) {
return unavailableWorkspaceOperation(tc, 'preview_edit');
}
let preview: WorkspacePreviewEditResult;
try {
preview = await options.previewWorkspaceEdit({
file_path: path.filePath,
edits: workspaceEdits,
...(matching ? { matching } : {}),
...workspaceParams,
});
} catch (error) {
if (signal?.aborted === true && isAbortError(error)) throw error;
if (error instanceof WorkspaceToolHttpError && error.upstreamStatus === 400) {
error.message +=
'. This attached environment must update its LibreChat Code worker before protected files can be edited.';
}
throw error;
}
const filteredContent = filteredFileResult(tc, req, path.filePath, preview.content);
if (filteredContent != null) return filteredContent;
expectedBaseSha256 = preview.baseSha256;
/** A spent queue horizon disables capacity retries, not the required
* hash-guarded edit attempt or its independent rate-limit recovery. */
if (workspaceParams.maxQueueWaitMs > 0) {
workspaceParams.maxQueueWaitMs = Math.max(0, queueDeadlineAt - Date.now());
}
}
const result = await options.editWorkspaceFile({
file_path: path.filePath,
edits: workspaceEdits,
...(expectedBaseSha256 ? { expected_base_sha256: expectedBaseSha256 } : {}),
...(matching ? { matching } : {}),
...workspaceParams,
});
return successResult(tc, describeAttachedEdit(path.filePath, result), {
path: `workspace/${path.filePath}`,
[HOST_FILE_AUTHORING_ARTIFACT_KEY]: true,
bytes_written: result.bytesWritten,
created: false,
edits: result.replacements,
strategies:
result.matches?.map((match) => match.strategy) ??
Array.from({ length: result.replacements }, () => 'exact'),
});
} catch (error) {
if (error instanceof WorkspaceToolHttpError) {
if (error.upstreamStatus !== 409) {
throw explainWorkspacePathRejection(error, 'edit', `workspace/${path.filePath}`);
}
const code = error.upstreamCode;
throw code == null || code === 'EDIT_CONFLICT'
? attachedEditConflict(
tc,
req,
path.filePath,
error,
selectedWorkspaceId(codeExecutionContext, 'read_file') != null,
)
: attachedEditRejection(path.filePath, error, code);
}
if (signal?.aborted === true && isAbortError(error)) throw error;
logger.warn('[file_authoring] Attached workspace edit failed', getSafeErrorMetadata(error));
return errorResult(tc, `Failed to edit "workspace/${path.filePath}".`);
}
}
async function handleSandboxCreateFileCall({
tc,
options,
req,
filePath,
content,
overwrite,
sandboxContext,
codeExecutionContext,
signal,
}: {
tc: ToolCallRequest;
options: ToolExecuteOptions;
req?: ServerRequest;
filePath: string;
content: string;
overwrite: boolean;
sandboxContext?: SandboxSessionContext;
codeExecutionContext?: CodeExecutionContext;
signal?: AbortSignal;
}): AuthoringResult {
if (codeExecutionContext?.environmentType === 'attached') {
return await handleAttachedWorkspaceCreateFileCall({
tc,
options,
req,
filePath,
content,
overwrite,
codeExecutionContext,
signal,
});
}
const pathError = invalidSandboxAuthoringPath(filePath);
if (pathError) {
return errorResult(tc, pathError);
}
const current = await loadSandboxTextForAuthoring({
filePath,
tc,
options,
req,
sandboxContext,
codeExecutionContext,
});
if (current.status === 'error') {
return errorResult(tc, current.message);
}
if (current.status === 'loaded' && !overwrite) {
return errorResult(tc, 'File already exists. Pass overwrite: true to replace.');
}
return await writeSandboxTextForAuthoring({
tc,
options,
req,
filePath,
content,
oldContent: current.status === 'loaded' ? current.content : undefined,
created: current.status === 'missing',
sandboxContext,
codeExecutionContext,
});
}
function hostEditFailure(tc: ToolCallRequest, error: unknown): ToolExecuteResult {
if (error instanceof HostEditError) return errorResult(tc, error.message);
logger.warn('[file_authoring] Host edit processing failed', getSafeErrorMetadata(error));
return errorResult(tc, 'File edit processing failed. Nothing was written.');
}
async function handleSandboxEditFileCall({
tc,
options,
req,
filePath,
edits,
sandboxContext,
codeExecutionContext,
signal,
}: {
tc: ToolCallRequest;
options: ToolExecuteOptions;
req?: ServerRequest;
filePath: string;
edits: TextEdit[];
sandboxContext?: SandboxSessionContext;
codeExecutionContext?: CodeExecutionContext;
signal?: AbortSignal;
}): AuthoringResult {
if (codeExecutionContext?.environmentType === 'attached') {
return await handleAttachedWorkspaceEditFileCall({
tc,
options,
req,
filePath,
edits,
codeExecutionContext,
signal,
});
}
const pathError = invalidSandboxAuthoringPath(filePath);
if (pathError) {
return errorResult(tc, pathError);
}
const current = await loadSandboxTextForAuthoring({
filePath,
tc,
options,
req,
sandboxContext,
codeExecutionContext,
});
if (current.status === 'missing') {
return errorResult(tc, `File not found: "${filePath}"`);
}
if (current.status === 'error') {
return errorResult(tc, current.message);
}
let edited: { content: string; strategies: string[] };
try {
edited = await applyHostTextEdits(
current.content,
edits,
req?.config?.endpoints?.agents?.hostFileEdits,
signal,
);
} catch (error) {
if (signal?.aborted) throw error;
return hostEditFailure(tc, error);
}
signal?.throwIfAborted();
if (Buffer.byteLength(edited.content, 'utf8') > MAX_AUTHORING_BYTES) {
return errorResult(tc, `edited content exceeds ${MAX_AUTHORING_BYTES} byte limit`);
}
const result = await writeSandboxTextForAuthoring({
tc,
options,
req,
filePath,
content: edited.content,
oldContent: current.content,
signal,
created: false,
sandboxContext,
codeExecutionContext,
});
if (result.status === 'success') {
result.artifact = {
...(typeof result.artifact === 'object' && result.artifact ? result.artifact : {}),
edits: edits.length,
strategies: edited.strategies,
};
result.content = `${String(result.content)}\n\nStrategies: ${edited.strategies.join(', ')}`;
}
return result;
}
async function handleCreateFileCall(
tc: ToolCallRequest,
mergedConfigurable: Record<string, unknown>,
options: ToolExecuteOptions,
req?: ServerRequest,
sourceConfigurable?: Record<string, unknown>,
sandboxContext?: SandboxSessionContext,
signal?: AbortSignal,
): AuthoringResult {
const args = tc.args as { path?: unknown; content?: unknown; overwrite?: unknown };
if (typeof args.path !== 'string' || args.path.length === 0) {
return errorResult(tc, 'path is required');
}
if (typeof args.content !== 'string') {
return errorResult(
tc,
'content is required. If the file is large, your response may have been cut off at the ' +
'output token limit before content finished. Keep the main file lean and move bulky ' +
'sections (templates, schemas, long docs) into separate files written in their own calls.',
);
}
if (Buffer.byteLength(args.content, 'utf8') > MAX_AUTHORING_BYTES) {
return errorResult(tc, `content exceeds ${MAX_AUTHORING_BYTES} byte limit`);
}
const overwrite = args.overwrite === true;
if (!isSkillFilePath(args.path)) {
if (mergedConfigurable?.codeEnvAvailable !== true) {
return errorResult(
tc,
`Path "${args.path}" is not a skill file, and this agent does not have code execution enabled.`,
);
}
return await handleSandboxCreateFileCall({
tc,
options,
req,
filePath: args.path,
content: args.content,
overwrite,
sandboxContext,
codeExecutionContext: getCodeExecutionContext(mergedConfigurable),
signal,
});
}
const parsed = parseSkillAuthoringPath(args.path);
if (typeof parsed === 'string') {
return errorResult(tc, parsed);
}
if (!isSkillAuthoringAvailable(mergedConfigurable)) {
return errorResult(tc, 'Skill file authoring is not available for this agent.');
}
let skill = await resolveSkillForAuthoring(parsed.skillName, mergedConfigurable, options);
if (!skill) {
skill = await resolveAuthorSkillForCurrentUser({
skillName: parsed.skillName,
mergedConfigurable,
sourceConfigurable,
options,
req,
});
}
const hiddenDenied = hiddenSkillAuthoringDenied(tc, skill, parsed.skillName, mergedConfigurable);
if (hiddenDenied) {
return hiddenDenied;
}
if (parsed.relativePath === SKILL_MD) {
if (skill && !overwrite) {
return errorResult(
tc,
`Skill "${parsed.skillName}" already exists. Use edit_file for targeted changes, or pass overwrite: true only if replacing the entire ${parsed.displayPath} is intended.`,
);
}
return await writeSkillMd({
tc,
options,
req,
mergedConfigurable,
sourceConfigurable,
skill,
skillName: parsed.skillName,
content: args.content,
});
}
if (!skill) {
return errorResult(tc, `Skill "${parsed.skillName}" not found or not accessible.`);
}
const current = await inspectBundledSkillFileForCreate({
skill,
relativePath: parsed.relativePath,
options,
req,
});
if (current.status === 'error') {
return errorResult(tc, current.message);
}
if (current.status === 'present' && !overwrite) {
return errorResult(tc, 'File already exists. Pass overwrite: true to replace.');
}
return await writeBundledSkillFile({
tc,
options,
req,
skill,
relativePath: parsed.relativePath,
displayPath: parsed.displayPath,
content: args.content,
oldContent: current.status === 'present' ? current.oldContent : undefined,
fileId: current.status === 'present' ? current.fileId : undefined,
created: current.status === 'missing',
});
}
async function handleEditFileCall(
tc: ToolCallRequest,
mergedConfigurable: Record<string, unknown>,
options: ToolExecuteOptions,
req?: ServerRequest,
sandboxContext?: SandboxSessionContext,
signal?: AbortSignal,
): AuthoringResult {
const args = tc.args as {
path?: unknown;
old_text?: unknown;
new_text?: unknown;
replace_all?: unknown;
edits?: unknown;
};
if (typeof args.path !== 'string' || args.path.length === 0) {
return errorResult(tc, 'path is required');
}
const edits = normalizeEditArgs(args);
if (typeof edits === 'string') {
return errorResult(tc, edits);
}
if (!isSkillFilePath(args.path)) {
if (mergedConfigurable?.codeEnvAvailable !== true) {
return errorResult(
tc,
`Path "${args.path}" is not a skill file, and this agent does not have code execution enabled.`,
);
}
return await handleSandboxEditFileCall({
tc,
options,
req,
filePath: args.path,
edits,
sandboxContext,
codeExecutionContext: getCodeExecutionContext(mergedConfigurable),
signal,
});
}
const parsed = parseSkillAuthoringPath(args.path);
if (typeof parsed === 'string') {
return errorResult(tc, parsed);
}
if (!isSkillAuthoringAvailable(mergedConfigurable)) {
return errorResult(tc, 'Skill file authoring is not available for this agent.');
}
let skill = await resolveSkillForAuthoring(parsed.skillName, mergedConfigurable, options);
if (!skill) {
skill = await resolveAuthorSkillForCurrentUser({
skillName: parsed.skillName,
mergedConfigurable,
options,
req,
});
}
if (!skill) {
return errorResult(tc, `Skill "${parsed.skillName}" not found or not accessible.`);
}
const hiddenDenied = hiddenSkillAuthoringDenied(tc, skill, parsed.skillName, mergedConfigurable);
if (hiddenDenied) {
return hiddenDenied;
}
const current = await loadSkillFileTextForAuthoring({
skill,
relativePath: parsed.relativePath,
options,
req,
});
if (current.status === 'missing') {
return errorResult(
tc,
`File not found: "${parsed.relativePath}" in skill "${parsed.skillName}"`,
);
}
if (current.status === 'error') {
return errorResult(tc, current.message);
}
let edited: { content: string; strategies: string[] };
try {
edited = await applyHostTextEdits(
current.content,
edits,
req?.config?.endpoints?.agents?.hostFileEdits,
signal,
);
} catch (error) {
if (signal?.aborted) throw error;
return hostEditFailure(tc, error);
}
signal?.throwIfAborted();
if (Buffer.byteLength(edited.content, 'utf8') > MAX_AUTHORING_BYTES) {
return errorResult(tc, `edited content exceeds ${MAX_AUTHORING_BYTES} byte limit`);
}
if (parsed.relativePath === SKILL_MD) {
const result = await writeSkillMd({
tc,
options,
req,
mergedConfigurable,
skill,
skillName: parsed.skillName,
content: edited.content,
signal,
});
if (result.status === 'success') {
result.artifact = {
...(typeof result.artifact === 'object' && result.artifact ? result.artifact : {}),
edits: edits.length,
strategies: edited.strategies,
};
result.content = `${String(result.content)}\n\nStrategies: ${edited.strategies.join(', ')}`;
}
return result;
}
const result = await writeBundledSkillFile({
tc,
options,
req,
skill,
relativePath: parsed.relativePath,
displayPath: parsed.displayPath,
content: edited.content,
signal,
oldContent: current.content,
fileId: current.fileId,
created: false,
});
if (result.status === 'success') {
result.artifact = {
...(typeof result.artifact === 'object' && result.artifact ? result.artifact : {}),
edits: edits.length,
strategies: edited.strategies,
};
result.content = `${String(result.content)}\n\nStrategies: ${edited.strategies.join(', ')}`;
}
return result;
}
async function handleReadFileCall(
tc: ToolCallRequest,
mergedConfigurable: Record<string, unknown>,
options: ToolExecuteOptions,
req?: ServerRequest,
onSandboxReadSuccess?: () => void,
signal?: AbortSignal,
): Promise<ToolExecuteResult> {
const { getSkillByName, getSkillFileByPath, getStrategyFunctions, updateSkillFileContent } =
options;
const args = tc.args as { path?: string };
if (!args.path) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'path is required',
};
}
const codeEnvAvailable = mergedConfigurable?.codeEnvAvailable === true;
const codeExecutionContext = getCodeExecutionContext(mergedConfigurable);
let accessibleIds = (mergedConfigurable?.accessibleSkillIds as Types.ObjectId[]) ?? [];
if (args.path.startsWith('workspace/')) {
if (!codeEnvAvailable || codeExecutionContext?.environmentType !== 'attached') {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'workspace/ paths require an attached code environment.',
};
}
return handleWorkspaceFileRead(
tc,
args.path.slice('workspace/'.length),
options,
req,
codeExecutionContext,
signal,
);
}
/**
* Short-circuit absolute code-env paths: the path can never be a skill
* reference (skill paths are relative `{skillName}/...`), and consulting
* `getSkillByName` would just burn a DB round-trip on a guaranteed miss.
*/
if (args.path.startsWith('/mnt/data/')) {
if (codeEnvAvailable) {
return handleSandboxFileFallback(
tc,
args.path,
options,
req,
codeExecutionContext,
onSandboxReadSuccess,
signal,
);
}
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Path "${args.path}" is a code-execution sandbox path, but this agent does not have code execution enabled.`,
};
}
let skillName: string;
let relativePath: string;
const explicitSkillNamespace = args.path.startsWith(SKILL_FILE_PREFIX);
if (explicitSkillNamespace) {
const parsed = parseSkillAuthoringPath(args.path);
if (typeof parsed === 'string') {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: parsed,
};
}
skillName = parsed.skillName;
relativePath = parsed.relativePath;
} else {
const slashIdx = args.path.indexOf('/');
if (slashIdx < 1) {
if (codeEnvAvailable) {
return handleSandboxFileFallback(
tc,
args.path,
options,
req,
codeExecutionContext,
onSandboxReadSuccess,
signal,
);
}
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Invalid file path "${args.path}". Use format: {skillName}/{path}`,
};
}
skillName = args.path.slice(0, slashIdx);
relativePath = args.path.slice(slashIdx + 1);
if (!relativePath) {
/**
* `read_file("output/")`: a malformed-but-unambiguously-not-a-skill
* path. Stay consistent with the other malformed-path branches and
* route to the sandbox when code execution is available, instead of
* dead-ending with a skill-centric error message.
*/
if (codeEnvAvailable) {
return handleSandboxFileFallback(
tc,
args.path,
options,
req,
codeExecutionContext,
onSandboxReadSuccess,
signal,
);
}
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'Missing file path after skill name',
};
}
}
let skillPrimedIdsByName =
(mergedConfigurable?.skillPrimedIdsByName as Record<string, string> | undefined) ?? {};
let primedIdString = skillPrimedIdsByName[skillName];
let isPrimedThisTurn = isSkillPrimedForAuthoring(skillName, mergedConfigurable);
const refreshSkillReadScope = () => {
accessibleIds = (mergedConfigurable?.accessibleSkillIds as Types.ObjectId[]) ?? [];
skillPrimedIdsByName =
(mergedConfigurable?.skillPrimedIdsByName as Record<string, string> | undefined) ?? {};
primedIdString = skillPrimedIdsByName[skillName];
isPrimedThisTurn = isSkillPrimedForAuthoring(skillName, mergedConfigurable);
};
let recoveredAuthorSkill: AuthoringSkill | null | undefined;
const recoverAuthorSkill = async () => {
if (recoveredAuthorSkill !== undefined) {
return recoveredAuthorSkill;
}
recoveredAuthorSkill = await resolveAuthorSkillForCurrentUser({
skillName,
mergedConfigurable,
options,
req,
});
refreshSkillReadScope();
return recoveredAuthorSkill;
};
/**
* `accessibleSkillIds` is the resolver's normal output (admin
* capability AND ACL access AND ephemeral badge / persisted
* `skills_enabled`). A skill authored earlier in this run is also
* resolvable through `skillPrimedIdsByName`, even when the run started
* with an empty accessible set for a first-time creator.
*/
let skillsEffectivelyEnabled = accessibleIds.length > 0 || isPrimedThisTurn;
if (
!skillsEffectivelyEnabled &&
explicitSkillNamespace &&
isSkillAuthoringAvailable(mergedConfigurable)
) {
await recoverAuthorSkill();
skillsEffectivelyEnabled = accessibleIds.length > 0 || isPrimedThisTurn;
}
/**
* Skills not in scope (admin capability off, ephemeral badge off, or
* persisted `skills_enabled !== true` — all already collapsed into
* `accessibleSkillIds.length === 0` by `resolveAgentScopedSkillIds`):
* route to the sandbox fallback when code execution is available, else
* the lookup truly has nowhere to go.
*/
if (!skillsEffectivelyEnabled) {
if (codeEnvAvailable && !explicitSkillNamespace) {
return handleSandboxFileFallback(
tc,
args.path,
options,
req,
codeExecutionContext,
onSandboxReadSuccess,
signal,
);
}
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage:
'Skill files are not available for this agent and code execution is not enabled.',
};
}
/**
* Read the primed-skills map BEFORE the `activeSkillNames` shortcut.
*
* `activeSkillNames` is the catalog-visible set after the
* `SKILL_CATALOG_LIMIT` cap and the active-state filter run in
* `injectSkillCatalog`. Manual ($-popover) primes and always-apply
* primes are intentionally resolved off the wider `accessibleSkillIds`
* ACL set BEFORE catalog injection — see `resolveManualSkills` for
* why a skill outside the catalog cap can still be authorized for
* direct manual invocation. So a primed skill name may legitimately
* be absent from `activeSkillNames`. Treat any name in
* `skillPrimedIdsByName` as "known" for the gate below; otherwise the
* shortcut would misroute `read_file("primed-skill/references/foo.md")`
* to the sandbox even though the primed skill is in scope.
*/
/**
* Skills are in scope, but the first segment isn't a name we know.
* Use the catalog-derived `activeSkillNames` Set (no DB read) to detect
* this and fall through to the sandbox so the model doesn't have to
* eat a wasted `read_file` error before retrying with `bash_tool`.
* Primed names bypass this shortcut even when absent from the catalog
* (see comment on `skillPrimedIdsByName` above).
*/
const activeSkillNames = mergedConfigurable?.activeSkillNames as Set<string> | undefined;
if (activeSkillNames && !activeSkillNames.has(skillName) && !isPrimedThisTurn) {
const recovered = await recoverAuthorSkill();
if (!recovered) {
if (codeEnvAvailable && !explicitSkillNamespace) {
return handleSandboxFileFallback(
tc,
args.path,
options,
req,
codeExecutionContext,
onSandboxReadSuccess,
signal,
);
}
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Skill "${skillName}" not found or not accessible`,
};
}
}
if (!getSkillByName) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'File reading is not configured',
};
}
/* On a primed lookup (manual `$` OR always-apply), pin the accessible
set to ONLY the primed `_id`. This guarantees the doc whose body got
primed is the SAME doc whose files we read, even when same-name
duplicates exist and `activeSkillIds` had to drop some via the
disable-model dedup. For autonomous probes we keep the full ACL set
+ `preferModelInvocable` so the lookup matches the catalog the model
saw (and falls back to newest so the disabled-only case still fires
the explicit rejection gate below). Constructing a real `ObjectId`
(rather than relying on mongoose's string auto-cast in `$in` queries)
keeps the value correct for any future consumer that compares with
`.equals()` or `===`. */
const pinnedIdString = getAuthoredSkillId(skillName, mergedConfigurable) ?? primedIdString;
const lookupAccessibleIds = pinnedIdString ? [new Types.ObjectId(pinnedIdString)] : accessibleIds;
const lookupOptions: { preferUserInvocable?: boolean; preferModelInvocable?: boolean } =
pinnedIdString ? {} : { preferModelInvocable: true };
let skill = await getSkillByName(skillName, lookupAccessibleIds, lookupOptions);
if (!skill) {
skill = await recoverAuthorSkill();
if (!skill) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Skill "${skillName}" not found or not accessible`,
};
}
}
/**
* `disable-model-invocation: true` blocks AUTONOMOUS read_file probes:
* a model that learned a hidden skill's name (stale catalog, hallucination)
* shouldn't be able to read its SKILL.md body or bundled files. But when
* the skill was primed this turn (manual `$` invocation OR always-apply),
* the body is already in context — and a primed skill that depends on
* `references/foo.md` would be non-functional if read_file were blocked.
* Bypass the gate for primed names so this stays usable end-to-end for
* both prime sources.
*
* Sticky-primed skills (manually or model-invoked in prior turns) are not
* yet in this exception list — that's a known limitation tracked for
* a follow-up. Same-turn priming is the load-bearing path.
*/
if (skill.disableModelInvocation === true && !isPrimedThisTurn) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Skill "${skillName}" cannot be invoked by the model`,
};
}
// SKILL.md special case: read from skill.body directly
if (relativePath === 'SKILL.md') {
if (!skill.body) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `SKILL.md is empty for skill "${skillName}"`,
};
}
const filtered = filteredSkillResult(tc, req, {
name: skill.name,
description: skill.description,
body: skill.body,
frontmatter: skill.frontmatter,
});
if (filtered != null) {
return filtered;
}
return localTextReadResult(tc, args.path, skill.body, `File: ${args.path}\n\n`);
}
/* Bundled skill files are primed into the sandbox under the `skills/`
* namespace (see `primeSkillFiles`), so the on-disk path is always
* `/mnt/data/skills/{skillName}/{relativePath}` regardless of whether the
* model addressed the file with or without the explicit prefix. Use this
* canonical path in the bash-fallback hints below so they never echo a
* prefix-less `args.path` that points nowhere on disk. */
const sandboxFilePath = `/mnt/data/${SKILL_FILE_PREFIX}${skillName}/${relativePath}`;
if (!getSkillFileByPath) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'File reading is not configured',
};
}
const file = await getSkillFileByPath(skill._id, relativePath);
if (!file) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `File not found: "${relativePath}" in skill "${skillName}"`,
};
}
const fileFiltered = IMAGE_MIMES.has(file.mimeType)
? filteredBinaryFileResult(tc, req, args.path)
: filteredFileNameResult(tc, req, args.path);
if (fileFiltered != null) {
return fileFiltered;
}
// Known binary — serve images as artifacts, others as metadata
if (file.isBinary === true) {
if (IMAGE_MIMES.has(file.mimeType) && file.bytes <= MAX_BINARY_BYTES) {
// Stream and return as image artifact (handled below in stream path)
} else {
return {
toolCallId: tc.id,
status: 'success',
content: `Binary file (${file.mimeType}, ${file.bytes} bytes). Use bash to process: ${sandboxFilePath}`,
};
}
}
// Cached text content
if (file.isBinary !== true && file.content != null && file.content !== '') {
const skillFiltered = filteredSkillResult(tc, req, {
files: [{ filename: args.path, content: file.content }],
});
if (skillFiltered != null) {
return skillFiltered;
}
const fileFiltered = filteredFileResult(tc, req, args.path, file.content);
if (fileFiltered != null) {
return fileFiltered;
}
return localTextReadResult(
tc,
args.path,
file.content,
`File: ${args.path} (${file.bytes} bytes)\n\n`,
);
}
// Early size check from DB metadata before streaming
const isImage = IMAGE_MIMES.has(file.mimeType);
if (!isImage && file.bytes > MAX_READABLE_BYTES) {
return {
toolCallId: tc.id,
status: 'success',
content: `File "${args.path}" is too large to read directly (${file.bytes} bytes, limit: ${MAX_READABLE_BYTES}). Invoke the skill first, then use bash to read it at ${sandboxFilePath}.`,
};
}
if (isImage && file.bytes > MAX_BINARY_BYTES) {
return {
toolCallId: tc.id,
status: 'success',
content: `File too large (${file.bytes} bytes, limit: ${MAX_BINARY_BYTES}). Use bash to process: ${sandboxFilePath}`,
};
}
// Stream from storage
if (!getStrategyFunctions || !req) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'Storage access not available',
};
}
try {
const strategy = getStrategyFunctions(file.source);
if (!strategy.getDownloadStream) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'Download not supported for this storage backend',
};
}
const stream = await strategy.getDownloadStream(req, resolveDownloadPath(file));
const chunks: Uint8Array[] = [];
// Use the larger binary limit as streaming cap; cheaper type-specific
// checks happen after binary detection on the assembled buffer.
const streamLimit = MAX_BINARY_BYTES;
let streamedBytes = 0;
for await (const chunk of stream as AsyncIterable<Uint8Array>) {
streamedBytes += chunk.byteLength;
if (streamedBytes > streamLimit) {
// Destroy the stream if possible to free resources
if (
'destroy' in stream &&
typeof (stream as NodeJS.ReadableStream & { destroy?: () => void }).destroy === 'function'
) {
(stream as NodeJS.ReadableStream & { destroy: () => void }).destroy();
}
return {
toolCallId: tc.id,
status: 'success',
content: `File "${args.path}" exceeded streaming limit (${streamLimit} bytes). Invoke the skill first, then use bash to read it at ${sandboxFilePath}.`,
};
}
chunks.push(chunk);
}
const buffer = Buffer.concat(chunks);
// Binary detection on first 8KB
const checkLen = Math.min(buffer.length, 8192);
let isBinary = file.isBinary === true;
if (!isBinary) {
for (let i = 0; i < checkLen; i++) {
if (buffer[i] === 0) {
isBinary = true;
break;
}
}
}
if (isBinary) {
// Cache the binary flag (first read only)
if (file.isBinary == null && updateSkillFileContent) {
updateSkillFileContent(skill._id, relativePath, { isBinary: true }, file.file_id).catch(
(err: unknown) => {
logAxiosError({
message: '[handleReadFileCall] cache write failed',
error: err,
});
},
);
}
// Return images/PDFs as artifacts
if (IMAGE_MIMES.has(file.mimeType) && buffer.length <= MAX_BINARY_BYTES) {
return buildImageArtifactResult(
tc.id,
args.path,
file.mimeType,
buffer.length,
buffer.toString('base64'),
);
}
// TODO: PDF artifact support requires a document content block path
// (image_url runs image processing which fails for PDFs). Falls through
// to the generic binary handler below.
return {
toolCallId: tc.id,
status: 'success',
content: `Binary file (${file.mimeType}, ${buffer.length} bytes). Use bash to process: ${sandboxFilePath}`,
};
}
const text = buffer.toString('utf-8');
const skillFiltered = filteredSkillResult(tc, req, {
files: [{ filename: args.path, content: text }],
});
if (skillFiltered != null) {
return skillFiltered;
}
const fileFiltered = filteredFileResult(tc, req, args.path, text);
if (fileFiltered != null) {
return fileFiltered;
}
// Cache text on first read (skill files are immutable)
if (file.content == null && updateSkillFileContent && buffer.length <= MAX_CACHE_BYTES) {
updateSkillFileContent(
skill._id,
relativePath,
{ content: text, isBinary: false },
file.file_id,
).catch((err: unknown) => {
logAxiosError({
message: '[handleReadFileCall] cache write failed',
error: err,
});
});
}
if (buffer.length > MAX_READABLE_BYTES) {
return {
toolCallId: tc.id,
status: 'success',
content: `File too large (${buffer.length} bytes, limit: ${MAX_READABLE_BYTES}). Use bash: cat ${sandboxFilePath}`,
};
}
return localTextReadResult(
tc,
args.path,
text,
`File: ${args.path} (${buffer.length} bytes)\n\n`,
);
} catch (error) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Failed to read file: ${error instanceof Error ? error.message : 'Unknown error'}`,
};
}
}
async function handleSkillToolCall(
tc: ToolCallRequest,
mergedConfigurable: Record<string, unknown>,
options: ToolExecuteOptions,
agentId?: string,
req?: ServerRequest,
signal?: AbortSignal,
rateLimitBudget?: import('~/utils').CodeApiRateLimitBudget,
): Promise<ToolExecuteResult> {
const {
getSkillByName,
listSkillFiles,
getStrategyFunctions,
batchUploadCodeEnvFiles,
getSessionInfo,
checkIfActive,
updateSkillFileCodeEnvIds,
} = options;
const args = tc.args as { skillName?: string; args?: string };
if (!args.skillName) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'skillName is required',
};
}
if (!getSkillByName) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: 'Skill execution is not configured',
};
}
const accessibleIds = (mergedConfigurable?.accessibleSkillIds as Types.ObjectId[]) ?? [];
/* On a name this run's authoring path bound to a specific doc, pin the
accessible set to ONLY that `_id`, exactly as the `read_file` path
pins to a primed `_id`. `getSkillByName` resolves deployment skills
from the registry before the database and matches on name plus
accessibility alone, so a same-name deployment skill sharing the
accessible set would otherwise shadow the doc just authored — the
model would be told its creation is invocable and then be handed
different instructions. Pinning also drops `preferModelInvocable`,
matching `resolveSkillForAuthoring`: with one candidate there is no
collision to resolve, and the `disable-model-invocation` gate below
must still see the authored doc rather than a same-name twin.
`preferModelInvocable` keeps name-collision resolution aligned with
the catalog otherwise: a newer `disable-model-invocation: true`
duplicate can't shadow the cataloged invocable doc. Model-only
(`userInvocable: false`) skills are intentionally still resolvable
here — they're valid model-invocation targets. Falls back to the
newest match so the disabled-only case still resolves and the gate
below fires its explicit error. */
const authoredIdString = getAuthoredSkillId(args.skillName, mergedConfigurable);
const lookupAccessibleIds = authoredIdString
? [new Types.ObjectId(authoredIdString)]
: accessibleIds;
const skill = await getSkillByName(
args.skillName,
lookupAccessibleIds,
authoredIdString ? {} : { preferModelInvocable: true },
);
if (!skill) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Skill "${args.skillName}" not found or not accessible`,
};
}
/**
* `disable-model-invocation: true` skills are excluded from the catalog
* the model sees, but a model that learned the name elsewhere (stale
* cache, hallucinated guess) could still try to invoke it. Reject
* explicitly so the error message tells the model exactly why and it
* doesn't loop retrying. Manual `$` invocation goes through
* `resolveManualSkills`, which is unaffected by this flag.
*/
if (skill.disableModelInvocation === true) {
return {
toolCallId: tc.id,
status: 'error',
content: '',
errorMessage: `Skill "${args.skillName}" cannot be invoked by the model`,
};
}
let body = skill.body;
if (args.args) {
body = body.replace(/\$ARGUMENTS/g, args.args);
}
const filtered = filteredSkillResult(tc, req, {
name: skill.name,
description: skill.description,
body,
frontmatter: skill.frontmatter,
});
if (filtered != null) {
return filtered;
}
const injectedMessages: InjectedMessage[] = [buildSkillPrimeMessage({ name: skill.name, body })];
let contentText = `Skill "${args.skillName}" loaded. Follow the instructions below.`;
let artifact:
| {
session_id: string;
files: Array<{
id: string;
/** Resource id (skill `_id`). codeapi requires this distinct
* from the storage `id` to scope sessionKey by resource. */
resource_id: string;
name: string;
storage_session_id: string;
kind?: 'skill' | 'agent' | 'user';
version?: number;
}>;
}
| undefined;
// Prime skill files to code env — only when the `execute_code` capability
// is enabled for this run. The flag is threaded via configurable upstream
// so this gate cannot be bypassed.
const codeEnvAvailable = mergedConfigurable?.codeEnvAvailable === true;
const codeExecutionContext = getCodeExecutionContext(mergedConfigurable);
if (
codeEnvAvailable &&
skill.fileCount > 0 &&
req &&
listSkillFiles &&
getStrategyFunctions &&
batchUploadCodeEnvFiles
) {
let primeResult: PrimeSkillFilesResult | null = null;
try {
signal?.throwIfAborted();
const skillFiles = await listSkillFiles(skill._id);
signal?.throwIfAborted();
primeResult = await primeSkillFiles({
skill,
skillFiles,
req,
getStrategyFunctions,
batchUploadCodeEnvFiles,
getSessionInfo,
checkIfActive,
updateSkillFileCodeEnvIds,
codeExecutionContext,
signal,
rateLimitBudget,
});
if (primeResult) {
/* `session_id` at the top of the artifact is the (representative)
* execution session — ToolNode reads it for CodeSessionContext
* continuity. Per-file storage lives on each file's
* `storage_session_id`. Skill files carry `kind: 'skill'` and
* the skill's version so codeapi's sessionKey scopes the
* cache per-revision. */
artifact = {
session_id: primeResult.storage_session_id,
files: primeResult.files.map((f) => ({
id: f.id,
/* `resource_id` (skill `_id`) is what codeapi feeds into
* `<tenant>:skill:<id>:v:<version>` — without it the next
* /exec authorizer sees `resource_id: undefined` and 400s. */
resource_id: f.resource_id,
name: f.name,
storage_session_id: f.storage_session_id,
kind: 'skill',
version: skill.version,
})),
};
}
} catch (error) {
if (isAbortError(error)) {
throw error;
}
if (isContentFilterError(error)) {
return error instanceof ContentFilterError
? errorResult(tc, modelBoundContentFilterErrorMessage(error.body))
: errorResult(tc, error.body.message);
}
logger.error(
`[handleSkillToolCall] Failed to prime files for skill "${args.skillName}":`,
error instanceof Error ? error.message : error,
);
}
if (!primeResult) {
/* Degrade loudly: without this note the model follows skill
* instructions referencing sandbox paths that were never mounted
* and burns turns on missing-path errors. */
contentText +=
`\n\nNote: this skill's bundled files could not be loaded into the code environment ` +
`(upload failed or was rate-limited). Paths under /mnt/data/${SKILL_FILE_PREFIX}${skill.name}/ ` +
`are NOT available to bash or code execution this turn. Use the read_file tool to view bundled files instead.`;
}
}
options.onSkillResolved?.(
{
id: skill._id.toString(),
name: skill.name,
version: skill.version,
contentDigest: createSkillContentDigest(skill.body),
},
{ agentId },
);
return {
toolCallId: tc.id,
content: contentText,
status: 'success',
artifact,
injectedMessages,
};
}
function getFileAuthoringQueueKey(
tc: ToolCallRequest,
mergedConfigurable: Record<string, unknown>,
): string | undefined {
if (!isHostFileAuthoringToolCall(tc.name, mergedConfigurable)) {
return undefined;
}
const args = tc.args as { path?: unknown };
if (typeof args.path !== 'string' || args.path.length === 0) {
return undefined;
}
if (!args.path.startsWith(SKILL_FILE_PREFIX)) {
return `sandbox:${args.path}`;
}
const parsed = parseSkillAuthoringPath(args.path);
if (typeof parsed === 'string') {
return `skill:${args.path}`;
}
return `skill:${parsed.skillName}`;
}
/**
* Creates the ON_TOOL_EXECUTE handler for event-driven tool execution.
* This handler receives batched tool calls, loads the required tools,
* executes them in parallel, and resolves with the results.
*/
/**
* Foreground tool failures reach persisted parts wrapped by the graph as
* `Error: [toolName] tool call failed: <message>` — the exact shape the
* client's `isError` detection keys on. Detached failures bypass the graph,
* so wrap them identically before patching the dispatch row, or a reloaded
* failed background run renders as clean stdout.
*/
function toBackgroundToolFailure(toolName: string, message: string): string {
if (hasToolCallErrorPrefix(message)) {
return message;
}
return `Error: [${toolName}] tool call failed: ${message}`;
}
/**
* Invoke-time `toolCall` config for a call: identity plus the stateful
* runtime-session hint and code-session context (`session_id` +
* `_injected_files`) for sandbox-bound tools. Shared by the foreground path
* and background dispatch so a detached code call keeps the same session and
* file continuity a foreground call gets.
*/
function buildToolCallConfig(
tc: ToolCallRequest,
mergedConfigurable: Record<string, unknown>,
): Record<string, unknown> {
const toolCallConfig: Record<string, unknown> = {
id: tc.id,
stepId: tc.stepId,
turn: tc.turn,
};
/* Stateful runtime-session hint: the SDK resolves it onto
* the request for execute_code/bash (orthogonal to the
* transient exec-session below — a first call has a hint but
* no session yet). The remote executors read it off
* `config.toolCall._runtime_session_hint`; without this the
* event-driven ON_TOOL_EXECUTE path drops it and every
* conversation collapses onto the Code API's `default`
* session (no per-conversation isolation). */
if (tc.runtimeSessionHint != null && tc.runtimeSessionHint !== '') {
toolCallConfig._runtime_session_hint = tc.runtimeSessionHint;
}
if (tc.codeSessionContext && isCodeSessionAwareToolCall(tc.name, mergedConfigurable)) {
toolCallConfig.session_id = tc.codeSessionContext.session_id;
if (tc.codeSessionContext.files && tc.codeSessionContext.files.length > 0) {
toolCallConfig._injected_files = tc.codeSessionContext.files;
/* Last LC-controlled point before the wire. Mirrors
* codeapi's validator context so the two log sides
* correlate on a single grep. */
const refs = tc.codeSessionContext.files as Array<{
id?: unknown;
resource_id?: unknown;
storage_session_id?: unknown;
kind?: unknown;
version?: unknown;
name?: unknown;
}>;
const summary = refs.map((f) => ({
kind: f.kind,
hasResourceId: typeof f.resource_id === 'string' && !!f.resource_id,
hasStorageSessionId: typeof f.storage_session_id === 'string' && !!f.storage_session_id,
hasVersion: typeof f.version === 'number',
}));
let missingResourceId = 0;
let missingStorageSessionId = 0;
let missingVersion = 0;
const kindCounts: Record<string, number> = {};
for (const s of summary) {
if (!s.hasResourceId) missingResourceId++;
if (!s.hasStorageSessionId) missingStorageSessionId++;
if (!s.hasVersion) missingVersion++;
const k = typeof s.kind === 'string' ? s.kind : 'unknown';
kindCounts[k] = (kindCounts[k] ?? 0) + 1;
}
logger.debug(
`[code-env:inject] tool=${tc.name} files=${refs.length} ` +
`missingResourceId=${missingResourceId} ` +
`missingStorageSessionId=${missingStorageSessionId} ` +
`missingVersion=${missingVersion} ` +
`kinds=${JSON.stringify(kindCounts)}`,
);
if (missingResourceId > 0) {
logger.warn(
`[code-env:inject] ${missingResourceId}/${refs.length} files missing resource_id ` +
`for tool=${tc.name} — codeapi will reject with 400`,
{ summary },
);
}
} else {
/* Empty `_injected_files` on a code-execution tool
* call. Almost always means the seeding chain
* (primeCodeFiles → initialSessions →
* CodeSessionContext) dropped the file upstream.
* `session_id` is still emitted for continuity, but
* concrete file refs must arrive through
* `_injected_files`; agents no longer falls back to
* `/files/<sid>`. Pair with `[primeCodeFiles]`
* traces below to locate the layer that lost the ref. */
logger.warn(
`[code-env:inject] tool=${tc.name} _injected_files=0 — sandbox will see no input files`,
{
tool: tc.name,
session_id: tc.codeSessionContext.session_id,
codeSessionContextHasFiles: tc.codeSessionContext.files !== undefined,
codeSessionContextFileCount: tc.codeSessionContext.files?.length ?? 0,
},
);
}
}
return toolCallConfig;
}
/**
* One-shot handoff of the files a `skill` call uploads to the code calls that
* share its batch.
*
* The graph hands every call in a batch the code-session snapshot it took when
* it planned the batch, and folds a `skill` call's artifact back into the
* session only after the whole batch settles. A code call dispatched beside a
* `skill` call therefore reads a context with none of the skill's bundled
* files: `_injected_files` omits them and the sandbox has no
* `/mnt/data/skills/<name>/` for that batch. Waiting here, then merging the
* uploaded refs into the code call's own context, is what makes the files
* visible on the turn that loaded them.
*/
interface SkillFilesHandoff {
/** Records a settled `skill` call; the last one releases every waiter. */
record(result: ToolExecuteResult): void;
/** Resolves once every `skill` call in the batch has settled, then merges
* their uploaded files into this call's own code-session context. Never
* rejects: a skill whose files failed to load contributes nothing and the
* waiting call runs with the context it already had. */
applyTo(tc: ToolCallRequest): Promise<void>;
}
function createSkillFilesHandoff(
skillToolCallIds: ReadonlySet<string>,
signal?: AbortSignal,
): SkillFilesHandoff {
const pendingSkillCallIds = new Set(skillToolCallIds);
const uploadedFiles: CodeEnvFile[] = [];
let release!: () => void;
const settled = new Promise<void>((resolve) => {
release = resolve;
});
/** A Stop ends the turn for every call in the batch, so waiters are released
* the moment it lands instead of riding out the upload's own cancellation. */
const onAbort = (): void => release();
if (signal?.aborted === true) {
release();
} else {
signal?.addEventListener('abort', onAbort, { once: true });
}
return {
record(result: ToolExecuteResult): void {
if (!pendingSkillCallIds.delete(result.toolCallId)) {
return;
}
const files =
result.status === 'success'
? (result.artifact as { files?: CodeEnvFile[] } | undefined)?.files
: undefined;
if (files && files.length > 0) {
uploadedFiles.push(...files);
}
if (pendingSkillCallIds.size === 0) {
signal?.removeEventListener('abort', onAbort);
release();
}
},
async applyTo(tc: ToolCallRequest): Promise<void> {
await settled;
/* Same call shape as the provisioned-attachment fold in the executor, so
* identity (`storage_session_id` + `id`) and destination rules stay
* consistent. Returns undefined when no skill contributed a file. */
const merged = mergeCodeFilesIntoContext(
tc.codeSessionContext as CodeSessionContext | undefined,
uploadedFiles,
);
if (merged) {
tc.codeSessionContext = merged;
}
},
};
}
function getToolFailureFeedback(content: ToolExecuteResult['content']): string {
if (typeof content === 'string') return content;
const messages: string[] = [];
for (const part of content) {
if (
part != null &&
typeof part === 'object' &&
'type' in part &&
part.type === 'text' &&
'text' in part &&
typeof part.text === 'string'
)
messages.push(part.text);
}
return messages.join('\n') || 'Tool execution failed.';
}
export function createToolExecuteHandler(handlerOptions: ToolExecuteOptions): EventHandler {
const authoredSkills = new AuthoredSkillState();
const resumedSkillConfigurables = new Map<string, Record<string, unknown>>();
const {
scheduledMCPExecution,
runSignal: hostRunSignal,
foregroundRunId,
loadTools,
toolEndCallback,
attachedCommandStepIds,
eventActorDetachedAction,
persistBackgroundCodeResult,
backgroundToolCompletion,
emitAttachment,
emitPtcProgress,
subagentTasks,
runFiles,
ordinaryToolCancellation = false,
backgroundCompletionResultMaxChars = AGENT_BACKGROUND_COMPLETION_RESULT_MAX_CHARS_DEFAULT,
provisionFiles,
} = handlerOptions;
const handler: EventHandler = {
handle: async (_event: string, data: ToolExecuteBatchRequest) => {
const {
toolCalls,
agentId,
configurable: incomingConfigurable,
metadata: incomingMetadata,
signal: eventRunSignal,
resolve,
reject,
} = data;
const onResultAdmissionStart = (data as InterruptibleToolBatchRequest).onResultAdmissionStart;
const executionContext = (
data as ToolExecuteBatchRequest & { executionContext?: SubagentExecutionContext }
).executionContext;
const authoredScope = authoredSkills.scope(agentId, executionContext);
const options: ToolExecuteOptions = {
...handlerOptions,
onSkillAuthored: (binding) => authoredSkills.record(authoredScope, binding),
};
// Only the SDK-owned batch field may establish a child execution. Runtime
// configurable and callback metadata can otherwise carry inherited values.
/**
* Authored-skill identity has to outlive the per-batch copy below, which
* is what makes a skill created in one batch resolvable in the next.
* A shallow copy shares object references, so seeding the map on the
* run's own configurable lets `rememberAuthoredSkill` mutate it in place
* and later batches observe it, exactly as the shared
* `accessibleSkillIds` array already crosses batches. A fresh map
* assigned onto the copy would be discarded with the copy.
*/
if (incomingConfigurable != null && incomingConfigurable.authoredSkillIdsByName == null) {
incomingConfigurable.authoredSkillIdsByName = {};
}
const configurable: Record<string, unknown> | undefined =
incomingConfigurable == null ? undefined : { ...incomingConfigurable, executionContext };
const metadata: Record<string, unknown> | undefined =
incomingMetadata == null && executionContext == null
? undefined
: { ...incomingMetadata, executionContext };
let eventRunId: string | undefined;
if (typeof metadata?.run_id === 'string') {
eventRunId = metadata.run_id;
} else if (typeof configurable?.run_id === 'string') {
eventRunId = configurable.run_id;
}
const foregroundHostSignal =
eventRunId == null || eventRunId === foregroundRunId ? hostRunSignal : undefined;
const runSignal =
foregroundHostSignal != null &&
eventRunSignal != null &&
foregroundHostSignal !== eventRunSignal
? AbortSignal.any([foregroundHostSignal, eventRunSignal])
: (foregroundHostSignal ?? eventRunSignal);
const callerCapabilityProjection = resolveCallerCapabilityProjectionSnapshot(
(
data as ToolExecuteBatchRequest & {
callerCapabilityProjection?: unknown;
}
).callerCapabilityProjection,
);
/** Optional per-call channel (agents SDK > 3.2.33); cast keeps older
* installed SDK typings compiling until the release lands. */
const onResult = (
data as ToolExecuteBatchRequest & {
onResult?: (result: ToolExecuteResult) => void;
}
).onResult;
/** Set only for a batch that mixes `skill` calls with code calls (see
* {@link createSkillFilesHandoff}); `undefined` leaves every other batch
* fully concurrent. */
let skillFilesHandoff: SkillFilesHandoff | undefined;
/** Reports a settled result so the agent graph can emit that call's
* completion immediately instead of waiting for the whole batch;
* `resolve` below remains the authoritative batch outcome. */
const reportResult = (result: ToolExecuteResult): ToolExecuteResult => {
/* Every per-call return in the batch funnels through here, so this is
* the one place that observes a `skill` call settling whatever path
* produced its result, including the filtered and error paths. */
skillFilesHandoff?.record(result);
try {
onResult?.(result);
} catch (callbackError) {
logger.warn('[ON_TOOL_EXECUTE] onResult callback error:', callbackError);
}
return result;
};
try {
await runOutsideTracing(async () => {
try {
const sourceConfigurable = configurable as Record<string, unknown> | undefined;
const sourceReq = sourceConfigurable?.req as ServerRequest | undefined;
const preloadedNameBlocks = new Map<ToolCallRequest, ToolExecuteResult>();
const allowedToolCalls: ToolCallRequest[] = [];
for (const tc of toolCalls) {
const filteredName = filteredToolArgumentsResult(tc, sourceReq, undefined);
if (filteredName != null) {
preloadedNameBlocks.set(tc, filteredName);
} else {
allowedToolCalls.push(tc);
}
}
if (allowedToolCalls.length === 0) {
resolve(
toolCalls.map((tc) =>
reportResult(
preloadedNameBlocks.get(tc) ??
errorResult(tc, 'Submitted tool name was blocked.'),
),
),
);
return;
}
const toolNames = [...new Set(allowedToolCalls.map((tc) => tc.name))];
const runFileSharingActive = runFiles?.isActive() === true;
if (runFileSharingActive) {
if (!agentId) throw new Error('Shared-file tools require an executing agent.');
await runFiles!.prepareTools(
agentId,
executionContext,
runSignal ?? new AbortController().signal,
toolNames.some(isFileResourceToolName) ? 'refresh' : 'snapshot',
);
}
const provisionedCodeFiles = provisionFiles
? await provisionFiles(toolNames, agentId, runSignal, executionContext)
: undefined;
const { loadedTools, configurable: toolConfigurable } = await loadTools(
toolNames,
agentId,
sourceConfigurable,
callerCapabilityProjection,
runSignal,
executionContext,
);
const toolMap = new Map(loadedTools.map((t) => [t.name, t]));
const loadedConfigurable = toolConfigurable as Record<string, unknown> | undefined;
const authoredScopeKey = JSON.stringify(authoredScope);
let resumedSkillConfigurable = resumedSkillConfigurables.get(authoredScopeKey);
const baseConfigurable = mergeToolConfigurables(sourceConfigurable, loadedConfigurable);
// Restored identity wins; current capability and request fields still come from loadTools.
const mergedConfigurable = resumedSkillConfigurable
? mergeToolConfigurables(resumedSkillConfigurable, baseConfigurable)
: baseConfigurable;
if (authoredSkills.hasPending) {
const requestedSkills = new Map<string, ToolCallRequest[]>();
for (const tc of allowedToolCalls) {
const args = tc.args as { path?: unknown; skillName?: unknown };
let skillName: string | undefined;
if (tc.name === Constants.SKILL_TOOL && typeof args.skillName === 'string') {
skillName = args.skillName;
} else if (
typeof args.path === 'string' &&
(args.path.startsWith(SKILL_FILE_PREFIX) ||
(tc.name === Constants.READ_FILE && !args.path.startsWith('workspace/'))) &&
(tc.name === Constants.READ_FILE ||
isHostFileAuthoringToolCall(tc.name, mergedConfigurable))
) {
const path = args.path.startsWith(SKILL_FILE_PREFIX)
? args.path.slice(SKILL_FILE_PREFIX.length)
: args.path;
skillName = path.split('/')[0];
}
if (skillName)
requestedSkills.set(skillName, [...(requestedSkills.get(skillName) ?? []), tc]);
}
const restored = authoredSkills.take(authoredScope, new Set(requestedSkills.keys()));
if (restored.length > 0) {
const req = mergedConfigurable.req as ServerRequest | undefined;
await Promise.all(
restored.map(async (binding) => {
const skill =
isSkillAuthoringAvailable(mergedConfigurable) &&
req &&
options.getAuthorSkillByName
? await options.getAuthorSkillByName({ req, name: binding.name })
: null;
const allowed =
skill &&
skill._id.toString() === binding.id &&
req &&
options.canEditSkill &&
(await options.canEditSkill({ req, skillId: skill._id }));
if (!allowed || !skill) {
for (const tc of requestedSkills.get(binding.name) ?? []) {
preloadedNameBlocks.set(
tc,
errorResult(tc, `Skill "${binding.name}" not found or not accessible.`),
);
}
return;
}
if (!resumedSkillConfigurable) {
resumedSkillConfigurable = {};
resumedSkillConfigurables.set(authoredScopeKey, resumedSkillConfigurable);
}
rememberAuthoredSkill([mergedConfigurable, resumedSkillConfigurable], skill, {
prime: binding.primed,
});
authoredSkills.confirm(authoredScope, binding.name);
}),
);
}
}
if (mergedConfigurable != null) mergedConfigurable.executionContext = executionContext;
/* The graph populated each call's code-session context from the sessions that
* existed at run start, before this batch provisioned anything, and nothing
* downstream refreshes it. buildToolCallConfig reads `_injected_files` from
* that context alone, so without this fold a successful upload still reaches
* a sandbox that cannot see the file. */
if (provisionedCodeFiles && provisionedCodeFiles.length > 0) {
for (const tc of allowedToolCalls) {
if (
!isCodeSessionAwareToolCall(tc.name, mergedConfigurable) &&
!(runFileSharingActive && isCodeFileToolName(tc.name))
) {
continue;
}
const merged = mergeCodeFilesIntoContext(
tc.codeSessionContext as CodeSessionContext | undefined,
provisionedCodeFiles,
);
if (merged) {
tc.codeSessionContext = merged;
}
}
}
/* A code call in this batch reads its code-session context when it
* executes, while the `skill` call beside it is still uploading the
* files that belong in that context. Only a batch carrying both
* kinds of call waits; every other batch stays fully concurrent. */
const waitsForSkillFiles = (tc: ToolCallRequest): boolean =>
tc.name !== Constants.SKILL_TOOL &&
(isCodeSessionAwareToolCall(tc.name, mergedConfigurable) ||
(runFileSharingActive && isCodeFileToolName(tc.name)));
const skillToolCallIds = new Set(
allowedToolCalls.filter((tc) => tc.name === Constants.SKILL_TOOL).map((tc) => tc.id),
);
if (skillToolCallIds.size > 0 && allowedToolCalls.some(waitsForSkillFiles)) {
skillFilesHandoff = createSkillFilesHandoff(skillToolCallIds, runSignal);
}
const codeExecutionContext = getCodeExecutionContext(mergedConfigurable);
const runtimeSessionHint = codeExecutionContext?.runtimeSessionHint;
if (runFileSharingActive && executionContext != null) {
for (const tc of allowedToolCalls) {
if (
!isCodeSessionAwareToolCall(tc.name, mergedConfigurable) &&
!isCodeFileToolName(tc.name)
)
continue;
if (!runtimeSessionHint || codeExecutionContext?.environmentType === 'attached') {
throw new Error('This child execution has no isolated file workspace.');
}
// SDK tool configs may still carry a parent's runtime hint. The
// host prepared this partition using the authorized child identity.
tc.runtimeSessionHint = runtimeSessionHint;
}
}
const executionRouteKey =
codeExecutionContext?.executionRouteKey ?? codeExecutionContext?.executionProfile;
const sandboxConversationId =
((metadata as Record<string, unknown>)?.thread_id as string | undefined) ??
(mergedConfigurable?.thread_id as string | undefined) ??
(
(mergedConfigurable?.req as ServerRequest | undefined)?.body as
| { conversationId?: string }
| undefined
)?.conversationId;
const markCodeSandboxWarm = (): void => {
if (runtimeSessionHint) {
void markSandboxReady(runtimeSessionHint, executionRouteKey);
}
if (sandboxConversationId) {
void markSandboxReady(sandboxConversationId);
}
};
/** Provenance is the resolved tool instance, never the output. */
const recordAttachedCommand = (tc: ToolCallRequest, tool: unknown): void => {
if (tc.stepId && isAttachedWorkspaceBashTool(tool)) {
attachedCommandStepIds?.add(tc.stepId);
}
};
const authoringQueues = new Map<string, Promise<void>>();
const sandboxAuthoringContexts = new Map<string, SandboxSessionContext>();
/**
* Background tool calls. The set of tools that received the injected
* `run_in_background` param is threaded per-agent from `initializeAgent`
* via `configurable.backgroundToolNames` (a reliable channel, unlike
* `toolRegistry` which only reaches the executor for PTC/tool_search).
* A non-empty set is the exact condition under which the run registered
* the poll tool and the model could have been shown the param, so it
* also gates the `check_background_task` interception and enforces the
* per-tool opt-in (a tool not in the set never had the param).
*/
const backgroundToolNames = mergedConfigurable?.backgroundToolNames as
| string[]
| undefined;
const backgroundEnabledForRun = (backgroundToolNames?.length ?? 0) > 0;
const backgroundControlEnabled = backgroundEnabledForRun || subagentTasks != null;
const backgroundToolSet: ReadonlySet<string> = backgroundEnabledForRun
? new Set(backgroundToolNames)
: EMPTY_BACKGROUND_TOOL_SET;
const backgroundReq = backgroundControlEnabled
? (mergedConfigurable?.req as ServerRequest | undefined)
: undefined;
const backgroundUserId = backgroundControlEnabled
? resolveBackgroundUserId(mergedConfigurable)
: '';
const backgroundConversationId = backgroundControlEnabled
? (((metadata as Record<string, unknown>)?.thread_id as string | undefined) ??
(mergedConfigurable?.thread_id as string | undefined) ??
(backgroundReq?.body as { conversationId?: string } | undefined)?.conversationId ??
'')
: '';
/**
* Registers the task, returns a synthetic handle immediately, and
* runs the real tool as a floating promise whose result lands in the
* registry for `check_background_task` to collect. Idempotent by
* `toolCallId` so graph re-execution (resume/replay) never double-fires.
*/
const backgroundRunId = (metadata as Record<string, unknown>)?.run_id as
| string
| undefined;
const dispatchBackgroundToolCall = async (
tc: ToolCallRequest,
): Promise<ToolExecuteResult> => {
/** A tool that failed to load must error immediately (matching the
* foreground path) — a synthetic "started" handle would tell the
* model a side effect is in flight that never executed. */
const tool = toolMap.get(tc.name);
if (!tool) {
const missingToolResult: ToolExecuteResult = {
toolCallId: tc.id,
status: 'error' as const,
content: '',
errorMessage: `Tool ${tc.name} not found`,
};
return (
filteredToolOutputResult(tc, backgroundReq, {
errorMessage: missingToolResult.errorMessage,
}) ?? missingToolResult
);
}
recordAttachedCommand(tc, tool);
const isCodeCall = isCodeSessionAwareToolCall(tc.name, mergedConfigurable);
const harvestEnabled = isCodeCall && persistBackgroundCodeResult != null;
const liveArtifactPollRequired =
!harvestEnabled &&
(tool as StructuredToolInterface & { responseFormat?: unknown }).responseFormat ===
Constants.CONTENT_AND_ARTIFACT;
const backgroundStepId =
typeof tc.stepId === 'string' && tc.stepId.trim() !== '' ? tc.stepId : undefined;
const strippedArgs = stripIntentForInvoke(stripRunInBackgroundArg(tc.args), tool);
const normalizedArgs = normalizeToolInvokeArgs(strippedArgs, tool);
const filtered = filteredToolArgumentsResult(tc, backgroundReq, normalizedArgs);
if (filtered != null) {
return filtered;
}
const registration = {
userId: backgroundUserId,
conversationId: backgroundConversationId,
toolCallId: tc.id,
stepId: backgroundStepId,
toolName: tc.name,
messageId: backgroundRunId,
harvestStarted: harvestEnabled,
liveArtifactPollRequired,
/** Scope idempotency to the agent + run + turn so a later turn's
* or a second agent's repeated provider id (e.g. `call_0`)
* starts a fresh task instead of colliding. */
agentId,
runId: `${backgroundRunId ?? ''}:${tc.turn ?? backgroundStepId ?? ''}`,
};
const capacityAdmission =
eventActorDetachedAction == null
? undefined
: backgroundTaskRegistry.reserveCapacity(registration);
if (capacityAdmission != null && 'atCapacity' in capacityAdmission) {
return {
toolCallId: tc.id,
status: 'success' as const,
content: buildBackgroundCapacityContent(tc.name, capacityAdmission.scope),
};
}
const capacityPermit =
capacityAdmission != null && 'permit' in capacityAdmission
? capacityAdmission.permit
: undefined;
let detachedReservation;
try {
detachedReservation = await eventActorDetachedAction?.reserve({
toolName: tc.name,
toolCallId: tc.id,
turnId: registration.runId,
arguments: normalizedArgs,
});
} catch (error) {
if (capacityPermit != null) {
backgroundTaskRegistry.releaseCapacity(capacityPermit);
}
throw error;
}
if (detachedReservation?.status === 'conflict') {
if (capacityPermit != null) {
backgroundTaskRegistry.releaseCapacity(capacityPermit);
}
return {
toolCallId: tc.id,
status: 'error' as const,
content: '',
errorMessage:
detachedReservation.error ??
'Detached Event Actor action conflicts with its durable launch authority',
};
}
if (detachedReservation?.status === 'terminal') {
if (capacityPermit != null) {
backgroundTaskRegistry.releaseCapacity(capacityPermit);
}
if (detachedReservation.outcome === 'succeeded') {
return {
toolCallId: tc.id,
status: 'success' as const,
content: detachedReservation.result ?? '',
};
}
return {
toolCallId: tc.id,
status: 'error' as const,
content: '',
errorMessage:
detachedReservation.error ?? `Detached action ${detachedReservation.outcome}`,
};
}
if (detachedReservation?.status === 'replay') {
if (capacityPermit != null) {
backgroundTaskRegistry.releaseCapacity(capacityPermit);
}
return {
toolCallId: tc.id,
status: 'success' as const,
content: buildBackgroundHandleContent({
id: detachedReservation.taskId,
toolName: tc.name,
status: 'running',
}),
};
}
const backgroundAbortController = new AbortController();
let backgroundAbortSource: 'manual' | 'timeout' | 'shutdown' | undefined;
const created = backgroundTaskRegistry.create({
...(detachedReservation?.status === 'reserved'
? { taskId: detachedReservation.taskId }
: {}),
...registration,
...(capacityPermit == null ? {} : { capacityPermit }),
requestCancellation: () => {
if (backgroundAbortSource != null || backgroundAbortController.signal.aborted) {
return false;
}
backgroundAbortSource = 'manual';
backgroundAbortController.abort(
new DOMException('Background task cancellation requested', 'AbortError'),
);
return true;
},
});
if ('atCapacity' in created) {
if (detachedReservation?.status === 'reserved') {
throw new Error('Detached Event Actor lost its pre-admitted background capacity');
}
return {
toolCallId: tc.id,
status: 'success' as const,
content: buildBackgroundCapacityContent(tc.name, created.scope),
};
}
const { task, isNew } = created;
let completionPreregistered = task.completionWakeup === true;
let completionAdmission: BackgroundToolWakeupAdmission | undefined;
if (isNew) {
if (
detachedReservation?.status !== 'reserved' &&
backgroundToolCompletion?.preregister != null &&
backgroundStepId != null &&
backgroundRunId != null &&
backgroundRunId !== ''
) {
try {
const admission = await backgroundToolCompletion.preregister({
scheduleMCPIdentity: scheduledMCPExecution?.identity ?? null,
taskId: task.id,
toolCallId: tc.id,
toolName: tc.name,
userId: backgroundUserId,
...(typeof backgroundReq?.user?.tenantId === 'string' &&
backgroundReq.user.tenantId !== ''
? { tenantId: backgroundReq.user.tenantId }
: {}),
conversationId: backgroundConversationId,
parentMessageId: backgroundRunId,
parentAgentId: agentId,
createdAt: task.createdAt,
});
if (admission !== false) {
completionAdmission = admission;
completionPreregistered = true;
backgroundTaskRegistry.markCompletionWakeup(
backgroundUserId,
backgroundConversationId,
task.id,
admission,
);
}
} catch (registrationError) {
logger.warn(
`[background] Failed to preregister completion for task ${task.id}; polling remains available.`,
registrationError,
);
}
}
let durableReceiptWrite: Promise<boolean> | undefined;
let durableReceiptAmbiguous = false;
let durableResultConfirmed = false;
let forcedShutdownResult = false;
let resolveDurableReceipt: () => void = () => undefined;
const durableReceiptSettled = new Promise<void>((resolve) => {
resolveDurableReceipt = resolve;
});
const confirmDurableResult = (): void => {
durableResultConfirmed = true;
resolveDurableReceipt();
};
/** One durable receipt per task. The task's own settlement and a
* shutdown flush share the first write, so neither can retire or
* contradict a receipt the other already stored. */
const writeDurableReceipt = (receipt: {
status: 'completed' | 'error' | 'cancelled';
output?: string;
settledAt: Date;
}): Promise<boolean> => {
if (durableReceiptWrite != null) {
return durableReceiptWrite;
}
durableReceiptWrite = (async (): Promise<boolean> => {
if (completionAdmission?.persistResult == null) {
return false;
}
try {
return await completionAdmission.persistResult({
status: receipt.status,
output: truncateMiddle(
receipt.output ?? '',
backgroundCompletionResultMaxChars,
),
settledAt: receipt.settledAt,
});
} catch (receiptError) {
durableReceiptAmbiguous = true;
logger.warn(
`[background] Failed to persist independent result receipt for task ${task.id}:`,
receiptError,
);
return false;
}
})();
void durableReceiptWrite.then((written) => {
if (written) {
confirmDurableResult();
}
});
return durableReceiptWrite;
};
/** The task's own terminal result, recorded before its (possibly slow)
* persistence starts, so a shutdown flush can store it durably. */
let settledReceipt:
| { status: 'completed' | 'error' | 'cancelled'; output?: string }
| undefined;
/** Persists the settled result onto the dispatch turn's message
* (patch the tool-call part's output, persist generated files,
* append attachments), so a backgrounded code call reads like a
* foreground one on reload and in later model turns — even if
* the model never polls. Runs DETACHED from task completion:
* the dispatch row may not exist until that turn finalizes, so
* gating `complete()` on the patch would livelock same-turn
* polls on `running`. Failures degrade to poll-only delivery. */
const persistBackgroundResult = async (params: {
output?: string;
artifact?: unknown;
status: 'completed' | 'error' | 'cancelled';
}): Promise<void> => {
/** A provider id alone is not a durable part identity: it may
* repeat in later turns of the same response. New automatic
* completion delivery therefore fails closed to the legacy
* poll path when the host run-step anchor is unavailable. */
if (
detachedReservation?.status !== 'reserved' &&
backgroundToolCompletion != null &&
backgroundStepId == null &&
!harvestEnabled
) {
return;
}
const resolveBackgroundTask = (): BackgroundToolResultState => {
const current = backgroundTaskRegistry.get(
backgroundUserId,
backgroundConversationId,
task.id,
);
return {
taskId: task.id,
toolName: tc.name,
status: params.status === 'cancelled' ? 'error' : params.status,
...(params.status === 'cancelled' ? { cancelled: true } : {}),
settledAt: new Date(current?.updatedAt ?? Date.now()),
...(completionPreregistered ? { completionWakeup: true } : {}),
...(completionAdmission?.persistResult != null
? { completionReceipt: true }
: {}),
...(current?.resultClaim != null
? {
resultClaim: {
kind: current.resultClaim.kind,
claimId: current.resultClaim.claimId,
claimedAt: new Date(current.resultClaim.claimedAt),
...(current.resultClaim.receiptReconciled === true && {
receiptReconciled: true,
}),
...(current.resultClaim.generationId == null
? {}
: { generationId: current.resultClaim.generationId }),
},
}
: {}),
};
};
const localTask = backgroundTaskRegistry.get(
backgroundUserId,
backgroundConversationId,
task.id,
);
const backgroundTask = resolveBackgroundTask();
let durableReceiptReady = false;
const persistDurableReceipt = (receipt: {
status: 'completed' | 'error' | 'cancelled';
output?: string;
}): Promise<boolean> =>
writeDurableReceipt({ ...receipt, settledAt: backgroundTask.settledAt });
const retireFailedPersistence = async (
reason: string,
certainty: 'definite' | 'ambiguous',
): Promise<void> => {
/** Never retire a delivery that already holds a durable receipt,
* including one a shutdown flush stored ahead of this path. */
if (durableReceiptAmbiguous || (await durableReceiptWrite) === true) {
return;
}
if (completionAdmission == null) {
backgroundTaskRegistry.markCompletionPersistenceFailed(
backgroundUserId,
backgroundConversationId,
task.id,
);
return;
}
try {
/** A thrown write receipt is ambiguous: Mongo may have
* applied it before the response was lost, so only an
* unclaimed delivery may fall back. A returned `false`
* proves no terminal row was anchored and may retire a
* live deferring lease before it dead-letters forever. */
const retired = await completionAdmission.retire(
reason,
certainty === 'ambiguous' ? { onlyIfUnclaimed: true } : undefined,
);
if (!retired) {
const current = backgroundTaskRegistry.get(
backgroundUserId,
backgroundConversationId,
task.id,
);
/** A prior manual poll may already have durably retired
* this exact unclaimed delivery. In that case there is
* no automatic consumer left to race the process-local
* fallback, even though a second retirement is a no-op. */
if (current?.completionWakeupRetired === true) {
backgroundTaskRegistry.markCompletionPersistenceFailed(
backgroundUserId,
backgroundConversationId,
task.id,
);
return;
}
logger.warn(
`[background] Could not retire failed completion delivery for task ${task.id}.`,
);
return;
}
backgroundTaskRegistry.markCompletionPersistenceFailed(
backgroundUserId,
backgroundConversationId,
task.id,
);
} catch (retireError) {
logger.warn(
`[background] Failed to retire completion delivery for task ${task.id}:`,
retireError,
);
}
};
if (!harvestEnabled || !persistBackgroundCodeResult) {
durableReceiptReady = await persistDurableReceipt({
status: params.status,
output: params.output ?? localTask?.result,
});
if (
backgroundToolCompletion == null ||
detachedReservation?.status === 'reserved'
) {
return;
}
try {
const deliveryReady = await backgroundToolCompletion.persist({
toolName: tc.name,
toolCallId: tc.id,
stepId: backgroundStepId,
messageId: backgroundRunId,
conversationId: backgroundConversationId,
agentId,
output: params.output ?? localTask?.result,
backgroundTask,
resolveBackgroundTask,
});
if (!deliveryReady && !durableReceiptReady) {
await retireFailedPersistence(
'background tool result was not persisted',
'definite',
);
} else if (deliveryReady && !durableReceiptReady) {
confirmDurableResult();
completionAdmission?.expedite?.();
}
} catch (persistError) {
if (!durableReceiptReady) {
await retireFailedPersistence(
'background tool result persistence failed',
isContentFilterError(persistError) ? 'definite' : 'ambiguous',
);
}
logger.warn(
`[background] Failed to persist result for task ${task.id}:`,
persistError,
);
}
return;
}
try {
const persisted = await persistBackgroundCodeResult({
toolName: tc.name,
toolCallId: tc.id,
stepId: backgroundStepId,
messageId: backgroundRunId,
conversationId: backgroundConversationId,
/** Disambiguates repeated provider ids (e.g. `call_0`)
* across agents sharing one response message. */
agentId,
/** Stale-output ordering is decided by DISPATCH order,
* not harvest wall-clock: a slow old task settling
* after a newer run wrote the same filename must not
* overwrite it. */
dispatchedAt: task.createdAt,
codeExecutionContext,
...(detachedReservation?.status === 'reserved' ||
(!completionPreregistered && params.status !== 'cancelled')
? {}
: { backgroundTask, resolveBackgroundTask }),
output: params.output ?? localTask?.result,
artifact: params.artifact,
onFilesPersisted: (attachments) =>
backgroundTaskRegistry.finishHarvest(
backgroundUserId,
backgroundConversationId,
task.id,
attachments,
),
});
if (persisted == null) {
/** Harvest never persisted anything (missing anchor
* identity): hand delivery back to the legacy poll-turn
* callback, restoring the artifact if a poll already
* claimed it while the harvest was in flight. */
backgroundTaskRegistry.revokeHarvest(
backgroundUserId,
backgroundConversationId,
task.id,
params.artifact,
);
if (completionPreregistered && !durableReceiptReady) {
await retireFailedPersistence(
'background code result had no durable message anchor',
'definite',
);
}
return;
}
if (persisted.deliveryReady !== false) {
durableReceiptReady = await persistDurableReceipt({
status: params.status,
output: params.output ?? localTask?.result,
});
}
if (persisted.deliveryReady !== false) {
confirmDurableResult();
}
if (persisted.deliveryReady === false) {
await retireFailedPersistence(
'background code result was not persisted',
'definite',
);
}
backgroundTaskRegistry.finishHarvest(
backgroundUserId,
backgroundConversationId,
task.id,
persisted.attachments,
);
} catch (persistError) {
if (isContentFilterError(persistError)) {
const blockedMessage =
persistError instanceof ContentFilterError
? modelBoundContentFilterErrorMessage(persistError.body)
: persistError.body.message;
backgroundTaskRegistry.blockArtifact(
backgroundUserId,
backgroundConversationId,
task.id,
blockedMessage,
);
durableReceiptReady = await persistDurableReceipt({
status: 'error',
output: blockedMessage,
});
if (completionPreregistered && !durableReceiptReady) {
await retireFailedPersistence(
'background code result was blocked by content policy',
'definite',
);
}
logger.warn(
`[background] Generated code output for task ${task.id} was blocked by content policy.`,
);
return;
}
if (completionPreregistered && !durableReceiptReady) {
await retireFailedPersistence(
'background code result persistence failed',
'ambiguous',
);
}
logger.warn(
`[background] Failed to persist code result for task ${task.id}:`,
persistError,
);
backgroundTaskRegistry.revokeHarvest(
backgroundUserId,
backgroundConversationId,
task.id,
params.artifact,
);
}
};
const persistSettledBackgroundResult = async (
params: {
output?: string;
artifact?: unknown;
status: 'completed' | 'error' | 'cancelled';
},
forced = false,
): Promise<void> => {
if (forcedShutdownResult && !forced) {
return;
}
settledReceipt = { status: params.status, output: params.output };
/** Held for the whole persist, including a code harvest that waits for
* a long dispatch turn, so retention pressure cannot evict the task. */
backgroundTaskRegistry.markCompletionPersistencePending(
backgroundUserId,
backgroundConversationId,
task.id,
);
try {
await persistBackgroundResult(params);
} finally {
backgroundTaskRegistry.markCompletionPersistenceFinished(
backgroundUserId,
backgroundConversationId,
task.id,
);
}
};
const approvalDispatch = {
agentId,
toolCallId: tc.id,
executionScope: getToolApprovalExecutionScope(executionContext),
background: true,
};
noteToolApprovalDispatch(approvalDispatch);
let invokePromise: Promise<{ content?: unknown; artifact?: unknown }>;
try {
invokePromise = Promise.resolve(
tool.invoke(normalizedArgs, {
/** Full invoke config (not just identity): a detached
* code call still needs `session_id`/`_injected_files`/
* `_runtime_session_hint` or it runs fileless on the
* Code API's default runtime session. */
toolCall: buildToolCallConfig(tc, mergedConfigurable),
signal: backgroundAbortController.signal,
configurable: {
...mergedConfigurable,
[BACKGROUND_TOOL_INVOCATION_CONFIG_KEY]: true,
...(detachedReservation?.status === 'reserved'
? {
eventActorDetachedAction: {
taskId: detachedReservation.taskId,
idempotencyKey: detachedReservation.idempotencyKey,
},
}
: {}),
},
metadata: bindToolApprovalInvocation(
{ ...metadata, executingAgentId: agentId },
approvalDispatch,
),
} as Record<string, unknown>),
) as Promise<{ content?: unknown; artifact?: unknown }>;
} catch (error) {
/** Structured tools are permitted to reject synchronously.
* Preserve the durable reservation and route that rejection
* through the same terminal-evidence path as an async one. */
invokePromise = Promise.reject(error);
}
invokePromise = invokePromise.finally(() =>
finishToolApprovalDispatch(approvalDispatch),
);
const persistDetachedTerminal = async (
input:
| { status: 'succeeded'; result: unknown }
| { status: 'failed' | 'cancelled'; error: string },
): Promise<boolean> => {
if (
detachedReservation?.status !== 'reserved' ||
eventActorDetachedAction == null
) {
return true;
}
return eventActorDetachedAction.settle({
taskId: detachedReservation.taskId,
idempotencyKey: detachedReservation.idempotencyKey,
...input,
});
};
const wakeDetachedActor = async (): Promise<void> => {
if (
detachedReservation?.status !== 'reserved' ||
eventActorDetachedAction == null
) {
return;
}
try {
await eventActorDetachedAction.wake({
taskId: detachedReservation.taskId,
idempotencyKey: detachedReservation.idempotencyKey,
});
} catch (wakeError) {
logger.warn(
`[event-actor] Failed to wake detached action ${detachedReservation.taskId}`,
wakeError,
);
}
};
let producerHeartbeatInFlight: Promise<void> | undefined;
let producerHeartbeatStopped = false;
const producerAdmission = completionAdmission;
const producerHeartbeat =
producerAdmission == null
? undefined
: setInterval(() => {
if (producerHeartbeatStopped) {
return;
}
if (producerHeartbeatInFlight != null) {
return;
}
producerHeartbeatInFlight = producerAdmission
.renew()
.then((renewed) => {
if (!renewed) {
producerHeartbeatStopped = true;
if (producerHeartbeat != null) {
clearInterval(producerHeartbeat);
}
logger.warn(
`[background] Completion producer lease was not renewed for task ${task.id}.`,
);
}
})
.catch((heartbeatError) => {
logger.warn(
`[background] Failed to renew completion producer lease for task ${task.id}:`,
heartbeatError,
);
})
.finally(() => {
producerHeartbeatInFlight = undefined;
});
}, BACKGROUND_TOOL_PRODUCER_HEARTBEAT_MS);
(producerHeartbeat as { unref?: () => void } | undefined)?.unref?.();
const stopProducerHeartbeat = async (retireReason?: string): Promise<void> => {
if (!producerHeartbeatStopped) {
producerHeartbeatStopped = true;
if (producerHeartbeat != null) {
clearInterval(producerHeartbeat);
}
}
await producerHeartbeatInFlight;
if (retireReason == null || producerAdmission == null) {
return;
}
try {
const retired = await producerAdmission.retire(retireReason, {
onlyIfUnclaimed: true,
});
if (!retired) {
logger.warn(
`[background] Could not retire timed-out completion delivery for task ${task.id}.`,
);
}
} catch (retireError) {
logger.warn(
`[background] Failed to retire timed-out completion delivery for task ${task.id}:`,
retireError,
);
}
};
let producerRetirementTimeout: ReturnType<typeof setTimeout> | undefined;
const requestBackgroundAbort = (): void => {
backgroundAbortSource ??= 'timeout';
backgroundAbortController.abort(
new DOMException('Background task timed out', 'AbortError'),
);
producerRetirementTimeout = setTimeout(() => {
producerRetirementTimeout = undefined;
void stopProducerHeartbeat(
'background task did not settle after its abort grace period',
);
}, BACKGROUND_TASK_ABORT_GRACE_MS);
producerRetirementTimeout.unref?.();
};
const settlement = (async () => {
try {
const result = await withBackgroundTaskTimeout(
invokePromise,
requestBackgroundAbort,
);
if (isCodeCall) {
markCodeSandboxWarm();
}
const content =
isCodeCall && typeof result.content === 'string'
? cleanCodeToolOutput(result.content)
: result.content;
const filteredOutput = filteredToolOutputResult(tc, backgroundReq, {
content,
artifact: result.artifact,
});
if (filteredOutput != null) {
const policyError =
filteredOutput.errorMessage ?? 'Submitted content was blocked.';
const errorOutput = toBackgroundToolFailure(tc.name, policyError);
const registryError = isCodeCall ? errorOutput : policyError;
if (
!(await persistDetachedTerminal({
status: 'succeeded',
result: registryError,
}))
) {
return;
}
backgroundTaskRegistry.fail(
backgroundUserId,
backgroundConversationId,
task.id,
registryError,
{ harvestStarted: harvestEnabled },
);
await persistSettledBackgroundResult({
output: errorOutput,
status: 'error',
});
await wakeDetachedActor();
return;
}
/** Hold any artifact (images, files, UI resources,
* citations) on the task instead of routing it through
* this dispatch turn's callback: a slow background call
* resolves after the turn finalized, when its
* artifactPromises are already awaited and the stream is
* closed, so that push would be silently dropped. The poll
* turn delivers it live in `check_background_task`. */
if (
!(await persistDetachedTerminal({
status: 'succeeded',
result: content,
}))
) {
return;
}
if (result.artifact != null && !harvestEnabled && completionAdmission != null) {
/** Eligibility is decided from the actual result, not the
* tool's declared response format. A content-only result
* from a content-and-artifact tool can wake normally; an
* actual artifact still needs the live poll callback. */
try {
const retired = await completionAdmission.retire(
'background tool artifact requires live polling',
);
if (!retired) {
logger.warn(
`[background] Could not retire artifact wakeup for task ${task.id}.`,
);
}
} catch (retireError) {
logger.warn(
`[background] Failed to retire artifact wakeup for task ${task.id}:`,
retireError,
);
} finally {
/** Never publish an eligibility marker for an artifact
* the continuation cannot reconstruct. An ambiguous
* retire receipt therefore fails closed to polling; any
* surviving delivery expires with the producer lease. */
completionPreregistered = false;
backgroundTaskRegistry.markCompletionPersistenceFailed(
backgroundUserId,
backgroundConversationId,
task.id,
);
}
}
const storedContent = backgroundTaskRegistry.complete(
backgroundUserId,
backgroundConversationId,
task.id,
{ content, artifact: result.artifact, harvestStarted: harvestEnabled },
);
await persistSettledBackgroundResult({
/** Use the registry's canonical bounded serialization so
* structured content cannot leave the durable card on its
* synthetic running handle. */
output: storedContent,
artifact: result.artifact,
status: 'completed',
});
await wakeDetachedActor();
} catch (toolError) {
const policyError =
toolError instanceof ContentFilterError
? modelBoundContentFilterErrorMessage(toolError.body)
: null;
const { message, logContext } = getSafeToolError(
toolError,
toolValidationFeedback(
toolError,
tc.name,
tool.schema,
normalizedArgs,
backgroundControlEnabled,
),
);
/** Tools report an abort in their own words; a shutdown interrupt
* tells the agent why it happened and that it may retry. */
const errorOutput =
backgroundAbortSource === 'shutdown'
? BACKGROUND_TASK_SHUTDOWN_MESSAGE
: (policyError ?? message);
const filteredError =
policyError == null
? filteredToolOutputResult(tc, backgroundReq, {
errorMessage: errorOutput,
upstreamBody:
toolError instanceof WorkspaceToolHttpError
? toolError.upstreamBody
: undefined,
})
: null;
const neutralizedError = filteredError?.errorMessage ?? errorOutput;
if (policyError == null && filteredError == null) {
logger.debug('[background] Tool failed', {
...logContext,
toolName: tc.name,
toolCallId: tc.id,
backgroundTaskId: task.id,
});
}
const deliveredError = toBackgroundToolFailure(tc.name, neutralizedError);
const registryError = isCodeCall ? deliveredError : neutralizedError;
/** Only an owner-authorized request is cancellation evidence.
* Providers and timeout controllers also use AbortError, so
* classifying by error shape would turn failures into a false
* claim that the owner cancelled the task. */
const detachedTerminalStatus =
backgroundAbortSource === 'manual' ? 'cancelled' : 'failed';
if (
!(await persistDetachedTerminal({
status: detachedTerminalStatus,
error: registryError,
}))
) {
return;
}
const settleOptions = { harvestStarted: harvestEnabled };
if (detachedTerminalStatus === 'cancelled') {
backgroundTaskRegistry.cancel(
backgroundUserId,
backgroundConversationId,
task.id,
registryError,
settleOptions,
);
} else {
backgroundTaskRegistry.fail(
backgroundUserId,
backgroundConversationId,
task.id,
registryError,
/** Failed code tasks join the heal path too: without this,
* a full-row save reverting the error patch would leave
* the dispatch card on the handle JSON forever. */
settleOptions,
);
}
await persistSettledBackgroundResult({
output: deliveredError,
status: detachedTerminalStatus === 'cancelled' ? 'cancelled' : 'error',
});
await wakeDetachedActor();
} finally {
if (producerRetirementTimeout != null) {
clearTimeout(producerRetirementTimeout);
}
await stopProducerHeartbeat();
}
})();
void settlement.then(
() => {
if (completionAdmission == null || !completionPreregistered) {
resolveDurableReceipt();
}
},
() => undefined,
);
backgroundTaskRegistry.trackShutdown(task, {
settled: durableReceiptSettled,
interrupt: (reason) => {
if (backgroundAbortSource != null || backgroundAbortController.signal.aborted) {
return;
}
backgroundAbortSource = 'shutdown';
backgroundAbortController.abort(new DOMException(reason, 'AbortError'));
},
flush: async (reason) => {
await stopProducerHeartbeat();
if (durableReceiptWrite != null) {
await durableReceiptWrite;
} else if (settledReceipt != null) {
await writeDurableReceipt({ ...settledReceipt, settledAt: new Date() });
} else {
forcedShutdownResult = true;
const failure = toBackgroundToolFailure(tc.name, reason);
backgroundTaskRegistry.fail(
backgroundUserId,
backgroundConversationId,
task.id,
isCodeCall ? failure : reason,
{ harvestStarted: harvestEnabled },
);
try {
await persistDetachedTerminal({ status: 'failed', error: failure });
} catch (detachedError) {
logger.warn(
`[background] Failed to settle detached action for interrupted task ${task.id}:`,
detachedError,
);
}
if (completionAdmission?.persistResult != null) {
await writeDurableReceipt({
status: 'error',
output: failure,
settledAt: new Date(),
});
} else if (completionAdmission != null) {
await persistSettledBackgroundResult(
{ status: 'error', output: failure },
true,
);
}
}
if (durableResultConfirmed || completionAdmission == null) {
return;
}
if (settledReceipt != null && !forcedShutdownResult) {
await settlement;
if (durableResultConfirmed) {
return;
}
}
if (completionPreregistered) {
throw new Error(`Background task ${task.id} has no durable shutdown result`);
}
},
});
if (
detachedReservation?.status === 'reserved' &&
eventActorDetachedAction != null &&
!(await eventActorDetachedAction.markRunning({
taskId: detachedReservation.taskId,
idempotencyKey: detachedReservation.idempotencyKey,
}))
) {
throw new Error('Detached Event Actor launch acknowledgement is stale');
}
}
return {
toolCallId: tc.id,
status: 'success' as const,
content: buildBackgroundHandleContent(task, {
completionWakeup: completionPreregistered,
liveArtifactPollRequired,
}),
};
};
const batchReq = mergedConfigurable?.req as ServerRequest | undefined;
const batchCodeApiRateLimitBudget = createCodeApiRateLimitBudget(
batchReq?.config?.endpoints?.agents?.codeApiMaxRetryWaitMs,
);
const results: ToolExecuteResult[] = await Promise.all(
toolCalls.map(async (tc: ToolCallRequest) => {
const preloadedNameBlock = preloadedNameBlocks.get(tc);
if (preloadedNameBlock != null) {
return reportResult(preloadedNameBlock);
}
/** Tool names are user/model-submitted content too. Check them
* before lookup so an unknown blocked name cannot reach logs
* or error history. Arguments are inspected after the tool
* schema normalizes them below. */
const filteredName = filteredToolArgumentsResult(
tc,
mergedConfigurable?.req as ServerRequest | undefined,
undefined,
);
if (filteredName != null) {
return reportResult(filteredName);
}
if (backgroundControlEnabled && tc.name === CHECK_BACKGROUND_TASK_NAME) {
const req = mergedConfigurable?.req as ServerRequest | undefined;
const filteredArguments = filteredToolArgumentsResult(tc, req, tc.args);
if (filteredArguments != null) {
return reportResult(filteredArguments);
}
if (runSignal?.reason instanceof SteerToolInterrupt) {
return reportResult(interruptedToolResult(tc.id));
}
onResultAdmissionStart?.(tc.id);
const pollContent = await runCheckBackgroundTask({
userId: backgroundUserId,
conversationId: backgroundConversationId,
args: tc.args,
toolCallId: tc.id,
agentId,
runId: `${backgroundRunId ?? ''}:${tc.turn ?? ''}`,
generationId: backgroundRunId,
subagentTasks,
claimBackgroundToolResult: backgroundToolCompletion?.claim,
recoverDeadBackgroundToolClaim: backgroundToolCompletion?.recoverDeadClaim,
pendingCompletions: backgroundToolCompletion?.pending,
ordinaryToolCancellation,
});
const taskSnapshot = getBackgroundTaskSnapshot({
userId: backgroundUserId,
conversationId: backgroundConversationId,
args: tc.args,
});
/** Read harvest delivery before filtering and reuse that
* snapshot below. If attachments land afterward, this poll
* cannot emit them; the next poll reads and inspects them. */
const delivery = getBackgroundCodeDelivery({
userId: backgroundUserId,
conversationId: backgroundConversationId,
args: tc.args,
});
const filteredPollOutput = filteredToolOutputResult(tc, req, {
content: pollContent,
task:
taskSnapshot == null
? undefined
: {
result: taskSnapshot.result,
error: taskSnapshot.error,
artifact: taskSnapshot.artifact,
attachments: taskSnapshot.attachments,
},
delivery,
});
if (filteredPollOutput != null) {
return reportResult(filteredPollOutput);
}
/** Deliver a completed task's artifact through THIS live poll
* turn (once): the tool's own turn finalized before the
* artifact resolved, so this is where it can be surfaced.
* Code tasks are claimed even without a `toolEndCallback` —
* their files were already persisted at completion, and the
* claimed artifact still has to ride this result so the SDK
* folds the exec session into the run's shared code session. */
let codeSessionArtifact: unknown;
const pending = claimBackgroundArtifact({
userId: backgroundUserId,
conversationId: backgroundConversationId,
args: tc.args,
shouldClaim: (pendingTask) =>
toolEndCallback != null ||
isCodeSessionAwareToolCall(pendingTask.toolName, mergedConfigurable),
});
if (pending) {
const isCodeTask = isCodeSessionAwareToolCall(
pending.toolName,
mergedConfigurable,
);
if (isCodeTask) {
codeSessionArtifact = pending.artifact;
}
/** Harvested code tasks never route through the poll turn's
* callback — their files were already persisted with the
* ORIGINAL tool-call identity by the completion harvest. */
if (toolEndCallback && !(isCodeTask && pending.harvestStarted === true)) {
try {
onResultAdmissionStart?.(tc.id);
await toolEndCallback(
{
input: tc.args,
backgroundDelivery: true,
output: {
name: pending.toolName,
tool_call_id: tc.id,
content: pending.content,
artifact: pending.artifact,
},
},
{
...(metadata ?? {}),
executingAgentId: agentId,
stepId: tc.stepId,
} as ToolEndCallbackMetadata,
);
} catch (callbackError) {
if (isContentFilterError(callbackError)) {
backgroundTaskRegistry.blockArtifact(
backgroundUserId,
backgroundConversationId,
pending.taskId,
callbackError instanceof ContentFilterError
? modelBoundContentFilterErrorMessage(callbackError.body)
: callbackError.body.message,
);
logger.warn(
`[background] Artifact delivery for task ${pending.taskId} was blocked by content policy.`,
);
return reportResult({
toolCallId: tc.id,
status: 'success' as const,
content: await runCheckBackgroundTask({
userId: backgroundUserId,
conversationId: backgroundConversationId,
args: tc.args,
}),
});
}
/** Only synchronous callback throws land here (e.g. a
* malformed artifact shape); the callback's downstream
* persistence is fire-and-forget, so a storage failure
* is at-most-once — the same semantics as a foreground
* artifact. */
restoreBackgroundArtifact({
userId: backgroundUserId,
conversationId: backgroundConversationId,
taskId: pending.taskId,
artifact: pending.artifact,
});
logger.warn(
'[background] toolEndCallback error delivering artifact on poll:',
callbackError,
);
}
}
}
/** Harvest delivery is independent of the one-shot artifact
* claim so attachments that land AFTER an earlier poll still
* reach a later one. Re-emitting is idempotent (the client
* upserts by `file_id`) and the row patch re-application
* guards against a HITL-pause/resume full-row save having
* reverted the anchored result. */
if (
delivery &&
delivery.status !== 'running' &&
isCodeSessionAwareToolCall(delivery.toolName, mergedConfigurable)
) {
for (const attachment of delivery.attachments ?? []) {
try {
emitAttachment?.(attachment);
} catch (emitError) {
logger.warn(
'[background] Failed to emit harvested attachment on poll:',
emitError,
);
}
}
/** Live completion signal for the original card: stdout-only
* runs emit no file attachments, so a settled task also
* emits a synthetic status marker (upserted client-side by
* its stable id; filtered out of file rendering). */
if (emitAttachment && delivery.messageId) {
try {
emitAttachment({
type: BACKGROUND_STATUS_ATTACHMENT_TYPE,
/** Provider ids repeat across agents and turns; the
* host identity suffix keeps sibling markers from
* upserting over each other client-side. */
file_id: `bg-${delivery.toolCallId}${
delivery.agentId != null ? `-${delivery.agentId}` : ''
}${delivery.stepId != null ? `-${delivery.stepId}` : ''}`,
messageId: delivery.messageId,
conversationId: backgroundConversationId,
toolCallId: delivery.toolCallId,
agentId: delivery.agentId,
stepId: delivery.stepId,
status: delivery.status,
});
} catch (emitError) {
logger.warn(
'[background] Failed to emit background status marker on poll:',
emitError,
);
}
}
if (persistBackgroundCodeResult && delivery.messageId) {
/** Error/cancelled tasks carry their message in `error`, not
* `result`; abort-confirmed timeouts store it raw, so
* wrap here — `toBackgroundToolFailure` is a no-op for
* already-wrapped detached failures. */
const reapplyOutput =
delivery.status === 'error' || delivery.status === 'cancelled'
? toBackgroundToolFailure(
delivery.toolName,
delivery.error ?? delivery.result ?? 'Background task failed',
)
: delivery.result;
void persistBackgroundCodeResult({
toolName: delivery.toolName,
toolCallId: delivery.toolCallId,
stepId: delivery.stepId,
messageId: delivery.messageId,
conversationId: backgroundConversationId,
agentId: delivery.agentId,
output: reapplyOutput,
attachments: delivery.attachments,
...(delivery.backgroundTask == null
? {}
: { backgroundTask: delivery.backgroundTask }),
reapply: true,
}).catch((reapplyError) => {
logger.warn(
'[background] Failed to re-anchor harvested code result:',
reapplyError,
);
});
}
}
return reportResult({
toolCallId: tc.id,
status: 'success' as const,
content: pollContent,
...(codeSessionArtifact != null ? { artifact: codeSessionArtifact } : {}),
});
}
const usesCodeFiles =
isCodeFileToolName(tc.name) ||
isCodeSessionAwareToolCall(tc.name, mergedConfigurable);
if (runFileSharingActive && usesCodeFiles && isBackgroundRequested(tc.args)) {
return reportResult(
errorResult(tc, 'Shared-file code tools require foreground execution.'),
);
}
/* Before the background dispatch and before the sandbox
* authoring context is cloned below: both capture this call's
* code-session context, and a copy taken now would stay the
* pre-skill snapshot for the rest of the call's life. */
if (skillFilesHandoff != null && waitsForSkillFiles(tc)) {
await skillFilesHandoff.applyTo(tc);
if (runSignal?.aborted === true) {
/** The Stop landed while the skill upload held this call.
* Starting the tool now would send a request the turn has
* already abandoned. */
return reportResult(errorResult(tc, 'This operation was aborted'));
}
}
if (
scheduledMCPExecution?.enrolled !== true &&
backgroundToolSet.has(tc.name) &&
isBackgroundRequested(tc.args) &&
!toolRequiresEphemeralConnection(toolMap.get(tc.name)) &&
/** Code tools depend on the completion-time harvest to anchor
* results; hosts that don't wire the persister (OpenAI-compat
* and Responses controllers) downgrade code calls to
* foreground rather than losing generated files. */
!(
isCodeSessionAwareToolCall(tc.name, mergedConfigurable) &&
persistBackgroundCodeResult == null
)
) {
if (runSignal?.reason instanceof SteerToolInterrupt) {
return reportResult(interruptedToolResult(tc.id));
}
onResultAdmissionStart?.(tc.id);
return reportResult(await dispatchBackgroundToolCall(tc));
}
const execute = async (
sandboxContext?: SandboxSessionContext,
): Promise<ToolExecuteResult> => {
const isFileAuthoringCall = isHostFileAuthoringToolCall(
tc.name,
mergedConfigurable,
);
const isSandboxFileAuthoringCall =
isFileAuthoringCall &&
typeof (tc.args as { path?: unknown }).path === 'string' &&
!(tc.args as { path: string }).path.startsWith(SKILL_FILE_PREFIX);
if (runSignal?.reason instanceof SteerToolInterrupt) {
return interruptedToolResult(tc.id);
}
let sandboxReadSucceeded = false;
if (
tc.name === Constants.SKILL_TOOL ||
tc.name === Constants.READ_FILE ||
tc.name === SEARCH_WORKSPACE_TOOL_NAME ||
tc.name === LIST_WORKSPACE_FILES_TOOL_NAME ||
isFileAuthoringCall
) {
const req = mergedConfigurable?.req as ServerRequest | undefined;
const filtered = filteredToolArgumentsResult(tc, req, tc.args);
if (filtered != null) {
return filtered;
}
let handlerResult: ToolExecuteResult;
try {
if (tc.name === Constants.SKILL_TOOL) {
handlerResult = await handleSkillToolCall(
tc,
mergedConfigurable,
options,
agentId,
req,
runSignal,
batchCodeApiRateLimitBudget,
);
} else if (tc.name === Constants.READ_FILE) {
handlerResult = await handleReadFileCall(
tc,
mergedConfigurable,
options,
req,
() => {
sandboxReadSucceeded = true;
},
runSignal,
);
} else if (tc.name === SEARCH_WORKSPACE_TOOL_NAME) {
handlerResult = await handleWorkspaceSearchCall(
tc,
mergedConfigurable,
options,
req,
runSignal,
);
} else if (tc.name === LIST_WORKSPACE_FILES_TOOL_NAME) {
handlerResult = await handleWorkspaceListCall(
tc,
mergedConfigurable,
options,
req,
runSignal,
);
} else if (tc.name === CREATE_FILE_TOOL_NAME && isFileAuthoringCall) {
handlerResult = await handleCreateFileCall(
tc,
mergedConfigurable,
options,
req,
sourceConfigurable,
sandboxContext,
runSignal,
);
} else if (tc.name === EDIT_FILE_TOOL_NAME && isFileAuthoringCall) {
handlerResult = await handleEditFileCall(
tc,
mergedConfigurable,
options,
req,
sandboxContext,
runSignal,
);
} else {
handlerResult = errorResult(tc, `Tool ${tc.name} not found`);
}
} catch (toolError) {
if (toolError instanceof ContentFilterError) {
logger.error(`[ON_TOOL_EXECUTE] Tool ${tc.name} error`, {
name: toolError.name,
contentFiltered: true,
});
return errorResult(tc, modelBoundContentFilterErrorMessage(toolError.body));
}
const { message, logContext } = getSafeToolError(toolError);
const filteredError = filteredToolOutputResult(tc, req, {
errorMessage: message,
upstreamBody:
toolError instanceof WorkspaceToolHttpError
? toolError.upstreamBody
: undefined,
});
if (filteredError != null) {
logger.error(`[ON_TOOL_EXECUTE] Tool ${tc.name} error`, {
errorName: logContext.errorName,
contentFiltered: true,
});
return filteredError;
}
const context = {
...logContext,
toolName: tc.name,
toolCallId: tc.id,
toolCallArgsShape: getValueShape(tc.args),
};
if (runSignal?.aborted === true && isAbortError(toolError)) {
logger.debug(
`[ON_TOOL_EXECUTE] Tool ${tc.name} cancelled by run abort`,
context,
);
} else {
logger.error(`[ON_TOOL_EXECUTE] Tool ${tc.name} error`, context);
}
return {
toolCallId: tc.id,
status: 'error' as const,
content: '',
errorMessage: message,
};
}
if (runSignal?.reason instanceof SteerToolInterrupt) {
return interruptedToolResult(tc.id);
}
const filteredOutput = filteredToolOutputResult(tc, req, {
content: handlerResult.content,
artifact: handlerResult.artifact,
errorMessage: handlerResult.errorMessage,
});
if (filteredOutput != null) {
/** The side effect already happened; only the returned
* content is being withheld. Emit execution identity so
* an applied action is never reclassified as actionless
* and re-executed — the blocked output stays blank. */
if (toolEndCallback && handlerResult.errorMessage == null) {
try {
onResultAdmissionStart?.(tc.id);
await toolEndCallback(
{
input: tc.args,
outputFiltered: true,
output: { name: tc.name, tool_call_id: tc.id, content: '' },
},
{
...(metadata ?? {}),
executingAgentId: agentId,
} as ToolEndCallbackMetadata,
);
} catch (evidenceError) {
logger.warn(
`[ON_TOOL_EXECUTE] Filtered-output evidence delivery failed for ${tc.name}`,
evidenceError,
);
}
}
return filteredOutput;
}
if (toolEndCallback && handlerResult.artifact) {
try {
onResultAdmissionStart?.(tc.id);
await toolEndCallback(
{
input: tc.args,
output: {
name: tc.name,
tool_call_id: tc.id,
content: handlerResult.content,
artifact: handlerResult.artifact,
},
},
{
run_id: (metadata as Record<string, unknown>)?.run_id as
| string
| undefined,
thread_id: (metadata as Record<string, unknown>)?.thread_id as
| string
| undefined,
...metadata,
executingAgentId: agentId,
stepId: tc.stepId,
codeExecutionContext,
},
);
} catch (callbackError) {
if (callbackError instanceof ContentFilterError) {
logger.warn(
`[ON_TOOL_EXECUTE] Artifact delivery for tool ${tc.name} was blocked by content policy.`,
);
return errorResult(
tc,
modelBoundContentFilterErrorMessage(callbackError.body),
);
}
throw callbackError;
}
}
if (
isSandboxFileAuthoringCall &&
handlerResult.status === 'success' &&
sandboxContext
) {
mergeSandboxSessionArtifact(sandboxContext, handlerResult.artifact);
}
/* Sandbox-routed host file tools return before the
* generic invoke path's marker below, so refresh the warm
* window here. `sandboxReadSucceeded` is set only after an
* actual Code API read succeeds, so skill reads never mark
* the sandbox warm. */
if (
(isSandboxFileAuthoringCall || sandboxReadSucceeded) &&
handlerResult.status === 'success' &&
(runtimeSessionHint || sandboxConversationId)
) {
markCodeSandboxWarm();
}
return handlerResult;
}
const tool = toolMap.get(tc.name);
if (!tool) {
const missingToolResult: ToolExecuteResult = {
toolCallId: tc.id,
status: 'error' as const,
content: '',
errorMessage: `Tool ${tc.name} not found`,
};
const filteredMissingTool = filteredToolOutputResult(
tc,
mergedConfigurable?.req as ServerRequest | undefined,
{ errorMessage: missingToolResult.errorMessage },
);
if (filteredMissingTool != null) {
return filteredMissingTool;
}
logger.warn(
`[ON_TOOL_EXECUTE] Tool "${tc.name}" not found. Available: ${[...toolMap.keys()].map((k) => `"${k}"`).join(', ')}`,
);
return missingToolResult;
}
recordAttachedCommand(tc, tool);
let normalizedArgs: unknown = tc.args;
try {
const toolCallConfig = buildToolCallConfig(tc, mergedConfigurable);
if (
tc.name === Constants.BASH_PROGRAMMATIC_TOOL_CALLING ||
tc.name === Constants.PROGRAMMATIC_TOOL_CALLING
) {
const toolRegistry = mergedConfigurable?.toolRegistry as
| LCToolRegistry
| undefined;
const ptcToolMap = mergedConfigurable?.ptcToolMap as
| Map<string, StructuredToolInterface>
| undefined;
if (toolRegistry) {
const activeCodeExecutionToolNames = callerCapabilityProjection
? new Set(callerCapabilityProjection.codeExecutionToolNames)
: undefined;
const activeDirectOnlyToolNames = callerCapabilityProjection
? new Set(callerCapabilityProjection.directOnlyToolNames)
: undefined;
const fileAuthoringToolNames =
getFileAuthoringToolNames(mergedConfigurable) ?? new Set<string>();
const eligibleToolDefs: LCTool[] = [];
const disallowedToolDefs: LCTool[] = [];
for (const toolDef of toolRegistry.values()) {
const isInnerTool =
toolDef.name !== Constants.PROGRAMMATIC_TOOL_CALLING &&
toolDef.name !== Constants.BASH_PROGRAMMATIC_TOOL_CALLING &&
toolDef.name !== Constants.TOOL_SEARCH &&
toolDef.name !== CHECK_BACKGROUND_TASK_NAME &&
!fileAuthoringToolNames.has(toolDef.name);
if (!isInnerTool) {
continue;
}
const allowsCodeExecution = (
toolDef.allowed_callers ?? ['direct']
).includes('code_execution');
if (
allowsCodeExecution &&
(activeCodeExecutionToolNames == null ||
activeCodeExecutionToolNames.has(toolDef.name))
) {
eligibleToolDefs.push(toolDef);
} else if (
!allowsCodeExecution &&
(activeDirectOnlyToolNames == null ||
activeDirectOnlyToolNames.has(toolDef.name))
) {
disallowedToolDefs.push({
name: toolDef.name,
});
}
}
/* PTC-generated calls don't go through the host background
* interceptor, so strip the injected `run_in_background`
* param from target schemas (the registry entries were
* mutated to include it) — mirrors the self-spawn path.
* Intent LABELS are stripped for the same reason —
* host-injected AND SDK-native alike (marker-guarded):
* no card renders for an inner call, so the sandbox
* bridge must not advertise them. */
const toolDefs = stripIntentLabelsFromToolDefinitions(
stripBackgroundFromToolDefinitions(
eligibleToolDefs,
mergedConfigurable?.backgroundToolNames as string[] | undefined,
),
);
toolCallConfig.toolDefs = toolDefs;
toolCallConfig.disallowedToolDefs = disallowedToolDefs;
const eligibleNames = new Set(toolDefs.map((toolDef) => toolDef.name));
/* Instrument the ELIGIBLE map, never the raw one: the
* caller-capability restriction decides what the sandbox
* may reach, and tracing must not widen it. */
const eligiblePtcToolMap = new Map(
[...(ptcToolMap ?? toolMap)].filter(([name]) => eligibleNames.has(name)),
);
/* Inner calls produce no run step and no card of their
* own, so the only record of what the program did is
* this trace. `invoke` is the single seam every inner
* call passes through.
*
* They also never reach `filteredToolArgumentsResult` —
* the sandbox bridge invokes them directly — so when the
* deployment filters tool arguments for PII, the trace
* must not put their values on the wire. */
const ptcReq = mergedConfigurable?.req as ServerRequest | undefined;
const ptcArgumentPii = ptcReq?.config?.filters?.toolArguments?.pii;
toolCallConfig.toolMap = emitPtcProgress
? instrumentPtcToolMap({
toolMap: eligiblePtcToolMap,
toolCallId: tc.id,
runId: (metadata as Record<string, unknown>)?.run_id as
| string
| undefined,
includePreviews: !hasActivePiiFields(ptcArgumentPii, [
'name',
'arguments',
'output',
]),
traceExclusions: collectFilteredPtcToolNames(
eligiblePtcToolMap.keys(),
ptcReq,
),
emit: (event) => {
if (!(runSignal?.reason instanceof SteerToolInterrupt)) {
emitPtcProgress(event);
}
},
})
: eligiblePtcToolMap;
}
}
/** Strip the host-only `run_in_background` flag on foreground
* calls (the model may emit it as `false`, or imitate it from
* another agent's history on a tool this agent never opted
* in), so a strict MCP/action schema doesn't reject an
* undeclared argument. Only a tool whose own schema declares
* the parameter receives it. */
const foregroundArgs =
backgroundToolSet.has(tc.name) ||
(hasRunInBackgroundArg(tc.args) && !toolDeclaresRunInBackgroundParam(tool))
? stripRunInBackgroundArg(tc.args)
: tc.args;
normalizedArgs = normalizeToolInvokeArgs(
stripIntentForInvoke(foregroundArgs, tool),
tool,
);
const filtered = filteredToolArgumentsResult(
tc,
mergedConfigurable?.req as ServerRequest | undefined,
normalizedArgs,
);
if (filtered != null) {
return filtered;
}
const result = await tool.invoke(normalizedArgs, {
toolCall: toolCallConfig,
configurable: mergedConfigurable,
metadata: { ...metadata, executingAgentId: agentId },
/** The run's cancellation signal. Without it a foreground
* tool call keeps running after Stop: an MCP call never
* sends `notifications/cancelled`, and every other
* signal-aware tool keeps burning quota on a turn the
* user already abandoned. Detached background calls
* intentionally use their own controller instead. */
...(runSignal != null && { signal: runSignal }),
} as Record<string, unknown>);
if (runSignal?.reason instanceof SteerToolInterrupt) {
return interruptedToolResult(tc.id);
}
/* Only sandbox-bound calls carry a runtime session hint, so
* this refreshes the prewarm module's warm window without
* inspecting tool names. */
if (isCodeSessionAwareToolCall(tc.name, mergedConfigurable)) {
markCodeSandboxWarm();
}
// Code-execution tools emit per-call boilerplate
// ("Note: ..." paragraphs and `| <annotation>` per-file
// suffixes) that wastes tokens when re-injected into
// every subsequent model turn. Strip it here, *after*
// the tool resolved but *before* downstream consumers
// (model context, SSE forwarding, persistence) see it.
// Non-code-execution tools pass through unchanged.
const cleanedContent =
isCodeSessionAwareToolCall(tc.name, mergedConfigurable) &&
typeof result.content === 'string'
? cleanCodeToolOutput(result.content)
: result.content;
const filteredOutput = filteredToolOutputResult(
tc,
mergedConfigurable?.req as ServerRequest | undefined,
{
content: cleanedContent,
artifact: result.artifact,
},
);
if (filteredOutput != null) {
/** The side effect already happened; only the returned
* content is being withheld. Emit execution identity so
* an applied action is never reclassified as actionless
* and re-executed — the blocked output stays blank. */
if (toolEndCallback) {
try {
onResultAdmissionStart?.(tc.id);
await toolEndCallback(
{
input: tc.args,
outputFiltered: true,
output: { name: tc.name, tool_call_id: tc.id, content: '' },
},
{
...(metadata ?? {}),
executingAgentId: agentId,
} as ToolEndCallbackMetadata,
);
} catch (evidenceError) {
logger.warn(
`[ON_TOOL_EXECUTE] Filtered-output evidence delivery failed for ${tc.name}`,
evidenceError,
);
}
}
return filteredOutput;
}
if (toolEndCallback) {
onResultAdmissionStart?.(tc.id);
await toolEndCallback(
{
input: tc.args,
output: {
name: tc.name,
tool_call_id: tc.id,
content: cleanedContent,
artifact: result.artifact,
},
},
{
run_id: (metadata as Record<string, unknown>)?.run_id as
| string
| undefined,
thread_id: (metadata as Record<string, unknown>)?.thread_id as
| string
| undefined,
...metadata,
executingAgentId: agentId,
stepId: tc.stepId,
codeExecutionContext,
},
);
}
return {
toolCallId: tc.id,
content: cleanedContent,
artifact: result.artifact,
status: result.status === 'error' ? ('error' as const) : ('success' as const),
...(result.status === 'error' && {
errorMessage: getToolFailureFeedback(cleanedContent),
}),
};
} catch (toolError) {
if (toolError instanceof ContentFilterError) {
logger.error(`[ON_TOOL_EXECUTE] Tool ${tc.name} error`, {
name: toolError.name,
contentFiltered: true,
});
return errorResult(tc, modelBoundContentFilterErrorMessage(toolError.body));
}
const { message, logContext } = getSafeToolError(
toolError,
toolValidationFeedback(
toolError,
tc.name,
tool.schema,
normalizedArgs,
backgroundControlEnabled,
),
);
/** A user Stop rejects every in-flight call at once. That is
* the abort working, not a fault, so it is logged at debug.
* An aborted run says the turn is over, not that THIS
* rejection was the cancellation, so the error must look
* like one too; an unrelated failure racing the Stop stays
* at error level. Either way the level is all that changes
* — filtering and the result shape are identical. */
const logToolFailure = (context: Record<string, unknown>): void => {
if (runSignal?.aborted === true && isAbortError(toolError)) {
logger.debug(
`[ON_TOOL_EXECUTE] Tool ${tc.name} cancelled by run abort`,
context,
);
return;
}
logger.error(`[ON_TOOL_EXECUTE] Tool ${tc.name} error`, context);
};
const req = mergedConfigurable?.req as ServerRequest | undefined;
const filteredError = filteredToolOutputResult(tc, req, {
errorMessage: message,
upstreamBody:
toolError instanceof WorkspaceToolHttpError
? toolError.upstreamBody
: undefined,
});
if (filteredError != null) {
logToolFailure({
errorName: logContext.errorName,
contentFiltered: true,
});
return filteredError;
}
logToolFailure({
...logContext,
toolName: tc.name,
toolCallId: tc.id,
toolCallArgsShape: getValueShape(tc.args),
toolInputSchemaKind: getToolInputSchemaKind(tool),
});
return {
toolCallId: tc.id,
status: 'error' as const,
content: '',
errorMessage: message,
};
}
};
const executeWithFileScope = (sandboxContext?: SandboxSessionContext) =>
runFileSharingActive && usesCodeFiles && runFiles != null && agentId != null
? runFiles.withCodeExecution(
agentId,
executionContext,
runSignal ?? new AbortController().signal,
() => execute(sandboxContext),
)
: execute(sandboxContext);
const queueKey = getFileAuthoringQueueKey(tc, mergedConfigurable);
if (!queueKey) {
return reportResult(await executeWithFileScope());
}
let sandboxContext: SandboxSessionContext | undefined;
if (queueKey.startsWith('sandbox:')) {
sandboxContext =
sandboxAuthoringContexts.get(queueKey) ??
cloneSandboxSessionContext(sandboxSessionContext(tc));
sandboxAuthoringContexts.set(queueKey, sandboxContext);
}
const previous = authoringQueues.get(queueKey) ?? Promise.resolve();
const resultPromise = previous.then(
() => executeWithFileScope(sandboxContext),
() => executeWithFileScope(sandboxContext),
);
authoringQueues.set(
queueKey,
resultPromise.then(
() => undefined,
() => undefined,
),
);
return reportResult(await resultPromise);
}),
);
resolve(results);
} catch (error) {
logger.error('[ON_TOOL_EXECUTE] Fatal error:', error);
reject(error as Error);
}
});
} catch (outerError) {
logger.error('[ON_TOOL_EXECUTE] Unexpected error:', outerError);
reject(outerError as Error);
}
},
};
authoredSkills.bind(handler);
return handler;
}