@opengeni/core 0.28.1 → 1.0.0

package/dist/domain/sessions.d.ts

@@ -1,18 +1,39 @@
+import type { SessionRetryRequest, SessionRetryResponse, SessionTurnSurface } from "@opengeni/contracts";
+import { type ProductUsageMetricsSink } from "../product-usage-metrics.js";
+import { type SessionStartObservability } from "./session-start-timing.js";
 import { type Settings } from "@opengeni/config";
-import { SessionSpawnDenial, type AccessGrant, type CreateSessionResponse, type GoalSpec, type FirstPartyMcpToolName, type McpPersonalConnectionDelegation, type Permission, type ReasoningEffort, type ResourceRef, type Session, type SessionSkill, type SessionEvent, SessionMcpApprovalPolicy, type SessionMcpCredentialUpdateInput, type SessionMcpServerMetadata, type SubmittedTimelineAnnotation, type TimelineAnnotation, type UpdateSessionMcpApprovalPolicyResponse, type UpdateSessionToolPolicyRequest, type SessionAuthorizationPort, type SessionToolPolicy, type SessionTurn, type ToolRef, type TurnInitiator, type TurnInitiatorContext, type TurnExecutionPolicyV1, type XaiProviderAccountAuthoritySnapshotV1 } from "@opengeni/contracts";
-import { type CreateSessionMcpServerInput, type Database, type UpdateSessionMcpServerCredentialsInput, type SessionCommandActor } from "@opengeni/db";
+import type { CodeSearchDeploymentPolicy } from "@opengeni/contracts/code-search";
+import { type AgentConfigCreator, type ResolvedAgentConfig, type UpdateSessionAgentRequest } from "@opengeni/contracts";
+import { SessionSpawnDenial, type AccessGrant, type ComposerDraft, type CreateSessionResponse, type GoalSpec, type FirstPartyMcpToolName, type McpPersonalConnectionDelegation, type McpConnectionAccountBinding, type McpConnectionAccountSelection, type Permission, type PersonalResourceAttachmentIntent, type ReasoningEffort, type ResourceRef, type Session, type SessionAgentAccess, type SessionCommandReceipt, type SessionScopeSubjectId, type SessionMemoryScope, type SessionSkill, type SessionEvent, SessionMcpApprovalPolicy, SetSessionModelRequest, type SessionMcpCredentialUpdateInput, type SessionMcpServerMetadata, type SubmittedTimelineAnnotation, type TimelineAnnotation, type UpdateSessionMcpApprovalPolicyResponse, type UpdateSessionToolPolicyRequest, type SessionAuthorizationPort, type SessionAuthorizationSurface, type SessionToolPolicy, type SessionTurn, type SessionPromptRouting, type SessionGoalSnapshot, type ToolRef, type TurnInitiator, type TurnInitiatorContext, type TurnExecutionPolicyV1, type VariableSet, type XaiProviderAccountAuthoritySnapshotV1, type ClaudeProviderAccountAuthoritySnapshotV1 } from "@opengeni/contracts";
+import { type CreateSessionMcpServerInput, type Database, type FrozenTurnInitiator, type UpdateSessionMcpServerCredentialsInput, type SessionCommandActor, type NewSessionDraftSnapshot } from "@opengeni/db";
 import { type EventBus } from "@opengeni/events";
+import { HTTPException } from "hono/http-exception";
+import { type AccessGrantAuthorization } from "../access/index.js";
 import type { AcceptSessionUserMessageDependencies, ApiRouteDeps, SessionWorkflowClient } from "../dependencies.js";
 /** Transport-neutral typed denial raised only after its audit row committed. */
 export declare class SessionSpawnDeniedError extends Error {
     readonly denial: SessionSpawnDenial;
     constructor(denial: SessionSpawnDenial);
 }
+/**
+ * A session's effective first-party selection as a ceiling for narrowing:
+ * the stored selection (or the deployment default for a legacy null) under
+ * the deployment ceiling, with the resume counterpart of pause authority the
+ * runtime already grants to existing sessions.
+ */
+export declare function effectiveFirstPartyMcpToolCeiling(stored: readonly FirstPartyMcpToolName[] | null | undefined, policy: {
+    default: readonly FirstPartyMcpToolName[];
+    allowed: readonly FirstPartyMcpToolName[];
+}): Set<FirstPartyMcpToolName>;
 /**
  * Resolve per-session first-party tool visibility without consulting
  * authorization. Top-level omission snapshots the complete runtime default;
  * child omission snapshots the parent's exact effective selection. Explicit
- * [] is authoritative and must never widen.
+ * [] is authoritative and must never widen. An explicit child selection may
+ * only narrow the parent's effective selection: a session that was handed a
+ * reduced catalog cannot spawn a child that sees more than it does. A
+ * top-level explicit selection keeps only the deployment ceiling (checked by
+ * the caller) because there is no creator selection to narrow.
  */
 export declare function resolveFirstPartyMcpToolsForCreate(requested: FirstPartyMcpToolName[] | undefined, parentStored: FirstPartyMcpToolName[] | null | undefined, policy?: {
     default: readonly FirstPartyMcpToolName[];
@@ -50,8 +71,17 @@ export type FrozenCreationInitiator = {
         type: "agent_attempt";
     }>;
 };
+/** Attribution is immutable accepted-work data, never the current request principal. */
+export declare function initiatingHumanForAllowance(frozen: Pick<FrozenTurnInitiator, "initiator" | "initiatingHumanSubjectId">): string | null;
 export declare function creationInitiatorForGrant(grant: AccessGrant): FrozenCreationInitiator;
+export declare function normalizedSessionMcpCredentialHeaders(headers: Record<string, string> | undefined): Record<string, string>;
 export declare function settingsWithSessionMcpServerMetadata(settings: Settings, servers: SessionMcpServerMetadata[]): Settings;
+export declare function validateSessionMcpCredentialUpdates(input: {
+    settings: Settings;
+    grant: AccessGrant;
+    session: Session;
+    updates: SessionMcpCredentialUpdateInput[];
+}): UpdateSessionMcpServerCredentialsInput[];
 export type CreateSessionOutcome = {
     session: CreateSessionResponse;
     /** The committed create/start effect represented by this request. */
@@ -65,7 +95,30 @@ export type CreateSessionRequestOutcome = CreateSessionOutcome & {
     /** Billing telemetry is recorded after the committed session start. */
     usageRecording: "recorded" | "failed";
 };
+type AgentChildSessionCreatePresentation = {
+    /** Model-authored title candidate from the first-party `session_create` tool.
+     * This is deliberately separate from the public REST request contract. */
+    automaticTitleCandidate?: string | null;
+};
+/** Trusted entry-point options for creating a session outside the REST body. */
+export type SessionCreateRequestOptions = {
+    /**
+     * Product surface when the entry point knows it (for example Slack or an
+     * in-process embedding host). Omitted derives it from the grant.
+     */
+    surface?: SessionTurnSurface;
+    /**
+     * Agent-configuration creator kind (renderer default and default-config
+     * policy). Omitted derives `slack` from a Slack surface, else the public API.
+     */
+    agentConfigCreator?: AgentConfigCreator;
+};
+/** @internal Exported for the keyed-create repair regression. */
+export declare function freezeAgentChildAutomaticTitleInCreatorContext(context: TurnInitiatorContext | undefined, title: string | null | undefined): TurnInitiatorContext | undefined;
+/** @internal Keyed repair must use the committed winner, not the retry payload. */
+export declare function initialAutomaticTitleForSessionStart(session: Pick<Session, "createdByContext">, requestedTitle: string | null | undefined): string | null;
 export declare function createAndStartSessionWithOutcome(input: {
+    initialAgentLearning?: import("@opengeni/contracts").AgentLearningOverrides | undefined;
     requestedSessionId?: string;
     db: Database;
     bus: EventBus;
@@ -73,14 +126,41 @@ export declare function createAndStartSessionWithOutcome(input: {
     /** Internal database-only composition seam. The exact session shell and this
      * linkage commit together before its first event/turn can be initialized. */
     beforeCreateCommit?: (tx: Database, sessionId: string) => Promise<void>;
+    /** Backend-only accepted-work composition. Recheck live caller authority
+     * here before capturing; session-shell authorization may have happened in
+     * an earlier transaction. Called only for a newly inserted initial turn. */
+    captureInitialTurnAuthority?: (tx: Database, sessionId: string, turnId: string) => Promise<void>;
+    /** Internal replay identity; the verified caller must also capture authority.
+     * Supplying selection metadata alone never grants runtime use. */
+    /** The custom workspace model was frozen by an earlier accepted boundary or
+     * inherited from an existing session, so retirement must not invalidate it. */
+    retainWorkspaceGatewayModel?: boolean;
+    /** Provider-neutral successor to retainWorkspaceGatewayModel. */
+    retainWorkspaceCustomModel?: boolean;
+    /** The selected workspace Gateway product is backed by a mutable custom row,
+     * rather than deployment-curated Gateway membership. */
+    workspaceGatewayCustomModel?: boolean;
+    /** Provider-neutral successor to workspaceGatewayCustomModel. */
+    workspaceCustomModel?: boolean;
     accountId: string;
     workspaceId: string;
+    visibility?: "user_private" | "workspace_shared";
     initialMessage: string;
+    /** Content-free product surface the create request entered through. */
+    surface?: SessionTurnSurface | null;
+    /**
+     * Live product usage counters: a newly created session (never a replay)
+     * counts once, and its initial user message once unless deferred.
+     */
+    metrics?: ProductUsageMetricsSink | null;
+    /** Optional content-free child spans; never a lifecycle dependency. */
+    startupObservability?: SessionStartObservability | null;
     /** Create the session shell without an initial user event/agent turn. */
     deferInitialTurn?: boolean;
-    turnInstructions?: string | null;
+    modelContext?: string | null;
     resources: ResourceRef[];
     skills?: SessionSkill[];
+    bundledSkillIds?: import("@opengeni/contracts").BundledSkillId[] | undefined;
     tools: ToolRef[];
     toolPolicy: SessionToolPolicy;
     clientEventId?: string;
@@ -96,34 +176,63 @@ export declare function createAndStartSessionWithOutcome(input: {
     createdByActor?: Extract<SessionCommandActor, {
         type: "agent_attempt";
     }> | null;
-    variableSet?: {
+    variableSets?: Array<{
         id: string;
         name: string;
-    } | null;
+        scope: VariableSet["scope"];
+    }>;
     rigId?: string | null;
     rigVersionId?: string | null;
     channelId?: string | null;
     goal?: GoalSpec | null;
+    /** Trusted sensitive-safe automatic title for an agent-created child. The
+     * atomic initializer commits the row mutation and `session.title_set`. */
+    initialAutomaticTitle?: string | null;
     instructions?: string | null;
     policyRole?: string | null;
     firstPartyMcpPermissions?: Permission[] | null;
     firstPartyMcpTools: FirstPartyMcpToolName[];
+    agentConfig?: ResolvedAgentConfig | null;
+    agentAccess?: SessionAgentAccess;
+    scopeSubjectId?: SessionScopeSubjectId | null;
+    memoryScope?: SessionMemoryScope;
     mcpServers?: CreateSessionMcpServerInput[];
+    mcpApprovalPolicies?: Record<string, SessionMcpApprovalPolicy>;
     sessionMcpServers?: SessionMcpServerMetadata[];
     personalConnectionDelegations?: McpPersonalConnectionDelegation[];
+    mcpAccountBindings?: McpConnectionAccountBinding[] | null;
+    initialPersonalResourceAttachmentIntent?: PersonalResourceAttachmentIntent | null;
     xaiProviderAccountAuthoritySnapshot?: XaiProviderAccountAuthoritySnapshotV1;
+    claudeProviderAccountAuthoritySnapshot?: ClaudeProviderAccountAuthoritySnapshotV1;
     parentSessionId?: string | null;
+    codeSearchDeploymentPolicy?: CodeSearchDeploymentPolicy;
     createIdempotencyKey?: string | null;
+    selectedInstalledSkillIds?: string[];
     sandboxGroupId?: string | null;
     sandboxOs?: Session["sandboxOs"];
     seedTargetSandbox?: {
         sandboxId: string;
         settings: Settings;
         workingDir?: string | null;
+        resourceSubjectId?: string | null;
     } | null;
     consumeNewSessionDraft?: {
         subjectId: string;
         expectedRevision: number;
+        expectedSnapshot: NewSessionDraftSnapshot;
+        acceptedSelection: {
+            channelId: string | null;
+            targetSandboxId: string | null;
+            workingDir: string | null;
+        };
+    } | null;
+    rememberNewSessionSelection?: {
+        subjectId: string;
+        acceptedSelection: {
+            channelId: string | null;
+            targetSandboxId: string | null;
+            workingDir: string | null;
+        };
     } | null;
     maxNestedAgentDepthOverride?: number | null;
     allowNestedAgentDepthIncrease?: boolean;
@@ -132,6 +241,13 @@ export declare function createAndStartSessionWithOutcome(input: {
 /** Backward-compatible entity-returning create path used by existing callers. */
 export declare function createAndStartSession(input: Parameters<typeof createAndStartSessionWithOutcome>[0]): Promise<CreateSessionResponse>;
 export declare function workflowIdForSession(sessionId: string): string;
+/**
+ * The one 422 for a model that is not selectable in the live catalog (retired,
+ * removed, or never offered). The message keeps its historical text; the typed
+ * cause lets the API envelope add `details.code: "model_unavailable"` so
+ * clients can ask for another model instead of offering a futile retry.
+ */
+export declare function modelUnavailableHttpException(model: string): HTTPException;
 /**
  * Reject an explicit model that the host does not expose. The set of usable
  * models is the union surfaced by `configuredAllowedModels` (the built-in
@@ -140,8 +256,9 @@ export declare function workflowIdForSession(sessionId: string): string;
  * the API edge with 422 rather than enqueuing a turn the worker can't honor.
  *
  * `model` is the effective value selected by the caller's boundary. Top-level
- * omission defaults to `settings.openaiModel`; child-session omission inherits
- * the worker-signed calling turn before reaching this helper. Centralized here
+ * omission resolves the new-chat default (`resolveDefaultSessionModel`);
+ * child-session omission inherits the worker-signed calling turn before
+ * reaching this helper. Centralized here
  * so every model-carrying choke point
  * (create-session, user-message/turn-accept, queued-turn update, and
  * scheduled-task agentConfig — a scheduled task is a session the worker runs
@@ -168,15 +285,13 @@ export declare function assertSessionAllowsProductModel(session: Pick<Session, "
  * worker's authoritative post-resolution gate would fail. `model` is the
  * EFFECTIVE value the caller is about to persist: pass the explicit value at
  * message/turn-update/scheduled-task edges (omitted inherits an
- * already-validated stored default), but at session CREATION pass
- * `payload.model ?? settings.openaiModel` — an omitted model stamps the
- * deployment default onto the session, and under a restricted policy that
- * default may be exactly the provider the policy exists to block.
+ * already-validated stored default), but at session CREATION pass the
+ * effective model: an omitted model stamps the resolved default onto the
+ * session, and under a restricted policy that default may be exactly the
+ * provider the policy exists to block.
  */
 export declare function assertWorkspaceModelPolicyAllows(db: Database, settings: Settings, workspaceId: string, model: string | null | undefined): Promise<void>;
 export declare function requireQueuedTurnForApi(db: Database, workspaceId: string, sessionId: string, turnId: string): Promise<SessionTurn>;
-export declare function reasoningEffortForSession(metadata: Record<string, unknown>, fallback: Settings["openaiReasoningEffort"]): Settings["openaiReasoningEffort"];
-export declare function latencyModeForSession(metadata: Record<string, unknown>, fallback?: "standard" | "priority" | "fast"): "standard" | "priority" | "fast";
 /**
  * Appends a `user.message` to an existing session and enqueues the resulting
  * turn, merging requested resources/tools into the session and waking the
@@ -184,7 +299,16 @@ export declare function latencyModeForSession(metadata: Record<string, unknown>,
  * `session_send_message` tool so the two surfaces cannot drift. Callers own
  * resource/tool validation and the per-message usage limit before calling.
  */
-export declare function postUserMessageTurn(input: {
+type PostUserMessageTurnResult = {
+    accepted: SessionEvent;
+    turn: SessionTurn;
+    draft: ComposerDraft | null;
+    receipt: SessionCommandReceipt;
+    routing: SessionPromptRouting;
+    interruptionCount: number;
+    replay: boolean;
+};
+type PostUserMessageTurnInput = {
     db: Database;
     bus: EventBus;
     workflowClient: Pick<SessionWorkflowClient, "wakeSessionWorkflow">;
@@ -194,45 +318,84 @@ export declare function postUserMessageTurn(input: {
     sessionId: string;
     text: string;
     annotations?: TimelineAnnotation[];
-    turnInstructions?: string | null;
+    modelContext?: string | null;
     resources: ResourceRef[];
+    /** Actor-owned resources used only for the exact durable-draft fence. */
+    composerDraftResources?: ResourceRef[];
     model?: string | null;
     reasoningEffort?: Settings["openaiReasoningEffort"] | null;
     latencyMode?: "standard" | "priority" | "fast" | null;
     clientEventId?: string;
     mcpCredentialUpdates?: UpdateSessionMcpServerCredentialsInput[];
     personalConnectionDelegations?: McpPersonalConnectionDelegation[];
+    mcpAccountBindings?: McpConnectionAccountBinding[] | null;
+    captureTurnAuthority?: (tx: Database, turnId: string) => Promise<void>;
+    personalResourceAttachment?: PersonalResourceAttachmentIntent;
     delivery?: "send" | "steer";
     origin?: "human" | "operator";
+    /** Content-free product surface the request entered through. */
+    surface?: SessionTurnSurface | null;
     actor?: string;
     actorLabel?: string;
     commandActor?: SessionCommandActor;
     controlEtag?: string | null;
     expectedDraftRevision?: number | null;
+    boundaryRequestHash?: string;
     reasoningEffortFallback?: Settings["openaiReasoningEffort"];
     turnExecutionPolicy: TurnExecutionPolicyV1;
     recordAgentRunUsage?: boolean;
     schedulePostCommit?: (task: () => Promise<void>) => void;
-}): Promise<{
-    accepted: SessionEvent;
-    turn: SessionTurn;
-    interruptionCount: number;
-    replay: boolean;
-}>;
+};
+export declare function postUserMessageTurn(input: PostUserMessageTurnInput): Promise<PostUserMessageTurnResult>;
 /**
  * Full create-session flow shared by `POST /sessions` and the first-party MCP
  * `session_create` tool: payload validation, resource/tool/variableSet
  * checks, usage limits, session start, and usage recording. `rawPayload` is
  * the unparsed request body so absent-vs-empty execution-context fields keep
- * their meaning: a child inherits omitted resources/tools/mcpServers from its
- * trusted immediate parent, while explicit arrays (including []) win. A
+ * their meaning: a child inherits repositories (never files), tools, and MCP
+ * servers from its trusted immediate parent when omitted; explicit arrays
+ * (including []) win. A
  * top-level create with omitted tools applies workspace-default capability MCPs.
  */
-export declare function createSessionForRequestWithOutcome(deps: ApiRouteDeps, grant: AccessGrant, workspaceId: string, rawPayload: unknown): Promise<CreateSessionRequestOutcome>;
+export declare function resolveChildGoalFromAcceptedSnapshot(goal: GoalSpec, parentGoalSnapshot: SessionGoalSnapshot): GoalSpec;
+export declare function resolveSessionCreateVisibility(input: {
+    requestedVisibility: "private" | "workspace";
+    visibilityProvided: boolean;
+    parentVisibility: "user_private" | "workspace_shared" | null;
+}): "user_private" | "workspace_shared";
+export type SessionCreateScope = {
+    agentAccess: SessionAgentAccess;
+    scopeSubjectId: SessionScopeSubjectId | null;
+    memoryScope: SessionMemoryScope;
+};
+/**
+ * Resolve a new session's agent-access scope, end-user label, and Memory
+ * selector (migration 0427). A top-level request takes its own values. An
+ * agent-created child inherits every omitted value from its trusted parent
+ * and may only NARROW an explicit one: agent access workspace > user >
+ * session, memory workspace > user > session > off, and the label must equal
+ * the parent's. Widening is a 403 because the parent's declared reach is a
+ * security boundary the child's own request cannot cross; a memory `user`
+ * selector without a label is a 422 in either position.
+ */
+export declare function resolveSessionCreateScope(input: {
+    requested: {
+        agentAccess: SessionAgentAccess;
+        agentAccessProvided: boolean;
+        scopeSubjectId: SessionScopeSubjectId | null;
+        endUserProvided: boolean;
+        memoryScope: SessionMemoryScope;
+        memoryScopeProvided: boolean;
+    };
+    parent: SessionCreateScope | null;
+}): SessionCreateScope;
+/** Explicit recovery, never a new prompt or a Pause/Resume command. */
+export declare function retryFailedSession(deps: ApiRouteDeps, grant: AccessGrant, workspaceId: string, sessionId: string, request: SessionRetryRequest): Promise<SessionRetryResponse>;
+declare function createSessionForRequestInFileScope(unresolvedDeps: ApiRouteDeps, grant: AccessGrant, workspaceId: string, rawPayload: unknown, authorization?: AccessGrantAuthorization, agentChildPresentation?: AgentChildSessionCreatePresentation, requestOptions?: SessionCreateRequestOptions): Promise<CreateSessionRequestOutcome>;
 /** @internal Fixed public projection; the committed session outcome remains authoritative. */
 export declare function reportSessionUsageRecordingFailure(_error: unknown): void;
 /** Backward-compatible entity-returning request path for REST and core callers. */
-export declare function createSessionForRequest(deps: ApiRouteDeps, grant: AccessGrant, workspaceId: string, rawPayload: unknown): Promise<CreateSessionResponse>;
+export declare function createSessionForRequest(deps: ApiRouteDeps, grant: AccessGrant, workspaceId: string, rawPayload: unknown, authorization?: AccessGrantAuthorization, requestOptions?: SessionCreateRequestOptions): Promise<CreateSessionResponse>;
 /**
  * Full accept-user-message flow shared by the `user.message` branch of
  * `POST /sessions/:id/events` and the first-party MCP `session_send_message`
@@ -240,23 +403,36 @@ export declare function createSessionForRequest(deps: ApiRouteDeps, grant: Acces
  * enqueue, and usage recording. `toolsProvided: false` durably preserves an
  * Tool selection is durable session state and never rides a follow-up prompt.
  */
-export declare function acceptSessionUserMessageWithOutcome(deps: AcceptSessionUserMessageDependencies, grant: AccessGrant, workspaceId: string, sessionId: string, input: {
+declare function acceptSessionUserMessageInFileScope(deps: AcceptSessionUserMessageDependencies, grant: AccessGrant, workspaceId: string, sessionId: string, input: {
     text: string;
     annotations?: SubmittedTimelineAnnotation[];
-    turnInstructions?: string | null;
+    modelContext?: string | null;
     resources?: ResourceRef[];
+    /** Actor-owned resources used only for the exact durable-draft fence. */
+    composerDraftResources?: ResourceRef[];
     model?: string | null;
     reasoningEffort?: ReasoningEffort | null;
     latencyMode?: "standard" | "priority" | "fast" | null;
     clientEventId?: string;
     mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[];
+    connectionAccounts?: McpConnectionAccountSelection[];
     delivery?: "send" | "steer";
     origin?: "human" | "operator";
+    /**
+     * Product surface when the entry point knows it (for example Slack or an
+     * in-process embedding host). Omitted derives it from the grant.
+     */
+    surface?: SessionTurnSurface;
     controlEtag?: string | null;
     expectedDraftRevision?: number | null;
+    personalResourceAttachment?: PersonalResourceAttachmentIntent;
+    authorization?: AccessGrantAuthorization;
 }): Promise<{
     accepted: SessionEvent;
     turn: SessionTurn;
+    draft: ComposerDraft | null;
+    receipt: SessionCommandReceipt;
+    routing: SessionPromptRouting;
     interruptionCount: number;
     replay: boolean;
 }>;
@@ -264,6 +440,8 @@ export declare function acceptSessionUserMessageWithOutcome(deps: AcceptSessionU
 export declare function acceptSessionUserMessage(deps: Parameters<typeof acceptSessionUserMessageWithOutcome>[0], grant: Parameters<typeof acceptSessionUserMessageWithOutcome>[1], workspaceId: Parameters<typeof acceptSessionUserMessageWithOutcome>[2], sessionId: Parameters<typeof acceptSessionUserMessageWithOutcome>[3], input: Parameters<typeof acceptSessionUserMessageWithOutcome>[4]): Promise<{
     accepted: SessionEvent;
     turn: SessionTurn;
+    receipt: SessionCommandReceipt;
+    routing: SessionPromptRouting;
     interruptionCount: number;
     replay: boolean;
 }>;
@@ -285,6 +463,18 @@ export declare function updateSessionTitle(deps: {
     title: string | null;
     relatedSessionAccess: "target" | "root";
 }>;
+/** Change future defaults without accepting a prompt or touching accepted work. */
+export declare function setSessionModel(deps: Pick<ApiRouteDeps, "db" | "bus" | "settings" | "catalogSourceSettings" | "sessionAuthorization">, grant: AccessGrant, sessionId: string, request: SetSessionModelRequest, surface?: SessionAuthorizationSurface): Promise<{
+    model: string;
+    reasoningEffort: "high" | "low" | "max" | "medium" | "minimal" | "none" | "xhigh";
+    latencyMode: "fast" | "priority" | "standard";
+    eventId: string;
+    receiptId: string;
+    timestamp: string;
+    replay: boolean;
+    sessionId: string;
+    effectiveFrom: "future_turns";
+}>;
 /**
  * Update one existing session MCP server's approval policy. The database
  * serializes this write with attempt claim under the session lock: an already
@@ -308,4 +498,61 @@ export declare function updateSessionToolPolicy(deps: {
     settings: Settings;
     sessionAuthorization?: SessionAuthorizationPort | null;
 }, grant: AccessGrant, sessionId: string, request: UpdateSessionToolPolicyRequest): Promise<Session>;
+/**
+ * Replace a running session's agent configuration (`PUT .../agent`). Omitted
+ * request fields keep their current values; a legacy (null) session converts
+ * from its current effective state without widening. The configuration and
+ * its write-through to the legacy tool columns (and the instructions alias)
+ * commit under the same tool-policy version CAS, so tool-policy and agent
+ * updates cannot race. Effective from the next attempt. Agent callers may only
+ * narrow; a child never widens past its parent.
+ */
+export declare function updateSessionAgent(deps: {
+    db: Database;
+    bus: EventBus;
+    settings: Settings;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+}, grant: AccessGrant, sessionId: string, request: UpdateSessionAgentRequest): Promise<Session>;
 export declare function readSessionLineage(deps: Pick<ApiRouteDeps, "db" | "sessionAuthorization">, grant: AccessGrant, sessionId: string): Promise<import("@opengeni/db").SessionLineage>;
+/**
+ * A server attached in the same root create request is selected by that
+ * attachment. Neither `tools` (an allow-list over the workspace/deployment
+ * registry) nor the workspace-default expansion can name it, so without this
+ * the attached endpoint was stored but never contacted and the model saw no
+ * tools. This grants nothing beyond the attach itself: the caller already
+ * passed `mcp_servers:attach` for exactly this endpoint, and the server's own
+ * approval policy still governs every call. An explicit ref for the same id
+ * wins unchanged so a caller can still mark it `eager` or `optional`; the
+ * added ref is strict, exactly like listing `{ kind: "mcp", id }` explicitly.
+ * Child creates never reach here: an inherited snapshot keeps the parent's
+ * selection and a child may only narrow it.
+ */
+export declare function withSameRequestSessionMcpServerTools(tools: ToolRef[], attachedServers: ReadonlyArray<{
+    id: string;
+}>): ToolRef[];
+/**
+ * The executable MCP tool list a follow-up on an existing session freezes
+ * connector accounts against.
+ *
+ * A `workspace_default` session stores only the tool snapshot taken when it
+ * was created and expands the current workspace defaults at run time, so a
+ * connector enabled after creation never enters the stored column. The
+ * composer projects that same expansion and submits account selections for
+ * it, so freezing against the stored column rejected every such selection as
+ * unmatched and never froze its personal delegation. Resolve through the one
+ * ID-only policy resolver the API projection and the worker use, with the
+ * same omitted-tools default, so all three agree on the executable set.
+ */
+export declare function sessionToolsForConnectionAccounts(input: {
+    session: Pick<Session, "tools" | "toolPolicy">;
+    /** The resolved runtime registry, including session-local servers. */
+    runtimeMcpServers: Iterable<{
+        id: string;
+    }>;
+    /** The current omitted-tools default for this workspace. */
+    defaultMcpServerIds: Iterable<string>;
+}): ToolRef[];
+/** Keep original-file ownership scoped across admission, history hydration and setup. */
+export declare function createSessionForRequestWithOutcome(...args: Parameters<typeof createSessionForRequestInFileScope>): Promise<CreateSessionRequestOutcome>;
+export declare function acceptSessionUserMessageWithOutcome(...args: Parameters<typeof acceptSessionUserMessageInFileScope>): ReturnType<typeof acceptSessionUserMessageInFileScope>;
+export {};

package/dist/domain/skill-imports.d.ts

@@ -8,6 +8,7 @@ export type GitHubSkillTreeEntry = Readonly<{
     size: number | null;
 }>;
 export type GitHubSkillSourceClient = Readonly<{
+    downloadSnapshot?(owner: string, repository: string, slug: string): Promise<readonly SkillLibraryFile[]>;
     resolveCommit(owner: string, repository: string, ref: string): Promise<string>;
     listTree(owner: string, repository: string, commit: string): Promise<readonly GitHubSkillTreeEntry[]>;
     readBlob(owner: string, repository: string, sha: string): Promise<Uint8Array>;

package/dist/domain/skill-search.d.ts

@@ -0,0 +1,30 @@
+import type { Settings } from "@opengeni/config";
+import { pinnedFetch } from "@opengeni/network";
+export type PublicSkillSearchInput = Readonly<{
+    query: string;
+    limit?: number;
+    owner?: string;
+}>;
+export type PublicSkillSearchResult = Readonly<{
+    provider: "skills_sh";
+    query: string;
+    items: readonly Readonly<{
+        id: string;
+        name: string;
+        source: string;
+        skillId: string;
+        url: string;
+        installs: number;
+    }>[];
+    nextCursor: null;
+}>;
+export type PublicSkillSearchClient = Readonly<{
+    search(input: PublicSkillSearchInput): Promise<PublicSkillSearchResult>;
+}>;
+export type PublicSkillSearchErrorCode = "invalid_query" | "rate_limited" | "timeout" | "unavailable" | "invalid_response";
+export declare class PublicSkillSearchError extends Error {
+    readonly code: PublicSkillSearchErrorCode;
+    readonly retryAfterSeconds: number | null;
+    constructor(code: PublicSkillSearchErrorCode, message: string, retryAfterSeconds?: number | null);
+}
+export declare function createPublicSkillSearchClient(settings: Settings, fetcher?: typeof pinnedFetch): PublicSkillSearchClient;

package/dist/domain/skills.d.ts

@@ -0,0 +1,117 @@
+import type { SkillFile, SkillInstallInput, SkillRevisionInput, SkillSaveInput, SkillRemoveInput } from "@opengeni/contracts";
+import { listSkillRecords, type Database, type SkillReadContext } from "@opengeni/db";
+export { replayPortableSkillInstall } from "@opengeni/db";
+/** Canonical text-only folder; rejects invalid Unicode before PostgreSQL conversion. */
+export declare function validateSkillFiles(files: readonly SkillFile[]): SkillFile[];
+/** Separate from the historical SKILL.md hash, which must never be rewritten. */
+export declare function skillBundleHash(files: readonly SkillFile[]): string;
+export declare const listSkills: typeof listSkillRecords;
+export declare function removeSkill(db: Database, input: SkillRemoveInput): Promise<{
+    removed?: boolean | undefined;
+    operationId: string;
+    skillId: string;
+    revisionId: string;
+    outcome: "applied" | "pending" | "preserved";
+    decision?: "rejected" | undefined;
+    pendingReason?: "approval" | "source_finalization" | undefined;
+    skillReview?: {
+        removalOperationId?: string | undefined;
+        sourceOperationId: string;
+        skillId: string;
+        revisionId: string;
+        expectedRevisionId: string | null;
+        expectedScopeVersion: number;
+    } | undefined;
+    replayed: boolean;
+}>;
+export declare function readSkill(db: Database, context: SkillReadContext, skillId: string, revisionId?: string): Promise<import("@opengeni/contracts").SkillRecord | null>;
+export declare function saveSkill(db: Database, input: SkillSaveInput): Promise<{
+    removed?: boolean | undefined;
+    operationId: string;
+    skillId: string;
+    revisionId: string;
+    outcome: "applied" | "pending" | "preserved";
+    decision?: "rejected" | undefined;
+    pendingReason?: "approval" | "source_finalization" | undefined;
+    skillReview?: {
+        removalOperationId?: string | undefined;
+        sourceOperationId: string;
+        skillId: string;
+        revisionId: string;
+        expectedRevisionId: string | null;
+        expectedScopeVersion: number;
+    } | undefined;
+    replayed: boolean;
+}>;
+export declare function installSkill(db: Database, input: SkillInstallInput): Promise<{
+    removed?: boolean | undefined;
+    operationId: string;
+    skillId: string;
+    revisionId: string;
+    outcome: "applied" | "pending" | "preserved";
+    decision?: "rejected" | undefined;
+    pendingReason?: "approval" | "source_finalization" | undefined;
+    skillReview?: {
+        removalOperationId?: string | undefined;
+        sourceOperationId: string;
+        skillId: string;
+        revisionId: string;
+        expectedRevisionId: string | null;
+        expectedScopeVersion: number;
+    } | undefined;
+    replayed: boolean;
+}>;
+export declare function approveSkill(db: Database, input: SkillRevisionInput): Promise<{
+    removed?: boolean | undefined;
+    operationId: string;
+    skillId: string;
+    revisionId: string;
+    outcome: "applied" | "pending" | "preserved";
+    decision?: "rejected" | undefined;
+    pendingReason?: "approval" | "source_finalization" | undefined;
+    skillReview?: {
+        removalOperationId?: string | undefined;
+        sourceOperationId: string;
+        skillId: string;
+        revisionId: string;
+        expectedRevisionId: string | null;
+        expectedScopeVersion: number;
+    } | undefined;
+    replayed: boolean;
+}>;
+export declare function rejectSkill(db: Database, input: SkillRevisionInput): Promise<{
+    removed?: boolean | undefined;
+    operationId: string;
+    skillId: string;
+    revisionId: string;
+    outcome: "applied" | "pending" | "preserved";
+    decision?: "rejected" | undefined;
+    pendingReason?: "approval" | "source_finalization" | undefined;
+    skillReview?: {
+        removalOperationId?: string | undefined;
+        sourceOperationId: string;
+        skillId: string;
+        revisionId: string;
+        expectedRevisionId: string | null;
+        expectedScopeVersion: number;
+    } | undefined;
+    replayed: boolean;
+}>;
+export declare function restoreSkill(db: Database, input: SkillRevisionInput): Promise<{
+    removed?: boolean | undefined;
+    operationId: string;
+    skillId: string;
+    revisionId: string;
+    outcome: "applied" | "pending" | "preserved";
+    decision?: "rejected" | undefined;
+    pendingReason?: "approval" | "source_finalization" | undefined;
+    skillReview?: {
+        removalOperationId?: string | undefined;
+        sourceOperationId: string;
+        skillId: string;
+        revisionId: string;
+        expectedRevisionId: string | null;
+        expectedScopeVersion: number;
+    } | undefined;
+    replayed: boolean;
+}>;