@opengeni/sdk 0.27.0 → 0.29.0

package/README.md

@@ -21,6 +21,8 @@ const client = new OpenGeniClient({
 const session = await client.createSession(workspaceId, {
   initialMessage: "Investigate the failing deploy on staging",
   resources: [{ kind: "repository", uri: "https://github.com/acme/app.git", ref: "main" }],
+  // Exact model-visible first-party surface; permissions remain independent.
+  firstPartyMcpTools: ["set_session_title"],
 });
 
 for await (const event of client.streamEvents(workspaceId, session.id)) {
@@ -30,6 +32,32 @@ for await (const event of client.streamEvents(workspaceId, session.id)) {
 }
 ```
 
+Omit `firstPartyMcpTools` for the minimal self-management default. An explicit
+`[]` exposes no broad first-party tools; attached resources and separately
+selected `files`/`docs` MCP servers are unaffected.
+
+## MCP tool output normalization
+
+MCP transports and event stores can represent the same tool result as a direct
+object, JSON text, a text content block, or nested `result`,
+`structuredContent`, and `content` envelopes. Use the shared zero-dependency
+normalizer when an embedding host needs one stable interpretation:
+
+```ts
+import { normalizeMcpOutput } from "@opengeni/sdk";
+
+const normalized = normalizeMcpOutput(toolOutput);
+
+normalized.value; // canonical machine-readable value
+normalized.text; // presentation text
+normalized.isError; // preserved across recognized nested envelopes
+normalized.raw; // original evidence
+```
+
+Malformed text and unknown objects pass through without throwing. Envelope
+recognition is deliberately conservative: an ordinary domain object is not
+unwrapped merely because it has a field named `result`.
+
 ## Error handling
 
 Non-2xx responses throw `OpenGeniApiError` with stable transport metadata:
@@ -194,14 +222,25 @@ version; the audited change takes effect on its next attempt:
 const session = await client.getSession(workspaceId, sessionId);
 const updated = await client.updateSessionToolPolicy(workspaceId, sessionId, {
   mode: "workspace_default",
-  expectedVersion: session.toolPolicyVersion ?? 1,
+  expectedVersion: session.toolPolicyVersion,
+});
+```
+
+To keep a fixed allow-list, replace both connected MCP servers and individual
+OpenGeni tools atomically:
+
+```ts
+await client.updateSessionToolPolicy(workspaceId, sessionId, {
+  mode: "explicit",
+  tools,
+  firstPartyMcpTools,
+  expectedVersion: session.toolPolicyVersion,
 });
 ```
 
-To keep a fixed MCP allow-list instead, use the backward-compatible explicit
-shape `{ tools, expectedVersion }`. `tool_search` discovers deferred MCP
-schemas; it is not public web search. Unsupported providers do not receive a
-cross-provider, MCP, or sandbox fallback.
+Follow-up Send and Steer requests inherit this session policy and cannot carry
+a private one-turn tool override. `tool_search` discovers deferred MCP schemas;
+it is not public web search.
 
 ## Goals
 

package/dist/index.d.ts

@@ -355,16 +355,16 @@ type ToolRef = {
     optional?: boolean | undefined;
 };
 type SessionToolPolicy = {
-    mode: "workspace_default" | "explicit" | "inherited" | "legacy";
+    mode: "workspace_default" | "explicit" | "inherited";
     inheritedFromSessionId: string | null;
 };
 type UpdateSessionToolPolicyRequest = {
     mode: "workspace_default";
     expectedVersion: number;
 } | {
-    /** Omitted for compatibility with the original explicit-only API. */
-    mode?: "explicit" | undefined;
+    mode: "explicit";
     tools: ToolRef[];
+    firstPartyMcpTools: FirstPartyMcpToolName[];
     expectedVersion: number;
 };
 type SessionEffectiveToolPolicy = {
@@ -548,8 +548,8 @@ type Session = {
     resources: ResourceRef[];
     skills: SessionSkill[];
     tools: ToolRef[];
-    toolPolicy?: SessionToolPolicy | undefined;
-    toolPolicyVersion?: number | undefined;
+    toolPolicy: SessionToolPolicy;
+    toolPolicyVersion: number;
     effectiveToolPolicy?: SessionEffectiveToolPolicy | undefined;
     metadata: Record<string, unknown>;
     /** Frozen creator fact; later turns carry their own independent initiator. */
@@ -567,6 +567,7 @@ type Session = {
     rigId: string | null;
     rigVersionId: string | null;
     firstPartyMcpPermissions: string[] | null;
+    firstPartyMcpTools: FirstPartyMcpToolName[];
     mcpServers: SessionMcpServerMetadata[];
     parentSessionId: string | null;
     /** Immutable server-authored nested-agent lineage and policy snapshot. */
@@ -725,7 +726,7 @@ type SessionHumanInputRequest = {
     createdAt: string;
     updatedAt: string;
 };
-declare const SESSION_EVENT_TYPES: readonly ["session.created", "session.event.envelope_omitted", "session.status.changed", "session.requiresAction", "session.humanInput.requested", "session.context.compaction.requested", "session.context.compacted", "session.context.compaction.skipped", "session.context.cleared", "user.message", "user.pause", "user.approvalDecision", "user.humanInputResponse", "turn.queued", "turn.started", "turn.completed", "turn.failed", "turn.cancelled", "turn.superseded", "turn.recovery.requested", "turn.capacity_waiting", "agent.message.delta", "agent.message.completed", "agent.reasoning.delta", "agent.toolCall.created", "agent.toolCall.output", "agent.model.request", "agent.model.usage", "tool.auth_needed", "credential.auth_needed", "agent.updated", "rig.setup.started", "rig.setup.completed", "rig.setup.skipped", "rig.setup.failed", "sandbox.operation.started", "sandbox.operation.completed", "sandbox.operation.failed", "sandbox.command.output.delta", "artifact.created", "goal.set", "goal.updated", "goal.completed", "goal.paused", "goal.resumed", "goal.cleared", "goal.continuation", "system.update.pending", "system.update.delivered", "session.control.paused", "session.control.resumed", "session.control.steer_requested", "workspace.inference.paused", "workspace.inference.resumed", "session.queue.changed", "session.queue.prompt.cancelled", "session.queue.history", "turn.event.rejected_late", "memory.saved", "memory.corrected", "stream.url.rotated", "stream.opened", "stream.closed", "stream.revoked", "recording.started", "recording.available", "recording.failed", "fs.changed", "git.changed", "terminal.pty.started", "terminal.pty.output.delta", "terminal.pty.exited", "session.title_set", "session.mcp.approval_policy.updated", "session.tool_policy.updated", "codex.account.switched", "codex.credential.selected", "codex.fleet.decision", "codex.capacity.waiting", "codex.capacity.resumed", "codex.capacity.superseded", "sandbox.box.created", "sandbox.box.lost", "sandbox.box.terminated", "sandbox.box.snapshot", "sandbox.env.drift", "session.route.reconciled", "workspace.revision.captured", "workspace.revision.degraded", "machine.op.failed", "machine.op.recovered", "machine.link.lost", "machine.link.restored", "machine.runner.restarted"];
+declare const SESSION_EVENT_TYPES: readonly ["session.created", "session.event.envelope_omitted", "session.status.changed", "session.requiresAction", "session.humanInput.requested", "session.context.compaction.requested", "session.context.compacted", "session.context.compaction.skipped", "session.context.cleared", "user.message", "user.pause", "user.approvalDecision", "user.humanInputResponse", "turn.queued", "turn.started", "turn.completed", "turn.failed", "turn.cancelled", "turn.superseded", "turn.recovery.requested", "turn.capacity_waiting", "agent.message.delta", "agent.message.completed", "agent.reasoning.delta", "agent.toolCall.created", "agent.toolCall.output", "agent.model.request", "agent.model.usage", "tool.auth_needed", "credential.auth_needed", "agent.updated", "rig.setup.started", "rig.setup.completed", "rig.setup.skipped", "rig.setup.failed", "sandbox.operation.started", "sandbox.operation.completed", "sandbox.operation.failed", "sandbox.command.output.delta", "artifact.created", "goal.set", "goal.updated", "goal.completed", "goal.paused", "goal.resumed", "goal.cleared", "goal.continuation", "system.update.pending", "system.update.delivered", "system.update.superseded", "system.update.cancelled", "system.update.settled", "session.control.paused", "session.control.resumed", "session.control.steer_requested", "workspace.inference.paused", "workspace.inference.resumed", "session.queue.changed", "session.queue.prompt.cancelled", "session.queue.history", "turn.event.rejected_late", "memory.saved", "memory.corrected", "stream.url.rotated", "stream.opened", "stream.closed", "stream.revoked", "recording.started", "recording.available", "recording.failed", "fs.changed", "git.changed", "terminal.pty.started", "terminal.pty.output.delta", "terminal.pty.exited", "session.title_set", "session.mcp.approval_policy.updated", "session.tool_policy.updated", "codex.account.switched", "codex.credential.selected", "codex.fleet.decision", "codex.capacity.waiting", "codex.capacity.resumed", "codex.capacity.superseded", "sandbox.box.created", "sandbox.box.lost", "sandbox.box.terminated", "sandbox.box.snapshot", "sandbox.env.drift", "session.route.reconciled", "workspace.revision.captured", "workspace.revision.degraded", "machine.op.failed", "machine.op.recovered", "machine.link.lost", "machine.link.restored", "machine.runner.restarted"];
 type KnownSessionEventType = (typeof SESSION_EVENT_TYPES)[number];
 /**
  * Event types the SDK knows about today, kept open so a newer OpenGeni server
@@ -1426,6 +1427,7 @@ type CreateSessionRequest = {
     expectedNewSessionDraftRevision?: number | undefined;
     maxNestedAgentDepth?: number | undefined;
     firstPartyMcpPermissions?: string[] | undefined;
+    firstPartyMcpTools?: FirstPartyMcpToolName[] | undefined;
     mcpServers?: SessionMcpServerInput[] | undefined;
     sandbox?: "shared" | "new" | {
         groupId: string;
@@ -1438,6 +1440,7 @@ type KnownPermission = (typeof KNOWN_PERMISSIONS)[number];
  * can introduce permissions without breaking older SDK consumers.
  */
 type Permission = KnownPermission | (string & {});
+type FirstPartyMcpToolName = "set_session_title" | "goal_set" | "goal_update" | "goal_complete" | "goal_pause" | "memory_search" | "memory_save" | "memory_correct" | "sandboxes_list" | "sandbox_attach" | "sandbox_swap" | "run_on" | "sandbox_provision" | "rig_list" | "rig_get" | "rig_propose_change" | "rig_verify" | "rig_promote" | "sessions_list" | "session_get" | "session_events" | "session_create" | "session_send_message" | "session_pause" | "session_resume" | "session_steer" | "set_other_session_title" | "variable_set_list" | "environment_list" | "variable_set_set_variable" | "environment_set_variable" | "github_connect_link" | "github_token" | "github_repositories_list" | "social_connections_list" | "social_posts_recent" | "social_daily_analysis_context" | "scheduled_tasks_list" | "scheduled_tasks_get" | "scheduled_tasks_create" | "scheduled_tasks_update" | "scheduled_tasks_pause" | "scheduled_tasks_resume" | "scheduled_tasks_trigger" | "scheduled_tasks_delete" | "scheduled_task_runs_list" | "slack_bot_list_channels" | "slack_bot_channel_history" | "slack_bot_list_users" | "slack_bot_post_message";
 type ProductAccessMode = "local" | "configured" | "managed";
 type ModelCapabilitySupportV1 = "supported" | "unsupported" | "unknown";
 type ModelCapabilityStateV1 = {
@@ -2018,9 +2021,6 @@ type ComposerDraft = {
     revision: number;
     text: string;
     resources: ResourceRef[];
-    tools: ToolRef[];
-    /** False inherits the session policy; true preserves an explicit array. */
-    toolsProvided: boolean;
     model: string;
     reasoningEffort: ReasoningEffort;
     sourceTurnId: string | null;
@@ -2035,6 +2035,7 @@ type NewSessionDraftOptions = {
     rigId?: string | undefined;
     goal?: GoalSpec | undefined;
     firstPartyMcpPermissions?: Permission[] | undefined;
+    firstPartyMcpTools?: FirstPartyMcpToolName[] | undefined;
 };
 type NewSessionDraft = {
     revision: number;
@@ -2054,10 +2055,18 @@ type SessionQueueSnapshot = {
     /** The latest interrupted attempt has not yet durably proved physical quiescence. */
     stoppingPreviousAttempt: boolean;
     items: SessionTurn[];
+    /** Canonical pending machine inputs. Events only invalidate this snapshot. */
+    pendingInputs: SessionPendingInputPreview[];
+    /** Exact next bounded input batch that will join an already-waiting prompt. */
+    pendingInputAttachment: {
+        turnId: string;
+        inputIds: string[];
+    } | null;
 };
+type SessionPendingInputPreview = Pick<SessionSystemUpdate, "id" | "sessionId" | "kind" | "classification" | "sourceId" | "summary" | "createdAt">;
 type SystemUpdateClassification = "success" | "failure" | "action_required" | "info";
 type SessionSystemUpdateKind = "scheduled_occurrence" | "goal_continuation" | "agent_message" | "agent_steer_instruction" | "child_terminal_result";
-type SessionSystemUpdateState = "pending" | "deferred" | "delivered" | "cancelled" | "superseded" | "failed";
+type SessionSystemUpdateState = "pending" | "delivered" | "cancelled" | "superseded" | "failed";
 type SessionSystemUpdate = {
     id: string;
     sessionId: string;
@@ -2070,6 +2079,7 @@ type SessionSystemUpdate = {
     lineage: Record<string, unknown>;
     state: SessionSystemUpdateState;
     deliveredTurnId: string | null;
+    deliveredHistoryItemId: string | null;
     deliveredAt: string | null;
     createdAt: string;
 };
@@ -2892,6 +2902,7 @@ type GitHubRepository = {
 };
 type GitHubRepositoryScope = "all" | "selected";
 type GitHubBindingStatus = "disabled" | "unbound" | "bound";
+type GitHubAppSetupMode = "platform" | "operator";
 type GitHubInstallationLifecycle = "active" | "suspended" | "deleted" | "unverified";
 type GitHubInstallationBinding = {
     installationId: number;
@@ -2901,6 +2912,8 @@ type GitHubInstallationBinding = {
     lifecycle: GitHubInstallationLifecycle;
     repositoryScope: GitHubRepositoryScope;
     repositoryCount: number;
+    /** OpenGeni-owned entry point for changing the installation's repository allowlist. */
+    configureUrl: string | null;
     createdAt: string;
     updatedAt: string;
 };
@@ -2908,12 +2921,14 @@ type GitHubAppInfo = {
     configured: boolean;
     /** Truthful workspace binding state; server App credentials alone are not a binding. */
     status: GitHubBindingStatus;
+    /** Platform deployments expose installation only; operator deployments may create an App. */
+    setupMode: GitHubAppSetupMode;
     appId: string | null;
     clientId: string | null;
     appSlug: string | null;
-    /** Fresh GitHub-controlled installation/configuration consent entry point. */
+    /** Fresh OAuth-first existing-installation discovery and install entry point. */
     installUrl: string | null;
-    /** Compatibility alias for installUrl; no repository-admin chooser is exposed. */
+    /** Compatibility alias for installUrl. */
     linkUrl: string | null;
     /** Installation bindings owned independently by this workspace. */
     installations: GitHubInstallationBinding[];
@@ -2995,7 +3010,6 @@ type UserMessageEventInput = {
         text: string;
         turnInstructions?: string | undefined;
         resources?: ResourceRef[] | undefined;
-        tools?: ToolRef[] | undefined;
         model?: string | undefined;
         reasoningEffort?: ReasoningEffort | undefined;
         mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[] | undefined;
@@ -4058,6 +4072,22 @@ type SseMessage = {
 };
 declare function parseSseStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage, void, void>;
 
+/**
+ * A transport-tolerant MCP tool result.
+ *
+ * `value` is the canonical machine-readable payload after recognized MCP/JSON
+ * envelopes are removed. `text` is the best presentation string without
+ * discarding structured data. `raw` always retains the original evidence.
+ */
+type NormalizedMcpOutput = Readonly<{
+    raw: unknown;
+    value: unknown;
+    text: string;
+    isError: boolean;
+}>;
+/** Normalize common direct, JSON, and standard MCP result envelopes without throwing. */
+declare function normalizeMcpOutput(output: unknown): NormalizedMcpOutput;
+
 /**
  * Translate the negotiated desktop capability into the WebSocket URL the noVNC
  * RFB client connects to. The scoped provider token is ALREADY embedded in the
@@ -4178,4 +4208,4 @@ declare function ttydInputFrame(data: string): string;
 /** Build a client→server RESIZE frame: "1" + JSON.stringify({ columns, rows }). */
 declare function ttydResizeFrame(columns: number, rows: number): string;
 
-export { type AccessContext, type AccessGrant, type AccountGrant, type AccountRole, type AcknowledgeStreamRequest, type AcknowledgeStreamResponse, type ActivateWorkspaceInstructionPolicyRequest, type AddDocumentRequest, type AddWorkspaceMemberRequest, type AgentMessageCompletedPayload, type AgentTextDeltaPayload, type AgentToolCallCreatedPayload, type AgentToolCallOutputPayload, type ApiKey, type AttachViewerRequest, type AttachViewerResponse, type BillingBalance, type BillingEntitlementsResponse, type BillingMode, type BillingSummary, type BillingUsageResponse, type CapabilityCatalogItem, type CapabilityCatalogResponse, type CapabilityInstallation, type CapabilityInstallationStatus, type CapabilityKind, type CapabilityPack, type CapabilityPackConnector, type CapabilityPackConnectorAuthModel, type CapabilityPackKnowledge, type CapabilityPackScheduledTaskTemplate, type CapabilityPackSkill, type CapabilityPackSkillFile, type CapabilityPackVariableSetSpec, type CapabilityRuntime, type CapabilitySource, type CapabilityUnavailableReason, type ClientAuthConfig, type ClientConfig, type ClientModel, type ClientSessionEventInput, type CodexAccount, type CodexAccountOverview, type CodexAccountSwitchedPayload, type CodexAccountsResponse, type CodexAllocatorUpdate, type CodexConnectPoll, type CodexConnectStart, type CodexConnectionStatus, type CodexFleetCacheState, type CodexFleetConfidence, type CodexFleetDecisionEventPayload, type CodexFleetDecisionScore, type CodexFleetShadowComparison, type CodexOverviewResponse, type CodexResetCredit, type CodexResetRedemptionRecovery, type CodexRotationSettings, type CodexUsage, type CodexUsageMap, type CodexUsagePayload, type CodexUsageWindow, type CompactSessionContextResult, type CompleteFileUploadResponse, type ComposerDraft, type ComputerUseCapability, type ConnectionKind, type ConnectionMetadata, type ConnectionResponse, type ConnectionStatus, type CreateApiKeyRequest, type CreateApiKeyResponse, type CreateCapabilityCatalogItemRequest, type CreateCheckoutRequest, type CreateCheckoutResponse, type CreateConnectionRequest, type CreateDocumentBaseRequest, type CreateFileUploadRequest, type CreateFileUploadResponse, type CreateGitHubAppManifestRequest, type CreateGitHubAppManifestResponse, type CreateKnowledgeDropRequest, type CreateKnowledgeMemoryRequest, type CreateRigRequest, type CreateScheduledTaskRequest, type CreateSessionRequest, type CreateVariableSetRequest, type CreateWorkspaceEnvironmentRequest, type CreateWorkspaceInstructionPolicyDraftRequest, type CreateWorkspaceRequest, DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY, type DeleteSessionQueueItemRequest, type DesktopConnectionState, type DesktopRfbFactory, type DesktopRfbLike, type DesktopStreamCapability, type DesktopStreamEvent, type DeviceEnrollmentApproveRequest, type DeviceEnrollmentApproveResponse, type DeviceEnrollmentDenyRequest, type DeviceEnrollmentDenyResponse, type DeviceEnrollmentLookupMachine, type DeviceEnrollmentLookupRequest, type DeviceEnrollmentLookupResponse, type DiscoverMcpCapabilitiesResponse, type Document, type DocumentBase, type DocumentCuration, type DocumentCurationStatus, type DocumentSearchMode, type DocumentSearchRequest, type DocumentSearchResponse, type DocumentSearchResult, type DocumentStatus, type DocumentVisibility, type EditSessionQueueItemRequest, type EffectiveControlBlocker, type EffectiveControlResumeOption, type EffectiveSessionControl, type EnableCapabilityRequest, type EnablePackRequest, type EnrollTokenExchangeRequest, type EnrollTokenExchangeResponse, type EnrollmentCredentials, type EnrollmentOs, type EntitlementValue, type Entitlements, type EntitlementsMode, type FetchLike, type FileAsset, type FileDownloadUrlResponse, type FileResourceRef, type FileStatus, type FileSystemCapability, type FileUploadData, type FsChangeKind, type FsChangedPayload, type FsDeleteRequest, type FsDeleteResponse, type FsEncoding, type FsListRequest, type FsListResponse, type FsMkdirRequest, type FsMkdirResponse, type FsMoveRequest, type FsMoveResponse, type FsNodeType, type FsReadRequest, type FsReadResponse, type FsTreeNode, type FsWriteRequest, type FsWriteResponse, type GetPackResponse, type GetWorkspaceCaptureFileResponse, type GetWorkspaceCaptureResponse, type GitCapability, type GitChangedPayload, type GitCommit, type GitCredentialBindingId, type GitCredentialProvider, type GitDiffHunk, type GitDiffLine, type GitDiffLineType, type GitDiffRequest, type GitDiffResponse, type GitFileDiff, type GitFileStatus, type GitFileStatusCode, type GitHubAppInfo, type GitHubBindingStatus, type GitHubInstallationBinding, type GitHubInstallationLifecycle, type GitHubRepositoriesResponse, type GitHubRepository, type GitHubRepositoryScope, type GitLogRequest, type GitLogResponse, type GitRepositoryAccess, type GitShowRequest, type GitShowResponse, type GitStatusRequest, type GitStatusResponse, type GoalSpec, type HumanInputAnswer, type HumanInputOption, type HumanInputQuestion, type HumanInputQuestionKind, type HumanInputResponse, type ImportLegacyWorkspaceInstructionPolicyDraftRequest, type IntegrationClientMetadata, KNOWN_PERMISSIONS, KNOWN_USAGE_EVENT_TYPES, type KnowledgeMemory, type KnowledgeMemoryKind, type KnowledgeMemorySearchRequest, type KnowledgeMemoryStatus, type KnowledgeSourceKind, type KnowledgeSourceRef, type KnownPermission, type KnownSessionEventType, type KnownUsageEventType, type LineageNode, type ListApiKeysResponse, type ListConnectionsResponse, type ListPacksResponse, type ListWorkspaceMembersResponse, type MachineKind, type MachineMetricsSeriesResponse, type MachineState, type MachineView, type MachinesResponse, type McpServerConnectionRef, type MetricSample, type MintEnrollTokenRequest, type MintEnrollTokenResponse, type ModelAvailabilityV1, type ModelBillingAttributionV1, type ModelCapabilitiesV1, type ModelCapabilityStateV1, type ModelCapabilitySupportV1, type ModelCredentialReadinessV1, type ModelCredentialSourceV1, type ModelPricingScheduleV1, type ModelPricingV1, type MoveDocumentRequest, type MoveSessionQueueItemRequest, type NewSessionDraft, type NewSessionDraftOptions, type OAuthStartRequest, type OAuthStartResponse, OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION, OPENGENI_CORRELATION_HEADER, OpenGeniApiContractMismatchError, OpenGeniApiError, OpenGeniClient, type OpenGeniClientOptions, type OpenGeniRequestOptions, OpenGeniSessionListCursorError, type OpenGeniSlackBotInstallRequest, type OpenGeniSlackBotInstallStart, OpenGeniStreamError, type PackInstallation, type PackInstallationStatus, type Permission, type ProductAccessMode, type ProposeRigChangeRequest, type ProxySessionEventStreamOptions, type PtyCloseRequest, type PtyOpenRequest, type PtyOpenResponse, type PtyResizeRequest, type PtyWriteRequest, RETAINED_OUTPUT_DEFAULT_PAGE_BYTES, RETAINED_OUTPUT_MAX_PAGE_BYTES, type ReasoningEffort, type RecordingAvailablePayload, type RecordingCapability, type RecordingCodec, type RecordingContentType, type RecordingFailedPayload, type RecordingFailedReason, type RecordingMode, type RecordingStartedPayload, type RegisterCapabilityPackRequest, type RepositoryResourceRef, type ResourceRef, type RetainedArtifactContent, type RetainedArtifactContentOptions, type RetainedArtifactMetadata, type RetainedArtifactReference, type RetainedArtifactUnavailable, type RetainedOutputKind, type RetainedOutputUnavailableReason, type Rig, type RigChange, type RigChangeKind, type RigChangeStatus, type RigChangeVerification, type RigCheck, type RigCheckResult, type RigDefinitionEditPayload, type RigSetupAppendPayload, type RigVersion, type RollbackWorkspaceInstructionPolicyRequest, SESSION_EVENT_TYPES, type SandboxBackend, type SandboxCapabilityName, type SandboxCommandOutputDeltaPayload, type SandboxOs, type SaveComposerDraftRequest, type SaveNewSessionDraftRequest, type ScheduledTask, type ScheduledTaskAgentConfig, type ScheduledTaskAgentConfigInput, type ScheduledTaskDayOfWeek, type ScheduledTaskOverlapPolicy, type ScheduledTaskRun, type ScheduledTaskRunMode, type ScheduledTaskRunStatus, type ScheduledTaskScheduleSpec, type ScheduledTaskStatus, type ScheduledTaskTriggerType, type SendMessageInput, type ServiceTurnInitiator, type ServiceTurnInitiatorContext, type Session, type SessionCapabilities, type SessionCommandReceipt, type SessionControlResponse, type SessionEffectiveToolPolicy, type SessionEvent, type SessionEventCompactResult, type SessionEventCompactResultOptions, type SessionEventLatestClass, type SessionEventListOptions, type SessionEventPage, type SessionEventPayloadMode, type SessionEventReadDirection, type SessionEventReadMode, type SessionEventResultMode, type SessionEventSemanticClass, type SessionEventStreamTransport, type SessionEventType, type SessionGoal, type SessionGoalCreatedBy, type SessionGoalStatus, type SessionHumanInputRequest, type SessionLineageResponse, type SessionListResponse, type SessionMcpApprovalPolicy, type SessionMcpCredentialUpdateInput, type SessionMcpServerInput, type SessionMcpServerMetadata, type SessionQueueMutationResponse, type SessionQueueSnapshot, type SessionStatus, type SessionStatusChangedPayload, type SessionStructuredCapabilities, type SessionSummary, type SessionSystemUpdate, type SessionSystemUpdateKind, type SessionSystemUpdateState, type SessionToolPolicy, type SessionTurn, type SessionTurnSource, type SessionTurnStatus, type SetWorkspaceEnvironmentVariableRequest, type SseMessage, type SseReStreamOptions, type SteerMessageResult, type SteerSessionQueueItemRequest, type StreamClosedPayload, type StreamConnectionState, type StreamOpenedPayload, type StreamRevokedPayload, type StreamSessionEventsOptions, type StreamUrlRotatedPayload, type SubmitHumanInputResponseRequest, type SwapActiveSandboxRequest, type SwapActiveSandboxResponse, TTYD_SUBPROTOCOL, type TerminalCapability, type TerminalExecRequest, type TerminalExecResponse, type TerminalPtyExitedPayload, type TerminalPtyOutputDeltaPayload, type TerminalPtyStartedPayload, type ToolAuthNeededPayload, type ToolRef, type TranscriptionAdapter, type TranscriptionAdapterDescriptor, type TranscriptionAdapterStartContext, type TranscriptionAuthorization, type TranscriptionCredentialMode, type TranscriptionDiagnostic, type TranscriptionErrorCode, type TranscriptionEvent, type TranscriptionEventListener, type TranscriptionLifecycleStatus, type TranscriptionPolicyBlockReason, type TranscriptionResultMetadata, type TranscriptionSession, type TranscriptionSessionRequest, type TranscriptionSpeaker, type TranscriptionTargetSelection, type TranscriptionTimeSpan, type TranscriptionWord, TtydClientCommand, TtydServerCommand, type TurnInitiator, type UpdateConnectionRequest, type UpdateKnowledgeMemoryRequest, type UpdateRigRequest, type UpdateScheduledTaskRequest, type UpdateSessionGoalRequest, type UpdateSessionMcpApprovalPolicyRequest, type UpdateSessionMcpApprovalPolicyResponse, type UpdateSessionPinRequest, type UpdateSessionRequest, type UpdateSessionToolPolicyRequest, type UpdateVariableSetRequest, type UpdateWorkspaceEnvironmentRequest, type UpdateWorkspaceMemberRequest, type UpdateWorkspaceRequest, type UpdateWorkspaceSettingsRequest, type UploadFileInput, type UsageEvent, type UsageEventType, type UserApprovalDecisionEventInput, type UserHumanInputResponseEventInput, type UserMessageEventInput, type VariableSet, type VariableSetVariableMetadata, type ViewerHeartbeatRequest, type ViewerHeartbeatResponse, type ViewerHolder, type Workspace, type WorkspaceCaptureDegradedReason, type WorkspaceCaptureFile, type WorkspaceCaptureManifest, type WorkspaceCaptureRepo, type WorkspaceCaptureSignedUrl, type WorkspaceCaptureStats, type WorkspaceControlEvent, type WorkspaceControlEventPage, type WorkspaceControlStreamTransport, type WorkspaceEnvironment, type WorkspaceEnvironmentVariableMetadata, type WorkspaceInferenceControlResponse, type WorkspaceInstructionPolicyActivationEvent, type WorkspaceInstructionPolicyActivationResponse, type WorkspaceInstructionPolicyActivationType, type WorkspaceInstructionPolicyConflictResponse, type WorkspaceInstructionPolicyDiffRequest, type WorkspaceInstructionPolicyDiffResponse, type WorkspaceInstructionPolicyDraftProvenanceSource, type WorkspaceInstructionPolicyHead, type WorkspaceInstructionPolicyKind, type WorkspaceInstructionPolicyListOptions, type WorkspaceInstructionPolicyListResponse, type WorkspaceInstructionPolicyProvenanceSource, type WorkspaceInstructionPolicyRevision, type WorkspaceInstructionPolicyRevisionIdentity, type WorkspaceInstructionPolicyScope, type WorkspaceInstructionPolicyTarget, type WorkspaceMember, type WorkspaceMemorySearchMode, type WorkspaceMemorySearchRequest, type WorkspaceMemorySearchResponse, type WorkspaceMemorySearchResult, type WorkspaceModelCatalogModel, type WorkspaceModelCatalogResponse, type WorkspaceRegisteredPack, type WorkspaceRevisionCapturedPayload, type WorkspaceRevisionDegradedPayload, type WorkspaceSettings, type WorkspaceTranscriptionPolicy, type WorkspaceTranscriptionTarget, applyUrlRotation, authorizeTranscriptionAdapter, createTranscriptionSessionRequest, desktopSocketUrl, formatSseEvent, isRetryableStreamError, nextDesktopState, normalizeWorkspaceInstructionPolicyRoleKey, parseSseStream, proxySessionEventStream, resolveWorkspaceTranscriptionPolicy, resumeSequenceFromRequest, sessionEventsToSseResponse, sessionEventsToSseStream, streamSessionEvents, streamWorkspaceControlEvents, terminalSocketUrl, ttydAuthFrame, ttydInputFrame, ttydResizeFrame };
+export { type AccessContext, type AccessGrant, type AccountGrant, type AccountRole, type AcknowledgeStreamRequest, type AcknowledgeStreamResponse, type ActivateWorkspaceInstructionPolicyRequest, type AddDocumentRequest, type AddWorkspaceMemberRequest, type AgentMessageCompletedPayload, type AgentTextDeltaPayload, type AgentToolCallCreatedPayload, type AgentToolCallOutputPayload, type ApiKey, type AttachViewerRequest, type AttachViewerResponse, type BillingBalance, type BillingEntitlementsResponse, type BillingMode, type BillingSummary, type BillingUsageResponse, type CapabilityCatalogItem, type CapabilityCatalogResponse, type CapabilityInstallation, type CapabilityInstallationStatus, type CapabilityKind, type CapabilityPack, type CapabilityPackConnector, type CapabilityPackConnectorAuthModel, type CapabilityPackKnowledge, type CapabilityPackScheduledTaskTemplate, type CapabilityPackSkill, type CapabilityPackSkillFile, type CapabilityPackVariableSetSpec, type CapabilityRuntime, type CapabilitySource, type CapabilityUnavailableReason, type ClientAuthConfig, type ClientConfig, type ClientModel, type ClientSessionEventInput, type CodexAccount, type CodexAccountOverview, type CodexAccountSwitchedPayload, type CodexAccountsResponse, type CodexAllocatorUpdate, type CodexConnectPoll, type CodexConnectStart, type CodexConnectionStatus, type CodexFleetCacheState, type CodexFleetConfidence, type CodexFleetDecisionEventPayload, type CodexFleetDecisionScore, type CodexFleetShadowComparison, type CodexOverviewResponse, type CodexResetCredit, type CodexResetRedemptionRecovery, type CodexRotationSettings, type CodexUsage, type CodexUsageMap, type CodexUsagePayload, type CodexUsageWindow, type CompactSessionContextResult, type CompleteFileUploadResponse, type ComposerDraft, type ComputerUseCapability, type ConnectionKind, type ConnectionMetadata, type ConnectionResponse, type ConnectionStatus, type CreateApiKeyRequest, type CreateApiKeyResponse, type CreateCapabilityCatalogItemRequest, type CreateCheckoutRequest, type CreateCheckoutResponse, type CreateConnectionRequest, type CreateDocumentBaseRequest, type CreateFileUploadRequest, type CreateFileUploadResponse, type CreateGitHubAppManifestRequest, type CreateGitHubAppManifestResponse, type CreateKnowledgeDropRequest, type CreateKnowledgeMemoryRequest, type CreateRigRequest, type CreateScheduledTaskRequest, type CreateSessionRequest, type CreateVariableSetRequest, type CreateWorkspaceEnvironmentRequest, type CreateWorkspaceInstructionPolicyDraftRequest, type CreateWorkspaceRequest, DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY, type DeleteSessionQueueItemRequest, type DesktopConnectionState, type DesktopRfbFactory, type DesktopRfbLike, type DesktopStreamCapability, type DesktopStreamEvent, type DeviceEnrollmentApproveRequest, type DeviceEnrollmentApproveResponse, type DeviceEnrollmentDenyRequest, type DeviceEnrollmentDenyResponse, type DeviceEnrollmentLookupMachine, type DeviceEnrollmentLookupRequest, type DeviceEnrollmentLookupResponse, type DiscoverMcpCapabilitiesResponse, type Document, type DocumentBase, type DocumentCuration, type DocumentCurationStatus, type DocumentSearchMode, type DocumentSearchRequest, type DocumentSearchResponse, type DocumentSearchResult, type DocumentStatus, type DocumentVisibility, type EditSessionQueueItemRequest, type EffectiveControlBlocker, type EffectiveControlResumeOption, type EffectiveSessionControl, type EnableCapabilityRequest, type EnablePackRequest, type EnrollTokenExchangeRequest, type EnrollTokenExchangeResponse, type EnrollmentCredentials, type EnrollmentOs, type EntitlementValue, type Entitlements, type EntitlementsMode, type FetchLike, type FileAsset, type FileDownloadUrlResponse, type FileResourceRef, type FileStatus, type FileSystemCapability, type FileUploadData, type FirstPartyMcpToolName, type FsChangeKind, type FsChangedPayload, type FsDeleteRequest, type FsDeleteResponse, type FsEncoding, type FsListRequest, type FsListResponse, type FsMkdirRequest, type FsMkdirResponse, type FsMoveRequest, type FsMoveResponse, type FsNodeType, type FsReadRequest, type FsReadResponse, type FsTreeNode, type FsWriteRequest, type FsWriteResponse, type GetPackResponse, type GetWorkspaceCaptureFileResponse, type GetWorkspaceCaptureResponse, type GitCapability, type GitChangedPayload, type GitCommit, type GitCredentialBindingId, type GitCredentialProvider, type GitDiffHunk, type GitDiffLine, type GitDiffLineType, type GitDiffRequest, type GitDiffResponse, type GitFileDiff, type GitFileStatus, type GitFileStatusCode, type GitHubAppInfo, type GitHubAppSetupMode, type GitHubBindingStatus, type GitHubInstallationBinding, type GitHubInstallationLifecycle, type GitHubRepositoriesResponse, type GitHubRepository, type GitHubRepositoryScope, type GitLogRequest, type GitLogResponse, type GitRepositoryAccess, type GitShowRequest, type GitShowResponse, type GitStatusRequest, type GitStatusResponse, type GoalSpec, type HumanInputAnswer, type HumanInputOption, type HumanInputQuestion, type HumanInputQuestionKind, type HumanInputResponse, type ImportLegacyWorkspaceInstructionPolicyDraftRequest, type IntegrationClientMetadata, KNOWN_PERMISSIONS, KNOWN_USAGE_EVENT_TYPES, type KnowledgeMemory, type KnowledgeMemoryKind, type KnowledgeMemorySearchRequest, type KnowledgeMemoryStatus, type KnowledgeSourceKind, type KnowledgeSourceRef, type KnownPermission, type KnownSessionEventType, type KnownUsageEventType, type LineageNode, type ListApiKeysResponse, type ListConnectionsResponse, type ListPacksResponse, type ListWorkspaceMembersResponse, type MachineKind, type MachineMetricsSeriesResponse, type MachineState, type MachineView, type MachinesResponse, type McpServerConnectionRef, type MetricSample, type MintEnrollTokenRequest, type MintEnrollTokenResponse, type ModelAvailabilityV1, type ModelBillingAttributionV1, type ModelCapabilitiesV1, type ModelCapabilityStateV1, type ModelCapabilitySupportV1, type ModelCredentialReadinessV1, type ModelCredentialSourceV1, type ModelPricingScheduleV1, type ModelPricingV1, type MoveDocumentRequest, type MoveSessionQueueItemRequest, type NewSessionDraft, type NewSessionDraftOptions, type NormalizedMcpOutput, type OAuthStartRequest, type OAuthStartResponse, OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION, OPENGENI_CORRELATION_HEADER, OpenGeniApiContractMismatchError, OpenGeniApiError, OpenGeniClient, type OpenGeniClientOptions, type OpenGeniRequestOptions, OpenGeniSessionListCursorError, type OpenGeniSlackBotInstallRequest, type OpenGeniSlackBotInstallStart, OpenGeniStreamError, type PackInstallation, type PackInstallationStatus, type Permission, type ProductAccessMode, type ProposeRigChangeRequest, type ProxySessionEventStreamOptions, type PtyCloseRequest, type PtyOpenRequest, type PtyOpenResponse, type PtyResizeRequest, type PtyWriteRequest, RETAINED_OUTPUT_DEFAULT_PAGE_BYTES, RETAINED_OUTPUT_MAX_PAGE_BYTES, type ReasoningEffort, type RecordingAvailablePayload, type RecordingCapability, type RecordingCodec, type RecordingContentType, type RecordingFailedPayload, type RecordingFailedReason, type RecordingMode, type RecordingStartedPayload, type RegisterCapabilityPackRequest, type RepositoryResourceRef, type ResourceRef, type RetainedArtifactContent, type RetainedArtifactContentOptions, type RetainedArtifactMetadata, type RetainedArtifactReference, type RetainedArtifactUnavailable, type RetainedOutputKind, type RetainedOutputUnavailableReason, type Rig, type RigChange, type RigChangeKind, type RigChangeStatus, type RigChangeVerification, type RigCheck, type RigCheckResult, type RigDefinitionEditPayload, type RigSetupAppendPayload, type RigVersion, type RollbackWorkspaceInstructionPolicyRequest, SESSION_EVENT_TYPES, type SandboxBackend, type SandboxCapabilityName, type SandboxCommandOutputDeltaPayload, type SandboxOs, type SaveComposerDraftRequest, type SaveNewSessionDraftRequest, type ScheduledTask, type ScheduledTaskAgentConfig, type ScheduledTaskAgentConfigInput, type ScheduledTaskDayOfWeek, type ScheduledTaskOverlapPolicy, type ScheduledTaskRun, type ScheduledTaskRunMode, type ScheduledTaskRunStatus, type ScheduledTaskScheduleSpec, type ScheduledTaskStatus, type ScheduledTaskTriggerType, type SendMessageInput, type ServiceTurnInitiator, type ServiceTurnInitiatorContext, type Session, type SessionCapabilities, type SessionCommandReceipt, type SessionControlResponse, type SessionEffectiveToolPolicy, type SessionEvent, type SessionEventCompactResult, type SessionEventCompactResultOptions, type SessionEventLatestClass, type SessionEventListOptions, type SessionEventPage, type SessionEventPayloadMode, type SessionEventReadDirection, type SessionEventReadMode, type SessionEventResultMode, type SessionEventSemanticClass, type SessionEventStreamTransport, type SessionEventType, type SessionGoal, type SessionGoalCreatedBy, type SessionGoalStatus, type SessionHumanInputRequest, type SessionLineageResponse, type SessionListResponse, type SessionMcpApprovalPolicy, type SessionMcpCredentialUpdateInput, type SessionMcpServerInput, type SessionMcpServerMetadata, type SessionPendingInputPreview, type SessionQueueMutationResponse, type SessionQueueSnapshot, type SessionStatus, type SessionStatusChangedPayload, type SessionStructuredCapabilities, type SessionSummary, type SessionSystemUpdate, type SessionSystemUpdateKind, type SessionSystemUpdateState, type SessionToolPolicy, type SessionTurn, type SessionTurnSource, type SessionTurnStatus, type SetWorkspaceEnvironmentVariableRequest, type SseMessage, type SseReStreamOptions, type SteerMessageResult, type SteerSessionQueueItemRequest, type StreamClosedPayload, type StreamConnectionState, type StreamOpenedPayload, type StreamRevokedPayload, type StreamSessionEventsOptions, type StreamUrlRotatedPayload, type SubmitHumanInputResponseRequest, type SwapActiveSandboxRequest, type SwapActiveSandboxResponse, TTYD_SUBPROTOCOL, type TerminalCapability, type TerminalExecRequest, type TerminalExecResponse, type TerminalPtyExitedPayload, type TerminalPtyOutputDeltaPayload, type TerminalPtyStartedPayload, type ToolAuthNeededPayload, type ToolRef, type TranscriptionAdapter, type TranscriptionAdapterDescriptor, type TranscriptionAdapterStartContext, type TranscriptionAuthorization, type TranscriptionCredentialMode, type TranscriptionDiagnostic, type TranscriptionErrorCode, type TranscriptionEvent, type TranscriptionEventListener, type TranscriptionLifecycleStatus, type TranscriptionPolicyBlockReason, type TranscriptionResultMetadata, type TranscriptionSession, type TranscriptionSessionRequest, type TranscriptionSpeaker, type TranscriptionTargetSelection, type TranscriptionTimeSpan, type TranscriptionWord, TtydClientCommand, TtydServerCommand, type TurnInitiator, type UpdateConnectionRequest, type UpdateKnowledgeMemoryRequest, type UpdateRigRequest, type UpdateScheduledTaskRequest, type UpdateSessionGoalRequest, type UpdateSessionMcpApprovalPolicyRequest, type UpdateSessionMcpApprovalPolicyResponse, type UpdateSessionPinRequest, type UpdateSessionRequest, type UpdateSessionToolPolicyRequest, type UpdateVariableSetRequest, type UpdateWorkspaceEnvironmentRequest, type UpdateWorkspaceMemberRequest, type UpdateWorkspaceRequest, type UpdateWorkspaceSettingsRequest, type UploadFileInput, type UsageEvent, type UsageEventType, type UserApprovalDecisionEventInput, type UserHumanInputResponseEventInput, type UserMessageEventInput, type VariableSet, type VariableSetVariableMetadata, type ViewerHeartbeatRequest, type ViewerHeartbeatResponse, type ViewerHolder, type Workspace, type WorkspaceCaptureDegradedReason, type WorkspaceCaptureFile, type WorkspaceCaptureManifest, type WorkspaceCaptureRepo, type WorkspaceCaptureSignedUrl, type WorkspaceCaptureStats, type WorkspaceControlEvent, type WorkspaceControlEventPage, type WorkspaceControlStreamTransport, type WorkspaceEnvironment, type WorkspaceEnvironmentVariableMetadata, type WorkspaceInferenceControlResponse, type WorkspaceInstructionPolicyActivationEvent, type WorkspaceInstructionPolicyActivationResponse, type WorkspaceInstructionPolicyActivationType, type WorkspaceInstructionPolicyConflictResponse, type WorkspaceInstructionPolicyDiffRequest, type WorkspaceInstructionPolicyDiffResponse, type WorkspaceInstructionPolicyDraftProvenanceSource, type WorkspaceInstructionPolicyHead, type WorkspaceInstructionPolicyKind, type WorkspaceInstructionPolicyListOptions, type WorkspaceInstructionPolicyListResponse, type WorkspaceInstructionPolicyProvenanceSource, type WorkspaceInstructionPolicyRevision, type WorkspaceInstructionPolicyRevisionIdentity, type WorkspaceInstructionPolicyScope, type WorkspaceInstructionPolicyTarget, type WorkspaceMember, type WorkspaceMemorySearchMode, type WorkspaceMemorySearchRequest, type WorkspaceMemorySearchResponse, type WorkspaceMemorySearchResult, type WorkspaceModelCatalogModel, type WorkspaceModelCatalogResponse, type WorkspaceRegisteredPack, type WorkspaceRevisionCapturedPayload, type WorkspaceRevisionDegradedPayload, type WorkspaceSettings, type WorkspaceTranscriptionPolicy, type WorkspaceTranscriptionTarget, applyUrlRotation, authorizeTranscriptionAdapter, createTranscriptionSessionRequest, desktopSocketUrl, formatSseEvent, isRetryableStreamError, nextDesktopState, normalizeMcpOutput, normalizeWorkspaceInstructionPolicyRoleKey, parseSseStream, proxySessionEventStream, resolveWorkspaceTranscriptionPolicy, resumeSequenceFromRequest, sessionEventsToSseResponse, sessionEventsToSseStream, streamSessionEvents, streamWorkspaceControlEvents, terminalSocketUrl, ttydAuthFrame, ttydInputFrame, ttydResizeFrame };

package/dist/index.js

@@ -393,6 +393,9 @@ var SESSION_EVENT_TYPES = [
   "goal.continuation",
   "system.update.pending",
   "system.update.delivered",
+  "system.update.superseded",
+  "system.update.cancelled",
+  "system.update.settled",
   "session.control.paused",
   "session.control.resumed",
   "session.control.steer_requested",
@@ -2636,6 +2639,127 @@ function proxySessionEventStream(client, workspaceId, sessionId, options = {}) {
   });
 }
 
+// src/mcp-output.ts
+var MAX_MCP_OUTPUT_DEPTH = 8;
+var RESULT_ENVELOPE_KEYS = /* @__PURE__ */ new Set(["result", "isError", "jsonrpc", "id", "_meta"]);
+function normalizeMcpOutput(output) {
+  const normalized = normalizeValue(output, 0, /* @__PURE__ */ new Set());
+  return {
+    raw: output,
+    value: normalized.value,
+    text: normalized.text,
+    isError: normalized.isError
+  };
+}
+function normalizeValue(value, depth, ancestors) {
+  if (value === null || value === void 0) {
+    return { value, text: "", isError: false };
+  }
+  if (typeof value === "string") {
+    return normalizeText(value, depth, ancestors);
+  }
+  if (typeof value !== "object") {
+    return { value, text: String(value), isError: false };
+  }
+  if (depth >= MAX_MCP_OUTPUT_DEPTH || ancestors.has(value)) {
+    return { value, text: safeStringify(value), isError: false };
+  }
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return { value, text: safeStringify(value), isError: false };
+    }
+    const record = value;
+    const envelopeError = record.isError === true;
+    if (record.type === "text" && typeof record.text === "string") {
+      const normalized = normalizeText(record.text, depth + 1, ancestors);
+      return {
+        value: normalized.value,
+        text: record.text,
+        isError: envelopeError || normalized.isError
+      };
+    }
+    if ("structuredContent" in record) {
+      const normalized = normalizeValue(record.structuredContent, depth + 1, ancestors);
+      return {
+        value: normalized.value,
+        text: firstMcpText(record.content) ?? normalized.text,
+        isError: envelopeError || normalized.isError
+      };
+    }
+    if (isMcpContent(record.content)) {
+      const text = firstMcpText(record.content);
+      if (text !== null) {
+        const normalized = normalizeText(text, depth + 1, ancestors);
+        return {
+          value: normalized.value,
+          text,
+          isError: envelopeError || normalized.isError
+        };
+      }
+      return {
+        value,
+        text: safeStringify(value),
+        isError: envelopeError
+      };
+    }
+    if (isResultEnvelope(record)) {
+      const normalized = normalizeValue(record.result, depth + 1, ancestors);
+      return {
+        value: normalized.value,
+        text: normalized.text,
+        isError: envelopeError || normalized.isError
+      };
+    }
+    return {
+      value,
+      text: safeStringify(value),
+      isError: envelopeError
+    };
+  } finally {
+    ancestors.delete(value);
+  }
+}
+function normalizeText(text, depth, ancestors) {
+  try {
+    const parsed = JSON.parse(text);
+    const normalized = normalizeValue(parsed, depth + 1, ancestors);
+    return {
+      value: normalized.value,
+      text,
+      isError: normalized.isError
+    };
+  } catch {
+    return { value: text, text, isError: false };
+  }
+}
+function isMcpContent(value) {
+  return Array.isArray(value) && value.some(
+    (part) => part !== null && typeof part === "object" && typeof part.type === "string"
+  );
+}
+function firstMcpText(value) {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  for (const part of value) {
+    if (part !== null && typeof part === "object" && part.type === "text" && typeof part.text === "string") {
+      return part.text;
+    }
+  }
+  return null;
+}
+function isResultEnvelope(record) {
+  return "result" in record && Object.keys(record).every((key) => RESULT_ENVELOPE_KEYS.has(key));
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return String(value);
+  }
+}
+
 // src/desktop.ts
 function desktopSocketUrl(cap) {
   if (!cap.url) {
@@ -2966,6 +3090,7 @@ export {
   formatSseEvent,
   isRetryableStreamError,
   nextDesktopState,
+  normalizeMcpOutput,
   normalizeWorkspaceInstructionPolicyRoleKey,
   parseSseStream,
   proxySessionEventStream,