@opengeni/contracts 3.1.0-canary.1 → 3.1.2

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

@@ -0,0 +1,4 @@
+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"> & 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,56 @@
+import {
+  deriveAutomaticSessionTitlePreview,
+  deriveSessionDisplayTitle,
+  sessionTitleIsPending
+} from "./chunk-E3GGUBHS.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,
+    title: session.title,
+    titleSource: session.titleSource,
+    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> &\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    title: session.title,\n    titleSource: session.titleSource,\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":";;;;;;;AAwCO,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,OAAO,QAAQ;AAAA,IACf,aAAa,QAAQ;AAAA,IACrB,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

@@ -166,6 +166,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-message-search.d.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+/** Literal Unicode case-insensitive search, without trimming or normalization. */
+export declare const SessionMessageSearchRequest: z.ZodObject<{
+    query: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    groupBy: z.ZodOptional<z.ZodLiteral<"session">>;
+    archiveStatus: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        all: "all";
+        archived: "archived";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SessionMessageSearchRequest = z.infer<typeof SessionMessageSearchRequest>;
+export declare const SessionMessageSearchMatch: z.ZodObject<{
+    sessionId: z.ZodString;
+    sessionTitle: z.ZodNullable<z.ZodString>;
+    eventId: z.ZodString;
+    sequence: z.ZodNumber;
+    turnId: z.ZodNullable<z.ZodString>;
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        user: "user";
+    }>;
+    messageId: z.ZodNullable<z.ZodString>;
+    messageMatchOffset: z.ZodNumber;
+    snippet: z.ZodObject<{
+        text: z.ZodString;
+        matchStart: z.ZodNumber;
+        matchEnd: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SessionMessageSearchMatch = z.infer<typeof SessionMessageSearchMatch>;
+/** A bounded scan page, not necessarily a full page of matches. Continue even
+ * after an empty page while hasMore is true. Counts describe this live traversal,
+ * not a frozen snapshot; restart to reflect concurrent changes. All non-overlapping
+ * literal occurrences in user messages and completed assistant messages.
+ * With groupBy=session, matches and both matched counts describe one first-hit
+ * representative per matching session, not full message/occurrence totals.
+ */
+export declare const SessionMessageSearchResponse: z.ZodObject<{
+    matches: z.ZodArray<z.ZodObject<{
+        sessionId: z.ZodString;
+        sessionTitle: z.ZodNullable<z.ZodString>;
+        eventId: z.ZodString;
+        sequence: z.ZodNumber;
+        turnId: z.ZodNullable<z.ZodString>;
+        role: z.ZodEnum<{
+            assistant: "assistant";
+            user: "user";
+        }>;
+        messageId: z.ZodNullable<z.ZodString>;
+        messageMatchOffset: z.ZodNumber;
+        snippet: z.ZodObject<{
+            text: z.ZodString;
+            matchStart: z.ZodNumber;
+            matchEnd: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+    hasMore: z.ZodBoolean;
+    scannedMessages: z.ZodNumber;
+    matchedMessageCount: z.ZodNumber;
+    matchedOccurrenceCount: z.ZodNumber;
+    countIsExact: z.ZodBoolean;
+}, z.core.$strip>;
+export type SessionMessageSearchResponse = z.infer<typeof SessionMessageSearchResponse>;

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-7ABONTXE.js";
+} from "./chunk-E3GGUBHS.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,41 @@
+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-OL23ARTF.js";
+import {
+  SESSION_USAGE_LIMIT_GOAL_PAUSED_REASON,
+  SESSION_USAGE_LIMIT_SEGMENT,
+  formatSessionUsageMicros,
+  parseSessionUsageLimitReachedRefusal,
+  sessionUsageLimitReachedMessage
+} from "./chunk-7272KVWZ.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":[]}

package/dist/signup-attribution.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+/**
+ * First-touch marketing parameters accepted on the web app landing URL. The
+ * browser keeps them in memory only and forwards them with a sign-up request,
+ * so nothing is written to the device before analytics consent.
+ */
+export declare const SIGNUP_ATTRIBUTION_URL_PARAMETERS: {
+    readonly utmSource: "utm_source";
+    readonly utmMedium: "utm_medium";
+    readonly utmCampaign: "utm_campaign";
+    readonly utmContent: "utm_content";
+    readonly ref: "ref";
+};
+/** Maximum retained length of one attribution value. */
+export declare const SIGNUP_ATTRIBUTION_VALUE_MAX_LENGTH = 100;
+/**
+ * Campaign labels are marketer-chosen slug tokens such as `hero-cta` or
+ * `opengeni.ai`. The closed character set has no space, `@`, `:`, `/`, `?`,
+ * `=`, or `%`, so free text, email addresses, and URL payloads are rejected
+ * before they reach any sink. The web boot capture and the session-set social
+ * start request mirror this rule; tests pin each copy to it.
+ */
+export declare const SIGNUP_ATTRIBUTION_VALUE_PATTERN: RegExp;
+export declare const SignupAttribution: z.ZodObject<{
+    utmSource: z.ZodOptional<z.ZodString>;
+    utmMedium: z.ZodOptional<z.ZodString>;
+    utmCampaign: z.ZodOptional<z.ZodString>;
+    utmContent: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SignupAttribution = z.infer<typeof SignupAttribution>;
+/** Closed acquisition channels reported by server-side sign-up metrics. */
+export declare const SIGNUP_ACQUISITION_SOURCES: readonly ["producthunt", "website", "direct", "other"];
+export type SignupAcquisitionSource = (typeof SIGNUP_ACQUISITION_SOURCES)[number];
+/**
+ * Normalize untrusted first-touch attribution to a closed channel. Missing
+ * attribution is `direct`; malformed or unrecognized attribution is `other`.
+ */
+export declare function signupAcquisitionSource(input: unknown): SignupAcquisitionSource;