@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/session-mcp-projections.ts

@@ -2,6 +2,13 @@ import type { SessionGoalStatus, SessionStatus } from "./session-topology-primit
 import type { WorkDiscoveryProjection } from "./work-claims";
 import type { Session, SessionQueueSnapshot } from "./index";
 
+/** Counts used by compact monitoring; full queue previews remain a separate read. */
+export type SessionMcpQueueSummary = {
+  queuedTurns: number;
+  pendingInputs: number;
+  stoppingPreviousAttempt: boolean;
+};
+
 /** MCP-only presentation choice. REST/SDK session shapes keep their own defaults. */
 export type SessionMcpDetail = "compact" | "full";
 
@@ -176,7 +183,7 @@ export type SessionMcpMonitoringSource = {
 export function compactSessionMcpDetail(
   session: Session,
   monitoring: SessionMcpMonitoringSource,
-  queue: SessionQueueSnapshot | null,
+  queue: SessionQueueSnapshot | SessionMcpQueueSummary | null,
 ) {
   const title = boundSessionMcpText(session.title, 200);
   const pause = compactSessionMcpPause(session.effectiveControl);
@@ -209,6 +216,17 @@ export function compactSessionMcpDetail(
     ...(session.parentSessionId ? { parentSessionId: session.parentSessionId } : {}),
     ...(session.activeTurnId ? { activeTurnId: session.activeTurnId } : {}),
     lastSequence: session.lastSequence,
+    // Archived sessions keep a readable timeline but accept no new work.
+    ...(session.retention?.archive
+      ? {
+          archive: {
+            state: session.retention.archive.state,
+            archivedAt: session.retention.archive.archivedAt,
+            readOnly: true,
+          },
+        }
+      : {}),
+    ...(session.retention?.keepLive ? { keepLive: true } : {}),
     ...(goal
       ? {
           goal: {
@@ -244,8 +262,8 @@ export function compactSessionMcpDetail(
     ...(queue
       ? {
           queue: {
-            queuedTurns: queue.items.length,
-            pendingInputs: queue.pendingInputs.length,
+            queuedTurns: "items" in queue ? queue.items.length : queue.queuedTurns,
+            pendingInputs: "items" in queue ? queue.pendingInputs.length : queue.pendingInputs,
             ...(queue.stoppingPreviousAttempt ? { stoppingPreviousAttempt: true } : {}),
           },
         }

package/src/session-mcp-tool-permissions.ts

@@ -0,0 +1,109 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+import { ConnectorToolPermission } from "./connector-tool-permissions";
+import { MCP_MAX_CATALOG_TOOL_ENTRIES } from "./mcp-catalog-limits";
+
+/**
+ * Tool `_meta` key an MCP server sets in `tools/list` to recommend a default
+ * permission for that tool: `"ask"` or `"allow"`. Like `requireApproval`, it
+ * applies only when the workspace has no saved choice for the tool and no
+ * server default. The tool asks when either this or `requireApproval` says so.
+ */
+export const MCP_TOOL_RECOMMENDED_PERMISSION_META_KEY = "opengeni/recommendedPermission" as const;
+
+/** True when a listed MCP tool recommends Ask through its `_meta`. */
+export function mcpToolRecommendsApproval(tool: object): boolean {
+  const meta = (tool as { _meta?: unknown })._meta;
+  return (
+    typeof meta === "object" &&
+    meta !== null &&
+    (meta as Record<string, unknown>)[MCP_TOOL_RECOMMENDED_PERMISSION_META_KEY] === "ask"
+  );
+}
+
+// Host-attached session MCP servers have no catalog capability. Their tool
+// permissions are keyed by the same secret-free identity the runtime derives:
+// `session-mcp:<serverId>:<sha256(exact url)>`. The host names the server and
+// the exact URL it attaches to sessions; Opengeni stores and enforces the rules.
+const sessionMcpServerId = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(/^[A-Za-z0-9_-]+$/),
+);
+const sessionMcpServerUrl = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(1)
+    .max(2048)
+    .refine(
+      (value) => {
+        try {
+          const url = new URL(value);
+          return url.protocol === "https:" || url.protocol === "http:";
+        } catch {
+          return false;
+        }
+      },
+      { message: "url must be the exact http(s) URL attached to sessions" },
+    ),
+);
+const exactToolName = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(1)
+    .max(512)
+    .refine((name) => name !== "*" && name === name.trim(), {
+      message: "Tool names must be exact and cannot use the server-default wildcard.",
+    }),
+);
+
+export const SessionMcpToolPermissionsQuery = /* @__PURE__ */ defineSchema(() =>
+  z.object({ serverId: sessionMcpServerId, url: sessionMcpServerUrl }).strict(),
+);
+export type SessionMcpToolPermissionsQuery = z.infer<typeof SessionMcpToolPermissionsQuery>;
+
+/** Saved choices only. Tools without a rule follow `defaultPermission`, then
+ * the server's recommendation (the tool's `opengeni/recommendedPermission`
+ * `_meta`, or the attaching session's `requireApproval`), then Allow. */
+export const SessionMcpToolPermissionsResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    connectionId: primitives.string,
+    serverId: primitives.string,
+    defaultPermission: ConnectorToolPermission.nullable(),
+    tools: z.array(z.object({ toolName: primitives.string, permission: ConnectorToolPermission })),
+    revision: primitives.string,
+    canManage: primitives.boolean,
+    appliesTo: z.literal("next_attempt"),
+  }),
+);
+export type SessionMcpToolPermissionsResponse = z.infer<typeof SessionMcpToolPermissionsResponse>;
+
+export const UpdateSessionMcpToolPermissionsRequest = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("target", [
+    z
+      .object({
+        serverId: sessionMcpServerId,
+        url: sessionMcpServerUrl,
+        target: z.literal("default"),
+        permission: ConnectorToolPermission.nullable(),
+        expectedRevision: z.string().optional(),
+      })
+      .strict(),
+    z
+      .object({
+        serverId: sessionMcpServerId,
+        url: sessionMcpServerUrl,
+        target: z.literal("tools"),
+        toolNames: z.array(exactToolName).min(1).max(MCP_MAX_CATALOG_TOOL_ENTRIES),
+        permission: ConnectorToolPermission.nullable(),
+        expectedRevision: z.string().optional(),
+      })
+      .strict(),
+  ]),
+);
+export type UpdateSessionMcpToolPermissionsRequest = z.infer<
+  typeof UpdateSessionMcpToolPermissionsRequest
+>;

package/src/session-message-search.ts

@@ -1,38 +1,44 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
 /** Literal Unicode case-insensitive search, without trimming or normalization. */
-export const SessionMessageSearchRequest = z
-  .object({
-    query: z.string().min(1).max(200),
-    sessionId: z.string().uuid().optional(),
-    groupBy: z.literal("session").optional(),
-    archiveStatus: z.enum(["active", "archived", "all"]).optional(),
-    limit: z.number().int().min(1).max(50).optional(),
-    cursor: z.string().min(1).max(4096).optional(),
-  })
-  .strict()
-  .refine((request) => !request.groupBy || !request.sessionId, {
-    message: "groupBy=session is only supported for workspace search without sessionId",
-    path: ["groupBy"],
-  });
+export const SessionMessageSearchRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      query: z.string().min(1).max(200),
+      sessionId: primitives.optionalUuid,
+      groupBy: z.literal("session").optional(),
+      archiveStatus: z.enum(["active", "archived", "all"]).optional(),
+      limit: z.number().int().min(1).max(50).optional(),
+      cursor: z.string().min(1).max(4096).optional(),
+    })
+    .strict()
+    .refine((request) => !request.groupBy || !request.sessionId, {
+      message: "groupBy=session is only supported for workspace search without sessionId",
+      path: ["groupBy"],
+    }),
+);
 export type SessionMessageSearchRequest = z.infer<typeof SessionMessageSearchRequest>;
 
-export const SessionMessageSearchMatch = z.object({
-  sessionId: z.string().uuid(),
-  sessionTitle: z.string().nullable(),
-  eventId: z.string().uuid(),
-  sequence: z.number().int().positive(),
-  turnId: z.string().uuid().nullable(),
-  role: z.enum(["user", "assistant"]),
-  messageId: z.string().nullable(),
-  /** All offsets are zero-based UTF-16 code units; ends are exclusive. */
-  messageMatchOffset: z.number().int().nonnegative(),
-  snippet: z.object({
-    text: z.string(),
-    matchStart: z.number().int().nonnegative(),
-    matchEnd: z.number().int().nonnegative(),
+export const SessionMessageSearchMatch = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    sessionId: primitives.uuid,
+    sessionTitle: primitives.nullableString,
+    eventId: primitives.uuid,
+    sequence: primitives.positiveInteger,
+    turnId: primitives.nullableUuid,
+    role: z.enum(["user", "assistant"]),
+    messageId: primitives.nullableString,
+    /** All offsets are zero-based UTF-16 code units; ends are exclusive. */
+    messageMatchOffset: primitives.nonnegativeInteger,
+    snippet: z.object({
+      text: primitives.string,
+      matchStart: primitives.nonnegativeInteger,
+      matchEnd: primitives.nonnegativeInteger,
+    }),
   }),
-});
+);
 export type SessionMessageSearchMatch = z.infer<typeof SessionMessageSearchMatch>;
 
 /** A bounded scan page, not necessarily a full page of matches. Continue even
@@ -42,13 +48,15 @@ export type SessionMessageSearchMatch = z.infer<typeof SessionMessageSearchMatch
  * With groupBy=session, matches and both matched counts describe one first-hit
  * representative per matching session, not full message/occurrence totals.
  */
-export const SessionMessageSearchResponse = z.object({
-  matches: z.array(SessionMessageSearchMatch).max(50),
-  nextCursor: z.string().nullable(),
-  hasMore: z.boolean(),
-  scannedMessages: z.number().int().nonnegative(),
-  matchedMessageCount: z.number().int().nonnegative(),
-  matchedOccurrenceCount: z.number().int().nonnegative(),
-  countIsExact: z.boolean(),
-});
+export const SessionMessageSearchResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    matches: z.array(SessionMessageSearchMatch).max(50),
+    nextCursor: primitives.nullableString,
+    hasMore: primitives.boolean,
+    scannedMessages: primitives.nonnegativeInteger,
+    matchedMessageCount: primitives.nonnegativeInteger,
+    matchedOccurrenceCount: primitives.nonnegativeInteger,
+    countIsExact: primitives.boolean,
+  }),
+);
 export type SessionMessageSearchResponse = z.infer<typeof SessionMessageSearchResponse>;

package/src/session-target.ts

@@ -0,0 +1,58 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/** Conversational context only. Never an authority or an implicit dispatch destination. */
+export const SessionTargetContext = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      version: primitives.nonnegativeInteger,
+      sessionId: primitives.nullableUuid,
+      operationId: primitives.nullableUuid,
+    })
+    .strict(),
+);
+export type SessionTargetContext = z.infer<typeof SessionTargetContext>;
+
+export const SetSessionTargetRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      sessionId: primitives.nullableUuid,
+      expectedVersion: primitives.nonnegativeInteger,
+      operationId: primitives.uuid,
+    })
+    .strict(),
+);
+export type SetSessionTargetRequest = z.infer<typeof SetSessionTargetRequest>;
+
+export const SESSION_TARGET_CONTEXT_KEY = "conversationTargetV1";
+
+export function sessionTargetContext(metadata: Record<string, unknown>): SessionTargetContext {
+  return SessionTargetContext.parse(
+    metadata[SESSION_TARGET_CONTEXT_KEY] ?? {
+      version: 0,
+      sessionId: null,
+      operationId: null,
+    },
+  );
+}
+
+/** CAS plus exact retry replay; an old retry cannot restore a subsequently cleared target. */
+export function nextSessionTargetContext(
+  current: SessionTargetContext,
+  request: SetSessionTargetRequest,
+): SessionTargetContext {
+  SetSessionTargetRequest.parse(request);
+  if (current.operationId === request.operationId) {
+    if (current.sessionId !== request.sessionId || current.version !== request.expectedVersion + 1)
+      throw new Error("Session target operation was reused with different input");
+    return current;
+  }
+  if (current.version !== request.expectedVersion)
+    throw new Error("Session target changed; read it again");
+  return {
+    version: current.version + 1,
+    sessionId: request.sessionId,
+    operationId: request.operationId,
+  };
+}

package/src/session-titles.ts

@@ -18,7 +18,7 @@ export const AUTOMATIC_SESSION_TITLE_FALLBACK = "New conversation";
 // Session creation accepts a body far larger than a navigation label. Bound
 // the source before any replace/split/normalization so a persisted large prompt
 // cannot amplify memory or CPU on every client render.
-const PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS = 4_096;
+export const PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS = 4_096;
 
 const SESSION_ID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
@@ -196,7 +196,9 @@ const TITLE_LABEL_PATTERN =
   /^(?:(?:suggested|generated|concise)\s+)?(?:(?:session|chat|conversation|task)\s+)?title\s*[:\-–—]\s*/iu;
 
 const LEADING_BOILERPLATE_PATTERNS = [
-  /^(?:hi|hello|hey)(?:\s+there)?\s*[,!:.\-–—]*\s*/iu,
+  // Require a real separator, not ASCII-only \b: History, HelloWorld and
+  // Unicode word continuations are title content, as is "thereabouts" after Hi.
+  /^(?:hi|hello|hey)(?:\s+there)?(?=$|[\s,!:.\-–—])\s*[,!:.\-–—]*\s*/iu,
   /^(?:i\s+(?:would\s+like|want|need)\s+you\s+to|i['’]d\s+like\s+you\s+to)\s+/iu,
   /^(?:please\s+)?(?:can|could|would|will)\s+you\s+/iu,
   /^(?:your|the)\s+(?:task|job)\s+is\s+to\s+/iu,
@@ -324,6 +326,39 @@ function automaticTitleGraphemes(value: string): string[] {
   return graphemes;
 }
 
+/**
+ * Model control tokens such as `<|fim_suffix|>`, `<|im_end|>` or `<｜end▁of▁sentence｜>`
+ * sometimes leak into generated text. They are never title content: each one
+ * becomes a line break, so a title keeps only its first real segment.
+ */
+const MODEL_CONTROL_TOKEN = /<[|｜][^<>|｜\s]{1,64}[|｜]>/gu;
+
+function withoutModelControlTokens(value: string): string {
+  return value.replace(MODEL_CONTROL_TOKEN, "\n");
+}
+
+/**
+ * Read-side cleanup for a durable title. Automatic titles written before
+ * control-token stripping can still hold a token ("Release plan<|fim_suffix|>");
+ * those keep only their first real segment, and a token-only title reads as no
+ * title. Human renames and titles without a token are returned unchanged.
+ */
+export function cleanStoredSessionTitle(
+  title: string | null | undefined,
+  titleSource: string | null | undefined,
+): string | null {
+  if (title === null || title === undefined) return null;
+  if (titleSource === "user") return title;
+  const stripped = withoutModelControlTokens(title);
+  if (stripped === title) return title;
+  return (
+    stripped
+      .split("\n")
+      .map((part) => part.trim())
+      .find(Boolean) ?? null
+  );
+}
+
 /** Bound an already-normalized automatic-title candidate without splitting graphemes. */
 export function boundAutomaticSessionTitle(value: string): string {
   const words = value.split(/\s+/u);
@@ -345,7 +380,7 @@ export function boundAutomaticSessionTitle(value: string): string {
  * title (normally {@link AUTOMATIC_SESSION_TITLE_FALLBACK}) in that case.
  */
 export function normalizeAutomaticSessionTitle(value: string): string | null {
-  const firstLine = value
+  const firstLine = withoutModelControlTokens(value)
     .replace(/[\u0000-\u001f\u007f-\u009f]+/gu, "\n")
     .split(/\n+/u)
     .map((line) => line.trim())
@@ -450,7 +485,8 @@ export function deriveSessionDisplayTitle(
     return title || automaticSessionReferenceTitle(input.id);
   }
   if (title && !sessionTitleIsPending(input)) {
-    return title;
+    const clean = cleanStoredSessionTitle(title, input.titleSource)?.trim();
+    if (clean) return clean;
   }
 
   for (const key of options.metadataKeys ?? []) {

package/src/session-topology-primitives.ts

@@ -1,21 +1,29 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
-export const SessionStatus = z.enum([
-  "queued",
-  "running",
-  "idle",
-  "requires_action",
-  "recovering",
-  "waiting_capacity",
-  "failed",
-  "cancelled",
-]);
+export const SessionStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "queued",
+    "running",
+    "idle",
+    "requires_action",
+    "recovering",
+    "waiting_capacity",
+    "failed",
+    "cancelled",
+  ]),
+);
 export type SessionStatus = z.infer<typeof SessionStatus>;
 
-export const SessionGoalStatus = z.enum(["active", "paused", "completed"]);
+export const SessionGoalStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["active", "paused", "completed"]),
+);
 export type SessionGoalStatus = z.infer<typeof SessionGoalStatus>;
 
 /** Physical ceiling of the PostgreSQL integer columns that persist depth policy. */
 export const MAX_NESTED_AGENT_DEPTH = 2_147_483_647;
-export const NestedAgentDepthValue = z.number().int().nonnegative().max(MAX_NESTED_AGENT_DEPTH);
+export const NestedAgentDepthValue = /* @__PURE__ */ defineSchema(() =>
+  primitives.nonnegativeInteger.max(MAX_NESTED_AGENT_DEPTH),
+);
 export type NestedAgentDepthValue = z.infer<typeof NestedAgentDepthValue>;

package/src/session-usage-limit-refusal.ts

@@ -0,0 +1,101 @@
+/**
+ * Browser/React Native-safe session usage limit helpers. Deliberately free of
+ * the zod runtime so synchronous timeline projection can use it; contract
+ * parity tests keep it aligned with `session-usage-limits.ts`.
+ */
+
+/** `turn.completed.segmentLimit` for a stop caused by a task usage limit. */
+export const SESSION_USAGE_LIMIT_SEGMENT = "session_usage_limit" as const;
+/** `SessionGoal.pausedReason` for a goal paused by a task usage limit. */
+export const SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON = "session_usage_limit" as const;
+
+const BASIS = "model_api_equivalent_v1";
+const MAX_LIMIT_MICROS = 10_000_000 * 1_000_000;
+const MESSAGE_MAX_UTF8_BYTES = 1_024;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export type ParsedSessionUsageLimitReachedRefusal = {
+  code: "session_usage_limit_reached";
+  basis: "model_api_equivalent_v1";
+  rootSessionId: string;
+  limitMicros: number;
+  usedMicros: number;
+  message: string;
+};
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function micros(value: unknown, max = Number.MAX_SAFE_INTEGER): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= max;
+}
+
+function boundedMessage(value: string): string {
+  const normalized = value
+    .slice(0, MESSAGE_MAX_UTF8_BYTES * 2)
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .trim();
+  const bytes = new TextEncoder().encode(normalized);
+  let end = Math.min(bytes.length, MESSAGE_MAX_UTF8_BYTES);
+  while (end > 0 && end < bytes.length && (bytes[end]! & 0xc0) === 0x80) end -= 1;
+  return new TextDecoder().decode(bytes.slice(0, end)).trim();
+}
+
+/**
+ * Select only the public refusal fields from an API error body (fields may sit
+ * in `details`), a `turn.completed` payload's `sessionUsageLimit` record, or a
+ * refusal object. Anything malformed returns null instead of a guessed amount.
+ */
+export function parseSessionUsageLimitReachedRefusal(
+  value: unknown,
+): ParsedSessionUsageLimitReachedRefusal | null {
+  const outer = record(value);
+  if (!outer) return null;
+  const source = record(outer.sessionUsageLimit) ?? outer;
+  if (source.code !== "session_usage_limit_reached") return null;
+  const fields = record(source.details) ?? source;
+  if (
+    fields.basis !== BASIS ||
+    typeof fields.rootSessionId !== "string" ||
+    !UUID.test(fields.rootSessionId) ||
+    !micros(fields.limitMicros, MAX_LIMIT_MICROS) ||
+    !micros(fields.usedMicros)
+  ) {
+    return null;
+  }
+  const refusal = {
+    code: "session_usage_limit_reached" as const,
+    basis: BASIS as "model_api_equivalent_v1",
+    rootSessionId: fields.rootSessionId.toLowerCase(),
+    limitMicros: fields.limitMicros,
+    usedMicros: fields.usedMicros,
+    message: "",
+  };
+  const message = typeof source.message === "string" ? boundedMessage(source.message) : "";
+  return { ...refusal, message: message || sessionUsageLimitReachedMessage(refusal) };
+}
+
+/**
+ * "$12.34" for known amounts, "<$0.01" for a positive amount under a cent.
+ * Callers must not pass unknown usage: render "Preparing usage" or
+ * "Usage unavailable" instead of a dollar figure.
+ */
+export function formatSessionUsageMicros(value: number): string {
+  if (value > 0 && value < 10_000) return "<$0.01";
+  const dollars = value / 1_000_000;
+  return `$${dollars.toLocaleString("en-US", {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  })}`;
+}
+
+/** Fixed, bounded wording: no reset date, purchase remedy or invoice claim. */
+export function sessionUsageLimitReachedMessage(refusal: {
+  limitMicros: number;
+  usedMicros: number;
+}): string {
+  return `This task's usage limit is reached (${formatSessionUsageMicros(refusal.usedMicros)} of ${formatSessionUsageMicros(refusal.limitMicros)} API-equivalent model usage). A person can raise or remove the limit to continue.`;
+}