diff --git a/packages/data-provider/specs/parsers.spec.ts b/packages/data-provider/specs/parsers.spec.ts index 36d2ff1270..c1cf132f5d 100644 --- a/packages/data-provider/specs/parsers.spec.ts +++ b/packages/data-provider/specs/parsers.spec.ts @@ -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 diff --git a/packages/data-provider/specs/stateful-code.spec.ts b/packages/data-provider/specs/stateful-code.spec.ts index 866a853ea7..a2ed3648e4 100644 --- a/packages/data-provider/specs/stateful-code.spec.ts +++ b/packages/data-provider/specs/stateful-code.spec.ts @@ -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', () => { diff --git a/packages/data-provider/src/actions.ts b/packages/data-provider/src/actions.ts index dd9a674444..639ec3ca7f 100644 --- a/packages/data-provider/src/actions.ts +++ b/packages/data-provider/src/actions.ts @@ -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; diff --git a/packages/data-provider/src/agentToolOptions.spec.ts b/packages/data-provider/src/agentToolOptions.spec.ts index be52b21b98..70ac60238f 100644 --- a/packages/data-provider/src/agentToolOptions.spec.ts +++ b/packages/data-provider/src/agentToolOptions.spec.ts @@ -1,4 +1,4 @@ -import type { AgentToolOptions } from './types/assistants'; +import type { AgentToolOptions } from './types/tools'; import { normalizeActionToolName, removeCodeExecutionCaller } from './agentToolOptions'; describe('normalizeActionToolName', () => { diff --git a/packages/data-provider/src/agentToolOptions.ts b/packages/data-provider/src/agentToolOptions.ts index 269e27a7b7..8de99fd47b 100644 --- a/packages/data-provider/src/agentToolOptions.ts +++ b/packages/data-provider/src/agentToolOptions.ts @@ -4,7 +4,7 @@ import { isActionTool, type AgentToolOptions, type AllowedCaller, -} from './types/assistants'; +} from './types/tools'; const actionDomainSeparatorRegex = new RegExp(actionDomainSeparator, 'g'); diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts index 3fc9fecf09..cafd0e1145 100644 --- a/packages/data-provider/src/config.ts +++ b/packages/data-provider/src/config.ts @@ -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'; diff --git a/packages/data-provider/src/data-service.ts b/packages/data-provider/src/data-service.ts index 60e2832b52..cf5ade19a1 100644 --- a/packages/data-provider/src/data-service.ts +++ b/packages/data-provider/src/data-service.ts @@ -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 => { +export const createAgent = ({ ...data }: ag.AgentCreateParams): Promise => { return request.post(endpoints.agents({}), data); }; -export const getAgentById = ({ agent_id }: { agent_id: string }): Promise => { +export const getAgentById = ({ agent_id }: { agent_id: string }): Promise => { return request.get( endpoints.agents({ path: agent_id, @@ -679,7 +680,7 @@ export const getAgentById = ({ agent_id }: { agent_id: string }): Promise => { +export const getExpandedAgentById = ({ agent_id }: { agent_id: string }): Promise => { 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 => { +export const getAgentVersions = ({ agent_id }: { agent_id: string }): Promise => { return request.get( endpoints.agents({ path: `${agent_id}/versions`, @@ -700,8 +701,8 @@ export const updateAgent = ({ data, }: { agent_id: string; - data: a.AgentUpdateParams; -}): Promise => { + data: ag.AgentUpdateParams; +}): Promise => { 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 => { ); }; -export const listAgents = (params: a.AgentListParams): Promise => { +export const listAgents = (params: ag.AgentListParams): Promise => { return request.get( endpoints.agents({ options: params, @@ -742,7 +743,7 @@ export const revertAgentVersion = ({ }: { agent_id: string; version_index: number; -}): Promise => request.post(endpoints.revertAgentVersion(agent_id), { version_index }); +}): Promise => 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 => { +}): Promise => { 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 => { +export const uploadAgentAvatar = (data: m.AgentAvatarVariables): Promise => { 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 => request.deleteWithOptions(endpoints.files(), { data: payload, diff --git a/packages/data-provider/src/index.ts b/packages/data-provider/src/index.ts index 2730533788..bcc234688b 100644 --- a/packages/data-provider/src/index.ts +++ b/packages/data-provider/src/index.ts @@ -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'; diff --git a/packages/data-provider/src/messages.spec.ts b/packages/data-provider/src/messages.spec.ts index 600478fdc0..d453f6b856 100644 --- a/packages/data-provider/src/messages.spec.ts +++ b/packages/data-provider/src/messages.spec.ts @@ -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'; diff --git a/packages/data-provider/src/messages.ts b/packages/data-provider/src/messages.ts index df952ba58a..b424f64890 100644 --- a/packages/data-provider/src/messages.ts +++ b/packages/data-provider/src/messages.ts @@ -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'; diff --git a/packages/data-provider/src/models.ts b/packages/data-provider/src/models.ts index de7fb5d333..4d14e25773 100644 --- a/packages/data-provider/src/models.ts +++ b/packages/data-provider/src/models.ts @@ -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, diff --git a/packages/data-provider/src/parsers.ts b/packages/data-provider/src/parsers.ts index 3de6365db7..9f49538d26 100644 --- a/packages/data-provider/src/parsers.ts +++ b/packages/data-provider/src/parsers.ts @@ -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 { diff --git a/packages/data-provider/src/resolve-llm-delivery-path.ts b/packages/data-provider/src/resolve-llm-delivery-path.ts index 09726f74c2..25fe9ab48f 100644 --- a/packages/data-provider/src/resolve-llm-delivery-path.ts +++ b/packages/data-provider/src/resolve-llm-delivery-path.ts @@ -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 diff --git a/packages/data-provider/src/schemas.ts b/packages/data-provider/src/schemas.ts index 7b13105363..527f26ba95 100644 --- a/packages/data-provider/src/schemas.ts +++ b/packages/data-provider/src/schemas.ts @@ -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(); diff --git a/packages/data-provider/src/types.ts b/packages/data-provider/src/types.ts index e619f933c0..aa94eba897 100644 --- a/packages/data-provider/src/types.ts +++ b/packages/data-provider/src/types.ts @@ -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'; diff --git a/packages/data-provider/src/types/agents.ts b/packages/data-provider/src/types/agents.ts index e95baff743..65c39d9f8b 100644 --- a/packages/data-provider/src/types/agents.ts +++ b/packages/data-provider/src/types/agents.ts @@ -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; + /** + * A list of files already fetched. + */ + files?: Array; +} + +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; +} +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 = 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; + metadata?: Record; + 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; + +export type AgentCreateParams = { + git_identity?: AgentGitIdentity; + name?: string | null; + description?: string | null; + avatar?: AgentAvatar | null; + file_ids?: string[]; + instructions?: string | null; + tools?: Array; + 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; + 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'; +}; diff --git a/packages/data-provider/src/types/assistants.ts b/packages/data-provider/src/types/assistants.ts index 38b60f4e0c..8b33fb8fb7 100644 --- a/packages/data-provider/src/types/assistants.ts +++ b/packages/data-provider/src/types/assistants.ts @@ -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; - 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; -} - -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; -} - /* 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; - /** - * A list of files already fetched. - */ - files?: Array; -} - -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; -} -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; - -/** - * 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 = 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; - metadata?: Record; - 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; - -export type AgentCreateParams = { - git_identity?: AgentGitIdentity; - name?: string | null; - description?: string | null; - avatar?: AgentAvatar | null; - file_ids?: string[]; - instructions?: string | null; - tools?: Array; - 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; - 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>; // 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; // 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; -}; - -// 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; - 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; - -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[]; - /** 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', diff --git a/packages/data-provider/src/types/content.ts b/packages/data-provider/src/types/content.ts new file mode 100644 index 0000000000..bdeeac8c7e --- /dev/null +++ b/packages/data-provider/src/types/content.ts @@ -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>; // 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; // 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; +}; + +// 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; + 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; + +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[]; + /** 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_'; diff --git a/packages/data-provider/src/types/files.ts b/packages/data-provider/src/types/files.ts index e7a80d81d6..2651cc6ddb 100644 --- a/packages/data-provider/src/types/files.ts +++ b/packages/data-provider/src/types/files.ts @@ -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', diff --git a/packages/data-provider/src/types/mutations.ts b/packages/data-provider/src/types/mutations.ts index 414d479b5c..a99e5a45e7 100644 --- a/packages/data-provider/src/types/mutations.ts +++ b/packages/data-provider/src/types/mutations.ts @@ -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'; diff --git a/packages/data-provider/src/types/tools.ts b/packages/data-provider/src/types/tools.ts new file mode 100644 index 0000000000..26db147d12 --- /dev/null +++ b/packages/data-provider/src/types/tools.ts @@ -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; + 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; +} + +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; +} + +/** + * 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; + +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; +} diff --git a/packages/data-provider/src/upload.ts b/packages/data-provider/src/upload.ts index 0edb86d5df..797a04b027 100644 --- a/packages/data-provider/src/upload.ts +++ b/packages/data-provider/src/upload.ts @@ -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';