@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/dist/product-analytics.d.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+/**
+ * The product surface through which a turn's request entered Opengeni.
+ *
+ * - `web`: the Opengeni web app (managed cookie or the local browser context).
+ * - `slack`: a Slack mention, command, DM, shortcut, thread reply, or reaction.
+ * - `api_key`: an API key or configured key, including the SDK and scripts.
+ * - `embedded`: a host that embeds Opengeni through signed delegation or an
+ *   organization key acting for an external user.
+ * - `scheduled`: a scheduled-task occurrence.
+ * - `agent`: another agent (a child session, an agent message, or Agent Steer).
+ * - `voice`: a realtime voice delegation or its end-of-call handoff.
+ * - `site`: a published workspace Site.
+ * - `automation`: an event-triggered automation run.
+ * - `mcp`: an external MCP client connected through workspace MCP OAuth.
+ * - `system`: Opengeni's own maintenance work with no human entry.
+ *
+ * Turns that no new request entered (goal continuations, child results,
+ * command results, wait timeouts, compaction) inherit the surface of the
+ * session's latest started turn. Null means no surface was captured: rows
+ * written before capture existed, or machine work in a session that has
+ * never started a turn with one.
+ */
+export declare const SESSION_TURN_SURFACES: readonly ["web", "slack", "api_key", "embedded", "scheduled", "agent", "voice", "site", "automation", "mcp", "system"];
+export declare const SessionTurnSurface: z.ZodEnum<{
+    agent: "agent";
+    api_key: "api_key";
+    automation: "automation";
+    embedded: "embedded";
+    mcp: "mcp";
+    scheduled: "scheduled";
+    site: "site";
+    slack: "slack";
+    system: "system";
+    voice: "voice";
+    web: "web";
+}>;
+export type SessionTurnSurface = z.infer<typeof SessionTurnSurface>;
+/**
+ * Request header the first-party web console sends while its tab is visible
+ * and the person interacted with it in the last few minutes. The API records
+ * server-side presence (`opengeni_active_users`, `user.active`) only for
+ * canonical managed browser sessions carrying this exact value, so an idle open
+ * tab, background polling and stream re-authorization never count as activity.
+ * Analytics only: it never grants or narrows access.
+ */
+export declare const OPENGENI_USER_ACTIVITY_HEADER = "x-opengeni-user-activity";
+export declare const OPENGENI_USER_ACTIVITY_ACTIVE = "active";
+/** Interaction recency, in milliseconds, behind the activity header. */
+export declare const OPENGENI_USER_ACTIVITY_WINDOW_MS: number;
+/** Parse a stored value; anything outside the fixed list is treated as absent. */
+export declare function sessionTurnSurfaceOrNull(value: unknown): SessionTurnSurface | null;
+/**
+ * Model provider families exported for analytics. Reserved Opengeni provider
+ * ids pass through unchanged; every operator-configured registry provider is
+ * reported as `registry` so a deployment's own naming never leaves it.
+ * `opengeni_private.analytics_model_provider` (migration 0533) mirrors this.
+ */
+export declare const ANALYTICS_MODEL_PROVIDERS: readonly ["openai", "azure", "codex-subscription", "supergrok-subscription", "opengeni-gateway", "workspace-gateway", "organization-gateway", "openrouter", "workspace-openrouter", "organization-openrouter", "opper", "workspace-opper", "organization-opper", "registry"];
+export declare const AnalyticsModelProvider: z.ZodEnum<{
+    azure: "azure";
+    "codex-subscription": "codex-subscription";
+    openai: "openai";
+    "opengeni-gateway": "opengeni-gateway";
+    openrouter: "openrouter";
+    opper: "opper";
+    "organization-gateway": "organization-gateway";
+    "organization-openrouter": "organization-openrouter";
+    "organization-opper": "organization-opper";
+    registry: "registry";
+    "supergrok-subscription": "supergrok-subscription";
+    "workspace-gateway": "workspace-gateway";
+    "workspace-openrouter": "workspace-openrouter";
+    "workspace-opper": "workspace-opper";
+}>;
+export type AnalyticsModelProvider = z.infer<typeof AnalyticsModelProvider>;
+/** Map an accepted turn's execution-policy provider id to its analytics family. */
+export declare function analyticsModelProvider(providerId: string | null | undefined): AnalyticsModelProvider | null;
+/**
+ * Tool family on a tool-call fact: an Opengeni first-party tool name,
+ * `integration:<catalog domain>` for a reviewed catalog integration, or
+ * `custom` for any other MCP server (a workspace's own server, a self-hosted
+ * provider, or an unreviewed catalog entry). The domain part is limited to
+ * {@link TOOL_FAMILY_INTEGRATION_DOMAINS}, so a tenant's own host name is
+ * never exported.
+ */
+export declare const ToolFamily: z.ZodString;
+export type ToolFamily = z.infer<typeof ToolFamily>;
+/**
+ * Reviewed integration domains that may appear as `integration:<domain>`:
+ * Opengeni's native provider domains plus the MCP host of every curated
+ * catalog entry (`data/catalog/curated.json`). A test keeps the curated part
+ * in sync. Any other domain is reported as `custom`.
+ */
+export declare const TOOL_FAMILY_INTEGRATION_DOMAINS: readonly ["github.com", "gitlab.com", "dev.azure.com", "slack.com", "chatgpt.com", "x.com", "reddit.com", "fiken.no", "api.atlassian.com", "googleapis.com", "gmailmcp.googleapis.com", "mcp.slack.com", "api.mobbin.com", "mcp.linear.app", "mcp.asana.com", "mcp.stripe.com", "mcp.figma.com", "mcp.canva.com", "mcp.sentry.dev", "mcp.vercel.com", "bindings.mcp.cloudflare.com", "mcp.paypal.com", "mcp.monday.com", "mcp.airtable.com", "mcp.zapier.com", "mcp.webflow.com", "mcp.supabase.com", "mcp.clickup.com", "mcp.calendly.com", "mcp.box.com", "mcp.dropbox.com", "mcp.amplitude.com", "mcp.posthog.com", "mcp.pagerduty.com", "mcp.apollo.io", "api.ahrefs.com", "mcp.semrush.com", "mcp.frontapp.com", "mcp.otter.ai", "mcp.notion.com", "mcp.hubspot.com", "mcp.atlassian.com", "mcp.intercom.com"];
+/**
+ * Tool family for an MCP server that is not first-party. The first candidate
+ * domain on the reviewed list wins; otherwise the server is `custom`.
+ */
+export declare function integrationToolFamily(candidateDomains: readonly (string | null | undefined)[]): ToolFamily;
+/**
+ * First-party tools the runtime exposes outside any MCP server: base sandbox
+ * and runtime tools, progressive-disclosure routers, media generation, and
+ * provider-hosted tool calls as the event stream names them.
+ */
+export declare const FIRST_PARTY_FUNCTION_TOOL_FAMILY_NAMES: readonly ["exec_command", "write_stdin", "view_image", "apply_patch", "skill_read", "repository_skill_read", "request_human_input", "list_models", "code_search", "tool_search", "tool_list", "tool_invoke", "generate_image", "generate_video", "get_video_generation_capabilities", "computer_screenshot", "web_search_call", "image_generation_call", "code_interpreter_call", "file_search_call", "computer_call", "local_shell_call", "shell_call", "apply_patch_call"];
+/**
+ * First-party tools served by in-process attempt definitions or the dedicated
+ * `files` server rather than the public `opengeni` MCP catalog.
+ */
+export declare const FIRST_PARTY_ATTEMPT_TOOL_FAMILY_NAMES: readonly ["skill_checkout", "skill_publish", "skill_install", "skill_remove", "skill_save", "skill_search", "operation_read", "knowledge_source_fetch", "knowledge_source_read", "files_get_download_url"];
+/**
+ * Opengeni's in-process integration tools that are not registry MCP servers,
+ * keyed by their catalog server id, with the provider domain they act on.
+ */
+export declare const IN_PROCESS_INTEGRATION_TOOL_FAMILY_DOMAINS: Readonly<Record<string, string>>;

package/dist/product-lifecycle-facts.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Content-free per-person product lifecycle facts.
+ *
+ * Migration `0532_product_lifecycle_fact_export.sql` captures one fact per
+ * product change with row triggers and writes it to the durable host export as
+ * the `lifecycle_fact` kind; `0565_usage_analytics_presence_and_facts.sql` adds
+ * `user.active`, `credits.granted` and `connection.revoked`. Every value is drawn from a fixed list; the
+ * database function `opengeni_private.product_lifecycle_fact_valid` enforces
+ * the same lists and a test keeps the two copies identical.
+ */
+/**
+ * Closed class of a positive credit grant (`grant` or `manual_credit_grant`
+ * ledger row). `opengeni_private.credit_grant_class` mirrors this mapping:
+ * - `signup_trial`: the one-time verified-signup trial (source `verified_signup_trial`).
+ * - `coupon`: a fully discounted Stripe checkout (source `stripe_checkout_coupon`).
+ * - `manual`: an operator grant (`manual_credit_grant` or source `operator_adjustment`).
+ * - `other`: any other grant source.
+ */
+export declare const CREDIT_GRANT_CLASSES: readonly ["signup_trial", "coupon", "manual", "other"];
+export type CreditGrantClass = (typeof CREDIT_GRANT_CLASSES)[number];
+/** Each fact type and the fixed values its `attribute` may carry. */
+export declare const PRODUCT_LIFECYCLE_FACT_ATTRIBUTES: {
+    /** A managed account was created. Attribute: first sign-in method. */
+    readonly "auth.sign_up": readonly ["email", "google", "github", "other"];
+    /**
+     * The account email became verified: by the verification link, or at
+     * creation when a social provider already verified it.
+     */
+    readonly "auth.email_verified": readonly [];
+    /** A live sign-in session was created. Attribute: method of that session. */
+    readonly "auth.sign_in": readonly ["email", "google", "github", "other"];
+    /** An organization was created by self-service setup or as an additional one. */
+    readonly "organization.setup": readonly ["created", "additional"];
+    /** A model subscription or organization model provider was connected. */
+    readonly "model.connected": readonly ["codex", "supergrok", "vercel_gateway", "openrouter", "anthropic", "claude_subscription", "opper"];
+    /** A credit top-up payment was granted. */
+    readonly "credits.purchased": readonly [];
+    /** Credits were granted without a purchase. Attribute: grant class. */
+    readonly "credits.granted": readonly ["signup_trial", "coupon", "manual", "other"];
+    /** An integration connection was created. Attribute: provider class. */
+    readonly "connection.created": readonly ["slack", "github", "gitlab", "azure_devops", "bitbucket", "google", "microsoft", "linear", "atlassian", "notion", "supabase", "datadog", "posthog", "openai", "x", "other"];
+    /**
+     * An integration connection was revoked, or deleted while still live.
+     * Attribute: provider class, the same list as `connection.created`.
+     */
+    readonly "connection.revoked": readonly ["slack", "github", "gitlab", "azure_devops", "bitbucket", "google", "microsoft", "linear", "atlassian", "notion", "supabase", "datadog", "posthog", "openai", "x", "other"];
+    readonly "scheduled_task.created": readonly [];
+    /** A catalog Skill was installed into a workspace. */
+    readonly "skill.installed": readonly [];
+    /** A Slack user was linked to an Opengeni user. */
+    readonly "slack.user_linked": readonly [];
+    /** A new Connected Machine was enrolled. */
+    readonly "machine.enrolled": readonly [];
+    /** A person became an active member of an organization that already had one. */
+    readonly "member.joined": readonly [];
+    /**
+     * A managed person was active in an authenticated browser session on a new
+     * UTC day: at most one fact per person per UTC day, with no organization.
+     */
+    readonly "user.active": readonly [];
+};
+export type ProductLifecycleFactType = keyof typeof PRODUCT_LIFECYCLE_FACT_ATTRIBUTES;
+export declare const PRODUCT_LIFECYCLE_FACT_TYPES: ProductLifecycleFactType[];
+/**
+ * What kind of subject caused the fact. Only `user` and `api_key` facts carry
+ * their opaque subject id; every other subject string is reduced to its kind
+ * because embedded hosts may put their own identifiers in it.
+ */
+export declare const PRODUCT_LIFECYCLE_SUBJECT_KINDS: readonly ["user", "api_key", "service", "other", "none"];
+export type ProductLifecycleSubjectKind = (typeof PRODUCT_LIFECYCLE_SUBJECT_KINDS)[number];
+/** Pseudonymous subject ids that may leave the database. */
+export declare const PRODUCT_LIFECYCLE_SUBJECT_ID_PATTERN: RegExp;
+export declare function isProductLifecycleFact(type: string, attribute: string | null): boolean;

package/dist/remember.d.ts

@@ -22,8 +22,8 @@ export declare const RememberScope: z.ZodEnum<{
 export type RememberScope = z.infer<typeof RememberScope>;
 /**
  * Ceiling for the Knowledge lane, which is retrieval evidence rather than
- * always-composed prompt text. The prompt-composed lanes are bounded far more
- * tightly: see `AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS` and
+ * always-composed prompt text. Other lanes have their own destination bounds:
+ * see `AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS` and
  * `AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS`.
  */
 export declare const REMEMBER_CONTENT_MAX_CHARS = 4000;
@@ -82,24 +82,70 @@ export declare const RememberHumanInputPrompt: z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
             multi_select: "multi_select";
+            secret: "secret";
             single_select: "single_select";
             text: "text";
         }>;
         prompt: z.ZodString;
         label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         helpText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        skillReview: z.ZodOptional<z.ZodObject<{
+        skillReview: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            removalOperationId: z.ZodOptional<z.ZodUUID>;
             sourceOperationId: z.ZodUUID;
             skillId: z.ZodUUID;
             revisionId: z.ZodUUID;
             expectedRevisionId: z.ZodNullable<z.ZodUUID>;
             expectedScopeVersion: z.ZodNumber;
-        }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         options: z.ZodDefault<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             label: z.ZodString;
             description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strip>>>;
+        secret: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            item: z.ZodString;
+            field: z.ZodDefault<z.ZodString>;
+            fieldKind: z.ZodDefault<z.ZodEnum<{
+                concealed: "concealed";
+                text: "text";
+                totp: "totp";
+            }>>;
+            itemType: z.ZodDefault<z.ZodEnum<{
+                api_key: "api_key";
+                login: "login";
+                note: "note";
+            }>>;
+            username: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                prompt: z.ZodString;
+                value: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strict>>>;
+            website: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            looksLike: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pattern: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            saveTo: z.ZodDefault<z.ZodEnum<{
+                task: "task";
+                user: "user";
+                workspace: "workspace";
+            }>>;
+            vault: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            allowGenerate: z.ZodDefault<z.ZodBoolean>;
+            generate: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                length: z.ZodDefault<z.ZodNumber>;
+                lowercase: z.ZodDefault<z.ZodBoolean>;
+                uppercase: z.ZodDefault<z.ZodBoolean>;
+                digits: z.ZodDefault<z.ZodBoolean>;
+                symbols: z.ZodDefault<z.ZodBoolean>;
+                symbolSet: z.ZodDefault<z.ZodString>;
+                excludeAmbiguous: z.ZodDefault<z.ZodBoolean>;
+                requireEachClass: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>>>;
+            autocomplete: z.ZodDefault<z.ZodEnum<{
+                "current-password": "current-password";
+                "new-password": "new-password";
+                off: "off";
+                "one-time-code": "one-time-code";
+            }>>;
+        }, z.core.$strict>>>;
         required: z.ZodDefault<z.ZodBoolean>;
         allowOther: z.ZodDefault<z.ZodBoolean>;
         validation: z.ZodOptional<z.ZodNullable<z.ZodObject<{
@@ -272,24 +318,70 @@ export declare const RememberReceipt: z.ZodDiscriminatedUnion<[z.ZodObject<{
             id: z.ZodString;
             kind: z.ZodEnum<{
                 multi_select: "multi_select";
+                secret: "secret";
                 single_select: "single_select";
                 text: "text";
             }>;
             prompt: z.ZodString;
             label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             helpText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-            skillReview: z.ZodOptional<z.ZodObject<{
+            skillReview: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                removalOperationId: z.ZodOptional<z.ZodUUID>;
                 sourceOperationId: z.ZodUUID;
                 skillId: z.ZodUUID;
                 revisionId: z.ZodUUID;
                 expectedRevisionId: z.ZodNullable<z.ZodUUID>;
                 expectedScopeVersion: z.ZodNumber;
-            }, z.core.$strip>>;
+            }, z.core.$strip>>>;
             options: z.ZodDefault<z.ZodArray<z.ZodObject<{
                 id: z.ZodString;
                 label: z.ZodString;
                 description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             }, z.core.$strip>>>;
+            secret: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                item: z.ZodString;
+                field: z.ZodDefault<z.ZodString>;
+                fieldKind: z.ZodDefault<z.ZodEnum<{
+                    concealed: "concealed";
+                    text: "text";
+                    totp: "totp";
+                }>>;
+                itemType: z.ZodDefault<z.ZodEnum<{
+                    api_key: "api_key";
+                    login: "login";
+                    note: "note";
+                }>>;
+                username: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                    prompt: z.ZodString;
+                    value: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                }, z.core.$strict>>>;
+                website: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                looksLike: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                pattern: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                saveTo: z.ZodDefault<z.ZodEnum<{
+                    task: "task";
+                    user: "user";
+                    workspace: "workspace";
+                }>>;
+                vault: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                allowGenerate: z.ZodDefault<z.ZodBoolean>;
+                generate: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                    length: z.ZodDefault<z.ZodNumber>;
+                    lowercase: z.ZodDefault<z.ZodBoolean>;
+                    uppercase: z.ZodDefault<z.ZodBoolean>;
+                    digits: z.ZodDefault<z.ZodBoolean>;
+                    symbols: z.ZodDefault<z.ZodBoolean>;
+                    symbolSet: z.ZodDefault<z.ZodString>;
+                    excludeAmbiguous: z.ZodDefault<z.ZodBoolean>;
+                    requireEachClass: z.ZodDefault<z.ZodBoolean>;
+                }, z.core.$strict>>>;
+                autocomplete: z.ZodDefault<z.ZodEnum<{
+                    "current-password": "current-password";
+                    "new-password": "new-password";
+                    off: "off";
+                    "one-time-code": "one-time-code";
+                }>>;
+            }, z.core.$strict>>>;
             required: z.ZodDefault<z.ZodBoolean>;
             allowOther: z.ZodDefault<z.ZodBoolean>;
             validation: z.ZodOptional<z.ZodNullable<z.ZodObject<{

package/dist/retained-output.d.ts

@@ -19,6 +19,7 @@ export declare const GENERATED_IMAGE_MAX_BYTES: number;
 export declare const GENERATED_VIDEO_MAX_BYTES: number;
 export declare const RetainedOutputKind: z.ZodEnum<{
     assistant_completion: "assistant_completion";
+    browser_screenshot: "browser_screenshot";
     computer_screenshot: "computer_screenshot";
     event_media: "event_media";
     file: "file";
@@ -47,6 +48,7 @@ export declare const RetainedArtifactReferenceSchema: z.ZodObject<{
     artifactId: z.ZodString;
     kind: z.ZodEnum<{
         assistant_completion: "assistant_completion";
+        browser_screenshot: "browser_screenshot";
         computer_screenshot: "computer_screenshot";
         event_media: "event_media";
         file: "file";
@@ -104,6 +106,7 @@ export declare const RetainedOutputEvidenceSchema: z.ZodDiscriminatedUnion<[z.Zo
     artifactId: z.ZodString;
     kind: z.ZodEnum<{
         assistant_completion: "assistant_completion";
+        browser_screenshot: "browser_screenshot";
         computer_screenshot: "computer_screenshot";
         event_media: "event_media";
         file: "file";
@@ -162,6 +165,7 @@ export declare const RetainedArtifactMetadataSchema: z.ZodUnion<readonly [z.ZodO
     artifactId: z.ZodString;
     kind: z.ZodEnum<{
         assistant_completion: "assistant_completion";
+        browser_screenshot: "browser_screenshot";
         computer_screenshot: "computer_screenshot";
         event_media: "event_media";
         file: "file";
@@ -223,7 +227,11 @@ export type RetainedScreenshotArtifactInput = RetainedArtifactFileInput & {
     width: number;
     height: number;
     expiresAt: string;
+    kind?: "computer_screenshot" | "browser_screenshot";
 };
+export type RetainedSessionScreenshotKind = "computer_screenshot" | "browser_screenshot";
+/** The persisted, server-authored storage key distinguishes browser captures from legacy computer captures. */
+export declare function retainedSessionScreenshotKindFromObjectKey(objectKey: string): RetainedSessionScreenshotKind | null;
 export type RetainedGeneratedImageArtifactInput = RetainedArtifactFileInput & {
     width: number;
     height: number;

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

@@ -22,6 +22,7 @@ export declare const SandboxFileArtifactReceipt: z.ZodObject<{
         artifactId: z.ZodString;
         kind: z.ZodEnum<{
             assistant_completion: "assistant_completion";
+            browser_screenshot: "browser_screenshot";
             computer_screenshot: "computer_screenshot";
             event_media: "event_media";
             file: "file";

package/dist/sandbox-provider-command.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 /** Provider-owned execution identity and acknowledged output cursors. These
  * values are retained by the control plane, never recovered from sandbox files. */
-export declare const SandboxProviderCommand: z.ZodObject<{
+export declare const ModalLegacyProviderCommand: z.ZodObject<{
     kind: z.ZodLiteral<"modal-control-v1">;
     sandboxId: z.ZodString;
     taskId: z.ZodString;
@@ -20,4 +20,94 @@ export declare const SandboxProviderCommand: z.ZodObject<{
         }, z.core.$strict>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+export type ModalLegacyProviderCommand = z.infer<typeof ModalLegacyProviderCommand>;
+export declare const CommandSupervisionDescriptor: z.ZodObject<{
+    protocol: z.ZodLiteral<"native-subreaper-v1">;
+    invocationId: z.ZodString;
+    nonce: z.ZodString;
+    controlPath: z.ZodString;
+}, z.core.$strict>;
+export type CommandSupervisionDescriptor = z.infer<typeof CommandSupervisionDescriptor>;
+export declare const CommandSupervisionReceipt: z.ZodObject<{
+    protocol: z.ZodLiteral<"native-subreaper-v1">;
+    invocationId: z.ZodString;
+    receiptId: z.ZodString;
+    leaderExitCode: z.ZodNumber;
+}, z.core.$strict>;
+export type CommandSupervisionReceipt = z.infer<typeof CommandSupervisionReceipt>;
+export declare const ModalRouterProviderCommand: z.ZodObject<{
+    kind: z.ZodLiteral<"modal-router-v1">;
+    sandboxId: z.ZodString;
+    taskId: z.ZodString;
+    execId: z.ZodString;
+    pty: z.ZodOptional<z.ZodBoolean>;
+    supervision: z.ZodOptional<z.ZodObject<{
+        protocol: z.ZodLiteral<"native-subreaper-v1">;
+        invocationId: z.ZodString;
+        nonce: z.ZodString;
+        controlPath: z.ZodString;
+    }, z.core.$strict>>;
+    streams: z.ZodObject<{
+        stdout: z.ZodObject<{
+            byteOffset: z.ZodNumber;
+            utf8Remainder: z.ZodString;
+            eof: z.ZodBoolean;
+            exitCode: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>;
+        stderr: z.ZodObject<{
+            byteOffset: z.ZodNumber;
+            utf8Remainder: z.ZodString;
+            eof: z.ZodBoolean;
+            exitCode: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ModalRouterProviderCommand = z.infer<typeof ModalRouterProviderCommand>;
+/** Legacy locators are read-only compatibility for already launched commands;
+ * new starts use authenticated task-router byte offsets, never batch indices. */
+export declare const SandboxProviderCommand: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"modal-control-v1">;
+    sandboxId: z.ZodString;
+    taskId: z.ZodString;
+    execId: z.ZodString;
+    pty: z.ZodOptional<z.ZodBoolean>;
+    streams: z.ZodObject<{
+        stdout: z.ZodObject<{
+            batchIndex: z.ZodNumber;
+            utf8Remainder: z.ZodString;
+            exitCode: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>;
+        stderr: z.ZodObject<{
+            batchIndex: z.ZodNumber;
+            utf8Remainder: z.ZodString;
+            exitCode: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"modal-router-v1">;
+    sandboxId: z.ZodString;
+    taskId: z.ZodString;
+    execId: z.ZodString;
+    pty: z.ZodOptional<z.ZodBoolean>;
+    supervision: z.ZodOptional<z.ZodObject<{
+        protocol: z.ZodLiteral<"native-subreaper-v1">;
+        invocationId: z.ZodString;
+        nonce: z.ZodString;
+        controlPath: z.ZodString;
+    }, z.core.$strict>>;
+    streams: z.ZodObject<{
+        stdout: z.ZodObject<{
+            byteOffset: z.ZodNumber;
+            utf8Remainder: z.ZodString;
+            eof: z.ZodBoolean;
+            exitCode: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>;
+        stderr: z.ZodObject<{
+            byteOffset: z.ZodNumber;
+            utf8Remainder: z.ZodString;
+            eof: z.ZodBoolean;
+            exitCode: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "kind">;
 export type SandboxProviderCommand = z.infer<typeof SandboxProviderCommand>;

package/dist/sandbox-recovery.d.ts

@@ -0,0 +1,146 @@
+import { z } from "zod";
+/** Public, content-free selection. Never include native provider bindings. */
+export declare const SandboxRecoverySelection: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    sandboxGroupId: z.ZodString;
+    leaseId: z.ZodString;
+    routeEpoch: z.ZodNumber;
+    authorityEpoch: z.ZodNumber;
+    leaseEpoch: z.ZodNumber;
+    workspaceGeneration: z.ZodNumber;
+    archiveGeneration: z.ZodNumber;
+    artifactId: z.ZodString;
+    revision: z.ZodString;
+    capturedAt: z.ZodString;
+}, z.core.$strict>;
+export type SandboxRecoverySelection = z.infer<typeof SandboxRecoverySelection>;
+export declare const SandboxRecoveryProjection: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        consent_accepted: "consent_accepted";
+        eligible: "eligible";
+        restored: "restored";
+        restoring: "restoring";
+        unsupported: "unsupported";
+    }>;
+    reason: z.ZodNullable<z.ZodString>;
+    checkpoint: z.ZodNullable<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        sessionId: z.ZodString;
+        sandboxGroupId: z.ZodString;
+        leaseId: z.ZodString;
+        routeEpoch: z.ZodNumber;
+        authorityEpoch: z.ZodNumber;
+        leaseEpoch: z.ZodNumber;
+        workspaceGeneration: z.ZodNumber;
+        archiveGeneration: z.ZodNumber;
+        artifactId: z.ZodString;
+        revision: z.ZodString;
+        capturedAt: z.ZodString;
+    }, z.core.$strict>>;
+    operationId: z.ZodNullable<z.ZodString>;
+    automaticAvailable: z.ZodOptional<z.ZodBoolean>;
+    automaticLane: z.ZodOptional<z.ZodEnum<{
+        checkpoint: "checkpoint";
+        fresh_workspace: "fresh_workspace";
+    }>>;
+    availableAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SandboxRecoveryProjection = z.infer<typeof SandboxRecoveryProjection>;
+/** Why a definitively lost managed sandbox continues on an empty workspace. */
+export declare const SandboxFreshWorkspaceReason: z.ZodEnum<{
+    archive_unavailable: "archive_unavailable";
+    archive_unverified: "archive_unverified";
+    checkpoint_restore_failed: "checkpoint_restore_failed";
+    checkpoint_unrestorable: "checkpoint_unrestorable";
+}>;
+export type SandboxFreshWorkspaceReason = z.infer<typeof SandboxFreshWorkspaceReason>;
+/** Durable, content-free fresh-workspace decision for one group member. */
+export declare const SandboxFreshWorkspaceRecovery: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    sandboxGroupId: z.ZodString;
+    leaseId: z.ZodString;
+    leaseEpoch: z.ZodNumber;
+    workspaceGeneration: z.ZodNumber;
+    archiveGeneration: z.ZodNullable<z.ZodNumber>;
+    lostAt: z.ZodString;
+    reason: z.ZodEnum<{
+        archive_unavailable: "archive_unavailable";
+        archive_unverified: "archive_unverified";
+        checkpoint_restore_failed: "checkpoint_restore_failed";
+        checkpoint_unrestorable: "checkpoint_unrestorable";
+    }>;
+}, z.core.$strict>;
+export type SandboxFreshWorkspaceRecovery = z.infer<typeof SandboxFreshWorkspaceRecovery>;
+export declare const SandboxRecoveryRequest: z.ZodObject<{
+    operationId: z.ZodString;
+    acceptHistoricalCheckpoint: z.ZodLiteral<true>;
+    selection: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        sessionId: z.ZodString;
+        sandboxGroupId: z.ZodString;
+        leaseId: z.ZodString;
+        routeEpoch: z.ZodNumber;
+        authorityEpoch: z.ZodNumber;
+        leaseEpoch: z.ZodNumber;
+        workspaceGeneration: z.ZodNumber;
+        archiveGeneration: z.ZodNumber;
+        artifactId: z.ZodString;
+        revision: z.ZodString;
+        capturedAt: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type SandboxRecoveryRequest = z.infer<typeof SandboxRecoveryRequest>;
+export declare const SandboxRecoveryResponse: z.ZodObject<{
+    outcome: z.ZodEnum<{
+        accepted: "accepted";
+        replayed: "replayed";
+    }>;
+    operationId: z.ZodString;
+    recovery: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        status: z.ZodEnum<{
+            blocked: "blocked";
+            consent_accepted: "consent_accepted";
+            eligible: "eligible";
+            restored: "restored";
+            restoring: "restoring";
+            unsupported: "unsupported";
+        }>;
+        reason: z.ZodNullable<z.ZodString>;
+        checkpoint: z.ZodNullable<z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            sessionId: z.ZodString;
+            sandboxGroupId: z.ZodString;
+            leaseId: z.ZodString;
+            routeEpoch: z.ZodNumber;
+            authorityEpoch: z.ZodNumber;
+            leaseEpoch: z.ZodNumber;
+            workspaceGeneration: z.ZodNumber;
+            archiveGeneration: z.ZodNumber;
+            artifactId: z.ZodString;
+            revision: z.ZodString;
+            capturedAt: z.ZodString;
+        }, z.core.$strict>>;
+        operationId: z.ZodNullable<z.ZodString>;
+        automaticAvailable: z.ZodOptional<z.ZodBoolean>;
+        automaticLane: z.ZodOptional<z.ZodEnum<{
+            checkpoint: "checkpoint";
+            fresh_workspace: "fresh_workspace";
+        }>>;
+        availableAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type SandboxRecoveryResponse = z.infer<typeof SandboxRecoveryResponse>;
+/** Re-injected from durable receipts on every attempt, not lossy transcript state. */
+export declare function sandboxRecoveryDiscontinuity(selection: SandboxRecoverySelection): string;
+/** Stable tail instructions, sourced from a durable system recovery receipt.
+ * `shared` names the sandbox this session shares with other sessions; every
+ * member of that group receives its own receipt for the same selection. */
+export declare function automaticSandboxRecoveryDiscontinuity(selection: SandboxRecoverySelection, scope?: "session" | "shared"): string;
+/** Stable tail instructions for continuing on a new empty workspace. The text
+ * is true on every later turn too: it names the loss, not the current tree. */
+export declare function freshWorkspaceSandboxRecoveryDiscontinuity(recovery: SandboxFreshWorkspaceRecovery): string;