@truefoundry/assistant-ui-runtime 0.1.5 → 0.1.6

package/dist/plugins/truefoundry-agent-server-adapter/index.d.ts

@@ -0,0 +1,162 @@
+import { AgentSessionClient } from 'truefoundry-gateway-sdk/agents';
+import { PrivateAgentSessionClient } from 'truefoundry-gateway-sdk/agents/private';
+import { A as AgentSpec, C as CreateSessionRequest, L as ListSessionsParams, S as Session, T as Turn, a as TurnState, b as AgentChatServer, U as UpdateSessionRequest } from '../../types-BfiFf8O1.js';
+import { TruefoundryGatewayApi } from 'truefoundry-gateway-sdk';
+
+/**
+ * TrueFoundry-specific type extensions over the runtime's generic bases.
+ *
+ * The runtime defines minimal bases (SkillMount = {id,name}, McpServerMount =
+ * {id,name}, AgentSpec.config = unknown, etc.) that hosts extend via generics.
+ *
+ * This file builds the concrete TrueFoundry types by:
+ *  - Importing the runtime's AgentSpec as the base to extend.
+ *  - Importing concrete sub-types from the gateway SDK namespace rather than
+ *    re-defining them — they're purely gateway concepts.
+ *  - Composing a TfyAgentSpec that satisfies both the runtime's
+ *    `TSpec extends AgentSpec` constraint and the gateway SDK's AgentSpec shape.
+ */
+
+type TfyRuntimeConfig = TruefoundryGatewayApi.RuntimeConfig;
+type TfyResponseFormat = TruefoundryGatewayApi.ResponseFormat;
+type TfyModelParams = TruefoundryGatewayApi.ModelParams;
+type TfySubject = TruefoundryGatewayApi.Subject;
+type ToolsSelectorTag = "@all" | "@read-only";
+type RequireApprovalToolsSelectorTag = "@all" | "@write" | "@destructive";
+type ToolsSelectorItem = ToolsSelectorTag | string;
+type RequireApprovalToolSelectorItem = RequireApprovalToolsSelectorTag | string;
+type RuntimeSkillMount = NonNullable<NonNullable<AgentSpec["skills"]>[number]>;
+type RuntimeMcpServerMount = NonNullable<NonNullable<AgentSpec["mcpServers"]>[number]>;
+type TfySkillMount = RuntimeSkillMount & TruefoundryGatewayApi.SkillMount;
+type TfyMcpServerMount = RuntimeMcpServerMount & TruefoundryGatewayApi.McpServer;
+interface TfyAgentSpec extends AgentSpec {
+    model: TruefoundryGatewayApi.Model;
+    skills?: TfySkillMount[];
+    mcpServers?: TfyMcpServerMount[];
+    config?: TruefoundryGatewayApi.RuntimeConfig;
+    responseFormat?: TruefoundryGatewayApi.ResponseFormat;
+    messages?: TruefoundryGatewayApi.AgentSpecUserMessage[];
+}
+type TfyTurnCancelledReason = TruefoundryGatewayApi.TurnStateCancelledReason;
+type TfyTurnStateDoneOutput = TruefoundryGatewayApi.TurnStateDoneOutput;
+type RuntimeTurnStateDone = Extract<TurnState, {
+    status: "done";
+}>;
+type RuntimeTurnStateCancelled = Extract<TurnState, {
+    status: "cancelled";
+}>;
+/**
+ * The runtime types `output` as `unknown` and `reason` as bare `string`. The
+ * gateway sends a model message and one of four reasons — `cancelled-for-next-turn`
+ * in particular is routine and should not render like a failure.
+ */
+type TfyTurnState = Exclude<TurnState, {
+    status: "done" | "cancelled";
+}> | (Omit<RuntimeTurnStateDone, "output"> & {
+    output?: TfyTurnStateDoneOutput;
+}) | (Omit<RuntimeTurnStateCancelled, "reason"> & {
+    reason: TfyTurnCancelledReason;
+});
+interface TfyTurn extends Turn {
+    state: TfyTurnState;
+    createdBySubject: TfySubject;
+}
+interface TfySession<TSpec extends TfyAgentSpec = TfyAgentSpec> extends Session<TSpec> {
+    createdBySubject: TfySubject;
+}
+interface TfyCreateSessionRequest<TSpec extends TfyAgentSpec = TfyAgentSpec> extends CreateSessionRequest<TSpec> {
+    /** Sent as `x-tfy-metadata`, persisted server-side as `request_metadata`. */
+    tfyMetadata?: string;
+}
+interface TfyListSessionsParams extends ListSessionsParams {
+    /** Inclusive upper bound on `createdAt` (ISO-8601). */
+    endTimestamp?: string;
+}
+type TfyToolInfo = TruefoundryGatewayApi.ToolInfo;
+type TfySystemToolInfo = TruefoundryGatewayApi.TrueFoundrySystemToolInfo;
+type TfyMcpToolInfo = TruefoundryGatewayApi.McpToolInfo;
+type TfyModelMessageUsage = TruefoundryGatewayApi.ModelMessageUsage;
+type TfyFinishReason = TruefoundryGatewayApi.FinishReason;
+type TfyThreadState = TruefoundryGatewayApi.ThreadState;
+type TfyMcpServerInitInfo = TruefoundryGatewayApi.McpServerInitInfo;
+
+/**
+ * Point-of-use narrowing for the event half of the gateway protocol.
+ *
+ * `AgentChatServer` hardcodes the runtime's event types on listEvents,
+ * listTurnEvents, subscribeToTurn and prepareAndExecuteTurn — there is no
+ * generic to override them from here. So instead of typing those channels,
+ * hosts call these guards on the values they receive.
+ *
+ * They validate rather than cast: this data comes off the network, and the
+ * runtime types the relevant fields as `unknown` precisely because nothing
+ * has checked them yet.
+ */
+
+/**
+ * Identifies built-in tools such as `ask_user_question` and `create_sub_agent`.
+ * Note `toolInfo` is legitimately absent on streamed deltas, so callers must
+ * keep their `function.name` fallback rather than treating absence as an error.
+ */
+declare function isTfySystemToolInfo(toolInfo: unknown): toolInfo is TfySystemToolInfo;
+/** Carries `serverId` / `serverName`, so the UI can attribute a call to its MCP server. */
+declare function isTfyMcpToolInfo(toolInfo: unknown): toolInfo is TfyMcpToolInfo;
+declare function isTfyToolInfo(toolInfo: unknown): toolInfo is TfyToolInfo;
+/**
+ * Token usage including the TrueFoundry-specific `inputTokensBreakdown`, which
+ * attributes input tokens across harness, skills, instructions, tool
+ * definitions and messages.
+ */
+declare function getTfyUsage(source: {
+    usage?: unknown;
+} | null | undefined): TfyModelMessageUsage | undefined;
+/**
+ * Completion state of a sub-agent thread. The runtime types `thread.done`'s
+ * `state` as `unknown`, so a sub-agent that errored is otherwise
+ * indistinguishable from one that succeeded.
+ */
+declare function getTfyThreadState(event: {
+    state?: unknown;
+} | null | undefined): TfyThreadState | undefined;
+/**
+ * Servers from an `mcp.initialize` event, including each one's `transportType`.
+ * The runtime models this event with an index signature, so the array is
+ * `unknown` until checked.
+ */
+declare function getTfyMcpInitServers(event: {
+    mcpServers?: unknown;
+} | null | undefined): TfyMcpServerInitInfo[] | undefined;
+
+type CreateTrueFoundryChatServerOptions = {
+    apiKey: string;
+    baseUrl: string;
+    /** Optional override — otherwise constructed from apiKey/baseUrl. */
+    client?: AgentSessionClient;
+    privateClient?: PrivateAgentSessionClient;
+    deleteSession?: (req: {
+        sessionId: string;
+    }) => Promise<void>;
+};
+/**
+ * Only the spec is generic. Session/Turn/list-params are the concrete Tfy*
+ * types because the adapter builds them as fixed object literals — a generic
+ * there would type fields that nothing ever populates. The spec is safe: the
+ * gateway SDK serializes with `unrecognizedObjectKeys: "passthrough"`, so
+ * host-added spec fields survive the round trip.
+ */
+type TrueFoundryChatServer<TSpec extends TfyAgentSpec = TfyAgentSpec> = AgentChatServer<TSpec, TfySession<TSpec>, TfyCreateSessionRequest<TSpec>, TfyListSessionsParams, UpdateSessionRequest<TSpec>, TfyTurn> & {
+    /** Escape hatch for hosts that still need raw gateway clients. */
+    getGatewayClients(): {
+        client: AgentSessionClient;
+        privateClient: PrivateAgentSessionClient;
+    };
+};
+/**
+ * Wraps TrueFoundry gateway clients into a flat `AgentChatServer`.
+ * Named vs draft routing is fully internal — an in-memory session-type cache
+ * (populated by createSession/listSessions) determines which gateway client
+ * to call. No try/catch fallback, no double network calls.
+ */
+declare function createTrueFoundryChatServer<TSpec extends TfyAgentSpec = TfyAgentSpec>(opts: CreateTrueFoundryChatServerOptions): TrueFoundryChatServer<TSpec>;
+
+export { type CreateTrueFoundryChatServerOptions, type RequireApprovalToolSelectorItem, type RequireApprovalToolsSelectorTag, type TfyAgentSpec, type TfyCreateSessionRequest, type TfyFinishReason, type TfyListSessionsParams, type TfyMcpServerInitInfo, type TfyMcpServerMount, type TfyMcpToolInfo, type TfyModelMessageUsage, type TfyModelParams, type TfyResponseFormat, type TfyRuntimeConfig, type TfySession, type TfySkillMount, type TfySubject, type TfySystemToolInfo, type TfyThreadState, type TfyToolInfo, type TfyTurn, type TfyTurnCancelledReason, type TfyTurnState, type TfyTurnStateDoneOutput, type ToolsSelectorItem, type ToolsSelectorTag, type TrueFoundryChatServer, createTrueFoundryChatServer, getTfyMcpInitServers, getTfyThreadState, getTfyUsage, isTfyMcpToolInfo, isTfySystemToolInfo, isTfyToolInfo };

package/dist/plugins/truefoundry-agent-server-adapter/index.js

@@ -0,0 +1,19 @@
+import {
+  createTrueFoundryChatServer,
+  getTfyMcpInitServers,
+  getTfyThreadState,
+  getTfyUsage,
+  isTfyMcpToolInfo,
+  isTfySystemToolInfo,
+  isTfyToolInfo
+} from "../../chunk-Q2SHKMLM.js";
+export {
+  createTrueFoundryChatServer,
+  getTfyMcpInitServers,
+  getTfyThreadState,
+  getTfyUsage,
+  isTfyMcpToolInfo,
+  isTfySystemToolInfo,
+  isTfyToolInfo
+};
+//# sourceMappingURL=index.js.map

package/dist/plugins/truefoundry-agent-server-adapter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/server/index.d.ts

@@ -0,0 +1,17 @@
+import { r as TurnStreamingEvent, D as DeltaEvents, c as TurnEvent } from '../types-BfiFf8O1.js';
+export { t as ActionRequiredEvent, h as AgentBuilderServer, b as AgentChatServer, u as AgentInfo, v as AgentParent, w as AgentSelectorEntry, A as AgentSpec, x as ApprovalDecision, y as ChunkDeltaToolCall, z as ConnectorSelectorEntry, C as CreateSessionRequest, i as ListResult, B as ListSessionsOrder, L as ListSessionsParams, M as McpAuthRequiredEvent, E as McpInitializeEvent, F as McpServerAuthInfo, G as McpServerMount, H as Model, I as ModelMessageContentPart, J as ModelMessageDeltaEvent, j as ModelMessageEvent, K as ModelParams, N as ModelSelectorEntry, O as PageParams, P as PreviousTurnIdInput, k as SandboxCreatedEvent, Q as SearchAgentSelectorParams, S as Session, l as SessionEventItem, R as SkillMount, V as SkillSelectorEntry, d as ThreadCreatedEvent, W as ThreadDoneEvent, m as ToolApprovalRequiredEvent, n as ToolCall, X as ToolCallFunction, Y as ToolCallRef, Z as ToolInfo, _ as ToolResponseEvent, o as ToolResponseRequiredEvent, T as Turn, $ as TurnCreatedEvent, a0 as TurnDoneEvent, g as TurnInputItem, a as TurnState, a1 as TurnStateCancelled, p as TurnStateDone, a2 as TurnStateError, a3 as TurnStateRunning, q as TurnStreamData, U as UpdateSessionRequest, s as UserMessage, a4 as UserMessageContent, f as UserToolApprovalEvent, e as UserToolResponseEvent } from '../types-BfiFf8O1.js';
+
+/**
+ * Local implementations of streaming delta helpers.
+ * Formerly imported from truefoundry-gateway-sdk/agents.
+ */
+
+/** True for `.delta` streaming events. */
+declare function isEventDelta(event: TurnStreamingEvent): event is DeltaEvents;
+/**
+ * Merge `delta` into `base` in place (same `id` required).
+ * Currently handles `model.message.delta` → `model.message`.
+ */
+declare function mergeEventDelta(base: TurnEvent, delta: DeltaEvents): void;
+
+export { DeltaEvents, TurnEvent, TurnStreamingEvent, isEventDelta, mergeEventDelta };

package/dist/server/index.js

@@ -0,0 +1,9 @@
+import {
+  isEventDelta,
+  mergeEventDelta
+} from "../chunk-3A2EPLQG.js";
+export {
+  isEventDelta,
+  mergeEventDelta
+};
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-BfiFf8O1.d.ts

@@ -0,0 +1,468 @@
+/**
+ * Runtime-owned turn/stream event protocol.
+ *
+ * Hosts must emit events matching these shapes. The TFY adapter maps
+ * truefoundry-gateway-sdk events 1:1 onto these types.
+ */
+
+interface ToolCallFunction {
+    name: string;
+    arguments: string;
+}
+type ToolInfo = {
+    type: "truefoundry-system";
+    name: string;
+} | {
+    type: "mcp";
+    serverId: string;
+    serverName: string;
+    name: string;
+} | {
+    type: string;
+    name?: string;
+    [key: string]: unknown;
+};
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: ToolCallFunction;
+    toolInfo?: ToolInfo;
+    providerSpecificFields?: Record<string, unknown>;
+}
+/** Ref used by approval/response-required events. */
+interface ToolCallRef {
+    id: string;
+    sourceEventId: string;
+}
+interface ChunkDeltaToolCall {
+    index: number;
+    id?: string;
+    type?: "function";
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+    toolInfo?: ToolInfo;
+    providerSpecificFields?: Record<string, unknown>;
+}
+type ModelMessageContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "refusal";
+    refusal: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+};
+interface ModelMessageEvent {
+    type: "model.message";
+    id: string;
+    threadId: string;
+    content?: string | ModelMessageContentPart[] | null;
+    name?: string;
+    refusal?: string | null;
+    reasoningContent?: string;
+    toolCalls?: ToolCall[];
+    finishReason?: string | null;
+    createdAt: string;
+    usage?: unknown;
+}
+interface ModelMessageDeltaEvent {
+    type: "model.message.delta";
+    id: string;
+    threadId: string;
+    content?: string | null;
+    refusal?: string | null;
+    reasoningContent?: string;
+    toolCalls?: ChunkDeltaToolCall[];
+    finishReason?: string | null;
+    createdAt?: string;
+    usage?: unknown;
+    /** Extended content-block deltas (image streaming). */
+    contentBlocks?: Array<{
+        index: number;
+        delta: {
+            type: "text";
+            text?: string;
+        } | {
+            type: "image_url";
+            image_url?: {
+                url?: string;
+            };
+        };
+    }>;
+    content_blocks?: Array<{
+        index: number;
+        delta: {
+            type: "text";
+            text?: string;
+        } | {
+            type: "image_url";
+            image_url?: {
+                url?: string;
+            };
+        };
+    }>;
+}
+interface ToolResponseEvent {
+    type: "tool.response";
+    id: string;
+    threadId: string;
+    toolCallId: string;
+    content: string;
+    createdAt: string;
+}
+interface ToolApprovalRequiredEvent {
+    type: "tool.approval_required";
+    id: string;
+    createdAt: string;
+    threadId: string;
+    toolCalls: ToolCallRef[];
+}
+interface ToolResponseRequiredEvent {
+    type: "tool.response_required";
+    id: string;
+    createdAt: string;
+    threadId: string;
+    toolCalls: ToolCallRef[];
+}
+interface AgentInfo {
+    type?: string;
+    name: string;
+    input: string;
+    model?: string;
+}
+interface AgentParent {
+    threadId: string;
+    toolCallId: string;
+}
+interface ThreadCreatedEvent {
+    type: "thread.created";
+    id: string;
+    threadId: string;
+    title: string;
+    agentInfo: AgentInfo;
+    parent: AgentParent;
+    createdAt: string;
+}
+interface ThreadDoneEvent {
+    type: "thread.done";
+    id: string;
+    threadId: string;
+    title?: string;
+    createdAt: string;
+    state?: unknown;
+}
+interface McpServerAuthInfo {
+    id: string;
+    name: string;
+    authUrl: string;
+}
+interface McpAuthRequiredEvent {
+    type: "mcp.auth_required";
+    id: string;
+    createdAt: string;
+    threadId?: string | null;
+    mcpServers: McpServerAuthInfo[];
+}
+interface SandboxCreatedEvent {
+    type: "sandbox.created";
+    id: string;
+    createdAt: string;
+    sandboxId: string;
+    threadId: string | null;
+}
+interface McpInitializeEvent {
+    type: "mcp.initialize";
+    id: string;
+    createdAt: string;
+    threadId: string | null;
+    [key: string]: unknown;
+}
+interface TurnCreatedEvent {
+    type: "turn.created";
+    id: string;
+    turnId: string;
+    previousTurnId?: string | null;
+    input?: TurnInputItem[];
+    state?: {
+        status: "running";
+    };
+    createdAt: string;
+    threadId?: string | null;
+}
+interface TurnDoneEvent {
+    type: "turn.done";
+    id: string;
+    state: Exclude<TurnState, {
+        status: "running";
+    }>;
+    createdAt: string;
+    threadId?: string | null;
+}
+/** Events stored in fold buckets (non-delta, non-turn-lifecycle). */
+type TurnEvent = ModelMessageEvent | ToolResponseEvent | ThreadCreatedEvent | ThreadDoneEvent | McpAuthRequiredEvent | McpInitializeEvent | SandboxCreatedEvent | ToolApprovalRequiredEvent | ToolResponseRequiredEvent;
+/** Full streaming event union (includes deltas + turn lifecycle). */
+type TurnStreamingEvent = TurnEvent | ModelMessageDeltaEvent | TurnCreatedEvent | TurnDoneEvent;
+type ActionRequiredEvent = ToolApprovalRequiredEvent | ToolResponseRequiredEvent | McpAuthRequiredEvent;
+interface TurnStreamData<TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent> {
+    sequenceNumber: number;
+    event: TStreamEvent;
+}
+/** Session-level event item from `listEvents`. */
+interface SessionEventItem {
+    turnId: string;
+    event: TurnCreatedEvent | TurnDoneEvent | TurnEvent;
+}
+type DeltaEvents = ModelMessageDeltaEvent;
+
+/**
+ * FE-owned AgentUIServer contract.
+ *
+ * Rule: only methods/fields the runtime or UI invokes.
+ * Hosts extend via `T extends Base` for system-specific extras.
+ * No dependency on truefoundry-gateway-sdk.
+ */
+
+/** Model selector row. Host extends for apiModel, modelId, pricing, etc. */
+interface ModelSelectorEntry {
+    name: string;
+    provider: string;
+}
+/** Skill selector row. Host extends for fqn, preload, etc. */
+interface SkillSelectorEntry {
+    id: string;
+    name: string;
+    description?: string;
+}
+/** MCP connector selector row. Host extends for type, enableTools, url, etc. */
+interface ConnectorSelectorEntry {
+    id: string;
+    name: string;
+    description?: string;
+}
+/** Agent selector row — UI shows name only. Host extends for metadata. */
+interface AgentSelectorEntry {
+    name: string;
+}
+type SearchAgentSelectorParams = {
+    query?: string;
+    limit?: number;
+    offset?: number;
+};
+/**
+ * Mounts written to AgentSpec.skills[] / AgentSpec.mcpServers[].
+ *
+ * These are opaque to the runtime — it stores and forwards them but never reads
+ * a field, and the backend owns the shape (the gateway identifies a skill by
+ * `fqn`, with no `id` or `name` anywhere). So the base constrains only that a
+ * mount is an object; hosts intersect their concrete mount type over it, as
+ * `TfySkillMount` / `TfyMcpServerMount` do in the gateway adapter.
+ *
+ * Naming a field here would not just be unread, it would be wrong: a base with
+ * required fields rejects the backend's own payloads, and one with only optional
+ * fields is a weak type, which TypeScript rejects for a source that shares no
+ * property with it — the gateway's registry skill shares none.
+ */
+type SkillMount = object;
+type McpServerMount = object;
+interface ModelParams {
+    maxTokens?: number;
+    reasoningEffort?: string;
+}
+interface Model {
+    name: string;
+    params?: ModelParams;
+}
+/**
+ * SDK-owned agent definition — fields the FE reads/writes.
+ * Host adds additional fields via `TSpec extends AgentSpec`.
+ */
+interface AgentSpec {
+    model: Model;
+    skills?: SkillMount[];
+    mcpServers?: McpServerMount[];
+    instructions?: string;
+    messages?: unknown[];
+    variables?: Record<string, string>;
+    responseFormat?: unknown;
+    config?: unknown;
+}
+interface Session<TSpec extends AgentSpec = AgentSpec> {
+    id: string;
+    title?: string | null;
+    agentName?: string | null;
+    agentSpec?: TSpec;
+    /** true → mutable builder + updateSession(spec) allowed. */
+    isMutable: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateSessionRequest<TSpec extends AgentSpec = AgentSpec> {
+    agentName?: string;
+    agentSpec?: TSpec;
+    title?: string;
+}
+interface UpdateSessionRequest<TSpec extends AgentSpec = AgentSpec> {
+    sessionId: string;
+    agentSpec?: TSpec;
+    title?: string;
+}
+interface ListResult<T> {
+    data: T[];
+    nextPageToken?: string;
+}
+type ListSessionsOrder = "asc" | "desc";
+type PageParams = {
+    limit?: number;
+    order?: ListSessionsOrder;
+    pageToken?: string;
+};
+interface ListSessionsParams extends PageParams {
+    agentName?: string;
+    /** Host-specific filter (e.g. TFY startTimestamp). */
+    startTimestamp?: string;
+}
+type PreviousTurnIdInput = "auto" | string;
+type UserMessageContent = string | Array<{
+    type: "text";
+    text: string;
+} | {
+    type: "file";
+    name: string;
+    data: string;
+}>;
+interface UserMessage {
+    type: "user.message";
+    content: UserMessageContent;
+}
+type ApprovalDecision = {
+    status: "allow";
+} | {
+    status: "deny";
+    reason?: string;
+};
+interface UserToolApprovalEvent {
+    type: "user.tool_approval";
+    threadId: string;
+    toolCallId: string;
+    approval: ApprovalDecision;
+}
+interface UserToolResponseEvent {
+    type: "user.tool_response";
+    threadId: string;
+    toolCallId: string;
+    content: string;
+}
+type TurnInputItem = UserMessage | UserToolApprovalEvent | UserToolResponseEvent;
+type TurnStateRunning = {
+    status: "running";
+};
+type TurnStateDone = {
+    status: "done";
+    output?: unknown;
+    requiredActions?: ActionRequiredEvent[];
+    completedAt: string;
+};
+type TurnStateCancelled = {
+    status: "cancelled";
+    reason: string;
+    completedAt: string;
+};
+type TurnStateError = {
+    status: "error";
+    message: string;
+    completedAt: string;
+};
+type TurnState = TurnStateRunning | TurnStateDone | TurnStateCancelled | TurnStateError;
+/** Plain turn DTO — no methods. */
+interface Turn {
+    id: string;
+    sessionId: string;
+    previousTurnId?: string | null;
+    input?: TurnInputItem[];
+    state: TurnState;
+    createdAt: string;
+}
+/**
+ * Chat / session port — the runtime calls these.
+ *
+ * All session ops are flat (sessionId param). No gateway client dependency.
+ * `createTrueFoundryServer` is one possible implementation (TFY adapter).
+ */
+interface AgentChatServer<TSpec extends AgentSpec = AgentSpec, TSession extends Session<TSpec> = Session<TSpec>, TCreate extends CreateSessionRequest<TSpec> = CreateSessionRequest<TSpec>, TList extends ListSessionsParams = ListSessionsParams, TUpdate extends UpdateSessionRequest<TSpec> = UpdateSessionRequest<TSpec>, TTurn extends Turn = Turn> {
+    createSession(req: TCreate): Promise<TSession>;
+    listSessions(req?: TList): Promise<ListResult<TSession>>;
+    getSession(req: {
+        sessionId: string;
+    }): Promise<TSession>;
+    updateSession(req: TUpdate): Promise<TSession>;
+    prepareAndExecuteTurn(req: {
+        sessionId: string;
+        input?: TurnInputItem[];
+        previousTurnId?: PreviousTurnIdInput;
+        abortSignal?: AbortSignal;
+        headers?: Record<string, string>;
+    }): AsyncIterable<TurnStreamData>;
+    cancelSession(req: {
+        sessionId: string;
+    }): Promise<void>;
+    deleteSession?(req: {
+        sessionId: string;
+    }): Promise<void>;
+    listTurns(req: {
+        sessionId: string;
+        limit?: number;
+        pageToken?: string;
+        order?: ListSessionsOrder;
+    }): Promise<ListResult<TTurn>>;
+    getTurn(req: {
+        sessionId: string;
+        turnId: string;
+    }): Promise<TTurn>;
+    listEvents(req: {
+        sessionId: string;
+        pageToken?: string;
+        lastTurnId?: string;
+        limit?: number;
+    }): Promise<ListResult<SessionEventItem>>;
+    /** Optional per-turn event listing (hydrate in-flight turn content). */
+    listTurnEvents?(req: {
+        sessionId: string;
+        turnId: string;
+        limit?: number;
+        pageToken?: string;
+        order?: ListSessionsOrder;
+    }): Promise<ListResult<TurnEvent>>;
+    subscribeToTurn?(req: {
+        sessionId: string;
+        turnId: string;
+        afterSequenceNumber?: number;
+        abortSignal?: AbortSignal;
+    }): AsyncIterable<TurnStreamData>;
+    downloadSandboxFile?(sandboxId: string, req: {
+        path: string;
+    }): Promise<Blob>;
+}
+/**
+ * Builder catalog + persist port — atoms call these.
+ * Passed separately from the runtime's chat server.
+ */
+interface AgentBuilderServer<TSpec extends AgentSpec = AgentSpec, TModel extends ModelSelectorEntry = ModelSelectorEntry, TSkill extends SkillSelectorEntry = SkillSelectorEntry, TMcp extends ConnectorSelectorEntry = ConnectorSelectorEntry, TAgent extends AgentSelectorEntry = AgentSelectorEntry, TSave = unknown> {
+    getModels(): Promise<TModel[]>;
+    getSkills(): Promise<TSkill[]>;
+    getMcp(): Promise<TMcp[]>;
+    searchAgents(req?: SearchAgentSelectorParams): Promise<TAgent[]>;
+    saveAgent(req: {
+        agentName: string;
+        agentSpec: TSpec;
+    }): Promise<TSave>;
+    deleteAgent?(req: {
+        agentName: string;
+    }): Promise<void>;
+}
+
+export type { TurnCreatedEvent as $, AgentSpec as A, ListSessionsOrder as B, CreateSessionRequest as C, DeltaEvents as D, McpInitializeEvent as E, McpServerAuthInfo as F, McpServerMount as G, Model as H, ModelMessageContentPart as I, ModelMessageDeltaEvent as J, ModelParams as K, ListSessionsParams as L, McpAuthRequiredEvent as M, ModelSelectorEntry as N, PageParams as O, PreviousTurnIdInput as P, SearchAgentSelectorParams as Q, SkillMount as R, Session as S, Turn as T, UpdateSessionRequest as U, SkillSelectorEntry as V, ThreadDoneEvent as W, ToolCallFunction as X, ToolCallRef as Y, ToolInfo as Z, ToolResponseEvent as _, TurnState as a, TurnDoneEvent as a0, TurnStateCancelled as a1, TurnStateError as a2, TurnStateRunning as a3, UserMessageContent as a4, AgentChatServer as b, TurnEvent as c, ThreadCreatedEvent as d, UserToolResponseEvent as e, UserToolApprovalEvent as f, TurnInputItem as g, AgentBuilderServer as h, ListResult as i, ModelMessageEvent as j, SandboxCreatedEvent as k, SessionEventItem as l, ToolApprovalRequiredEvent as m, ToolCall as n, ToolResponseRequiredEvent as o, TurnStateDone as p, TurnStreamData as q, TurnStreamingEvent as r, UserMessage as s, ActionRequiredEvent as t, AgentInfo as u, AgentParent as v, AgentSelectorEntry as w, ApprovalDecision as x, ChunkDeltaToolCall as y, ConnectorSelectorEntry as z };