@opengeni/api-router 3.0.1 → 3.0.2-canary.38894290271001

package/dist/routes/workspaces.d.ts

@@ -1,4 +1,4 @@
-import { type WorkspaceMember as WorkspaceMemberValue } from "@opengeni/contracts";
+import { type AccessContext, type WorkspaceMember as WorkspaceMemberValue } from "@opengeni/contracts";
 import type { Hono } from "hono";
 import type { ApiRouteDeps } from "@opengeni/core";
 import { type Settings } from "@opengeni/config";
@@ -16,10 +16,19 @@ export declare function workspaceMembersResponse(members: readonly WorkspaceMemb
         subjectId: string;
         subjectLabel: string | null;
         role: string;
-        permissions: ("account:admin" | "account:read" | "api_keys:manage" | "artifacts:publish" | "artifacts:read" | "billing:manage" | "billing:read" | "capabilities:manage" | "codemode:call" | "connections:read" | "connections:write" | "documents:manage" | "documents:search" | "enrollments:manage" | "enrollments:read" | "environments:manage" | "environments:use" | "files:read" | "files:upload" | "files:write" | "github:manage" | "github:use" | "goals:manage" | "mcp_servers:attach" | "members:manage" | "rigs:manage" | "rigs:use" | "scheduled_tasks:manage" | "scheduled_tasks:run" | "secrets:list" | "secrets:read" | "secrets:write" | "sessions:control" | "sessions:create" | "sessions:read" | "stream:acknowledge" | "stream:control" | "stream:view" | "terminal:attach" | "variable-sets:attach" | "variable-sets:list" | "variable-sets:manage" | "variable-sets:read" | "variable-sets:use" | "variable-sets:write" | "workspace:admin" | "workspace:create" | "workspace:read")[];
+        permissions: ("account:admin" | "account:read" | "api_keys:manage" | "artifacts:publish" | "artifacts:read" | "billing:manage" | "billing:read" | "capabilities:manage" | "codemode:call" | "connections:read" | "connections:write" | "documents:manage" | "documents:search" | "enrollments:manage" | "enrollments:read" | "environments:manage" | "environments:use" | "files:read" | "files:upload" | "files:write" | "github:manage" | "github:use" | "goals:manage" | "mcp_servers:attach" | "members:manage" | "rigs:manage" | "rigs:use" | "scheduled_tasks:manage" | "scheduled_tasks:run" | "secrets:list" | "secrets:read" | "secrets:use" | "secrets:write" | "sessions:control" | "sessions:create" | "sessions:read" | "stream:acknowledge" | "stream:control" | "stream:view" | "terminal:attach" | "usage_allowances:manage" | "variable-sets:attach" | "variable-sets:list" | "variable-sets:manage" | "variable-sets:read" | "variable-sets:use" | "variable-sets:write" | "workspace:admin" | "workspace:create" | "workspace:read")[];
         createdAt: string;
     }[];
 };
+export declare function workspaceUpdateRequestsSettings(value: unknown): boolean;
 export declare function workspaceUpdateRequestsAccountTransfer(value: unknown): boolean;
+/**
+ * Owning organization for `PUT /v1/workspaces/external`. An organization API
+ * key can only ever create workspaces in its own organization, so an omitted
+ * `accountId` resolves to that organization. Every other caller - notably a
+ * human who may belong to several organizations - must name it explicitly;
+ * guessing a default there could create the workspace in the wrong tenant.
+ */
+export declare function externalWorkspaceAccountId(context: AccessContext, requested: string | undefined): string;
 export declare function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void;
 export {};

package/dist/sandbox/agent-update.d.ts

@@ -0,0 +1,64 @@
+import type { Settings } from "@opengeni/config";
+import { type Database, type EnrollmentRecord } from "@opengeni/db";
+import type { EventBus } from "@opengeni/events";
+import type { Observability } from "@opengeni/observability";
+export type AgentUpdateDeps = {
+    db: Database;
+    bus?: EventBus | null;
+    settings: Settings;
+};
+export type AgentUpdateRequestResult = {
+    kind: "accepted";
+    operationId: string;
+    targetVersion: string;
+} | {
+    kind: "refused";
+    status: 409 | 422 | 502;
+    message: string;
+};
+/** Reserve one exact-generation operation, ask the authoritative runner to
+ * apply the promoted release, then let progress events + the successor Hello
+ * drive the durable state to completion. `live` must be the enrollment's
+ * current live connection. */
+export declare function requestAgentUpdate(deps: AgentUpdateDeps, live: EnrollmentRecord, input: {
+    releaseBaseUrl: string;
+}): Promise<AgentUpdateRequestResult>;
+/** First agent release whose restart detaches from its managed browsers so
+ * the successor adopts them with their tabs and page state. An older agent
+ * closes every managed browser while it shuts down for an update. */
+export declare const BROWSER_PRESERVING_AGENT_VERSION = "0.1.58";
+/** Recorded when the automatic updater leaves an older agent alone because
+ * updating it would close managed browsers. A `update_busy_*` code, so it
+ * reads and retries as a postponement rather than a failure. */
+export declare const UPDATE_POSTPONED_FOR_BROWSERS = "update_busy_browsers";
+/** Whether updating this agent would close browsers it manages. */
+export declare function agentUpdateWouldCloseBrowsers(db: Database, enrollment: EnrollmentRecord): Promise<boolean>;
+/** How long the automatic updater leaves a machine alone after an attempt. */
+export declare const AUTOMATIC_AGENT_UPDATE_RETRY_MS: {
+    /** A machine postponed because it was busy (running work, or managed
+     * browsers an older agent would close) is looked at again soon: the check
+     * is instant and interrupts nothing. */
+    readonly busy: number;
+    /** A request the runner never answered is re-sent under the same operation. */
+    readonly unanswered: number;
+    /** Other retryable failures (download, verification, a replaced process). */
+    readonly retryable: number;
+};
+/** Whether a live machine should be asked now to move to `targetVersion`.
+ * Pure: decided from the enrollment the heartbeat already read. Only upgrades
+ * are automatic; moving a machine to an older promoted build stays an explicit
+ * per-machine request. A non-retryable failure waits for a newer promotion. */
+export declare function automaticAgentUpdateDue(enrollment: EnrollmentRecord, targetVersion: string, now: number): boolean;
+export type AutomaticAgentUpdater = {
+    /** Consider one live machine, typically from the enrollment its heartbeat
+     * just read and renewed. Never blocks the caller. */
+    consider(enrollment: EnrollmentRecord): void;
+};
+/** Keep live machines on their promoted build. Returns null when the
+ * deployment turned automatic updates off or has no public base URL for the
+ * agent to fetch the release manifest from. Concurrent API replicas are safe:
+ * reserving an operation is an atomic conditional write. */
+export declare function createAutomaticAgentUpdater(deps: AgentUpdateDeps & {
+    observability?: Observability;
+    now?: () => number;
+}): AutomaticAgentUpdater | null;

package/dist/sandbox/auth-callout.d.ts

@@ -1,3 +1,4 @@
+import { type LogThrottle } from "@opengeni/observability";
 import { type NatsCalloutConfig, type Settings } from "@opengeni/config";
 import { type Database } from "@opengeni/db";
 import { type ResponderConnection } from "@opengeni/events";
@@ -11,7 +12,14 @@ export interface AuthCalloutDeps {
     settings: Settings;
     callout: NatsCalloutConfig;
     observability?: Observability;
+    /** Bounds repeated denial warnings; defaults to one process-wide throttle. */
+    denialWarningThrottle?: LogThrottle;
 }
+/** A stale or revoked machine re-dials on its reconnect backoff forever, so an
+ * unthrottled denial warning repeats every few seconds per machine. Log each
+ * distinct machine's first denial, then at most once per interval with the
+ * count of denials it hid. The denial decision itself is never throttled. */
+export declare const AUTH_CALLOUT_DENIAL_WARNING_INTERVAL_MS = 60000;
 /**
  * The pure validate→scoped-JWT decision, isolated from the NATS transport so it is
  * unit-testable. Given the raw authorization-request JWT bytes, returns the signed

package/dist/sandbox/channel-a.d.ts

@@ -1,10 +1,11 @@
 import { type Settings } from "@opengeni/config";
-import type { Session } from "@opengeni/contracts";
+import type { AccessGrant, Session } from "@opengeni/contracts";
 import { type Database, type LeaseSnapshot } from "@opengeni/db";
 import { type EventBus } from "@opengeni/events";
 import { type Observability } from "@opengeni/observability";
 import type { ObjectStorage } from "@opengeni/storage";
 import { SandboxChannelAService, type ChannelASession, type EstablishedSandboxSession, type RoutingSandboxSession } from "@opengeni/runtime/sandbox";
+import { type ChannelAMachineAuthority } from "@opengeni/core";
 export type ChannelAServices = {
     db: Database;
     settings: Settings;
@@ -18,6 +19,9 @@ export type ChannelAContext = {
     workspaceId: string;
     session: Session;
     subjectId: string;
+    /** The authenticated route grant, when one drives the op. It resolves the
+     *  session's Sandbox Environment for an agent attempt as its initiating human. */
+    grant?: AccessGrant | undefined;
     /** Cancel lifecycle waiting when the originating HTTP request disconnects. */
     waitSignal?: AbortSignal | undefined;
     /** Bounded route identity for metrics and safe operator diagnostics. */
@@ -27,6 +31,10 @@ export type ChannelAContext = {
      * provider handle and replay the request. Tab/lifecycle mutations that lack
      * a controller operation id must never opt into this recovery. */
     retryControllerTransport?: boolean | undefined;
+    /** Ephemeral browser callbacks must never replay after an ambiguous result. */
+    allowOperationReplay?: boolean | undefined;
+    /** Exact existing interaction provider; may not spawn/rotate on image drift. */
+    retainedInstanceId?: string | undefined;
 };
 export type ChannelAOperationFailureReason = "request_cancelled" | "provider_read_busy" | "provider_unavailable" | "lifecycle_conflict" | "request_rejected" | "unexpected";
 export type ChannelAOperationFailureDiagnostic = {
@@ -44,6 +52,10 @@ export type ChannelAHandle = {
      * active-sandbox pointer and is safe for placement-bound controllers. */
     homeSession: ChannelASession;
     routingSession: RoutingSandboxSession;
+    /** Whose access this request uses to reach a Connected Machine: the person
+     * who started an agent's turn, or the calling person. Routes that look up
+     * the routed machine again must use it rather than the raw caller grant. */
+    machineAuthority: () => Promise<ChannelAMachineAuthority>;
     requestId: string;
 };
 export type EstablishedHandleCacheKind = "read" | "process" | "none";
@@ -65,6 +77,8 @@ type ChannelAReadRecoveryOptions = {
     /** Modal may expose one more stale command-router route after the first
      * successful handle rebuild. Keep this closed and statically bounded. */
     maxFreshHandleRetries?: 1 | 2;
+    /** Explicit opt-out overrides every transport/provider retry classification. */
+    allowOperationReplay?: boolean | undefined;
     /** Never start another provider attempt after the originating request ends. */
     waitSignal?: AbortSignal | undefined;
     /** Additional callback-specific failure that is safe to replay. */

package/dist/sandbox/enrollment.d.ts

@@ -1,10 +1,16 @@
 import { type Settings } from "@opengeni/config";
-import { type DeviceEnrollmentLookupResponse, type DeviceEnrollmentPollResponse, type DeviceEnrollmentStartResponse, type EnrollTokenExchangeResponse, type MintEnrollTokenResponse } from "@opengeni/contracts";
+import { type RenewEnrollmentRequest, type DeviceEnrollmentLookupResponse, type DeviceEnrollmentPollResponse, type DeviceEnrollmentStartResponse, type EnrollmentCredentialsResponse, type EnrollTokenExchangeResponse, type MintEnrollTokenResponse } from "@opengeni/contracts";
 import { type Database, type DeviceEnrollmentRequestRecord, type EnrollmentOs } from "@opengeni/db";
 export declare const DEVICE_CODE_TTL_SECONDS = 600;
 export declare const DEVICE_POLL_INTERVAL_SECONDS = 5;
 export declare const ENROLLMENT_BEARER_TTL_SECONDS: number;
 export declare const RELAY_TOKEN_TTL_SECONDS: number;
+/** Renew an existing grant, including after a long offline interval. The expired
+ * bearer is only an authenticated enrollment/generation locator here: current
+ * install-key possession and live enrollment authority are both required. Normal
+ * NATS/relay authentication continues to reject expired transport credentials.
+ * Nothing creates/reactivates an enrollment or changes its consent or scope. */
+export declare function renewEnrollmentCredentials(services: EnrollmentServices, input: RenewEnrollmentRequest, nowSeconds?: number): Promise<EnrollmentCredentialsResponse | null>;
 export declare const ENROLL_TOKEN_TTL_SECONDS = 3600;
 export type EnrollmentServices = {
     db: Database;
@@ -69,13 +75,17 @@ export declare function denyDeviceEnrollment(services: EnrollmentServices, input
     denied: boolean;
 }>;
 /** MINT a headless enroll token (design 11 §A2.2). Signs an `oget_` token bound to
- *  the workspace + account + the screen-control consent, with a 1h TTL. Returns
- *  null when the credential plane is disabled (no signing secret) so the route can
- *  mirror poll's "disabled" handling. The token value is NEVER logged. */
+ *  the workspace + account + the screen-control consent, with a 1h TTL. With an
+ *  `ownerSubjectId` the token is personal (`enroll_user`): the machine it connects
+ *  belongs to that person. Callers must pass only an authenticated human's own
+ *  subject. Returns null when the credential plane is disabled (no signing secret)
+ *  so the route can mirror poll's "disabled" handling. The token value is NEVER
+ *  logged. */
 export declare function mintEnrollToken(services: EnrollmentServices, input: {
     accountId: string;
     workspaceId: string;
     allowScreenControl: boolean;
+    ownerSubjectId?: string | null;
 }): Promise<MintEnrollTokenResponse | null>;
 /** Distinguishes the two exchange failure modes for the route. */
 export type ExchangeEnrollTokenResult = {
@@ -87,6 +97,18 @@ export type ExchangeEnrollTokenResult = {
 } | {
     ok: false;
     reason: "invalid";
+} | {
+    ok: false;
+    reason: "used";
+} | {
+    ok: false;
+    reason: "owner_unavailable";
+} | {
+    ok: false;
+    reason: "connected_elsewhere";
+} | {
+    ok: false;
+    reason: "busy";
 };
 /** EXCHANGE a headless enroll token (design 11 §A2.3) — the UNAUTHENTICATED path
  *  where the token IS the auth. Verifies the `oget_` token, then performs the SAME

package/dist/sandbox/machine-audience.d.ts

@@ -0,0 +1,29 @@
+import { ChangeMachineAudienceResponse, MachineAudiencePreview, type MachineAudience } from "@opengeni/contracts";
+import type { MachineAudienceChangeRecord, MachineAudiencePreviewRecord, MachineAudienceRefusal } from "@opengeni/db";
+import { ApiHttpError } from "../http/api-error.js";
+type AudienceCaller = {
+    subjectId: string;
+    permissions: readonly string[];
+};
+type AudienceMachine = {
+    workspaceId: string;
+    scope: "organization" | "workspace" | "user";
+};
+/**
+ * Decide whether the caller may ask for this change and who would own the
+ * machine. Narrowing to Only me: the person who will own it, or a workspace
+ * admin acting for that person. Sharing with the workspace: a workspace admin
+ * (the database also requires the caller to be the machine's owner, so nobody
+ * can expose another person's Only me machine).
+ */
+export declare function machineAudienceRequestFor(caller: AudienceCaller, routeWorkspaceId: string, machine: AudienceMachine, request: {
+    audience: MachineAudience;
+    ownerSubjectId?: string | undefined;
+}): {
+    ownerSubjectId: string | null;
+};
+export declare function machineAudienceRefusalError(refusal: MachineAudienceRefusal): ApiHttpError;
+export declare function machineAudiencePreview(record: MachineAudiencePreviewRecord): MachineAudiencePreview;
+/** Map an applied change, or explain why nothing changed. */
+export declare function machineAudienceChangeResponse(record: MachineAudienceChangeRecord): ChangeMachineAudienceResponse;
+export {};

package/dist/sandbox/machines.d.ts

@@ -1,10 +1,22 @@
 import type { Settings } from "@opengeni/config";
-import { type Database, type MachineMetricsRow } from "@opengeni/db";
-import { MetricSample, type MachinesResponse } from "@opengeni/contracts";
+import { type Database, type EnrollmentRecord, type MachineMetricsRow } from "@opengeni/db";
+import { MetricSample, type MachineRuntime, type MachinesResponse } from "@opengeni/contracts";
 export type MachinesServices = {
     db: Database;
     settings: Settings;
 };
+export declare const ACTIVE_UPDATE_STATUSES: ReadonlySet<string>;
+export declare function compareAgentVersions(left: string, right: string): number | null;
+/** The build the operator promoted for a machine's update channel. */
+export declare function promotedAgentVersion(settings: Pick<Settings, "agentStableVersion" | "agentBetaVersion">, channel: string | null): string;
+/** Older Mac updaters replace a single file inside a sealed app. They must
+ * bootstrap once through the official whole-app installer, never an RPC swap. */
+export declare function machineUpdateBlockedReason(os: string, version: string | null): string | null;
+type AgentUpdateRecord = EnrollmentRecord["agentUpdate"];
+/** Where the installed agent stands against the promoted build. A failed update
+ * stops mattering once its target (or newer) is installed, and a busy machine
+ * postponing an update (`update_busy_*`) has not failed: it is still outdated. */
+export declare function agentVersionState(installedVersion: string | null, desiredVersion: string | null, update: AgentUpdateRecord): MachineRuntime["versionState"];
 /**
  * Project a stored `machine_metrics_latest` row to the contract `MetricSample`.
  * The DB carries `gpuUtilPercent` + `gpuMemUsedBytes`/`gpuMemTotalBytes`; the wire
@@ -27,3 +39,4 @@ export declare function listMachines(services: MachinesServices, input: {
     subjectId?: string;
     sessionId?: string | null;
 }): Promise<MachinesResponse>;
+export {};

package/dist/sandbox/metrics-ingestion.d.ts

@@ -1,7 +1,8 @@
-import { type Database, type MachineMetricsSample } from "@opengeni/db";
+import { type Database, type EnrollmentMacPermissions, type MachineMetricsSample } from "@opengeni/db";
 import { type AttachedBrowserInventorySnapshot as AttachedBrowserInventoryContractValue } from "@opengeni/contracts";
 import { type EventBus } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
+import type { AutomaticAgentUpdater } from "./agent-update.js";
 import { Hello, type AttachedBrowserInventorySnapshot as WireAttachedBrowserInventorySnapshot, type MetricsSample } from "@opengeni/agent-proto";
 /** The wildcard subject the agent event plane publishes heartbeats on. */
 export declare const AGENT_EVENTS_SUBJECT = "agent.*.*.connection.*.events";
@@ -57,7 +58,7 @@ export declare function wireAttachedBrowserInventoryToContract(wire: WireAttache
  * are reported + swallowed. `bus` (when present) enables the session-event
  * fan-out; the live consumer always supplies it, pure unit tests may omit it.
  */
-export declare function handleAgentEventPayload(db: Database, observability: Observability | undefined, payload: Uint8Array, subject: string, bus?: EventBus): Promise<void>;
+export declare function handleAgentEventPayload(db: Database, observability: Observability | undefined, payload: Uint8Array, subject: string, bus?: EventBus, agentUpdates?: AutomaticAgentUpdater | null): Promise<void>;
 /**
  * Start the metrics-ingestion consumer: subscribe exact process events and ingest
  * every heartbeat. Gated by sandboxSelfhostedEnabled (the caller checks the flag;
@@ -67,6 +68,7 @@ export declare function startMetricsIngestion(deps: {
     db: Database;
     bus: EventBus;
     observability?: Observability;
+    agentUpdates?: AutomaticAgentUpdater | null;
 }): () => void;
 /**
  * The LIVE display presence the agent's Hello reports: a desktop framebuffer is
@@ -100,6 +102,8 @@ export declare function refreshEnrollmentDisplay(db: Database, input: {
     agentId: string;
     hasDisplay: boolean;
     desktopUnavailableReason?: string | null;
+    runtimeDesktop?: boolean;
+    macPermissions?: EnrollmentMacPermissions;
     connectionInstanceId?: string;
 }): Promise<{
     updated: boolean;

package/dist/sandbox/screen-control.d.ts

@@ -0,0 +1,85 @@
+import { type Hello } from "@opengeni/agent-proto";
+import { EnableMachineScreenControlResponse, OpenMachinePrivacySettingsResponse, type MachinePrivacySettingsPane } from "@opengeni/contracts";
+import { type FleetServices } from "@opengeni/core";
+import { type EnrollmentRecord } from "@opengeni/db";
+import type { EventBus } from "@opengeni/events";
+import type { Observability } from "@opengeni/observability";
+type Services = Pick<FleetServices, "db" | "settings" | "bus"> & {
+    observability?: Observability | undefined;
+};
+type EnrollmentAccess = string | {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+};
+/** macOS System Settings deep links for the three desktop permissions. */
+export declare const MAC_PRIVACY_PANE_URLS: Record<MachinePrivacySettingsPane, string>;
+/** Read access for live-connection lookups, matching the machine's scope. */
+export declare function enrollmentAccess(enrollment: Pick<EnrollmentRecord, "scope" | "workspaceId">, personal: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+}): EnrollmentAccess;
+export type CredentialRenewOutcome = {
+    kind: "renewed";
+    consentedScreenControl: boolean;
+} | {
+    kind: "offline";
+} | {
+    kind: "failed";
+    failureCode: string;
+};
+/** Ask one exact live runner process to renew its credentials now. */
+export declare function requestCredentialRenew(bus: EventBus | undefined, target: {
+    workspaceId: string;
+    enrollmentId: string;
+    connectionInstanceId: string;
+}): Promise<CredentialRenewOutcome>;
+/** The enrollment was revoked or removed between lookup and update. */
+export declare class MachineNotActiveError extends Error {
+    constructor();
+}
+/** Who turned screen control on, for the audit trail. */
+export type ScreenControlActor = {
+    subjectId: string | null;
+    sessionId?: string | null;
+    attemptId?: string | null;
+};
+/**
+ * Turn screen control on for one enrolled machine, in place. The caller has
+ * already authorized the actor for this enrollment (enrollments:manage, plus
+ * account:admin for an organization machine, plus personal-machine admission
+ * for an agent attempt). Safe to repeat: a retry re-requests the renewal.
+ */
+export declare function enableMachineScreenControl(services: Services, input: {
+    enrollment: EnrollmentRecord;
+    access: EnrollmentAccess;
+    actor: ScreenControlActor;
+}): Promise<EnableMachineScreenControlResponse>;
+/**
+ * A machine whose enrollment allows screen control but whose credentials do
+ * not (it was offline, or updated from an agent without credential_renew)
+ * renews them as soon as it says Hello. The agent subscribes to requests just
+ * after its Hello, so wait briefly and retry once. Never throws.
+ */
+export declare function reconcileScreenControlOnHello(deps: {
+    bus: EventBus | undefined;
+    observability?: Observability | undefined;
+    sleep?: (ms: number) => Promise<void>;
+}, input: {
+    authority: Pick<EnrollmentRecord, "allowScreenControl">;
+    hello: Hello;
+    target: {
+        workspaceId: string;
+        enrollmentId: string;
+        connectionInstanceId: string;
+    };
+}): Promise<CredentialRenewOutcome | null>;
+/** Open one macOS Privacy & Security pane on a connected Mac. Opening a pane
+ * grants nothing; the person flips the switch for Opengeni. */
+export declare function openMachinePrivacySettings(services: Services, input: {
+    enrollment: EnrollmentRecord;
+    access: EnrollmentAccess;
+    pane: MachinePrivacySettingsPane;
+}): Promise<OpenMachinePrivacySettingsResponse>;
+export {};

package/dist/sandbox/viewer.d.ts

@@ -1,5 +1,5 @@
 import type { Settings } from "@opengeni/config";
-import { type Session } from "@opengeni/contracts";
+import { type AccessGrant, type Session } from "@opengeni/contracts";
 import { type Database, type LeaseSnapshot, type SandboxRecord } from "@opengeni/db";
 import { type EventBus } from "@opengeni/events";
 import type { ObjectStorage } from "@opengeni/storage";
@@ -73,6 +73,10 @@ export declare function attachViewer(services: ViewerServices, input: {
     /** The authenticated subject attaching this viewer (0281): recorded on
      *  the holder row together with the live session authority epoch. */
     viewerSubjectId?: string;
+    /** The authenticated route grant, when one drives the attach. It resolves
+     *  the session's Sandbox Environment for an agent attempt as its
+     *  initiating human. */
+    grant?: AccessGrant;
     /** Cancel lifecycle waiting when the originating HTTP request disconnects. */
     waitSignal?: AbortSignal;
 }): Promise<ViewerAttachResult>;

package/dist/sandbox-file-artifacts.d.ts

@@ -1,6 +1,7 @@
 import { SandboxFileArtifactReceipt, type AccessGrant, type Session } from "@opengeni/contracts";
 import { type ApiRouteDeps, type AccessGrantAuthorization } from "@opengeni/core";
 import { getFile } from "@opengeni/db";
+import { type SandboxChannelAService } from "@opengeni/runtime/sandbox";
 /** Original bytes inherit the already-authorized source session's ownership. */
 export declare function publishSandboxFileArtifact(deps: ApiRouteDeps, input: Parameters<typeof publishSandboxFileArtifactInScope>[1]): Promise<SandboxFileArtifactReceipt>;
 declare function publishSandboxFileArtifactInScope(deps: ApiRouteDeps, input: {
@@ -10,7 +11,22 @@ declare function publishSandboxFileArtifactInScope(deps: ApiRouteDeps, input: {
     path: string;
     signal?: AbortSignal | undefined;
 }): Promise<SandboxFileArtifactReceipt>;
-export declare function sandboxArtifactRelativePath(value: string): string;
+/** Use the root captured by the same fenced Channel-A service that reads bytes,
+ * not the session's placement-home label or a caller-supplied root. */
+export declare function readSandboxArtifactFile(service: Pick<SandboxChannelAService, "capabilities" | "fsRead">, value: string, maxBytes: number): Promise<{
+    path: string;
+    sandboxPath: string;
+    read: {
+        path: string;
+        encoding: "base64" | "utf8";
+        content: string;
+        sizeBytes: number;
+        truncated: boolean;
+        isBinary: boolean;
+        revision: number;
+    };
+}>;
+export declare function sandboxArtifactRelativePath(value: string, workspaceRoot?: string): string;
 export declare function sandboxArtifactSafeFilename(filename: string): string;
 export declare function sandboxFileContentType(filename: string): string;
 export declare function sandboxArtifactIdentity(input: {

package/dist/scheduled-task-blockers.d.ts

@@ -0,0 +1,39 @@
+import { type Database, type ScheduledTaskBlockerDecision, type ScheduledTaskBlockerFacts, type ScheduledTaskBlockerRun } from "@opengeni/db";
+import { type EventBus } from "@opengeni/events";
+import type { Observability } from "@opengeni/observability";
+/**
+ * A schedule must never stay stuck without its owner knowing. After each
+ * settled scheduled run:
+ *
+ * - When the platform knows no later run can start until a person acts (its
+ *   chat is paused or gone, a pinned account or other resource it needs is
+ *   unavailable, or it was refused as non-retryable), the schedule pauses
+ *   itself with that reason and its owner is told once.
+ * - When runs keep failing or being skipped for a reason that may clear by
+ *   itself, the owner is told once, after {@link SCHEDULED_TASK_BLOCKER_STREAK}
+ *   in a row; the schedule keeps running. A single skip or failure is normal.
+ *
+ * The notice is withdrawn when a later run succeeds or a person resumes,
+ * pauses or deletes the schedule. Only scheduled (not manual) runs count, and
+ * only runs since the schedule was last edited or resumed.
+ */
+export declare const SCHEDULED_TASK_BLOCKER_STREAK = 3;
+type Blocker = {
+    reason: string;
+    text: string;
+};
+/** A blocker no later run can get past until a person acts, or null. */
+export declare function scheduledRunHardBlocker(task: Pick<ScheduledTaskBlockerFacts["task"], "runMode">, run: ScheduledTaskBlockerRun): Blocker | null;
+export declare function scheduledTaskBlockerNoticeKey(taskId: string): string;
+/** The pure review of one schedule's newest settled scheduled run. */
+export declare function decideScheduledTaskBlocker(facts: ScheduledTaskBlockerFacts): ScheduledTaskBlockerDecision;
+type Dependencies = {
+    db: Database;
+    bus: EventBus;
+    observability?: Pick<Observability, "error"> | undefined;
+};
+/** Post or withdraw the owner notice a review left pending. */
+export declare function deliverScheduledTaskBlockerNotice(deps: Dependencies, workspaceId: string, taskId: string): Promise<void>;
+/** One bounded pass over schedules with a run to review or a notice to deliver. */
+export declare function reviewScheduledTaskBlockerInventory(deps: Dependencies): Promise<void>;
+export {};

package/dist/scheduled-task-deletion.d.ts

@@ -1,13 +1,12 @@
-import type { ScheduledTask as ScheduledTaskValue } from "@opengeni/contracts";
+import type { AccessGrant, ScheduledTask as ScheduledTaskValue } from "@opengeni/contracts";
 import { type ApiRouteDeps } from "@opengeni/core";
 import type { TemporalScheduleCleanupClaim } from "@opengeni/db";
 /** Execute one exact connector obligation frozen into the tombstone outbox row. */
 export declare function cleanupScheduledTaskConnectorAuthorization(deps: ApiRouteDeps, claim: TemporalScheduleCleanupClaim): Promise<void>;
 /** Shared HTTP/MCP domain operation: authorize, tombstone, persist, then accelerate cleanup. */
-export declare function deleteScheduledTaskWithDurableCleanup(deps: ApiRouteDeps, input: {
-    workspaceId: string;
+export declare function deleteScheduledTaskWithDurableCleanup(deps: ApiRouteDeps, request: {
+    grant: AccessGrant;
     taskId: string;
-    subjectId: string;
 }): Promise<{
     task: ScheduledTaskValue;
     changed: boolean;

package/dist/scheduled-task-lifecycle.d.ts

@@ -0,0 +1,14 @@
+import { type Database } from "@opengeni/db";
+import type { ScheduledTask } from "@opengeni/contracts";
+import type { EventBus } from "@opengeni/events";
+import type { Observability } from "@opengeni/observability";
+type Dependencies = {
+    db: Database;
+    sync(task: Pick<ScheduledTask, "id" | "workspaceId" | "temporalScheduleId">): Promise<void>;
+    /** Enables blocked-schedule review: self-pause and the owner notice it posts. */
+    bus?: EventBus;
+    observability?: Pick<Observability, "error">;
+};
+export declare function reconcileExhaustedScheduledTasks(deps: Dependencies): Promise<void>;
+export declare function startScheduledTaskLifecyclePump(deps: Dependencies, intervalMs?: number): () => Promise<void>;
+export {};

package/dist/secret-answers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Secret ask-card answers on the way in. Every surface that accepts an answer
+ * (the events route, `session_human_input_respond`) prepares them here: the
+ * value is generated when asked for, encrypted with the vault key and sized.
+ * The prepared answers go to `acceptSessionHumanInputResponse`, which writes
+ * them in the accept transaction; nothing here is stored or logged.
+ */
+import { type Settings } from "@opengeni/config";
+import { type HumanInputSecretAnswer, type SecretPrincipal } from "@opengeni/contracts";
+import { type PreparedSecretAnswer, type VaultDbContext } from "@opengeni/db";
+export type SecretAnswerSource = "human" | "agent";
+/**
+ * Generate and encrypt write-only secret answers. Agents may only send a
+ * generate spec (AC-7): a raw value from an agent is refused here, before
+ * anything is written.
+ */
+export declare function prepareSecretAnswers(settings: Settings, answers: readonly HumanInputSecretAnswer[], source: SecretAnswerSource): PreparedSecretAnswer[];
+/** A raw value where only a reference or generate spec is allowed. */
+export declare class SecretAnswerRejectedError extends Error {
+    readonly name = "SecretAnswerRejectedError";
+}
+/** The vault authority that writes a person's answers. */
+export declare function humanSecretWriteContext(input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+}): VaultDbContext;
+/** The vault authority that writes an agent attempt's generated answers. */
+export declare function attemptSecretWriteContext(principal: Extract<SecretPrincipal, {
+    kind: "attempt";
+}>): VaultDbContext;
+/**
+ * Separate the write-only secret answers from a submitted response. They may
+ * arrive inside the response (the documented shape) or next to it on the
+ * event payload; both are merged and removed from what gets stored.
+ */
+export declare function splitSecretAnswers<T>(response: T, besideResponse: readonly HumanInputSecretAnswer[] | undefined): {
+    response: T;
+    secretAnswers: HumanInputSecretAnswer[];
+};

package/dist/session-create-observability.d.ts

@@ -0,0 +1,5 @@
+import { type Observability } from "@opengeni/observability";
+type SessionCreatePhase = "authorization" | "body_read" | "site_origin" | "core_create" | "response_projection";
+/** Content-free child boundaries within the existing HTTP request span. */
+export declare function measureSessionCreatePhase<T>(observability: Pick<Observability, "startSpan"> | null | undefined, phase: SessionCreatePhase, work: () => Promise<T>): Promise<T>;
+export {};