@opengeni/contracts 2.2.0-canary.0 → 2.5.0-canary.0

package/src/organization-membership-lifecycle.ts

@@ -4,12 +4,40 @@ import { Permission } from "./permissions";
 export const OrganizationMembershipRole = z.enum(["owner", "admin", "member"]);
 export type OrganizationMembershipRole = z.infer<typeof OrganizationMembershipRole>;
 
+export const WorkspaceMemberRole = z.enum(["viewer", "member", "admin", "custom"]);
+export type WorkspaceMemberRole = z.infer<typeof WorkspaceMemberRole>;
+
+export const AssignableWorkspaceMemberRole = z.enum(["viewer", "member", "admin"]);
+export type AssignableWorkspaceMemberRole = z.infer<typeof AssignableWorkspaceMemberRole>;
+
 export const OrganizationInvitationStatus = z.enum(["pending", "accepted", "revoked", "expired"]);
 export type OrganizationInvitationStatus = z.infer<typeof OrganizationInvitationStatus>;
 
+export const OrganizationUserSetupDeliveryState = z.enum([
+  "pending",
+  "sent",
+  "failed",
+  "outcome_unknown",
+  "revoked",
+]);
+export type OrganizationUserSetupDeliveryState = z.infer<typeof OrganizationUserSetupDeliveryState>;
+
+export const OrganizationUserSetupDelivery = z.object({
+  id: z.string().uuid(),
+  state: OrganizationUserSetupDeliveryState,
+  attemptCount: z.number().int().nonnegative(),
+  revision: z.number().int().positive(),
+  errorClass: z.string().min(1).max(64).nullable(),
+  retryState: z.enum(["available", "reconciliation_required", "unavailable"]),
+  sentAt: z.string().datetime({ offset: true }).nullable(),
+  updatedAt: z.string().datetime({ offset: true }),
+});
+export type OrganizationUserSetupDelivery = z.infer<typeof OrganizationUserSetupDelivery>;
+
 export const OrganizationInvitation = z.object({
   id: z.string().uuid(),
   organizationId: z.string().uuid(),
+  organizationName: z.string().trim().min(1).max(120).nullable().default(null),
   targetEmail: z.string().email(),
   targetName: z.string().trim().min(1).max(120).nullable().default(null),
   initialWorkspaceIds: z.array(z.string().uuid()).max(100).default([]),
@@ -20,6 +48,7 @@ export const OrganizationInvitation = z.object({
   acceptedMembershipId: z.string().uuid().nullable(),
   createdAt: z.string().datetime({ offset: true }),
   updatedAt: z.string().datetime({ offset: true }),
+  delivery: OrganizationUserSetupDelivery.nullable().default(null),
 });
 export type OrganizationInvitation = z.infer<typeof OrganizationInvitation>;
 
@@ -40,6 +69,34 @@ export const OrganizationMember = z.object({
 });
 export type OrganizationMember = z.infer<typeof OrganizationMember>;
 
+export const OrganizationAdministrationMemberWorkspaceAccess = z.object({
+  workspaceId: z.string().uuid(),
+  workspaceName: z.string().min(1).max(255),
+  membershipId: z.string().uuid(),
+  role: WorkspaceMemberRole,
+  updatedAt: z.string().datetime({ offset: true }),
+});
+export type OrganizationAdministrationMemberWorkspaceAccess = z.infer<
+  typeof OrganizationAdministrationMemberWorkspaceAccess
+>;
+
+/** Safe admin projection. Personal-workspace and personal-resource metadata are absent. */
+export const OrganizationAdministrationMember = z.object({
+  id: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  subjectId: z.string().min(1).max(1024),
+  name: z.string().min(1).max(1024).nullable(),
+  email: z.string().email().max(320).nullable(),
+  role: OrganizationMembershipRole,
+  status: z.enum(["provisioning", "active", "suspended", "revoked"]),
+  authorizationRevision: z.number().int().positive(),
+  sharedWorkspaceAccess: z.array(OrganizationAdministrationMemberWorkspaceAccess).max(500),
+  revokedAt: z.string().datetime({ offset: true }).nullable(),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+});
+export type OrganizationAdministrationMember = z.infer<typeof OrganizationAdministrationMember>;
+
 export const OrganizationSummary = z.object({
   id: z.string().uuid(),
   name: z.string().trim().min(1).max(120),
@@ -71,12 +128,17 @@ export type UpdateOrganizationPrivateSessionSettingsRequest = z.infer<
 
 export const OrganizationWorkspaceAccessMember = z.object({
   membershipId: z.string().uuid(),
+  organizationMembershipId: z.string().uuid().nullable(),
   subjectId: z.string().min(1).max(1024),
+  name: z.string().min(1).max(1024).nullable(),
+  email: z.string().email().max(320).nullable(),
   subjectLabel: z.string().min(1).max(1024).nullable(),
   principalKind: z.enum(["human", "service"]),
-  role: z.string().min(1).max(64),
+  organizationRole: OrganizationMembershipRole.nullable(),
+  role: WorkspaceMemberRole,
   permissions: z.array(z.string().min(1).max(128)),
   createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
 });
 export type OrganizationWorkspaceAccessMember = z.infer<typeof OrganizationWorkspaceAccessMember>;
 
@@ -90,32 +152,80 @@ export const OrganizationWorkspaceAccess = z.object({
 });
 export type OrganizationWorkspaceAccess = z.infer<typeof OrganizationWorkspaceAccess>;
 
+export const OrganizationWorkspaceRoleDefinition = z.object({
+  role: AssignableWorkspaceMemberRole,
+  label: z.string().min(1).max(64),
+  description: z.string().min(1).max(512),
+  permissions: z.array(Permission).min(1),
+});
+export type OrganizationWorkspaceRoleDefinition = z.infer<
+  typeof OrganizationWorkspaceRoleDefinition
+>;
+
 export const OrganizationAdministrationOverview = z.object({
   organization: OrganizationSummary,
+  roles: z.array(OrganizationWorkspaceRoleDefinition).length(3),
   workspaces: z.array(OrganizationWorkspaceAccess).max(500),
 });
 export type OrganizationAdministrationOverview = z.infer<typeof OrganizationAdministrationOverview>;
 
-// Organization-control-plane assignment of an existing active organization
-// member to a shared workspace. The target is a membership rather than an
-// email address: joining the organization and receiving workspace access stay
-// two explicit lifecycle steps, and this surface cannot become a user lookup.
-export const AddOrganizationWorkspaceMemberRequest = z.object({
-  organizationMembershipId: z.string().uuid(),
-  role: z.string().trim().min(1).max(64).optional(),
-  permissions: z.array(Permission).max(128),
-});
-export type AddOrganizationWorkspaceMemberRequest = z.infer<
-  typeof AddOrganizationWorkspaceMemberRequest
+export const CreateOrganizationWorkspaceRequest = z
+  .object({
+    name: z.string().trim().min(1).max(120),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type CreateOrganizationWorkspaceRequest = z.infer<typeof CreateOrganizationWorkspaceRequest>;
+
+export const UpdateOrganizationWorkspaceRequest = z
+  .object({
+    name: z.string().trim().min(1).max(120),
+    expectedUpdatedAt: z.string().datetime({ offset: true }),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type UpdateOrganizationWorkspaceRequest = z.infer<typeof UpdateOrganizationWorkspaceRequest>;
+
+export const PutOrganizationWorkspaceMemberRequest = z.discriminatedUnion("role", [
+  z
+    .object({
+      role: AssignableWorkspaceMemberRole,
+      expectedUpdatedAt: z.string().datetime({ offset: true }).nullable(),
+      operationId: z.string().uuid(),
+    })
+    .strict(),
+  z
+    .object({
+      role: z.literal("custom"),
+      permissions: z.array(Permission).max(128),
+      expectedUpdatedAt: z.string().datetime({ offset: true }).nullable(),
+      operationId: z.string().uuid(),
+    })
+    .strict(),
+]);
+export type PutOrganizationWorkspaceMemberRequest = z.infer<
+  typeof PutOrganizationWorkspaceMemberRequest
 >;
 
-export const CreateOrganizationWorkspaceRequest = z.object({
-  name: z.string().trim().min(1).max(120),
-  slug: z.string().trim().min(1).max(120).nullable().optional(),
-  agentInstructions: z.string().nullable().optional(),
-  operationId: z.string().uuid(),
-});
-export type CreateOrganizationWorkspaceRequest = z.infer<typeof CreateOrganizationWorkspaceRequest>;
+export const RevokeOrganizationWorkspaceMemberRequest = z
+  .object({
+    expectedUpdatedAt: z.string().datetime({ offset: true }),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type RevokeOrganizationWorkspaceMemberRequest = z.infer<
+  typeof RevokeOrganizationWorkspaceMemberRequest
+>;
+
+export const RevokeOrganizationWorkspaceMemberResponse = z
+  .object({
+    removed: z.boolean(),
+    replay: z.boolean(),
+  })
+  .strict();
+export type RevokeOrganizationWorkspaceMemberResponse = z.infer<
+  typeof RevokeOrganizationWorkspaceMemberResponse
+>;
 
 export const CreateOrganizationRequest = z.object({
   name: z.string().trim().min(1).max(120),
@@ -238,6 +348,96 @@ export type CreateOrganizationInvitationRequest = z.infer<
   typeof CreateOrganizationInvitationRequest
 >;
 
+/**
+ * Public, signed-out completion contract for an invitation-bound account setup.
+ * The bearer is delivered out of band to the invited email address. It is
+ * never persisted in plaintext; `operationId` makes an outcome-unknown retry
+ * converge on the first committed result.
+ */
+export const CompleteOrganizationUserSetupRequest = z.object({
+  token: z.string().min(32).max(2048),
+  name: z.string().trim().min(1).max(120),
+  password: z.string().min(8).max(128),
+  operationId: z.string().uuid(),
+});
+export type CompleteOrganizationUserSetupRequest = z.infer<
+  typeof CompleteOrganizationUserSetupRequest
+>;
+
+export const CompleteOrganizationUserSetupResponse = z.object({
+  status: z.literal("complete"),
+});
+export type CompleteOrganizationUserSetupResponse = z.infer<
+  typeof CompleteOrganizationUserSetupResponse
+>;
+
+export const PreviewOrganizationUserSetupRequest = z
+  .object({ token: z.string().min(32).max(2048) })
+  .strict();
+export type PreviewOrganizationUserSetupRequest = z.infer<
+  typeof PreviewOrganizationUserSetupRequest
+>;
+
+export const OrganizationUserSetupPreviewWorkspace = z.object({
+  workspaceId: z.string().uuid(),
+  workspaceName: z.string().min(1).max(255),
+  role: AssignableWorkspaceMemberRole,
+});
+export type OrganizationUserSetupPreviewWorkspace = z.infer<
+  typeof OrganizationUserSetupPreviewWorkspace
+>;
+
+const OrganizationUserSetupPreviewUnavailable = z.object({
+  state: z.enum(["unavailable", "expired", "revoked", "completed"]),
+});
+const OrganizationUserSetupPreviewPending = z.object({
+  state: z.literal("pending"),
+  organizationId: z.string().uuid(),
+  organizationName: z.string().trim().min(1).max(120),
+  targetEmail: z.string().email().max(320),
+  targetName: z.string().trim().min(1).max(120).nullable(),
+  organizationRole: OrganizationMembershipRole,
+  sharedWorkspaceAccess: z.array(OrganizationUserSetupPreviewWorkspace).max(100),
+  expiresAt: z.string().datetime({ offset: true }),
+});
+export const OrganizationUserSetupPreview = z.discriminatedUnion("state", [
+  OrganizationUserSetupPreviewUnavailable,
+  OrganizationUserSetupPreviewPending,
+]);
+export type OrganizationUserSetupPreview = z.infer<typeof OrganizationUserSetupPreview>;
+
+export const RetryOrganizationUserSetupDeliveryRequest = z
+  .object({ operationId: z.string().uuid() })
+  .strict();
+export type RetryOrganizationUserSetupDeliveryRequest = z.infer<
+  typeof RetryOrganizationUserSetupDeliveryRequest
+>;
+
+/** Authenticated organization-name-only setup after ordinary account creation. */
+export const CompleteSelfServiceOrganizationSetupRequest = z.object({
+  organizationName: z.string().trim().min(1).max(120),
+  operationId: z.string().uuid(),
+});
+export type CompleteSelfServiceOrganizationSetupRequest = z.infer<
+  typeof CompleteSelfServiceOrganizationSetupRequest
+>;
+
+export const CompleteSelfServiceOrganizationSetupResponse = z.object({
+  status: z.literal("complete"),
+  organizationId: z.string().uuid(),
+  personalWorkspaceId: z.string().uuid(),
+});
+export type CompleteSelfServiceOrganizationSetupResponse = z.infer<
+  typeof CompleteSelfServiceOrganizationSetupResponse
+>;
+
+export const SelfServiceOrganizationOnboardingStatus = z.object({
+  state: z.enum(["required", "invitation_pending", "unavailable", "complete"]),
+});
+export type SelfServiceOrganizationOnboardingStatus = z.infer<
+  typeof SelfServiceOrganizationOnboardingStatus
+>;
+
 export const AcceptOrganizationInvitationRequest = z.object({
   expectedRevision: z.number().int().positive(),
   operationId: z.string().uuid(),
@@ -325,6 +525,9 @@ export type AcceptOrganizationInvitationResponse = z.infer<
 export const ListOrganizationMembersResponse = z.object({
   members: z.array(OrganizationMember),
 });
+export const ListOrganizationAdministrationMembersResponse = z.object({
+  members: z.array(OrganizationAdministrationMember).max(1000),
+});
 export const ListSelfOrganizationMembershipsResponse = z.object({
   memberships: z.array(OrganizationMember),
 });

package/src/remember.ts

@@ -21,7 +21,7 @@ import { WorkspaceInstructionPolicyTarget } from "./workspace-instruction-polici
 /**
  * Explicit user-directed durable write ("remember X for this workspace").
  *
- * The lane is the Company Brain area the content belongs to:
+ * The lane is the Agent Knowledge area the content belongs to:
  * - `preference`: a Ways-of-working preference (how agents should act);
  * - `instruction_policy`: a mandatory workspace rule ("always"/"never");
  * - `knowledge`: a company/product/people fact.
@@ -84,7 +84,7 @@ export const RememberRequest = z.discriminatedUnion("lane", [
       lane: z.literal("instruction_policy"),
       // A mandatory rule is composed verbatim into the prompt of every session
       // it applies to, for as long as it stays active, so this is the tightest
-      // agent budget in the Company Brain.
+      // agent budget in Agent Knowledge.
       content: z
         .string()
         .trim()
@@ -145,11 +145,13 @@ export const RememberActivationSummary = z.discriminatedUnion("destination", [
     destination: z.literal("knowledge"),
     receiptId: z.string().uuid(),
     claimId: z.string().uuid(),
+    /** The retrievable Memory record materialized from the approved claim. */
+    memoryId: z.string().uuid(),
     approvalReviewId: z.string().uuid(),
     effectiveAt: z.string().datetime().nullable(),
     authorityKind: z.literal("human_confirmed"),
-    /** Knowledge approvals are undone through the Knowledge review lifecycle (`knowledge_correct` or a human revocation). */
-    undo: z.literal("knowledge_review"),
+    /** Correct or archive the materialized record through the Memory lifecycle. */
+    undo: z.literal("memory_management"),
   }),
 ]);
 export type RememberActivationSummary = z.infer<typeof RememberActivationSummary>;

package/src/session-titles.ts

@@ -0,0 +1,324 @@
+/** Human-authored session titles keep the existing public API ceiling. */
+export const SESSION_TITLE_MAX_CHARACTERS = 200;
+
+/**
+ * Automatic titles are intentionally much shorter than the manual rename
+ * ceiling. This is measured in grapheme clusters so emoji and combining text
+ * are never split into malformed display strings.
+ */
+export const AUTOMATIC_SESSION_TITLE_MAX_GRAPHEMES = 80;
+
+/**
+ * Safe durable title used until semantic generation succeeds. It contains no
+ * user prompt bytes, so provider failure/offline operation cannot leak a
+ * credential or leave a raw prompt prefix in navigation surfaces.
+ */
+export const AUTOMATIC_SESSION_TITLE_FALLBACK = "New conversation";
+
+let titleSegmenter: Intl.Segmenter | null | undefined;
+
+const KNOWN_SENSITIVE_VALUE_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/iu,
+  /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/iu,
+  /\b(?:sk-(?:proj-)?|gh[oprsu]_|github_pat_|glpat-|xox[baprs]-)[A-Za-z0-9_-]{8,}/iu,
+  /\bAKIA[0-9A-Z]{16}\b/u,
+  /\bAIza[0-9A-Za-z_-]{20,}\b/u,
+  /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/u,
+  /[?&](?:access_token|api_key|apikey|password|secret|token)=[^\s&#]+/iu,
+] as const;
+
+const URI_SCHEME_CANDIDATE_PATTERN = /\b[a-z][a-z0-9+.-]*:\S+/giu;
+const WINDOWS_DRIVE_PATH_PATTERN = /^[a-z]:[\\/](?![\\/])[^:]*$/iu;
+
+const SCHEMELESS_HOST_CANDIDATE_PATTERN =
+  /\b(?:www\.)?(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?(?::\d{1,5})?(?:[/?#][^\s]*)?/giu;
+
+const SCHEMELESS_LOCAL_NETWORK_PATTERNS = [
+  /\blocalhost(?:(?::\d{1,5})(?:[/?#][^\s]*)?|[/?#][^\s]*)/iu,
+  /\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)(?:(?::\d{1,5})(?:[/?#][^\s]*)?|[/?#][^\s]*)/u,
+  /\[(?=[0-9a-f:.]*:[0-9a-f:.]*\])[0-9a-f:.]+\](?:(?::\d{1,5})(?:[/?#][^\s]*)?|[/?#][^\s]*)/iu,
+] as const;
+
+const FILE_LIKE_HOST_SUFFIXES = new Set([
+  "css",
+  "html",
+  "js",
+  "json",
+  "jsx",
+  "lock",
+  "md",
+  "sql",
+  "toml",
+  "ts",
+  "tsx",
+  "xml",
+  "yaml",
+  "yml",
+]);
+
+// These authorities are established framework/namespace notation whose exact
+// casing is meaningful. Keep this exception deliberately narrow: generic
+// PascalCase or uppercase authorities remain host-like because an uppercase
+// real domain (for example MICROSOFT.COM/Admin) must not bypass the URL gate.
+const DOTTED_TECHNOLOGY_PATH_AUTHORITIES = new Set([
+  "ASP.NET",
+  "AWS.SDK",
+  "Microsoft.Extensions",
+  "System.IO",
+]);
+
+const SECRET_ASSIGNMENT_CANDIDATE_PATTERN =
+  /(?:^|[^A-Za-z0-9])(?:(['"])([A-Za-z][A-Za-z0-9_. -]*)\1|([A-Za-z][A-Za-z0-9_.-]*))\s*[=:]\s*[^\s,;]+/gu;
+
+const SECRET_LABEL_ASSIGNMENT_PATTERN =
+  /\b(?:api[ _-]?key|access[ _-]?token|auth[ _-]?token|credential|credentials|password|passwd|private[ _-]?key|secret|token)\b\s*[=:]\s*[^\s,;]+/iu;
+
+const SENSITIVE_ASSIGNMENT_KEY_SUFFIXES = new Set([
+  "credential",
+  "credentials",
+  "password",
+  "passwd",
+  "secret",
+  "token",
+]);
+
+const COMPACT_SENSITIVE_ASSIGNMENT_KEY_SUFFIXES = [
+  "apikey",
+  "accesskey",
+  "accesskeyid",
+  "accesstoken",
+  "authtoken",
+  "credential",
+  "credentials",
+  "password",
+  "passwd",
+  "privatekey",
+  "secret",
+  "secretkey",
+  "token",
+] as const;
+
+const SENSITIVE_ASSIGNMENT_KEY_WORD_SUFFIXES = [
+  ["api", "key"],
+  ["access", "key"],
+  ["access", "key", "id"],
+  ["auth", "key"],
+  ["private", "key"],
+  ["secret", "key"],
+] as const;
+
+function hasWordSuffix(words: readonly string[], suffix: readonly string[]): boolean {
+  if (words.length < suffix.length) return false;
+  const offset = words.length - suffix.length;
+  return suffix.every((word, index) => words[offset + index] === word);
+}
+
+function containsSensitiveAssignment(value: string): boolean {
+  for (const match of value.matchAll(SECRET_ASSIGNMENT_CANDIDATE_PATTERN)) {
+    const key = match[2] ?? match[3];
+    if (!key) continue;
+    const words = key
+      .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+      .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter(Boolean);
+    const last = words.at(-1);
+    if (last && SENSITIVE_ASSIGNMENT_KEY_SUFFIXES.has(last)) return true;
+    if (last && COMPACT_SENSITIVE_ASSIGNMENT_KEY_SUFFIXES.some((suffix) => last.endsWith(suffix))) {
+      return true;
+    }
+    if (SENSITIVE_ASSIGNMENT_KEY_WORD_SUFFIXES.some((suffix) => hasWordSuffix(words, suffix))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function containsUriScheme(value: string): boolean {
+  for (const match of value.matchAll(URI_SCHEME_CANDIDATE_PATTERN)) {
+    // A Windows drive path is the one scheme-shaped token accepted here. Keep
+    // the exception exact: one separator after the drive letter and no later
+    // colon, so x://host and a nested scheme remain rejected.
+    if (!WINDOWS_DRIVE_PATH_PATTERN.test(match[0])) return true;
+  }
+  return false;
+}
+
+function isDottedTechnologyPath(candidate: string): boolean {
+  if (/[?:#]/u.test(candidate)) return false;
+  const [authority, ...pathSegments] = candidate.split("/");
+  if (!authority || pathSegments.length === 0 || pathSegments.some((segment) => !segment)) {
+    return false;
+  }
+  if (
+    !DOTTED_TECHNOLOGY_PATH_AUTHORITIES.has(authority) ||
+    pathSegments.some((segment) => !/^[A-Z][A-Za-z0-9_-]*$/u.test(segment))
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function containsSchemelessUrl(value: string): boolean {
+  if (SCHEMELESS_LOCAL_NETWORK_PATTERNS.some((pattern) => pattern.test(value))) return true;
+
+  for (const match of value.matchAll(SCHEMELESS_HOST_CANDIDATE_PATTERN)) {
+    const candidate = match[0];
+    if (candidate.toLowerCase().startsWith("www.")) return true;
+    if (!/[/?#]/u.test(candidate)) continue;
+
+    const authority = candidate.split(/[/?#]/u, 1)[0] ?? "";
+    const hostname = authority.replace(/:\d{1,5}$/u, "");
+    const suffix = hostname.split(".").at(-1)?.toLowerCase();
+    if (suffix && FILE_LIKE_HOST_SUFFIXES.has(suffix)) continue;
+    if (isDottedTechnologyPath(candidate)) continue;
+    return true;
+  }
+  return false;
+}
+
+const OPAQUE_IDENTIFIER_PATTERN =
+  /\b(?=[A-Za-z0-9_-]{32,}\b)(?=[A-Za-z0-9_-]*[A-Za-z])(?=[A-Za-z0-9_-]*\d)[A-Za-z0-9_-]+\b/u;
+
+const DEFAULT_IGNORABLE_CODE_POINTS = /\p{Default_Ignorable_Code_Point}+/gu;
+const ESCAPED_QUOTE_DELIMITERS = /\\+(?=["'])/gu;
+
+const TITLE_LABEL_PATTERN =
+  /^(?:(?:suggested|generated|concise)\s+)?(?:(?:session|chat|conversation|task)\s+)?title\s*[:\-–—]\s*/iu;
+
+const LEADING_BOILERPLATE_PATTERNS = [
+  /^(?:hi|hello|hey)(?:\s+there)?\s*[,!:.\-–—]*\s*/iu,
+  /^(?:i\s+(?:would\s+like|want|need)\s+you\s+to|i['’]d\s+like\s+you\s+to)\s+/iu,
+  /^(?:please\s+)?(?:can|could|would|will)\s+you\s+/iu,
+  /^(?:your|the)\s+(?:task|job)\s+is\s+to\s+/iu,
+  /^(?:please\s+)?help\s+me\s+(?:to\s+)?/iu,
+  /^please(?:\s*[,!:.\-–—]+\s*|\s+|$)/iu,
+] as const;
+
+function automaticTitleDetectionValue(value: string): string {
+  // Detection uses a compatibility-normalized shadow value so fullwidth
+  // punctuation/letters, invisible token splits, and serialized quote
+  // delimiters cannot evade the policy.
+  // The accepted title itself stays byte-for-byte in the user's language and
+  // emoji form; this shadow is never returned or persisted.
+  return value
+    .normalize("NFKC")
+    .replace(DEFAULT_IGNORABLE_CODE_POINTS, "")
+    .replace(ESCAPED_QUOTE_DELIMITERS, "");
+}
+
+function hasVisibleAutomaticTitleContent(value: string): boolean {
+  return automaticTitleDetectionValue(value).trim().length > 0;
+}
+
+function containsSensitiveAutomaticTitleValue(value: string): boolean {
+  const detectionValue = automaticTitleDetectionValue(value);
+
+  if (KNOWN_SENSITIVE_VALUE_PATTERNS.some((pattern) => pattern.test(detectionValue))) return true;
+  if (containsUriScheme(detectionValue)) return true;
+  if (containsSchemelessUrl(detectionValue)) return true;
+  if (SECRET_LABEL_ASSIGNMENT_PATTERN.test(detectionValue)) return true;
+  if (containsSensitiveAssignment(detectionValue)) return true;
+  if (OPAQUE_IDENTIFIER_PATTERN.test(detectionValue)) return true;
+  return false;
+}
+
+function stripAutomaticTitleBoilerplate(value: string): string {
+  let title = value;
+  for (let pass = 0; pass < 4; pass += 1) {
+    const before = title;
+    title = title
+      .replace(/^(?:```[^\n]*|[\s#>*_`"'“”‘’\-–—]+)+/u, "")
+      .replace(TITLE_LABEL_PATTERN, "");
+    for (const pattern of LEADING_BOILERPLATE_PATTERNS) {
+      title = title.replace(pattern, "");
+    }
+    title = title.trim();
+    if (title === before) break;
+  }
+  return title;
+}
+
+function automaticTitleGraphemes(value: string): string[] {
+  if (titleSegmenter === undefined) {
+    titleSegmenter =
+      typeof Intl.Segmenter === "function"
+        ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+        : null;
+  }
+  if (titleSegmenter) {
+    return Array.from(titleSegmenter.segment(value), (part) => part.segment);
+  }
+
+  // Older embedded runtimes may not ship Intl.Segmenter. Preserve surrogate
+  // pairs plus common combining/emoji sequences instead of failing module load
+  // or slicing UTF-16 code units.
+  const graphemes: string[] = [];
+  for (const point of value) {
+    const prior = graphemes.at(-1);
+    if (
+      prior &&
+      (/^[\p{Mark}\u{FE0E}\u{FE0F}\p{Emoji_Modifier}]$/u.test(point) ||
+        point === "\u200d" ||
+        prior.endsWith("\u200d"))
+    ) {
+      graphemes[graphemes.length - 1] = `${prior}${point}`;
+    } else {
+      graphemes.push(point);
+    }
+  }
+  return graphemes;
+}
+
+function boundAutomaticTitle(value: string): string {
+  const words = value.split(/\s+/u);
+  const wordBounded = words.length > 10 ? words.slice(0, 10).join(" ") : value;
+  const graphemes = automaticTitleGraphemes(wordBounded);
+  if (graphemes.length <= AUTOMATIC_SESSION_TITLE_MAX_GRAPHEMES) return wordBounded;
+
+  const prefix = graphemes.slice(0, AUTOMATIC_SESSION_TITLE_MAX_GRAPHEMES).join("");
+  const lastWhitespace = prefix.search(/\s+\S*$/u);
+  return (lastWhitespace >= 16 ? prefix.slice(0, lastWhitespace) : prefix).trimEnd();
+}
+
+/**
+ * Normalize a model/system-authored title before it reaches durable session
+ * metadata. Human renames intentionally do not use this path.
+ *
+ * Returns null when the candidate is empty, only boilerplate, or appears to
+ * contain a credential/opaque prompt value. Callers should retain the current
+ * title (normally {@link AUTOMATIC_SESSION_TITLE_FALLBACK}) in that case.
+ */
+export function normalizeAutomaticSessionTitle(value: string): string | null {
+  const firstLine = value
+    .replace(/[\u0000-\u001f\u007f-\u009f]+/gu, "\n")
+    .split(/\n+/u)
+    .map((line) => line.trim())
+    .find(Boolean);
+  if (
+    !firstLine ||
+    !hasVisibleAutomaticTitleContent(firstLine) ||
+    containsSensitiveAutomaticTitleValue(firstLine)
+  ) {
+    return null;
+  }
+
+  let title = stripAutomaticTitleBoilerplate(firstLine)
+    .replace(/\s+/gu, " ")
+    .replace(/[\s.!?,;:\-–—]+$/u, "")
+    .trim();
+  if (
+    !title ||
+    !hasVisibleAutomaticTitleContent(title) ||
+    containsSensitiveAutomaticTitleValue(title)
+  ) {
+    return null;
+  }
+
+  title = boundAutomaticTitle(title)
+    .replace(/[\s.!?,;:\-–—]+$/u, "")
+    .trim();
+  if (!title || !hasVisibleAutomaticTitleContent(title)) return null;
+  return title;
+}