@opengeni/core 0.12.7 → 0.14.3

package/dist/domain/sessions.d.ts

@@ -0,0 +1,256 @@
+import { type Settings } from "@opengeni/config";
+import { SessionSpawnDenial, type AccessGrant, type CreateSessionResponse, type GoalSpec, type FirstPartyMcpToolName, type Permission, type ReasoningEffort, type ResourceRef, type Session, type SessionSkill, type SessionEvent, SessionMcpApprovalPolicy, type SessionMcpCredentialUpdateInput, type SessionMcpServerMetadata, type UpdateSessionMcpApprovalPolicyResponse, type UpdateSessionToolPolicyRequest, type SessionAuthorizationPort, type SessionToolPolicy, type SessionTurn, type ToolRef, type TurnInitiator, type TurnInitiatorContext, type TurnExecutionPolicyV1 } from "@opengeni/contracts";
+import { type CreateSessionMcpServerInput, type Database, type UpdateSessionMcpServerCredentialsInput, type SessionCommandActor } from "@opengeni/db";
+import { type EventBus } from "@opengeni/events";
+import type { AcceptSessionUserMessageDependencies, ApiRouteDeps, SessionWorkflowClient } from "../dependencies";
+/** Transport-neutral typed denial raised only after its audit row committed. */
+export declare class SessionSpawnDeniedError extends Error {
+    readonly denial: SessionSpawnDenial;
+    constructor(denial: SessionSpawnDenial);
+}
+/**
+ * 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.
+ */
+export declare function resolveFirstPartyMcpToolsForCreate(requested: FirstPartyMcpToolName[] | undefined, parentStored: FirstPartyMcpToolName[] | null | undefined): FirstPartyMcpToolName[];
+export declare function sessionSpawnDenialEnvelope(error: SessionSpawnDeniedError): {
+    readonly error: {
+        readonly code: "nested_agent_depth_exceeded" | "nested_agent_depth_override_forbidden";
+        readonly message: string;
+        readonly details: {
+            readonly denial: {
+                id: string;
+                accountId: string;
+                workspaceId: string;
+                parentSessionId: string | null;
+                rootSessionId: string | null;
+                currentDepth: number;
+                attemptedDepth: number;
+                effectiveMaxNestedAgentDepth: number;
+                requestedMaxNestedAgentDepthOverride: number | null;
+                policySource: "default" | "deployment" | "session" | "workspace";
+                policySessionId: string | null;
+                subjectId: string | null;
+                code: "nested_agent_depth_exceeded" | "nested_agent_depth_override_forbidden";
+                idempotencyKey: string | null;
+                createdAt: string;
+            };
+        };
+    };
+};
+export declare function settingsWithSessionMcpServerMetadata(settings: Settings, servers: SessionMcpServerMetadata[]): Settings;
+export declare function createAndStartSession(input: {
+    requestedSessionId?: string;
+    db: Database;
+    bus: EventBus;
+    workflowClient: SessionWorkflowClient;
+    accountId: string;
+    workspaceId: string;
+    initialMessage: string;
+    turnInstructions?: string | null;
+    resources: ResourceRef[];
+    skills?: SessionSkill[];
+    tools: ToolRef[];
+    toolPolicy: SessionToolPolicy;
+    clientEventId?: string;
+    model: string;
+    reasoningEffort: Settings["openaiReasoningEffort"];
+    /** Session default Fast/standard; mirrored into metadata when set. */
+    latencyMode?: "standard" | "priority" | "fast";
+    turnExecutionPolicy: TurnExecutionPolicyV1;
+    sandboxBackend: Settings["sandboxBackend"];
+    metadata: Record<string, unknown>;
+    createdBy?: TurnInitiator;
+    createdByContext?: TurnInitiatorContext;
+    createdByActor?: Extract<SessionCommandActor, {
+        type: "agent_attempt";
+    }> | null;
+    variableSet?: {
+        id: string;
+        name: string;
+    } | null;
+    rigId?: string | null;
+    rigVersionId?: string | null;
+    goal?: GoalSpec | null;
+    instructions?: string | null;
+    firstPartyMcpPermissions?: Permission[] | null;
+    firstPartyMcpTools: FirstPartyMcpToolName[];
+    mcpServers?: CreateSessionMcpServerInput[];
+    sessionMcpServers?: SessionMcpServerMetadata[];
+    parentSessionId?: string | null;
+    createIdempotencyKey?: string | null;
+    sandboxGroupId?: string | null;
+    sandboxOs?: Session["sandboxOs"];
+    seedTargetSandbox?: {
+        sandboxId: string;
+        settings: Settings;
+        workingDir?: string | null;
+    } | null;
+    consumeNewSessionDraft?: {
+        subjectId: string;
+        expectedRevision: number;
+    } | null;
+    maxNestedAgentDepthOverride?: number | null;
+    allowNestedAgentDepthIncrease?: boolean;
+    subjectId?: string | null;
+}): Promise<CreateSessionResponse>;
+export 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.
+ */
+export declare function canonicalConfiguredModel(settings: Settings, model: string | null | undefined): string | null | undefined;
+export declare function assertConfiguredModel(settings: Settings, model: string | null | undefined): void;
+export declare const CODEX_COMPACTION_V2_PROVIDER_LOCKED: "codex_compaction_v2_provider_locked";
+/** Session is frozen on Codex remote compaction v2; non-Codex models are refused. */
+export declare class CodexCompactionV2ProviderLockedError extends Error {
+    readonly code: "codex_compaction_v2_provider_locked";
+    readonly productModelId: string;
+    constructor(productModelId: string);
+}
+/**
+ * Fail closed when a remote_v2 session would run a non-Codex product model.
+ * Portable sessions and non-Codex sessions keep free mid-session provider swap.
+ */
+export declare function assertSessionAllowsProductModel(session: Pick<Session, "codexCompactionMode">, productModelId: string | null | undefined): void;
+/**
+ * Reject a model the WORKSPACE's model policy blocks, at the same choke points
+ * as assertConfiguredModel — a 422 at the edge instead of a queued turn the
+ * 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.
+ */
+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
+ * 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.
+ */
+export declare function postUserMessageTurn(input: {
+    db: Database;
+    bus: EventBus;
+    workflowClient: Pick<SessionWorkflowClient, "wakeSessionWorkflow">;
+    settings: Settings;
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    text: string;
+    turnInstructions?: string | null;
+    resources: ResourceRef[];
+    model?: string | null;
+    reasoningEffort?: Settings["openaiReasoningEffort"] | null;
+    latencyMode?: "standard" | "priority" | "fast" | null;
+    clientEventId?: string;
+    mcpCredentialUpdates?: UpdateSessionMcpServerCredentialsInput[];
+    delivery?: "send" | "steer";
+    origin?: "human" | "operator";
+    actor?: string;
+    actorLabel?: string;
+    commandActor?: SessionCommandActor;
+    controlEtag?: string | null;
+    expectedDraftRevision?: number | null;
+    reasoningEffortFallback?: Settings["openaiReasoningEffort"];
+    turnExecutionPolicy: TurnExecutionPolicyV1;
+}): 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/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
+ * top-level create with omitted tools applies workspace-default capability MCPs.
+ */
+export 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` durably preserves an
+ * Tool selection is durable session state and never rides a follow-up prompt.
+ */
+export declare function acceptSessionUserMessage(deps: AcceptSessionUserMessageDependencies, grant: AccessGrant, workspaceId: string, sessionId: string, input: {
+    text: string;
+    turnInstructions?: string | null;
+    resources?: ResourceRef[];
+    model?: string | null;
+    reasoningEffort?: ReasoningEffort | null;
+    latencyMode?: "standard" | "priority" | "fast" | null;
+    clientEventId?: string;
+    mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[];
+    delivery?: "send" | "steer";
+    origin?: "human" | "operator";
+    controlEtag?: string | null;
+    expectedDraftRevision?: number | null;
+}): 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.
+ */
+export declare function updateSessionTitle(deps: {
+    db: Database;
+    bus: EventBus;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+}, grant: AccessGrant, sessionId: string, title: string, source: "user" | "agent"): Promise<{
+    updated: boolean;
+    title: string | null;
+    relatedSessionAccess: "target" | "root";
+}>;
+/**
+ * Update one existing session MCP server's approval policy. The database
+ * serializes this write with attempt claim under the session lock: an already
+ * claimed attempt retains its immutable snapshot, while the next claim captures
+ * this value. No attempt is cancelled, restarted, or reinterpreted.
+ */
+export declare function updateSessionMcpApprovalPolicy(deps: {
+    db: Database;
+    bus: EventBus;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+}, grant: AccessGrant, sessionId: string, serverId: string, requireApproval: SessionMcpApprovalPolicy): Promise<UpdateSessionMcpApprovalPolicyResponse>;
+/**
+ * Replace the durable session tool policy. The target and its parent (when
+ * present) are locked by the DB event-writer helper, and the update/event are
+ * committed under one version-fenced transaction. An already claimed turn
+ * keeps its immutable snapshot; the next attempt observes this policy.
+ */
+export declare function updateSessionToolPolicy(deps: {
+    db: Database;
+    bus: EventBus;
+    settings: Settings;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+}, grant: AccessGrant, sessionId: string, request: UpdateSessionToolPolicyRequest): Promise<Session>;
+export declare function readSessionLineage(deps: Pick<ApiRouteDeps, "db" | "sessionAuthorization">, grant: AccessGrant, sessionId: string): Promise<import("@opengeni/db").SessionLineage>;

package/dist/domain/slack-bot.d.ts

@@ -0,0 +1,19 @@
+import { type AccessGrant, type ConnectionMetadata, type OpenGeniSlackBotConnectionMetadata as OpenGeniSlackBotMetadata, type Session } from "@opengeni/contracts";
+import { type ConnectionMetadataWithVerification, type Database } from "@opengeni/db";
+export declare function openGeniSlackBotMetadata(metadata: Record<string, unknown>): OpenGeniSlackBotMetadata | null;
+export declare function isOpenGeniSlackBotConnection(connection: ConnectionMetadata & Partial<Pick<ConnectionMetadataWithVerification, "verifiedInstallAt" | "verifiedInstallVersion">>): boolean;
+export declare function hasReservedOpenGeniSlackBotMetadata(metadata: Record<string, unknown> | null | undefined): boolean;
+export declare function hasReservedOpenGeniSlackBotSessionMetadata(metadata: Record<string, unknown> | null | undefined): boolean;
+/**
+ * Internal, pre-authorized lookup used by the scheduler and Slack tool adapter.
+ * Public callers must perform their permission check before calling this helper.
+ */
+export declare function requireOpenGeniSlackBotConnection(db: Database, workspaceId: string, connectionId: string): Promise<ConnectionMetadata>;
+export declare function validateOpenGeniSlackBotConnectionSelection(db: Database, grant: AccessGrant, workspaceId: string, connectionId: string): Promise<ConnectionMetadata>;
+export declare function scheduledSlackBotConnectionId(metadata: Record<string, unknown> | null | undefined): string | null;
+/**
+ * The scheduler writes the connection pointer together with immutable creator
+ * provenance. Requiring both prevents ordinary session metadata from becoming
+ * an authorization mechanism for a workspace-shared bot credential.
+ */
+export declare function isTrustedScheduledSlackBotSession(session: Pick<Session, "createdBy" | "createdByContext" | "metadata">): boolean;

package/dist/domain/workspace-members.d.ts

@@ -0,0 +1,34 @@
+import type { WorkspaceMember } from "@opengeni/contracts";
+/** A member can manage other members (directly or via the admin wildcard). */
+export declare function memberCanAdminister(member: Pick<WorkspaceMember, "permissions">): boolean;
+/** Only `user:` subjects are people; `api_key:` subjects belong to API keys. */
+export 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.
+ */
+export 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).
+ */
+export 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).
+ */
+export declare function assertWorkspaceDeletable(input: {
+    workspaceCountForAccount: number;
+    activeSessionCount: number;
+}): void;