@opengeni/api-router 2.13.0-canary.0 → 2.13.0-canary.2

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

@@ -1,271 +0,0 @@
-import {
-  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,
-  PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS,
-  PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS,
-  PREFERENCE_REGISTRY_TITLE_MAX_CHARS,
-  WorkspaceInstructionPolicyTarget,
-  type CompanyBrainGovernedWriteAttempt,
-} from "@opengeni/contracts";
-import { createCompanyBrainLearningPolicyRouter } from "@opengeni/core";
-import { PreferenceRegistryStableKeyConflictError, type Database } from "@opengeni/db";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import * as z from "zod/v4";
-
-type JsonResult = (value: unknown) => {
-  content: { type: "text"; text: string }[];
-};
-
-const reason = z.string().trim().min(1).max(4_096);
-const evidence = {
-  operationId: z.string().uuid(),
-  claimId: z.string().uuid(),
-  evidenceId: z.string().uuid(),
-};
-const taskNotePromotion = {
-  operationId: z.string().uuid(),
-  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,
-};
-
-export type RegisterCompanyBrainGovernedWriteToolsInput = {
-  server: McpServer;
-  db: Database;
-  attempt: CompanyBrainGovernedWriteAttempt;
-  authorize: () => Promise<void>;
-  json: JsonResult;
-  router?: Pick<ReturnType<typeof createCompanyBrainLearningPolicyRouter>, "write">;
-};
-
-/**
- * Register explicit proposal-only Company Brain tools. The signed host attempt
- * owns tenant/session authority and the exact evidence id owns the learning
- * policy source override. Tool input cannot select scope, active authority, or
- * another policy source.
- */
-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",
-    {
-      description:
-        "Propose one existing evidence-backed workspace Knowledge claim through the frozen learning policy. Off creates nothing; Suggest and Automatic both create a proposal that only the human Knowledge review lifecycle can accept.",
-      inputSchema: { ...evidence, reason },
-    },
-    async (request) => {
-      await input.authorize();
-      return writeResult(() =>
-        router.write({
-          attempt: input.attempt,
-          request: { kind: "propose_knowledge", ...request },
-        }),
-      );
-    },
-  );
-
-  input.server.registerTool(
-    "knowledge_correct",
-    {
-      description:
-        "Propose an evidence-backed replacement for another workspace Knowledge claim. The old claim remains in immutable history and the correction never widens scope.",
-      inputSchema: { ...evidence, replacesClaimId: z.string().uuid(), reason },
-    },
-    async (request) => {
-      await input.authorize();
-      return writeResult(() =>
-        router.write({
-          attempt: input.attempt,
-          request: { kind: "correct_knowledge", ...request },
-        }),
-      );
-    },
-  );
-
-  input.server.registerTool(
-    "task_note_promote_knowledge",
-    {
-      description:
-        "Promote one still-active note from this exact root task tree into a normalized workspace Knowledge proposal. The immutable note bytes remain source evidence; this never activates the claim or widens it to personal/organization scope.",
-      inputSchema: taskNotePromotion,
-    },
-    async (request) => {
-      await input.authorize();
-      return writeResult(() =>
-        router.write({
-          attempt: input.attempt,
-          request: { kind: "promote_task_note_knowledge", ...request },
-        }),
-      );
-    },
-  );
-
-  input.server.registerTool(
-    "task_note_promote_instruction_policy",
-    {
-      description:
-        "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; Require approval 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,
-        expectedCurrentRevisionId: z.string().uuid().nullable(),
-        expectedActivationVersion: z.number().int().nonnegative(),
-      },
-    },
-    async (request) => {
-      await input.authorize();
-      return writeResult(() =>
-        router.write({
-          attempt: input.attempt,
-          request: { kind: "promote_task_note_instruction_policy", ...request },
-        }),
-      );
-    },
-  );
-
-  input.server.registerTool(
-    "task_note_promote_preference",
-    {
-      description:
-        "Legacy Skill promotion entry point. Returns a redirect without changing the note or writing a Skill. Read the note, then use skill_save for reusable guidance governed directly by Learning mode. Read opengeni-skills with skill_read for instructions.",
-      inputSchema: {
-        ...taskNotePromotion,
-        stableKey: z.string().trim().min(1).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).optional().default(0),
-        conflictStrategy: z
-          .enum(["override", "merge", "reject", "inform"])
-          .optional()
-          .default("override"),
-        conflictsWith: z.array(z.string().min(1)).max(32).optional().default([]),
-        expiresAt: z.string().datetime({ offset: true }).nullable().optional().default(null),
-      },
-    },
-    async () => {
-      await input.authorize();
-      return input.json({
-        status: "not_saved",
-        code: "use_skill_save",
-        message: "Read the task note, then use skill_save. The note has not been changed.",
-      });
-    },
-  );
-
-  input.server.registerTool(
-    "instruction_policy_propose",
-    {
-      description:
-        "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; Require approval keeps the proposal inactive; Autonomous may activate an eligible proposal through the governed instruction lifecycle with an undoable receipt.",
-      inputSchema: {
-        ...evidence,
-        target: WorkspaceInstructionPolicyTarget,
-        content: z
-          .string()
-          .trim()
-          .min(1)
-          .max(
-            AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
-            AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
-          ),
-        expectedCurrentRevisionId: z.string().uuid().nullable(),
-        expectedActivationVersion: z.number().int().nonnegative(),
-        reason,
-      },
-    },
-    async (request) => {
-      await input.authorize();
-      return writeResult(() =>
-        router.write({
-          attempt: input.attempt,
-          request: { kind: "propose_instruction_policy", ...request },
-        }),
-      );
-    },
-  );
-
-  input.server.registerTool(
-    "preference_propose",
-    {
-      description:
-        "Legacy Skill proposal entry point. Returns a redirect without writing. Use skill_read to read opengeni-skills, then discover skill_save for shared Skill file changes governed directly by Learning mode.",
-      inputSchema: {
-        ...evidence,
-        stableKey: z.string().trim().min(1).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),
-        content: z
-          .string()
-          .trim()
-          .min(1)
-          .max(
-            AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
-            AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
-          ),
-        precedenceRank: z.number().int().min(-1_000).max(1_000).optional().default(0),
-        conflictStrategy: z
-          .enum(["override", "merge", "reject", "inform"])
-          .optional()
-          .default("override"),
-        conflictsWith: z.array(z.string().min(1)).max(32).optional().default([]),
-        expiresAt: z.string().datetime({ offset: true }).nullable().optional().default(null),
-        reason,
-      },
-    },
-    async () => {
-      await input.authorize();
-      return input.json({
-        status: "not_saved",
-        code: "use_skill_save",
-        message:
-          "Use skill_save for Skill changes. This legacy entry point made no durable change.",
-      });
-    },
-  );
-}

package/src/mcp/remember.ts

@@ -1,191 +0,0 @@
-import {
-  AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
-  AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
-  AGENT_AUTHORED_REMEMBER_CONTENT_TOO_LONG_MESSAGE,
-  PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS,
-  PREFERENCE_REGISTRY_TITLE_MAX_CHARS,
-  REMEMBER_CONTENT_MAX_CHARS,
-  WorkspaceInstructionPolicyTarget,
-  agentAuthoredDurableTextTooLongMessage,
-  type CompanyBrainGovernedWriteAttempt,
-  type RememberLane,
-} from "@opengeni/contracts";
-import { RememberError, createRememberRouter } from "@opengeni/core";
-import { PreferenceRegistryStableKeyConflictError, type Database } from "@opengeni/db";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import * as z from "zod/v4";
-
-type JsonResult = (value: unknown) => {
-  content: { type: "text"; text: string }[];
-};
-
-export type RegisterRememberToolsInput = {
-  server: McpServer;
-  db: Database;
-  attempt: CompanyBrainGovernedWriteAttempt;
-  authorize: () => Promise<void>;
-  json: JsonResult;
-  router?: Pick<ReturnType<typeof createRememberRouter>, "remember" | "confirm">;
-};
-
-/**
- * Per-lane budgets. The flat MCP input schema cannot vary `content` by lane, so
- * it carries the widest lane (Knowledge) and the handler rejects an over-budget
- * prompt-composed lane with the actionable message before anything durable is
- * written. The contract enforces the same bounds for every other caller.
- */
-const laneContentMaxChars: Record<RememberLane, number> = {
-  instruction_policy: AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
-  preference: AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
-  knowledge: REMEMBER_CONTENT_MAX_CHARS,
-};
-
-const laneFields = {
-  operationId: z.string().uuid(),
-  content: z
-    .string()
-    .trim()
-    .min(1)
-    // The widest lane, because one flat schema serves all three. Carry the
-    // lane-aware guidance in the message so an over-long rule is not refused
-    // with a generic bound that points at the wrong number.
-    .max(REMEMBER_CONTENT_MAX_CHARS, AGENT_AUTHORED_REMEMBER_CONTENT_TOO_LONG_MESSAGE)
-    .describe(
-      `The exact thing to remember, in the user's words. Budgets by lane: instruction_policy at most ${AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters because it is composed into the prompt of every session it applies to, preference at most ${AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS} (its short descriptor is what is composed; the content is retrieved on demand), knowledge at most ${REMEMBER_CONTENT_MAX_CHARS}.`,
-    ),
-  reason: z.string().trim().min(1).max(4_096),
-};
-
-/**
- * Explicit user-directed remember. Content becomes exact task-note evidence,
- * promotion runs through the frozen workspace learning policy, and activation
- * is either automatic (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.
- */
-export function registerRememberTools(input: RegisterRememberToolsInput): void {
-  const router = input.router ?? createRememberRouter({ db: input.db });
-  input.server.registerTool(
-    "remember",
-    {
-      description:
-        "Create governed durable knowledge or a mandatory workspace instruction. Skills now use skill_save; the legacy preference lane returns a redirect without writing. When memory_save is available, use it for ordinary durable facts, decisions, incidents, bug fixes, and confirmed outcomes; 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=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. Do not copy one item into multiple lanes. ` +
-        "Under Autonomous learning, an eligible workspace instruction may activate immediately through its governed lifecycle. Under Require approval, 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,
-        stableKey: z
-          .string()
-          .trim()
-          .min(1)
-          .max(128)
-          .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/)
-          .optional(),
-        title: z.string().trim().min(1).max(PREFERENCE_REGISTRY_TITLE_MAX_CHARS).optional(),
-        description: z
-          .string()
-          .trim()
-          .min(1)
-          .max(PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS)
-          .optional(),
-        target: WorkspaceInstructionPolicyTarget.optional(),
-        subject: z.string().trim().min(1).max(512).optional(),
-      },
-    },
-    async (request) => {
-      await input.authorize();
-      const { lane, operationId, content, reason } = request;
-      if (lane === "preference")
-        return input.json({
-          status: "not_remembered",
-          code: "use_skill_save",
-          message:
-            "Skills use the shared file lifecycle. Read opengeni-skills with skill_read, then discover skill_save. No Knowledge evidence or confirmation question is needed for Skill edits.",
-        });
-      if (lane !== "knowledge" && content.length > laneContentMaxChars[lane]) {
-        return input.json({
-          status: "not_remembered",
-          code: "content_too_long",
-          message: agentAuthoredDurableTextTooLongMessage({
-            kind: lane,
-            actualChars: content.length,
-          }),
-        });
-      }
-      const base = { operationId, content, reason, scope: "workspace" as const };
-      const rememberRequest =
-        lane === "instruction_policy"
-          ? { ...base, lane, target: request.target }
-          : { ...base, lane, subject: request.subject ?? content.slice(0, 80) };
-      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;
-      }
-    },
-  );
-
-  input.server.registerTool(
-    "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; confirmed knowledge is materialized into searchable Memory from the exact approved text.",
-      inputSchema: {
-        operationId: z.string().uuid(),
-        proposalId: z.string().uuid().optional(),
-        decisionReceiptId: z.string().uuid().optional(),
-        claimId: z.string().uuid().optional(),
-        humanInputRequestId: z.string().uuid(),
-      },
-    },
-    async (request) => {
-      await input.authorize();
-      const confirmRequest =
-        request.proposalId && request.decisionReceiptId
-          ? {
-              target: "proposal" as const,
-              operationId: request.operationId,
-              proposalId: request.proposalId,
-              decisionReceiptId: request.decisionReceiptId,
-              humanInputRequestId: request.humanInputRequestId,
-            }
-          : request.claimId
-            ? {
-                target: "knowledge_claim" as const,
-                operationId: request.operationId,
-                claimId: request.claimId,
-                humanInputRequestId: request.humanInputRequestId,
-              }
-            : null;
-      if (!confirmRequest) {
-        return input.json({
-          status: "not_confirmed",
-          code: "invalid_target",
-          message:
-            "Pass proposalId + decisionReceiptId (preference/instruction_policy) or claimId (knowledge).",
-        });
-      }
-      try {
-        return input.json(
-          await router.confirm({ attempt: input.attempt, request: confirmRequest }),
-        );
-      } catch (error) {
-        if (error instanceof RememberError) {
-          return input.json({ status: "not_confirmed", code: error.code, message: error.message });
-        }
-        throw error;
-      }
-    },
-  );
-}