@opengeni/api-router 2.2.0-canary.0 → 2.3.2-canary.0

package/src/auth/organization-user-setup.ts

@@ -0,0 +1,217 @@
+import type { Settings } from "@opengeni/config";
+import type { ManagedEmailTransport } from "@opengeni/core";
+
+const encoder = new TextEncoder();
+
+/**
+ * Prove that the stable invited-user setup bearer can be constructed before an
+ * invitation commits. Provider availability is intentionally outside this
+ * precondition: the durable delivery journal records a failed or ambiguous
+ * transport outcome after the invitation exists.
+ */
+export function assertOrganizationUserSetupDeliveryConfigured(
+  settings: Settings,
+  transport: ManagedEmailTransport,
+): void {
+  requiredSetupSecret(settings);
+  requiredPublicBaseUrl(settings);
+  assertManagedEmailTransportMetadata(transport);
+}
+
+/** Reject an invalid embedded-provider contract before any durable boundary. */
+export function assertManagedEmailTransportMetadata(transport: ManagedEmailTransport): void {
+  if (
+    transport.sender.trim() !== transport.sender ||
+    encoder.encode(transport.sender).byteLength < 3 ||
+    encoder.encode(transport.sender).byteLength > 320
+  ) {
+    throw new Error("Managed email sender is invalid");
+  }
+  const { scope, retentionSeconds } = transport.idempotency;
+  if (
+    scope.trim() !== scope ||
+    !/^[a-z0-9][a-z0-9:._-]*$/.test(scope) ||
+    encoder.encode(scope).byteLength > 200 ||
+    !Number.isInteger(retentionSeconds) ||
+    retentionSeconds < 0 ||
+    retentionSeconds > 31_536_000
+  ) {
+    throw new Error("Managed email idempotency contract is invalid");
+  }
+}
+
+export async function deriveOrganizationUserSetupToken(
+  settings: Settings,
+  input: { invitationId: string; deliveryId: string },
+): Promise<{ token: string; digest: string; url: string }> {
+  const secret = requiredSetupSecret(settings);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(
+      `opengeni:organization-user-setup-delivery:v1:${input.deliveryId}:${input.invitationId}`,
+    ),
+  );
+  const token = base64Url(new Uint8Array(signature));
+  const digest = await sha256Hex(token);
+  const url = new URL("/setup-account", requiredPublicBaseUrl(settings));
+  url.hash = new URLSearchParams({ token }).toString();
+  return { token, digest, url: url.toString() };
+}
+
+export type OrganizationUserSetupEmailSnapshot = {
+  senderEmail: string;
+  recipientEmail: string;
+  recipientName: string | null;
+  organizationName: string;
+  organizationRole: "owner" | "admin" | "member";
+  sharedWorkspaceAccess: Array<{
+    workspaceId: string;
+    workspaceName: string;
+    role: "viewer" | "member" | "admin";
+  }>;
+  setupUrl: string;
+};
+
+export function renderOrganizationUserSetupEmail(input: OrganizationUserSetupEmailSnapshot): {
+  from: string;
+  to: string;
+  subject: string;
+  text: string;
+  html: string;
+} {
+  const greeting = input.recipientName ? `Hi ${input.recipientName},` : "Hello,";
+  const role = titleCase(input.organizationRole);
+  const workspaceSummary =
+    input.sharedWorkspaceAccess.length === 0
+      ? "No shared workspaces are assigned yet."
+      : `Shared workspace access:\n${input.sharedWorkspaceAccess
+          .map((workspace) => `- ${workspace.workspaceName}: ${titleCase(workspace.role)}`)
+          .join("\n")}`;
+  const workspaceHtml =
+    input.sharedWorkspaceAccess.length === 0
+      ? "<p>No shared workspaces are assigned yet.</p>"
+      : `<p>Shared workspace access:</p><ul>${input.sharedWorkspaceAccess
+          .map(
+            (workspace) =>
+              `<li>${escapeHtml(workspace.workspaceName)}: ${escapeHtml(titleCase(workspace.role))}</li>`,
+          )
+          .join("")}</ul>`;
+  return {
+    from: input.senderEmail,
+    to: input.recipientEmail,
+    subject: `Join ${input.organizationName} on OpenGeni`,
+    text: `${greeting}\n\nYou have been invited to ${input.organizationName} as ${role}.\n\n${workspaceSummary}\n\nThis invitation grants only the organization role and shared workspace access listed above. It never shares anyone's Personal workspace.\n\nSet up your account: ${input.setupUrl}\n\nIf you already have an OpenGeni account, sign in and accept the invitation instead.`,
+    html: `<p>${escapeHtml(greeting)}</p><p>You have been invited to <strong>${escapeHtml(input.organizationName)}</strong> as ${escapeHtml(role)}.</p>${workspaceHtml}<p>This invitation grants only the organization role and shared workspace access listed above. It never shares anyone's Personal workspace.</p><p><a href="${escapeHtml(input.setupUrl)}">Set up your account</a></p><p>If you already have an OpenGeni account, sign in and accept the invitation instead.</p>`,
+  };
+}
+
+export async function organizationUserSetupPayloadDigest(input: {
+  from: string;
+  to: string;
+  subject: string;
+  text: string;
+  html: string;
+  providerIdempotencyScope: string;
+}): Promise<string> {
+  return await sha256Hex(
+    JSON.stringify({
+      version: 2,
+      providerIdempotencyScope: input.providerIdempotencyScope,
+      from: input.from,
+      to: input.to,
+      subject: input.subject,
+      text: input.text,
+      html: input.html,
+    }),
+  );
+}
+
+export async function organizationUserSetupRequestFingerprint(
+  settings: Settings,
+  input: { tokenDigest: string; name: string; password: string },
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(requiredSetupSecret(settings)),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(
+      JSON.stringify({
+        tokenDigest: input.tokenDigest,
+        name: input.name,
+        password: input.password,
+      }),
+    ),
+  );
+  return hex(new Uint8Array(signature));
+}
+
+export async function selfServiceOrganizationSetupRequestFingerprint(input: {
+  authUserId: string;
+  organizationName: string;
+}): Promise<string> {
+  const actorSubjectId = `user:${input.authUserId}`;
+  const organizationNameBytes = encoder.encode(input.organizationName);
+  return await sha256Hex(
+    `opengeni:self-service-organization:v1:${actorSubjectId}:${organizationNameBytes.byteLength}:${input.organizationName}`,
+  );
+}
+
+export async function organizationUserSetupTokenDigest(token: string): Promise<string> {
+  return await sha256Hex(token);
+}
+
+function requiredSetupSecret(settings: Settings): string {
+  if (!settings.betterAuthSecret) {
+    throw new Error("OPENGENI_BETTER_AUTH_SECRET is required for organization user setup");
+  }
+  return settings.betterAuthSecret;
+}
+
+function requiredPublicBaseUrl(settings: Settings): string {
+  if (!settings.publicBaseUrl) {
+    throw new Error("OPENGENI_PUBLIC_BASE_URL is required for organization user setup");
+  }
+  return settings.publicBaseUrl;
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(value));
+  return hex(new Uint8Array(digest));
+}
+
+function hex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function base64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+
+function titleCase(value: string): string {
+  return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}

package/src/http/auth.ts

@@ -5,6 +5,8 @@ import { installExactPaths, isInstallRedirectPath } from "../routes/install";
 
 const githubConnectPathPattern = /^\/v1\/workspaces\/[^/]+\/github\/connect$/;
 const githubInstallationLinkPathPattern = /^\/v1\/workspaces\/[^/]+\/github\/installations$/;
+const prReviewGithubBrowserPathPattern =
+  /^\/v1\/workspaces\/[^/]+\/pr-review\/github\/(?:connect|installations\/select|installations\/[^/]+\/configure)$/;
 
 export function requireAccessKey(settings: Settings): MiddlewareHandler {
   return async (c, next) => {
@@ -43,6 +45,9 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (c.req.method === "POST" && path.startsWith("/v1/webhooks/automations/")) {
     return true;
   }
+  if (c.req.method === "POST" && path === "/v1/webhooks/pr-review/github") {
+    return true;
+  }
   if (
     path === "/v1/github/setup" ||
     path === "/v1/github/install/callback" ||
@@ -51,6 +56,13 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   ) {
     return true;
   }
+  if (
+    path === "/v1/pr-review/github/setup" ||
+    path === "/v1/pr-review/github/install/callback" ||
+    path === "/v1/pr-review/github/oauth/callback"
+  ) {
+    return true;
+  }
   if (
     path === "/v1/integrations/oauth/callback" ||
     path === "/v1/integrations/provider-oauth/callback" ||
@@ -83,6 +95,9 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (githubConnectPathPattern.test(path)) {
     return true;
   }
+  if (prReviewGithubBrowserPathPattern.test(path)) {
+    return true;
+  }
   // Compatibility endpoint for stale chooser submissions. It remains public
   // only so already-rendered forms can authenticate their signed account and
   // workspace state locally before terminating with 410; it does not parse a

package/src/http/sse.ts

@@ -13,6 +13,7 @@ import {
   coalesceSessionEventDeltas,
   formatSessionEventSse,
   formatWorkspaceControlEventSse,
+  requireSessionEventDurableFanoutCapability,
   SESSION_EVENT_SSE_FRAME_MAX_BYTES,
   sessionEventResumeSequence,
   type EventBus,
@@ -269,12 +270,14 @@ export async function sseSessionStream(
   signal: AbortSignal,
   options: SessionSseDeliveryOptions = {},
 ): Promise<Response> {
+  const durableFanout = requireSessionEventDurableFanoutCapability(bus);
   const heartbeatIntervalMs = resolveHeartbeatInterval(options.heartbeatIntervalMs);
   let lastSent = after;
   let bootstrapping = true;
   let newestBuffered: SessionEvent | null = null;
   let unsubscribe: (() => void) | null = null;
   let delivery: LatestWinsDelivery<SessionEvent> | null = null;
+  let stopReconnectObservation = () => {};
   let stopReauthorization = () => {};
   let heartbeatTimer: ReturnType<typeof setTimeout> | null = null;
   let detachAbortListener = () => {};
@@ -282,6 +285,8 @@ export async function sseSessionStream(
   const stopUpstream = () => {
     closeMetrics();
     detachAbortListener();
+    stopReconnectObservation();
+    stopReconnectObservation = () => {};
     stopReauthorization();
     if (heartbeatTimer) {
       clearTimeout(heartbeatTimer);
@@ -316,17 +321,6 @@ export async function sseSessionStream(
     writeTail = write.catch(() => {});
     return write;
   };
-  const scheduleHeartbeat = () => {
-    if (channel.stopped()) return;
-    heartbeatTimer = setTimeout(() => {
-      heartbeatTimer = null;
-      void writeFrame(": heartbeat\n\n")
-        .then(scheduleHeartbeat)
-        .catch((error) => {
-          if (!(error instanceof SseStreamStoppedError)) fail(error);
-        });
-    }, heartbeatIntervalMs);
-  };
   const deliverDurableThrough = async (targetSequence?: number) => {
     while (true) {
       if (targetSequence !== undefined && lastSent >= targetSequence) return;
@@ -364,12 +358,66 @@ export async function sseSessionStream(
       if (targetSequence === undefined && page.length < limit) return;
     }
   };
+  let durableDeliveryTail = Promise.resolve();
+  const reconcileDurableThrough = (targetSequence?: number): Promise<void> => {
+    const deliveryRun = durableDeliveryTail.then(() => deliverDurableThrough(targetSequence));
+    durableDeliveryTail = deliveryRun.catch(() => {});
+    return deliveryRun;
+  };
+  let newestReconnectGeneration = 0;
+  let reconnectReconcilePending = false;
+  let reconnectReconcileRunning = false;
+  const drainReconnectReconciliation = () => {
+    if (
+      bootstrapping ||
+      reconnectReconcileRunning ||
+      !reconnectReconcilePending ||
+      channel.stopped()
+    ) {
+      return;
+    }
+    reconnectReconcileRunning = true;
+    void (async () => {
+      while (reconnectReconcilePending && !channel.stopped()) {
+        // Multiple reconnects during one durable read collapse into one newest
+        // catch-up. Postgres is authoritative, so that later read covers every
+        // disconnect window without one query per heartbeat or buffered event.
+        reconnectReconcilePending = false;
+        await reconcileDurableThrough();
+      }
+    })()
+      .catch((error) => {
+        if (!(error instanceof SseStreamStoppedError)) fail(error);
+      })
+      .finally(() => {
+        reconnectReconcileRunning = false;
+        drainReconnectReconciliation();
+      });
+  };
+  const scheduleReconnectReconciliation = (generation: number) => {
+    if (generation <= newestReconnectGeneration || channel.stopped()) return;
+    newestReconnectGeneration = generation;
+    reconnectReconcilePending = true;
+    drainReconnectReconciliation();
+  };
   const send = async (event: SessionEvent) => {
     const targetSequence = sessionEventResumeSequence(event);
     if (targetSequence <= lastSent) return;
-    await deliverDurableThrough(targetSequence);
+    await reconcileDurableThrough(targetSequence);
+  };
+  const scheduleHeartbeat = () => {
+    if (channel.stopped()) return;
+    heartbeatTimer = setTimeout(() => {
+      heartbeatTimer = null;
+      void writeFrame(": heartbeat\n\n")
+        .then(scheduleHeartbeat)
+        .catch((error) => {
+          if (!(error instanceof SseStreamStoppedError)) fail(error);
+        });
+    }, heartbeatIntervalMs);
   };
   delivery = createLatestWinsDelivery(send, fail);
+  stopReconnectObservation = durableFanout.subscribeRecovery(scheduleReconnectReconciliation);
 
   void (async () => {
     const release = await bus.subscribe(workspaceId, sessionId, (events) => {
@@ -389,10 +437,11 @@ export async function sseSessionStream(
     }
     unsubscribe = release;
 
-    await deliverDurableThrough();
+    await reconcileDurableThrough();
     await writeFrame(": connected\n\n");
     scheduleHeartbeat();
     bootstrapping = false;
+    drainReconnectReconciliation();
     const buffered = newestBuffered;
     newestBuffered = null;
     if (buffered) delivery.publish([buffered]);

package/src/integrations/slack-app-home.ts

@@ -1,4 +1,4 @@
-import type { Session } from "@opengeni/contracts";
+import { AUTOMATIC_SESSION_TITLE_FALLBACK, type Session } from "@opengeni/contracts";
 import type { SlackHomeBlock } from "./slack-bot";
 
 const ATTENTION_LIMIT = 5;
@@ -186,7 +186,7 @@ function appendSessionGroup(
   );
   for (const session of sessions) {
     const url = sessionUrl(session.id);
-    const title = (session.title || session.initialMessage || "Untitled task").slice(0, 180);
+    const title = (session.title?.trim() || AUTOMATIC_SESSION_TITLE_FALLBACK).slice(0, 180);
     blocks.push({
       type: "section",
       block_id: `opengeni_home_session_${session.id}`,

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

@@ -125,7 +125,7 @@ export function registerCompanyBrainGovernedWriteTools(
     {
       description:
         "Atomically promote one still-active note from this exact root task tree into an inactive workspace instruction-policy draft. The note bytes remain exact evidence and draft content. " +
-        `Once a human activates the draft, those bytes are composed verbatim into the prompt of every session the target applies to, so a note over ${AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters is rejected here rather than truncated: write a fresh short imperative note instead of promoting a long working note. ` +
+        `Use this only for a universal always-on rule, never for an incident, fact, decision, outcome, or conditional procedure. Once a human activates the draft, those bytes are composed verbatim into the prompt of every session the target applies to, so a note over ${AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters is rejected here rather than truncated: write a fresh minimal imperative note instead of promoting a long working note. ` +
         "The frozen learning policy records a decision receipt, but mandatory policy still requires human activation even under Automatic; this never widens scope.",
       inputSchema: {
         ...taskNotePromotion,
@@ -149,7 +149,7 @@ export function registerCompanyBrainGovernedWriteTools(
     "task_note_promote_preference",
     {
       description:
-        "Atomically promote one still-active note from this exact root task tree into a workspace preference proposal. The note bytes remain exact evidence and full proposal content. " +
+        "Atomically promote one still-active note from this exact root task tree into a workspace Skill proposal backed by the structured preference authority. Use this for reusable conditional how-to guidance, never for an incident, fact, decision, outcome, or universal always-on rule. The note bytes remain exact evidence and full proposal content. " +
         `The title and description you supply are what gets composed into every session prompt, so write them as one short imperative statement; the note content is retrieved on demand and a note over ${AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS} characters is rejected here rather than truncated. ` +
         "Under Suggest the proposal waits for human review; under Automatic an eligible decision is activated through the preference lifecycle and remains undoable. This never widens scope.",
       inputSchema: {
@@ -186,7 +186,7 @@ export function registerCompanyBrainGovernedWriteTools(
     {
       description:
         "Materialize an evidence-backed inactive workspace instruction-policy draft. " +
-        `Once a human activates it, this content is composed verbatim into the prompt of every session the target applies to (every session in this workspace for a global charter or policy, every session bound to the role for a role policy), so keep it under ${AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters. ${AGENT_AUTHORED_DURABLE_TEXT_STYLE} ` +
+        `Use this only for a minimal universal rule, never for an incident, fact, decision, outcome, or conditional procedure. Once a human activates it, this content is composed verbatim into the prompt of every session the target applies to (every session in this workspace for a global charter or policy, every session bound to the role for a role policy), so keep it under ${AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters. ${AGENT_AUTHORED_DURABLE_TEXT_STYLE} ` +
         "The frozen learning policy records a decision receipt, but this tool cannot activate mandatory behavior, including when learning mode is Automatic; a human must activate the draft.",
       inputSchema: {
         ...evidence,
@@ -219,7 +219,7 @@ export function registerCompanyBrainGovernedWriteTools(
     "preference_propose",
     {
       description:
-        "Materialize an evidence-backed workspace preference proposal. " +
+        "Materialize an evidence-backed workspace Skill proposal in the structured preference authority. Use this only for reusable conditional how-to guidance, never for an incident, fact, decision, outcome, or universal always-on rule. " +
         `Its short title and description are what get composed into every session prompt; the content is retrieved on demand, so its length is retrieval cost rather than standing prompt cost. Keep the content under ${AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS} characters. ${AGENT_AUTHORED_DURABLE_TEXT_STYLE} ` +
         "Under Suggest it stays inactive for human review; under Automatic an eligible decision is activated through the governed preference lifecycle with an undoable receipt. It never creates mandatory authority.",
       inputSchema: {

package/src/mcp/company-profile-agent-admin.ts

@@ -1,10 +1,8 @@
 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,
   AgentAuthoredCompanyProfileContent,
-  COMPANY_PROFILE_ENTRY_MAX_COUNT,
   COMPANY_PROFILE_REASON_MAX_CHARS,
   COMPANY_PROFILE_STABLE_KEY_MAX_CHARS,
   normalizeCompanyProfileStableKey,
@@ -32,9 +30,9 @@ export type RegisterCompanyProfileAgentAdminToolsInput = {
   router?: Pick<ReturnType<typeof createCompanyProfileAgentAdminRouter>, "propose" | "confirm">;
 };
 
-// Agent-only bounds. The human `account:admin` route keeps the wider
-// `COMPANY_PROFILE_*` limits; this profile is the largest always-on prompt
-// surface in the product, so an agent gets a much smaller budget for it.
+// Agent-only bounds. The human `account:admin` API keeps the wider historical
+// `COMPANY_PROFILE_*` limits; the current agent tool authors only the two
+// always-on identity fields and therefore gets a much smaller budget.
 const scalar = z
   .string()
   .trim()
@@ -55,8 +53,7 @@ const entry = z.object({
       AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE,
     ),
 });
-const entries = z.array(entry).max(COMPANY_PROFILE_ENTRY_MAX_COUNT);
-const DEFAULT_PROPOSAL_REASON = "Activate agent-proposed organization company profile";
+const DEFAULT_PROPOSAL_REASON = "Activate agent-proposed organization identity";
 const STABLE_KEY_WORDS = 6;
 
 type EntryInput = z.infer<typeof entry>;
@@ -127,18 +124,14 @@ export function registerCompanyProfileAgentAdminTools(
     "company_profile_propose",
     {
       description:
-        "Prepare one complete organization company profile covering identity, mission, products, customers, strategic goals, and critical constraints. Omitted list keys are derived from content. " +
-        "Once activated, every field here is mandatory prompt context in every session for the whole organization, so write it as a concise profile rather than a document: one plain descriptive statement per field, no numbered procedure and no marketing copy. Longer source material belongs in organization Documents and is retrieved as evidence; never copy it into the profile. " +
-        `Bounds for this tool are ${AGENT_AUTHORED_COMPANY_PROFILE_SCALAR_MAX_CHARS} characters for identity and mission, ${AGENT_AUTHORED_COMPANY_PROFILE_ENTRY_MAX_CHARS} per list entry, ${COMPANY_PROFILE_ENTRY_MAX_COUNT} entries per list, and ${AGENT_AUTHORED_COMPANY_PROFILE_CONTENT_MAX_UTF8_BYTES} UTF-8 bytes for the whole profile. ` +
+        "Prepare the organization's small, stable identity: identity says who the organization is, and mission says why it exists. " +
+        "Once activated, both fields are mandatory prompt context in every root session for the whole organization, so use one plain descriptive statement per field with no products, customers, goals, constraints, procedures, or marketing copy. Those details belong in organization-scoped Documents and are retrieved only when relevant. " +
+        `Each field is bounded to ${AGENT_AUTHORED_COMPANY_PROFILE_SCALAR_MAX_CHARS} characters for agent-authored proposals. ` +
         "This creates only an immutable inactive proposal for the exact live turn initiated by the organization owner and does not use workspace learning policy. The receipt returns the exact `humanInput` payload; call `request_human_input` with it verbatim, then call `company_profile_confirm` with the returned requestId.",
       inputSchema: {
         operationId: z.string().uuid(),
         identity: scalar,
         mission: scalar,
-        products: entries,
-        customers: entries,
-        goals: entries,
-        constraints: entries,
         reason: z.string().trim().min(1).max(COMPANY_PROFILE_REASON_MAX_CHARS).optional(),
       },
     },
@@ -147,10 +140,10 @@ export function registerCompanyProfileAgentAdminTools(
       const parsed = AgentAuthoredCompanyProfileContent.safeParse({
         identity: request.identity,
         mission: request.mission,
-        products: resolveCompanyProfileEntries(request.products),
-        customers: resolveCompanyProfileEntries(request.customers),
-        goals: resolveCompanyProfileEntries(request.goals),
-        constraints: resolveCompanyProfileEntries(request.constraints),
+        products: [],
+        customers: [],
+        goals: [],
+        constraints: [],
       });
       if (!parsed.success) {
         return input.json({

package/src/mcp/remember.ts

@@ -70,9 +70,9 @@ export function registerRememberTools(input: RegisterRememberToolsInput): void {
     "remember",
     {
       description:
-        "Durably remember something the user explicitly asked to keep for this workspace. Use lane=preference for how agents should act, lane=instruction_policy only when the user stated a hard always/never rule, lane=knowledge for a company/product/people fact. " +
-        `Write it short. A lane=instruction_policy rule is composed verbatim into the prompt of every session it applies to (every session in this workspace for a global rule, every session bound to the role for a role rule) for as long as it stays active, so keep it under ${AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters: one imperative rule in 1-3 sentences, no numbered steps, no examples, no rationale, no restating of defaults. At most three rules compose at once, so this is a standing budget you share. Keep a lane=preference under ${AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS} characters; there only its short title and description are composed and the content is retrieved on demand, so length is retrieval cost rather than standing prompt cost. Prefer several small entries over one long one, and put procedure in a Document or Skill that the rule references instead of inlining it. ` +
-        "Under Automatic learning a preference activates immediately; otherwise the receipt returns status=confirmation_required with the exact `humanInput` payload: call `request_human_input` with it verbatim, then call `remember_confirm` with the returned requestId. Mandatory rules always need that confirmation. Do not use this for facts you merely inferred; use knowledge_propose or task notes for those. A confirmed lane=knowledge fact enters the human-reviewed Knowledge claim lifecycle; it does not become workspace memory, so do not expect to find it later through `memory_search`.",
+        "Durably remember something the user explicitly asked to keep for this workspace. Route by purpose: lane=knowledge for a fact, decision, incident, bug fix, or outcome that should become searchable Memory; lane=preference creates a Skill for reusable conditional how-to guidance; lane=instruction_policy is only for a universal always/never rule that should apply to nearly every task. " +
+        `Write the instruction lane as the shortest complete rule, at most ${AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters and normally 1-3 imperative sentences, with no numbered steps, examples, rationale, or restated defaults. Keep a Skill under ${AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS} characters; only its one-sentence descriptor is composed and the full instructions are retrieved on demand. Do not copy one item into multiple lanes. ` +
+        "Under Automatic learning a Skill may activate immediately; otherwise the receipt returns status=confirmation_required with the exact `humanInput` payload: call `request_human_input` with it verbatim, then call `remember_confirm` with the returned requestId. Workspace instructions and Memory always need that confirmation. Do not use this for facts you merely inferred; use knowledge_propose or task notes for those. Confirmed lane=knowledge content keeps its reviewed claim provenance and materializes its exact approved text into Memory for later `memory_search` retrieval.",
       inputSchema: {
         lane: z.enum(["preference", "instruction_policy", "knowledge"]),
         ...laneFields,
@@ -130,7 +130,7 @@ export function registerRememberTools(input: RegisterRememberToolsInput): void {
     "remember_confirm",
     {
       description:
-        "Complete a `remember` that returned status=confirmation_required after the human answered the bound `request_human_input` question. For preference/instruction_policy pass proposalId and learning.receiptId (as decisionReceiptId) from that receipt; for knowledge pass claimId. Always pass the requestId returned by request_human_input. Activation only succeeds when the exact initiating human answered Save on this turn; otherwise the proposal stays for review.",
+        "Complete a `remember` that returned status=confirmation_required after the human answered the bound `request_human_input` question. For preference/instruction_policy pass proposalId and learning.receiptId (as decisionReceiptId) from that receipt; for knowledge pass claimId. Always pass the requestId returned by request_human_input. Activation only succeeds when the exact initiating human answered Save on this turn; confirmed knowledge is materialized into searchable Memory from the exact approved text.",
       inputSchema: {
         operationId: z.string().uuid(),
         proposalId: z.string().uuid().optional(),

package/src/mcp/server.ts

@@ -38,6 +38,7 @@ import {
   SESSION_GOAL_SUCCESS_CRITERIA_MAX_BYTES,
   SESSION_GOAL_TEXT_MAX_BYTES,
   SESSION_INSTRUCTIONS_MAX_CHARACTERS,
+  MAX_SELECTED_VARIABLE_SETS,
   sessionGoalUtf8Bytes,
   TASK_NOTE_LIST_DEFAULT_LIMIT,
   TASK_NOTE_LIST_MAX_LIMIT,
@@ -755,7 +756,7 @@ export function buildOpenGeniMcpServer(
       "set_session_title",
       {
         description:
-          "Set this session's display title to a concise 3-7 word summary. The title persists across turns: call once on a new untitled session, then only when the topic materially changes. Never call it as routine setup after a continuation, resume, or interruption, or merely to reassert the same title. A human-set title cannot be replaced.",
+          "Set this session's display title to a concise 3-7 word topic label. Use a stable noun phrase about the actual task or subject, never a quote/prefix of a prompt, greeting, request boilerplate, URL, identifier, credential, token, or other sensitive value. Call once on a new session, then only when the topic materially changes. Never call it as routine setup after a continuation, resume, or interruption, or merely to reassert the same title. A human-set title cannot be replaced.",
         inputSchema: { title: z4.string().min(1).max(200) },
       },
       async ({ title }) => {
@@ -3256,7 +3257,7 @@ function registerPreferenceRegistryTools(
     "preference_registry_summary",
     {
       description:
-        "List bounded deterministic descriptors for organization, workspace, and immutable initiating-human preferences frozen to this exact attempt. Full content is omitted; retrieve only a relevant returned handle.",
+        "List bounded deterministic Skill descriptors for organization, workspace, and the immutable initiating human, frozen to this exact attempt. Full Skill instructions are omitted; retrieve only a relevant returned handle.",
       inputSchema: {},
     },
     async () => json(await getOrCreatePreferenceRegistrySnapshot(deps.db, attemptClaims())),
@@ -3266,7 +3267,7 @@ function registerPreferenceRegistryTools(
     "preference_registry_get",
     {
       description:
-        "Retrieve full content for one preference in this exact attempt snapshot. Handles from another account, workspace, human, or attempt are rejected.",
+        "Retrieve the full instructions for one Skill in this exact attempt snapshot. Handles from another account, workspace, human, or attempt are rejected.",
       inputSchema: { retrievalHandle: z4.string().min(1).max(512) },
     },
     async ({ retrievalHandle }) =>
@@ -4295,6 +4296,7 @@ function registerWorkspaceOrchestrationTools(
         tools: z4.array(z4.unknown()).optional(),
         mcpServers: z4.array(z4.unknown()).optional(),
         variableSetId: z4.string().uuid().optional(),
+        variableSetIds: z4.array(z4.string().uuid()).max(MAX_SELECTED_VARIABLE_SETS).optional(),
         environmentId: z4.string().uuid().optional(),
         rigId: z4.string().uuid().optional(),
         model: z4
@@ -4345,6 +4347,26 @@ function registerWorkspaceOrchestrationTools(
           .union([z4.literal("new"), z4.object({ groupId: z4.string().uuid() })])
           .optional(),
       })
+      .superRefine((value, context) => {
+        if (!value.variableSetIds) return;
+        if (new Set(value.variableSetIds).size !== value.variableSetIds.length) {
+          context.addIssue({
+            code: z4.ZodIssueCode.custom,
+            path: ["variableSetIds"],
+            message: "variableSetIds must not contain duplicates",
+          });
+        }
+        const singular = value.variableSetId ?? value.environmentId;
+        if (singular === undefined) return;
+        const expected = value.variableSetIds[value.variableSetIds.length - 1];
+        if (singular !== expected) {
+          context.addIssue({
+            code: z4.ZodIssueCode.custom,
+            path: ["variableSetId"],
+            message: "variableSetId must match the last variableSetIds entry",
+          });
+        }
+      })
       .strict();
     server.registerTool(
       "session_create",
@@ -4355,6 +4377,11 @@ function registerWorkspaceOrchestrationTools(
       },
       async (args) => {
         try {
+          requireVariableSetsUseForMcpAttachments(grant, {
+            variableSetIds: args.variableSetIds,
+            variableSetId: args.variableSetId,
+            environmentId: args.environmentId,
+          });
           if (callerSessionId !== null) {
             await authorizeFirstPartySession(deps, grant, callerSessionId, "session.child.create");
           }
@@ -4744,7 +4771,7 @@ function registerWorkspaceOrchestrationTools(
       "set_other_session_title",
       {
         description:
-          "Set another session's display title to a concise 3-7 word summary. The target session must belong to this workspace. Replaces an existing title unless a human has manually set it.",
+          "Set another session's display title to a concise 3-7 word topic label. Use a stable noun phrase about the actual task or subject, never a quote/prefix of a prompt, greeting, request boilerplate, URL, identifier, credential, token, or other sensitive value. The target session must belong to this workspace. Replaces an existing automatic title unless a human has manually set it.",
         inputSchema: {
           session_id: z4.string().uuid(),
           title: z4.string().min(1).max(200),
@@ -5342,6 +5369,25 @@ function requireVariableSetsUseForMcpAttachment(
   }
 }
 
+function requireVariableSetsUseForMcpAttachments(
+  grant: AccessGrant,
+  selection: {
+    variableSetIds?: string[] | undefined;
+    variableSetId?: string | undefined;
+    environmentId?: string | undefined;
+  },
+): void {
+  const singular = selection.variableSetId ?? selection.environmentId;
+  const variableSetIds = selection.variableSetIds ?? (singular ? [singular] : undefined);
+  if (variableSetIds === undefined) return;
+  if (!hasPermission(grant.permissions, "variable-sets:attach")) {
+    throw new HTTPException(403, { message: "missing permission: variable-sets:attach" });
+  }
+  if (variableSetIds.length > 0 && !hasPermission(grant.permissions, "variable-sets:use")) {
+    throw new HTTPException(403, { message: "missing permission: variable-sets:use" });
+  }
+}
+
 /**
  * Project one allowlisted GitHub App repository into the resource an agent or
  * scheduled task attaches. Every listed repository is in the workspace