⚗️ refactor: Separate Content, Tool, and Agent Types From the Assistants Module (#15910)
Some checks are pending
Backend Unit Tests / Build packages (push) Waiting to run
Backend Unit Tests / Codegraph select (push) Waiting to run
Backend Unit Tests / TypeScript type checks (push) Blocked by required conditions
Backend Unit Tests / Circular dependency checks (push) Waiting to run
Backend Unit Tests / Tests: api (shard 1/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 2/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: api (shard 3/3) (push) Blocked by required conditions
Backend Unit Tests / Tests: data-provider (push) Blocked by required conditions
Backend Unit Tests / Tests: data-schemas (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 1/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 2/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 3/4) (push) Blocked by required conditions
Backend Unit Tests / Tests: @librechat/api (shard 4/4) (push) Blocked by required conditions
Codegraph E2E Votes / vote (full suite) (push) Waiting to run
Docker Dev Branch Images Build / publish (push) Waiting to run
Frontend Unit Tests / Client build recovery regression (push) Waiting to run
Frontend Unit Tests / Codegraph select (push) Waiting to run
Frontend Unit Tests / Build packages (push) Waiting to run
Frontend Unit Tests / TypeScript type checks (client) (push) Blocked by required conditions
Frontend Unit Tests / Tests: @librechat/client (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 1/2) (push) Blocked by required conditions
Frontend Unit Tests / Tests: Ubuntu (shard 2/2) (push) Blocked by required conditions
Frontend Unit Tests / Vite build verification (push) Blocked by required conditions
Docker Dev Images Build / publish (push) Waiting to run
Sync Helm Chart Tags / Ignore non-main push (push) Waiting to run
Sync Helm Chart Tags / Sync chart tags (push) Waiting to run

types/assistants.ts held ~60 exports of which only ~11 were Assistants
API types. The rest were core message-content types and the Agent entity
types, so schemas.ts and agents.ts both imported foundational types from
a file named after the Assistants API.

Split into types/tools.ts (tool primitives, action naming) and
types/content.ts (message content parts, annotations, tool calls), moved
the Agent entity types into the existing types/agents.ts, and left a slim
Assistants-only types/assistants.ts.

No behavior change: every symbol keeps its public export from the package
barrel, so no consumer outside data-provider changes.

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-09-15 14:15:24 -04:00 • committed by GitHub
parent c80f5a7090
commit 385c6f8a1a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 839 additions and 834 deletions

View file

@ -12,7 +12,7 @@ import {
import { specialVariables } from '../src/config';
import { EModelEndpoint, Providers } from '../src/schemas';
import { ContentTypes } from '../src/types/runs';
import type { TMessageContentParts } from '../src/types/assistants';
import type { TMessageContentParts } from '../src/types/content';
import type { TUser, TConversation } from '../src/types';
// Mock dayjs module with consistent date/time values regardless of environment

View file

@ -2,7 +2,7 @@ import {
STATEFUL_CODE_ENVIRONMENTS,
resolveStatefulCodeEnvironment,
resolveAllowedStatefulCodeEnvironments,
} from '../src/types/assistants';
} from '../src/types/agents';
describe('stateful code environment policy', () => {
it('allows every environment when deployment configuration is omitted', () => {

View file

@ -5,9 +5,9 @@ import crypto from 'crypto';
import { load } from 'js-yaml';
import type { OpenAPIV3 } from 'openapi-types';
import type { ActionMetadata, ActionMetadataRuntime } from './types/agents';
import type { FunctionTool, Schema, Reference } from './types/assistants';
import type { FunctionTool, Schema, Reference } from './types/tools';
import { AuthTypeEnum, AuthorizationTypeEnum } from './types/agents';
import { Tools } from './types/assistants';
import { Tools } from './types/tools';
export type ParametersSchema = {
type: string;

View file

@ -1,4 +1,4 @@
import type { AgentToolOptions } from './types/assistants';
import type { AgentToolOptions } from './types/tools';
import { normalizeActionToolName, removeCodeExecutionCaller } from './agentToolOptions';
describe('normalizeActionToolName', () => {

View file

@ -4,7 +4,7 @@ import {
isActionTool,
type AgentToolOptions,
type AllowedCaller,
} from './types/assistants';
} from './types/tools';
const actionDomainSeparatorRegex = new RegExp(actionDomainSeparator, 'g');

View file

@ -31,8 +31,8 @@ import { CODE_ENVIRONMENT_DECISION_VERSION, CODE_ENVIRONMENT_MOVE_VERSION } from
import { ComponentTypes, SettingTypes, OptionTypes } from './generate';
import { STATEFUL_CODE_ENVIRONMENTS } from './stateful-code';
import { specsConfigSchema, TSpecsConfig } from './models';
import { isActionTool } from './types/assistants';
import { fileConfigSchema } from './file-config';
import { isActionTool } from './types/tools';
import { apiBaseUrl } from './api-endpoints';
import { FileSources } from './types/files';
import { MCPServersSchema } from './mcp';

View file

@ -8,6 +8,7 @@ import type {
} from './types/traces';
import type { TInsightsAccessResponse, TInsightsParams, TInsightsResponse } from './types/insights';
import type { TFileConfig } from './file-config';
import type * as tl from './types/tools';
import type * as t from './types';
import * as permissions from './accessPermissions';
import * as endpoints from './api-endpoints';
@ -667,11 +668,11 @@ export const deleteAction = async ({
* Agents
*/
export const createAgent = ({ ...data }: a.AgentCreateParams): Promise<a.Agent> => {
export const createAgent = ({ ...data }: ag.AgentCreateParams): Promise<ag.Agent> => {
return request.post(endpoints.agents({}), data);
};
export const getAgentById = ({ agent_id }: { agent_id: string }): Promise<a.Agent> => {
export const getAgentById = ({ agent_id }: { agent_id: string }): Promise<ag.Agent> => {
return request.get(
endpoints.agents({
path: agent_id,
@ -679,7 +680,7 @@ export const getAgentById = ({ agent_id }: { agent_id: string }): Promise<a.Agen
);
};
export const getExpandedAgentById = ({ agent_id }: { agent_id: string }): Promise<a.Agent> => {
export const getExpandedAgentById = ({ agent_id }: { agent_id: string }): Promise<ag.Agent> => {
return request.get(
endpoints.agents({
path: `${agent_id}/expanded`,
@ -687,7 +688,7 @@ export const getExpandedAgentById = ({ agent_id }: { agent_id: string }): Promis
);
};
export const getAgentVersions = ({ agent_id }: { agent_id: string }): Promise<a.Agent[]> => {
export const getAgentVersions = ({ agent_id }: { agent_id: string }): Promise<ag.Agent[]> => {
return request.get(
endpoints.agents({
path: `${agent_id}/versions`,
@ -700,8 +701,8 @@ export const updateAgent = ({
data,
}: {
agent_id: string;
data: a.AgentUpdateParams;
}): Promise<a.Agent> => {
data: ag.AgentUpdateParams;
}): Promise<ag.Agent> => {
return request.patch(
endpoints.agents({
path: agent_id,
@ -712,7 +713,7 @@ export const updateAgent = ({
export const duplicateAgent = ({
agent_id,
}: m.DuplicateAgentBody): Promise<{ agent: a.Agent; actions: ag.Action[] }> => {
}: m.DuplicateAgentBody): Promise<{ agent: ag.Agent; actions: ag.Action[] }> => {
return request.post(
endpoints.agents({
path: `${agent_id}/duplicate`,
@ -728,7 +729,7 @@ export const deleteAgent = ({ agent_id }: m.DeleteAgentBody): Promise<void> => {
);
};
export const listAgents = (params: a.AgentListParams): Promise<a.AgentListResponse> => {
export const listAgents = (params: ag.AgentListParams): Promise<ag.AgentListResponse> => {
return request.get(
endpoints.agents({
options: params,
@ -742,7 +743,7 @@ export const revertAgentVersion = ({
}: {
agent_id: string;
version_index: number;
}): Promise<a.Agent> => request.post(endpoints.revertAgentVersion(agent_id), { version_index });
}): Promise<ag.Agent> => request.post(endpoints.revertAgentVersion(agent_id), { version_index });
/* Marketplace */
@ -763,7 +764,7 @@ export const getMarketplaceAgents = (params: {
limit?: number;
cursor?: string;
promoted?: 0 | 1;
}): Promise<a.AgentListResponse> => {
}): Promise<ag.AgentListResponse> => {
return request.get(
endpoints.agents({
// path: 'marketplace',
@ -877,7 +878,7 @@ export const uploadAssistantAvatar = (data: m.AssistantAvatarVariables): Promise
);
};
export const uploadAgentAvatar = (data: m.AgentAvatarVariables): Promise<a.Agent> => {
export const uploadAgentAvatar = (data: m.AgentAvatarVariables): Promise<ag.Agent> => {
return request.postMultiPart(
`${endpoints.images()}/agents/${data.agent_id}/avatar`,
data.formData,
@ -926,7 +927,7 @@ export const deleteFiles = async (payload: {
files: f.BatchFile[];
agent_id?: string;
assistant_id?: string;
tool_resource?: a.EToolResources;
tool_resource?: tl.EToolResources;
}): Promise<f.DeleteFilesResponse> =>
request.deleteWithOptions(endpoints.files(), {
data: payload,

View file

@ -29,6 +29,8 @@ export * from './roles';
export * from './types';
export * from './types/agents';
export * from './types/assistants';
export * from './types/content';
export * from './types/tools';
export * from './types/files';
export * from './types/mcpServers';
export * from './types/mutations';

View file

@ -1,4 +1,4 @@
import type { SummaryContentPart } from './types/assistants';
import type { SummaryContentPart } from './types/content';
import type { ParentMessage } from './messages';
import type { TFile } from './types/files';
import type { TMessage } from './types';

View file

@ -1,4 +1,4 @@
import type { TMessageContentParts } from './types/assistants';
import type { TMessageContentParts } from './types/content';
import type { TFile } from './types/files';
import type { TMessage } from './types';
import { ContentTypes } from './types/runs';

View file

@ -1,5 +1,5 @@
import { z } from 'zod';
import type { AgentSubagentsConfig } from './types/assistants';
import type { AgentSubagentsConfig } from './types/agents';
import type { TModelSpecPreset } from './schemas';
import {
EModelEndpoint,

View file

@ -2,7 +2,7 @@ import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc.js';
import timezonePlugin from 'dayjs/plugin/timezone.js';
import type { ZodIssue } from 'zod';
import type * as a from './types/assistants';
import type * as a from './types/content';
import type * as s from './schemas';
import type * as t from './types';
import {

View file

@ -15,8 +15,8 @@ import {
isMediaSupportedProvider,
isDocumentSupportedProvider,
} from './schemas';
import { EToolResources } from './types/assistants';
import { normalizeEndpointName } from './utils';
import { EToolResources } from './types/tools';
/**
* The native provider a custom endpoint declares, when it declares one. A custom endpoint

View file

@ -1,12 +1,14 @@
import { z } from 'zod';
import type { TMessageContentParts, AgentSubagentGraph, FunctionTool } from './types/assistants';
import type { TMessageContentParts } from './types/content';
import type { AgentSubagentGraph } from './types/agents';
import type { SearchResultData } from './types/web';
import type { FunctionTool } from './types/tools';
import type { TFile } from './types/files';
import { CODE_ENVIRONMENT_MODES, CODE_WORKSPACE_ID_PATTERN } from './code/workspace';
import { userSubmittedMessageFieldPathSchema } from './filters';
import { TFeedback, feedbackSchema } from './feedback';
import { CODE_APPROVAL_MODES } from './code/approval';
import { Tools } from './types/assistants';
import { Tools } from './types/tools';
export const isUUID = z.string().uuid();

View file

@ -21,13 +21,15 @@ import type {
CodeEnvironmentUserSettings,
TAgentsEndpoint,
} from './config';
import type { Agent, EToolResources, StatefulCodeEnvironment } from './types/assistants';
import type { StatefulCodeEnvironment } from './stateful-code';
import type { CodeApprovalMode } from './code/approval';
import type { EToolResources } from './types/tools';
import type { RefillIntervalUnit } from './balance';
import type { SettingDefinition } from './generate';
import type { TMinimalFeedback } from './feedback';
import type { ContentTypes } from './types/runs';
import type { ProviderId } from './providers';
import type { Agent } from './types/agents';
export * from './schemas';
export * from './types/subagents';

View file

@ -1,8 +1,20 @@
/* eslint-disable @typescript-eslint/no-namespace */
import { z } from 'zod';
import type { TAttachment, TPlugin, AgentProvider, MemoryScope, SkillsScope } from 'src/schemas';
import type { TTokenUsageEvent, TContextUsageEvent, TPendingSteer } from './runs';
import type { TAttachment, TPlugin } from 'src/schemas';
import type { SummaryContentPart } from './assistants';
import type { FunctionTool, ToolResources, AgentToolOptions } from './tools';
import type { StatefulCodeEnvironment } from '../stateful-code';
import type { SummaryContentPart } from './content';
import type { TFile } from './files';
import { StepTypes, ContentTypes, ToolCallTypes } from './runs';
import { ArtifactModes } from 'src/artifacts';
import { EToolResources } from './tools';
export {
STATEFUL_CODE_ENVIRONMENTS,
resolveStatefulCodeEnvironment,
resolveAllowedStatefulCodeEnvironments,
} from '../stateful-code';
export type { StatefulCodeEnvironment } from '../stateful-code';
export namespace Agents {
export type MessageType = 'human' | 'ai' | 'generic' | 'system' | 'function' | 'tool' | 'remove';
@ -835,3 +847,306 @@ export type GraphEdge = {
*/
promptKey?: string;
};
/* Agent types */
export type AgentAvatar = {
filepath: string;
source: string;
};
export type AgentParameterValue = number | string | null;
export type AgentModelParameters = {
model?: string;
temperature: AgentParameterValue;
maxContextTokens: AgentParameterValue;
max_context_tokens: AgentParameterValue;
max_output_tokens: AgentParameterValue;
top_p: AgentParameterValue;
frequency_penalty: AgentParameterValue;
presence_penalty: AgentParameterValue;
useResponsesApi?: boolean;
};
export interface AgentBaseResource {
/**
* A list of file IDs made available to the tool.
*/
file_ids?: Array<string>;
/**
* A list of files already fetched.
*/
files?: Array<TFile>;
}
export interface AgentToolResources {
[EToolResources.image_edit]?: AgentBaseResource;
[EToolResources.execute_code]?: ExecuteCodeResource;
[EToolResources.file_search]?: AgentFileResource;
[EToolResources.context]?: AgentBaseResource;
/** @deprecated Use context instead */
[EToolResources.ocr]?: AgentBaseResource;
}
/**
* A resource for the execute_code tool.
* Contains file IDs made available to the tool (max 20 files) and already fetched files.
*/
export type ExecuteCodeResource = AgentBaseResource;
export interface AgentFileResource extends AgentBaseResource {
/**
* The ID of the vector store attached to this agent. There
* can be a maximum of 1 vector store attached to the agent.
*/
vector_store_ids?: Array<string>;
}
export type SupportContact = {
name?: string;
email?: string;
};
export type AgentOwnerContact = {
name?: string;
};
/**
* Configuration for spawning subagents (isolated-context child agents) from an agent.
* When `enabled` is true, the agent gets a subagent-spawn tool that can delegate work
* to itself, listed single-agent targets, and/or explicit saved-agent teams.
*/
export type AgentSubagentGraphEdge = Omit<
GraphEdge,
'edgeType' | 'condition' | 'prompt' | 'promptKey'
> & {
edgeType: 'direct';
condition?: never;
prompt?: string;
promptKey?: never;
};
/** A bounded saved-agent team that can be spawned as one isolated child graph. */
export type AgentSubagentGraph = {
/** Stable spawn-tool enum value for the team. */
type: string;
name: string;
description: string;
/** Member IDs. In create/update payloads, an empty ID refers to the current agent. */
agent_ids: string[];
edges: AgentSubagentGraphEdge[];
/** Entry member ID. In create/update payloads, an empty ID refers to the current agent. */
entry_agent_id: string;
/** Result member ID. In create/update payloads, an empty ID refers to the current agent. */
result_agent_id: string;
};
export type AgentSubagentsConfig = {
enabled?: boolean;
/** When true (default), the agent may spawn itself in an isolated context. */
allowSelf?: boolean;
/** Share current-turn files with authorized descendants. Off unless explicitly enabled. */
shareFiles?: boolean;
/** Specific agents that may be spawned as subagents. */
agent_ids?: string[];
/** Explicit saved-agent teams that may be spawned as bounded child graphs. */
graphs?: AgentSubagentGraph[];
};
export type AgentGitIdentity = {
/** Commit author and committer display name. */
name: string;
/** Commit author and committer email address. */
email: string;
};
export const agentGitIdentitySchema: z.ZodType<AgentGitIdentity | undefined> = z
.object({
name: z
.string()
.trim()
.min(1)
.max(128)
.refine((value) => !/[\0\r\n]/.test(value)),
email: z
.string()
.trim()
.email()
.max(254)
.refine((value) => !/[\0\r\n]/.test(value)),
})
.optional();
export type Agent = {
_id?: string;
id: string;
name: string | null;
author?: string | null;
/** The original custom endpoint name, lowercased */
endpoint?: string | null;
authorName?: string | null;
description: string | null;
created_at: number;
avatar: AgentAvatar | null;
instructions?: string | null;
additional_instructions?: string | null;
tools?: string[];
tool_kwargs?: Record<string, unknown>;
metadata?: Record<string, unknown>;
provider: AgentProvider;
model: string | null;
model_parameters: AgentModelParameters;
conversation_starters?: string[];
tool_resources?: AgentToolResources;
/** @deprecated Use edges instead */
agent_ids?: string[];
edges?: GraphEdge[];
end_after_tools?: boolean;
hide_sequential_outputs?: boolean;
/** Per-agent opt-in for stateful code sessions (requires the app-level capability). */
stateful_code_sessions?: boolean;
/** Stateful workspace sharing scope. Defaults to one workspace per user. */
stateful_code_environment?: StatefulCodeEnvironment;
/** Operator-configured managed or attached stateful execution environment. */
code_environment_id?: string | null;
/** Default attached workspace for new chats; empty means no agent default. */
code_workspace_id?: string;
/** Non-secret Git authorship injected into this agent's sandboxed commands. */
git_identity?: AgentGitIdentity | null;
artifacts?: ArtifactModes;
recursion_limit?: number;
isPublic?: boolean;
/**
* Whether the requesting user holds EDIT on this agent, so a single VIEW-scoped fetch can
* serve consumers that only need the editable subset instead of issuing a second full
* paginated walk under an EDIT-scoped cache key.
*
* Set by the list endpoint only; single-agent responses omit it. Treat absence as unknown
* and fail open (`isEditable !== false`), never as `false`, since a client on an older
* server would otherwise see an empty list rather than too many rows.
*
* Reflects the caller's ACL grant. The `MANAGE_AGENTS` capability bypasses ACL on write,
* so a capability holder can edit agents this flag reports as not editable.
*/
isEditable?: boolean;
version?: number;
category?: string;
support_contact?: SupportContact;
owner_contact?: AgentOwnerContact;
/** Per-tool configuration options (deferred loading, allowed callers, etc.) */
tool_options?: AgentToolOptions;
/** Attached action registrations, each `${encodedDomain}${actionDelimiter}${action_id}` */
actions?: string[];
/** Optional allowlist of skill ObjectIds. Only applies when `skills_enabled`. */
skills?: string[];
/** Master toggle for skill use on this agent. `true` = active (full catalog unless
* `skills` narrows it). `false`/undefined = inactive (no skills available). */
skills_enabled?: boolean;
/** Enables runtime skill creation without exposing an existing skill catalog. */
skill_authoring_enabled?: boolean;
/** Explicit catalog exposure while skills are enabled. Missing preserves legacy semantics. */
skills_scope?: SkillsScope;
/** Subagent spawning configuration — isolated-context child agents. */
subagents?: AgentSubagentsConfig;
/** Memory partition: `agent` isolates memories per (user, agent); default shared pool */
memory_scope?: MemoryScope;
};
export type TAgentsMap = Record<string, Agent | undefined>;
export type AgentCreateParams = {
git_identity?: AgentGitIdentity;
name?: string | null;
description?: string | null;
avatar?: AgentAvatar | null;
file_ids?: string[];
instructions?: string | null;
tools?: Array<FunctionTool | string>;
provider: AgentProvider;
model: string | null;
model_parameters: AgentModelParameters;
} & Pick<
Agent,
| 'agent_ids'
| 'edges'
| 'end_after_tools'
| 'hide_sequential_outputs'
| 'stateful_code_sessions'
| 'stateful_code_environment'
| 'code_environment_id'
| 'code_workspace_id'
| 'artifacts'
| 'recursion_limit'
| 'category'
| 'support_contact'
| 'tool_options'
| 'skills'
| 'skills_enabled'
| 'skill_authoring_enabled'
| 'skills_scope'
| 'subagents'
| 'memory_scope'
>;
export type AgentUpdateParams = {
name?: string | null;
description?: string | null;
avatar?: AgentAvatar | null;
file_ids?: string[];
instructions?: string | null;
tools?: Array<FunctionTool | string>;
tool_resources?: ToolResources;
provider?: AgentProvider;
model?: string | null;
model_parameters?: AgentModelParameters;
} & Pick<
Agent,
| 'agent_ids'
| 'edges'
| 'end_after_tools'
| 'hide_sequential_outputs'
| 'stateful_code_sessions'
| 'stateful_code_environment'
| 'code_environment_id'
| 'git_identity'
| 'code_workspace_id'
| 'artifacts'
| 'recursion_limit'
| 'category'
| 'support_contact'
| 'tool_options'
| 'skills'
| 'skills_enabled'
| 'skill_authoring_enabled'
| 'skills_scope'
| 'subagents'
| 'memory_scope'
>;
export type AgentListParams = {
limit?: number;
requiredPermission: number;
category?: string;
search?: string;
cursor?: string;
promoted?: 0 | 1;
};
export type AgentListResponse = {
object: string;
data: Agent[];
first_id: string;
last_id: string;
has_more: boolean;
after?: string;
};
export type AgentFile = {
file_id: string;
id?: string;
temp_file_id?: string;
bytes: number;
created_at: number;
filename: string;
object: string;
purpose: 'fine-tune' | 'fine-tune-results' | 'agents' | 'agents_output';
};

View file

@ -1,20 +1,5 @@
import { z } from 'zod';
import type { OpenAPIV3 } from 'openapi-types';
import type { AssistantsEndpoint, AgentProvider, MemoryScope, SkillsScope } from 'src/schemas';
import type { StatefulCodeEnvironment } from '../stateful-code';
import type { ContentTypes, SubagentIdentity } from './runs';
import type { Agents, GraphEdge } from './agents';
import type { TFile } from './files';
import { ArtifactModes } from 'src/artifacts';
export {
STATEFUL_CODE_ENVIRONMENTS,
resolveStatefulCodeEnvironment,
resolveAllowedStatefulCodeEnvironments,
} from '../stateful-code';
export type { StatefulCodeEnvironment } from '../stateful-code';
export type Schema = OpenAPIV3.SchemaObject & { description?: string };
export type Reference = OpenAPIV3.ReferenceObject & { description?: string };
import type { FunctionTool, ToolResources } from './tools';
import type { AssistantsEndpoint } from 'src/schemas';
export type Metadata = {
avatar?: string;
@ -23,73 +8,6 @@ export type Metadata = {
[key: string]: unknown;
};
export enum Tools {
execute_code = 'execute_code',
code_interpreter = 'code_interpreter',
file_search = 'file_search',
web_search = 'web_search',
retrieval = 'retrieval',
function = 'function',
memory = 'memory',
ui_resources = 'ui_resources',
skill = 'skill',
read_file = 'read_file',
bash_tool = 'bash_tool',
}
export enum EToolResources {
code_interpreter = 'code_interpreter',
execute_code = 'execute_code',
file_search = 'file_search',
image_edit = 'image_edit',
context = 'context',
ocr = 'ocr',
}
export type Tool = {
[type: string]: Tools;
};
export type FunctionTool = {
type: Tools;
function?: {
description: string;
name: string;
parameters: Record<string, unknown>;
strict?: boolean;
additionalProperties?: boolean; // must be false if strict is true https://platform.openai.com/docs/guides/structured-outputs/some-type-specific-keywords-are-not-yet-supported
};
};
/**
* A set of resources that are used by the assistant's tools. The resources are
* specific to the type of tool. For example, the `code_interpreter` tool requires
* a list of file IDs, while the `file_search` tool requires a list of vector store
* IDs.
*/
export interface ToolResources {
code_interpreter?: CodeInterpreterResource;
file_search?: FileSearchResource;
}
export interface CodeInterpreterResource {
/**
* A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made
* available to the `code_interpreter`` tool. There can be a maximum of 20 files
* associated with the tool.
*/
file_ids?: Array<string>;
}
export interface FileSearchResource {
/**
* The ID of the
* [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object)
* attached to this assistant. There can be a maximum of 1 vector store attached to
* the assistant.
*/
vector_store_ids?: Array<string>;
}
/* Assistant types */
export type Assistant = {
@ -164,476 +82,6 @@ export type File = {
purpose: 'fine-tune' | 'fine-tune-results' | 'assistants' | 'assistants_output';
};
/* Agent types */
export type AgentParameterValue = number | string | null;
export type AgentModelParameters = {
model?: string;
temperature: AgentParameterValue;
maxContextTokens: AgentParameterValue;
max_context_tokens: AgentParameterValue;
max_output_tokens: AgentParameterValue;
top_p: AgentParameterValue;
frequency_penalty: AgentParameterValue;
presence_penalty: AgentParameterValue;
useResponsesApi?: boolean;
};
export interface AgentBaseResource {
/**
* A list of file IDs made available to the tool.
*/
file_ids?: Array<string>;
/**
* A list of files already fetched.
*/
files?: Array<TFile>;
}
export interface AgentToolResources {
[EToolResources.image_edit]?: AgentBaseResource;
[EToolResources.execute_code]?: ExecuteCodeResource;
[EToolResources.file_search]?: AgentFileResource;
[EToolResources.context]?: AgentBaseResource;
/** @deprecated Use context instead */
[EToolResources.ocr]?: AgentBaseResource;
}
/**
* A resource for the execute_code tool.
* Contains file IDs made available to the tool (max 20 files) and already fetched files.
*/
export type ExecuteCodeResource = AgentBaseResource;
export interface AgentFileResource extends AgentBaseResource {
/**
* The ID of the vector store attached to this agent. There
* can be a maximum of 1 vector store attached to the agent.
*/
vector_store_ids?: Array<string>;
}
export type SupportContact = {
name?: string;
email?: string;
};
export type AgentOwnerContact = {
name?: string;
};
/**
* Specifies who can invoke a tool.
* - 'direct': LLM can call directly
* - 'code_execution': Only callable via programmatic tool calling (PTC)
*/
export type AllowedCaller = 'direct' | 'code_execution';
/**
* Per-tool configuration options stored at the agent level.
* Keyed by tool_id (e.g., "search_mcp_github").
*/
export type ToolOptions = {
/**
* If true, the tool uses deferred loading (discoverable via tool search).
* @default false
*/
defer_loading?: boolean;
/**
* Specifies who can invoke this tool.
* - 'direct': LLM can call directly (default behavior)
* - 'code_execution': Only callable via PTC sandbox
* @default ['direct']
*/
allowed_callers?: AllowedCaller[];
/**
* If true (and the `run_in_background` capability is enabled), the tool's
* schema gains a `run_in_background` boolean so the model can dispatch the
* call detached and poll its result via `check_background_task`.
* @default false
*/
run_in_background?: boolean;
/**
* If true (and the `tool_intents` capability is enabled), the tool's schema
* gains an `intent` string as its FIRST property — one model-authored
* sentence per call, rendered as the call's live status label. Native host
* tools default on while the capability is enabled; `false` opts one out.
* @default false
*/
describe_intent?: boolean;
};
/**
* Map of tool_id to its configuration options.
* Used to customize tool behavior per agent.
*/
export type AgentToolOptions = Record<string, ToolOptions>;
/**
* Configuration for spawning subagents (isolated-context child agents) from an agent.
* When `enabled` is true, the agent gets a subagent-spawn tool that can delegate work
* to itself, listed single-agent targets, and/or explicit saved-agent teams.
*/
export type AgentSubagentGraphEdge = Omit<
GraphEdge,
'edgeType' | 'condition' | 'prompt' | 'promptKey'
> & {
edgeType: 'direct';
condition?: never;
prompt?: string;
promptKey?: never;
};
/** A bounded saved-agent team that can be spawned as one isolated child graph. */
export type AgentSubagentGraph = {
/** Stable spawn-tool enum value for the team. */
type: string;
name: string;
description: string;
/** Member IDs. In create/update payloads, an empty ID refers to the current agent. */
agent_ids: string[];
edges: AgentSubagentGraphEdge[];
/** Entry member ID. In create/update payloads, an empty ID refers to the current agent. */
entry_agent_id: string;
/** Result member ID. In create/update payloads, an empty ID refers to the current agent. */
result_agent_id: string;
};
export type AgentSubagentsConfig = {
enabled?: boolean;
/** When true (default), the agent may spawn itself in an isolated context. */
allowSelf?: boolean;
/** Share current-turn files with authorized descendants. Off unless explicitly enabled. */
shareFiles?: boolean;
/** Specific agents that may be spawned as subagents. */
agent_ids?: string[];
/** Explicit saved-agent teams that may be spawned as bounded child graphs. */
graphs?: AgentSubagentGraph[];
};
export type AgentGitIdentity = {
/** Commit author and committer display name. */
name: string;
/** Commit author and committer email address. */
email: string;
};
export const agentGitIdentitySchema: z.ZodType<AgentGitIdentity | undefined> = z
.object({
name: z
.string()
.trim()
.min(1)
.max(128)
.refine((value) => !/[\0\r\n]/.test(value)),
email: z
.string()
.trim()
.email()
.max(254)
.refine((value) => !/[\0\r\n]/.test(value)),
})
.optional();
export type Agent = {
_id?: string;
id: string;
name: string | null;
author?: string | null;
/** The original custom endpoint name, lowercased */
endpoint?: string | null;
authorName?: string | null;
description: string | null;
created_at: number;
avatar: AgentAvatar | null;
instructions?: string | null;
additional_instructions?: string | null;
tools?: string[];
tool_kwargs?: Record<string, unknown>;
metadata?: Record<string, unknown>;
provider: AgentProvider;
model: string | null;
model_parameters: AgentModelParameters;
conversation_starters?: string[];
tool_resources?: AgentToolResources;
/** @deprecated Use edges instead */
agent_ids?: string[];
edges?: GraphEdge[];
end_after_tools?: boolean;
hide_sequential_outputs?: boolean;
/** Per-agent opt-in for stateful code sessions (requires the app-level capability). */
stateful_code_sessions?: boolean;
/** Stateful workspace sharing scope. Defaults to one workspace per user. */
stateful_code_environment?: StatefulCodeEnvironment;
/** Operator-configured managed or attached stateful execution environment. */
code_environment_id?: string | null;
/** Default attached workspace for new chats; empty means no agent default. */
code_workspace_id?: string;
/** Non-secret Git authorship injected into this agent's sandboxed commands. */
git_identity?: AgentGitIdentity | null;
artifacts?: ArtifactModes;
recursion_limit?: number;
isPublic?: boolean;
/**
* Whether the requesting user holds EDIT on this agent, so a single VIEW-scoped fetch can
* serve consumers that only need the editable subset instead of issuing a second full
* paginated walk under an EDIT-scoped cache key.
*
* Set by the list endpoint only; single-agent responses omit it. Treat absence as unknown
* and fail open (`isEditable !== false`), never as `false`, since a client on an older
* server would otherwise see an empty list rather than too many rows.
*
* Reflects the caller's ACL grant. The `MANAGE_AGENTS` capability bypasses ACL on write,
* so a capability holder can edit agents this flag reports as not editable.
*/
isEditable?: boolean;
version?: number;
category?: string;
support_contact?: SupportContact;
owner_contact?: AgentOwnerContact;
/** Per-tool configuration options (deferred loading, allowed callers, etc.) */
tool_options?: AgentToolOptions;
/** Attached action registrations, each `${encodedDomain}${actionDelimiter}${action_id}` */
actions?: string[];
/** Optional allowlist of skill ObjectIds. Only applies when `skills_enabled`. */
skills?: string[];
/** Master toggle for skill use on this agent. `true` = active (full catalog unless
* `skills` narrows it). `false`/undefined = inactive (no skills available). */
skills_enabled?: boolean;
/** Enables runtime skill creation without exposing an existing skill catalog. */
skill_authoring_enabled?: boolean;
/** Explicit catalog exposure while skills are enabled. Missing preserves legacy semantics. */
skills_scope?: SkillsScope;
/** Subagent spawning configuration — isolated-context child agents. */
subagents?: AgentSubagentsConfig;
/** Memory partition: `agent` isolates memories per (user, agent); default shared pool */
memory_scope?: MemoryScope;
};
export type TAgentsMap = Record<string, Agent | undefined>;
export type AgentCreateParams = {
git_identity?: AgentGitIdentity;
name?: string | null;
description?: string | null;
avatar?: AgentAvatar | null;
file_ids?: string[];
instructions?: string | null;
tools?: Array<FunctionTool | string>;
provider: AgentProvider;
model: string | null;
model_parameters: AgentModelParameters;
} & Pick<
Agent,
| 'agent_ids'
| 'edges'
| 'end_after_tools'
| 'hide_sequential_outputs'
| 'stateful_code_sessions'
| 'stateful_code_environment'
| 'code_environment_id'
| 'code_workspace_id'
| 'artifacts'
| 'recursion_limit'
| 'category'
| 'support_contact'
| 'tool_options'
| 'skills'
| 'skills_enabled'
| 'skill_authoring_enabled'
| 'skills_scope'
| 'subagents'
| 'memory_scope'
>;
export type AgentUpdateParams = {
name?: string | null;
description?: string | null;
avatar?: AgentAvatar | null;
file_ids?: string[];
instructions?: string | null;
tools?: Array<FunctionTool | string>;
tool_resources?: ToolResources;
provider?: AgentProvider;
model?: string | null;
model_parameters?: AgentModelParameters;
} & Pick<
Agent,
| 'agent_ids'
| 'edges'
| 'end_after_tools'
| 'hide_sequential_outputs'
| 'stateful_code_sessions'
| 'stateful_code_environment'
| 'code_environment_id'
| 'git_identity'
| 'code_workspace_id'
| 'artifacts'
| 'recursion_limit'
| 'category'
| 'support_contact'
| 'tool_options'
| 'skills'
| 'skills_enabled'
| 'skill_authoring_enabled'
| 'skills_scope'
| 'subagents'
| 'memory_scope'
>;
export type AgentListParams = {
limit?: number;
requiredPermission: number;
category?: string;
search?: string;
cursor?: string;
promoted?: 0 | 1;
};
export type AgentListResponse = {
object: string;
data: Agent[];
first_id: string;
last_id: string;
has_more: boolean;
after?: string;
};
export type AgentFile = {
file_id: string;
id?: string;
temp_file_id?: string;
bytes: number;
created_at: number;
filename: string;
object: string;
purpose: 'fine-tune' | 'fine-tune-results' | 'agents' | 'agents_output';
};
/**
* Details of the Code Interpreter tool call the run step was involved in.
* Includes the tool call ID, the code interpreter definition, and the type of tool call.
*/
export type CodeToolCall = {
id: string; // The ID of the tool call.
code_interpreter: {
input: string; // The input to the Code Interpreter tool call.
outputs: Array<Record<string, unknown>>; // The outputs from the Code Interpreter tool call.
};
type: 'code_interpreter'; // The type of tool call, always 'code_interpreter'.
};
/**
* Details of a Function tool call the run step was involved in.
* Includes the tool call ID, the function definition, and the type of tool call.
*/
export type FunctionToolCall = {
id: string; // The ID of the tool call object.
function: {
arguments: string; // The arguments passed to the function.
name: string; // The name of the function.
output: string | null; // The output of the function, null if not submitted.
};
type: 'function'; // The type of tool call, always 'function'.
};
/**
* Details of a Retrieval tool call the run step was involved in.
* Includes the tool call ID and the type of tool call.
*/
export type RetrievalToolCall = {
id: string; // The ID of the tool call object.
retrieval: unknown; // An empty object for now.
type: 'retrieval'; // The type of tool call, always 'retrieval'.
};
/**
* Details of a Retrieval tool call the run step was involved in.
* Includes the tool call ID and the type of tool call.
*/
export type FileSearchToolCall = {
id: string; // The ID of the tool call object.
file_search: unknown; // An empty object for now.
type: 'file_search'; // The type of tool call, always 'retrieval'.
};
/**
* Details of the tool calls involved in a run step.
* Can be associated with one of three types of tools: `code_interpreter`, `retrieval`, or `function`.
*/
export type ToolCallsStepDetails = {
tool_calls: Array<CodeToolCall | RetrievalToolCall | FileSearchToolCall | FunctionToolCall>; // An array of tool calls the run step was involved in.
type: 'tool_calls'; // Always 'tool_calls'.
};
export type ImageFile = TFile & {
/**
* The [File](https://platform.openai.com/docs/api-reference/files) ID of the image
* in the message content.
*/
file_id: string;
filename: string;
filepath: string;
height: number;
width: number;
/**
* Prompt used to generate the image if applicable.
*/
prompt?: string;
/**
* Additional metadata used to generate or about the image/tool_call.
*/
metadata?: Record<string, unknown>;
};
// FileCitation.ts
export type FileCitation = {
end_index: number;
file_citation: FileCitationDetails;
start_index: number;
text: string;
type: 'file_citation';
};
export type FileCitationDetails = {
file_id: string;
quote: string;
};
export type FilePath = {
end_index: number;
file_path: FilePathDetails;
start_index: number;
text: string;
type: 'file_path';
};
export type FilePathDetails = {
file_id: string;
};
export type Text = {
annotations?: Array<FileCitation | FilePath>;
value: string;
};
export enum AnnotationTypes {
FILE_CITATION = 'file_citation',
FILE_PATH = 'file_path',
}
export enum StepStatus {
IN_PROGRESS = 'in_progress',
CANCELLED = 'cancelled',
FAILED = 'failed',
COMPLETED = 'completed',
EXPIRED = 'expired',
}
export enum MessageContentTypes {
TEXT = 'text',
IMAGE_FILE = 'image_file',
}
//enum for RunStatus
// The status of the run: queued, in_progress, requires_action, cancelling, cancelled, failed, completed, or expired.
export enum RunStatus {
@ -647,242 +95,6 @@ export enum RunStatus {
EXPIRED = 'expired',
}
export type PartMetadata = {
/** Host-resolved execution identity for a saved subagent invocation. */
subagentIdentity?: SubagentIdentity;
progress?: number;
asset_pointer?: string;
status?: string;
action?: boolean;
auth?: string;
expires_at?: number;
/** Index indicating parallel sibling content (same stepIndex in multi-agent runs) */
siblingIndex?: number;
/** Agent ID for parallel agent rendering - identifies which agent produced this content */
agentId?: string;
/** Group ID for parallel content - parts with same groupId are displayed in columns */
groupId?: number;
/**
* Terminal lifecycle status of the run step that produced this part, from
* `on_run_step_closed`. Distinct from `status`, which is already claimed by
* activity-label and question-form parts. Absent on parts predating the
* event or from endpoints that do not emit it, in which case renderers fall
* back to inferring "stopped" from `progress` and `isSubmitting`.
*/
runStepStatus?: Agents.RunStepClosedStatus;
/**
* Wall-clock milliseconds the run step took, derived from the same
* `on_run_step_closed` event as {@link runStepStatus} via
* `getRunStepDurationMs`. Only written when the event carried both
* timestamps and they agree in order — so its absence means "not
* derivable", never "instant". The raw value is persisted unfiltered;
* whether it is worth showing (`isReportableRunStepDuration`) is decided
* at render time.
*/
runStepDurationMs?: number;
/**
* Stamped by the background harvester when a detached task's final output
* replaces the dispatch handle in `tool_call.output`. The handle JSON and
* the live status-marker attachment are both transient, so after the patch
* (or a reload) this is the only signal that the call ran in the
* background — renderers use it to keep treating {@link runStepDurationMs}
* as dispatch time rather than the task's runtime.
*/
backgrounded?: boolean;
/**
* Content index this part occupied while its run streamed. The aggregator
* writes parts at provider-source indexes, so the streamed array is sparse;
* persistence compacts it and every part after a hole shifts down. The
* client's final handler stamps the streamed position onto the compacted
* parts it adopts, so index-derived render identity survives the swap
* instead of remounting the settled message. Client-only and absent
* everywhere else — persisted content never carries it.
*/
streamedIndex?: number;
};
/** Metadata for parallel content rendering - subset of PartMetadata */
export type ContentMetadata = Pick<PartMetadata, 'agentId' | 'groupId' | 'streamedIndex'>;
export type ContentPart = (
| CodeToolCall
| RetrievalToolCall
| FileSearchToolCall
| FunctionToolCall
| Agents.AgentToolCall
| ImageFile
| Text
) &
PartMetadata;
export type TextData = (Text & PartMetadata) | undefined;
export type SummaryContentPart = {
type: ContentTypes.SUMMARY;
content?: Array<{ type: ContentTypes.TEXT; text: string }>;
tokenCount?: number;
summarizing?: boolean;
/** A summarize round that ended in error. Partial deltas already streamed
* into this slot are kept, so the renderer needs this to avoid presenting
* truncated text under the "Conversation summarized" label. */
failed?: boolean;
/** Set when the user compacted the context manually rather than the
* automatic detour firing on context pressure. */
initiatedBy?: 'user';
summaryVersion?: number;
model?: string;
provider?: string;
createdAt?: string;
boundary?: {
messageId: string;
contentIndex: number;
};
};
/**
* A user steering message injected mid-run at a tool-batch boundary.
* Persisted inline in the response message's content array (keyed by the
* type name like `text`/`think` so token counting reads it for free);
* replayed as a user message on subsequent turns by `formatAgentMessages`.
*/
export type SteerContentPart = {
type: ContentTypes.STEER;
steer: string;
steerId?: string;
/** Stable optimistic-client id used to settle a POST whose response was lost. */
clientSteerId?: string;
createdAt?: number;
/** Attachments steered with the message; re-encoded per turn on replay
* like any other user-message media (refs only, never encoded data). */
files?: Partial<TFile>[];
/** Quoted excerpts steered with the message, persisted separately from the
* typed text (mirroring `TMessage.quotes`) so the UI renders them as
* reference blocks; merged into the model-bound user turn on every replay. */
quotes?: string[];
};
export type TMessageContentParts =
| ({
type: ContentTypes.ERROR;
text?: string | TextData;
error?: string;
/** Set when this failure is what a manual compaction produced instead of a
* summary. The turn has no other record of having been one, so the rerun
* controls read it the same way they read a summary's marker. */
initiatedBy?: 'user';
} & ContentMetadata)
| ({
type: ContentTypes.THINK;
think?: string | TextData;
/** Generated orientation for this user-visible reasoning step. */
reasoning_label?: string;
/** Stable SDK run-step identity used to correlate live revisions. */
reasoning_label_step_id?: string;
/** Durable provider-call count used to enforce the per-run cost cap across resumes. */
reasoning_label_attempts?: number;
/** Visible reasoning length included in this step's latest provider call. */
reasoning_label_submitted_chars?: number;
/** Monotonic provider-call revision; gaps are allowed after unsuccessful attempts. */
reasoning_label_revision?: number;
/** Whether the reasoning step can still produce a newer label. */
reasoning_label_status?: 'streaming' | 'complete';
/** The reasoning happened but its text is not available to this view
* (e.g. detached subagent projections retain only a marker). */
reasoning_unavailable?: boolean;
} & ContentMetadata)
| (SteerContentPart & ContentMetadata)
| ({
type: ContentTypes.TEXT;
text?: string | TextData;
tool_call_ids?: string[];
/** Open Responses semantic channel for assistant text. */
phase?: 'commentary' | 'final_answer';
} & ContentMetadata)
| ({
type: ContentTypes.TOOL_CALL;
tool_call: (
| CodeToolCall
| RetrievalToolCall
| FileSearchToolCall
| FunctionToolCall
| Agents.AgentToolCall
) &
PartMetadata;
} & ContentMetadata)
| ({ type: ContentTypes.IMAGE_FILE; image_file: ImageFile & PartMetadata } & ContentMetadata)
| (SummaryContentPart & ContentMetadata)
| ({
/** One-line LLM-generated note describing a completed tool batch. UI-only:
* never sent to the model (stripped before payload formatting). */
type: ContentTypes.ACTIVITY_LABEL;
activity_label?: string;
/** Missing means the legacy/per-batch activity label. */
activity_label_type?: 'phase';
tool_call_ids?: string[];
/** Parent phase bounds and telemetry. */
activity_start_index?: number;
/** Exclusive end of the grouped content; may precede the marker itself. */
activity_end_index?: number;
activity_count?: number;
agent_ids?: string[];
/** ok = all tools succeeded, failed = all failed, partial = mixed. */
status?: 'ok' | 'partial' | 'failed';
pending?: boolean;
} & ContentMetadata)
| (Agents.AgentUpdate & ContentMetadata)
| (Agents.MessageContentImageUrl & ContentMetadata)
| (Agents.MessageContentVideoUrl & ContentMetadata)
| (Agents.MessageContentInputAudio & ContentMetadata);
export type StreamContentData = TMessageContentParts & {
/** The index of the current content part */
index: number;
/** The current text content was already served but edited to replace elements therein */
edited?: boolean;
};
export type TContentData = StreamContentData & {
messageId: string;
conversationId: string;
userMessageId: string;
thread_id: string;
stream?: boolean;
};
export const actionDelimiter = '_action_';
export const actionDomainSeparator = '---';
/** Mirrors `Constants.mcp_delimiter`; duplicated here to avoid a circular import from `config.ts`. */
const mcpDelimiter = '_mcp_';
/**
* Checks whether a tool name is an OpenAPI action tool.
*
* Action format: `operationId_action_normalizedDomain`
* MCP format: `toolName_mcp_serverName`
*
* Cross-delimiter collision: an MCP tool like `get_action_mcp_srv` contains
* `_action_` as a false positive. Guarded by checking whether `_mcp_` appears
* after `_action_`. In the collision case the `_mcp_` suffix always follows
* `_action_`; in a valid action tool whose operationId contains `_mcp_`, the
* `_mcp_` precedes `_action_`.
*
* Theoretical limitation: a non-RFC-compliant domain containing literal
* underscores that form `_mcp_` (e.g. `api_mcp_internal.com`) would produce
* a false negative. RFC 952/1123 prohibit underscores in hostnames, so this
* is not expected in practice.
*/
export function isActionTool(toolName: string): boolean {
const actionIdx = toolName.indexOf(actionDelimiter);
if (actionIdx < 0) {
return false;
}
const mcpIdx = toolName.indexOf(mcpDelimiter);
return mcpIdx < 0 || mcpIdx < actionIdx;
}
export const hostImageIdSuffix = '_host_copy';
export const hostImageNamePrefix = 'host_copy_';
export type AssistantAvatar = {
filepath: string;
source: string;
@ -901,13 +113,6 @@ export type AssistantDocument = {
append_current_datetime?: boolean;
};
/* Agent types */
export type AgentAvatar = {
filepath: string;
source: string;
};
export enum FilePurpose {
Vision = 'vision',
FineTune = 'fine-tune',

View file

@ -0,0 +1,333 @@
import type { SubagentIdentity, ContentTypes } from './runs';
import type { Agents } from './agents';
import type { TFile } from './files';
/**
* Details of the Code Interpreter tool call the run step was involved in.
* Includes the tool call ID, the code interpreter definition, and the type of tool call.
*/
export type CodeToolCall = {
id: string; // The ID of the tool call.
code_interpreter: {
input: string; // The input to the Code Interpreter tool call.
outputs: Array<Record<string, unknown>>; // The outputs from the Code Interpreter tool call.
};
type: 'code_interpreter'; // The type of tool call, always 'code_interpreter'.
};
/**
* Details of a Function tool call the run step was involved in.
* Includes the tool call ID, the function definition, and the type of tool call.
*/
export type FunctionToolCall = {
id: string; // The ID of the tool call object.
function: {
arguments: string; // The arguments passed to the function.
name: string; // The name of the function.
output: string | null; // The output of the function, null if not submitted.
};
type: 'function'; // The type of tool call, always 'function'.
};
/**
* Details of a Retrieval tool call the run step was involved in.
* Includes the tool call ID and the type of tool call.
*/
export type RetrievalToolCall = {
id: string; // The ID of the tool call object.
retrieval: unknown; // An empty object for now.
type: 'retrieval'; // The type of tool call, always 'retrieval'.
};
/**
* Details of a Retrieval tool call the run step was involved in.
* Includes the tool call ID and the type of tool call.
*/
export type FileSearchToolCall = {
id: string; // The ID of the tool call object.
file_search: unknown; // An empty object for now.
type: 'file_search'; // The type of tool call, always 'retrieval'.
};
/**
* Details of the tool calls involved in a run step.
* Can be associated with one of three types of tools: `code_interpreter`, `retrieval`, or `function`.
*/
export type ToolCallsStepDetails = {
tool_calls: Array<CodeToolCall | RetrievalToolCall | FileSearchToolCall | FunctionToolCall>; // An array of tool calls the run step was involved in.
type: 'tool_calls'; // Always 'tool_calls'.
};
export type ImageFile = TFile & {
/**
* The [File](https://platform.openai.com/docs/api-reference/files) ID of the image
* in the message content.
*/
file_id: string;
filename: string;
filepath: string;
height: number;
width: number;
/**
* Prompt used to generate the image if applicable.
*/
prompt?: string;
/**
* Additional metadata used to generate or about the image/tool_call.
*/
metadata?: Record<string, unknown>;
};
// FileCitation.ts
export type FileCitation = {
end_index: number;
file_citation: FileCitationDetails;
start_index: number;
text: string;
type: 'file_citation';
};
export type FileCitationDetails = {
file_id: string;
quote: string;
};
export type FilePath = {
end_index: number;
file_path: FilePathDetails;
start_index: number;
text: string;
type: 'file_path';
};
export type FilePathDetails = {
file_id: string;
};
export type Text = {
annotations?: Array<FileCitation | FilePath>;
value: string;
};
export enum AnnotationTypes {
FILE_CITATION = 'file_citation',
FILE_PATH = 'file_path',
}
export enum StepStatus {
IN_PROGRESS = 'in_progress',
CANCELLED = 'cancelled',
FAILED = 'failed',
COMPLETED = 'completed',
EXPIRED = 'expired',
}
export enum MessageContentTypes {
TEXT = 'text',
IMAGE_FILE = 'image_file',
}
export type PartMetadata = {
/** Host-resolved execution identity for a saved subagent invocation. */
subagentIdentity?: SubagentIdentity;
progress?: number;
asset_pointer?: string;
status?: string;
action?: boolean;
auth?: string;
expires_at?: number;
/** Index indicating parallel sibling content (same stepIndex in multi-agent runs) */
siblingIndex?: number;
/** Agent ID for parallel agent rendering - identifies which agent produced this content */
agentId?: string;
/** Group ID for parallel content - parts with same groupId are displayed in columns */
groupId?: number;
/**
* Terminal lifecycle status of the run step that produced this part, from
* `on_run_step_closed`. Distinct from `status`, which is already claimed by
* activity-label and question-form parts. Absent on parts predating the
* event or from endpoints that do not emit it, in which case renderers fall
* back to inferring "stopped" from `progress` and `isSubmitting`.
*/
runStepStatus?: Agents.RunStepClosedStatus;
/**
* Wall-clock milliseconds the run step took, derived from the same
* `on_run_step_closed` event as {@link runStepStatus} via
* `getRunStepDurationMs`. Only written when the event carried both
* timestamps and they agree in order — so its absence means "not
* derivable", never "instant". The raw value is persisted unfiltered;
* whether it is worth showing (`isReportableRunStepDuration`) is decided
* at render time.
*/
runStepDurationMs?: number;
/**
* Stamped by the background harvester when a detached task's final output
* replaces the dispatch handle in `tool_call.output`. The handle JSON and
* the live status-marker attachment are both transient, so after the patch
* (or a reload) this is the only signal that the call ran in the
* background — renderers use it to keep treating {@link runStepDurationMs}
* as dispatch time rather than the task's runtime.
*/
backgrounded?: boolean;
/**
* Content index this part occupied while its run streamed. The aggregator
* writes parts at provider-source indexes, so the streamed array is sparse;
* persistence compacts it and every part after a hole shifts down. The
* client's final handler stamps the streamed position onto the compacted
* parts it adopts, so index-derived render identity survives the swap
* instead of remounting the settled message. Client-only and absent
* everywhere else — persisted content never carries it.
*/
streamedIndex?: number;
};
/** Metadata for parallel content rendering - subset of PartMetadata */
export type ContentMetadata = Pick<PartMetadata, 'agentId' | 'groupId' | 'streamedIndex'>;
export type ContentPart = (
| CodeToolCall
| RetrievalToolCall
| FileSearchToolCall
| FunctionToolCall
| Agents.AgentToolCall
| ImageFile
| Text
) &
PartMetadata;
export type TextData = (Text & PartMetadata) | undefined;
export type SummaryContentPart = {
type: ContentTypes.SUMMARY;
content?: Array<{ type: ContentTypes.TEXT; text: string }>;
tokenCount?: number;
summarizing?: boolean;
/** A summarize round that ended in error. Partial deltas already streamed
* into this slot are kept, so the renderer needs this to avoid presenting
* truncated text under the "Conversation summarized" label. */
failed?: boolean;
/** Set when the user compacted the context manually rather than the
* automatic detour firing on context pressure. */
initiatedBy?: 'user';
summaryVersion?: number;
model?: string;
provider?: string;
createdAt?: string;
boundary?: {
messageId: string;
contentIndex: number;
};
};
/**
* A user steering message injected mid-run at a tool-batch boundary.
* Persisted inline in the response message's content array (keyed by the
* type name like `text`/`think` so token counting reads it for free);
* replayed as a user message on subsequent turns by `formatAgentMessages`.
*/
export type SteerContentPart = {
type: ContentTypes.STEER;
steer: string;
steerId?: string;
/** Stable optimistic-client id used to settle a POST whose response was lost. */
clientSteerId?: string;
createdAt?: number;
/** Attachments steered with the message; re-encoded per turn on replay
* like any other user-message media (refs only, never encoded data). */
files?: Partial<TFile>[];
/** Quoted excerpts steered with the message, persisted separately from the
* typed text (mirroring `TMessage.quotes`) so the UI renders them as
* reference blocks; merged into the model-bound user turn on every replay. */
quotes?: string[];
};
export type TMessageContentParts =
| ({
type: ContentTypes.ERROR;
text?: string | TextData;
error?: string;
/** Set when this failure is what a manual compaction produced instead of a
* summary. The turn has no other record of having been one, so the rerun
* controls read it the same way they read a summary's marker. */
initiatedBy?: 'user';
} & ContentMetadata)
| ({
type: ContentTypes.THINK;
think?: string | TextData;
/** Generated orientation for this user-visible reasoning step. */
reasoning_label?: string;
/** Stable SDK run-step identity used to correlate live revisions. */
reasoning_label_step_id?: string;
/** Durable provider-call count used to enforce the per-run cost cap across resumes. */
reasoning_label_attempts?: number;
/** Visible reasoning length included in this step's latest provider call. */
reasoning_label_submitted_chars?: number;
/** Monotonic provider-call revision; gaps are allowed after unsuccessful attempts. */
reasoning_label_revision?: number;
/** Whether the reasoning step can still produce a newer label. */
reasoning_label_status?: 'streaming' | 'complete';
/** The reasoning happened but its text is not available to this view
* (e.g. detached subagent projections retain only a marker). */
reasoning_unavailable?: boolean;
} & ContentMetadata)
| (SteerContentPart & ContentMetadata)
| ({
type: ContentTypes.TEXT;
text?: string | TextData;
tool_call_ids?: string[];
/** Open Responses semantic channel for assistant text. */
phase?: 'commentary' | 'final_answer';
} & ContentMetadata)
| ({
type: ContentTypes.TOOL_CALL;
tool_call: (
| CodeToolCall
| RetrievalToolCall
| FileSearchToolCall
| FunctionToolCall
| Agents.AgentToolCall
) &
PartMetadata;
} & ContentMetadata)
| ({ type: ContentTypes.IMAGE_FILE; image_file: ImageFile & PartMetadata } & ContentMetadata)
| (SummaryContentPart & ContentMetadata)
| ({
/** One-line LLM-generated note describing a completed tool batch. UI-only:
* never sent to the model (stripped before payload formatting). */
type: ContentTypes.ACTIVITY_LABEL;
activity_label?: string;
/** Missing means the legacy/per-batch activity label. */
activity_label_type?: 'phase';
tool_call_ids?: string[];
/** Parent phase bounds and telemetry. */
activity_start_index?: number;
/** Exclusive end of the grouped content; may precede the marker itself. */
activity_end_index?: number;
activity_count?: number;
agent_ids?: string[];
/** ok = all tools succeeded, failed = all failed, partial = mixed. */
status?: 'ok' | 'partial' | 'failed';
pending?: boolean;
} & ContentMetadata)
| (Agents.AgentUpdate & ContentMetadata)
| (Agents.MessageContentImageUrl & ContentMetadata)
| (Agents.MessageContentVideoUrl & ContentMetadata)
| (Agents.MessageContentInputAudio & ContentMetadata);
export type StreamContentData = TMessageContentParts & {
/** The index of the current content part */
index: number;
/** The current text content was already served but edited to replace elements therein */
edited?: boolean;
};
export type TContentData = StreamContentData & {
messageId: string;
conversationId: string;
userMessageId: string;
thread_id: string;
stream?: boolean;
};
export const hostImageIdSuffix = '_host_copy';
export const hostImageNamePrefix = 'host_copy_';

View file

@ -1,6 +1,6 @@
import type { TDefaultLLMDeliveryPathConfig } from '../file-config';
import type { CodeEnvRef, CodeEnvRefMap } from '../codeEnvRef';
import { EToolResources } from './assistants';
import { EToolResources } from './tools';
export enum FileSources {
local = 'local',

View file

@ -12,17 +12,13 @@ import type {
TSkillListResponse,
} from './skills';
import {
Tools,
Assistant,
AssistantCreateParams,
AssistantUpdateParams,
FunctionTool,
AssistantDocument,
Agent,
AgentCreateParams,
AgentUpdateParams,
} from './assistants';
import { Action, ActionMetadata } from './agents';
import { Action, ActionMetadata, Agent, AgentCreateParams, AgentUpdateParams } from './agents';
import { Tools, FunctionTool } from './tools';
import * as p from '../permissions';
import * as types from '../types';
import * as r from '../roles';

View file

@ -0,0 +1,149 @@
import type { OpenAPIV3 } from 'openapi-types';
export type Schema = OpenAPIV3.SchemaObject & { description?: string };
export type Reference = OpenAPIV3.ReferenceObject & { description?: string };
export enum Tools {
execute_code = 'execute_code',
code_interpreter = 'code_interpreter',
file_search = 'file_search',
web_search = 'web_search',
retrieval = 'retrieval',
function = 'function',
memory = 'memory',
ui_resources = 'ui_resources',
skill = 'skill',
read_file = 'read_file',
bash_tool = 'bash_tool',
}
export enum EToolResources {
code_interpreter = 'code_interpreter',
execute_code = 'execute_code',
file_search = 'file_search',
image_edit = 'image_edit',
context = 'context',
ocr = 'ocr',
}
export type Tool = {
[type: string]: Tools;
};
export type FunctionTool = {
type: Tools;
function?: {
description: string;
name: string;
parameters: Record<string, unknown>;
strict?: boolean;
additionalProperties?: boolean; // must be false if strict is true https://platform.openai.com/docs/guides/structured-outputs/some-type-specific-keywords-are-not-yet-supported
};
};
/**
* A set of resources that are used by the assistant's tools. The resources are
* specific to the type of tool. For example, the `code_interpreter` tool requires
* a list of file IDs, while the `file_search` tool requires a list of vector store
* IDs.
*/
export interface ToolResources {
code_interpreter?: CodeInterpreterResource;
file_search?: FileSearchResource;
}
export interface CodeInterpreterResource {
/**
* A list of [file](https://platform.openai.com/docs/api-reference/files) IDs made
* available to the `code_interpreter`` tool. There can be a maximum of 20 files
* associated with the tool.
*/
file_ids?: Array<string>;
}
export interface FileSearchResource {
/**
* The ID of the
* [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object)
* attached to this assistant. There can be a maximum of 1 vector store attached to
* the assistant.
*/
vector_store_ids?: Array<string>;
}
/**
* Specifies who can invoke a tool.
* - 'direct': LLM can call directly
* - 'code_execution': Only callable via programmatic tool calling (PTC)
*/
export type AllowedCaller = 'direct' | 'code_execution';
/**
* Per-tool configuration options stored at the agent level.
* Keyed by tool_id (e.g., "search_mcp_github").
*/
export type ToolOptions = {
/**
* If true, the tool uses deferred loading (discoverable via tool search).
* @default false
*/
defer_loading?: boolean;
/**
* Specifies who can invoke this tool.
* - 'direct': LLM can call directly (default behavior)
* - 'code_execution': Only callable via PTC sandbox
* @default ['direct']
*/
allowed_callers?: AllowedCaller[];
/**
* If true (and the `run_in_background` capability is enabled), the tool's
* schema gains a `run_in_background` boolean so the model can dispatch the
* call detached and poll its result via `check_background_task`.
* @default false
*/
run_in_background?: boolean;
/**
* If true (and the `tool_intents` capability is enabled), the tool's schema
* gains an `intent` string as its FIRST property — one model-authored
* sentence per call, rendered as the call's live status label. Native host
* tools default on while the capability is enabled; `false` opts one out.
* @default false
*/
describe_intent?: boolean;
};
/**
* Map of tool_id to its configuration options.
* Used to customize tool behavior per agent.
*/
export type AgentToolOptions = Record<string, ToolOptions>;
export const actionDelimiter = '_action_';
export const actionDomainSeparator = '---';
/** Mirrors `Constants.mcp_delimiter`; duplicated here to avoid a circular import from `config.ts`. */
const mcpDelimiter = '_mcp_';
/**
* Checks whether a tool name is an OpenAPI action tool.
*
* Action format: `operationId_action_normalizedDomain`
* MCP format: `toolName_mcp_serverName`
*
* Cross-delimiter collision: an MCP tool like `get_action_mcp_srv` contains
* `_action_` as a false positive. Guarded by checking whether `_mcp_` appears
* after `_action_`. In the collision case the `_mcp_` suffix always follows
* `_action_`; in a valid action tool whose operationId contains `_mcp_`, the
* `_mcp_` precedes `_action_`.
*
* Theoretical limitation: a non-RFC-compliant domain containing literal
* underscores that form `_mcp_` (e.g. `api_mcp_internal.com`) would produce
* a false negative. RFC 952/1123 prohibit underscores in hostnames, so this
* is not expected in practice.
*/
export function isActionTool(toolName: string): boolean {
const actionIdx = toolName.indexOf(actionDelimiter);
if (actionIdx < 0) {
return false;
}
const mcpIdx = toolName.indexOf(mcpDelimiter);
return mcpIdx < 0 || mcpIdx < actionIdx;
}

View file

@ -1,4 +1,4 @@
import type { EToolResources } from './types/assistants';
import type { EToolResources } from './types/tools';
import type { TFileUpload } from './types/files';
import request from './request';