@opengeni/api-router 0.30.3 → 1.0.0

package/src/codemode.ts

@@ -1,3 +1,4 @@
+import { siteRequestHeaders } from "@opengeni/contracts/site-session-http";
 import {
   codemodeDispatchSubject,
   decodeCodemodeDispatchAck,
@@ -13,13 +14,113 @@ import {
   type CodemodeOperation,
 } from "@opengeni/contracts";
 import type { ApiRouteDeps } from "@opengeni/core";
-import { hasPermission, requireSessionAuthorization } from "@opengeni/core";
+import { hasPermission, isDeveloperSetupGrant, requireSessionAuthorization } from "@opengeni/core";
 import {
   getActiveSessionTurnForExecution,
   getAttemptToolCatalog,
   getCodemodeOperation,
   submitCodemodeOperation,
+  type SessionTurnForExecution,
 } from "@opengeni/db";
+import { getSession } from "@opengeni/db";
+import {
+  allowedFirstPartyMcpToolsForSession,
+  resolveFirstPartyDelegationSecret,
+  type Settings,
+} from "@opengeni/config";
+import {
+  DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
+  signDelegatedAccessToken,
+  readTurnExecutionPolicyV1,
+  siteSessionPath,
+  OPENGENI_API_CONTRACT_HEADER,
+  OPENGENI_API_CONTRACT_REVISION,
+  type Permission,
+  type Session,
+} from "@opengeni/contracts";
+import { permissionsRequiredByFirstPartyTools } from "./mcp/first-party-tool-permissions";
+
+/** The REST authority a Codemode SDK proxy token may ever carry. */
+export const CODEMODE_SESSION_PROXY_PERMISSION_CEILING = [
+  "workspace:read",
+  "sessions:read",
+  "sessions:create",
+  "sessions:control",
+] as const satisfies readonly Permission[];
+
+/**
+ * Proxy permissions = the session's effective first-party permissions, cut
+ * down to what its exact model-visible tool selection could actually
+ * exercise (plus workspace:read for the context routes), under the fixed
+ * ceiling above. A session whose selection has no session_* tool therefore
+ * gets only workspace:read and every proxied /sessions handler refuses it,
+ * exactly as its MCP surface would.
+ */
+export function codemodeSessionProxyPermissions(
+  settings: Pick<Settings, "defaultFirstPartyMcpTools" | "allowedFirstPartyMcpTools">,
+  session: Pick<Session, "firstPartyMcpTools" | "firstPartyMcpPermissions">,
+): Permission[] {
+  const sessionPermissions = session.firstPartyMcpPermissions ?? [
+    ...DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
+  ];
+  const selection = allowedFirstPartyMcpToolsForSession(settings, session.firstPartyMcpTools);
+  const requiredBySelection = new Set<Permission>([
+    "workspace:read",
+    ...permissionsRequiredByFirstPartyTools(selection),
+  ]);
+  return CODEMODE_SESSION_PROXY_PERMISSION_CEILING.filter(
+    (permission) => requiredBySelection.has(permission) && sessionPermissions.includes(permission),
+  );
+}
+
+/** Reuse normal REST handlers, including their resource/command authorization.
+ * The exact attempt is checked before issuing this internal-only credential. */
+export async function codemodeSessionRequest(
+  deps: ApiRouteDeps,
+  grant: AccessGrant,
+  request: Request,
+  path: string,
+  resolveProxySettings?: (
+    session: Session,
+  ) => Pick<Settings, "defaultFirstPartyMcpTools" | "allowedFirstPartyMcpTools">,
+): Promise<Request> {
+  siteSessionPath(path, grant.workspaceId, request.method);
+  const { authority, turn } = await requireActiveCodemodeCatalog(deps, grant);
+  const session = await getSession(deps.db, authority.workspaceId, authority.sessionId);
+  const secret = resolveFirstPartyDelegationSecret(deps.settings);
+  if (!session || !secret) throw new CodemodeAuthorityError("invalid_grant");
+  const permissions = codemodeSessionProxyPermissions(
+    resolveProxySettings?.(session) ?? deps.settings,
+    session,
+  );
+  const turnPolicy = readTurnExecutionPolicyV1(turn.metadata);
+  const initialPolicy = readTurnExecutionPolicyV1(session.metadata);
+  const restricted =
+    isDeveloperSetupGrant(grant) ||
+    (turnPolicy.kind === "valid" &&
+      turnPolicy.policy.credentialRestriction === "developer_setup") ||
+    (initialPolicy.kind === "valid" &&
+      initialPolicy.policy.credentialRestriction === "developer_setup");
+  const token = await signDelegatedAccessToken(secret, {
+    ...authority,
+    permissions,
+    principalKind: "agent_attempt",
+    ...(restricted ? { credentialRestriction: "developer_setup" as const } : {}),
+    exp: Math.floor(Date.now() / 1000) + 60,
+  });
+  const target = new URL(request.url);
+  const rewritten = siteSessionPath(path, authority.workspaceId, request.method);
+  const url = new URL(rewritten, target.origin);
+  const headers = siteRequestHeaders(request.headers);
+  headers.set("authorization", `Bearer ${token}`);
+  headers.set(OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION);
+  return new Request(url, {
+    method: request.method,
+    headers,
+    signal: request.signal,
+    ...(request.body ? { body: await request.text() } : {}),
+  });
+}
 
 export type CodemodeGrantAuthority = {
   accountId: string;
@@ -31,12 +132,42 @@ export type CodemodeGrantAuthority = {
   subjectId: string;
 };
 
+export type CodemodeAuthorityFailureReason =
+  | "invalid_grant"
+  | "inactive_attempt"
+  | "catalog_mismatch";
+
+const CODEMODE_AUTHORITY_FAILURE_MESSAGES: Record<CodemodeAuthorityFailureReason, string> = {
+  invalid_grant: "Codemode bearer does not carry valid execution-attempt authority",
+  inactive_attempt: "Codemode execution attempt is no longer active",
+  catalog_mismatch: "Codemode tool catalog does not match the active execution attempt",
+};
+
 export class CodemodeAuthorityError extends Error {
-  readonly code = "codemode_authority_invalid";
+  readonly code: `codemode_${CodemodeAuthorityFailureReason}`;
 
-  constructor() {
-    super("Codemode bearer is not bound to an active execution attempt");
+  constructor(readonly reason: CodemodeAuthorityFailureReason) {
+    super(CODEMODE_AUTHORITY_FAILURE_MESSAGES[reason]);
     this.name = "CodemodeAuthorityError";
+    this.code = `codemode_${reason}`;
+  }
+}
+
+export class CodemodeCatalogNotReadyError extends Error {
+  readonly code = "codemode_catalog_not_ready";
+
+  constructor() {
+    super("Codemode tool catalog is not ready for the active execution attempt");
+    this.name = "CodemodeCatalogNotReadyError";
+  }
+}
+
+export class CodemodeCatalogStaleError extends Error {
+  readonly code = "codemode_catalog_stale";
+
+  constructor() {
+    super("Codemode tool catalog is stale for the active execution attempt");
+    this.name = "CodemodeCatalogStaleError";
   }
 }
 
@@ -71,11 +202,33 @@ export function isCodemodeGrant(grant: AccessGrant): boolean {
   );
 }
 
+export function requireMatchingCodemodeCatalog(
+  authority: CodemodeGrantAuthority,
+  catalog: AttemptToolCatalog | null,
+): AttemptToolCatalog {
+  if (!catalog) throw new CodemodeCatalogNotReadyError();
+  if (
+    catalog.accountId !== authority.accountId ||
+    catalog.workspaceId !== authority.workspaceId ||
+    catalog.sessionId !== authority.sessionId ||
+    catalog.turnId !== authority.turnId ||
+    catalog.attemptId !== authority.attemptId ||
+    catalog.executionGeneration !== authority.executionGeneration
+  ) {
+    throw new CodemodeAuthorityError("catalog_mismatch");
+  }
+  return catalog;
+}
+
 export async function requireActiveCodemodeCatalog(
   deps: ApiRouteDeps,
   grant: AccessGrant,
-): Promise<{ authority: CodemodeGrantAuthority; catalog: AttemptToolCatalog }> {
-  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError();
+): Promise<{
+  authority: CodemodeGrantAuthority;
+  catalog: AttemptToolCatalog;
+  turn: SessionTurnForExecution;
+}> {
+  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError("invalid_grant");
   const authority = codemodeAuthorityForGrant(grant)!;
   await requireSessionAuthorization(deps, grant, {
     sessionId: authority.sessionId,
@@ -94,25 +247,17 @@ export async function requireActiveCodemodeCatalog(
     active.activeAttemptId !== authority.attemptId ||
     active.executionGeneration !== authority.executionGeneration
   ) {
-    throw new CodemodeAuthorityError();
+    throw new CodemodeAuthorityError("inactive_attempt");
   }
-  const catalog = await getAttemptToolCatalog(deps.db, {
-    accountId: authority.accountId,
-    workspaceId: authority.workspaceId,
-    attemptId: authority.attemptId,
-  });
-  if (
-    !catalog ||
-    catalog.accountId !== authority.accountId ||
-    catalog.workspaceId !== authority.workspaceId ||
-    catalog.sessionId !== authority.sessionId ||
-    catalog.turnId !== authority.turnId ||
-    catalog.attemptId !== authority.attemptId ||
-    catalog.executionGeneration !== authority.executionGeneration
-  ) {
-    throw new CodemodeAuthorityError();
-  }
-  return { authority, catalog };
+  const catalog = requireMatchingCodemodeCatalog(
+    authority,
+    await getAttemptToolCatalog(deps.db, {
+      accountId: authority.accountId,
+      workspaceId: authority.workspaceId,
+      attemptId: authority.attemptId,
+    }),
+  );
+  return { authority, catalog, turn: active };
 }
 
 export async function submitAndDispatchCodemodeCall(
@@ -122,13 +267,13 @@ export async function submitAndDispatchCodemodeCall(
 ): Promise<CodemodeCallSubmissionValue> {
   const request = CodemodeCallRequest.parse(rawRequest);
   const { authority, catalog } = await requireActiveCodemodeCatalog(deps, grant);
+  if (request.catalogDigest !== catalog.digest) throw new CodemodeCatalogStaleError();
   const submitted = await submitCodemodeOperation(deps.db, {
     ...authority,
     call: {
       ...request,
       caller: { kind: "codemode", subjectId: authority.subjectId },
     },
-    callLimit: deps.settings.codemodeMaxCallsPerTurn,
   });
   let operation = submitted.operation;
   let dispatch: CodemodeCallSubmissionValue["dispatch"] = terminal(operation)
@@ -136,7 +281,7 @@ export async function submitAndDispatchCodemodeCall(
     : operation.state === "running"
       ? "already_running"
       : "unavailable";
-  if (operation.state === "queued") {
+  if (codemodeOperationNeedsDispatch(operation)) {
     try {
       const reply = await deps.bus.request(
         codemodeDispatchSubject(authority.workspaceId, authority.attemptId),
@@ -151,13 +296,14 @@ export async function submitAndDispatchCodemodeCall(
     } catch {
       dispatch = "unavailable";
     }
-    operation =
-      (await getCodemodeOperation(deps.db, {
+    operation = await refreshAdmittedCodemodeOperation(operation, () =>
+      getCodemodeOperation(deps.db, {
         accountId: authority.accountId,
         workspaceId: authority.workspaceId,
         attemptId: authority.attemptId,
         operationId: operation.operationId,
-      })) ?? operation;
+      }),
+    );
     if (terminal(operation)) dispatch = "terminal";
     else if (operation.state === "running" && dispatch === "unavailable") {
       dispatch = "already_running";
@@ -166,12 +312,16 @@ export async function submitAndDispatchCodemodeCall(
   return CodemodeCallSubmission.parse({ operation, dispatch });
 }
 
+export function codemodeOperationNeedsDispatch(operation: CodemodeOperation): boolean {
+  return operation.state === "queued" || operation.state === "running";
+}
+
 export async function readCodemodeOperation(
   deps: ApiRouteDeps,
   grant: AccessGrant,
   operationId: string,
 ): Promise<CodemodeOperation | null> {
-  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError();
+  if (!isCodemodeGrant(grant)) throw new CodemodeAuthorityError("invalid_grant");
   const authority = codemodeAuthorityForGrant(grant)!;
   return await getCodemodeOperation(deps.db, {
     accountId: authority.accountId,
@@ -184,3 +334,17 @@ export async function readCodemodeOperation(
 function terminal(operation: CodemodeOperation): boolean {
   return ["completed", "failed", "outcome_unknown", "cancelled"].includes(operation.state);
 }
+
+export async function refreshAdmittedCodemodeOperation(
+  admitted: CodemodeOperation,
+  read: () => Promise<CodemodeOperation | null>,
+): Promise<CodemodeOperation> {
+  try {
+    return (await read()) ?? admitted;
+  } catch {
+    // Admission is already durable. Returning the known row lets the client
+    // continue with the same operation id instead of turning a refresh outage
+    // into an unmarked post-commit failure.
+    return admitted;
+  }
+}

package/src/codex-realtime.ts

@@ -5,6 +5,7 @@ import {
   CodexRealtimeError,
   CodexReloginRequired,
   createCodexRealtimeCall,
+  fetchCodexRealtimeProviderConfig,
   selectCodexCredentialId,
   type CodexAuthHeaders,
   type CodexFetch,
@@ -295,8 +296,13 @@ export function buildSessionCodexRealtimeBroker(
         },
         tokenResolver: (credentialId) =>
           buildCodexTokenResolver(db, settings, workspaceId, credentialId),
-        createCall: async (auth, callInput, options) =>
-          await createCodexRealtimeCall(auth, callInput, fetchImpl, options),
+        createCall: async (auth, callInput, options) => {
+          const providerConfig = await fetchCodexRealtimeProviderConfig(auth, fetchImpl, options);
+          return await createCodexRealtimeCall(auth, callInput, fetchImpl, {
+            ...options,
+            providerConfig,
+          });
+        },
       },
       { ...input, sessionId },
     );

package/src/company-brain-okf.ts

@@ -0,0 +1,340 @@
+import {
+  COMPANY_BRAIN_GUIDANCE_MAX_CONTENT_BYTES,
+  COMPANY_BRAIN_GUIDANCE_MAX_ENTRIES,
+  CompanyBrainOkfPackage,
+  type CompanyBrainGuidanceEntry,
+  type CompanyBrainGuidanceTruncationReason,
+  type CompanyBrainOkfPackage as CompanyBrainOkfPackageType,
+  type CompanyProfileListResponse,
+  type WorkspaceInstructionPolicyListResponse,
+  type WorkspaceInstructionPolicyRevision,
+  type WorkspaceStateKnowledge,
+} from "@opengeni/contracts";
+import type { CompanyBrainPreferenceGuidancePage } from "@opengeni/db";
+
+const OKF_MARKER = "<!-- opengeni-company-brain-okf-v1 -->";
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, nested]) => [key, canonicalize(nested)]),
+  );
+}
+
+function canonicalJson(value: unknown): string {
+  return `${JSON.stringify(canonicalize(value), null, 2)}\n`;
+}
+
+function companyProfileEntries(profile: CompanyProfileListResponse): {
+  entries: CompanyBrainGuidanceEntry[];
+  truncated: boolean;
+} {
+  const activeRevisionId = profile.current?.revisionId ?? null;
+  const byId = new Map(profile.revisions.map((revision) => [revision.id, revision] as const));
+  if (profile.activeRevision) byId.set(profile.activeRevision.id, profile.activeRevision);
+  return {
+    entries: [...byId.values()].map((revision) => {
+      const active = revision.id === activeRevisionId;
+      return {
+        id: "company-profile",
+        revisionId: revision.id,
+        path: "company/profile",
+        scope: "organization",
+        classification: "company_profile",
+        title: "Company profile",
+        description: "Company identity, mission, products, customers, goals, and constraints.",
+        // Company-profile hashes cover this exact canonical field order.
+        content: JSON.stringify(revision.profile),
+        contentHash: revision.contentHash,
+        revision: revision.revision,
+        active,
+        lifecycle: active ? "active" : revision.intent === "proposal" ? "proposal" : "historical",
+        provenance: {
+          source: revision.provenance.source,
+          sourceId: revision.provenance.sourceId,
+          trust: revision.intent === "proposal" ? "untrusted_proposal" : "organization_managed",
+        },
+        relationships:
+          revision.supersedesRevisionId && byId.has(revision.supersedesRevisionId)
+            ? [{ type: "supersedes" as const, targetId: revision.supersedesRevisionId }]
+            : [],
+        createdAt: revision.createdAt,
+      } satisfies CompanyBrainGuidanceEntry;
+    }),
+    truncated: profile.nextAfterRevision !== null,
+  };
+}
+
+function instructionPolicyEntries(
+  policies: WorkspaceInstructionPolicyListResponse,
+  activeRevisions: WorkspaceInstructionPolicyRevision[],
+  activatedRevisionIds: string[],
+): { entries: CompanyBrainGuidanceEntry[]; truncated: boolean } {
+  const byId = new Map(policies.revisions.map((revision) => [revision.id, revision] as const));
+  for (const revision of activeRevisions) byId.set(revision.id, revision);
+  const activeIds = new Set(policies.activeHeads.map((head) => head.revisionId));
+  const activatedIds = new Set(activatedRevisionIds);
+  return {
+    entries: [...byId.values()].map((revision) => {
+      const roleSegment = revision.roleKey ?? "all";
+      const active = activeIds.has(revision.id);
+      const lifecycle = active
+        ? "active"
+        : activatedIds.has(revision.id)
+          ? "historical"
+          : revision.provenance.source === "onboarding" ||
+              revision.provenance.source === "knowledge_proposal"
+            ? "proposal"
+            : "inactive";
+      return {
+        id: `instruction-policy:${revision.kind}:${revision.scope}:${roleSegment}`,
+        revisionId: revision.id,
+        path: `ways-of-working/rules/${revision.kind}/${revision.scope}/${roleSegment}`,
+        scope: "workspace",
+        classification: "mandatory_rule",
+        title:
+          revision.kind === "charter"
+            ? "Workspace charter"
+            : revision.scope === "role"
+              ? `Role policy: ${roleSegment}`
+              : "Workspace policy",
+        description: active ? "Mandatory context included for applicable agents." : null,
+        content: revision.content,
+        contentHash: revision.contentHash,
+        revision: revision.revision,
+        active,
+        lifecycle,
+        provenance: {
+          source: revision.provenance.source,
+          sourceId: revision.provenance.sourceId,
+          trust:
+            revision.provenance.source === "human"
+              ? "workspace_managed"
+              : revision.provenance.source === "legacy_import"
+                ? "migrated"
+                : "untrusted_proposal",
+        },
+        relationships:
+          revision.supersedesRevisionId && byId.has(revision.supersedesRevisionId)
+            ? [{ type: "supersedes" as const, targetId: revision.supersedesRevisionId }]
+            : [],
+        createdAt: revision.createdAt,
+      } satisfies CompanyBrainGuidanceEntry;
+    }),
+    truncated: policies.nextAfterRevision !== null,
+  };
+}
+
+function preferenceLifecycle(
+  row: CompanyBrainPreferenceGuidancePage["rows"][number],
+  generatedAt: string,
+): CompanyBrainGuidanceEntry["lifecycle"] {
+  if (row.active && row.expiresAt && row.expiresAt.getTime() <= Date.parse(generatedAt)) {
+    return "expired";
+  }
+  if (row.active && row.status === "active") return "active";
+  if (row.status === "proposed") return "proposal";
+  if (row.status === "inactive") return "inactive";
+  if (row.status === "rejected") return "rejected";
+  if (row.status === "superseded") return "superseded";
+  return "historical";
+}
+
+function preferenceEntries(
+  page: CompanyBrainPreferenceGuidancePage,
+  generatedAt: string,
+): CompanyBrainGuidanceEntry[] {
+  const visibleRevisionIds = new Set(page.rows.map((row) => row.revisionId));
+  const visiblePreferenceIds = new Set(page.rows.map((row) => row.preferenceId));
+  return page.rows.map((row) => {
+    const scope =
+      row.scope === "organization"
+        ? "organization"
+        : row.scope === "user"
+          ? "personal"
+          : "workspace";
+    const lifecycle = preferenceLifecycle(row, generatedAt);
+    const relationships: CompanyBrainGuidanceEntry["relationships"] = [];
+    if (row.correctsRevisionId && visibleRevisionIds.has(row.correctsRevisionId)) {
+      relationships.push({ type: "corrects", targetId: row.correctsRevisionId });
+    }
+    if (row.supersededByPreferenceId && visiblePreferenceIds.has(row.supersededByPreferenceId)) {
+      relationships.push({
+        type: "superseded_by",
+        targetId: `preference:${row.supersededByPreferenceId}`,
+      });
+    }
+    return {
+      id: `preference:${row.preferenceId}`,
+      revisionId: row.revisionId,
+      path: `ways-of-working/guides/${scope}/${row.stableKey}`,
+      scope,
+      classification: "guide",
+      title: row.title,
+      description: row.description,
+      content: row.content,
+      contentHash: row.contentHash,
+      revision: row.revision,
+      active: lifecycle === "active",
+      lifecycle,
+      provenance: {
+        source: row.provenanceSource,
+        sourceId: row.provenanceSourceId,
+        trust: row.trust,
+      },
+      relationships,
+      createdAt: row.createdAt.toISOString(),
+    } satisfies CompanyBrainGuidanceEntry;
+  });
+}
+
+function guidanceEntryOrder(
+  left: CompanyBrainGuidanceEntry,
+  right: CompanyBrainGuidanceEntry,
+): number {
+  return (
+    left.classification.localeCompare(right.classification) ||
+    left.path.localeCompare(right.path) ||
+    right.revision - left.revision ||
+    left.revisionId.localeCompare(right.revisionId)
+  );
+}
+
+function relationshipTargetKeys(entry: CompanyBrainGuidanceEntry): string[] {
+  return [entry.id, entry.revisionId];
+}
+
+export function boundCompanyBrainGuidanceEntries(entries: CompanyBrainGuidanceEntry[]): {
+  entries: CompanyBrainGuidanceEntry[];
+  itemCountTruncated: boolean;
+  contentBytesTruncated: boolean;
+} {
+  const prioritized = [...entries].sort(
+    (left, right) => Number(right.active) - Number(left.active) || guidanceEntryOrder(left, right),
+  );
+  const selected: CompanyBrainGuidanceEntry[] = [];
+  let contentBytes = 0;
+  let itemCountTruncated = false;
+  let contentBytesTruncated = false;
+  for (const entry of prioritized) {
+    if (selected.length >= COMPANY_BRAIN_GUIDANCE_MAX_ENTRIES) {
+      itemCountTruncated = true;
+      continue;
+    }
+    const entryBytes = new TextEncoder().encode(entry.content).byteLength;
+    if (contentBytes + entryBytes > COMPANY_BRAIN_GUIDANCE_MAX_CONTENT_BYTES) {
+      contentBytesTruncated = true;
+      continue;
+    }
+    selected.push(entry);
+    contentBytes += entryBytes;
+  }
+  const visibleTargets = new Set(selected.flatMap(relationshipTargetKeys));
+  return {
+    entries: selected
+      .map((entry) => ({
+        ...entry,
+        relationships: entry.relationships.filter((relationship) =>
+          visibleTargets.has(relationship.targetId),
+        ),
+      }))
+      .sort(guidanceEntryOrder),
+    itemCountTruncated,
+    contentBytesTruncated,
+  };
+}
+
+export function createCompanyBrainOkfPackage(input: {
+  workspaceId: string;
+  generatedAt: string;
+  companyProfile: CompanyProfileListResponse;
+  instructionPolicies: WorkspaceInstructionPolicyListResponse;
+  activeInstructionPolicyRevisions: WorkspaceInstructionPolicyRevision[];
+  activatedInstructionPolicyRevisionIds: string[];
+  preferences: CompanyBrainPreferenceGuidancePage;
+  knowledge: WorkspaceStateKnowledge;
+}): CompanyBrainOkfPackageType {
+  const company = companyProfileEntries(input.companyProfile);
+  const policies = instructionPolicyEntries(
+    input.instructionPolicies,
+    input.activeInstructionPolicyRevisions,
+    input.activatedInstructionPolicyRevisionIds,
+  );
+  const preferences = preferenceEntries(input.preferences, input.generatedAt);
+  const truncationReasons: CompanyBrainGuidanceTruncationReason[] = [];
+  if (company.truncated) truncationReasons.push("company_profile_history");
+  if (policies.truncated) truncationReasons.push("instruction_policy_history");
+  if (input.preferences.preferenceCountTruncated) truncationReasons.push("preference_count");
+  if (input.preferences.revisionCountTruncated) truncationReasons.push("preference_history");
+  if (input.preferences.contentBytesTruncated) truncationReasons.push("aggregate_content_bytes");
+
+  const bounded = boundCompanyBrainGuidanceEntries([
+    ...company.entries,
+    ...policies.entries,
+    ...preferences,
+  ]);
+  if (bounded.itemCountTruncated) truncationReasons.push("aggregate_item_count");
+  if (bounded.contentBytesTruncated && !truncationReasons.includes("aggregate_content_bytes")) {
+    truncationReasons.push("aggregate_content_bytes");
+  }
+  const knowledgeAvailable = input.knowledge.availability === "available";
+  return CompanyBrainOkfPackage.parse({
+    kind: "opengeni.company_brain.okf",
+    schemaVersion: 1,
+    workspaceId: input.workspaceId,
+    generatedAt: input.generatedAt,
+    permissions: {
+      guidance: "available",
+      knowledge: knowledgeAvailable ? "available" : "unavailable",
+    },
+    guidance: {
+      entries: bounded.entries,
+      truncated: truncationReasons.length > 0,
+      truncationReasons,
+    },
+    knowledge: input.knowledge,
+    omissions: [
+      ...(knowledgeAvailable ? [] : (["inaccessible_knowledge"] as const)),
+      "document_bodies_use_documents_export",
+      "memory_bodies_and_provenance",
+      "secret_values_and_credentials",
+      "session_messages_and_task_notes",
+      "policy_and_preference_actor_identifiers",
+    ],
+  });
+}
+
+/**
+ * JSON is a strict subset of YAML 1.2. Keeping the payload in one fenced YAML
+ * block gives humans a readable Markdown package while making arbitrary
+ * guidance Markdown structurally inert and exactly round-trippable.
+ */
+export function serializeCompanyBrainOkf(value: CompanyBrainOkfPackageType): string {
+  const parsed = CompanyBrainOkfPackage.parse(value);
+  return [
+    OKF_MARKER,
+    "# Opengeni Company Brain",
+    "",
+    "This permission-filtered package is portable evidence. Postgres remains canonical.",
+    "",
+    "```yaml",
+    canonicalJson(parsed).trimEnd(),
+    "```",
+    "",
+  ].join("\n");
+}
+
+export function parseCompanyBrainOkf(markdown: string): CompanyBrainOkfPackageType {
+  if (!markdown.startsWith(`${OKF_MARKER}\n`)) throw new Error("Invalid Company Brain OKF marker");
+  const opening = markdown.indexOf("```yaml\n");
+  if (opening < 0) throw new Error("Company Brain OKF payload is missing");
+  const payloadStart = opening + "```yaml\n".length;
+  const closing = markdown.indexOf("\n```", payloadStart);
+  if (closing < 0) throw new Error("Company Brain OKF payload is incomplete");
+  const trailing = markdown.slice(closing + "\n```".length).trim();
+  if (trailing.length > 0) throw new Error("Company Brain OKF has unexpected trailing content");
+  return CompanyBrainOkfPackage.parse(JSON.parse(markdown.slice(payloadStart, closing)));
+}