@opengeni/contracts 1.0.1 → 2.2.0-canary.0

package/src/company-brain-governed-writes.ts

@@ -0,0 +1,356 @@
+import { z } from "zod";
+import {
+  AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+  AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
+  AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
+  AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
+} from "./agent-authored-durable-text";
+import {
+  PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS,
+  PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS,
+  PREFERENCE_REGISTRY_TITLE_MAX_CHARS,
+  PreferenceRegistryConflictStrategy,
+  PreferenceRegistryStableKey,
+} from "./preference-registry";
+import { GovernedLearningActivationDestination } from "./governed-learning-activation";
+import {
+  GovernedLearningDecisionOutcome,
+  GovernedLearningDecisionReason,
+} from "./governed-learning-evaluator";
+import { WorkspaceInstructionPolicyTarget } from "./workspace-instruction-policies";
+import { WorkspaceLearningPolicyEffectiveMode } from "./workspace-learning-policy";
+
+const boundedReason = z.string().trim().min(1).max(4_096);
+const operationId = z.string().uuid();
+const exactEvidence = {
+  claimId: z.string().uuid(),
+  evidenceId: z.string().uuid(),
+};
+
+/** Exact accepted-attempt authority. It is validated again inside the write transaction. */
+export const CompanyBrainGovernedWriteAttempt = z
+  .object({
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    attemptId: z.string().uuid(),
+    executionGeneration: z.number().int().positive(),
+  })
+  .strict();
+export type CompanyBrainGovernedWriteAttempt = z.infer<typeof CompanyBrainGovernedWriteAttempt>;
+
+export const ProposeWorkspaceKnowledgeClaimRequest = z
+  .object({
+    kind: z.literal("propose_knowledge"),
+    operationId,
+    ...exactEvidence,
+    reason: boundedReason,
+  })
+  .strict();
+export type ProposeWorkspaceKnowledgeClaimRequest = z.infer<
+  typeof ProposeWorkspaceKnowledgeClaimRequest
+>;
+
+export const CorrectWorkspaceKnowledgeClaimRequest = z
+  .object({
+    kind: z.literal("correct_knowledge"),
+    operationId,
+    ...exactEvidence,
+    replacesClaimId: z.string().uuid(),
+    reason: boundedReason,
+  })
+  .strict();
+export type CorrectWorkspaceKnowledgeClaimRequest = z.infer<
+  typeof CorrectWorkspaceKnowledgeClaimRequest
+>;
+
+/**
+ * Promote one still-active task-tree note into a normalized, workspace-local
+ * Knowledge claim proposal. The note text is the exact fact value and source
+ * evidence; callers may describe the subject and predicate but cannot widen
+ * authority or supply replacement source bytes.
+ */
+export const PromoteTaskNoteKnowledgeRequest = z
+  .object({
+    kind: z.literal("promote_task_note_knowledge"),
+    operationId,
+    noteId: z.string().uuid(),
+    expectedNoteVersion: z.literal(1),
+    entityType: z
+      .string()
+      .trim()
+      .min(1)
+      .max(96)
+      .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+    normalizedKey: z.string().trim().min(1).max(512),
+    displayName: z.string().trim().min(1).max(512),
+    predicateKey: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+    confidenceBps: z.number().int().min(0).max(10_000),
+    reason: boundedReason,
+  })
+  .strict();
+export type PromoteTaskNoteKnowledgeRequest = z.infer<typeof PromoteTaskNoteKnowledgeRequest>;
+
+/**
+ * Promote the exact immutable Task-note bytes into an inactive mandatory-rule
+ * draft. The caller selects only the governed target and active-head baseline;
+ * it cannot replace the source content or activate the draft.
+ */
+export const PromoteTaskNoteInstructionPolicyRequest = z
+  .strictObject({
+    kind: z.literal("promote_task_note_instruction_policy"),
+    operationId,
+    noteId: z.string().uuid(),
+    expectedNoteVersion: z.literal(1),
+    entityType: z
+      .string()
+      .trim()
+      .min(1)
+      .max(96)
+      .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+    normalizedKey: z.string().trim().min(1).max(512),
+    displayName: z.string().trim().min(1).max(512),
+    predicateKey: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+    confidenceBps: z.number().int().min(0).max(10_000),
+    target: WorkspaceInstructionPolicyTarget,
+    expectedCurrentRevisionId: z.string().uuid().nullable(),
+    expectedActivationVersion: z.number().int().nonnegative(),
+    reason: boundedReason,
+  })
+  .superRefine((value, context) => {
+    const target = WorkspaceInstructionPolicyTarget.safeParse(value.target);
+    if (!target.success) {
+      for (const issue of target.error.issues) {
+        context.addIssue({ ...issue, path: ["target", ...issue.path] });
+      }
+    }
+  });
+export type PromoteTaskNoteInstructionPolicyRequest = z.infer<
+  typeof PromoteTaskNoteInstructionPolicyRequest
+>;
+
+/**
+ * Promote the exact immutable Task-note bytes into an inactive workspace
+ * preference proposal. Descriptor metadata is caller-supplied and bounded,
+ * while the full proposal content always comes from the admitted note.
+ */
+export const PromoteTaskNotePreferenceRequest = z.strictObject({
+  kind: z.literal("promote_task_note_preference"),
+  operationId,
+  noteId: z.string().uuid(),
+  expectedNoteVersion: z.literal(1),
+  entityType: z
+    .string()
+    .trim()
+    .min(1)
+    .max(96)
+    .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+  normalizedKey: z.string().trim().min(1).max(512),
+  displayName: z.string().trim().min(1).max(512),
+  predicateKey: z
+    .string()
+    .trim()
+    .min(1)
+    .max(128)
+    .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+  confidenceBps: z.number().int().min(0).max(10_000),
+  stableKey: PreferenceRegistryStableKey.max(PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS),
+  title: z.string().trim().min(1).max(PREFERENCE_REGISTRY_TITLE_MAX_CHARS),
+  description: z.string().trim().min(1).max(PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS),
+  precedenceRank: z.number().int().min(-1_000).max(1_000).default(0),
+  conflictStrategy: PreferenceRegistryConflictStrategy.default("override"),
+  conflictsWith: z.array(PreferenceRegistryStableKey).max(32).default([]),
+  expiresAt: z.string().datetime({ offset: true }).nullable().default(null),
+  reason: boundedReason,
+});
+export type PromoteTaskNotePreferenceRequest = z.infer<typeof PromoteTaskNotePreferenceRequest>;
+
+export const ProposeWorkspaceInstructionPolicyRequest = z
+  .strictObject({
+    kind: z.literal("propose_instruction_policy"),
+    operationId,
+    ...exactEvidence,
+    target: WorkspaceInstructionPolicyTarget,
+    // Agent-authored: this draft becomes prompt text in every session once a
+    // human activates it, so it is bounded far below the human editor limit.
+    content: z
+      .string()
+      .min(1)
+      .max(
+        AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+        AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
+      )
+      .refine((value) => value.trim().length > 0, "instruction proposal must not be blank"),
+    expectedCurrentRevisionId: z.string().uuid().nullable(),
+    expectedActivationVersion: z.number().int().nonnegative(),
+    reason: boundedReason,
+  })
+  .superRefine((value, context) => {
+    const target = WorkspaceInstructionPolicyTarget.safeParse(value.target);
+    if (!target.success) {
+      for (const issue of target.error.issues) {
+        context.addIssue({ ...issue, path: ["target", ...issue.path] });
+      }
+    }
+  });
+export type ProposeWorkspaceInstructionPolicyRequest = z.infer<
+  typeof ProposeWorkspaceInstructionPolicyRequest
+>;
+
+export const ProposeWorkspacePreferenceRequest = z.strictObject({
+  kind: z.literal("propose_preference"),
+  operationId,
+  ...exactEvidence,
+  stableKey: PreferenceRegistryStableKey.max(PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS),
+  title: z.string().trim().min(1).max(PREFERENCE_REGISTRY_TITLE_MAX_CHARS),
+  description: z.string().trim().min(1).max(PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS),
+  // Agent-authored: the descriptor pair is prompt-composed in every session and
+  // the content is retrieved on demand, so it stays short.
+  content: z
+    .string()
+    .min(1)
+    .max(
+      AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
+      AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
+    )
+    .refine((value) => value.trim().length > 0, "preference proposal must not be blank"),
+  precedenceRank: z.number().int().min(-1_000).max(1_000).default(0),
+  conflictStrategy: PreferenceRegistryConflictStrategy.default("override"),
+  conflictsWith: z.array(PreferenceRegistryStableKey).max(32).default([]),
+  expiresAt: z.string().datetime({ offset: true }).nullable().default(null),
+  reason: boundedReason,
+});
+export type ProposeWorkspacePreferenceRequest = z.infer<typeof ProposeWorkspacePreferenceRequest>;
+
+/**
+ * Destination selection is explicit and structured. There is deliberately no
+ * generic "remember" operation, classifier, personal scope, or active authority.
+ */
+export const CompanyBrainGovernedWriteRequest = z.discriminatedUnion("kind", [
+  ProposeWorkspaceKnowledgeClaimRequest,
+  CorrectWorkspaceKnowledgeClaimRequest,
+  PromoteTaskNoteKnowledgeRequest,
+  PromoteTaskNoteInstructionPolicyRequest,
+  PromoteTaskNotePreferenceRequest,
+  ProposeWorkspaceInstructionPolicyRequest,
+  ProposeWorkspacePreferenceRequest,
+]);
+export type CompanyBrainGovernedWriteRequest = z.infer<typeof CompanyBrainGovernedWriteRequest>;
+
+export const CompanyBrainGovernedWriteDestination = z.enum([
+  "knowledge",
+  "instruction_policy",
+  "preference",
+]);
+export type CompanyBrainGovernedWriteDestination = z.infer<
+  typeof CompanyBrainGovernedWriteDestination
+>;
+
+export const CompanyBrainGovernedWriteReceipt = z.object({
+  operationId,
+  inputHash: z.string().regex(/^[0-9a-f]{64}$/),
+  workspaceId: z.string().uuid(),
+  destination: CompanyBrainGovernedWriteDestination,
+  outcome: z.literal("proposed"),
+  claimId: z.string().uuid(),
+  evidenceId: z.string().uuid(),
+  relationId: z.string().uuid().nullable(),
+  reviewId: z.string().uuid().nullable(),
+  knowledgeChangeProposalId: z.string().uuid().nullable(),
+  destinationProposalId: z.string().uuid().nullable(),
+  destinationRevisionId: z.string().uuid().nullable(),
+  taskNoteSource: z
+    .object({
+      noteId: z.string().uuid(),
+      rootSessionId: z.string().uuid(),
+      noteVersion: z.literal(1),
+      textHash: z.string().regex(/^[0-9a-f]{64}$/),
+    })
+    .nullable()
+    .optional(),
+  effectiveBoundary: z.literal("human_review_required"),
+  rollback: z.object({
+    supported: z.literal(false),
+    mechanism: z.literal("not_applicable_proposal_only"),
+  }),
+});
+export type CompanyBrainGovernedWriteReceipt = z.infer<typeof CompanyBrainGovernedWriteReceipt>;
+
+/**
+ * Policy routing is deliberately separate from destination admission. The
+ * immutable accepted-attempt snapshot decides whether derived evidence may
+ * create a proposal; the destination still owns activation and rollback.
+ */
+export const CompanyBrainLearningPolicyDecision = z.enum([
+  "blocked",
+  "proposal_created",
+  "activation_requested",
+  "activated",
+]);
+export type CompanyBrainLearningPolicyDecision = z.infer<typeof CompanyBrainLearningPolicyDecision>;
+
+/**
+ * Content-free summary of the governed-learning decision receipt recorded for
+ * a Ways-of-working proposal (instruction policy or preference). Knowledge
+ * destinations create no `knowledge_change_proposals` row and are therefore
+ * never evaluated; they report `null`.
+ */
+export const CompanyBrainLearningDecisionSummary = z.object({
+  receiptId: z.string().uuid(),
+  outcome: GovernedLearningDecisionOutcome,
+  automaticEligible: z.boolean(),
+  reasons: z.array(GovernedLearningDecisionReason).max(16),
+});
+export type CompanyBrainLearningDecisionSummary = z.infer<
+  typeof CompanyBrainLearningDecisionSummary
+>;
+
+/**
+ * Bounded, content-free reason why evaluation or activation did not complete.
+ * The proposal write itself remains durable regardless.
+ */
+export const CompanyBrainLearningStepFailure = z.object({
+  stage: z.enum(["evaluation", "activation"]),
+  code: z.enum(["authority", "conflict", "invalid_operation", "unavailable"]),
+});
+export type CompanyBrainLearningStepFailure = z.infer<typeof CompanyBrainLearningStepFailure>;
+
+export const CompanyBrainLearningPolicyRouteReceipt = z.object({
+  operationId,
+  workspaceId: z.string().uuid(),
+  effectivePolicy: WorkspaceLearningPolicyEffectiveMode,
+  decision: CompanyBrainLearningPolicyDecision,
+  write: CompanyBrainGovernedWriteReceipt.nullable(),
+  learning: CompanyBrainLearningDecisionSummary.nullable().default(null),
+  learningFailure: CompanyBrainLearningStepFailure.nullable().default(null),
+  activation: z.object({
+    requested: z.boolean(),
+    activated: z.boolean(),
+    boundary: z.enum([
+      "policy_off",
+      "human_review",
+      "destination_authority",
+      "not_eligible",
+      "human_activation_required",
+      "activated",
+    ]),
+    receiptId: z.string().uuid().nullable().default(null),
+    destination: GovernedLearningActivationDestination.nullable().default(null),
+    destinationRevisionId: z.string().uuid().nullable().default(null),
+    effectiveAt: z.string().datetime().nullable().default(null),
+  }),
+});
+export type CompanyBrainLearningPolicyRouteReceipt = z.infer<
+  typeof CompanyBrainLearningPolicyRouteReceipt
+>;

package/src/company-brain.ts

@@ -0,0 +1,201 @@
+import { z } from "zod";
+
+import { WorkspaceStateKnowledge } from "./workspace-state";
+
+export const COMPANY_BRAIN_OKF_SCHEMA_VERSION = 1 as const;
+export const COMPANY_BRAIN_GUIDANCE_MAX_ENTRIES = 512;
+export const COMPANY_BRAIN_GUIDANCE_CONTENT_MAX_CHARS = 262_144;
+export const COMPANY_BRAIN_GUIDANCE_MAX_CONTENT_BYTES = 4 * 1024 * 1024;
+export const COMPANY_BRAIN_INSPECTOR_DEFAULT_LIMIT = 20;
+export const COMPANY_BRAIN_INSPECTOR_MAX_LIMIT = 50;
+export const COMPANY_BRAIN_INSPECTOR_CURSOR_MAX_CHARS = 1_024;
+export const COMPANY_BRAIN_PROPOSAL_CONTENT_MAX_BYTES = 16 * 1_024;
+export const COMPANY_BRAIN_PROPOSAL_RESPONSE_MAX_BYTES = 64 * 1_024;
+
+const utf8Bytes = (value: string): number => new TextEncoder().encode(value).byteLength;
+const boundedUtf8 = (maxBytes: number) =>
+  z.string().superRefine((value, context) => {
+    if (utf8Bytes(value) > maxBytes) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `must be at most ${maxBytes} UTF-8 bytes`,
+      });
+    }
+  });
+
+export const CompanyBrainContextReceipt = z
+  .object({
+    id: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    rootSessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    acceptedAt: z.string().datetime(),
+    createdAt: z.string().datetime(),
+    sessionRole: z.enum(["root", "child"]),
+    memoryEnabled: z.boolean(),
+    // Snapshots are immutable: a turn accepted before the standing block was
+    // retired recorded `legacy_standing` and still reads back that way. This
+    // is a historical fact about that turn, not a mode anyone can select.
+    memoryPromptMode: z.enum(["legacy_standing", "retrieval_only"]),
+    companyProfileIncluded: z.boolean(),
+    instructionPolicyEntryHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    preferenceDescriptorHash: z
+      .string()
+      .regex(/^[0-9a-f]{64}$/u)
+      .nullable(),
+    companyProfileSnapshotHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    turnContextSnapshotId: z.string().uuid(),
+    turnContextSnapshotHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    turnContextSnapshotSource: z.enum(["accepted_turn", "legacy_first_claim"]),
+    selectionHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    selectedMemoryCount: z.number().int().nonnegative().max(50),
+    renderedMemoryCount: z.number().int().nonnegative().max(50),
+    budgetOmittedMemoryCount: z.number().int().nonnegative().max(50),
+  })
+  .strict();
+export type CompanyBrainContextReceipt = z.infer<typeof CompanyBrainContextReceipt>;
+
+export const CompanyBrainContextReceiptPage = z
+  .object({
+    receipts: z.array(CompanyBrainContextReceipt).max(COMPANY_BRAIN_INSPECTOR_MAX_LIMIT),
+    nextCursor: z.string().min(1).max(COMPANY_BRAIN_INSPECTOR_CURSOR_MAX_CHARS).nullable(),
+    hasMore: z.boolean(),
+  })
+  .strict();
+export type CompanyBrainContextReceiptPage = z.infer<typeof CompanyBrainContextReceiptPage>;
+
+export const CompanyBrainKnowledgeProposal = z
+  .object({
+    id: z.string().uuid(),
+    authority: z.object({ kind: z.enum(["organization", "workspace", "personal"]) }).strict(),
+    targetKind: z.enum(["instruction_policy", "preference"]),
+    targetScope: z.string().min(1).max(96),
+    targetKey: z.string().min(1).max(96).nullable(),
+    content: boundedUtf8(COMPANY_BRAIN_PROPOSAL_CONTENT_MAX_BYTES),
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/u),
+    source: z.object({ claimId: z.string().uuid(), evidenceId: z.string().uuid() }).strict(),
+    status: z.literal("proposed"),
+    createdAt: z.string().datetime(),
+    projection: z
+      .object({
+        truncated: z.boolean(),
+        originalContentUtf8Bytes: z.number().int().nonnegative().max(1_048_576),
+      })
+      .strict(),
+  })
+  .strict();
+export type CompanyBrainKnowledgeProposal = z.infer<typeof CompanyBrainKnowledgeProposal>;
+
+export const CompanyBrainKnowledgeProposalPage = z
+  .object({
+    proposals: z.array(CompanyBrainKnowledgeProposal).max(COMPANY_BRAIN_INSPECTOR_MAX_LIMIT),
+    truncatedForCount: z.boolean(),
+    truncatedForResponseBytes: z.boolean(),
+    responseBytes: z.number().int().nonnegative().max(COMPANY_BRAIN_PROPOSAL_RESPONSE_MAX_BYTES),
+  })
+  .strict();
+export type CompanyBrainKnowledgeProposalPage = z.infer<typeof CompanyBrainKnowledgeProposalPage>;
+
+export const CompanyBrainGuidanceClassification = z.enum([
+  "company_profile",
+  "mandatory_rule",
+  "guide",
+]);
+export type CompanyBrainGuidanceClassification = z.infer<typeof CompanyBrainGuidanceClassification>;
+
+export const CompanyBrainGuidanceScope = z.enum(["organization", "workspace", "personal"]);
+export type CompanyBrainGuidanceScope = z.infer<typeof CompanyBrainGuidanceScope>;
+
+export const CompanyBrainGuidanceLifecycle = z.enum([
+  "active",
+  "proposal",
+  "inactive",
+  "rejected",
+  "superseded",
+  "expired",
+  "historical",
+]);
+export type CompanyBrainGuidanceLifecycle = z.infer<typeof CompanyBrainGuidanceLifecycle>;
+
+export const CompanyBrainGuidanceRelationship = z
+  .object({
+    type: z.enum(["corrects", "supersedes", "superseded_by"]),
+    targetId: z.string().min(1).max(512),
+  })
+  .strict();
+export type CompanyBrainGuidanceRelationship = z.infer<typeof CompanyBrainGuidanceRelationship>;
+
+export const CompanyBrainGuidanceEntry = z
+  .object({
+    id: z.string().min(1).max(512),
+    revisionId: z.string().uuid(),
+    path: z.string().min(1).max(512),
+    scope: CompanyBrainGuidanceScope,
+    classification: CompanyBrainGuidanceClassification,
+    title: z.string().min(1).max(160),
+    description: z.string().max(512).nullable(),
+    content: z.string().min(1).max(COMPANY_BRAIN_GUIDANCE_CONTENT_MAX_CHARS),
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/),
+    revision: z.number().int().positive(),
+    active: z.boolean(),
+    lifecycle: CompanyBrainGuidanceLifecycle,
+    provenance: z
+      .object({
+        source: z.string().min(1).max(96),
+        sourceId: z.string().min(1).max(512).nullable(),
+        trust: z.string().min(1).max(96).nullable(),
+      })
+      .strict(),
+    relationships: z.array(CompanyBrainGuidanceRelationship).max(32),
+    createdAt: z.string().datetime(),
+  })
+  .strict();
+export type CompanyBrainGuidanceEntry = z.infer<typeof CompanyBrainGuidanceEntry>;
+
+export const CompanyBrainGuidanceTruncationReason = z.enum([
+  "company_profile_history",
+  "instruction_policy_history",
+  "preference_count",
+  "preference_history",
+  "aggregate_item_count",
+  "aggregate_content_bytes",
+]);
+export type CompanyBrainGuidanceTruncationReason = z.infer<
+  typeof CompanyBrainGuidanceTruncationReason
+>;
+
+export const CompanyBrainOkfPackage = z
+  .object({
+    kind: z.literal("opengeni.company_brain.okf"),
+    schemaVersion: z.literal(COMPANY_BRAIN_OKF_SCHEMA_VERSION),
+    workspaceId: z.string().uuid(),
+    generatedAt: z.string().datetime(),
+    permissions: z
+      .object({
+        guidance: z.literal("available"),
+        knowledge: z.enum(["available", "unavailable"]),
+      })
+      .strict(),
+    guidance: z
+      .object({
+        entries: z.array(CompanyBrainGuidanceEntry).max(COMPANY_BRAIN_GUIDANCE_MAX_ENTRIES),
+        truncated: z.boolean(),
+        truncationReasons: z.array(CompanyBrainGuidanceTruncationReason).max(6),
+      })
+      .strict(),
+    knowledge: WorkspaceStateKnowledge,
+    omissions: z
+      .array(
+        z.enum([
+          "inaccessible_knowledge",
+          "document_bodies_use_documents_export",
+          "memory_bodies_and_provenance",
+          "secret_values_and_credentials",
+          "session_messages_and_task_notes",
+          "policy_and_preference_actor_identifiers",
+        ]),
+      )
+      .max(6),
+  })
+  .strict();
+export type CompanyBrainOkfPackage = z.infer<typeof CompanyBrainOkfPackage>;

package/src/company-profile.ts

@@ -1,4 +1,11 @@
 import { z } from "zod";
+import {
+  AGENT_AUTHORED_COMPANY_PROFILE_CONTENT_MAX_UTF8_BYTES,
+  AGENT_AUTHORED_COMPANY_PROFILE_ENTRY_MAX_CHARS,
+  AGENT_AUTHORED_COMPANY_PROFILE_SCALAR_MAX_CHARS,
+  AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE,
+} from "./agent-authored-durable-text";
+import { HumanInputQuestion } from "./index";
 
 export const COMPANY_PROFILE_SCALAR_MAX_CHARS = 2_048;
 export const COMPANY_PROFILE_ENTRY_MAX_CHARS = 1_024;
@@ -100,10 +107,56 @@ export const CompanyProfileContent = z
   });
 export type CompanyProfileContent = z.infer<typeof CompanyProfileContent>;
 
+/**
+ * The same profile, bounded for an **agent** author. The human `account:admin`
+ * route keeps `CompanyProfileContent` and its wider limits; this is the shape
+ * the first-party `company_profile_propose` tool accepts, because the profile is
+ * the largest always-on prompt surface in the product and a model left to its
+ * own judgement fills every field to the ceiling.
+ */
+export const AgentAuthoredCompanyProfileContent = CompanyProfileContent.superRefine(
+  (value, context) => {
+    for (const field of ["identity", "mission"] as const) {
+      const scalar = value[field];
+      if (scalar !== null && scalar.length > AGENT_AUTHORED_COMPANY_PROFILE_SCALAR_MAX_CHARS) {
+        context.addIssue({
+          code: "custom",
+          path: [field],
+          message: `${field} is ${scalar.length} characters. ${AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE}`,
+        });
+      }
+    }
+    for (const field of ["products", "customers", "goals", "constraints"] as const) {
+      for (const [index, entry] of value[field].entries()) {
+        if (entry.content.length > AGENT_AUTHORED_COMPANY_PROFILE_ENTRY_MAX_CHARS) {
+          context.addIssue({
+            code: "custom",
+            path: [field, index, "content"],
+            message: `this entry is ${entry.content.length} characters. ${AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE}`,
+          });
+        }
+      }
+    }
+    const contentBytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+    if (contentBytes > AGENT_AUTHORED_COMPANY_PROFILE_CONTENT_MAX_UTF8_BYTES) {
+      context.addIssue({
+        code: "custom",
+        message: `this profile is ${contentBytes} UTF-8 bytes. ${AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE}`,
+      });
+    }
+  },
+);
+export type AgentAuthoredCompanyProfileContent = z.infer<typeof AgentAuthoredCompanyProfileContent>;
+
 export const CompanyProfileRevisionIntent = z.enum(["active", "proposal"]);
 export type CompanyProfileRevisionIntent = z.infer<typeof CompanyProfileRevisionIntent>;
 
-export const CompanyProfileProvenanceSource = z.enum(["human", "durable_learning", "migration"]);
+export const CompanyProfileProvenanceSource = z.enum([
+  "human",
+  "agent_admin",
+  "durable_learning",
+  "migration",
+]);
 export type CompanyProfileProvenanceSource = z.infer<typeof CompanyProfileProvenanceSource>;
 
 export const CompanyProfilePrincipalKind = z.enum(["human_session", "agent_attempt", "service"]);
@@ -240,6 +293,74 @@ export const CompanyProfileMutationResponse = z.object({
 });
 export type CompanyProfileMutationResponse = z.infer<typeof CompanyProfileMutationResponse>;
 
+export const COMPANY_PROFILE_AGENT_APPROVE_OPTION = "activate" as const;
+export const COMPANY_PROFILE_AGENT_REJECT_OPTION = "skip" as const;
+
+export const CompanyProfileAgentAttempt = z
+  .object({
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    turnId: z.string().uuid(),
+    attemptId: z.string().uuid(),
+    executionGeneration: z.number().int().positive(),
+    agentSubjectId: z.string().trim().min(1).max(1_024),
+  })
+  .strict();
+export type CompanyProfileAgentAttempt = z.infer<typeof CompanyProfileAgentAttempt>;
+
+export const CompanyProfileAgentProposalRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    profile: CompanyProfileContent,
+    reason: z.string().trim().min(1).max(COMPANY_PROFILE_REASON_MAX_CHARS),
+  })
+  .strict();
+export type CompanyProfileAgentProposalRequest = z.infer<typeof CompanyProfileAgentProposalRequest>;
+
+// z.lazy avoids an import cycle because HumanInputQuestion is declared in the
+// root contracts module that re-exports this file.
+export const CompanyProfileAgentHumanInputPrompt = z.object({
+  questions: z.array(z.lazy(() => HumanInputQuestion)).length(1),
+  allowSkip: z.literal(false),
+});
+export type CompanyProfileAgentHumanInputPrompt = z.infer<
+  typeof CompanyProfileAgentHumanInputPrompt
+>;
+
+export const CompanyProfileAgentProposalReceipt = z.object({
+  status: z.literal("confirmation_required"),
+  operationId: z.string().uuid(),
+  proposalReceiptId: z.string().uuid(),
+  revision: CompanyProfileRevision,
+  humanInput: CompanyProfileAgentHumanInputPrompt,
+  confirmWith: z.literal("company_profile_confirm"),
+  replayed: z.boolean(),
+});
+export type CompanyProfileAgentProposalReceipt = z.infer<typeof CompanyProfileAgentProposalReceipt>;
+
+export const CompanyProfileAgentConfirmRequest = z
+  .object({
+    operationId: z.string().uuid(),
+    proposalReceiptId: z.string().uuid(),
+    humanInputRequestId: z.string().uuid(),
+  })
+  .strict();
+export type CompanyProfileAgentConfirmRequest = z.infer<typeof CompanyProfileAgentConfirmRequest>;
+
+export const CompanyProfileAgentConfirmationReceipt = z.object({
+  status: z.literal("activated"),
+  operationId: z.string().uuid(),
+  confirmationReceiptId: z.string().uuid(),
+  proposalReceiptId: z.string().uuid(),
+  humanInputRequestId: z.string().uuid(),
+  mutation: CompanyProfileMutationResponse,
+  replayed: z.boolean(),
+});
+export type CompanyProfileAgentConfirmationReceipt = z.infer<
+  typeof CompanyProfileAgentConfirmationReceipt
+>;
+
 export const CompanyProfileDiffRequest = z
   .object({ fromRevisionId: z.string().uuid(), toRevisionId: z.string().uuid() })
   .refine((value) => value.fromRevisionId !== value.toRevisionId, {