@opengeni/api-router 0.30.1 → 1.0.0

package/src/mcp/capability-account-readiness.ts

@@ -0,0 +1,17 @@
+import type { McpConnectionAccountBinding } from "@opengeni/contracts";
+
+/** Canonical readiness comes only from routes present in this exact attempt,
+ * joined to this turn's accepted bindings. It never grants account access. */
+export function capabilityAccountReadiness(
+  availableRoutes: Iterable<string>,
+  bindings: readonly McpConnectionAccountBinding[] | null,
+) {
+  const available = new Set(availableRoutes);
+  const actualRoutes = new Set(available);
+  const accepted = new Set<string>();
+  for (const binding of bindings ?? []) {
+    accepted.add(binding.canonicalServerId);
+    if (actualRoutes.has(binding.serverId)) available.add(binding.canonicalServerId);
+  }
+  return { available, accepted };
+}

package/src/mcp/child-read-evidence.ts

@@ -0,0 +1,19 @@
+/** Select only whole items that actually survived the model-facing envelope.
+ * A cursor is a position, never proof that preceding content was consumed. */
+export function completeChildReadSequences(page: {
+  view: string;
+  sourceExact: boolean;
+  events: readonly ({ sequence: number } & Record<string, unknown>)[];
+}): number[] {
+  if (!page.sourceExact || !["conversation", "results"].includes(page.view)) return [];
+  return page.events
+    .filter((event) => {
+      if (event.sourceOmitted) return false;
+      if (event.fragment === undefined) return true;
+      if (!event.fragment || typeof event.fragment !== "object") return false;
+      const fragment = event.fragment as Record<string, unknown>;
+      // A final fragment cannot prove earlier fragments were ever read.
+      return fragment.offset === 0 && fragment.complete === true;
+    })
+    .map((event) => event.sequence);
+}

package/src/mcp/command-read.ts

@@ -0,0 +1,109 @@
+import type { SessionEvent } from "@opengeni/contracts";
+import { COMMAND_OUTPUT_MAX_BYTES } from "@opengeni/db/session-background-commands";
+
+export const COMMAND_READ_MAX_WAIT_SECONDS = 50;
+export const COMMAND_WAIT_DEFAULT_SECONDS = 45;
+
+/** Shared provider-neutral command_read/command_wait operation. Notifications
+ * are only wake hints. Every result, including timeout, comes from durable DB
+ * state. Subscribe before reading to close the finish/subscription race, and
+ * periodically recheck durable state because live hints may be lost. */
+export async function readCommandWithWait<
+  T extends { terminal: boolean; chunks: unknown[]; hasMore?: boolean },
+>(input: {
+  commandId: string;
+  waitSeconds?: number;
+  maxOutputBytes?: number | undefined;
+  signal?: AbortSignal;
+  read: () => Promise<T>;
+  subscribe: (onEvents: (events: SessionEvent[]) => void) => Promise<() => void>;
+}) {
+  const seconds = input.waitSeconds ?? 0;
+  if (!Number.isInteger(seconds) || seconds < 0 || seconds > COMMAND_READ_MAX_WAIT_SECONDS) {
+    throw new Error("waitSeconds must be between 0 and 50");
+  }
+  if (
+    input.maxOutputBytes !== undefined &&
+    (!Number.isInteger(input.maxOutputBytes) ||
+      input.maxOutputBytes < 4 ||
+      input.maxOutputBytes > COMMAND_OUTPUT_MAX_BYTES)
+  ) {
+    throw new Error("maxOutputBytes must be between 4 and 65536");
+  }
+  const started = Date.now();
+  const deadline = started + seconds * 1000;
+  let unsubscribe: (() => void) | undefined;
+  let wake: (() => void) | undefined;
+  let changed = false;
+  let liveFanout = true;
+  const notify = () => {
+    changed = true;
+    wake?.();
+  };
+  input.signal?.addEventListener("abort", notify);
+  try {
+    if (seconds > 0) {
+      try {
+        unsubscribe = await input.subscribe((events) => {
+          if (
+            events.some(
+              (event) =>
+                (event.type === "session.command.finished" ||
+                  event.type === "sandbox.command.output.delta") &&
+                event.payload !== null &&
+                typeof event.payload === "object" &&
+                (event.payload as Record<string, unknown>).commandId === input.commandId,
+            )
+          )
+            notify();
+        });
+      } catch {
+        liveFanout = false;
+      }
+    }
+    while (true) {
+      changed = false;
+      const result = await input.read();
+      const expired = Date.now() >= deadline;
+      if (
+        result.terminal ||
+        result.chunks.length > 0 ||
+        result.hasMore ||
+        expired ||
+        input.signal?.aborted
+      ) {
+        return {
+          ...result,
+          waitedMs: Date.now() - started,
+          timedOut:
+            seconds > 0 &&
+            expired &&
+            !result.terminal &&
+            result.chunks.length === 0 &&
+            !result.hasMore,
+          aborted: input.signal?.aborted ?? false,
+          liveFanout,
+        };
+      }
+      if (changed) continue;
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(
+          () => {
+            wake = undefined;
+            resolve();
+          },
+          Math.max(0, Math.min(1_000, deadline - Date.now())),
+        );
+        wake = () => {
+          clearTimeout(timer);
+          wake = undefined;
+          resolve();
+        };
+        if (changed || input.signal?.aborted) wake();
+      });
+    }
+  } finally {
+    input.signal?.removeEventListener("abort", notify);
+    unsubscribe?.();
+  }
+}

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

@@ -0,0 +1,198 @@
+import {
+  AGENT_AUTHORED_COMPANY_PROFILE_ENTRY_MAX_CHARS,
+  AGENT_AUTHORED_COMPANY_PROFILE_SCALAR_MAX_CHARS,
+  AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE,
+  AgentAuthoredCompanyProfileContent,
+  COMPANY_PROFILE_REASON_MAX_CHARS,
+  COMPANY_PROFILE_STABLE_KEY_MAX_CHARS,
+  normalizeCompanyProfileStableKey,
+  type CompanyProfileAgentAttempt,
+  type CompanyProfileEntry,
+} from "@opengeni/contracts";
+import {
+  CompanyProfileAgentAdminError,
+  createCompanyProfileAgentAdminRouter,
+} from "@opengeni/core";
+import 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 RegisterCompanyProfileAgentAdminToolsInput = {
+  server: McpServer;
+  db: Database;
+  attempt: CompanyProfileAgentAttempt;
+  authorize: () => Promise<void>;
+  json: JsonResult;
+  router?: Pick<ReturnType<typeof createCompanyProfileAgentAdminRouter>, "propose" | "confirm">;
+};
+
+// 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()
+  .min(1)
+  .max(
+    AGENT_AUTHORED_COMPANY_PROFILE_SCALAR_MAX_CHARS,
+    AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE,
+  )
+  .nullable();
+const entry = z.object({
+  key: z.string().trim().min(1).max(COMPANY_PROFILE_STABLE_KEY_MAX_CHARS).optional(),
+  content: z
+    .string()
+    .trim()
+    .min(1)
+    .max(
+      AGENT_AUTHORED_COMPANY_PROFILE_ENTRY_MAX_CHARS,
+      AGENT_AUTHORED_COMPANY_PROFILE_TOO_LONG_MESSAGE,
+    ),
+});
+const DEFAULT_PROPOSAL_REASON = "Activate agent-proposed organization identity";
+const STABLE_KEY_WORDS = 6;
+
+type EntryInput = z.infer<typeof entry>;
+
+/**
+ * Derive a stable key from entry content: the first few words, normalized into
+ * the company-profile key alphabet and bounded to the stable-key length.
+ */
+export function deriveCompanyProfileStableKey(content: string): string {
+  const words = content
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s._-]+/gu, " ")
+    .trim()
+    .split(/\s+/u)
+    .filter(Boolean)
+    .slice(0, STABLE_KEY_WORDS)
+    .join(" ");
+  const normalized = normalizeCompanyProfileStableKey(words)
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/-+/g, "-")
+    .slice(0, COMPANY_PROFILE_STABLE_KEY_MAX_CHARS)
+    .replace(/^[._-]+|[._-]+$/g, "");
+  return normalized.length > 0 ? normalized : "entry";
+}
+
+/**
+ * Resolve explicit or derived keys for one list and de-duplicate by suffixing
+ * `-2`, `-3`, ... so the profile passes the unique-key contract.
+ */
+export function resolveCompanyProfileEntries(input: readonly EntryInput[]): CompanyProfileEntry[] {
+  const used = new Set<string>();
+  return input.map(({ key, content }) => {
+    const base = key
+      ? normalizeCompanyProfileStableKey(key)
+      : deriveCompanyProfileStableKey(content);
+    let candidate = base;
+    for (let suffix = 2; used.has(candidate); suffix += 1) {
+      const tail = `-${suffix}`;
+      candidate = `${base.slice(0, COMPANY_PROFILE_STABLE_KEY_MAX_CHARS - tail.length)}${tail}`;
+    }
+    used.add(candidate);
+    return { key: candidate, content };
+  });
+}
+
+function boundedIssueMessage(error: z.ZodError): string {
+  return error.issues
+    .slice(0, 5)
+    .map((issue) => `${issue.path.join(".") || "profile"}: ${issue.message}`)
+    .join("; ")
+    .slice(0, 1_024);
+}
+
+/**
+ * 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,
+): void {
+  const router = input.router ?? createCompanyProfileAgentAdminRouter({ db: input.db });
+  input.server.registerTool(
+    "company_profile_propose",
+    {
+      description:
+        "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 is independent of workspace learning policy and follows the organization owner's Agent-managed identity mode. Off creates nothing. Require approval 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,
+        mission: scalar,
+        reason: z.string().trim().min(1).max(COMPANY_PROFILE_REASON_MAX_CHARS).optional(),
+      },
+    },
+    async (request) => {
+      await input.authorize();
+      const parsed = AgentAuthoredCompanyProfileContent.safeParse({
+        identity: request.identity,
+        mission: request.mission,
+        products: [],
+        customers: [],
+        goals: [],
+        constraints: [],
+      });
+      if (!parsed.success) {
+        return input.json({
+          status: "not_proposed",
+          code: "invalid_profile",
+          message: boundedIssueMessage(parsed.error),
+        });
+      }
+      try {
+        return input.json(
+          await router.propose({
+            attempt: input.attempt,
+            request: {
+              operationId: request.operationId,
+              profile: parsed.data,
+              reason: request.reason ?? DEFAULT_PROPOSAL_REASON,
+            },
+          }),
+        );
+      } catch (error) {
+        if (error instanceof CompanyProfileAgentAdminError) {
+          return input.json({ status: "not_proposed", code: error.code, message: error.message });
+        }
+        throw error;
+      }
+    },
+  );
+
+  input.server.registerTool(
+    "company_profile_confirm",
+    {
+      description:
+        "Activate a `company_profile_propose` receipt only after the exact initiating organization owner answered Activate on the returned `request_human_input` prompt. Pass the proposalReceiptId and requestId unchanged. Confirmation revalidates the live turn, organization role, proposal hash, and unchanged active-profile baseline, then returns the immutable activation receipt.",
+      inputSchema: {
+        operationId: z.string().uuid(),
+        proposalReceiptId: z.string().uuid(),
+        humanInputRequestId: z.string().uuid(),
+      },
+    },
+    async (request) => {
+      await input.authorize();
+      try {
+        return input.json(await router.confirm({ attempt: input.attempt, request }));
+      } catch (error) {
+        if (error instanceof CompanyProfileAgentAdminError) {
+          return input.json({ status: "not_confirmed", code: error.code, message: error.message });
+        }
+        throw error;
+      }
+    },
+  );
+}

package/src/mcp/contract-input.ts

@@ -0,0 +1,141 @@
+import * as z from "zod/v4";
+
+/**
+ * Publish the input side of a contract, validate it, and retain the exact call.
+ * MCP parsing must not insert defaults, trim text, or erase omitted fields before
+ * the application applies presence-sensitive inheritance and authority rules.
+ * A narrower projection may hide host-only fields; validation retains the full
+ * contract's preprocessors and cross-field checks.
+ */
+export function contractToolInput<T extends z.ZodObject>(
+  projection: T,
+  validation: z.ZodType = projection,
+): z.ZodType<z.input<T>, z.input<T>> {
+  const inputProjection = projection.strict();
+  const jsonSchema = z.toJSONSchema(inputProjection, {
+    io: "input",
+    target: "draft-7",
+  });
+  assertDescribedToolInput(jsonSchema);
+  // MCP's SDK only publishes recognized object schemas. A passthrough object
+  // keeps the call intact, while metadata supplies the projected JSON Schema.
+  return z
+    .object({})
+    .catchall(z.unknown())
+    .superRefine((args, context) => {
+      const projected = inputProjection.safeParse(args);
+      const parsed = projected.success ? validation.safeParse(args) : projected;
+      if (!parsed.success) {
+        for (const issue of inputIssues(parsed.error.issues)) context.addIssue({ ...issue });
+      }
+    })
+    .meta(jsonSchema) as unknown as z.ZodType<z.input<T>, z.input<T>>;
+}
+
+/** Every named input and array element needs a schema. Dictionary values may be arbitrary JSON. */
+export function assertDescribedToolInput(schema: unknown, tool = "tool"): void {
+  const activeRefs = new Set<string>();
+  function visit(value: unknown, path: string, allowOpaque = false): void {
+    if (value === false) return;
+    if (value === true && allowOpaque) return;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error(`${tool}: invalid input schema at ${path}`);
+    }
+    const node = value as Record<string, unknown>;
+    const constraints = ["type", "$ref", "enum", "const", "anyOf", "oneOf", "allOf", "not"];
+    if (!constraints.some((key) => Object.hasOwn(node, key))) {
+      if (allowOpaque) return;
+      throw new Error(`${tool}: input ${path} has no declared structure; use its contract schema`);
+    }
+    if (typeof node.$ref === "string" && node.$ref.startsWith("#/") && !activeRefs.has(node.$ref)) {
+      const ref = node.$ref;
+      let target = schema;
+      for (const part of ref.slice(2).split("/")) {
+        target = (target as Record<string, unknown>)?.[
+          part.replace(/~1/g, "/").replace(/~0/g, "~")
+        ];
+      }
+      activeRefs.add(ref);
+      visit(target, path, allowOpaque);
+      activeRefs.delete(ref);
+    }
+    for (const [key, child] of Object.entries((node.properties ?? {}) as Record<string, unknown>)) {
+      visit(child, `${path}.${key}`);
+    }
+    if (node.type === "array" && node.items === undefined && node.prefixItems === undefined) {
+      throw new Error(
+        `${tool}: input ${path}[] has no declared structure; use its contract schema`,
+      );
+    }
+    if (Array.isArray(node.items)) {
+      node.items.forEach((child, index) => visit(child, `${path}[${index}]`));
+      if (node.additionalItems !== undefined) visit(node.additionalItems, `${path}[...]`);
+      else if (typeof node.maxItems !== "number" || node.maxItems > node.items.length) {
+        throw new Error(
+          `${tool}: input ${path}[...] has no declared structure; use its contract schema`,
+        );
+      }
+    } else if (node.items !== undefined) visit(node.items, `${path}[]`);
+    if (Array.isArray(node.prefixItems)) {
+      node.prefixItems.forEach((child, index) => visit(child, `${path}[${index}]`));
+      if (
+        node.items === undefined &&
+        (typeof node.maxItems !== "number" || node.maxItems > node.prefixItems.length)
+      ) {
+        throw new Error(
+          `${tool}: input ${path}[...] has no declared structure; use its contract schema`,
+        );
+      }
+    }
+    // An unconstrained dictionary is intentional extension data. If its values
+    // declare a structure, check that structure's fields just like named inputs.
+    const dictionary = node.additionalProperties;
+    if (dictionary && typeof dictionary === "object" && Object.keys(dictionary).length > 0) {
+      visit(dictionary, `${path}.*`, true);
+    }
+    for (const [key, child] of Object.entries(
+      (node.patternProperties ?? {}) as Record<string, unknown>,
+    )) {
+      if (child && typeof child === "object" && Object.keys(child).length === 0) continue;
+      visit(child, `${path}.[${key}]`, true);
+    }
+    for (const keyword of ["anyOf", "oneOf", "allOf"]) {
+      for (const [index, child] of ((node[keyword] ?? []) as unknown[]).entries()) {
+        visit(child, `${path}.${keyword}[${index}]`, allowOpaque);
+      }
+    }
+  }
+  visit(schema, "arguments");
+}
+
+/** Only raw contract preflight errors, never downstream provider or storage exceptions. */
+function inputIssues(issues: readonly z.core.$ZodIssue[]): z.core.$ZodIssueCustom[] {
+  const result: z.core.$ZodIssueCustom[] = [];
+  for (const issue of issues.slice(0, 8)) {
+    const path = [...issue.path];
+    let message: string;
+    if (issue.code === "invalid_type") message = `expected ${issue.expected}`;
+    else if (issue.code === "invalid_value")
+      message = `allowed values: ${JSON.stringify(issue.values)}`;
+    else if (issue.code === "invalid_union" && issue.errors.length === 0 && issue.discriminator) {
+      if (path.at(-1) !== issue.discriminator) path.push(issue.discriminator);
+      message = `allowed values: ${JSON.stringify("options" in issue ? issue.options : [])}`;
+    } else if (issue.code === "invalid_union") {
+      // These are alternatives, never cumulative requirements.
+      message = "does not match any of the declared alternative input formats";
+    } else if (issue.code === "unrecognized_keys")
+      message = `fields not declared by this tool: ${JSON.stringify(issue.keys)}`;
+    else if (issue.code === "too_small") message = `must meet minimum ${issue.minimum}`;
+    else if (issue.code === "too_big") message = `must meet maximum ${issue.maximum}`;
+    else message = issue.message;
+    result.push({ code: "custom", path, message });
+  }
+  if (issues.length > 8) {
+    result.push({
+      code: "custom",
+      path: [],
+      message: `${issues.length - 8} additional input problems`,
+    });
+  }
+  return result;
+}