@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/dist/session-history.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Conversation-first session history: which durable events are the steps of a
+ * turn, and which tool results stay visible without opening those steps.
+ * Dependency-free so browser packages can import it without the schema bundle.
+ */
+/**
+ * The bulk of a long agent turn: tool calls, their outputs and streamed
+ * reasoning or command output. A turn whose window skips any of these has
+ * steps a reader can open.
+ */
+export declare const SESSION_EVENT_CONTENT_STEP_TYPES: readonly ["agent.toolCall.created", "agent.toolCall.output", "agent.reasoning.delta", "sandbox.command.output.delta", "terminal.pty.output.delta"];
+/**
+ * Turn bookkeeping that renders nothing in the conversation: a turn writes a
+ * few `agent.model.request` rows and an `agent.model.usage` row per model
+ * call. Only a turn's request rows up to its first model response draw
+ * anything (the "first model response" startup phase); a conversation-filter
+ * server keeps those, and every bookkeeping row of a turn without other
+ * steps, so it never looks like it has steps to open.
+ */
+export declare const SESSION_EVENT_BOOKKEEPING_STEP_TYPES: readonly ["agent.model.request", "agent.model.usage"];
+/**
+ * Everything conversation-first history reads exclude and load per turn, only
+ * when a reader asks for that turn's steps.
+ */
+export declare const SESSION_EVENT_STEP_TYPES: readonly ["agent.toolCall.created", "agent.toolCall.output", "agent.reasoning.delta", "sandbox.command.output.delta", "terminal.pty.output.delta", "agent.model.request", "agent.model.usage"];
+/**
+ * The conversation-filter behavior a server applies to a read that sends
+ * `presentedToolCalls=include`, announced in the `X-OpenGeni-Conversation-Filter`
+ * response header. Version 2 keeps presented tool calls and the bookkeeping
+ * rows described by {@link SESSION_EVENT_BOOKKEEPING_STEP_TYPES}; excluded
+ * turnless output (PTY and command output) stays out, for the sandbox dock to
+ * read itself. A server without the header may ignore `presentedToolCalls`
+ * entirely.
+ */
+export declare const SESSION_EVENT_CONVERSATION_FILTER_VERSION = 2;
+export declare const SESSION_EVENT_CONVERSATION_FILTER_HEADER = "X-OpenGeni-Conversation-Filter";
+/**
+ * What a reader excludes from a conversation read when the server has not
+ * announced {@link SESSION_EVENT_CONVERSATION_FILTER_VERSION}: tool calls stay
+ * in (an older server would otherwise drop presented calls with them) and the
+ * reader drops the ones that are not presented.
+ */
+export declare const SESSION_EVENT_COMPAT_EXCLUDED_STEP_TYPES: readonly ["agent.toolCall.output", "agent.reasoning.delta", "sandbox.command.output.delta", "terminal.pty.output.delta"];
+/**
+ * Whether an `agent.model.request` phase is the model's first response. A
+ * turn's request rows after its first response no longer change what the
+ * conversation draws.
+ */
+export declare function isSessionModelResponsePhase(phase: unknown): boolean;
+/**
+ * Tools whose result is primary output a reader sees without opening the
+ * turn's steps: presented images and published files, Skill changes that may
+ * need review, learning writes whose refusal is told outside the folded work
+ * row, and worker spawns or messages that a turn's wait counts. Matched on the
+ * tool name's leaf (`x__leaf` or `leaf`).
+ */
+export declare const SESSION_EVENT_PRESENTED_TOOL_LEAVES: readonly ["generate_image", "image_generation_call", "sandbox_file_publish", "skill_save", "skill_remove", "skill_install", "skill_publish", "instruction_policy_save", "knowledge_save", "knowledge_retain_file", "knowledge_retain_message", "knowledge_archive", "task_note_promote_knowledge", "remember_confirm", "session_create", "session_send_message"];
+/** Whether a tool name is one of {@link SESSION_EVENT_PRESENTED_TOOL_LEAVES}. */
+export declare function isPresentedSessionToolName(name: unknown): boolean;
+/** The tool leaf a session runs the app's own actions through. */
+export declare const SESSION_EVENT_APP_ACTION_CALL_LEAF = "admin_action_call";
+/** The page an app action opens: buying credits, starting a subscription, or the billing portal. */
+export type PresentedAppActionPage = "credits" | "subscription" | "portal";
+/**
+ * App actions whose call is primary output too: each opens a payment page,
+ * and the chat shows it as a button that later confirms the payment, which a
+ * person returning to the chat (often in a reloaded tab) needs to see.
+ * Keyed by action id, with the "METHOD /path" a call may name it by instead
+ * (as `findAppAction` accepts) and the page it opens.
+ */
+export declare const SESSION_EVENT_PRESENTED_APP_ACTIONS: {
+    readonly createBillingCheckout: {
+        readonly route: "POST /v1/billing/checkout";
+        readonly page: "credits";
+    };
+    readonly createSubscriptionCheckout: {
+        readonly route: "POST /v1/billing/subscription/checkout";
+        readonly page: "subscription";
+    };
+    readonly createBillingPortalSession: {
+        readonly route: "POST /v1/billing/portal";
+        readonly page: "portal";
+    };
+    readonly createSubscriptionPortalSession: {
+        readonly route: "POST /v1/billing/subscription/portal";
+        readonly page: "portal";
+    };
+};
+export type PresentedAppActionId = keyof typeof SESSION_EVENT_PRESENTED_APP_ACTIONS;
+/**
+ * The whitespace a call's action id is trimmed of before it's matched: exactly
+ * what `String.prototype.trim` removes, as the action runner trims the id
+ * (`findAppAction`), spelled out so the history query (Postgres `btrim`) and
+ * every client agree.
+ */
+export declare const SESSION_EVENT_APP_ACTION_ID_SPACE = " \t\n\v\f\r\u00A0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF";
+/** Every name that calls one of {@link SESSION_EVENT_PRESENTED_APP_ACTIONS}: each id and its "METHOD /path". */
+export declare const SESSION_EVENT_PRESENTED_APP_ACTION_NAMES: readonly string[];
+/**
+ * Which of {@link SESSION_EVENT_PRESENTED_APP_ACTIONS} an app action call's
+ * `id` names, by its id or its "METHOD /path"; undefined for anything else.
+ */
+export declare function presentedAppActionId(id: unknown): PresentedAppActionId | undefined;
+/**
+ * Whether a tool call's result is primary output: a presented tool
+ * ({@link isPresentedSessionToolName}), or an app action call that runs one of
+ * {@link SESSION_EVENT_PRESENTED_APP_ACTIONS} (its arguments' top-level `id`,
+ * see {@link presentedAppActionId}). Takes the `agent.toolCall.created`
+ * payload (its `name` and `arguments`, an object or JSON text).
+ */
+export declare function isPresentedSessionToolCall(call: unknown): boolean;

package/dist/session-history.js

@@ -0,0 +1,35 @@
+import {
+  SESSION_EVENT_APP_ACTION_CALL_LEAF,
+  SESSION_EVENT_APP_ACTION_ID_SPACE,
+  SESSION_EVENT_BOOKKEEPING_STEP_TYPES,
+  SESSION_EVENT_COMPAT_EXCLUDED_STEP_TYPES,
+  SESSION_EVENT_CONTENT_STEP_TYPES,
+  SESSION_EVENT_CONVERSATION_FILTER_HEADER,
+  SESSION_EVENT_CONVERSATION_FILTER_VERSION,
+  SESSION_EVENT_PRESENTED_APP_ACTIONS,
+  SESSION_EVENT_PRESENTED_APP_ACTION_NAMES,
+  SESSION_EVENT_PRESENTED_TOOL_LEAVES,
+  SESSION_EVENT_STEP_TYPES,
+  isPresentedSessionToolCall,
+  isPresentedSessionToolName,
+  isSessionModelResponsePhase,
+  presentedAppActionId
+} from "./chunk-UIZWGPHV.js";
+export {
+  SESSION_EVENT_APP_ACTION_CALL_LEAF,
+  SESSION_EVENT_APP_ACTION_ID_SPACE,
+  SESSION_EVENT_BOOKKEEPING_STEP_TYPES,
+  SESSION_EVENT_COMPAT_EXCLUDED_STEP_TYPES,
+  SESSION_EVENT_CONTENT_STEP_TYPES,
+  SESSION_EVENT_CONVERSATION_FILTER_HEADER,
+  SESSION_EVENT_CONVERSATION_FILTER_VERSION,
+  SESSION_EVENT_PRESENTED_APP_ACTIONS,
+  SESSION_EVENT_PRESENTED_APP_ACTION_NAMES,
+  SESSION_EVENT_PRESENTED_TOOL_LEAVES,
+  SESSION_EVENT_STEP_TYPES,
+  isPresentedSessionToolCall,
+  isPresentedSessionToolName,
+  isSessionModelResponsePhase,
+  presentedAppActionId
+};
+//# sourceMappingURL=session-history.js.map

package/dist/session-history.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/session-list-entries.d.ts

@@ -0,0 +1,8 @@
+import type { Session, SessionListEntry } from "./index.js";
+/** Explicit list projection. Detail/configuration remains available from getSession. */
+export type SessionListEntryInput = Omit<SessionListEntry, "displayTitle" | "renameSeed" | "scheduledTaskId" | "siteOrigin" | "pinned" | "pinnedAt" | "pinVersion" | "unread" | "activelyWorking" | "attentionVersion" | "archived" | "archivedAt" | "archiveVersion" | "description" | "avatar"> & {
+    /** Absent from older servers' rows and SDK-projected sessions. */
+    description?: string | null | undefined;
+    avatar?: Session["avatar"] | undefined;
+} & Partial<Pick<Session, "pinned" | "pinnedAt" | "pinVersion" | "unread" | "activelyWorking" | "attentionVersion" | "archived" | "archivedAt" | "archiveVersion">> & Pick<Session, "metadata" | "initialMessage">;
+export declare function sessionListEntry(session: SessionListEntryInput): SessionListEntry;

package/dist/session-list-entries.js

@@ -0,0 +1,61 @@
+import {
+  deriveAutomaticSessionTitlePreview,
+  deriveSessionDisplayTitle,
+  sessionTitleIsPending
+} from "./chunk-T3HSWMA5.js";
+
+// src/session-list-entries.ts
+function sessionListEntry(session) {
+  const origin = session.metadata._opengeniSiteOrigin;
+  const siteOrigin = origin && typeof origin.siteId === "string" && /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i.test(origin.siteId) && typeof origin.title === "string" ? { siteId: origin.siteId, title: origin.title } : null;
+  const scheduledTaskId = session.metadata.scheduledTaskId;
+  return {
+    id: session.id,
+    workspaceId: session.workspaceId,
+    accountId: session.accountId,
+    status: session.status,
+    backgroundCommandActivity: session.backgroundCommandActivity,
+    hasSchedules: session.hasSchedules,
+    hasUpcomingSchedules: session.hasUpcomingSchedules,
+    waitingForEvents: session.waitingForEvents,
+    automationWait: session.automationWait,
+    title: session.title,
+    titleSource: session.titleSource,
+    description: session.description ?? null,
+    avatar: session.avatar ?? null,
+    displayTitle: deriveSessionDisplayTitle(session),
+    renameSeed: sessionTitleIsPending(session) ? deriveAutomaticSessionTitlePreview(session.initialMessage) ?? "" : session.title?.trim() ?? "",
+    scheduledTaskId: typeof scheduledTaskId === "string" && scheduledTaskId.length > 0 ? scheduledTaskId : null,
+    siteOrigin,
+    ...session.model ? { model: session.model } : {},
+    ...session.reasoningEffort ? { reasoningEffort: session.reasoningEffort } : {},
+    createdBy: session.createdBy,
+    channelId: session.channelId,
+    parentSessionId: session.parentSessionId,
+    rootSessionId: session.rootSessionId,
+    effectiveControl: session.effectiveControl,
+    inputWait: session.inputWait,
+    lastSequence: session.lastSequence,
+    pinned: session.pinned ?? false,
+    pinnedAt: session.pinnedAt ?? null,
+    pinVersion: session.pinVersion ?? 0,
+    unread: session.unread ?? false,
+    activelyWorking: session.activelyWorking ?? false,
+    attentionVersion: session.attentionVersion ?? 0,
+    archived: session.archived ?? false,
+    archivedAt: session.archivedAt ?? null,
+    importedArchive: session.importedArchive,
+    ...session.retention ? { retention: session.retention } : {},
+    archiveVersion: session.archiveVersion ?? 0,
+    treeStats: session.treeStats,
+    requiresActionSince: session.requiresActionSince,
+    // Lets lists tell a runtime-held session apart from one waiting on a person.
+    ...session.admissionBlock !== void 0 ? { admissionBlock: session.admissionBlock } : {},
+    createdAt: session.createdAt,
+    updatedAt: session.updatedAt
+  };
+}
+export {
+  sessionListEntry
+};
+//# sourceMappingURL=session-list-entries.js.map

package/dist/session-list-entries.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/session-list-entries.ts"],"sourcesContent":["import type { Session, SessionListEntry } from \"./index\";\nimport {\n  deriveAutomaticSessionTitlePreview,\n  deriveSessionDisplayTitle,\n  sessionTitleIsPending,\n} from \"./session-titles\";\n\n/** Explicit list projection. Detail/configuration remains available from getSession. */\nexport type SessionListEntryInput = Omit<\n  SessionListEntry,\n  | \"displayTitle\"\n  | \"renameSeed\"\n  | \"scheduledTaskId\"\n  | \"siteOrigin\"\n  | \"pinned\"\n  | \"pinnedAt\"\n  | \"pinVersion\"\n  | \"unread\"\n  | \"activelyWorking\"\n  | \"attentionVersion\"\n  | \"archived\"\n  | \"archivedAt\"\n  | \"archiveVersion\"\n  | \"description\"\n  | \"avatar\"\n> & {\n  /** Absent from older servers' rows and SDK-projected sessions. */\n  description?: string | null | undefined;\n  avatar?: Session[\"avatar\"] | undefined;\n} & Partial<\n    Pick<\n      Session,\n      | \"pinned\"\n      | \"pinnedAt\"\n      | \"pinVersion\"\n      | \"unread\"\n      | \"activelyWorking\"\n      | \"attentionVersion\"\n      | \"archived\"\n      | \"archivedAt\"\n      | \"archiveVersion\"\n    >\n  > &\n  Pick<Session, \"metadata\" | \"initialMessage\">;\n\nexport function sessionListEntry(session: SessionListEntryInput): SessionListEntry {\n  const origin = session.metadata._opengeniSiteOrigin as\n    | { siteId?: unknown; title?: unknown }\n    | undefined;\n  const siteOrigin =\n    origin &&\n    typeof origin.siteId === \"string\" &&\n    /^[\\da-f]{8}-[\\da-f]{4}-[\\da-f]{4}-[\\da-f]{4}-[\\da-f]{12}$/i.test(origin.siteId) &&\n    typeof origin.title === \"string\"\n      ? { siteId: origin.siteId, title: origin.title }\n      : null;\n  const scheduledTaskId = session.metadata.scheduledTaskId;\n  return {\n    id: session.id,\n    workspaceId: session.workspaceId,\n    accountId: session.accountId,\n    status: session.status,\n    backgroundCommandActivity: session.backgroundCommandActivity,\n    hasSchedules: session.hasSchedules,\n    hasUpcomingSchedules: session.hasUpcomingSchedules,\n    waitingForEvents: session.waitingForEvents,\n    automationWait: session.automationWait,\n    title: session.title,\n    titleSource: session.titleSource,\n    description: session.description ?? null,\n    avatar: session.avatar ?? null,\n    displayTitle: deriveSessionDisplayTitle(session),\n    renameSeed: sessionTitleIsPending(session)\n      ? (deriveAutomaticSessionTitlePreview(session.initialMessage) ?? \"\")\n      : (session.title?.trim() ?? \"\"),\n    scheduledTaskId:\n      typeof scheduledTaskId === \"string\" && scheduledTaskId.length > 0 ? scheduledTaskId : null,\n    siteOrigin,\n    ...(session.model ? { model: session.model } : {}),\n    ...(session.reasoningEffort ? { reasoningEffort: session.reasoningEffort } : {}),\n    createdBy: session.createdBy,\n    channelId: session.channelId,\n    parentSessionId: session.parentSessionId,\n    rootSessionId: session.rootSessionId,\n    effectiveControl: session.effectiveControl,\n    inputWait: session.inputWait,\n    lastSequence: session.lastSequence,\n    pinned: session.pinned ?? false,\n    pinnedAt: session.pinnedAt ?? null,\n    pinVersion: session.pinVersion ?? 0,\n    unread: session.unread ?? false,\n    activelyWorking: session.activelyWorking ?? false,\n    attentionVersion: session.attentionVersion ?? 0,\n    archived: session.archived ?? false,\n    archivedAt: session.archivedAt ?? null,\n    importedArchive: session.importedArchive,\n    ...(session.retention ? { retention: session.retention } : {}),\n    archiveVersion: session.archiveVersion ?? 0,\n    treeStats: session.treeStats,\n    requiresActionSince: session.requiresActionSince,\n    // Lets lists tell a runtime-held session apart from one waiting on a person.\n    ...(session.admissionBlock !== undefined ? { admissionBlock: session.admissionBlock } : {}),\n    createdAt: session.createdAt,\n    updatedAt: session.updatedAt,\n  };\n}\n"],"mappings":";;;;;;;AA6CO,SAAS,iBAAiB,SAAkD;AACjF,QAAM,SAAS,QAAQ,SAAS;AAGhC,QAAM,aACJ,UACA,OAAO,OAAO,WAAW,YACzB,6DAA6D,KAAK,OAAO,MAAM,KAC/E,OAAO,OAAO,UAAU,WACpB,EAAE,QAAQ,OAAO,QAAQ,OAAO,OAAO,MAAM,IAC7C;AACN,QAAM,kBAAkB,QAAQ,SAAS;AACzC,SAAO;AAAA,IACL,IAAI,QAAQ;AAAA,IACZ,aAAa,QAAQ;AAAA,IACrB,WAAW,QAAQ;AAAA,IACnB,QAAQ,QAAQ;AAAA,IAChB,2BAA2B,QAAQ;AAAA,IACnC,cAAc,QAAQ;AAAA,IACtB,sBAAsB,QAAQ;AAAA,IAC9B,kBAAkB,QAAQ;AAAA,IAC1B,gBAAgB,QAAQ;AAAA,IACxB,OAAO,QAAQ;AAAA,IACf,aAAa,QAAQ;AAAA,IACrB,aAAa,QAAQ,eAAe;AAAA,IACpC,QAAQ,QAAQ,UAAU;AAAA,IAC1B,cAAc,0BAA0B,OAAO;AAAA,IAC/C,YAAY,sBAAsB,OAAO,IACpC,mCAAmC,QAAQ,cAAc,KAAK,KAC9D,QAAQ,OAAO,KAAK,KAAK;AAAA,IAC9B,iBACE,OAAO,oBAAoB,YAAY,gBAAgB,SAAS,IAAI,kBAAkB;AAAA,IACxF;AAAA,IACA,GAAI,QAAQ,QAAQ,EAAE,OAAO,QAAQ,MAAM,IAAI,CAAC;AAAA,IAChD,GAAI,QAAQ,kBAAkB,EAAE,iBAAiB,QAAQ,gBAAgB,IAAI,CAAC;AAAA,IAC9E,WAAW,QAAQ;AAAA,IACnB,WAAW,QAAQ;AAAA,IACnB,iBAAiB,QAAQ;AAAA,IACzB,eAAe,QAAQ;AAAA,IACvB,kBAAkB,QAAQ;AAAA,IAC1B,WAAW,QAAQ;AAAA,IACnB,cAAc,QAAQ;AAAA,IACtB,QAAQ,QAAQ,UAAU;AAAA,IAC1B,UAAU,QAAQ,YAAY;AAAA,IAC9B,YAAY,QAAQ,cAAc;AAAA,IAClC,QAAQ,QAAQ,UAAU;AAAA,IAC1B,iBAAiB,QAAQ,mBAAmB;AAAA,IAC5C,kBAAkB,QAAQ,oBAAoB;AAAA,IAC9C,UAAU,QAAQ,YAAY;AAAA,IAC9B,YAAY,QAAQ,cAAc;AAAA,IAClC,iBAAiB,QAAQ;AAAA,IACzB,GAAI,QAAQ,YAAY,EAAE,WAAW,QAAQ,UAAU,IAAI,CAAC;AAAA,IAC5D,gBAAgB,QAAQ,kBAAkB;AAAA,IAC1C,WAAW,QAAQ;AAAA,IACnB,qBAAqB,QAAQ;AAAA;AAAA,IAE7B,GAAI,QAAQ,mBAAmB,SAAY,EAAE,gBAAgB,QAAQ,eAAe,IAAI,CAAC;AAAA,IACzF,WAAW,QAAQ;AAAA,IACnB,WAAW,QAAQ;AAAA,EACrB;AACF;","names":[]}

package/dist/session-mcp-projections.d.ts

@@ -1,6 +1,12 @@
 import type { SessionGoalStatus, SessionStatus } from "./session-topology-primitives.js";
 import type { WorkDiscoveryProjection } from "./work-claims.js";
 import type { Session, SessionQueueSnapshot } from "./index.js";
+/** 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";
 /** Search evidence is inseparable from matching; presentation opts never weaken search. */
@@ -157,7 +163,7 @@ export type SessionMcpMonitoringSource = {
 };
 /** Closed management projection shared by adapters; never includes session configuration.
  * Apply target/ancestor authorization projection to session before calling. */
-export declare function compactSessionMcpDetail(session: Session, monitoring: SessionMcpMonitoringSource, queue: SessionQueueSnapshot | null): {
+export declare function compactSessionMcpDetail(session: Session, monitoring: SessionMcpMonitoringSource, queue: SessionQueueSnapshot | SessionMcpQueueSummary | null): {
     id: string;
     projectId?: string;
     title: string | null;
@@ -166,6 +172,12 @@ export declare function compactSessionMcpDetail(session: Session, monitoring: Se
     parentSessionId?: string;
     activeTurnId?: string;
     lastSequence: number;
+    archive?: {
+        state: "archived" | "archiving";
+        archivedAt: string | null;
+        readOnly: boolean;
+    };
+    keepLive?: boolean;
     goal?: {
         status: "active" | "completed" | "paused";
         summary: string | null;

package/dist/session-mcp-tool-permissions.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+/**
+ * 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 declare const MCP_TOOL_RECOMMENDED_PERMISSION_META_KEY: "opengeni/recommendedPermission";
+/** True when a listed MCP tool recommends Ask through its `_meta`. */
+export declare function mcpToolRecommendsApproval(tool: object): boolean;
+export declare const SessionMcpToolPermissionsQuery: z.ZodObject<{
+    serverId: z.ZodString;
+    url: z.ZodString;
+}, z.core.$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 declare const SessionMcpToolPermissionsResponse: z.ZodObject<{
+    connectionId: z.ZodString;
+    serverId: z.ZodString;
+    defaultPermission: z.ZodNullable<z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+        block: "block";
+    }>>;
+    tools: z.ZodArray<z.ZodObject<{
+        toolName: z.ZodString;
+        permission: z.ZodEnum<{
+            allow: "allow";
+            ask: "ask";
+            block: "block";
+        }>;
+    }, z.core.$strip>>;
+    revision: z.ZodString;
+    canManage: z.ZodBoolean;
+    appliesTo: z.ZodLiteral<"next_attempt">;
+}, z.core.$strip>;
+export type SessionMcpToolPermissionsResponse = z.infer<typeof SessionMcpToolPermissionsResponse>;
+export declare const UpdateSessionMcpToolPermissionsRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    serverId: z.ZodString;
+    url: z.ZodString;
+    target: z.ZodLiteral<"default">;
+    permission: z.ZodNullable<z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+        block: "block";
+    }>>;
+    expectedRevision: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    serverId: z.ZodString;
+    url: z.ZodString;
+    target: z.ZodLiteral<"tools">;
+    toolNames: z.ZodArray<z.ZodString>;
+    permission: z.ZodNullable<z.ZodEnum<{
+        allow: "allow";
+        ask: "ask";
+        block: "block";
+    }>>;
+    expectedRevision: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "target">;
+export type UpdateSessionMcpToolPermissionsRequest = z.infer<typeof UpdateSessionMcpToolPermissionsRequest>;

package/dist/session-target.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/** Conversational context only. Never an authority or an implicit dispatch destination. */
+export declare const SessionTargetContext: z.ZodObject<{
+    version: z.ZodNumber;
+    sessionId: z.ZodNullable<z.ZodString>;
+    operationId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type SessionTargetContext = z.infer<typeof SessionTargetContext>;
+export declare const SetSessionTargetRequest: z.ZodObject<{
+    sessionId: z.ZodNullable<z.ZodString>;
+    expectedVersion: z.ZodNumber;
+    operationId: z.ZodString;
+}, z.core.$strict>;
+export type SetSessionTargetRequest = z.infer<typeof SetSessionTargetRequest>;
+export declare const SESSION_TARGET_CONTEXT_KEY = "conversationTargetV1";
+export declare function sessionTargetContext(metadata: Record<string, unknown>): SessionTargetContext;
+/** CAS plus exact retry replay; an old retry cannot restore a subsequently cleared target. */
+export declare function nextSessionTargetContext(current: SessionTargetContext, request: SetSessionTargetRequest): SessionTargetContext;

package/dist/session-titles.d.ts

@@ -12,6 +12,7 @@ export declare const AUTOMATIC_SESSION_TITLE_MAX_GRAPHEMES = 80;
  * credential or leave a raw prompt prefix in navigation surfaces.
  */
 export declare const AUTOMATIC_SESSION_TITLE_FALLBACK = "New conversation";
+export declare const PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS = 4096;
 /**
  * Whether a bounded automatic-title candidate contains a credential, URL, or
  * opaque identifier that must stay out of navigation and other display-title
@@ -19,6 +20,13 @@ export declare const AUTOMATIC_SESSION_TITLE_FALLBACK = "New conversation";
  * this helper.
  */
 export declare function containsSensitiveAutomaticSessionTitleValue(value: string): boolean;
+/**
+ * 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 declare function cleanStoredSessionTitle(title: string | null | undefined, titleSource: string | null | undefined): string | null;
 /** Bound an already-normalized automatic-title candidate without splitting graphemes. */
 export declare function boundAutomaticSessionTitle(value: string): string;
 /**

package/dist/session-titles.js

@@ -1,19 +1,23 @@
 import {
   AUTOMATIC_SESSION_TITLE_FALLBACK,
   AUTOMATIC_SESSION_TITLE_MAX_GRAPHEMES,
+  PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS,
   SESSION_TITLE_MAX_CHARACTERS,
   boundAutomaticSessionTitle,
+  cleanStoredSessionTitle,
   containsSensitiveAutomaticSessionTitleValue,
   deriveAutomaticSessionTitlePreview,
   deriveSessionDisplayTitle,
   normalizeAutomaticSessionTitle,
   sessionTitleIsPending
-} from "./chunk-HHZSZYYF.js";
+} from "./chunk-T3HSWMA5.js";
 export {
   AUTOMATIC_SESSION_TITLE_FALLBACK,
   AUTOMATIC_SESSION_TITLE_MAX_GRAPHEMES,
+  PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS,
   SESSION_TITLE_MAX_CHARACTERS,
   boundAutomaticSessionTitle,
+  cleanStoredSessionTitle,
   containsSensitiveAutomaticSessionTitleValue,
   deriveAutomaticSessionTitlePreview,
   deriveSessionDisplayTitle,

package/dist/session-usage-limit-refusal.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare const SESSION_USAGE_LIMIT_SEGMENT: "session_usage_limit";
+/** `SessionGoal.pausedReason` for a goal paused by a task usage limit. */
+export declare const SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON: "session_usage_limit";
+export type ParsedSessionUsageLimitReachedRefusal = {
+    code: "session_usage_limit_reached";
+    basis: "model_api_equivalent_v1";
+    rootSessionId: string;
+    limitMicros: number;
+    usedMicros: number;
+    message: string;
+};
+/**
+ * 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 declare function parseSessionUsageLimitReachedRefusal(value: unknown): ParsedSessionUsageLimitReachedRefusal | null;
+/**
+ * "$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 declare function formatSessionUsageMicros(value: number): string;
+/** Fixed, bounded wording: no reset date, purchase remedy or invoice claim. */
+export declare function sessionUsageLimitReachedMessage(refusal: {
+    limitMicros: number;
+    usedMicros: number;
+}): string;

package/dist/session-usage-limit-refusal.js

@@ -0,0 +1,15 @@
+import {
+  SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON,
+  SESSION_USAGE_LIMIT_SEGMENT,
+  formatSessionUsageMicros,
+  parseSessionUsageLimitReachedRefusal,
+  sessionUsageLimitReachedMessage
+} from "./chunk-7272KVWZ.js";
+export {
+  SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON,
+  SESSION_USAGE_LIMIT_SEGMENT,
+  formatSessionUsageMicros,
+  parseSessionUsageLimitReachedRefusal,
+  sessionUsageLimitReachedMessage
+};
+//# sourceMappingURL=session-usage-limit-refusal.js.map

package/dist/session-usage-limit-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/session-usage-limits.d.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+/**
+ * Per-task (root session) usage limits.
+ *
+ * One optional limit belongs to a root session and is shared by every
+ * descendant. It is measured in integer USD micros ($1 = 1,000,000) of the
+ * canonical pre-margin API-equivalent model cost (`estimatedProviderCostMicros`)
+ * recorded when a model response settles, whatever funds the call (Opengeni
+ * credits, a connected subscription or a workspace-owned key).
+ *
+ * The limit is checked before each new model request; it is not a reservation.
+ * Requests already admitted may finish and take recorded usage above the
+ * limit, and concurrently admitted requests may overshoot together. Usage
+ * without a known price is excluded from the total and disclosed as partial
+ * coverage instead of being valued at zero. It is not an invoice cap.
+ */
+/** Versioned measurement basis, exposed so a future basis cannot be confused with this one. */
+export declare const SESSION_USAGE_LIMIT_BASIS: "model_api_equivalent_v1";
+export declare const SessionUsageLimitBasis: z.ZodLiteral<"model_api_equivalent_v1">;
+export type SessionUsageLimitBasis = z.infer<typeof SessionUsageLimitBasis>;
+export declare const SESSION_USAGE_LIMIT_MICROS_PER_DOLLAR = 1000000;
+/** $10M: the largest configurable limit, far inside safe integers. Usage itself is never clamped. */
+export declare const SESSION_USAGE_LIMIT_MAX_MICROS: number;
+/** A configured limit. Zero is a valid immediate stop; `null` (not this schema) means no limit. */
+export declare const SessionUsageLimitMicros: z.ZodNumber;
+export type SessionUsageLimitMicros = z.infer<typeof SessionUsageLimitMicros>;
+/**
+ * - `unlimited`: no limit is configured; usage is still recorded.
+ * - `within`: a limit is configured and recorded usage is below it.
+ * - `reached`: recorded usage is at or above the limit; new model requests are refused.
+ * - `preparing`: historical usage for a task created before this feature is
+ *   still being imported; the total is not yet meaningful and a new limit
+ *   cannot be set until it finishes.
+ * - `unavailable`: the usage state could not be read. Never treat it as zero or unlimited.
+ */
+export declare const SessionUsageLimitStatus: z.ZodEnum<{
+    preparing: "preparing";
+    reached: "reached";
+    unavailable: "unavailable";
+    unlimited: "unlimited";
+    within: "within";
+}>;
+export type SessionUsageLimitStatus = z.infer<typeof SessionUsageLimitStatus>;
+/**
+ * `complete`: every recorded model response of this task was metered live.
+ * `legacy_partial`: the task predates usage limits; available historical cost
+ * snapshots were imported, but older usage may be missing. This never upgrades
+ * to complete, because a missing old record is not proof of no usage.
+ * `preparing`: the historical import has not finished.
+ */
+export declare const SessionUsageLimitHistory: z.ZodEnum<{
+    complete: "complete";
+    legacy_partial: "legacy_partial";
+    preparing: "preparing";
+}>;
+export type SessionUsageLimitHistory = z.infer<typeof SessionUsageLimitHistory>;
+export declare const SessionUsageLimit: z.ZodObject<{
+    basis: z.ZodLiteral<"model_api_equivalent_v1">;
+    rootSessionId: z.ZodString;
+    inherited: z.ZodBoolean;
+    status: z.ZodEnum<{
+        preparing: "preparing";
+        reached: "reached";
+        unavailable: "unavailable";
+        unlimited: "unlimited";
+        within: "within";
+    }>;
+    limitMicros: z.ZodNullable<z.ZodNumber>;
+    usedMicros: z.ZodNullable<z.ZodNumber>;
+    version: z.ZodNumber;
+    usageRevision: z.ZodNumber;
+    history: z.ZodEnum<{
+        complete: "complete";
+        legacy_partial: "legacy_partial";
+        preparing: "preparing";
+    }>;
+    coverage: z.ZodEnum<{
+        complete: "complete";
+        partial: "partial";
+    }>;
+    pricedCalls: z.ZodNumber;
+    freeCalls: z.ZodNumber;
+    unpricedCalls: z.ZodNumber;
+    updatedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type SessionUsageLimit = z.infer<typeof SessionUsageLimit>;
+/**
+ * Compare-and-set write of a root task's limit. `expectedVersion` is the
+ * `version` the caller last read; a stale version returns 409. A replay of the
+ * same `operationId` with the same request returns the committed result.
+ */
+export declare const SetSessionUsageLimitRequest: z.ZodObject<{
+    limitMicros: z.ZodNullable<z.ZodNumber>;
+    expectedVersion: z.ZodNumber;
+    operationId: z.ZodString;
+}, z.core.$strict>;
+export type SetSessionUsageLimitRequest = z.infer<typeof SetSessionUsageLimitRequest>;
+/** Typed refusal for a fresh model request, message or goal resume after the limit is reached. */
+export declare const SessionUsageLimitReachedRefusal: z.ZodObject<{
+    code: z.ZodLiteral<"session_usage_limit_reached">;
+    basis: z.ZodLiteral<"model_api_equivalent_v1">;
+    rootSessionId: z.ZodString;
+    limitMicros: z.ZodNumber;
+    usedMicros: z.ZodNumber;
+    message: z.ZodString;
+}, z.core.$strict>;
+export type SessionUsageLimitReachedRefusal = z.infer<typeof SessionUsageLimitReachedRefusal>;
+/** Typed error codes for the usage-limit routes. */
+export declare const SessionUsageLimitErrorCode: z.ZodEnum<{
+    session_usage_limit_conflict: "session_usage_limit_conflict";
+    session_usage_limit_disabled: "session_usage_limit_disabled";
+    session_usage_limit_forbidden: "session_usage_limit_forbidden";
+    session_usage_limit_not_root: "session_usage_limit_not_root";
+    session_usage_limit_preparing: "session_usage_limit_preparing";
+    session_usage_limit_reached: "session_usage_limit_reached";
+    session_usage_limit_unavailable: "session_usage_limit_unavailable";
+}>;
+export type SessionUsageLimitErrorCode = z.infer<typeof SessionUsageLimitErrorCode>;
+/** The durable event appended to a root's stream when an authorized person changes its limit. */
+export declare const SessionUsageLimitUpdatedPayload: z.ZodObject<{
+    basis: z.ZodLiteral<"model_api_equivalent_v1">;
+    limitMicros: z.ZodNullable<z.ZodNumber>;
+    previousLimitMicros: z.ZodNullable<z.ZodNumber>;
+    version: z.ZodNumber;
+}, z.core.$strict>;
+export type SessionUsageLimitUpdatedPayload = z.infer<typeof SessionUsageLimitUpdatedPayload>;
+export { formatSessionUsageMicros, parseSessionUsageLimitReachedRefusal, SESSION_USAGE_LIMIT_SEGMENT, SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON, sessionUsageLimitReachedMessage, } from "./session-usage-limit-refusal.js";

package/dist/session-usage-limits.js

@@ -0,0 +1,43 @@
+import {
+  SESSION_USAGE_LIMIT_BASIS,
+  SESSION_USAGE_LIMIT_MAX_MICROS,
+  SESSION_USAGE_LIMIT_MICROS_PER_DOLLAR,
+  SessionUsageLimit,
+  SessionUsageLimitBasis,
+  SessionUsageLimitErrorCode,
+  SessionUsageLimitHistory,
+  SessionUsageLimitMicros,
+  SessionUsageLimitReachedRefusal,
+  SessionUsageLimitStatus,
+  SessionUsageLimitUpdatedPayload,
+  SetSessionUsageLimitRequest
+} from "./chunk-5RWB6QVL.js";
+import "./chunk-AQYDZUJV.js";
+import {
+  SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON,
+  SESSION_USAGE_LIMIT_SEGMENT,
+  formatSessionUsageMicros,
+  parseSessionUsageLimitReachedRefusal,
+  sessionUsageLimitReachedMessage
+} from "./chunk-7272KVWZ.js";
+import "./chunk-56SNIMDO.js";
+export {
+  SESSION_USAGE_LIMIT_BASIS,
+  SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON,
+  SESSION_USAGE_LIMIT_MAX_MICROS,
+  SESSION_USAGE_LIMIT_MICROS_PER_DOLLAR,
+  SESSION_USAGE_LIMIT_SEGMENT,
+  SessionUsageLimit,
+  SessionUsageLimitBasis,
+  SessionUsageLimitErrorCode,
+  SessionUsageLimitHistory,
+  SessionUsageLimitMicros,
+  SessionUsageLimitReachedRefusal,
+  SessionUsageLimitStatus,
+  SessionUsageLimitUpdatedPayload,
+  SetSessionUsageLimitRequest,
+  formatSessionUsageMicros,
+  parseSessionUsageLimitReachedRefusal,
+  sessionUsageLimitReachedMessage
+};
+//# sourceMappingURL=session-usage-limits.js.map

package/dist/session-usage-limits.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}