letagents 0.12.9 → 0.12.11

package/dist/mcp/sse-client.js

@@ -1,5 +1,4 @@
 import { encodeRoomIdPath } from "./room-id.js";
-import { buildRoomAgentPrompt, normalizeAgentPromptKind } from "../shared/room-agent-prompts.js";
 export class SseClient {
     apiUrl;
     getAccessToken;
@@ -42,8 +41,8 @@ export class SseClient {
             this.unsubscribe(roomId);
         }
     }
-    getHeaders() {
-        const token = this.getAccessToken?.();
+    async getHeaders() {
+        const token = await this.getAccessToken?.();
         if (!token) {
             return { Accept: "text/event-stream" };
         }
@@ -83,7 +82,7 @@ export class SseClient {
     }
     async openStream(url, signal, onMessage) {
         const response = await fetch(url, {
-            headers: this.getHeaders(),
+            headers: await this.getHeaders(),
             signal,
         });
         if (!response.ok) {
@@ -123,19 +122,12 @@ export class SseClient {
         if (dataLines.length === 0) {
             return;
         }
-        onMessage(this.enrichPromptMetadata(JSON.parse(dataLines.join("\n"))));
-    }
-    enrichPromptMetadata(message) {
-        const kind = normalizeAgentPromptKind(message.agent_prompt_kind);
-        if (!kind) {
-            return message;
-        }
-        return {
-            ...message,
-            visible_text: message.text,
-            agent_prompt: buildRoomAgentPrompt(kind),
-            prompt_injected: kind === "inline",
-        };
+        // No prompt enrichment here: the only SSE subscriber (room-state.ts) discards
+        // the message body, and expanding the room-agent prompt on this background
+        // path would consume the once-per-session full-prompt delivery before the
+        // agent ever sees it. Prompt expansion happens only on visible tool
+        // responses (runtime/messages.ts).
+        onMessage(JSON.parse(dataLines.join("\n")));
     }
     isMissingRouteError(error) {
         return (error instanceof Error &&

package/dist/shared/activation-routing.js

@@ -0,0 +1,272 @@
+const NON_AGENT_AT_HANDLES = new Set([
+    "charset",
+    "container",
+    "counter-style",
+    "font-face",
+    "font-feature-values",
+    "font-palette-values",
+    "import",
+    "keyframes",
+    "layer",
+    "media",
+    "namespace",
+    "page",
+    "package",
+    "property",
+    "scope",
+    "starting-style",
+    "supports",
+    "types",
+    "viewport",
+]);
+const TASK_OWNER_FOLLOW_UP_PATTERNS = [
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:try again|retry|rerun|re-run|continue|proceed|go ahead|carry on)\b/,
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:open|create|make|raise)\s+(?:a\s+)?pr\b/,
+    /^(?:ok(?:ay)?|right|cool|great|nice)?[\s,]*(?:push|merge|ship|fix|test|run|update)\s+(?:it|that|this|again|tests?|the\s+tests?|ci)\b/,
+    /\b(?:try again|open\s+(?:a\s+)?pr|create\s+(?:a\s+)?pr|make\s+(?:a\s+)?pr|push it|merge it|update it)\b/,
+];
+export function attachAgentMessageActivation(message, identity, context = {}) {
+    return {
+        ...message,
+        activation: {
+            for_current_agent: decideAgentMessageActivation(message, identity, context),
+        },
+    };
+}
+export function attachAgentMessageActivations(messages, identity, context = {}) {
+    if (!identity || identity.session_kind !== "worker") {
+        return [...messages];
+    }
+    return messages.map((message) => attachAgentMessageActivation(message, identity, context));
+}
+export function decideAgentMessageActivation(message, identity, context = {}) {
+    if (normalizeSender(message.source) === "managed_agent_failure") {
+        return decision("silent", "system_event");
+    }
+    if (senderMatchesIdentity(message.sender, identity)) {
+        return decision("silent", "self_message");
+    }
+    const mentions = extractMentionHandles(message.text);
+    if (mentions.some(isBroadcastHandle)) {
+        return decision("activate", "broadcast");
+    }
+    if (mentions.some((mention) => identityAliases(identity).has(normalizeMentionIdentityHandle(mention)))) {
+        return decision("activate", "explicit_mention");
+    }
+    if (hasBroadcastAddress(message.text)) {
+        return decision("activate", "broadcast");
+    }
+    if (mentions.some(isLikelyAgentMentionHandle)) {
+        return decision("silent", "explicit_other_mention");
+    }
+    if (senderMatchesIdentity(message.reply_to?.sender, identity)) {
+        return decision("activate", "reply_target");
+    }
+    if (isAgentReplyTarget(message.reply_to) && !isThreadReply(message)) {
+        return decision("silent", "other_reply_target");
+    }
+    if (isThreadReply(message) && threadParticipantsIncludeIdentity(message, identity)) {
+        return decision("activate", "thread_participant");
+    }
+    const taskOwnerDecision = decideTaskOwnerActivation(message, identity, context);
+    if (taskOwnerDecision) {
+        return taskOwnerDecision;
+    }
+    return decision("unclear", "unaddressed");
+}
+function decision(decisionValue, reason) {
+    return {
+        decision: decisionValue,
+        reason,
+        addressed: decisionValue === "activate",
+    };
+}
+function isThreadReply(message) {
+    const ownId = normalizedString(message.id);
+    const rootId = normalizedString(message.thread_root_id) || normalizedString(message.thread?.root_message_id);
+    return Boolean(ownId && rootId && ownId !== rootId);
+}
+function isAgentReplyTarget(replyTo) {
+    return normalizeSender(replyTo?.source) === "agent";
+}
+function threadParticipantsIncludeIdentity(message, identity) {
+    const senders = [
+        message.reply_to?.sender,
+        message.thread?.latest_reply?.sender,
+        ...(message.thread?.participants ?? []).map((participant) => participant.sender),
+    ];
+    return senders.some((sender) => senderMatchesIdentity(sender, identity));
+}
+function decideTaskOwnerActivation(message, identity, context) {
+    if (!isTaskOwnerFollowUp(message.text)) {
+        return null;
+    }
+    const owners = uniqueActiveWorkOwners(context.activeTaskLeases ?? []);
+    if (owners.length !== 1) {
+        return null;
+    }
+    const owner = owners[0];
+    if (senderMatchesLeaseOwner(message.sender, owner)) {
+        return null;
+    }
+    if (leaseOwnerMatchesIdentity(owner, identity)) {
+        return decision("activate", "task_owner");
+    }
+    if (identityOverlapsLeaseOwner(identity, owner)) {
+        return null;
+    }
+    return decision("silent", "task_owner");
+}
+function uniqueActiveWorkOwners(leases) {
+    const ownersByKey = new Map();
+    for (const lease of leases) {
+        if (lease.kind !== "work" || lease.status !== "active")
+            continue;
+        const key = leaseOwnerKey(lease);
+        if (!key)
+            continue;
+        ownersByKey.set(key, lease);
+    }
+    return [...ownersByKey.values()];
+}
+function leaseOwnerKey(lease) {
+    const sessionId = normalizedString(lease.agent_session_id);
+    if (sessionId)
+        return `session:${sessionId}`;
+    const instanceId = normalizedString(lease.agent_instance_id);
+    const agentKey = normalizeSender(lease.agent_key);
+    if (instanceId)
+        return `instance:${agentKey}:${instanceId}`;
+    if (agentKey)
+        return `agent:${agentKey}`;
+    const actorLabel = normalizeSender(lease.actor_label);
+    return actorLabel ? `label:${actorLabel}` : null;
+}
+function leaseOwnerMatchesIdentity(lease, identity) {
+    const leaseSessionId = normalizedString(lease.agent_session_id);
+    if (leaseSessionId) {
+        return leaseSessionId === normalizedString(identity.agent_session_id);
+    }
+    const leaseInstanceId = normalizedString(lease.agent_instance_id);
+    if (leaseInstanceId) {
+        return (leaseInstanceId === normalizedString(identity.agent_instance_id) &&
+            normalizeSender(lease.agent_key) === normalizeSender(identity.agent_key));
+    }
+    const leaseAgentKey = normalizeSender(lease.agent_key);
+    if (leaseAgentKey) {
+        return leaseAgentKey === normalizeSender(identity.agent_key);
+    }
+    return senderMatchesIdentity(lease.actor_label, identity);
+}
+function senderMatchesLeaseOwner(sender, lease) {
+    const normalizedSender = normalizeSender(sender);
+    if (!normalizedSender)
+        return false;
+    return leaseOwnerAliases(lease).has(normalizedSender);
+}
+function identityOverlapsLeaseOwner(identity, lease) {
+    const identityAliasesForOwner = aliasesForValues([
+        identity.actor_label,
+        identity.display_name,
+        identity.agent_key,
+        identity.agent_instance_id,
+        identity.agent_session_id,
+    ]);
+    for (const ownerAlias of leaseOwnerAliases(lease)) {
+        if (identityAliasesForOwner.has(ownerAlias)) {
+            return true;
+        }
+    }
+    return false;
+}
+function leaseOwnerAliases(lease) {
+    return aliasesForValues([
+        lease.actor_label,
+        ...String(lease.actor_label || "").split("|"),
+        lease.agent_key,
+        lease.agent_instance_id,
+        lease.agent_session_id,
+    ]);
+}
+function aliasesForValues(values) {
+    const aliases = new Set();
+    for (const value of values) {
+        const senderAlias = normalizeSender(value);
+        if (senderAlias)
+            aliases.add(senderAlias);
+        const handleAlias = normalizeHandle(value);
+        if (handleAlias)
+            aliases.add(handleAlias);
+    }
+    return aliases;
+}
+function senderMatchesIdentity(sender, identity) {
+    const normalizedSender = normalizeSender(sender);
+    if (!normalizedSender)
+        return false;
+    const aliases = identityAliases(identity);
+    if (aliases.has(normalizedSender))
+        return true;
+    return String(sender || "")
+        .split("|")
+        .some((part) => aliases.has(normalizeSender(part)));
+}
+function identityAliases(identity) {
+    const aliases = new Set();
+    const values = [
+        identity.actor_label,
+        identity.display_name,
+        identity.agent_key,
+        identity.agent_key.split("/").pop(),
+    ];
+    for (const alias of aliasesForValues(values))
+        aliases.add(alias);
+    return aliases;
+}
+function extractMentionHandles(text) {
+    const raw = typeof text === "string" ? text : "";
+    const mentions = [];
+    for (const match of raw.matchAll(/(^|[\s([{:;,])@([A-Za-z0-9][A-Za-z0-9_.:-]*(?:\/[A-Za-z0-9][A-Za-z0-9_.-]*)*)/g)) {
+        mentions.push(match[2]);
+    }
+    return mentions;
+}
+function isBroadcastHandle(handle) {
+    const normalized = normalizeHandle(handle);
+    return normalized === "agents" || normalized === "everyone" || normalized === "room";
+}
+function isLikelyAgentMentionHandle(handle) {
+    const raw = normalizedString(handle);
+    if (!raw)
+        return false;
+    const normalized = raw.toLowerCase();
+    const firstSegment = normalized.split("/", 1)[0].replace(/_/g, "-");
+    if (normalized.startsWith("agent:"))
+        return true;
+    if (normalized.includes("/") && normalized === raw)
+        return false;
+    return !NON_AGENT_AT_HANDLES.has(firstSegment);
+}
+function hasBroadcastAddress(text) {
+    const raw = typeof text === "string" ? text.toLowerCase() : "";
+    return /\b(everyone|all agents|you guys|both of you|any agent|whoever owns this)\b/.test(raw);
+}
+function isTaskOwnerFollowUp(text) {
+    const raw = typeof text === "string" ? text.trim().toLowerCase() : "";
+    if (!raw)
+        return false;
+    return TASK_OWNER_FOLLOW_UP_PATTERNS.some((pattern) => pattern.test(raw));
+}
+function normalizedString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function normalizeSender(value) {
+    return normalizedString(value).toLowerCase().replace(/\s+/g, " ");
+}
+function normalizeHandle(value) {
+    return normalizedString(value).toLowerCase().replace(/[^a-z0-9_.:/-]+/g, "");
+}
+function normalizeMentionIdentityHandle(value) {
+    const normalized = normalizeHandle(value);
+    return normalized.startsWith("agent:") ? normalized.slice("agent:".length) : normalized;
+}

package/dist/shared/agent-identity.js

@@ -35,24 +35,40 @@ export function formatOwnerAttribution(ownerLabel) {
     return /s$/i.test(trimmed) ? `${trimmed}' agent` : `${trimmed}'s agent`;
 }
 export function inferAgentIdeLabel(value) {
-    const normalized = normalizeWhitespace(String(value ?? "")).toLowerCase();
+    const raw = normalizeWhitespace(String(value ?? ""));
+    const normalized = raw.toLowerCase();
     if (!normalized) {
         return null;
     }
-    if (normalized === "codex" || normalized.startsWith("codex-")) {
+    if (matchesRuntimePrefix(raw, "codex")) {
         return "Codex";
     }
-    if (normalized === "antigravity" || normalized.startsWith("antigravity-")) {
+    if (matchesRuntimePrefix(raw, "antigravity")) {
         return "Antigravity";
     }
-    if (normalized === "claude" || normalized.startsWith("claude-")) {
+    if (matchesRuntimePrefix(raw, "claude")) {
         return "Claude";
     }
-    if (normalized === "orchestrator" || normalized.startsWith("orchestrator-")) {
+    if (matchesRuntimePrefix(raw, "orchestrator")) {
         return "Orchestrator";
     }
     return null;
 }
+function matchesRuntimePrefix(value, prefix) {
+    const normalized = value.toLowerCase();
+    if (normalized === prefix || normalized.startsWith(`${prefix}-`)) {
+        return true;
+    }
+    const compact = value.replace(/[^a-zA-Z0-9]+/g, "");
+    if (compact.toLowerCase() === prefix) {
+        return true;
+    }
+    if (!compact.toLowerCase().startsWith(prefix)) {
+        return false;
+    }
+    const next = compact[prefix.length];
+    return Boolean(next && /[A-Z0-9]/.test(next));
+}
 export function buildAgentActorLabel(input) {
     const displayName = normalizeWhitespace(input.display_name) || "Agent";
     const ownerAttribution = formatOwnerAttribution(input.owner_label);

package/dist/shared/agent-presence.js

@@ -15,6 +15,7 @@ export const ROOM_AGENT_RECONNECT_GRACE_MS = 10_000;
 export const ROOM_AGENT_DELIVERY_TRANSPORTS = [
     "long_poll",
     "sse",
+    "desktop_events",
 ];
 export const ROOM_AGENT_SESSION_KINDS = [
     "controller",
@@ -42,8 +43,9 @@ export function getAgentPresenceFreshnessFromReachability(isReachable) {
     return isReachable ? "active" : "stale";
 }
 export function isAgentDeliverySessionReachable(input, now = Date.now()) {
-    if (input.activeConnectionCount <= 0) {
-        return false;
+    if (input.activeConnectionCount > 0 && getAgentPresenceFreshness(input.updatedAt ?? "", now) === "active") {
+        return true;
     }
-    return getAgentPresenceFreshness(input.updatedAt ?? "", now) === "active";
+    const graceExpiresAt = new Date(input.reconnectGraceExpiresAt ?? "").getTime();
+    return Number.isFinite(graceExpiresAt) && graceExpiresAt >= now;
 }

package/dist/shared/agent-session-bearer.js

@@ -0,0 +1,28 @@
+export const AGENT_SESSION_BEARER_CAPABILITIES = [
+    "messages.read",
+    "messages.write",
+    "coordination.read",
+    "coordination.self_write",
+    "coordination.propose",
+    "artifacts.read",
+    "artifacts.self_write",
+];
+export const DEFAULT_AGENT_SESSION_BEARER_CAPABILITIES = [
+    ...AGENT_SESSION_BEARER_CAPABILITIES,
+];
+export function isAgentSessionBearerCapability(value) {
+    return AGENT_SESSION_BEARER_CAPABILITIES.includes(value);
+}
+// The new direct worker principal is deliberately opt-in until F2 uses it.
+export function isAgentSessionBearerFeatureEnabled() {
+    return /^(1|true|yes)$/i.test(process.env.LETAGENTS_AGENT_SESSION_BEARER_ENABLED ?? "");
+}
+export function isSupervisorHostGrantFeatureEnabled() {
+    return /^(1|true|yes)$/i.test(process.env.LETAGENTS_SUPERVISOR_HOST_GRANT_ENABLED ?? "");
+}
+export function getAgentSessionBearerTtlMs() {
+    const configured = Number.parseInt(process.env.LETAGENTS_AGENT_SESSION_BEARER_TTL_MS ?? "", 10);
+    if (!Number.isFinite(configured))
+        return 30 * 60 * 1000;
+    return Math.min(Math.max(configured, 60_000), 24 * 60 * 60 * 1000);
+}

package/dist/shared/board-manager-failover.js

@@ -0,0 +1,16 @@
+export const BOARD_MANAGER_FAILOVER_MODES = ["off", "announce", "auto"];
+/**
+ * What the liveness sweep does when the active Board Manager's worker session
+ * goes unreachable: 'off' ignores it, 'announce' posts a room warning with a
+ * suggested successor, 'auto' (default) promotes the best reachable worker.
+ */
+export const DEFAULT_BOARD_MANAGER_FAILOVER = "auto";
+export function isBoardManagerFailoverMode(value) {
+    return BOARD_MANAGER_FAILOVER_MODES.includes(value);
+}
+export function normalizeBoardManagerFailoverMode(value) {
+    const normalized = value?.trim().toLowerCase();
+    return normalized && isBoardManagerFailoverMode(normalized)
+        ? normalized
+        : DEFAULT_BOARD_MANAGER_FAILOVER;
+}

package/dist/shared/rental/lrt.js

@@ -0,0 +1,214 @@
+/**
+ * LetAgents Rental Token (LRT) primitives.
+ *
+ * Pure functions. No I/O, no IDE-local reads, no DB. Importable from
+ * both the desktop main process and the API server.
+ *
+ * Spec §17.3 (LRT definition + suggested weights) and §17.13
+ * (confidence-based safety buffers).
+ */
+/**
+ * Default LRT weights. Match the suggested starting values in §17.3:
+ * input=1, output=4, cache_creation=1.25, cache_read=0.1, reasoning=4,
+ * tool=0. Other weights extend the formula for providers that bill on
+ * those axes.
+ *
+ * These are the public defaults; individual providers (per
+ * {@link PROVIDER_LRT_WEIGHTS}) may override any field.
+ */
+export const DEFAULT_LRT_WEIGHTS = Object.freeze({
+    input: 1.0,
+    output: 4.0,
+    cacheCreation: 1.25,
+    cacheRead: 0.1,
+    reasoning: 4.0,
+    tool: 0.0,
+    command: 0.0,
+    request: 0.0,
+    usdToLrt: 0.0,
+    creditsToLrt: 0.0,
+});
+/**
+ * Per-provider weight overrides applied on top of {@link DEFAULT_LRT_WEIGHTS}.
+ *
+ * V1 intentionally ships **no** baked-in non-zero overrides. Hard-coded
+ * placeholder weights (e.g. an arbitrary LRT-per-request for Cursor)
+ * would cause Budget Sentinel to systematically over- or under-count
+ * before any real calibration history exists. Instead, request-based
+ * and credit-based providers calibrate at the **session/adapter level**
+ * via the `calibratedWeights` argument to {@link computeLrt}, which the
+ * meter adapter populates from observed LRT-per-{request,credit,USD}
+ * once {@link CalibrationHistory} has enough samples.
+ *
+ * Future per-provider defaults can be added here once calibrated values
+ * are well-known across the fleet (e.g. \"LRT per Cursor premium request\"
+ * has converged after N sessions).
+ */
+export const PROVIDER_LRT_WEIGHTS = Object.freeze({
+    claude_code: {
+    // Claude Code emits exact token logs locally; defaults work.
+    },
+    codex: {
+    // Codex exposes token logs + credits; rely on tokens when present.
+    },
+    antigravity: {
+    // Antigravity exposes percent-window + reset only; token weights still
+    // apply when tokens can be observed, otherwise the calibrated estimator
+    // does the heavy lifting (see estimateLrtFromPercentWindow below).
+    },
+    cursor: {
+    // Request weight intentionally left at the 0 default — adapters
+    // supply a calibrated per-request weight via `computeLrt`'s
+    // `calibratedWeights` argument once history is available.
+    },
+});
+/**
+ * Resolve the effective weight table for one provider, optionally
+ * applying a session-level calibrated override on top.
+ *
+ * Lookup order, highest precedence first:
+ *
+ *   1. `calibratedWeights` argument          (per-session adapter override)
+ *   2. PROVIDER_LRT_WEIGHTS[provider]        (well-known per-provider override)
+ *   3. DEFAULT_LRT_WEIGHTS                   (§17.3 starting weights)
+ */
+export function resolveWeights(provider, calibratedWeights) {
+    const providerOverride = PROVIDER_LRT_WEIGHTS[provider] ?? {};
+    return { ...DEFAULT_LRT_WEIGHTS, ...providerOverride, ...(calibratedWeights ?? {}) };
+}
+/**
+ * Compute LRT consumed by a {@link UsageDelta}.
+ *
+ * Spec §17.3. The formula is:
+ *
+ *   lrt =
+ *     input_tokens          × input_weight
+ *   + output_tokens         × output_weight
+ *   + cache_creation_tokens × cache_creation_weight
+ *   + cache_read_tokens     × cache_read_weight
+ *   + reasoning_tokens      × reasoning_weight
+ *   + tool_events           × tool_weight
+ *   + command_runs          × command_weight
+ *   + requests              × request_weight
+ *   + credits               × credits_to_lrt
+ *   + usd                   × usd_to_lrt
+ *
+ * `calibratedWeights` lets the meter adapter pass a per-session
+ * calibrated override (e.g. an observed LRT-per-request for Cursor
+ * derived from {@link CalibrationHistory}). Without it, only the
+ * default + provider weights apply, which means request/credit/USD
+ * components contribute 0 LRT until an adapter calibrates them.
+ *
+ * Negative deltas are clamped to zero — a meter that goes "backwards"
+ * is treated as a reset event, not a refund.
+ */
+export function computeLrt(delta, provider, calibratedWeights) {
+    const w = resolveWeights(provider, calibratedWeights);
+    const tokens = Math.max(0, delta.inputTokens) * w.input
+        + Math.max(0, delta.outputTokens) * w.output
+        + Math.max(0, delta.cacheCreationTokens) * w.cacheCreation
+        + Math.max(0, delta.cacheReadTokens) * w.cacheRead
+        + Math.max(0, delta.reasoningTokens) * w.reasoning;
+    const events = Math.max(0, delta.toolCalls) * w.tool
+        + Math.max(0, delta.commandRuns) * w.command
+        + Math.max(0, delta.requests) * w.request;
+    const money = Math.max(0, delta.credits) * w.creditsToLrt
+        + Math.max(0, delta.usd) * w.usdToLrt;
+    return tokens + events + money;
+}
+/**
+ * Estimate LRT remaining when the only signal is a percent-window
+ * reading plus observed LRT consumed in the current window.
+ *
+ *   used_so_far  = LRT observed since window start
+ *   percent_used = 1 - percent_remaining
+ *   window_total = used_so_far / percent_used
+ *   remaining    = window_total - used_so_far
+ *
+ * Spec §17.4 percent-window calibration example.
+ *
+ * Returns `null` when the estimate cannot be computed (e.g. we have
+ * not observed any LRT yet, so the denominator is undefined).
+ */
+export function estimateLrtFromPercentWindow(percentRemaining, lrtObservedThisWindow) {
+    if (!Number.isFinite(percentRemaining) || percentRemaining < 0 || percentRemaining > 1) {
+        return null;
+    }
+    if (!Number.isFinite(lrtObservedThisWindow) || lrtObservedThisWindow <= 0) {
+        return null;
+    }
+    const percentUsed = 1 - percentRemaining;
+    if (percentUsed <= 0) {
+        return null;
+    }
+    const windowTotal = lrtObservedThisWindow / percentUsed;
+    const remaining = windowTotal * percentRemaining;
+    return Math.max(0, remaining);
+}
+/**
+ * Confidence-based stop thresholds.
+ *
+ * Spec §17.13: lower confidence stops earlier to avoid overrun when
+ * the meter lags.
+ *
+ *   official_exact / local_exact  → stop at 98 %
+ *   derived                       → stop at 95 %
+ *   calibrated                    → stop at 92 %
+ *   estimated                     → stop at 87 %
+ *   weak_estimate                 → stop at 80 %
+ *   unknown                       → stop at 75 % (or earlier per policy)
+ *
+ * Returned as the *fraction of budget* at which we close the rails.
+ * The Budget Sentinel multiplies an LRT limit by this to compute the
+ * effective ceiling before exhaustion.
+ */
+export const STOP_THRESHOLD_BY_CONFIDENCE = Object.freeze({
+    official_exact: 0.98,
+    local_exact: 0.98,
+    derived: 0.95,
+    calibrated: 0.92,
+    estimated: 0.87,
+    weak_estimate: 0.80,
+    unknown: 0.75,
+});
+/**
+ * Return the effective LRT ceiling a session is allowed to spend given
+ * its budget and the meter's confidence.
+ *
+ * The result is `Math.floor(lrtLimit × stopThreshold)`.
+ */
+export function effectiveLrtCeiling(lrtLimit, confidence) {
+    if (!Number.isFinite(lrtLimit) || lrtLimit <= 0) {
+        return 0;
+    }
+    const fraction = STOP_THRESHOLD_BY_CONFIDENCE[confidence] ?? STOP_THRESHOLD_BY_CONFIDENCE.unknown;
+    return Math.floor(lrtLimit * fraction);
+}
+/**
+ * Order on confidence levels — exact > local_exact > derived > calibrated
+ * > estimated > weak_estimate > unknown. Used to decide whether a new
+ * snapshot upgrades or downgrades meter confidence on a session.
+ */
+const CONFIDENCE_ORDER = [
+    "unknown",
+    "weak_estimate",
+    "estimated",
+    "calibrated",
+    "derived",
+    "local_exact",
+    "official_exact",
+];
+/**
+ * Compare two confidence values. Returns a negative number when `a` is
+ * weaker than `b`, positive when stronger, 0 when equal.
+ */
+export function compareConfidence(a, b) {
+    return CONFIDENCE_ORDER.indexOf(a) - CONFIDENCE_ORDER.indexOf(b);
+}
+/**
+ * Whether the meter signal qualifies as "exact" for marketplace
+ * eligibility (§7.4 preflight). Either local-exact or vendor-exact.
+ */
+export function isExactConfidence(confidence) {
+    return confidence === "official_exact" || confidence === "local_exact";
+}

package/dist/shared/rental/meter-types.js

@@ -0,0 +1,14 @@
+/**
+ * Shared rental meter contract.
+ *
+ * These types describe how a per-IDE meter adapter reports native quota
+ * state and rental usage from the desktop/MCP-local process to the API
+ * server. They live in `src/shared/` because both sides import them.
+ *
+ * Per spec §17.7 (Meter Adapter Contract) and §17.8 (Rental Scope
+ * Attribution). Adapters run **desktop-side** (Electron main process
+ * or MCP-local) because they read local IDE files such as JSONL session
+ * logs and SQLite conversation rows; the API server only ingests the
+ * normalized snapshots they report.
+ */
+export {};