@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/learning-refusal.ts

@@ -0,0 +1,90 @@
+/**
+ * Browser/React Native-safe learning-refusal fact. Deliberately free of the
+ * zod runtime so synchronous timeline projection can read it.
+ *
+ * A durable learning write (a Skill, workspace instruction, or Knowledge
+ * change) that authority or policy refused carries this fact under `_meta`.
+ * MCP `_meta` never reaches the model: it survives only into the
+ * `agent.toolCall.output` event projection, where the timeline tells the
+ * person their change was not saved, whatever the agent then says.
+ */
+export const LEARNING_REFUSAL_META_KEY = "opengeni/learningRefusal" as const;
+
+export const LEARNING_REFUSAL_DESTINATIONS = ["skill", "instruction", "knowledge"] as const;
+/** Where the refused change would have been saved. */
+export type LearningRefusalDestination = (typeof LEARNING_REFUSAL_DESTINATIONS)[number];
+
+/**
+ * Why it was refused, in terms a person can act on. An agent saves to the
+ * destination it explicitly chooses, so only a genuine refusal is reported:
+ * - `learning_off`: Agent learning for this destination is Off, in this
+ *   chat's or the workspace's settings.
+ * - `site_agent`: historical receipts from the retired Site-specific policy.
+ * - `not_permitted`: any other definite authority or policy refusal.
+ */
+export const LEARNING_REFUSAL_REASONS = ["learning_off", "site_agent", "not_permitted"] as const;
+export type LearningRefusalReason = (typeof LEARNING_REFUSAL_REASONS)[number];
+
+/** Codes and ids only: never the refused text, a Skill's name, or a server message. */
+export type LearningRefusal = {
+  destination: LearningRefusalDestination;
+  reason: LearningRefusalReason;
+  /** The existing Skill the change targeted, when there was one. */
+  skillId?: string;
+};
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function oneOf<T extends string>(values: readonly T[], value: unknown): value is T {
+  return typeof value === "string" && (values as readonly string[]).includes(value);
+}
+
+/** The exact closed fact, or null when the input is not one. */
+function exactRefusal(value: unknown): LearningRefusal | null {
+  const fact = record(value);
+  if (!fact) return null;
+  if (Object.keys(fact).some((key) => !["destination", "reason", "skillId"].includes(key)))
+    return null;
+  if (!oneOf(LEARNING_REFUSAL_DESTINATIONS, fact.destination)) return null;
+  if (!oneOf(LEARNING_REFUSAL_REASONS, fact.reason)) return null;
+  if (fact.skillId !== undefined && (typeof fact.skillId !== "string" || !UUID.test(fact.skillId)))
+    return null;
+  return {
+    destination: fact.destination,
+    reason: fact.reason,
+    ...(fact.skillId !== undefined ? { skillId: fact.skillId as string } : {}),
+  };
+}
+
+/**
+ * The tool result with the refusal fact added to its `_meta`; nothing else
+ * changes. Only the exact closed shape is attached.
+ */
+export function withLearningRefusalMeta<T extends object>(result: T, refusal: LearningRefusal): T {
+  const fact = exactRefusal(refusal);
+  if (!fact) throw new TypeError("Invalid learning refusal");
+  const meta = record((result as { _meta?: unknown })._meta);
+  return { ...result, _meta: { ...meta, [LEARNING_REFUSAL_META_KEY]: fact } } as T;
+}
+
+/**
+ * The learning-refusal fact on a tool result or its event projection, when
+ * present and valid. Stored events outlive their writer: a reader ignores
+ * fields a newer writer added, and reads an unknown newer reason as the
+ * generic refusal rather than dropping the fact.
+ */
+export function learningRefusalFromToolOutput(output: unknown): LearningRefusal | null {
+  const fact = record(record(record(output)?._meta)?.[LEARNING_REFUSAL_META_KEY]);
+  if (!fact || typeof fact.reason !== "string") return null;
+  return exactRefusal({
+    destination: fact.destination,
+    reason: oneOf(LEARNING_REFUSAL_REASONS, fact.reason) ? fact.reason : "not_permitted",
+    ...(fact.skillId !== undefined ? { skillId: fact.skillId } : {}),
+  });
+}

package/src/managed-auth-session-sets.ts

@@ -1,3 +1,5 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
 export const MANAGED_AUTH_SESSION_SET_MAX_SLOTS = 8 as const;
@@ -7,45 +9,59 @@ export const MANAGED_AUTH_SESSION_SET_API_CONTRACT_HEADER = "x-opengeni-api-cont
 export const MANAGED_AUTH_SESSION_SET_API_CONTRACT_REVISION =
   "2026-08-personal-only-organization-setup-v1" as const;
 
-export const ManagedAuthSessionSetMode = z.enum(["legacy", "dual", "broker"]);
+export const ManagedAuthSessionSetMode = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["legacy", "dual", "broker"]),
+);
 export type ManagedAuthSessionSetMode = z.infer<typeof ManagedAuthSessionSetMode>;
 
-export const ManagedAuthLoginSlotState = z.enum(["active", "reauth_required"]);
+export const ManagedAuthLoginSlotState = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["active", "reauth_required"]),
+);
 export type ManagedAuthLoginSlotState = z.infer<typeof ManagedAuthLoginSlotState>;
 
-export const ManagedAuthVerifiedClaim = z.object({
-  kind: z.literal("email"),
-  value: z.string().email().max(320),
-});
+export const ManagedAuthVerifiedClaim = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    kind: z.literal("email"),
+    value: z.string().email().max(320),
+  }),
+);
 export type ManagedAuthVerifiedClaim = z.infer<typeof ManagedAuthVerifiedClaim>;
 
 /** Secret-free, browser-safe summary. Provider session ids and tokens never enter this shape. */
-export const ManagedAuthLoginSlot = z.object({
-  id: z.string().uuid(),
-  displayName: z.string().min(1).max(256),
-  verifiedClaim: ManagedAuthVerifiedClaim,
-  state: ManagedAuthLoginSlotState,
-});
+export const ManagedAuthLoginSlot = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: primitives.uuid,
+    displayName: z.string().min(1).max(256),
+    verifiedClaim: ManagedAuthVerifiedClaim,
+    state: ManagedAuthLoginSlotState,
+  }),
+);
 export type ManagedAuthLoginSlot = z.infer<typeof ManagedAuthLoginSlot>;
 
-export const ManagedAuthSessionSetState = z.enum(["ready", "actor_change_required"]);
+export const ManagedAuthSessionSetState = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["ready", "actor_change_required"]),
+);
 export type ManagedAuthSessionSetState = z.infer<typeof ManagedAuthSessionSetState>;
 
-export const ManagedAuthSessionSetProjection = z.object({
-  mode: ManagedAuthSessionSetMode,
-  generation: z.string().regex(/^[1-9][0-9]*$/),
-  actorEpoch: z.string().regex(/^[1-9][0-9]*$/),
-  csrfToken: z.string().min(32).max(512),
-  selectedSlotId: z.string().uuid().nullable(),
-  state: ManagedAuthSessionSetState,
-  slots: z.array(ManagedAuthLoginSlot).max(MANAGED_AUTH_SESSION_SET_MAX_SLOTS),
-});
+export const ManagedAuthSessionSetProjection = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    mode: ManagedAuthSessionSetMode,
+    generation: primitives.string.regex(/^[1-9][0-9]*$/),
+    actorEpoch: primitives.string.regex(/^[1-9][0-9]*$/),
+    csrfToken: z.string().min(32).max(512),
+    selectedSlotId: primitives.nullableUuid,
+    state: ManagedAuthSessionSetState,
+    slots: z.array(ManagedAuthLoginSlot).max(MANAGED_AUTH_SESSION_SET_MAX_SLOTS),
+  }),
+);
 export type ManagedAuthSessionSetProjection = z.infer<typeof ManagedAuthSessionSetProjection>;
 
-export const ManagedAuthOperationIdentity = z.object({
-  operationId: z.string().uuid(),
-  expectedGeneration: z.string().regex(/^[1-9][0-9]*$/),
-});
+export const ManagedAuthOperationIdentity = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    operationId: primitives.uuid,
+    expectedGeneration: primitives.string.regex(/^[1-9][0-9]*$/),
+  }),
+);
 export type ManagedAuthOperationIdentity = z.infer<typeof ManagedAuthOperationIdentity>;
 
 export const BootstrapManagedAuthSessionSetRequest = ManagedAuthOperationIdentity;
@@ -53,10 +69,8 @@ export type BootstrapManagedAuthSessionSetRequest = z.infer<
   typeof BootstrapManagedAuthSessionSetRequest
 >;
 
-export const ManagedAuthReturnIntent = z
-  .string()
-  .min(1)
-  .superRefine((value, context) => {
+export const ManagedAuthReturnIntent = /* @__PURE__ */ defineSchema(() =>
+  primitives.nonEmptyString.superRefine((value, context) => {
     if (new TextEncoder().encode(value).byteLength > MANAGED_AUTH_RETURN_INTENT_MAX_BYTES) {
       context.addIssue({ code: "custom", message: "return intent exceeds its UTF-8 byte limit" });
     }
@@ -100,34 +114,41 @@ export const ManagedAuthReturnIntent = z
         message: "return intent is not a valid same-origin path",
       });
     }
-  });
-
-export const BeginManagedAuthLoginTransactionRequest = ManagedAuthOperationIdentity.extend({
-  kind: z.enum(["add", "reauth"]),
-  slotId: z.string().uuid().optional(),
-  returnIntent: ManagedAuthReturnIntent.optional(),
-}).superRefine((value, context) => {
-  if ((value.kind === "reauth") !== Boolean(value.slotId)) {
-    context.addIssue({
-      code: "custom",
-      path: ["slotId"],
-      message: "reauth requires exactly one slot id and add forbids one",
-    });
-  }
-});
+  }),
+);
+
+export const BeginManagedAuthLoginTransactionRequest = /* @__PURE__ */ defineSchema(() =>
+  ManagedAuthOperationIdentity.extend({
+    kind: z.enum(["add", "reauth"]),
+    slotId: primitives.optionalUuid,
+    returnIntent: ManagedAuthReturnIntent.optional(),
+  }).superRefine((value, context) => {
+    if ((value.kind === "reauth") !== Boolean(value.slotId)) {
+      context.addIssue({
+        code: "custom",
+        path: ["slotId"],
+        message: "reauth requires exactly one slot id and add forbids one",
+      });
+    }
+  }),
+);
 export type BeginManagedAuthLoginTransactionRequest = z.infer<
   typeof BeginManagedAuthLoginTransactionRequest
 >;
 
-export const ManagedAuthLoginTransaction = z.object({
-  id: z.string().uuid(),
-  kind: z.enum(["add", "reauth"]),
-  expiresAt: z.string().datetime(),
-  returnIntentId: z.string().uuid().nullable(),
-});
+export const ManagedAuthLoginTransaction = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: primitives.uuid,
+    kind: z.enum(["add", "reauth"]),
+    expiresAt: primitives.dateTime,
+    returnIntentId: primitives.nullableUuid,
+  }),
+);
 export type ManagedAuthLoginTransaction = z.infer<typeof ManagedAuthLoginTransaction>;
 
-export const ManagedAuthSocialProvider = z.enum(["google", "github"]);
+export const ManagedAuthSocialProvider = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["google", "github"]),
+);
 export type ManagedAuthSocialProvider = z.infer<typeof ManagedAuthSocialProvider>;
 
 /**
@@ -135,119 +156,145 @@ export type ManagedAuthSocialProvider = z.infer<typeof ManagedAuthSocialProvider
  * them together). Declared here, not imported, so the browser session-set
  * client does not pull the attribution module into a new shared web chunk.
  */
-const SocialStartAttributionValue = z
-  .string()
-  .trim()
-  .min(1)
-  .max(100)
-  .regex(/^[A-Za-z0-9._~+-]+$/);
-const SocialStartAttribution = z
-  .object({
-    utmSource: SocialStartAttributionValue.optional(),
-    utmMedium: SocialStartAttributionValue.optional(),
-    utmCampaign: SocialStartAttributionValue.optional(),
-    utmContent: SocialStartAttributionValue.optional(),
-    ref: SocialStartAttributionValue.optional(),
-  })
-  .strict();
-
-export const StartManagedAuthSocialTransactionRequest = ManagedAuthOperationIdentity.extend({
-  transactionId: z.string().uuid(),
-  provider: ManagedAuthSocialProvider,
-  /**
-   * Optional untrusted first-touch campaign tokens, used only by the
-   * content-free sign-up acquisition counter when this start creates a new
-   * account. Invalid attribution is dropped rather than failing the sign-in.
-   */
-  attribution: SocialStartAttribution.optional().catch(undefined),
-});
+const SocialStartAttributionValue = /* @__PURE__ */ defineSchema(() =>
+  primitives.string
+    .trim()
+    .min(1)
+    .max(100)
+    .regex(/^[A-Za-z0-9._~+-]+$/),
+);
+const SocialStartAttribution = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      utmSource: SocialStartAttributionValue.optional(),
+      utmMedium: SocialStartAttributionValue.optional(),
+      utmCampaign: SocialStartAttributionValue.optional(),
+      utmContent: SocialStartAttributionValue.optional(),
+      ref: SocialStartAttributionValue.optional(),
+    })
+    .strict(),
+);
+
+export const StartManagedAuthSocialTransactionRequest = /* @__PURE__ */ defineSchema(() =>
+  ManagedAuthOperationIdentity.extend({
+    transactionId: primitives.uuid,
+    provider: ManagedAuthSocialProvider,
+    signupChallengeToken: z.string().max(2048).optional(),
+    /**
+     * Optional untrusted first-touch campaign tokens, used only by the
+     * content-free sign-up acquisition counter when this start creates a new
+     * account. Invalid attribution is dropped rather than failing the sign-in.
+     */
+    attribution: SocialStartAttribution.optional().catch(undefined),
+  }),
+);
 export type StartManagedAuthSocialTransactionRequest = z.infer<
   typeof StartManagedAuthSocialTransactionRequest
 >;
 
-export const StartManagedAuthSocialTransactionResponse = z.object({
-  url: z.string().url().max(4_096),
-});
+export const StartManagedAuthSocialTransactionResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    url: z.string().url().max(4_096),
+  }),
+);
 export type StartManagedAuthSocialTransactionResponse = z.infer<
   typeof StartManagedAuthSocialTransactionResponse
 >;
 
 export const CompleteManagedAuthEmailPasswordTransactionRequest =
-  ManagedAuthOperationIdentity.extend({
-    transactionId: z.string().uuid(),
-    email: z.string().email().max(320),
-    password: z.string().min(1).max(1_024),
-  });
+  /* @__PURE__ */ defineSchema(() =>
+    ManagedAuthOperationIdentity.extend({
+      transactionId: primitives.uuid,
+      email: z.string().email().max(320),
+      password: z.string().min(1).max(1_024),
+    }),
+  );
 export type CompleteManagedAuthEmailPasswordTransactionRequest = z.infer<
   typeof CompleteManagedAuthEmailPasswordTransactionRequest
 >;
 
-export const CompleteManagedAuthLoginTransactionResponse = z.object({
-  projection: ManagedAuthSessionSetProjection,
-  returnIntent: ManagedAuthReturnIntent.nullable(),
-});
+export const CompleteManagedAuthLoginTransactionResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    projection: ManagedAuthSessionSetProjection,
+    returnIntent: ManagedAuthReturnIntent.nullable(),
+  }),
+);
 export type CompleteManagedAuthLoginTransactionResponse = z.infer<
   typeof CompleteManagedAuthLoginTransactionResponse
 >;
 
-export const CancelManagedAuthLoginTransactionRequest = ManagedAuthOperationIdentity.extend({
-  transactionId: z.string().uuid(),
-});
+export const CancelManagedAuthLoginTransactionRequest = /* @__PURE__ */ defineSchema(() =>
+  ManagedAuthOperationIdentity.extend({
+    transactionId: primitives.uuid,
+  }),
+);
 export type CancelManagedAuthLoginTransactionRequest = z.infer<
   typeof CancelManagedAuthLoginTransactionRequest
 >;
 
-export const SelectManagedAuthLoginSlotRequest = ManagedAuthOperationIdentity.extend({
-  slotId: z.string().uuid(),
-});
+export const SelectManagedAuthLoginSlotRequest = /* @__PURE__ */ defineSchema(() =>
+  ManagedAuthOperationIdentity.extend({
+    slotId: primitives.uuid,
+  }),
+);
 export type SelectManagedAuthLoginSlotRequest = z.infer<typeof SelectManagedAuthLoginSlotRequest>;
 
-export const LogoutManagedAuthLoginSlotRequest = ManagedAuthOperationIdentity.extend({
-  slotId: z.string().uuid(),
-  replacementSlotId: z.string().uuid().nullable(),
-});
+export const LogoutManagedAuthLoginSlotRequest = /* @__PURE__ */ defineSchema(() =>
+  ManagedAuthOperationIdentity.extend({
+    slotId: primitives.uuid,
+    replacementSlotId: primitives.nullableUuid,
+  }),
+);
 export type LogoutManagedAuthLoginSlotRequest = z.infer<typeof LogoutManagedAuthLoginSlotRequest>;
 
 export const LogoutManagedAuthSessionSetRequest = ManagedAuthOperationIdentity;
 export type LogoutManagedAuthSessionSetRequest = z.infer<typeof LogoutManagedAuthSessionSetRequest>;
 
-export const ManagedAuthLogoutAllReceipt = z.object({
-  generation: z.string().regex(/^[1-9][0-9]*$/),
-  actorEpoch: z.string().regex(/^[1-9][0-9]*$/),
-  state: z.literal("logged_out"),
-});
+export const ManagedAuthLogoutAllReceipt = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    generation: primitives.string.regex(/^[1-9][0-9]*$/),
+    actorEpoch: primitives.string.regex(/^[1-9][0-9]*$/),
+    state: z.literal("logged_out"),
+  }),
+);
 export type ManagedAuthLogoutAllReceipt = z.infer<typeof ManagedAuthLogoutAllReceipt>;
 
-export const ResolveManagedAuthDeepLinkRequest = z.object({
-  path: ManagedAuthReturnIntent,
-});
+export const ResolveManagedAuthDeepLinkRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    path: ManagedAuthReturnIntent,
+  }),
+);
 export type ResolveManagedAuthDeepLinkRequest = z.infer<typeof ResolveManagedAuthDeepLinkRequest>;
 
-export const ManagedAuthDeepLinkResolution = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("current") }),
-  z.object({ kind: z.literal("switch_required"), slot: ManagedAuthLoginSlot }),
-  z.object({ kind: z.literal("unavailable") }),
-]);
+export const ManagedAuthDeepLinkResolution = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("current") }),
+    z.object({ kind: z.literal("switch_required"), slot: ManagedAuthLoginSlot }),
+    z.object({ kind: z.literal("unavailable") }),
+  ]),
+);
 export type ManagedAuthDeepLinkResolution = z.infer<typeof ManagedAuthDeepLinkResolution>;
 
-export const ManagedAuthSessionSetErrorCode = z.enum([
-  "actor_change_required",
-  "actor_mutation_in_flight",
-  "api_contract_changed",
-  "browser_session_set_required",
-  "browser_session_set_unavailable",
-  "generation_conflict",
-  "invalid_browser_session_set_request",
-  "invalid_transaction",
-  "managed_authentication_required",
-  "managed_authentication_unavailable",
-  "operation_outcome_unknown",
-  "operation_reused",
-  "origin_rejected",
-  "login_transaction_rate_limited",
-  "provider_route_blocked",
-  "slot_limit_reached",
-  "slot_already_exists",
-  "slot_unavailable",
-]);
+export const ManagedAuthSessionSetErrorCode = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "actor_change_required",
+    "actor_mutation_in_flight",
+    "api_contract_changed",
+    "browser_session_set_required",
+    "browser_session_set_unavailable",
+    "generation_conflict",
+    "invalid_browser_session_set_request",
+    "invalid_transaction",
+    "managed_authentication_required",
+    "managed_authentication_unavailable",
+    "operation_outcome_unknown",
+    "operation_reused",
+    "origin_rejected",
+    "login_transaction_rate_limited",
+    "provider_route_blocked",
+    "slot_limit_reached",
+    "slot_already_exists",
+    "slot_unavailable",
+  ]),
+);
 export type ManagedAuthSessionSetErrorCode = z.infer<typeof ManagedAuthSessionSetErrorCode>;