@opengeni/core 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,735 @@
+import { Settings } from '@opengeni/config';
+import { ScheduledTask, Document, Permission, AccessContext, AccessGrant, LimitAction, LimitDecision, CapabilityCatalogResponse, CreateCapabilityCatalogItemRequest, CapabilityCatalogItem, CapabilityInstallation, EnableCapabilityRequest, WorkspaceEnvironment, CapabilityPack, SocialConnection, ScheduledTaskAgentConfig, ToolRef, ResourceRef, CreateScheduledTaskRequest, UpdateScheduledTaskRequest, ReasoningEffort, SessionEvent, SessionTurn, GoalSpec, Session, WorkspaceMember } from '@opengeni/contracts';
+export { mergeToolRefs, stableJson } from '@opengeni/contracts';
+import { Database, SandboxRecord, EnabledMcpCapabilityServer, UpdateScheduledTaskInput } from '@opengeni/db';
+import { DocumentServices } from '@opengeni/documents';
+import { EventBus } from '@opengeni/events';
+import { Observability } from '@opengeni/observability';
+import { createObjectStorage } from '@opengeni/storage';
+import { Auth } from 'better-auth';
+import { SelfhostedRelayConfig, EstablishedSandboxSession } from '@opengeni/runtime/sandbox';
+import { Context } from 'hono';
+
+type ManagedAuth = Auth<any>;
+
+type ApiSandboxSession = {
+    state?: Record<string, unknown> & {
+        sandboxId?: string;
+    };
+    running?(): Promise<boolean>;
+    exec?(args: {
+        cmd: string;
+        workdir?: string;
+        runAs?: string;
+        yieldTimeMs?: number;
+        maxOutputTokens?: number;
+    }): Promise<unknown>;
+    execCommand?(args: {
+        cmd: string;
+        workdir?: string;
+        runAs?: string;
+        yieldTimeMs?: number;
+        maxOutputTokens?: number;
+    }): Promise<string>;
+    shutdown?(options?: unknown): Promise<void>;
+    delete?(options?: unknown): Promise<void>;
+    close?(): Promise<void>;
+};
+type ApiSandboxClient = {
+    backendId: string;
+    deserializeSessionState?(state: Record<string, unknown>): Promise<unknown>;
+    resume?(state: unknown, options?: unknown): Promise<ApiSandboxSession>;
+    delete?(state: unknown): Promise<void>;
+};
+type ResumeBoxByIdInput = {
+    /**
+     * The backend the box was created on — the lease's `resume_backend_id`. Must
+     * match the API's configured sandbox client backendId, or the resume is
+     * rejected (a cross-backend envelope can never deserialize correctly).
+     */
+    backend: string;
+    /**
+     * The serialized resume-state envelope — the lease's `resume_state` jsonb
+     * (the record produced by `client.serializeSessionState(state)`). This is the
+     * box identity + reattach descriptor; resume() reattaches to the live box by
+     * id (warm reattach) or cold-restores from its snapshot.
+     */
+    resumeState: Record<string, unknown>;
+};
+/**
+ * A live, resumed sandbox session for a SINGLE in-process op. The caller
+ * resumes → uses (exec/readFile/resolvePort) → drops it; lifecycle/refcount is
+ * the lease's job (P1.x), NOT this handle's. The session is non-owned by
+ * construction (resume-by-id never owns the box), so dropping it does not
+ * terminate the box.
+ */
+type ResumedSandboxSession = ApiSandboxSession;
+
+type SessionWorkflowClient = {
+    signalUserMessage: (input: {
+        sessionId: string;
+        eventId: string;
+        workflowId: string;
+    }) => Promise<void>;
+    wakeSessionWorkflow: (input: {
+        accountId: string;
+        workspaceId: string;
+        sessionId: string;
+        workflowId: string;
+    }) => Promise<void>;
+    signalApprovalDecision: (input: {
+        sessionId: string;
+        eventId: string;
+        workflowId: string;
+    }) => Promise<void>;
+    signalInterrupt: (input: {
+        accountId: string;
+        workspaceId: string;
+        sessionId: string;
+        eventId: string;
+        workflowId: string;
+    }) => Promise<void>;
+    syncScheduledTask: (input: {
+        task: ScheduledTask;
+    }) => Promise<void>;
+    deleteScheduledTaskSchedule: (input: {
+        temporalScheduleId: string;
+    }) => Promise<void>;
+    triggerScheduledTask: (input: {
+        task: ScheduledTask;
+        agentRunUsageIdempotencyKey?: string;
+        triggerWorkflowId?: string;
+    }) => Promise<void>;
+};
+type DocumentIndexClient = {
+    indexDocument: (input: {
+        accountId: string;
+        workspaceId: string;
+        documentId: string;
+    }) => Promise<Document | void>;
+};
+type AppDependencies = {
+    settings: Settings;
+    db: Database;
+    bus: EventBus;
+    workflowClient: SessionWorkflowClient;
+    documentIndexer?: DocumentIndexClient;
+    documentServices?: DocumentServices;
+    observability?: Observability;
+    githubStateSecret?: string;
+    managedAuth?: ManagedAuth | null;
+    sandboxClient?: ApiSandboxClient;
+    /**
+     * Resume a box by id from a serialized resume_state envelope (the lease's
+     * `resume_state` + `resume_backend_id` from P1.1) and return a live session
+     * for a single in-process op. resume → use → drop; the lease owns lifecycle,
+     * the returned handle does NOT own the box. Throws SandboxResumeError on a
+     * backend mismatch or a resume failure.
+     */
+    resumeBoxById?: (input: ResumeBoxByIdInput) => Promise<ResumedSandboxSession>;
+};
+type ObjectStorageDependency = ReturnType<typeof createObjectStorage>;
+type ApiRouteDeps = AppDependencies & {
+    objectStorage: ObjectStorageDependency;
+    githubStateSecret: string;
+    documentIndexer: DocumentIndexClient;
+    getDocumentServices: () => DocumentServices;
+    resumeBoxById: (input: ResumeBoxByIdInput) => Promise<ResumedSandboxSession>;
+};
+
+type FleetServices = {
+    db: Database;
+    settings: Settings;
+    bus?: EventBus;
+};
+type FleetContext = {
+    accountId: string;
+    workspaceId: string;
+    /** The calling session (the pointer the attach/swap mutates + whose group box
+     *  is the default fleet member). */
+    sessionId: string;
+    /** The session's own group sandbox backend (modal/selfhosted/…). */
+    sessionBackend: string;
+    /** The session's own group sandbox id (the lease group). */
+    sessionGroupId: string;
+};
+/**
+ * Build a session-scoped {@link FleetContext}: load the session (workspace-
+ * scoped), reject a session with no box (backend:none — the fleet is only
+ * meaningful for a sandboxed session), and project its group backend/id. Shared
+ * by the worker-signed MCP fleet tools and the user-authenticated swap REST
+ * route so both resolve the SAME context (no drift). The `accountId`/`workspaceId`/
+ * `sessionId` come from the trusted grant/route; the backend + group id come from
+ * the session row.
+ */
+declare function buildFleetContextForSession(deps: {
+    db: Database;
+}, ctx: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+}): Promise<FleetContext>;
+/** The dominant liveness of a fleet member, surfaced to the dock + the agent. */
+type FleetLiveness = "online" | "reconnecting" | "offline";
+/**
+ * A fleet member as the agent + the dock see it (the M8b/M9 UI seam — the
+ * `sandboxes_list` response entry the dock renders). STABLE shape: the dock keys
+ * on `id`, renders `name`/`kind`/`liveness`, and marks `active`. The session's own
+ * Modal group box is a synthetic entry with `id: groupId`, `kind: "modal"`, and a
+ * null `enrollmentId`; an enrolled machine carries its sandbox + enrollment ids.
+ */
+type FleetSandboxEntry = {
+    /** The sandbox id used as the attach/swap/run_on `target`. For the session's
+     *  own group box this is the group id (a null active pointer == this box). */
+    id: string;
+    kind: "modal" | "selfhosted";
+    name: string;
+    liveness: FleetLiveness;
+    /** True for the session's currently-active sandbox (the routing target). */
+    active: boolean;
+    /** True for the session's own group box (the default/home sandbox). */
+    isSessionGroup: boolean;
+    enrollmentId: string | null;
+    /** Whether this target can be attached/swapped to right now (live + addressable). */
+    attachable: boolean;
+    /** Selfhosted only: whether whole-machine + screen-control consent is acked. */
+    consented?: boolean;
+    /** Selfhosted only: whether a display (real/Xvfb) is present. */
+    hasDisplay?: boolean;
+    lastSeenAt?: string | null;
+};
+type FleetListResult = {
+    /** The session's currently-active sandbox id, or null == the group box. */
+    activeSandboxId: string | null;
+    activeEpoch: number;
+    sandboxes: FleetSandboxEntry[];
+};
+/** A swap/attach outcome the tool returns. */
+type FleetSwapResult = {
+    swapped: boolean;
+    activeSandboxId: string | null;
+    activeEpoch: number;
+    reason?: string;
+};
+/**
+ * List the fleet: the session's own Modal group box (a synthetic entry) + the
+ * workspace's first-class selfhosted sandboxes (each probed for liveness), each
+ * with an `active` marker derived from the session's active pointer.
+ */
+declare function listFleet(services: FleetServices, ctx: FleetContext): Promise<FleetListResult>;
+/**
+ * THE SWAP (and attach — identical mechanic). Validate the target's ownership +
+ * liveness, then repoint the session via the epoch-fenced CAS `setActiveSandbox`:
+ * read the current epoch, then CAS on it. A concurrent double-swap lets exactly
+ * one win; the loser re-reads + may retry. The bumped epoch fences any in-flight
+ * op cached against the old pointer, which then retries against the new active
+ * sandbox (the routing proxy's fenced-retry role).
+ */
+declare function swapActiveSandbox(services: FleetServices, ctx: FleetContext, target: string, workingDir?: string | null): Promise<FleetSwapResult>;
+type RunOnOp = {
+    kind: "exec";
+    cmd: string;
+    workdir?: string;
+} | {
+    kind: "read";
+    path: string;
+} | {
+    kind: "write";
+    path: string;
+    content: string;
+};
+type RunOnResult = {
+    target: string;
+    kind: string;
+    ok: boolean;
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number | null;
+    content?: string;
+    bytesWritten?: number;
+    reason?: string;
+};
+/**
+ * Run a ONE-OFF op against a SPECIFIC target WITHOUT changing the active pointer
+ * (the dossier `run_on`). Only selfhosted targets are routable as a one-off here
+ * (a Modal target is the session's group box, reached via the normal Channel-A /
+ * turn path — `run_on` is for reaching a NON-active enrolled machine without
+ * swapping). The op is fenced under the target's enrollment, addressed to its
+ * agent subject; an offline machine surfaces a clear reason, never a wrong-box
+ * landing.
+ */
+declare function runOnSandbox(services: FleetServices, ctx: FleetContext, target: string, op: RunOnOp): Promise<RunOnResult>;
+type ProvisionResult = {
+    kind: "selfhosted";
+    instructions: string;
+    installCommandUnix: string;
+    installCommandWindows: string;
+    verificationUri: string;
+    note: string;
+} | {
+    kind: "modal";
+    sandbox: SandboxRecord;
+    note: string;
+};
+/**
+ * Provision a new fleet member.
+ *   - selfhosted → return the device-flow enrollment instructions (the agent
+ *     surfaces them to a HUMAN, who installs the agent + enrolls — the agent
+ *     cannot click the loud whole-machine consent itself).
+ *   - modal → create a first-class named modal `sandboxes` record (a swap target).
+ *     NOTE: the Modal BOX is materialized lazily when first swapped-to (Modal
+ *     lifecycle is owned by the lease — unchanged per dossier §21).
+ */
+declare function provisionSandbox(services: FleetServices, ctx: FleetContext, input: {
+    kind: "selfhosted" | "modal";
+    name?: string;
+}): Promise<ProvisionResult>;
+
+type ChannelARoutingServices = {
+    db: Database;
+    settings: Settings;
+    bus?: EventBus;
+};
+/** Map the deployment relay URL to the leaf's `SelfhostedRelayConfig` shape. The
+ *  relay URL (`OPENGENI_SELFHOSTED_RELAY_URL`) may carry a path (the relay's wss
+ *  route); a path-less URL defaults to the relay's `/stream` route (M8b). */
+declare function relayConfigFromSettings(settings: Settings): SelfhostedRelayConfig;
+/** The canonical relay dial-BASE URL (`scheme://host[:port]/stream`) handed to the
+ *  agent PRODUCER. The agent's relay channel appends ONLY its routing query to
+ *  this base (`channel.rs`: `format!("{relay_url}{sep}{query}")`) and relies on the
+ *  base ALREADY carrying the relay's `/stream` route. `OPENGENI_SELFHOSTED_RELAY_URL`
+ *  is frequently pathless (e.g. `wss://relay.<env>.app.opengeni.ai`), which made the
+ *  producer dial a path-less URL the relay 400s. Derive the base from the SAME parser
+ *  the CONSUMER uses (`relayConfigFromSettings`) so producer + consumer always agree
+ *  on `/stream` — even when the configured URL omits it. An unconfigured relay maps to
+ *  `""` (graceful degrade: the agent reports no-relay rather than dialing a synthetic
+ *  host). Fixes preview AND managed prod with no agent rebuild (dossier §V5/§V6). */
+declare function relayDialBaseFromSettings(settings: Settings): string;
+/** Whether the routing proxy should wrap the Channel-A box: gated by the
+ *  selfhosted flag (the active pointer + swap are only meaningful then). */
+declare function routingEnabled(settings: Settings): boolean;
+/**
+ * Wrap an established group-box session in a `RoutingSandboxSession` so a
+ * Channel-A op routes to the session's currently-active sandbox. Returns the
+ * established handle with its `session` replaced by the stable proxy. With the
+ * default pointer (active_sandbox_id == null) this routes to the group box
+ * unchanged; a selfhosted active pointer routes the op to the machine.
+ */
+declare function wrapChannelABoxWithRouting(services: ChannelARoutingServices, ids: {
+    workspaceId: string;
+    sessionId: string;
+}, established: EstablishedSandboxSession): EstablishedSandboxSession;
+
+type AccessDeps = {
+    db: Database;
+    settings: Settings;
+    managedAuth?: ManagedAuth | null;
+};
+declare function requireAccessContext(c: Context, deps: AccessDeps): Promise<AccessContext>;
+declare function requireAccessGrant(c: Context, deps: AccessDeps, workspaceId: string, permission?: Permission): Promise<AccessGrant>;
+declare function requirePermission(grant: AccessGrant, permission: Permission): void;
+declare function hasPermission(permissions: Permission[], permission: Permission): boolean;
+
+type LimitCheckInput = {
+    accountId: string;
+    workspaceId?: string;
+    action: LimitAction;
+    quantity?: number;
+    model?: string | null;
+};
+declare function requireLimit(deps: ApiRouteDeps, input: LimitCheckInput): Promise<void>;
+declare function checkLimit(deps: ApiRouteDeps, input: LimitCheckInput): Promise<LimitDecision>;
+declare function recordWorkspaceUsage(deps: ApiRouteDeps, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId?: string | null;
+    eventType: "agent_run.created" | "file.uploaded" | "document.indexed" | "scheduled_task.fired";
+    quantity: number;
+    unit: string;
+    sourceResourceType: string;
+    sourceResourceId: string;
+    idempotencyKey: string;
+}): Promise<void>;
+
+declare const officialMcpRegistryUrl = "https://registry.modelcontextprotocol.io";
+declare function buildCapabilityCatalog(input: {
+    db: Database;
+    workspaceId: string;
+    settings: Settings;
+}): Promise<CapabilityCatalogResponse>;
+declare function createCatalogItem(input: {
+    db: Database;
+    accountId: string;
+    workspaceId: string;
+    payload: CreateCapabilityCatalogItemRequest;
+}): Promise<CapabilityCatalogItem>;
+declare function enableCapability(input: {
+    db: Database;
+    grant: AccessGrant;
+    accountId: string;
+    workspaceId: string;
+    settings: Settings;
+    capabilityId: string;
+    payload: EnableCapabilityRequest;
+    probeMcpServer?: McpCapabilityProbe;
+}): Promise<CapabilityInstallation>;
+type McpCapabilityProbeInput = {
+    id: string;
+    name: string;
+    url: string;
+    timeoutMs: number;
+    headers?: Record<string, string>;
+};
+type McpCapabilityProbeResult = {
+    toolCount: number;
+};
+type McpCapabilityProbe = (input: McpCapabilityProbeInput) => Promise<McpCapabilityProbeResult>;
+declare function validateMcpCapabilityConnection(item: CapabilityCatalogItem, probe?: McpCapabilityProbe, headers?: Record<string, string>): Promise<Record<string, unknown>>;
+declare function disableCapability(input: {
+    db: Database;
+    accountId: string;
+    workspaceId: string;
+    settings: Settings;
+    capabilityId: string;
+}): Promise<CapabilityInstallation>;
+declare function settingsWithEnabledCapabilityMcpServers(db: Database, workspaceId: string, settings: Settings): Promise<Settings>;
+declare function settingsWithMcpCapabilityServers(settings: Settings, enabled: EnabledMcpCapabilityServer[]): Settings;
+declare function discoverMcpRegistryCapabilities(input: {
+    query?: string;
+    limit?: number;
+    fetchImpl?: McpRegistryFetch;
+    timeoutMs?: number;
+}): Promise<CapabilityCatalogItem[]>;
+
+type McpRegistryFetch = (input: URL, init?: RequestInit) => Promise<Response>;
+
+declare const MAX_ENVIRONMENTS_PER_WORKSPACE = 25;
+declare const MAX_VARIABLES_PER_ENVIRONMENT = 100;
+declare function assertAllowedEnvironmentVariableName(name: string): void;
+declare function requireEnvironmentEncryption(settings: Settings): Uint8Array;
+declare function requireEnvironmentForApi(db: Database, workspaceId: string, environmentId: string): Promise<WorkspaceEnvironment>;
+/**
+ * Validates an environment attachment supplied in a request payload (session
+ * create, scheduled task create/update, pack enable). Requires the
+ * `environments:use` permission unless the attachment was already authorized
+ * (pack-installation-inherited attachments), and maps a missing or
+ * cross-workspace environment to 422 because the id is payload, not the route
+ * target. RLS plus the workspace_id clause make cross-workspace ids
+ * indistinguishable from missing ones.
+ */
+declare function validateEnvironmentAttachment(deps: {
+    settings: Settings;
+    db: Database;
+}, grant: AccessGrant, workspaceId: string, environmentId: string, options?: {
+    preauthorized?: boolean;
+}): Promise<WorkspaceEnvironment>;
+declare function recordEnvironmentAuditEvent(db: Database, input: {
+    grant: AccessGrant;
+    action: "environment.created" | "environment.updated" | "environment.deleted" | "environment.variable.set" | "environment.variable.deleted";
+    environmentId: string;
+    variableName?: string;
+}): Promise<void>;
+
+declare const MARKETING_SOCIAL_PACK_ID = "marketing-social-daily-analysis";
+declare function listCapabilityPacks(): CapabilityPack[];
+declare function getCapabilityPack(packId: string): CapabilityPack | null;
+declare function isBuiltInCapabilityPack(packId: string): boolean;
+/**
+ * Built-in packs plus the manifests registered for this workspace. Stored
+ * manifests were validated at registration time; rows that no longer parse
+ * (for example after a contract tightening) are skipped instead of breaking
+ * the whole catalog.
+ */
+declare function listWorkspaceCapabilityPacks(db: Database, workspaceId: string): Promise<CapabilityPack[]>;
+declare function resolveCapabilityPack(db: Database, workspaceId: string, packId: string): Promise<CapabilityPack | null>;
+/**
+ * v1 pack-scoped runtime rule: at most one enabled pack per workspace may
+ * declare a `sandboxImage` — there is deliberately no image composition or
+ * layering. Enforced when a pack is enabled (both the packs endpoint and the
+ * generic capability enable path) and re-checked at session start by the
+ * worker, which also covers manifests re-registered after enablement.
+ */
+declare function assertPackSandboxImageCompatible(db: Database, workspaceId: string, pack: CapabilityPack): Promise<void>;
+declare function buildMarketingDailyAnalysisAgentConfig(input: {
+    connections: SocialConnection[];
+    documentBaseIds: string[];
+    promptInstructions?: string;
+}): ScheduledTaskAgentConfig;
+
+declare function validateToolRefs(tools: ToolRef[], settings: Settings): ToolRef[];
+type McpSettings = Pick<Settings, "mcpServers">;
+declare function enabledCapabilityMcpToolRefs(settings: McpSettings, runtimeSettings: McpSettings): ToolRef[];
+declare function withDefaultEnabledCapabilityMcpTools(tools: ToolRef[], settings: McpSettings, runtimeSettings: McpSettings): ToolRef[];
+declare function normalizeResources(resources: ResourceRef[]): ResourceRef[];
+declare function mergeResourceRefs(existing: ResourceRef[], additions: ResourceRef[]): ResourceRef[];
+declare function validateGitHubRepositorySelectionShape(resources: ResourceRef[]): number | null;
+declare function validateGitHubRepositorySelection(db: Database, workspaceId: string, resources: ResourceRef[]): Promise<void>;
+declare function validateFileResources(db: Database, workspaceId: string, resources: ResourceRef[]): Promise<void>;
+
+/**
+ * Whether a raw scheduled-task payload explicitly set agentConfig.tools.
+ * Zod's `.default([])` erases the distinction between "absent" and
+ * "explicitly empty", so callers detect it on the raw payload — the same
+ * contract sessions use: absent tools mean "give me the workspace defaults
+ * (enabled capability MCP servers)", an explicit list (even empty) is taken
+ * verbatim.
+ */
+declare function scheduledTaskToolsProvided(rawPayload: unknown): boolean;
+declare function createValidatedScheduledTask(input: {
+    settings: Settings;
+    db: Database;
+    objectStorage: ObjectStorageDependency;
+    grant: AccessGrant;
+    payload: CreateScheduledTaskRequest;
+    toolsProvided?: boolean;
+    environmentPreauthorized?: boolean;
+}): Promise<ScheduledTask>;
+declare function validatedScheduledTaskUpdate(input: {
+    settings: Settings;
+    db: Database;
+    objectStorage: ObjectStorageDependency;
+    grant: AccessGrant;
+    existing: ScheduledTask;
+    payload: UpdateScheduledTaskRequest;
+    /** See createValidatedScheduledTask; only consulted when agentConfig is updated. */
+    toolsProvided?: boolean;
+}): Promise<UpdateScheduledTaskInput>;
+declare function requireScheduledTaskForApi(db: Database, workspaceId: string, taskId: string): Promise<ScheduledTask>;
+declare function restoreScheduledTask(db: Database, task: ScheduledTask): Promise<ScheduledTask>;
+declare function syncCreatedScheduledTask(input: {
+    db: Database;
+    workflowClient: SessionWorkflowClient;
+    task: ScheduledTask;
+}): Promise<void>;
+declare function syncUpdatedScheduledTask(input: {
+    db: Database;
+    workflowClient: SessionWorkflowClient;
+    previous: ScheduledTask;
+    task: ScheduledTask;
+}): Promise<void>;
+declare function scheduledTaskTemporalScheduleId(taskId: string): string;
+/**
+ * Stable token that identifies a single logical manual trigger. A client that
+ * retries a `/trigger` POST (network blip, lambda re-invocation) passes the
+ * SAME token so the retry is idempotent — one usage charge, one workflow run.
+ * When the client supplies nothing we mint one UUID PER REQUEST and reuse it
+ * for both the idempotency key and the workflowId, so a single request stays
+ * internally consistent while two genuinely-distinct manual triggers (no token,
+ * fired a second apart) still each get their own run. The token is sanitized to
+ * the Temporal workflow-id-safe charset so a client value cannot smuggle a
+ * collision into a different task's id space.
+ */
+declare function scheduledTaskTriggerToken(clientTriggerId?: string | null): string;
+/**
+ * Deterministic Temporal workflow id for a manual trigger. Derived purely from
+ * the task id and the stable trigger token, so a retry with the same token maps
+ * to the same id and `workflowIdReusePolicy: "REJECT_DUPLICATE"` collapses the
+ * second start into a no-op instead of spawning a second run.
+ */
+declare function manualScheduledTaskTriggerWorkflowId(taskId: string, triggerToken: string): string;
+/**
+ * Deterministic usage idempotency key for a manual trigger's agent_run.created
+ * charge. Shares the stable trigger token with the workflow id so the charge
+ * and the run dedupe together under retry.
+ */
+declare function manualScheduledTaskTriggerUsageKey(workspaceId: string, taskId: string, triggerToken: string): string;
+
+declare function createAndStartSession(input: {
+    db: Database;
+    bus: EventBus;
+    workflowClient: SessionWorkflowClient;
+    accountId: string;
+    workspaceId: string;
+    initialMessage: string;
+    resources: ResourceRef[];
+    tools: ToolRef[];
+    clientEventId?: string;
+    model: string;
+    reasoningEffort: Settings["openaiReasoningEffort"];
+    sandboxBackend: Settings["sandboxBackend"];
+    metadata: Record<string, unknown>;
+    environment?: {
+        id: string;
+        name: string;
+    } | null;
+    goal?: GoalSpec | null;
+    firstPartyMcpPermissions?: Permission[] | null;
+    parentSessionId?: string | null;
+    createIdempotencyKey?: string | null;
+    sandboxGroupId?: string | null;
+    sandboxOs?: Session["sandboxOs"];
+    seedTargetSandbox?: {
+        sandboxId: string;
+        settings: Settings;
+        workingDir?: string | null;
+    } | null;
+}): Promise<{
+    id: string;
+    workspaceId: string;
+    accountId: string;
+    status: "queued" | "running" | "idle" | "requires_action" | "failed" | "cancelled";
+    initialMessage: string;
+    title: string | null;
+    titleSource: "user" | "agent" | null;
+    resources: ({
+        kind: "repository";
+        uri: string;
+        ref: string;
+        mountPath?: string | undefined;
+        subpath?: string | undefined;
+        githubInstallationId?: number | undefined;
+        githubRepositoryId?: number | undefined;
+    } | {
+        kind: "file";
+        fileId: string;
+        mountPath?: string | undefined;
+    })[];
+    tools: {
+        kind: "mcp";
+        id: string;
+        optional?: boolean | undefined;
+    }[];
+    metadata: Record<string, unknown>;
+    model: string;
+    sandboxBackend: "docker" | "modal" | "local" | "none" | "daytona" | "runloop" | "e2b" | "blaxel" | "cloudflare" | "vercel" | "selfhosted";
+    sandboxOs: "linux" | "macos" | "windows";
+    sandboxGroupId: string;
+    activeSandboxId: string | null;
+    activeEpoch: number;
+    environmentId: string | null;
+    firstPartyMcpPermissions: ("account:read" | "account:admin" | "members:manage" | "workspace:create" | "billing:read" | "billing:manage" | "workspace:read" | "workspace:admin" | "sessions:create" | "sessions:read" | "sessions:control" | "stream:view" | "stream:control" | "stream:acknowledge" | "files:upload" | "files:read" | "files:write" | "terminal:attach" | "documents:manage" | "documents:search" | "scheduled_tasks:manage" | "scheduled_tasks:run" | "github:manage" | "github:use" | "api_keys:manage" | "environments:manage" | "environments:use" | "goals:manage" | "enrollments:read" | "enrollments:manage")[] | null;
+    parentSessionId: string | null;
+    createIdempotencyKey: string | null;
+    temporalWorkflowId: string | null;
+    activeTurnId: string | null;
+    lastInputTokens: number | null;
+    lastSequence: number;
+    codexPinnedCredentialId: string | null;
+    codexLastCredentialId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}>;
+declare function workflowIdForSession(sessionId: string): string;
+/**
+ * Reject an explicit model that the host does not expose. The set of usable
+ * models is the union surfaced by `configuredAllowedModels` (the built-in
+ * provider's allow-list plus every registry provider's ids); a `model` outside
+ * it cannot be resolved to a provider at run time, so we fail the request at
+ * the API edge with 422 rather than enqueuing a turn the worker can't honor.
+ *
+ * `model` is the explicit, caller-supplied value (null/undefined when omitted).
+ * An omitted model defaults to `settings.openaiModel` downstream — which is
+ * always first in `configuredAllowedModels` — so only an explicit value is
+ * checked. 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
+ * later) and the MCP surfaces that share them validate identically and cannot
+ * drift.
+ */
+declare function assertConfiguredModel(settings: Settings, model: string | null | undefined): void;
+declare function requireQueuedTurnForApi(db: Database, workspaceId: string, sessionId: string, turnId: string): Promise<SessionTurn>;
+declare function reasoningEffortForSession(metadata: Record<string, unknown>, fallback: Settings["openaiReasoningEffort"]): Settings["openaiReasoningEffort"];
+/**
+ * Appends a `user.message` to an existing session and enqueues the resulting
+ * turn, merging requested resources/tools into the session and waking the
+ * workflow. Shared by the public events route and the first-party MCP
+ * `session_send_message` tool so the two surfaces cannot drift. Callers own
+ * resource/tool validation and the per-message usage limit before calling.
+ */
+declare function postUserMessageTurn(input: {
+    db: Database;
+    bus: EventBus;
+    workflowClient: SessionWorkflowClient;
+    settings: Settings;
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    text: string;
+    resources: ResourceRef[];
+    tools: ToolRef[];
+    model?: string | null;
+    reasoningEffort?: Settings["openaiReasoningEffort"] | null;
+    clientEventId?: string;
+}): Promise<{
+    accepted: SessionEvent;
+    turn: SessionTurn;
+}>;
+/**
+ * Full create-session flow shared by `POST /sessions` and the first-party MCP
+ * `session_create` tool: payload validation, resource/tool/environment
+ * checks, usage limits, session start, and usage recording. `rawPayload` is
+ * the unparsed request body so absent-vs-empty `tools` keeps its meaning
+ * (absent applies the workspace's default capability MCP tools).
+ */
+declare function createSessionForRequest(deps: ApiRouteDeps, grant: AccessGrant, workspaceId: string, rawPayload: unknown): Promise<Session>;
+/**
+ * Full accept-user-message flow shared by the `user.message` branch of
+ * `POST /sessions/:id/events` and the first-party MCP `session_send_message`
+ * tool: resource/tool validation, usage limits, the locked append + turn
+ * enqueue, and usage recording. `toolsProvided: false` applies the
+ * workspace's default capability MCP tools, matching an absent `tools` key.
+ */
+declare function acceptSessionUserMessage(deps: ApiRouteDeps, grant: AccessGrant, workspaceId: string, sessionId: string, input: {
+    text: string;
+    resources?: ResourceRef[];
+    tools?: ToolRef[];
+    toolsProvided: boolean;
+    model?: string | null;
+    reasoningEffort?: ReasoningEffort | null;
+    clientEventId?: string;
+}): Promise<{
+    accepted: SessionEvent;
+    turn: SessionTurn;
+}>;
+/**
+ * Shared title-write path for the manual rename route AND both MCP tools
+ * (set_session_title / set_other_session_title). The clobber guard lives in
+ * the db `updateSessionTitle` UPDATE: an agent write is skipped when a user
+ * title already pinned the session. On a real write we emit `session.title_set`
+ * exactly like goal mutations emit their events; when nothing changed (agent
+ * write blocked by the user lock) we emit nothing. Returns whether a write
+ * happened so callers can avoid double work.
+ */
+declare function updateSessionTitle(deps: {
+    db: Database;
+    bus: EventBus;
+}, workspaceId: string, sessionId: string, title: string, source: "user" | "agent"): Promise<{
+    updated: boolean;
+    title: string | null;
+}>;
+
+/** A member can manage other members (directly or via the admin wildcard). */
+declare function memberCanAdminister(member: Pick<WorkspaceMember, "permissions">): boolean;
+/** Only `user:` subjects are people; `api_key:` subjects belong to API keys. */
+declare function isUserMember(member: Pick<WorkspaceMember, "subjectId">): boolean;
+/**
+ * Turn an email lookup result into the membership subject id. A null id means
+ * no registered user matched the email — email invites for not-yet-registered
+ * users are deferred, so that is a 404 (not a 400) at the API surface.
+ */
+declare function resolveMemberSubjectId(userId: string | null): string;
+/**
+ * Guard the member-remove path. Refuses (409) to remove the caller's own
+ * membership and refuses to remove the last member that still holds an admin
+ * permission, so a workspace can never be orphaned with no one able to manage
+ * it. `members` is the full roster (every subject, including api_key ones —
+ * an api_key with workspace:admin still counts as an administering subject).
+ */
+declare function assertWorkspaceMemberRemovable(input: {
+    members: WorkspaceMember[];
+    subjectId: string;
+    callerSubjectId: string;
+}): void;
+/**
+ * Guard the workspace-delete path before any external/DB mutation. Refuses
+ * (409) to delete the account's last workspace, and refuses while any session
+ * could still be running in Temporal (there is no clean per-session terminate
+ * to call first, so we will not orphan a workflow — the operator must stop the
+ * sessions first).
+ */
+declare function assertWorkspaceDeletable(input: {
+    workspaceCountForAccount: number;
+    activeSessionCount: number;
+}): void;
+
+export { type AccessDeps, type ApiRouteDeps, type ApiSandboxClient, type ApiSandboxSession, type AppDependencies, type ChannelARoutingServices, type DocumentIndexClient, type FleetContext, type FleetListResult, type FleetLiveness, type FleetSandboxEntry, type FleetServices, type FleetSwapResult, type LimitCheckInput, MARKETING_SOCIAL_PACK_ID, MAX_ENVIRONMENTS_PER_WORKSPACE, MAX_VARIABLES_PER_ENVIRONMENT, type ManagedAuth, type McpCapabilityProbe, type McpCapabilityProbeInput, type McpCapabilityProbeResult, type ObjectStorageDependency, type ProvisionResult, type ResumeBoxByIdInput, type ResumedSandboxSession, type RunOnOp, type RunOnResult, type SessionWorkflowClient, acceptSessionUserMessage, assertAllowedEnvironmentVariableName, assertConfiguredModel, assertPackSandboxImageCompatible, assertWorkspaceDeletable, assertWorkspaceMemberRemovable, buildCapabilityCatalog, buildFleetContextForSession, buildMarketingDailyAnalysisAgentConfig, checkLimit, createAndStartSession, createCatalogItem, createSessionForRequest, createValidatedScheduledTask, disableCapability, discoverMcpRegistryCapabilities, enableCapability, enabledCapabilityMcpToolRefs, getCapabilityPack, hasPermission, isBuiltInCapabilityPack, isUserMember, listCapabilityPacks, listFleet, listWorkspaceCapabilityPacks, manualScheduledTaskTriggerUsageKey, manualScheduledTaskTriggerWorkflowId, memberCanAdminister, mergeResourceRefs, normalizeResources, officialMcpRegistryUrl, postUserMessageTurn, provisionSandbox, reasoningEffortForSession, recordEnvironmentAuditEvent, recordWorkspaceUsage, relayConfigFromSettings, relayDialBaseFromSettings, requireAccessContext, requireAccessGrant, requireEnvironmentEncryption, requireEnvironmentForApi, requireLimit, requirePermission, requireQueuedTurnForApi, requireScheduledTaskForApi, resolveCapabilityPack, resolveMemberSubjectId, restoreScheduledTask, routingEnabled, runOnSandbox, scheduledTaskTemporalScheduleId, scheduledTaskToolsProvided, scheduledTaskTriggerToken, settingsWithEnabledCapabilityMcpServers, settingsWithMcpCapabilityServers, swapActiveSandbox, syncCreatedScheduledTask, syncUpdatedScheduledTask, updateSessionTitle, validateEnvironmentAttachment, validateFileResources, validateGitHubRepositorySelection, validateGitHubRepositorySelectionShape, validateMcpCapabilityConnection, validateToolRefs, validatedScheduledTaskUpdate, withDefaultEnabledCapabilityMcpTools, workflowIdForSession, wrapChannelABoxWithRouting };