@opengeni/contracts 3.1.0-canary.2 → 3.1.2

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;

package/dist/secret-generator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The one password generator shared by agents (`secret_save` with
+ * `generate`), the ask card's server-side generate, and the web/mobile UI.
+ *
+ * Isomorphic and dependency-free: randomness comes from
+ * `crypto.getRandomValues` unless a test injects `random`. Output is ASCII
+ * only, and every character is drawn uniformly from the selected alphabet by
+ * rejection sampling, so no modulo bias is introduced. When
+ * `requireEachClass` is set, whole candidates lacking an enabled class are
+ * rejected and redrawn, which keeps the result uniform over all compliant
+ * passwords.
+ */
+import { z } from "zod";
+export declare const SECRET_GENERATOR_DEFAULT_SYMBOLS = "!#%+-.:=?@_";
+/** Characters that are easy to confuse when a person reads them. */
+export declare const SECRET_GENERATOR_AMBIGUOUS_CHARACTERS = "0O1lI|";
+export declare const GeneratePasswordSpec: 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>;
+export type GeneratePasswordSpec = z.infer<typeof GeneratePasswordSpec>;
+export type GeneratePasswordSpecInput = z.input<typeof GeneratePasswordSpec>;
+export declare class PasswordGeneratorError extends Error {
+    constructor(message: string);
+}
+/** The enabled character classes after exclusions; empty classes are dropped. */
+export declare function passwordCharacterClasses(spec: GeneratePasswordSpec): string[];
+/** Generate a password. The spec input is parsed (defaults applied) first. */
+export declare function generatePassword(spec?: GeneratePasswordSpecInput, random?: (n: number) => Uint8Array): string;
+export type PasswordStrengthLabel = "weak" | "fair" | "strong" | "very_strong";
+/**
+ * Estimated entropy from length and the character pools the password uses.
+ * A display hint for the UI, not a security decision.
+ */
+export declare function passwordStrength(password: string): {
+    bits: number;
+    label: PasswordStrengthLabel;
+};

package/dist/secret-references.d.ts

@@ -0,0 +1,90 @@
+export type SecretReferenceKind = "secret" | "secretfile";
+export type SecretReferenceTarget = {
+    form: "id";
+    itemId: string;
+    field: string | null;
+} | {
+    form: "path";
+    segments: [string] | [string, string] | [string, string, string];
+};
+export interface SecretReference {
+    kind: SecretReferenceKind;
+    raw: string;
+    /** Offsets in the source text; `end` is exclusive. */
+    start: number;
+    end: number;
+    target: SecretReferenceTarget;
+    otp: boolean;
+    previous: boolean;
+}
+export type SecretTextToken = 
+/** Escapes already unescaped. */
+{
+    type: "text";
+    value: string;
+} | {
+    type: "reference";
+    reference: SecretReference;
+} | {
+    type: "invalid";
+    raw: string;
+    start: number;
+    end: number;
+    reason: string;
+};
+/** Fast-path needle; also matches `{{secretfile:`. */
+export declare const SECRET_REFERENCE_MARKER = "{{secret";
+export declare class SecretReferenceSyntaxError extends Error {
+    readonly reason: string;
+    constructor(reason: string, message?: string);
+}
+export declare function containsSecretReference(text: string): boolean;
+/**
+ * Split text into literal text, references and invalid candidates. Adjacent
+ * text is merged; an escaped reference (`\{{secret:…}}`) becomes literal
+ * text without the backslash. Never throws.
+ */
+export declare function tokenizeSecretText(text: string): SecretTextToken[];
+/** Valid references only, in text order. */
+export declare function findSecretReferences(text: string): SecretReference[];
+/** Invalid candidates only, in text order. */
+export declare function findInvalidSecretReferences(text: string): Array<Extract<SecretTextToken, {
+    type: "invalid";
+}>>;
+/** Parse exactly one reference (`{{…}}`). Throws SecretReferenceSyntaxError. */
+export declare function parseSecretReference(raw: string): SecretReference;
+export type FormatSecretReferenceInput = {
+    kind?: SecretReferenceKind;
+    vault?: string;
+    item: string;
+    field?: string;
+    otp?: boolean;
+    previous?: boolean;
+} | {
+    kind?: SecretReferenceKind;
+    itemId: string;
+    field?: string;
+    otp?: boolean;
+    previous?: boolean;
+};
+/** Build a reference. Throws SecretReferenceSyntaxError when a name cannot be referenced. */
+export declare function formatSecretReference(input: FormatSecretReferenceInput): string;
+/** NFC + trim + lowercase. For UI and dedupe only; SQL `vault_name_key` is authoritative. */
+export declare function secretNameKey(name: string): string;
+/** Canonical dedupe key within one call (same target and modifiers → same key). */
+export declare function referenceKey(ref: SecretReference): string;
+/** Remove escapes (`\{{secret:…}}` → `{{secret:…}}`); references stay as written. */
+export declare function unescapeSecretText(text: string): string;
+/** Every valid reference in every string value of a JSON-like structure. */
+export declare function collectReferencesDeep(value: unknown): SecretReference[];
+/** Every invalid candidate in every string value of a JSON-like structure. */
+export declare function collectInvalidReferencesDeep(value: unknown): Array<Extract<SecretTextToken, {
+    type: "invalid";
+}>>;
+/**
+ * Deep copy with each reference replaced by `replace(ref)` and escapes
+ * removed. Strings without the marker are copied unchanged; invalid
+ * candidates are kept verbatim (callers reject them before replacing).
+ * Object keys are not rewritten.
+ */
+export declare function replaceReferencesDeep<T>(value: T, replace: (ref: SecretReference) => string): T;