@opengeni/api-router 2.5.0 → 2.6.4

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

@@ -1,9 +1,10 @@
 import {
-  AGENT_AUTHORED_DURABLE_TEXT_STYLE,
   AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
   AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
+  AGENT_AUTHORED_INSTRUCTION_POLICY_STYLE,
   AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
   AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
+  AGENT_AUTHORED_SKILL_STYLE,
   PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS,
   PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS,
   PREFERENCE_REGISTRY_TITLE_MAX_CHARS,
@@ -11,7 +12,7 @@ import {
   type CompanyBrainGovernedWriteAttempt,
 } from "@opengeni/contracts";
 import { createCompanyBrainLearningPolicyRouter } from "@opengeni/core";
-import type { Database } from "@opengeni/db";
+import { PreferenceRegistryStableKeyConflictError, type Database } from "@opengeni/db";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod/v4";
 
@@ -66,6 +67,20 @@ export function registerCompanyBrainGovernedWriteTools(
   input: RegisterCompanyBrainGovernedWriteToolsInput,
 ): void {
   const router = input.router ?? createCompanyBrainLearningPolicyRouter({ db: input.db });
+  const writeResult = async (write: () => ReturnType<typeof router.write>) => {
+    try {
+      return input.json(await write());
+    } catch (error) {
+      if (error instanceof PreferenceRegistryStableKeyConflictError) {
+        return input.json({
+          status: "not_proposed",
+          code: "preference_stable_key_conflict",
+          message: error.message,
+        });
+      }
+      throw error;
+    }
+  };
   input.server.registerTool(
     "knowledge_propose",
     {
@@ -75,8 +90,8 @@ export function registerCompanyBrainGovernedWriteTools(
     },
     async (request) => {
       await input.authorize();
-      return input.json(
-        await router.write({
+      return writeResult(() =>
+        router.write({
           attempt: input.attempt,
           request: { kind: "propose_knowledge", ...request },
         }),
@@ -93,8 +108,8 @@ export function registerCompanyBrainGovernedWriteTools(
     },
     async (request) => {
       await input.authorize();
-      return input.json(
-        await router.write({
+      return writeResult(() =>
+        router.write({
           attempt: input.attempt,
           request: { kind: "correct_knowledge", ...request },
         }),
@@ -111,8 +126,8 @@ export function registerCompanyBrainGovernedWriteTools(
     },
     async (request) => {
       await input.authorize();
-      return input.json(
-        await router.write({
+      return writeResult(() =>
+        router.write({
           attempt: input.attempt,
           request: { kind: "promote_task_note_knowledge", ...request },
         }),
@@ -124,9 +139,9 @@ export function registerCompanyBrainGovernedWriteTools(
     "task_note_promote_instruction_policy",
     {
       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. " +
-        `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.",
+        "Atomically promote one still-active note from this exact root task tree into a workspace instruction-policy proposal. The note bytes remain exact evidence and draft content. " +
+        `Use this only for a universal always-on rule, never for an incident, fact, decision, outcome, or conditional procedure. Once active, 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. ` +
+        "Off creates nothing; Review first keeps the proposal inactive; Autonomous may activate an eligible proposal through the governed instruction lifecycle with an undoable receipt. This never widens scope.",
       inputSchema: {
         ...taskNotePromotion,
         target: WorkspaceInstructionPolicyTarget,
@@ -136,8 +151,8 @@ export function registerCompanyBrainGovernedWriteTools(
     },
     async (request) => {
       await input.authorize();
-      return input.json(
-        await router.write({
+      return writeResult(() =>
+        router.write({
           attempt: input.attempt,
           request: { kind: "promote_task_note_instruction_policy", ...request },
         }),
@@ -172,8 +187,8 @@ export function registerCompanyBrainGovernedWriteTools(
     },
     async (request) => {
       await input.authorize();
-      return input.json(
-        await router.write({
+      return writeResult(() =>
+        router.write({
           attempt: input.attempt,
           request: { kind: "promote_task_note_preference", ...request },
         }),
@@ -185,9 +200,9 @@ export function registerCompanyBrainGovernedWriteTools(
     "instruction_policy_propose",
     {
       description:
-        "Materialize an evidence-backed inactive workspace instruction-policy draft. " +
-        `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.",
+        "Materialize an evidence-backed workspace instruction-policy proposal. " +
+        `Use this only for a minimal universal rule, never for an incident, fact, decision, outcome, or conditional procedure. Once active, 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_INSTRUCTION_POLICY_STYLE} ` +
+        "Off creates nothing; Review first keeps the proposal inactive; Autonomous may activate an eligible proposal through the governed instruction lifecycle with an undoable receipt.",
       inputSchema: {
         ...evidence,
         target: WorkspaceInstructionPolicyTarget,
@@ -206,8 +221,8 @@ export function registerCompanyBrainGovernedWriteTools(
     },
     async (request) => {
       await input.authorize();
-      return input.json(
-        await router.write({
+      return writeResult(() =>
+        router.write({
           attempt: input.attempt,
           request: { kind: "propose_instruction_policy", ...request },
         }),
@@ -220,7 +235,7 @@ export function registerCompanyBrainGovernedWriteTools(
     {
       description:
         "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} ` +
+        `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_SKILL_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: {
         ...evidence,
@@ -251,8 +266,8 @@ export function registerCompanyBrainGovernedWriteTools(
     },
     async (request) => {
       await input.authorize();
-      return input.json(
-        await router.write({
+      return writeResult(() =>
+        router.write({
           attempt: input.attempt,
           request: { kind: "propose_preference", ...request },
         }),

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

@@ -109,12 +109,12 @@ function boundedIssueMessage(error: z.ZodError): string {
 }
 
 /**
- * Register the explicit owner-confirmed organization profile path. This is
- * administration, not derived learning: workspace learning mode is never
- * consulted, the initiating human must be the organization's active owner (the
- * same authority as the manual `account:admin` route), and the proposal cannot
- * become active without the exact bound human-input response returned by the
- * first call.
+ * Register the organization profile administration path. This is not derived
+ * workspace learning: the initiating human must be the organization's active
+ * owner (the same authority as the manual `account:admin` route). The separate
+ * organization policy either blocks the proposal, keeps the exact bound
+ * human-confirmation path, or permits immediate activation through the native
+ * company-profile lifecycle.
  */
 export function registerCompanyProfileAgentAdminTools(
   input: RegisterCompanyProfileAgentAdminToolsInput,
@@ -127,7 +127,7 @@ export function registerCompanyProfileAgentAdminTools(
         "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.",
+        "This is independent of workspace learning policy and follows the organization owner's Agent-managed identity mode. Off creates nothing. Review first returns status=confirmation_required with the exact `humanInput` payload; call `request_human_input` with it verbatim, then call `company_profile_confirm` with the returned requestId. Autonomous may return status=activated immediately after exact live-owner, stale-head, and compare-and-swap checks; do not ask for another confirmation in that case.",
       inputSchema: {
         operationId: z.string().uuid(),
         identity: scalar,

package/src/mcp/remember.ts

@@ -11,7 +11,7 @@ import {
   type RememberLane,
 } from "@opengeni/contracts";
 import { RememberError, createRememberRouter } from "@opengeni/core";
-import type { Database } from "@opengeni/db";
+import { PreferenceRegistryStableKeyConflictError, type Database } from "@opengeni/db";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod/v4";
 
@@ -59,7 +59,7 @@ const laneFields = {
 /**
  * Explicit user-directed remember. Content becomes exact task-note evidence,
  * promotion runs through the frozen workspace learning policy, and activation
- * is either automatic (preference under Automatic mode) or requires exactly one
+ * is either automatic (Skill or instruction under Automatic mode) or requires exactly one
  * bound human confirmation through the built-in `request_human_input` tool.
  * Tool input cannot select scope beyond the workspace, active authority, or
  * another learning-policy source.
@@ -70,9 +70,9 @@ export function registerRememberTools(input: RegisterRememberToolsInput): void {
     "remember",
     {
       description:
-        "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.",
+        "Create governed durable knowledge, a Skill, or a mandatory workspace instruction. When the agent-only memory_save tool is available, use it instead for ordinary durable facts, decisions, incidents, bug fixes, and confirmed outcomes; those Memory writes are autonomous and independent of Learning mode. Use lane=knowledge only when memory_save is unavailable and the user explicitly requests reviewed workspace knowledge; 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 with one clear trigger and outcome, only the necessary steps, checks, and exceptions, and a one-sentence descriptor. Do not copy one item into multiple lanes. ` +
+        "Under Autonomous learning, an eligible Skill or workspace instruction may activate immediately through its governed lifecycle. Under Review first, it remains inactive and 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. Off creates no governed change. Reviewed Knowledge always needs confirmation. Do not use lane=knowledge for facts you merely inferred; use memory_save when available, otherwise knowledge_propose or task notes. 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,
@@ -120,9 +120,20 @@ export function registerRememberTools(input: RegisterRememberToolsInput): void {
           : lane === "instruction_policy"
             ? { ...base, lane, target: request.target }
             : { ...base, lane, subject: request.subject ?? content.slice(0, 80) };
-      return input.json(
-        await router.remember({ attempt: input.attempt, request: rememberRequest }),
-      );
+      try {
+        return input.json(
+          await router.remember({ attempt: input.attempt, request: rememberRequest }),
+        );
+      } catch (error) {
+        if (error instanceof PreferenceRegistryStableKeyConflictError) {
+          return input.json({
+            status: "not_remembered",
+            code: "preference_stable_key_conflict",
+            message: error.message,
+          });
+        }
+        throw error;
+      }
     },
   );