@opengeni/contracts 2.9.2 → 2.13.0-canary.0

package/dist/mcp-oauth.d.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+export declare const MCP_OAUTH_SCOPE: "mcp:access";
+export declare const MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS: number;
+export declare const MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS: number;
+export declare const MCP_OAUTH_AUTHORIZATION_CODE_TTL_SECONDS: number;
+export declare const MCP_OAUTH_CONSENT_TTL_SECONDS: number;
+export declare const McpOAuthClientRegistrationRequest: z.ZodObject<{
+    redirect_uris: z.ZodArray<z.ZodString>;
+    client_name: z.ZodOptional<z.ZodString>;
+    application_type: z.ZodOptional<z.ZodEnum<{
+        native: "native";
+        web: "web";
+    }>>;
+    token_endpoint_auth_method: z.ZodDefault<z.ZodLiteral<"none">>;
+    scope: z.ZodOptional<z.ZodLiteral<"mcp:access">>;
+    grant_types: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        authorization_code: "authorization_code";
+        refresh_token: "refresh_token";
+    }>>>;
+    response_types: z.ZodDefault<z.ZodArray<z.ZodLiteral<"code">>>;
+}, z.core.$strict>;
+export type McpOAuthClientRegistrationRequest = z.infer<typeof McpOAuthClientRegistrationRequest>;
+export declare const McpOAuthClientRegistrationResponse: z.ZodObject<{
+    redirect_uris: z.ZodArray<z.ZodString>;
+    client_name: z.ZodOptional<z.ZodString>;
+    application_type: z.ZodOptional<z.ZodEnum<{
+        native: "native";
+        web: "web";
+    }>>;
+    token_endpoint_auth_method: z.ZodDefault<z.ZodLiteral<"none">>;
+    scope: z.ZodOptional<z.ZodLiteral<"mcp:access">>;
+    grant_types: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        authorization_code: "authorization_code";
+        refresh_token: "refresh_token";
+    }>>>;
+    response_types: z.ZodDefault<z.ZodArray<z.ZodLiteral<"code">>>;
+    client_id: z.ZodString;
+    client_id_issued_at: z.ZodNumber;
+}, z.core.$strict>;
+export type McpOAuthClientRegistrationResponse = z.infer<typeof McpOAuthClientRegistrationResponse>;
+export declare const McpOAuthTokenResponse: z.ZodObject<{
+    access_token: z.ZodString;
+    token_type: z.ZodLiteral<"Bearer">;
+    expires_in: z.ZodNumber;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    scope: z.ZodLiteral<"mcp:access">;
+}, z.core.$strip>;
+export type McpOAuthTokenResponse = z.infer<typeof McpOAuthTokenResponse>;
+export declare const McpOAuthProtectedResourceMetadata: z.ZodObject<{
+    resource: z.ZodString;
+    authorization_servers: z.ZodArray<z.ZodString>;
+    scopes_supported: z.ZodArray<z.ZodLiteral<"mcp:access">>;
+    bearer_methods_supported: z.ZodArray<z.ZodLiteral<"header">>;
+}, z.core.$strip>;
+export type McpOAuthProtectedResourceMetadata = z.infer<typeof McpOAuthProtectedResourceMetadata>;
+export declare const McpOAuthAuthorizationServerMetadata: z.ZodObject<{
+    issuer: z.ZodString;
+    authorization_endpoint: z.ZodString;
+    token_endpoint: z.ZodString;
+    registration_endpoint: z.ZodString;
+    response_types_supported: z.ZodArray<z.ZodLiteral<"code">>;
+    grant_types_supported: z.ZodArray<z.ZodEnum<{
+        authorization_code: "authorization_code";
+        refresh_token: "refresh_token";
+    }>>;
+    code_challenge_methods_supported: z.ZodArray<z.ZodLiteral<"S256">>;
+    token_endpoint_auth_methods_supported: z.ZodArray<z.ZodLiteral<"none">>;
+    scopes_supported: z.ZodArray<z.ZodLiteral<"mcp:access">>;
+    authorization_response_iss_parameter_supported: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type McpOAuthAuthorizationServerMetadata = z.infer<typeof McpOAuthAuthorizationServerMetadata>;

package/dist/model-context-inspector.d.ts

@@ -0,0 +1,205 @@
+import { z } from "zod";
+export declare const MODEL_CONTEXT_SNAPSHOT_VERSION: 1;
+export declare const MODEL_CONTEXT_INSTRUCTIONS_MAX_UTF8_BYTES: number;
+export declare const MODEL_CONTEXT_SNAPSHOT_MAX_UTF8_BYTES: number;
+export declare const MODEL_CONTEXT_LAYER_MAX_COUNT = 16;
+export declare const MODEL_CONTEXT_TOOL_MAX_COUNT = 2048;
+export declare const MODEL_CONTEXT_SKILL_MAX_COUNT = 1024;
+export declare const ModelContextInstructionLayerId: z.ZodEnum<{
+    codemode: "codemode";
+    genesis_title: "genesis_title";
+    git_bindings: "git_bindings";
+    operational_contract: "operational_contract";
+    persona_and_core: "persona_and_core";
+    sandbox_filesystem: "sandbox_filesystem";
+    sandbox_preamble: "sandbox_preamble";
+    sdk_capability_instructions: "sdk_capability_instructions";
+    sent_system_instructions: "sent_system_instructions";
+    session_instructions: "session_instructions";
+    workspace_governance: "workspace_governance";
+    workspace_memory: "workspace_memory";
+}>;
+export type ModelContextInstructionLayerId = z.infer<typeof ModelContextInstructionLayerId>;
+export declare const ModelContextInstructionLayer: z.ZodObject<{
+    id: z.ZodEnum<{
+        codemode: "codemode";
+        genesis_title: "genesis_title";
+        git_bindings: "git_bindings";
+        operational_contract: "operational_contract";
+        persona_and_core: "persona_and_core";
+        sandbox_filesystem: "sandbox_filesystem";
+        sandbox_preamble: "sandbox_preamble";
+        sdk_capability_instructions: "sdk_capability_instructions";
+        sent_system_instructions: "sent_system_instructions";
+        session_instructions: "session_instructions";
+        workspace_governance: "workspace_governance";
+        workspace_memory: "workspace_memory";
+    }>;
+    title: z.ZodString;
+    content: z.ZodString;
+    utf8Bytes: z.ZodNumber;
+    estimatedTokens: z.ZodNumber;
+}, z.core.$strict>;
+export type ModelContextInstructionLayer = z.infer<typeof ModelContextInstructionLayer>;
+export declare const ModelContextToolVisibility: z.ZodEnum<{
+    eager: "eager";
+    searchable: "searchable";
+}>;
+export type ModelContextToolVisibility = z.infer<typeof ModelContextToolVisibility>;
+export declare const ModelContextTool: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodString;
+    visibility: z.ZodEnum<{
+        eager: "eager";
+        searchable: "searchable";
+    }>;
+    description: z.ZodOptional<z.ZodString>;
+    namespace: z.ZodOptional<z.ZodString>;
+    schema: z.ZodOptional<z.ZodUnknown>;
+    utf8Bytes: z.ZodNumber;
+    estimatedTokens: z.ZodNumber;
+}, z.core.$strict>;
+export type ModelContextTool = z.infer<typeof ModelContextTool>;
+export declare const ModelContextSkillKind: z.ZodEnum<{
+    native_tool_skill: "native_tool_skill";
+    preference_descriptor: "preference_descriptor";
+    runtime_skill: "runtime_skill";
+}>;
+export type ModelContextSkillKind = z.infer<typeof ModelContextSkillKind>;
+export declare const ModelContextSkill: z.ZodObject<{
+    kind: z.ZodEnum<{
+        native_tool_skill: "native_tool_skill";
+        preference_descriptor: "preference_descriptor";
+        runtime_skill: "runtime_skill";
+    }>;
+    name: z.ZodString;
+    description: z.ZodString;
+    source: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ModelContextSkill = z.infer<typeof ModelContextSkill>;
+export declare const ModelContextTokenCounts: z.ZodObject<{
+    instructions: z.ZodNumber;
+    tools: z.ZodNumber;
+    prefix: z.ZodNumber;
+}, z.core.$strict>;
+export type ModelContextTokenCounts = z.infer<typeof ModelContextTokenCounts>;
+export declare const ModelContextSnapshot: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    capturedAt: z.ZodString;
+    source: z.ZodLiteral<"model_request">;
+    requestIndex: z.ZodNumber;
+    instructions: z.ZodString;
+    layers: z.ZodArray<z.ZodObject<{
+        id: z.ZodEnum<{
+            codemode: "codemode";
+            genesis_title: "genesis_title";
+            git_bindings: "git_bindings";
+            operational_contract: "operational_contract";
+            persona_and_core: "persona_and_core";
+            sandbox_filesystem: "sandbox_filesystem";
+            sandbox_preamble: "sandbox_preamble";
+            sdk_capability_instructions: "sdk_capability_instructions";
+            sent_system_instructions: "sent_system_instructions";
+            session_instructions: "session_instructions";
+            workspace_governance: "workspace_governance";
+            workspace_memory: "workspace_memory";
+        }>;
+        title: z.ZodString;
+        content: z.ZodString;
+        utf8Bytes: z.ZodNumber;
+        estimatedTokens: z.ZodNumber;
+    }, z.core.$strict>>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+        visibility: z.ZodEnum<{
+            eager: "eager";
+            searchable: "searchable";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        namespace: z.ZodOptional<z.ZodString>;
+        schema: z.ZodOptional<z.ZodUnknown>;
+        utf8Bytes: z.ZodNumber;
+        estimatedTokens: z.ZodNumber;
+    }, z.core.$strict>>;
+    skills: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            native_tool_skill: "native_tool_skill";
+            preference_descriptor: "preference_descriptor";
+            runtime_skill: "runtime_skill";
+        }>;
+        name: z.ZodString;
+        description: z.ZodString;
+        source: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    tokens: z.ZodObject<{
+        instructions: z.ZodNumber;
+        tools: z.ZodNumber;
+        prefix: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ModelContextSnapshot = z.infer<typeof ModelContextSnapshot>;
+export declare const SessionModelContextResponse: z.ZodObject<{
+    sessionId: z.ZodString;
+    attemptId: z.ZodNullable<z.ZodString>;
+    turnId: z.ZodNullable<z.ZodString>;
+    snapshot: z.ZodNullable<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        capturedAt: z.ZodString;
+        source: z.ZodLiteral<"model_request">;
+        requestIndex: z.ZodNumber;
+        instructions: z.ZodString;
+        layers: z.ZodArray<z.ZodObject<{
+            id: z.ZodEnum<{
+                codemode: "codemode";
+                genesis_title: "genesis_title";
+                git_bindings: "git_bindings";
+                operational_contract: "operational_contract";
+                persona_and_core: "persona_and_core";
+                sandbox_filesystem: "sandbox_filesystem";
+                sandbox_preamble: "sandbox_preamble";
+                sdk_capability_instructions: "sdk_capability_instructions";
+                sent_system_instructions: "sent_system_instructions";
+                session_instructions: "session_instructions";
+                workspace_governance: "workspace_governance";
+                workspace_memory: "workspace_memory";
+            }>;
+            title: z.ZodString;
+            content: z.ZodString;
+            utf8Bytes: z.ZodNumber;
+            estimatedTokens: z.ZodNumber;
+        }, z.core.$strict>>;
+        tools: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            visibility: z.ZodEnum<{
+                eager: "eager";
+                searchable: "searchable";
+            }>;
+            description: z.ZodOptional<z.ZodString>;
+            namespace: z.ZodOptional<z.ZodString>;
+            schema: z.ZodOptional<z.ZodUnknown>;
+            utf8Bytes: z.ZodNumber;
+            estimatedTokens: z.ZodNumber;
+        }, z.core.$strict>>;
+        skills: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                native_tool_skill: "native_tool_skill";
+                preference_descriptor: "preference_descriptor";
+                runtime_skill: "runtime_skill";
+            }>;
+            name: z.ZodString;
+            description: z.ZodString;
+            source: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        tokens: z.ZodObject<{
+            instructions: z.ZodNumber;
+            tools: z.ZodNumber;
+            prefix: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SessionModelContextResponse = z.infer<typeof SessionModelContextResponse>;

package/dist/model-picker-order.d.ts

@@ -0,0 +1,23 @@
+export type ModelPickerBillingClass = "opengeni_credits" | "external" | "codex_subscription" | "supergrok_subscription" | "byok" | "organization_byok";
+export type ModelPickerBillingCandidate = {
+    source?: string | undefined;
+    cost?: "free" | "credits" | "subscription" | "workspace" | "organization" | undefined;
+    billing?: {
+        upstreamPayer?: string | undefined;
+        metering?: string | undefined;
+    } | undefined;
+    credentialSource?: {
+        kind?: string | undefined;
+        provider?: string | undefined;
+    } | undefined;
+};
+export declare function modelPickerBillingClassFor(model: ModelPickerBillingCandidate): ModelPickerBillingClass;
+export declare function compareModelPickerOrder(left: {
+    billingClass: ModelPickerBillingClass;
+    selectable: boolean;
+    label: string;
+}, right: {
+    billingClass: ModelPickerBillingClass;
+    selectable: boolean;
+    label: string;
+}): number;

package/dist/model-picker-order.js

@@ -0,0 +1,42 @@
+// src/model-picker-order.ts
+var MODEL_PICKER_BILLING_CLASS_ORDER = [
+  "opengeni_credits",
+  "external",
+  "codex_subscription",
+  "supergrok_subscription",
+  "byok",
+  "organization_byok"
+];
+function modelPickerBillingClassFor(model) {
+  if (model.cost === "credits") return "opengeni_credits";
+  if (model.cost === "workspace") return "byok";
+  if (model.cost === "organization") return "organization_byok";
+  const source = model.source;
+  const credential = model.credentialSource;
+  const payer = model.billing?.upstreamPayer;
+  if (model.billing?.metering === "external" && payer === "deployment") {
+    return "external";
+  }
+  if (source === "supergrok" || credential?.kind === "connected_subscription" && credential.provider === "xai") {
+    return "supergrok_subscription";
+  }
+  if (source === "codex" || credential?.kind === "connected_subscription" || payer === "connected_subscription") {
+    return "codex_subscription";
+  }
+  if (source === "workspace_gateway" || credential?.kind === "workspace_connection" || payer === "workspace") {
+    return "byok";
+  }
+  if (credential?.kind === "organization_connection" || payer === "organization") {
+    return "organization_byok";
+  }
+  return "opengeni_credits";
+}
+function compareModelPickerOrder(left, right) {
+  const classDelta = MODEL_PICKER_BILLING_CLASS_ORDER.indexOf(left.billingClass) - MODEL_PICKER_BILLING_CLASS_ORDER.indexOf(right.billingClass);
+  return classDelta || +right.selectable - +left.selectable || (left.label < right.label ? -1 : left.label > right.label ? 1 : 0);
+}
+export {
+  compareModelPickerOrder,
+  modelPickerBillingClassFor
+};
+//# sourceMappingURL=model-picker-order.js.map

package/dist/model-picker-order.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/model-picker-order.ts"],"sourcesContent":["export type ModelPickerBillingClass =\n  | \"opengeni_credits\"\n  | \"external\"\n  | \"codex_subscription\"\n  | \"supergrok_subscription\"\n  | \"byok\"\n  | \"organization_byok\";\n\n// Every closed billing class has a unique first character. Keeping the order\n// as initials avoids duplicating the full public labels in browser bundles.\nconst MODEL_PICKER_BILLING_CLASS_ORDER: readonly ModelPickerBillingClass[] = [\n  \"opengeni_credits\",\n  \"external\",\n  \"codex_subscription\",\n  \"supergrok_subscription\",\n  \"byok\",\n  \"organization_byok\",\n];\n\nexport type ModelPickerBillingCandidate = {\n  source?: string | undefined;\n  cost?: \"free\" | \"credits\" | \"subscription\" | \"workspace\" | \"organization\" | undefined;\n  billing?:\n    | {\n        upstreamPayer?: string | undefined;\n        metering?: string | undefined;\n      }\n    | undefined;\n  credentialSource?:\n    | {\n        kind?: string | undefined;\n        provider?: string | undefined;\n      }\n    | undefined;\n};\n\nexport function modelPickerBillingClassFor(\n  model: ModelPickerBillingCandidate,\n): ModelPickerBillingClass {\n  if (model.cost === \"credits\") return \"opengeni_credits\";\n  if (model.cost === \"workspace\") return \"byok\";\n  if (model.cost === \"organization\") return \"organization_byok\";\n  const source = model.source;\n  const credential = model.credentialSource;\n  const payer = model.billing?.upstreamPayer;\n  if (model.billing?.metering === \"external\" && payer === \"deployment\") {\n    return \"external\";\n  }\n  if (\n    source === \"supergrok\" ||\n    (credential?.kind === \"connected_subscription\" && credential.provider === \"xai\")\n  ) {\n    return \"supergrok_subscription\";\n  }\n  if (\n    source === \"codex\" ||\n    credential?.kind === \"connected_subscription\" ||\n    payer === \"connected_subscription\"\n  ) {\n    return \"codex_subscription\";\n  }\n  if (\n    source === \"workspace_gateway\" ||\n    credential?.kind === \"workspace_connection\" ||\n    payer === \"workspace\"\n  ) {\n    return \"byok\";\n  }\n  if (credential?.kind === \"organization_connection\" || payer === \"organization\") {\n    return \"organization_byok\";\n  }\n  return \"opengeni_credits\";\n}\n\nexport function compareModelPickerOrder(\n  left: { billingClass: ModelPickerBillingClass; selectable: boolean; label: string },\n  right: { billingClass: ModelPickerBillingClass; selectable: boolean; label: string },\n): number {\n  const classDelta =\n    MODEL_PICKER_BILLING_CLASS_ORDER.indexOf(left.billingClass) -\n    MODEL_PICKER_BILLING_CLASS_ORDER.indexOf(right.billingClass);\n  return (\n    classDelta ||\n    +right.selectable - +left.selectable ||\n    (left.label < right.label ? -1 : left.label > right.label ? 1 : 0)\n  );\n}\n"],"mappings":";AAUA,IAAM,mCAAuE;AAAA,EAC3E;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAmBO,SAAS,2BACd,OACyB;AACzB,MAAI,MAAM,SAAS,UAAW,QAAO;AACrC,MAAI,MAAM,SAAS,YAAa,QAAO;AACvC,MAAI,MAAM,SAAS,eAAgB,QAAO;AAC1C,QAAM,SAAS,MAAM;AACrB,QAAM,aAAa,MAAM;AACzB,QAAM,QAAQ,MAAM,SAAS;AAC7B,MAAI,MAAM,SAAS,aAAa,cAAc,UAAU,cAAc;AACpE,WAAO;AAAA,EACT;AACA,MACE,WAAW,eACV,YAAY,SAAS,4BAA4B,WAAW,aAAa,OAC1E;AACA,WAAO;AAAA,EACT;AACA,MACE,WAAW,WACX,YAAY,SAAS,4BACrB,UAAU,0BACV;AACA,WAAO;AAAA,EACT;AACA,MACE,WAAW,uBACX,YAAY,SAAS,0BACrB,UAAU,aACV;AACA,WAAO;AAAA,EACT;AACA,MAAI,YAAY,SAAS,6BAA6B,UAAU,gBAAgB;AAC9E,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAEO,SAAS,wBACd,MACA,OACQ;AACR,QAAM,aACJ,iCAAiC,QAAQ,KAAK,YAAY,IAC1D,iCAAiC,QAAQ,MAAM,YAAY;AAC7D,SACE,cACA,CAAC,MAAM,aAAa,CAAC,KAAK,eACzB,KAAK,QAAQ,MAAM,QAAQ,KAAK,KAAK,QAAQ,MAAM,QAAQ,IAAI;AAEpE;","names":[]}

package/dist/organization-membership-lifecycle.d.ts

@@ -517,6 +517,23 @@ export declare const CreateOrganizationResponse: z.ZodObject<{
     workspaceId: z.ZodString;
 }, z.core.$strip>;
 export type CreateOrganizationResponse = z.infer<typeof CreateOrganizationResponse>;
+export declare const CreateAdditionalOrganizationRequest: z.ZodObject<{
+    name: z.ZodString;
+    workspaceName: z.ZodString;
+    operationId: z.ZodString;
+}, z.core.$strict>;
+export type CreateAdditionalOrganizationRequest = z.infer<typeof CreateAdditionalOrganizationRequest>;
+export declare const CreateAdditionalOrganizationResponse: z.ZodObject<{
+    organization: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>;
+    workspaceId: z.ZodString;
+    personalWorkspaceId: z.ZodString;
+}, z.core.$strip>;
+export type CreateAdditionalOrganizationResponse = z.infer<typeof CreateAdditionalOrganizationResponse>;
 export declare const UpdateOrganizationNameRequest: z.ZodObject<{
     name: z.ZodString;
     expectedUpdatedAt: z.ZodString;

package/dist/personal-github.js

@@ -1,25 +1,25 @@
 import {
   ConnectionMetadata
-} from "./chunk-AWNGBY5I.js";
-import "./chunk-WYBDERIY.js";
-import "./chunk-MRWYRAS5.js";
-import "./chunk-4IVHBXRI.js";
-import "./chunk-CM6BMECR.js";
-import "./chunk-JUFK3T4Q.js";
+} from "./chunk-DPCCW6U7.js";
 import "./chunk-YBW5JSA3.js";
-import "./chunk-N6GRVXAJ.js";
+import "./chunk-NPBM4QSK.js";
+import "./chunk-CM6BMECR.js";
+import "./chunk-MRWYRAS5.js";
 import "./chunk-3SIZGL3O.js";
+import "./chunk-M5ZGRVIQ.js";
+import "./chunk-BCS7WHCK.js";
+import "./chunk-WYBDERIY.js";
+import "./chunk-7ABONTXE.js";
 import "./chunk-NVJMJWLL.js";
 import "./chunk-YRKRZ6OF.js";
-import "./chunk-7RMTKFJW.js";
+import "./chunk-7Q6HPDY2.js";
 import "./chunk-Y3KNXVTD.js";
+import "./chunk-TXTQIYCV.js";
 import "./chunk-RIY7GYQS.js";
 import "./chunk-D2HKF2EF.js";
 import "./chunk-MYBZRDTY.js";
-import "./chunk-TXTQIYCV.js";
 import "./chunk-PX3VCKAU.js";
-import "./chunk-BCS7WHCK.js";
-import "./chunk-M5ZGRVIQ.js";
+import "./chunk-JUFK3T4Q.js";
 
 // src/personal-github.ts
 import { z } from "zod";

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

@@ -0,0 +1,210 @@
+import type { SessionGoalStatus, SessionStatus } from "./session-topology-primitives.js";
+import type { WorkDiscoveryProjection } from "./work-claims.js";
+import type { Session, SessionQueueSnapshot } from "./index.js";
+/** 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. */
+export declare function sessionMcpIncludesRelatedWork(options: {
+    detail?: SessionMcpDetail | undefined;
+    includeRelatedWork?: boolean | undefined;
+    query?: string | undefined;
+    subject?: unknown;
+}): boolean;
+/** A database prefix plus its exact Unicode code-point count, not a JS UTF-16 count. */
+export declare function boundSessionMcpText(value: string | null, maxChars?: number, originalChars?: number | null): {
+    text: null;
+    truncated: boolean;
+} | {
+    text: string;
+    truncated: boolean;
+};
+export type SessionMcpControlSource = {
+    state: string;
+    primaryBlocker: {
+        kind: "session" | "workspace";
+        sessionId?: string | undefined;
+        displayName: string;
+        displayNameOriginalChars?: number;
+        reason?: string | null;
+    } | null;
+    additionalBlockerCount: number;
+};
+/** Call only after related-access projection: this helper never grants ancestor access. */
+export declare function compactSessionMcpPause(control: SessionMcpControlSource): {
+    state: string;
+    source?: {
+        kind: "session" | "workspace";
+        sessionId?: string;
+        displayName: string | null;
+        displayNameTruncated?: boolean;
+        reason?: string | null;
+        reasonTruncated?: boolean;
+    };
+    additionalBlockerCount?: number;
+} | undefined;
+export type SessionMcpListSource = {
+    id: string;
+    title: string | null;
+    titleOriginalChars?: number | null;
+    status: SessionStatus;
+    parentSessionId: string | null;
+    effectiveControl: SessionMcpControlSource;
+    goal: {
+        status: SessionGoalStatus;
+        text: string;
+        textOriginalChars?: number;
+    } | null;
+    updatedAt: string;
+    workDiscovery?: WorkDiscoveryProjection;
+    treeStats?: {
+        attentionDescendants: number;
+        pausedDescendants: number;
+        failedDescendants: number;
+        truncated: boolean;
+    };
+};
+/** Closed allowlist, shared by MCP adapters. Never spread a database/session object. */
+export declare function compactSessionMcpListRow(session: SessionMcpListSource, includeRelatedWork?: boolean): {
+    id: string;
+    title: string | null;
+    status: "cancelled" | "failed" | "idle" | "queued" | "recovering" | "requires_action" | "running" | "waiting_capacity";
+    titleTruncated?: boolean;
+    parentSessionId?: string;
+    goal?: {
+        status: "active" | "completed" | "paused";
+        summary: string | null;
+        summaryTruncated?: boolean;
+    };
+    pause?: {
+        state: string;
+        source?: {
+            kind: "session" | "workspace";
+            sessionId?: string;
+            displayName: string | null;
+            displayNameTruncated?: boolean;
+            reason?: string | null;
+            reasonTruncated?: boolean;
+        };
+        additionalBlockerCount?: number;
+    };
+    attention?: {
+        requiresActionDescendants?: number;
+        pausedDescendants?: number;
+        failedDescendants?: number;
+        truncated?: boolean;
+    };
+    relatedWork?: {
+        claims: {
+            id: string;
+            sessionId: string;
+            subject: {
+                namespace: string;
+                type: "artifact" | "branch" | "ci_run" | "issue" | "other" | "pull_request" | "release" | "repository";
+                canonicalKey: string;
+                displayLabel: string | null;
+            };
+            role: "delivering" | "monitoring" | "reviewing" | "working";
+            state: "active" | "released" | "stale" | "superseded";
+            revision: number;
+            provenance: "explicit_agent" | "session_resource" | "system_lifecycle" | "trusted_integration" | "user_api";
+            version: {
+                kind: "artifact_version" | "branch_head" | "ci_run" | "git_commit" | "other" | "pull_request_head" | "release_version";
+                value: string;
+            } | null;
+            observedAt: string;
+            updatedAt: string;
+            settledAt: string | null;
+        }[];
+        claimsTruncated: boolean;
+        match: {
+            class: "exact_subject" | "fuzzy" | "goal" | "title";
+            field: "claim_key" | "claim_label" | "goal" | "subject" | "title";
+            scoreBand: "exact" | "related" | "strong";
+            claimId: string | null;
+        } | null;
+        possibleOverlap: boolean;
+        advisoryOnly: true;
+        noAdditionalAccess: true;
+    };
+    updatedAt: string;
+};
+export type SessionMcpMonitoringSource = {
+    goal: {
+        status: SessionGoalStatus;
+        text: string;
+        textOriginalChars: number;
+        evidence: string | null;
+        evidenceOriginalChars: number | null;
+        rationale: string | null;
+        rationaleOriginalChars: number | null;
+        pausedReason: string | null;
+        pausedReasonOriginalChars: number | null;
+    } | null;
+    progress: {
+        sequence: number;
+        text: string | null;
+        originalChars: number | null;
+        occurredAt: string;
+    } | null;
+    wait: {
+        reason: string;
+        until: string;
+    } | null;
+};
+/** 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): {
+    id: string;
+    title: string | null;
+    status: "cancelled" | "failed" | "idle" | "queued" | "recovering" | "requires_action" | "running" | "waiting_capacity";
+    titleTruncated?: boolean;
+    parentSessionId?: string;
+    activeTurnId?: string;
+    lastSequence: number;
+    goal?: {
+        status: "active" | "completed" | "paused";
+        summary: string | null;
+        summaryTruncated?: boolean;
+        evidence?: string | null;
+        evidenceTruncated?: true;
+        pausedReason?: string | null;
+        pausedReasonTruncated?: true;
+        rationale?: string | null;
+        rationaleTruncated?: true;
+    };
+    progress?: {
+        sequence: number;
+        text: string | null;
+        occurredAt: string;
+        textTruncated?: boolean;
+    };
+    pause?: {
+        state: string;
+        source?: {
+            kind: "session" | "workspace";
+            sessionId?: string;
+            displayName: string | null;
+            displayNameTruncated?: boolean;
+            reason?: string | null;
+            reasonTruncated?: boolean;
+        };
+        additionalBlockerCount?: number;
+    };
+    wait?: {
+        reason: string | null;
+        until: string;
+        reasonTruncated?: boolean;
+    };
+    queue?: {
+        queuedTurns: number;
+        pendingInputs: number;
+        stoppingPreviousAttempt?: boolean;
+    };
+    stopping?: {
+        attempts?: number;
+        backgroundCommands?: number;
+    };
+    updatedAt: string;
+};
+export type SessionMcpCompactListRow = ReturnType<typeof compactSessionMcpListRow>;
+export type SessionMcpCompactDetail = ReturnType<typeof compactSessionMcpDetail>;

package/dist/session-titles.d.ts

@@ -30,3 +30,38 @@ export declare function boundAutomaticSessionTitle(value: string): string;
  * title (normally {@link AUTOMATIC_SESSION_TITLE_FALLBACK}) in that case.
  */
 export declare function normalizeAutomaticSessionTitle(value: string): string | null;
+export type SessionDisplayTitleInput = {
+    id?: string | null | undefined;
+    title?: string | null | undefined;
+    titleSource?: "user" | "agent" | null | undefined;
+    initialMessage?: string | null | undefined;
+    metadata?: Readonly<Record<string, unknown>> | undefined;
+};
+export type SessionDisplayTitleOptions = {
+    /** Optional metadata fields to try before the opening-prompt preview. */
+    metadataKeys?: readonly string[] | undefined;
+};
+/**
+ * Derive a bounded, sensitive-safe preview from the opening prompt.
+ *
+ * Unsafe leading lines are skipped instead of forcing the whole session back
+ * to a generic label. This covers prompts that begin with a pasted URL or
+ * identifier followed by an ordinary natural-language request on the next
+ * line, without putting the rejected value into navigation surfaces.
+ */
+export declare function deriveAutomaticSessionTitlePreview(value: unknown): string | null;
+/**
+ * Whether the durable title still represents the automatic-title pending state.
+ * A user-authored title always wins, even when its literal value is the marker.
+ */
+export declare function sessionTitleIsPending(input: SessionDisplayTitleInput): boolean;
+/**
+ * Derive the title a human-facing client should display for a session.
+ *
+ * A semantic agent title or human rename wins. While automatic naming is still
+ * pending, clients show a short, sensitive-safe preview of the opening prompt.
+ * If no safe prompt text exists, a UUID-derived reference keeps real sessions
+ * distinguishable without exposing prompt bytes. The durable pending marker is
+ * therefore an internal lifecycle value rather than the ordinary visible name.
+ */
+export declare function deriveSessionDisplayTitle(input: SessionDisplayTitleInput, options?: SessionDisplayTitleOptions): string;