@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/sandbox-recovery.ts

@@ -0,0 +1,129 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/** Public, content-free selection. Never include native provider bindings. */
+export const SandboxRecoverySelection = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      version: z.literal(1),
+      sessionId: z.string().uuid(),
+      sandboxGroupId: z.string().uuid(),
+      leaseId: z.string().uuid(),
+      routeEpoch: z.number().int().nonnegative(),
+      authorityEpoch: z.number().int().positive(),
+      leaseEpoch: z.number().int().nonnegative(),
+      workspaceGeneration: z.number().int().nonnegative(),
+      archiveGeneration: z.number().int().nonnegative(),
+      artifactId: z.string().uuid(),
+      revision: z.string().min(1).max(512),
+      capturedAt: z.string().datetime(),
+    })
+    .strict(),
+);
+export type SandboxRecoverySelection = z.infer<typeof SandboxRecoverySelection>;
+
+export const SandboxRecoveryProjection = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      version: z.literal(1),
+      status: z.enum([
+        "unsupported",
+        "blocked",
+        "eligible",
+        "consent_accepted",
+        "restoring",
+        "restored",
+      ]),
+      reason: z.string().max(128).nullable(),
+      checkpoint: SandboxRecoverySelection.nullable(),
+      operationId: z.string().uuid().nullable(),
+      /** Retry may elect a system-selected verified checkpoint; no consent POST. */
+      automaticAvailable: z.boolean().optional(),
+      /** What an automatic Retry will do: restore `checkpoint`, or continue on a
+       * new empty workspace because no usable checkpoint survived the loss. */
+      automaticLane: z.enum(["checkpoint", "fresh_workspace"]).optional(),
+      /** For a timed recovery wait: the earliest time a Retry or a new message
+       * can let Opengeni decide again. Nothing proceeds by itself before then. */
+      availableAt: z.string().datetime().optional(),
+    })
+    .strict(),
+);
+export type SandboxRecoveryProjection = z.infer<typeof SandboxRecoveryProjection>;
+
+/** Why a definitively lost managed sandbox continues on an empty workspace. */
+export const SandboxFreshWorkspaceReason = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "archive_unavailable",
+    "archive_unverified",
+    "checkpoint_unrestorable",
+    "checkpoint_restore_failed",
+  ]),
+);
+export type SandboxFreshWorkspaceReason = z.infer<typeof SandboxFreshWorkspaceReason>;
+
+/** Durable, content-free fresh-workspace decision for one group member. */
+export const SandboxFreshWorkspaceRecovery = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      version: z.literal(1),
+      sessionId: z.string().uuid(),
+      sandboxGroupId: z.string().uuid(),
+      leaseId: z.string().uuid(),
+      leaseEpoch: z.number().int().nonnegative(),
+      workspaceGeneration: z.number().int().nonnegative(),
+      archiveGeneration: z.number().int().nonnegative().nullable(),
+      lostAt: z.string().datetime(),
+      reason: SandboxFreshWorkspaceReason,
+    })
+    .strict(),
+);
+export type SandboxFreshWorkspaceRecovery = z.infer<typeof SandboxFreshWorkspaceRecovery>;
+
+export const SandboxRecoveryRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      operationId: z.string().uuid(),
+      acceptHistoricalCheckpoint: z.literal(true),
+      selection: SandboxRecoverySelection,
+    })
+    .strict(),
+);
+export type SandboxRecoveryRequest = z.infer<typeof SandboxRecoveryRequest>;
+
+export const SandboxRecoveryResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      outcome: z.enum(["accepted", "replayed"]),
+      operationId: z.string().uuid(),
+      recovery: SandboxRecoveryProjection,
+    })
+    .strict(),
+);
+export type SandboxRecoveryResponse = z.infer<typeof SandboxRecoveryResponse>;
+
+/** Re-injected from durable receipts on every attempt, not lossy transcript state. */
+export function sandboxRecoveryDiscontinuity(selection: SandboxRecoverySelection): string {
+  return `Filesystem discontinuity: the human explicitly consented to restoring this session's workspace from the checkpoint captured at ${selection.capturedAt} (archive generation ${selection.archiveGeneration}, pre-recovery workspace generation ${selection.workspaceGeneration}). Newer filesystem changes are unavailable. The generation gap is not a count of lost files or edits. Conversation and tool receipts remain historical evidence, not proof that their files still exist. External effects are not undone. Verify the current filesystem before relying on previous work. Never automatically replay prior commands or operations with unknown outcomes to rebuild missing files. Consent alone is not proof that restoration succeeded.`;
+}
+
+/** 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 function automaticSandboxRecoveryDiscontinuity(
+  selection: SandboxRecoverySelection,
+  scope: "session" | "shared" = "session",
+): string {
+  const subject =
+    scope === "shared"
+      ? "the latest verified checkpoint of the sandbox this session shares with other sessions"
+      : "this session's latest verified checkpoint";
+  return `Filesystem discontinuity: after the managed sandbox was lost, Opengeni selected ${subject}, captured at ${selection.capturedAt} (archive generation ${selection.archiveGeneration}, pre-recovery workspace generation ${selection.workspaceGeneration}). Newer filesystem changes may be unavailable; the generation gap is not a count of lost files or edits. Conversation and tool receipts remain historical evidence, not proof that their files still exist. External effects are not undone. Verify the restored filesystem before relying on previous work. Never automatically replay prior commands or operations with unknown outcomes. Checkpoint selection alone is not proof that restoration succeeded.`;
+}
+
+/** 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 function freshWorkspaceSandboxRecoveryDiscontinuity(
+  recovery: SandboxFreshWorkspaceRecovery,
+): string {
+  return `Filesystem discontinuity: the previous managed sandbox was lost at ${recovery.lostAt} and there is no checkpoint Opengeni can restore automatically, so Opengeni continued this session on a new empty workspace. Files, repository clones, installed packages and running processes from before that time are not available in this workspace; do not assume they exist. Anything now in the workspace was created after that loss. Conversation and tool receipts from before it remain historical evidence, not proof that their files still exist. External effects are not undone. Verify the current filesystem before relying on previous work, and recreate what you need deliberately. Never automatically replay prior commands or operations with unknown outcomes.`;
+}

package/src/scoped-knowledge.ts

@@ -1,29 +1,36 @@
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
 /** Tenant scope for normalized knowledge and source provenance. */
-export const ScopedKnowledgeScopeKind = z.enum(["organization", "workspace", "personal"]);
+export const ScopedKnowledgeScopeKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["organization", "workspace", "personal"]),
+);
 export type ScopedKnowledgeScopeKind = z.infer<typeof ScopedKnowledgeScopeKind>;
 
-export const ScopedKnowledgeScope = z.discriminatedUnion("kind", [
-  z.object({
-    kind: z.literal("organization"),
-    workspaceId: z.null(),
-    subjectId: z.null(),
-  }),
-  z.object({
-    kind: z.literal("workspace"),
-    workspaceId: z.string().uuid(),
-    subjectId: z.null(),
-  }),
-  z.object({
-    kind: z.literal("personal"),
-    workspaceId: z.string().uuid().nullable(),
-    subjectId: z.string().min(1).max(1024),
-  }),
-]);
+export const ScopedKnowledgeScope = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("organization"),
+      workspaceId: z.null(),
+      subjectId: z.null(),
+    }),
+    z.object({
+      kind: z.literal("workspace"),
+      workspaceId: z.string().uuid(),
+      subjectId: z.null(),
+    }),
+    z.object({
+      kind: z.literal("personal"),
+      workspaceId: z.string().uuid().nullable(),
+      subjectId: z.string().min(1).max(1024),
+    }),
+  ]),
+);
 export type ScopedKnowledgeScope = z.infer<typeof ScopedKnowledgeScope>;
 
-export const ScopedKnowledgeActorKind = z.enum(["human", "service"]);
+export const ScopedKnowledgeActorKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["human", "service"]),
+);
 export type ScopedKnowledgeActorKind = z.infer<typeof ScopedKnowledgeActorKind>;
 
 /**
@@ -36,46 +43,57 @@ export type ScopedKnowledgeActor = {
   initiatingHumanSubjectId: string | null;
 };
 
-export const KnowledgeLifecycleState = z.enum(["active", "deleted", "revoked"]);
+export const KnowledgeLifecycleState = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["active", "deleted", "revoked"]),
+);
 export type KnowledgeLifecycleState = z.infer<typeof KnowledgeLifecycleState>;
 
-export const KnowledgeLifecycleEventType = z.enum([
-  "deleted",
-  "revoked",
-  "restored",
-  "acl_changed",
-  "sync_succeeded",
-  "sync_failed",
-  "object_version_added",
-]);
+export const KnowledgeLifecycleEventType = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "deleted",
+    "revoked",
+    "restored",
+    "acl_changed",
+    "sync_succeeded",
+    "sync_failed",
+    "object_version_added",
+  ]),
+);
 export type KnowledgeLifecycleEventType = z.infer<typeof KnowledgeLifecycleEventType>;
 
-export const KnowledgeSyncRunState = z.enum(["started", "succeeded", "failed"]);
+export const KnowledgeSyncRunState = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["started", "succeeded", "failed"]),
+);
 export type KnowledgeSyncRunState = z.infer<typeof KnowledgeSyncRunState>;
 
-export const KnowledgeClaimOrigin = z.enum(["explicit", "inferred"]);
+export const KnowledgeClaimOrigin = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["explicit", "inferred"]),
+);
 export type KnowledgeClaimOrigin = z.infer<typeof KnowledgeClaimOrigin>;
 
-export const KnowledgeClaimRelationType = z.enum(["supersedes", "conflicts_with"]);
+export const KnowledgeClaimRelationType = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["supersedes", "conflicts_with"]),
+);
 export type KnowledgeClaimRelationType = z.infer<typeof KnowledgeClaimRelationType>;
 
-export const KnowledgeClaimEvidencePolarity = z.enum(["supports", "contradicts"]);
+export const KnowledgeClaimEvidencePolarity = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["supports", "contradicts"]),
+);
 export type KnowledgeClaimEvidencePolarity = z.infer<typeof KnowledgeClaimEvidencePolarity>;
 
-export const KnowledgeClaimReviewState = z.enum(["proposed", "approved", "rejected", "revoked"]);
+export const KnowledgeClaimReviewState = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["proposed", "approved", "rejected", "revoked"]),
+);
 export type KnowledgeClaimReviewState = z.infer<typeof KnowledgeClaimReviewState>;
 
-export const KnowledgeFactObjectKind = z.enum([
-  "entity",
-  "text",
-  "number",
-  "boolean",
-  "json",
-  "timestamp",
-]);
+export const KnowledgeFactObjectKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["entity", "text", "number", "boolean", "json", "timestamp"]),
+);
 export type KnowledgeFactObjectKind = z.infer<typeof KnowledgeFactObjectKind>;
 
-export const KnowledgeChangeProposalTargetKind = z.enum(["instruction_policy", "preference"]);
+export const KnowledgeChangeProposalTargetKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["instruction_policy", "preference"]),
+);
 export type KnowledgeChangeProposalTargetKind = z.infer<typeof KnowledgeChangeProposalTargetKind>;
 
 export type KnowledgeProviderRecord = {

package/src/secret-generator.ts

@@ -0,0 +1,155 @@
+import { defineSchema } from "./define-schema";
+/**
+ * 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 const SECRET_GENERATOR_DEFAULT_SYMBOLS = "!#%+-.:=?@_";
+/** Characters that are easy to confuse when a person reads them. */
+export const SECRET_GENERATOR_AMBIGUOUS_CHARACTERS = "0O1lI|";
+
+const LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
+const UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const DIGITS = "0123456789";
+
+function isPrintableAscii(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 0x21 || code > 0x7e) return false;
+  }
+  return true;
+}
+
+export const GeneratePasswordSpec = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      length: z.number().int().min(8).max(128).default(24),
+      lowercase: z.boolean().default(true),
+      uppercase: z.boolean().default(true),
+      digits: z.boolean().default(true),
+      symbols: z.boolean().default(true),
+      // No quotes, $, `, \, braces, /, &, ; or | by default: generated values
+      // stay safe to paste into shells, URLs and config files.
+      symbolSet: z
+        .string()
+        .min(1)
+        .max(64)
+        .refine(isPrintableAscii, "symbolSet must be printable ASCII without spaces")
+        .default(SECRET_GENERATOR_DEFAULT_SYMBOLS),
+      excludeAmbiguous: z.boolean().default(true),
+      requireEachClass: z.boolean().default(true),
+    })
+    .strict()
+    .refine(
+      (spec) => spec.lowercase || spec.uppercase || spec.digits || spec.symbols,
+      "at least one character class must be enabled",
+    ),
+);
+export type GeneratePasswordSpec = z.infer<typeof GeneratePasswordSpec>;
+export type GeneratePasswordSpecInput = z.input<typeof GeneratePasswordSpec>;
+
+export class PasswordGeneratorError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PasswordGeneratorError";
+  }
+}
+
+function defaultRandom(n: number): Uint8Array {
+  const bytes = new Uint8Array(n);
+  globalThis.crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+function uniqueCharacters(value: string): string {
+  return [...new Set(value)].join("");
+}
+
+/** The enabled character classes after exclusions; empty classes are dropped. */
+export function passwordCharacterClasses(spec: GeneratePasswordSpec): string[] {
+  const ambiguous = spec.excludeAmbiguous ? new Set(SECRET_GENERATOR_AMBIGUOUS_CHARACTERS) : null;
+  const strip = (alphabet: string) =>
+    uniqueCharacters(alphabet)
+      .split("")
+      .filter((character) => !ambiguous?.has(character))
+      .join("");
+  const classes: string[] = [];
+  if (spec.lowercase) classes.push(strip(LOWERCASE));
+  if (spec.uppercase) classes.push(strip(UPPERCASE));
+  if (spec.digits) classes.push(strip(DIGITS));
+  if (spec.symbols) classes.push(strip(spec.symbolSet));
+  return classes.filter((characters) => characters.length > 0);
+}
+
+/** Draws `count` uniform indexes in `[0, size)` by rejection sampling bytes. */
+function uniformIndexes(count: number, size: number, random: (n: number) => Uint8Array): number[] {
+  if (size < 1 || size > 256) throw new PasswordGeneratorError("alphabet size out of range");
+  const limit = 256 - (256 % size);
+  const out: number[] = [];
+  let guard = 0;
+  while (out.length < count) {
+    const bytes = random(Math.max(16, (count - out.length) * 2));
+    for (const byte of bytes) {
+      if (byte < limit) out.push(byte % size);
+      if (out.length === count) break;
+    }
+    guard += 1;
+    if (guard > 10_000) throw new PasswordGeneratorError("random source is not producing entropy");
+  }
+  return out;
+}
+
+/** Generate a password. The spec input is parsed (defaults applied) first. */
+export function generatePassword(
+  spec?: GeneratePasswordSpecInput,
+  random: (n: number) => Uint8Array = defaultRandom,
+): string {
+  const parsed = GeneratePasswordSpec.parse(spec ?? {});
+  const classes = passwordCharacterClasses(parsed);
+  if (classes.length === 0) throw new PasswordGeneratorError("no characters available");
+  const alphabet = uniqueCharacters(classes.join(""));
+  const requireClasses = parsed.requireEachClass ? classes : [];
+  if (requireClasses.length > parsed.length) {
+    throw new PasswordGeneratorError("length is shorter than the number of required classes");
+  }
+  for (let attempt = 0; attempt < 1_000; attempt += 1) {
+    const password = uniformIndexes(parsed.length, alphabet.length, random)
+      .map((index) => alphabet[index]!)
+      .join("");
+    if (requireClasses.every((characters) => [...password].some((c) => characters.includes(c)))) {
+      return password;
+    }
+  }
+  throw new PasswordGeneratorError("could not satisfy the character class requirements");
+}
+
+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 function passwordStrength(password: string): {
+  bits: number;
+  label: PasswordStrengthLabel;
+} {
+  let pool = 0;
+  if (/[a-z]/.test(password)) pool += 26;
+  if (/[A-Z]/.test(password)) pool += 26;
+  if (/[0-9]/.test(password)) pool += 10;
+  if (/[^a-zA-Z0-9]/.test(password)) pool += 33;
+  const length = [...password].length;
+  const bits = pool === 0 ? 0 : Math.round(length * Math.log2(pool) * 10) / 10;
+  const label: PasswordStrengthLabel =
+    bits < 40 ? "weak" : bits < 60 ? "fair" : bits < 100 ? "strong" : "very_strong";
+  return { bits, label };
+}