dsh-connect-trae 2.0.6 → 2.2.0

package/lib/index.d.ts

@@ -1156,6 +1156,21 @@ declare class TraeDelegatingUpstreamClient implements TraeUpstreamClient {
 declare const TRAE_PAY_BASE = "https://api.trae.cn";
 interface TraeUsageOptions {
   credential(): Promise<TraeCredential | undefined>;
+  /**
+   * Device identity of the credential's own installation, sent as
+   * `x-device-id` on the check-in routes.
+   *
+   * The claim endpoint is the one WRITE in this client, and it is guarded
+   * server-side by that header: with the same Authorization but no
+   * `x-device-id`, the upstream answers HTTP 200 with business code `9004`
+   * ("The submitted order parameters are incorrect") and grants nothing —
+   * verified 2026-09-24 against a live CN account, where adding the header
+   * flipped the same request to `code: 0` and the daily reward landed. The
+   * official client sends it on every check-in call
+   * (`main.js`'s `fb(headers)` sets `x-device-id` from `guaranteedDeviceId`).
+   * Absent, the client still reads status; only the claim refuses.
+   */
+  deviceId?(): Promise<string | undefined>;
   fetchImpl?: typeof fetch;
   baseUrl?: string;
   timeoutMs?: number;
@@ -1209,8 +1224,27 @@ interface TraeUsageSnapshot {
 }
 interface TraeCheckinStatus {
   checkedIn: boolean;
+  /** Reward for one check-in, as reported by the upstream (`credits`). */
   credits: number;
   enabled: boolean;
+  /**
+   * Whether today's reward was claimed in a previous session. The upstream
+   * reports `did_checked_in` separately from `checked_in`: the app uses the
+   * former to keep the claim button disabled for the rest of the Beijing day
+   * even when the status read happens to report `checked_in: false`.
+   */
+  didCheckedIn: boolean;
+  /** Bonus credit granted on top of the base reward, when the upstream reports one. */
+  extraCredits?: number;
+}
+/** Result of claiming today's check-in reward. */
+interface TraeCheckinClaim {
+  /** Whether the upstream accepted the claim (`code === 0`). */
+  claimed: boolean;
+  /** Business code from the answer; `0` on success. */
+  code: number;
+  /** Upstream message, verbatim but truncated — never token material. */
+  message: string;
 }
 interface TraeActivityRule {
   activityId: string;
@@ -1226,8 +1260,11 @@ interface TraeUsageView {
   activities: TraeActivityRule[];
 }
 /**
- * A read-only client for the verified Trae usage/credits endpoints.
- * All methods are safe to call from a plugin and never mutate account state.
+ * A client for the verified Trae usage/credits endpoints.
+ *
+ * Every method is read-only except {@link TraeUsageClient.claimCheckin}, which
+ * claims the daily check-in reward — the one deliberate mutation, requested by
+ * the user from the card and guarded before it is sent.
  */
 declare class TraeUsageClient {
   private readonly options;
@@ -1243,6 +1280,13 @@ declare class TraeUsageClient {
    * international region its own verified pay gateway.
    */
   private payBase;
+  /**
+   * Device id for the check-in routes, or undefined when the machine's
+   * installation identity cannot be read. Best-effort on purpose: a missing
+   * identity must not break the read-only status query, which the upstream
+   * answers with or without the header.
+   */
+  private deviceIdHeader;
   private authedHeaders;
   private post;
   /**
@@ -1260,8 +1304,26 @@ declare class TraeUsageClient {
   private requireCnRegion;
   /** Total entitlements / credits and per-pack breakdown. */
   snapshot(signal?: AbortSignal): Promise<TraeUsageSnapshot>;
-  /** Daily check-in status. */
+  /**
+   * Daily check-in status. Read-only, and answered with or without the device
+   * header — the claim is what needs it.
+   */
   checkinStatus(signal?: AbortSignal): Promise<TraeCheckinStatus>;
+  /**
+   * Claim today's check-in reward. The ONLY state-changing call in this client.
+   *
+   * The upstream is idempotent per Beijing day (verified 2026-09-24: repeating
+   * the call on an already-claimed day answers `code: 0` while the entitlement
+   * total stays byte-identical), so a double click cannot double-grant. The
+   * card and its route still guard, because "cannot double-grant" is a property
+   * of the upstream we verify rather than one we rely on.
+   *
+   * A business refusal arrives as HTTP 200 with a non-zero `code` — most often
+   * `9004` when the request carries no `x-device-id`. That is reported as
+   * `claimed: false` rather than thrown, so the caller can tell "the upstream
+   * refused this" apart from "the request never arrived".
+   */
+  claimCheckin(signal?: AbortSignal): Promise<TraeCheckinClaim>;
   /** Rewards / activity rules. */
   activities(signal?: AbortSignal): Promise<TraeActivityRule[]>;
   /** Convenience: snapshot + check-in + activities in one call (best-effort, non-fatal on missing). */
@@ -1271,6 +1333,11 @@ declare class TraeUsageClient {
 //#region src/status-paths.d.ts
 /** Plugin-owned usage endpoint consumed by its browser half. */
 declare const TRAE_USAGE_PATH = "/plugins/dsh-connect-trae/usage";
+/**
+ * Plugin-owned daily check-in claim endpoint. POST, loopback-only, and the only
+ * route in this plugin that changes upstream account state.
+ */
+declare const TRAE_CHECKIN_PATH = "/plugins/dsh-connect-trae/checkin";
 /** Query parameter naming the region a card request addresses. */
 declare const TRAE_REGION_PARAM = "region";
 /** Every region, in card tab order. */
@@ -1316,10 +1383,32 @@ interface TraeWebModel {
   };
   maxContextWindow?: number;
 }
-/** Daily check-in status rendered by the card. */
+/**
+ * Daily check-in state rendered below the credit stats.
+ *
+ * `didCheckedIn` is not redundant with `checkedIn`: the upstream reports them
+ * separately, and the official client keeps the claim button disabled for the
+ * rest of the Beijing day off `did_checked_in` even when a status read comes
+ * back `checked_in: false`. The card mirrors that rule so a stale-looking
+ * status cannot invite a pointless second claim.
+ */
 interface TraeWebCheckin {
   checkedIn: boolean;
+  didCheckedIn: boolean;
   credits: number;
+  enabled: boolean;
+  extraCredits?: number;
+}
+/** The claim route's answer, so the card can report a business refusal verbatim. */
+interface TraeWebCheckinClaim {
+  /** False when the upstream answered a non-zero business code (e.g. 9004). */
+  claimed: boolean;
+  /** True when today was already claimed, so nothing was sent upstream. */
+  alreadyCheckedIn: boolean;
+  code?: number;
+  message?: string;
+  /** The refreshed check-in state, present whenever the claim path ran. */
+  checkin?: TraeWebCheckin;
 }
 /** One reward activity rule (name + work/general credits when present). */
 interface TraeWebActivity {
@@ -1346,6 +1435,31 @@ interface TraeWebSearchPath {
   reason: 'missing' | 'unreadable' | 'invalid';
   message?: string;
 }
+/**
+ * Peel ONE `{get(): T}` live reference, the shape DSH 0.1.7 delivers a
+ * volatile-marked settings field as (see {@link unwrapVolatileDeep}).
+ */
+declare function unwrapVolatile<T>(value: T): T;
+/**
+ * Deep copy of a value with every `{get(): T}` live reference replaced by the
+ * value it resolves to.
+ *
+ * DSH 0.1.7 hands volatile-marked fields back as live references, and a live
+ * reference is still `typeof === 'object'` — so it passes a naive object check
+ * and every lookup on it is `undefined`. Worse, spreading one (`{ ...ref }`)
+ * does NOT read the field: it produces `{ get: <function> }`. Any merge that
+ * spreads a resolved field to preserve its siblings — the card's "write one
+ * region, keep the other" write, or the account map's spread — would otherwise
+ * DROP every sibling and leak a function into the document.
+ *
+ * Both halves therefore unwrap before touching a resolved field. This lives in
+ * the node-free host↔client bridge because the browser half needs it too.
+ *
+ * Non-reference values are recursed into so a nested volatile field is caught
+ * as well; arrays and objects are rebuilt rather than mutated, so the caller's
+ * value is never touched.
+ */
+declare function unwrapVolatileDeep<T>(value: T): T;
 /**
  * Build the next `regions` settings value for the card's save. The write
  * targets ONLY the signed-in account's region slot; every other region's slot
@@ -1425,6 +1539,14 @@ type TraeWebUsage = {
   };
   credits?: TraeWebCredits;
   creditsError?: string;
+  /**
+   * Daily check-in state (CN only). Absent on the international region,
+   * whose check-in surface does not exist — probed 2026-09-24: the
+   * `/trae/api/v2/ug/*` family answers 404 on every ai gateway, so the card
+   * shows no claim button there rather than a button that cannot work.
+   */
+  checkin?: TraeWebCheckin;
+  checkinError?: string;
   /** Subscription status of an international account (region ai only). */
   payStatus?: TraeWebPayStatus;
   payStatusError?: string;
@@ -1558,7 +1680,27 @@ declare function regionStateOf(config: Config, region: TraeRegion): TraeRegionSt
  * disagree about a region's state.
  */
 declare function regionEnabled(config: Config, region: TraeRegion): boolean;
+/**
+ * Mark a schema's field as volatile on the DSH lines that support it.
+ *
+ * `volatile()` exists from schemastery 3.18.3 (the DSH 0.1.7 line, which is the
+ * only line whose settings write gate reads the marker). Older pinning (3.18.2,
+ * the 0.1.5 line) has no such method, and the schema must stay byte-identical
+ * to the unmarked original there: hand-writing `meta.volatile = true` would
+ * bypass schemastery's own `validateVolatileSchema` checks and produce a schema
+ * no 0.1.5 consumer understands — so on that line this degrades to an identity
+ * no-op.
+ *
+ * Without the marker, 0.1.7's settings write gate REJECTS every write with
+ * `Plugin entry "trae" has no volatile fields` while the scope's `set()` still
+ * resolves — so the card would look like it saved and silently revert.
+ *
+ * Exported so BOTH arms are testable on any machine: the capability is decided
+ * by whichever schemastery the dependency tree resolves, so without a seam the
+ * no-op arm would silently stop being exercised the moment the pin moved up.
+ */
+declare function asVolatile<S>(schema: S): S;
 declare const Config: z<Config>;
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { Config, FALLBACK_TRAE_MODELS, FALLBACK_TRAE_MODELS_AI, REGION_GATEWAYS, type RawChatDelta, type RawChatMessage, type RawChatTool, SseDecoder, type SseEvent, TRAE_AI_PROVIDER, TRAE_CN_AGENT_TASK_PATH, TRAE_CN_TITLE_PATH, TRAE_MODEL_DETAIL_FUNCTIONS, TRAE_MODEL_DETAIL_PATH, TRAE_PAY_BASE, TRAE_PROVIDER, TRAE_PROVIDERS, TRAE_PROVIDER_DISPLAY_NAMES, TRAE_RAW_CHAT_V1_PATH, TRAE_RAW_CHAT_V2_PATH, TRAE_REASONING_EFFORTS, TRAE_REGIONS, TRAE_REGION_PARAM, TRAE_SETTINGS_NS, TRAE_SOLO_CHAT_PATH, TRAE_SOLO_FUNCTION, TRAE_SOLO_MODELS_PATH, TRAE_SOLO_REMOTE_BASE, TRAE_STREAM_IDLE_TIMEOUT_MS, TRAE_USAGE_PATH, TRAE_VERSION_CODE_FALLBACK, type TraeActivityRule, type TraeAdapter, type TraeCachedModelConfig, TraeCatalog, type TraeChatResult, type TraeCheckinStatus, type TraeContextBudget, type TraeCredential, TraeCredentialStore, TraeDelegatingUpstreamClient, type TraeDiscoveredModel, type TraeDiscoveredReasoning, type TraeEdition, TraeFallbackUpstreamClient, type TraeFallbackUpstreamOptions, type TraeFusionRawChatEnvelope, TraeGatedUpstreamClient, type TraeGatedUpstreamOptions, type TraeIdentity, type TraeInputModality, type TraeModelDetailRequest, type TraeModelInfo, type TraeObservedModelConfig, TraeRawCapabilityController, type TraeRawCapabilityControllerOptions, type TraeRawCapabilitySnapshot, TraeRawCapabilityState, type TraeRawChatBehaviorConfig, type TraeRawChatCapability, type TraeRawChatClientOptions, type TraeRawChatConfig, type TraeRawChatFailureReason, type TraeRawChatRuntimeConfig, TraeRawChatUpstreamClient, type TraeRawDiagnostic, type TraeRawDiagnosticState, type TraeRawGateway, type TraeRawGatewayOptions, type TraeRawResolverResult, type TraeReasoningCapability, type TraeReasoningEffort, type TraeRefreshDevice, type TraeRegion, type TraeRegionGateways, TraeRegionState, type TraeShim, TraeSoloBridge, type TraeSoloClientOptions, TraeSoloRemoteCatalogClient, type TraeSoloRemoteCatalogOptions, TraeSoloUpstreamClient, type TraeStorageCandidate, type TraeStreamEvent, type TraeUpstreamClient, TraeUsageClient, type TraeUsageOptions, type TraeUsagePack, type TraeUsageRouteOptions, type TraeUsageSnapshot, type TraeUsageSummary, type TraeUsageView, type TraeWebActivity, type TraeWebCheckin, type TraeWebCredits, type TraeWebUsage, type TraeWireModel, UnconfiguredTraeUpstreamClient, apply, applyContextBudgets, applyImageSelection, applyReasoningEffort, bridgeTraeSoloStream, buildTraeAgentTaskBody, buildTraeCnHeaders, buildTraeFusionRawChatEnvelope, buildTraeModelDetailRequest, buildTraeRawChatDraft, buildTraeRawChatRuntimeConfig, classifyTraeRawChatFailure, createTraeAdapter, createTraeRawGateway, createTraeShim, decodeRawChatChunk, decodeTraeEvent, decryptTraeStorageValue, deriveCatalog, discoveredCatalog, fallbackModelsFor, hashTraeRawChatArg, identityHeaders, inject, legacyTraeOwnAuthPath, mergeTraeModelSources, name, nextRegionEnabled, nextRegionSlots, normalizeTraeCredential, normalizeTraeVersionCode, parseObservedModelConfig, parseReasoningCapability, parseTraeAuthValue, parseTraeCachedModel, parseTraeModelExtraConfigLogLine, parseTraeRawChatBehaviorConfig, parseTraeRemoteModel, parseTraeStorageDocument, pickTraeStorageIdentity, prepareSoloBody, probeTraeRawChatCapability, rawCapabilityDiagnostic, rawCapabilityFingerprint, readTraeCachedModel, readTraeCliIdentity, readTraeIdentity, refreshTraeCredential, regionEnabled, regionEnabledOf, regionOfCredential, regionOfEdition, regionOfHost, regionOfTraeProvider, regionOfTraeStatusUrl, regionOfUserRegion, regionStateOf, registerTraeUsageRoute, resolveTraeIdentity, resolveTraeRawRuntime, sanitizeCatalog, traeEndpoint, traeInputModalities, traeModelDisplayName, traeOwnAuthPath, traeRawChatExtraInfo, traeStorageCandidates, traeWebUsage, withTraeRegion };
+export { Config, FALLBACK_TRAE_MODELS, FALLBACK_TRAE_MODELS_AI, REGION_GATEWAYS, type RawChatDelta, type RawChatMessage, type RawChatTool, SseDecoder, type SseEvent, TRAE_AI_PROVIDER, TRAE_CHECKIN_PATH, TRAE_CN_AGENT_TASK_PATH, TRAE_CN_TITLE_PATH, TRAE_MODEL_DETAIL_FUNCTIONS, TRAE_MODEL_DETAIL_PATH, TRAE_PAY_BASE, TRAE_PROVIDER, TRAE_PROVIDERS, TRAE_PROVIDER_DISPLAY_NAMES, TRAE_RAW_CHAT_V1_PATH, TRAE_RAW_CHAT_V2_PATH, TRAE_REASONING_EFFORTS, TRAE_REGIONS, TRAE_REGION_PARAM, TRAE_SETTINGS_NS, TRAE_SOLO_CHAT_PATH, TRAE_SOLO_FUNCTION, TRAE_SOLO_MODELS_PATH, TRAE_SOLO_REMOTE_BASE, TRAE_STREAM_IDLE_TIMEOUT_MS, TRAE_USAGE_PATH, TRAE_VERSION_CODE_FALLBACK, type TraeActivityRule, type TraeAdapter, type TraeCachedModelConfig, TraeCatalog, type TraeChatResult, type TraeCheckinClaim, type TraeCheckinStatus, type TraeContextBudget, type TraeCredential, TraeCredentialStore, TraeDelegatingUpstreamClient, type TraeDiscoveredModel, type TraeDiscoveredReasoning, type TraeEdition, TraeFallbackUpstreamClient, type TraeFallbackUpstreamOptions, type TraeFusionRawChatEnvelope, TraeGatedUpstreamClient, type TraeGatedUpstreamOptions, type TraeIdentity, type TraeInputModality, type TraeModelDetailRequest, type TraeModelInfo, type TraeObservedModelConfig, TraeRawCapabilityController, type TraeRawCapabilityControllerOptions, type TraeRawCapabilitySnapshot, TraeRawCapabilityState, type TraeRawChatBehaviorConfig, type TraeRawChatCapability, type TraeRawChatClientOptions, type TraeRawChatConfig, type TraeRawChatFailureReason, type TraeRawChatRuntimeConfig, TraeRawChatUpstreamClient, type TraeRawDiagnostic, type TraeRawDiagnosticState, type TraeRawGateway, type TraeRawGatewayOptions, type TraeRawResolverResult, type TraeReasoningCapability, type TraeReasoningEffort, type TraeRefreshDevice, type TraeRegion, type TraeRegionGateways, TraeRegionState, type TraeShim, TraeSoloBridge, type TraeSoloClientOptions, TraeSoloRemoteCatalogClient, type TraeSoloRemoteCatalogOptions, TraeSoloUpstreamClient, type TraeStorageCandidate, type TraeStreamEvent, type TraeUpstreamClient, TraeUsageClient, type TraeUsageOptions, type TraeUsagePack, type TraeUsageRouteOptions, type TraeUsageSnapshot, type TraeUsageSummary, type TraeUsageView, type TraeWebActivity, type TraeWebCheckin, type TraeWebCheckinClaim, type TraeWebCredits, type TraeWebUsage, type TraeWireModel, UnconfiguredTraeUpstreamClient, apply, applyContextBudgets, applyImageSelection, applyReasoningEffort, asVolatile, bridgeTraeSoloStream, buildTraeAgentTaskBody, buildTraeCnHeaders, buildTraeFusionRawChatEnvelope, buildTraeModelDetailRequest, buildTraeRawChatDraft, buildTraeRawChatRuntimeConfig, classifyTraeRawChatFailure, createTraeAdapter, createTraeRawGateway, createTraeShim, decodeRawChatChunk, decodeTraeEvent, decryptTraeStorageValue, deriveCatalog, discoveredCatalog, fallbackModelsFor, hashTraeRawChatArg, identityHeaders, inject, legacyTraeOwnAuthPath, mergeTraeModelSources, name, nextRegionEnabled, nextRegionSlots, normalizeTraeCredential, normalizeTraeVersionCode, parseObservedModelConfig, parseReasoningCapability, parseTraeAuthValue, parseTraeCachedModel, parseTraeModelExtraConfigLogLine, parseTraeRawChatBehaviorConfig, parseTraeRemoteModel, parseTraeStorageDocument, pickTraeStorageIdentity, prepareSoloBody, probeTraeRawChatCapability, rawCapabilityDiagnostic, rawCapabilityFingerprint, readTraeCachedModel, readTraeCliIdentity, readTraeIdentity, refreshTraeCredential, regionEnabled, regionEnabledOf, regionOfCredential, regionOfEdition, regionOfHost, regionOfTraeProvider, regionOfTraeStatusUrl, regionOfUserRegion, regionStateOf, registerTraeUsageRoute, resolveTraeIdentity, resolveTraeRawRuntime, sanitizeCatalog, traeEndpoint, traeInputModalities, traeModelDisplayName, traeOwnAuthPath, traeRawChatExtraInfo, traeStorageCandidates, traeWebUsage, unwrapVolatile, unwrapVolatileDeep, withTraeRegion };

package/lib/index.js

@@ -3043,8 +3043,11 @@ function parseUsageSnapshot(payload) {
 	};
 }
 /**
-* A read-only client for the verified Trae usage/credits endpoints.
-* All methods are safe to call from a plugin and never mutate account state.
+* A client for the verified Trae usage/credits endpoints.
+*
+* Every method is read-only except {@link TraeUsageClient.claimCheckin}, which
+* claims the daily check-in reward — the one deliberate mutation, requested by
+* the user from the card and guarded before it is sent.
 */
 var TraeUsageClient = class {
 	options;
@@ -3070,6 +3073,20 @@ var TraeUsageClient = class {
 	async payBase() {
 		return this.baseUrl ?? REGION_GATEWAYS[await this.currentRegion()].pay;
 	}
+	/**
+	* Device id for the check-in routes, or undefined when the machine's
+	* installation identity cannot be read. Best-effort on purpose: a missing
+	* identity must not break the read-only status query, which the upstream
+	* answers with or without the header.
+	*/
+	async deviceIdHeader() {
+		try {
+			const deviceId = await this.options.deviceId?.();
+			return deviceId === void 0 || deviceId === "" ? {} : { "x-device-id": deviceId };
+		} catch {
+			return {};
+		}
+	}
 	async authedHeaders() {
 		const credential = await this.options.credential();
 		if (credential === void 0 || credential.accessToken === "") throw new Error("Trae credential is not available; cannot query usage");
@@ -3082,8 +3099,11 @@ var TraeUsageClient = class {
 			"Referer": `${origin}/`
 		};
 	}
-	async post(path, data, signal) {
-		const headers = await this.authedHeaders();
+	async post(path, data, signal, extraHeaders = {}) {
+		const headers = {
+			...await this.authedHeaders(),
+			...extraHeaders
+		};
 		const response = await this.fetchImpl(`${await this.payBase()}${path}`, {
 			method: "POST",
 			headers,
@@ -3137,14 +3157,46 @@ var TraeUsageClient = class {
 		await this.requireCnRegion("usage snapshot");
 		return parseUsageSnapshot(await this.post("/trae/api/v2/pay/web_user_ent_usage", { require_usage: true }, signal));
 	}
-	/** Daily check-in status. */
+	/**
+	* Daily check-in status. Read-only, and answered with or without the device
+	* header — the claim is what needs it.
+	*/
 	async checkinStatus(signal) {
 		await this.requireCnRegion("check-in status");
-		const payload = await this.post("/trae/api/v2/ug/checkin_credits/status", {}, signal);
+		const headers = await this.deviceIdHeader();
+		const payload = await this.post("/trae/api/v2/ug/checkin_credits/status", {}, signal, headers);
+		const extraCredits = asNumber(payload["extra_credits"]);
 		return {
 			checkedIn: payload["checked_in"] === true,
 			credits: asNumber(payload["credits"]) ?? 0,
-			enabled: payload["enable"] !== false
+			enabled: payload["enable"] !== false,
+			didCheckedIn: payload["did_checked_in"] === true,
+			...extraCredits === void 0 || extraCredits <= 0 ? {} : { extraCredits }
+		};
+	}
+	/**
+	* Claim today's check-in reward. The ONLY state-changing call in this client.
+	*
+	* The upstream is idempotent per Beijing day (verified 2026-09-24: repeating
+	* the call on an already-claimed day answers `code: 0` while the entitlement
+	* total stays byte-identical), so a double click cannot double-grant. The
+	* card and its route still guard, because "cannot double-grant" is a property
+	* of the upstream we verify rather than one we rely on.
+	*
+	* A business refusal arrives as HTTP 200 with a non-zero `code` — most often
+	* `9004` when the request carries no `x-device-id`. That is reported as
+	* `claimed: false` rather than thrown, so the caller can tell "the upstream
+	* refused this" apart from "the request never arrived".
+	*/
+	async claimCheckin(signal) {
+		await this.requireCnRegion("check-in claim");
+		const headers = await this.deviceIdHeader();
+		const payload = await this.post("/trae/api/v2/ug/checkin_credits/claim", {}, signal, headers);
+		const code = asNumber(payload["code"]) ?? 0;
+		return {
+			claimed: code === 0,
+			code,
+			message: typeof payload["message"] === "string" ? payload["message"].slice(0, 200) : ""
 		};
 	}
 	/** Rewards / activity rules. */
@@ -3189,6 +3241,11 @@ const TRAE_USAGE_PATH = "/plugins/dsh-connect-trae/usage";
 const TRAE_MODELS_REFRESH_PATH = "/plugins/dsh-connect-trae/models/refresh";
 /** Plugin-owned local account rescan endpoint. */
 const TRAE_ACCOUNTS_REFRESH_PATH = "/plugins/dsh-connect-trae/accounts/refresh";
+/**
+* Plugin-owned daily check-in claim endpoint. POST, loopback-only, and the only
+* route in this plugin that changes upstream account state.
+*/
+const TRAE_CHECKIN_PATH = "/plugins/dsh-connect-trae/checkin";
 /** Query parameter naming the region a card request addresses. */
 const TRAE_REGION_PARAM = "region";
 /** Every region, in card tab order. */
@@ -3212,6 +3269,42 @@ function regionOfTraeStatusUrl(url) {
 	return TRAE_REGIONS.includes(value) ? value : void 0;
 }
 /**
+* Peel ONE `{get(): T}` live reference, the shape DSH 0.1.7 delivers a
+* volatile-marked settings field as (see {@link unwrapVolatileDeep}).
+*/
+function unwrapVolatile(value) {
+	if (value !== null && typeof value === "object" && typeof value.get === "function") return value.get();
+	return value;
+}
+/**
+* Deep copy of a value with every `{get(): T}` live reference replaced by the
+* value it resolves to.
+*
+* DSH 0.1.7 hands volatile-marked fields back as live references, and a live
+* reference is still `typeof === 'object'` — so it passes a naive object check
+* and every lookup on it is `undefined`. Worse, spreading one (`{ ...ref }`)
+* does NOT read the field: it produces `{ get: <function> }`. Any merge that
+* spreads a resolved field to preserve its siblings — the card's "write one
+* region, keep the other" write, or the account map's spread — would otherwise
+* DROP every sibling and leak a function into the document.
+*
+* Both halves therefore unwrap before touching a resolved field. This lives in
+* the node-free host↔client bridge because the browser half needs it too.
+*
+* Non-reference values are recursed into so a nested volatile field is caught
+* as well; arrays and objects are rebuilt rather than mutated, so the caller's
+* value is never touched.
+*/
+function unwrapVolatileDeep(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (typeof value.get === "function") return unwrapVolatileDeep(value.get());
+	if (Array.isArray(value)) return value.map((entry) => unwrapVolatileDeep(entry));
+	const source = value;
+	const out = {};
+	for (const key of Object.keys(source)) out[key] = unwrapVolatileDeep(source[key]);
+	return out;
+}
+/**
 * Build the next `regions` settings value for the card's save. The write
 * targets ONLY the signed-in account's region slot; every other region's slot
 * is carried over untouched, so switching accounts never clobbers the other
@@ -3219,8 +3312,9 @@ function regionOfTraeStatusUrl(url) {
 * from an empty document.
 */
 function nextRegionSlots(regions, region, slot) {
+	const unwrapped = unwrapVolatileDeep(regions);
 	return {
-		...typeof regions === "object" && regions !== null && !Array.isArray(regions) ? regions : {},
+		...typeof unwrapped === "object" && unwrapped !== null && !Array.isArray(unwrapped) ? unwrapped : {},
 		[region]: slot
 	};
 }
@@ -3231,17 +3325,23 @@ function nextRegionSlots(regions, region, slot) {
 * where the map was expected was a real shipped bug — the lookup then read
 * `section['cn']` (absent), so the card's checkbox reported `true` forever and
 * clicking it appeared to do nothing even though the write succeeded.
+*
+* Unwraps live references first: on DSH 0.1.7 the `regions` field arrives as a
+* `{get(): T}` reference, which passes the `typeof === 'object'` check below
+* and would otherwise be returned as if it were the map — making every region
+* read back as absent (and the enabled flag read as "on" forever).
 */
 function regionsMapOf(value) {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
-	const record = value;
+	const unwrapped = unwrapVolatileDeep(value);
+	if (typeof unwrapped !== "object" || unwrapped === null || Array.isArray(unwrapped)) return {};
+	const record = unwrapped;
 	const nested = record["regions"];
 	if (typeof nested === "object" && nested !== null && !Array.isArray(nested)) return nested;
 	return record;
 }
 /** One region's stored slot as a plain object; any other shape reads as empty. */
 function regionSlotOf(value, region) {
-	const slot = regionsMapOf(value)[region];
+	const slot = unwrapVolatile(regionsMapOf(value)[region]);
 	return typeof slot === "object" && slot !== null && !Array.isArray(slot) ? slot : {};
 }
 /**
@@ -3323,6 +3423,16 @@ function toCredits(snapshot) {
 		accounts
 	};
 }
+/** Map the check-in answer to the card's compact document. */
+function toCheckin(status) {
+	return {
+		checkedIn: status.checkedIn,
+		didCheckedIn: status.didCheckedIn,
+		credits: status.credits,
+		enabled: status.enabled,
+		...status.extraCredits === void 0 ? {} : { extraCredits: status.extraCredits }
+	};
+}
 /**
 * Assemble one region's card document. `region` is the tab the card is on; the
 * region-scoped store already answers with only that region's accounts, so the
@@ -3389,20 +3499,13 @@ async function traeWebUsage(deps, region) {
 			payStatusError: safeMessage(error)
 		};
 	}
-	try {
-		const snapshot = await client.snapshot();
-		return {
-			status: "signed-in",
-			...account,
-			credits: toCredits(snapshot)
-		};
-	} catch (error) {
-		return {
-			status: "signed-in",
-			...account,
-			creditsError: safeMessage(error)
-		};
-	}
+	const [snapshotResult, checkinResult] = await Promise.allSettled([client.snapshot(), client.checkinStatus()]);
+	return {
+		status: "signed-in",
+		...account,
+		...snapshotResult.status === "fulfilled" ? { credits: toCredits(snapshotResult.value) } : { creditsError: safeMessage(snapshotResult.reason) },
+		...checkinResult.status === "fulfilled" ? { checkin: toCheckin(checkinResult.value) } : { checkinError: safeMessage(checkinResult.reason) }
+	};
 }
 /**
 * The region a request addresses, or a 400 answer. Absent parameter means the
@@ -3471,7 +3574,49 @@ function registerTraeUsageRoute(ctx, deps) {
 				}
 			}
 		});
+		/**
+		* Daily check-in claim — the ONLY route in this plugin that mutates
+		* upstream account state, so it is guarded more tightly than its siblings:
+		* POST only, loopback origin only, and the status read runs FIRST so an
+		* already-claimed day never reaches the upstream claim at all. The upstream
+		* is idempotent per Beijing day anyway (verified 2026-09-24: a repeat claim
+		* answers `code: 0` with the entitlement total unchanged), but relying on
+		* that for correctness would put the guard in someone else's hands.
+		*/
+		const disposeCheckin = ctx.webServer.register({
+			kind: "exact",
+			path: TRAE_CHECKIN_PATH,
+			handler: async (req, res) => {
+				if (req.method !== "POST") return json(res, 405, { error: "method not allowed" });
+				if (!loopbackOrigin(req)) return json(res, 403, { error: "origin-not-trusted" });
+				const region = requestRegion(req, res);
+				if (region === void 0) return;
+				if (region !== "cn") return json(res, 404, { error: "check-in is not available for the international region" });
+				try {
+					const client = deps.client(region);
+					const current = await client.checkinStatus();
+					if (!current.enabled) return json(res, 409, { error: "check-in is not enabled for this account" });
+					if (current.checkedIn || current.didCheckedIn) return json(res, 200, {
+						claimed: false,
+						alreadyCheckedIn: true,
+						checkin: toCheckin(current)
+					});
+					const claim = await client.claimCheckin();
+					const checkin = await client.checkinStatus();
+					json(res, 200, {
+						claimed: claim.claimed,
+						alreadyCheckedIn: false,
+						code: claim.code,
+						message: claim.message,
+						checkin: toCheckin(checkin)
+					});
+				} catch (error) {
+					json(res, 500, { error: safeMessage(error) });
+				}
+			}
+		});
 		return () => {
+			disposeCheckin();
 			disposeRefresh();
 			disposeAccounts();
 			disposeUsage();
@@ -3633,7 +3778,7 @@ const TRAE_SETTINGS_NS = "trae";
 * picks (the same failure workbuddy fixed with its region split).
 */
 function regionStateOf(config, region) {
-	const stored = config.regions?.[region];
+	const stored = unwrapVolatile(unwrapVolatile(config.regions)?.[region]);
 	if (stored !== void 0) return stored;
 	if (region !== "cn") return {};
 	return {
@@ -3654,6 +3799,29 @@ function regionStateOf(config, region) {
 function regionEnabled(config, region) {
 	return regionStateOf(config, region).enabled !== false;
 }
+/**
+* Mark a schema's field as volatile on the DSH lines that support it.
+*
+* `volatile()` exists from schemastery 3.18.3 (the DSH 0.1.7 line, which is the
+* only line whose settings write gate reads the marker). Older pinning (3.18.2,
+* the 0.1.5 line) has no such method, and the schema must stay byte-identical
+* to the unmarked original there: hand-writing `meta.volatile = true` would
+* bypass schemastery's own `validateVolatileSchema` checks and produce a schema
+* no 0.1.5 consumer understands — so on that line this degrades to an identity
+* no-op.
+*
+* Without the marker, 0.1.7's settings write gate REJECTS every write with
+* `Plugin entry "trae" has no volatile fields` while the scope's `set()` still
+* resolves — so the card would look like it saved and silently revert.
+*
+* Exported so BOTH arms are testable on any machine: the capability is decided
+* by whichever schemastery the dependency tree resolves, so without a seam the
+* no-op arm would silently stop being exercised the moment the pin moved up.
+*/
+function asVolatile(schema) {
+	if (typeof schema.volatile === "function") return schema.volatile();
+	return schema;
+}
 const modelConfig = z.object({
 	id: z.string().required(),
 	name: z.string().required(),
@@ -3675,17 +3843,17 @@ const accountSelectionConfig = z.object({
 	ai: z.string().description("Selected international account id (never a token)")
 });
 const Config = z.object({
-	authFile: z.string().description("Optional Trae storage.json path override"),
-	edition: z.union([
+	authFile: asVolatile(z.string().description("Optional Trae storage.json path override")),
+	edition: asVolatile(z.union([
 		"auto",
 		"cn",
 		"sg",
 		"solo",
 		"solo-sg"
-	]).default("auto").description("Trae edition hint"),
+	]).default("auto").description("Trae edition hint")),
 	accountId: z.string().description("Deprecated: pre-split account selector, attributed to its own region"),
-	accounts: accountSelectionConfig.description("Per-region account selections, keyed cn | ai"),
-	regions: z.dict(regionStateConfig).default({}).description("Per-region model directory and selection, keyed cn | ai"),
+	accounts: asVolatile(accountSelectionConfig.description("Per-region account selections, keyed cn | ai")),
+	regions: asVolatile(z.dict(regionStateConfig).default({}).description("Per-region model directory and selection, keyed cn | ai")),
 	lastCatalog: z.array(modelConfig).description("Deprecated: pre-region-split CN model directory"),
 	enabledModelIds: z.array(z.string()).default([]).description("Deprecated: pre-region-split CN selection"),
 	contextBudgets: z.dict(z.number().step(1).min(1)).default({}).description("Deprecated: pre-region-split CN context budgets"),
@@ -3744,7 +3912,7 @@ function apply(ctx, config) {
 	*/
 	let legacyAccountRegion;
 	const effectiveAccountFor = (region, value) => {
-		const explicit = value.accounts?.[region];
+		const explicit = unwrapVolatile(value.accounts)?.[region];
 		if (explicit !== void 0) return explicit;
 		return legacyAccountRegion === region ? value.accountId : void 0;
 	};
@@ -3785,10 +3953,12 @@ function apply(ctx, config) {
 			try {
 				preferred = (await store.current())?.edition;
 			} catch {}
-			const hint = (config.edition !== void 0 && config.edition !== "auto" ? config.edition : void 0) ?? preferred;
-			return resolveTraeIdentity(config.authFile === void 0 ? traeStorageCandidates().filter((item) => item.source === "desktop" && (hint !== void 0 ? item.edition === hint : regionOfEdition(item.edition) === region)) : [{
+			const authFile = unwrapVolatile(config.authFile);
+			const edition = unwrapVolatile(config.edition);
+			const hint = (edition !== void 0 && edition !== "auto" ? edition : void 0) ?? preferred;
+			return resolveTraeIdentity(authFile === void 0 ? traeStorageCandidates().filter((item) => item.source === "desktop" && (hint !== void 0 ? item.edition === hint : regionOfEdition(item.edition) === region)) : [{
 				edition: hint ?? (region === "ai" ? "sg" : "solo"),
-				path: config.authFile,
+				path: authFile,
 				source: "desktop"
 			}], hint ?? (region === "ai" ? "solo-sg" : "cn"));
 		};
@@ -3810,8 +3980,8 @@ function apply(ctx, config) {
 		};
 		const store = new TraeCredentialStore({
 			region,
-			...config.authFile === void 0 ? {} : { storagePath: config.authFile },
-			edition: config.edition ?? "auto",
+			...unwrapVolatile(config.authFile) === void 0 ? {} : { storagePath: unwrapVolatile(config.authFile) },
+			edition: unwrapVolatile(config.edition) ?? "auto",
 			refresh: async (credential) => refreshTraeCredential(credential, void 0, await refreshDeviceSafe())
 		});
 		const solo = new TraeSoloUpstreamClient({
@@ -3866,7 +4036,10 @@ function apply(ctx, config) {
 			catalog,
 			shim,
 			delegating,
-			usageClient: new TraeUsageClient({ credential: () => store.resolve() }),
+			usageClient: new TraeUsageClient({
+				credential: () => store.resolve(),
+				deviceId: async () => (await identity()).deviceId
+			}),
 			discoverModels: async (signal) => {
 				const merged = mergeTraeModelSources(await withDirectoryRetry(() => remoteCatalog.fetchModels(signal)), await solo.fetchModels(signal));
 				wire.callableKeys.clear();
@@ -3936,7 +4109,7 @@ function apply(ctx, config) {
 	const applySelection = (value) => {
 		for (const region of REGION_KEYS) {
 			const stack = stacks[region];
-			stack.store.setSource(value.authFile, value.edition ?? "auto", effectiveAccountFor(region, value));
+			stack.store.setSource(unwrapVolatile(value.authFile), unwrapVolatile(value.edition) ?? "auto", effectiveAccountFor(region, value));
 			stack.catalog.set(configuredModels(value, region));
 			stack.invalidateAdapter();
 		}
@@ -3965,7 +4138,18 @@ function apply(ctx, config) {
 	const legacyInstallSettingsSection = dshSettings.installSettingsSection;
 	if (typeof legacyInstallSettingsSection === "function") legacyInstallSettingsSection(ctx, TRAE_SETTINGS_NS, Config, config, sectionHooks);
 	else ctx.inject(["settings"], (settingsCtx) => {
-		settingsCtx.settings.installSection(ctx, TRAE_SETTINGS_NS, Config, config, sectionHooks);
+		const settings = settingsCtx.settings;
+		if (typeof settings.configure === "function") {
+			settings.configure({ auto: true }, ctx.fiber);
+			return;
+		}
+		if (typeof settings.installSection === "function") {
+			const entry = unwrapVolatileDeep(config);
+			settings.installSection(ctx, TRAE_SETTINGS_NS, Config, entry, sectionHooks);
+		}
+	});
+	ctx.on("loader/volatile-update", () => {
+		applySelection(current());
 	});
 	let stopped = false;
 	ctx.effect(() => () => {
@@ -4048,4 +4232,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, FALLBACK_TRAE_MODELS, FALLBACK_TRAE_MODELS_AI, REGION_GATEWAYS, SseDecoder, TRAE_AI_PROVIDER, TRAE_CN_AGENT_TASK_PATH, TRAE_CN_TITLE_PATH, TRAE_MODEL_DETAIL_FUNCTIONS, TRAE_MODEL_DETAIL_PATH, TRAE_PAY_BASE, TRAE_PROVIDER, TRAE_PROVIDERS, TRAE_PROVIDER_DISPLAY_NAMES, TRAE_RAW_CHAT_V1_PATH, TRAE_RAW_CHAT_V2_PATH, TRAE_REASONING_EFFORTS, TRAE_REGIONS, TRAE_REGION_PARAM, TRAE_SETTINGS_NS, TRAE_SOLO_CHAT_PATH, TRAE_SOLO_FUNCTION, TRAE_SOLO_MODELS_PATH, TRAE_SOLO_REMOTE_BASE, TRAE_STREAM_IDLE_TIMEOUT_MS, TRAE_USAGE_PATH, TRAE_VERSION_CODE_FALLBACK, TraeCatalog, TraeCredentialStore, TraeDelegatingUpstreamClient, TraeFallbackUpstreamClient, TraeGatedUpstreamClient, TraeRawCapabilityController, TraeRawCapabilityState, TraeRawChatUpstreamClient, TraeSoloBridge, TraeSoloRemoteCatalogClient, TraeSoloUpstreamClient, TraeUsageClient, UnconfiguredTraeUpstreamClient, apply, applyContextBudgets, applyImageSelection, applyReasoningEffort, bridgeTraeSoloStream, buildTraeAgentTaskBody, buildTraeCnHeaders, buildTraeFusionRawChatEnvelope, buildTraeModelDetailRequest, buildTraeRawChatDraft, buildTraeRawChatRuntimeConfig, classifyTraeRawChatFailure, createTraeAdapter, createTraeRawGateway, createTraeShim, decodeRawChatChunk, decodeTraeEvent, decryptTraeStorageValue, deriveCatalog, discoveredCatalog, fallbackModelsFor, hashTraeRawChatArg, identityHeaders, inject, legacyTraeOwnAuthPath, mergeTraeModelSources, name, nextRegionEnabled, nextRegionSlots, normalizeTraeCredential, normalizeTraeVersionCode, parseObservedModelConfig, parseReasoningCapability, parseTraeAuthValue, parseTraeCachedModel, parseTraeModelExtraConfigLogLine, parseTraeRawChatBehaviorConfig, parseTraeRemoteModel, parseTraeStorageDocument, pickTraeStorageIdentity, prepareSoloBody, probeTraeRawChatCapability, rawCapabilityDiagnostic, rawCapabilityFingerprint, readTraeCachedModel, readTraeCliIdentity, readTraeIdentity, refreshTraeCredential, regionEnabled, regionEnabledOf, regionOfCredential, regionOfEdition, regionOfHost, regionOfTraeProvider, regionOfTraeStatusUrl, regionOfUserRegion, regionStateOf, registerTraeUsageRoute, resolveTraeIdentity, resolveTraeRawRuntime, sanitizeCatalog, traeEndpoint, traeInputModalities, traeModelDisplayName, traeOwnAuthPath, traeRawChatExtraInfo, traeStorageCandidates, traeWebUsage, withTraeRegion };
+export { Config, FALLBACK_TRAE_MODELS, FALLBACK_TRAE_MODELS_AI, REGION_GATEWAYS, SseDecoder, TRAE_AI_PROVIDER, TRAE_CHECKIN_PATH, TRAE_CN_AGENT_TASK_PATH, TRAE_CN_TITLE_PATH, TRAE_MODEL_DETAIL_FUNCTIONS, TRAE_MODEL_DETAIL_PATH, TRAE_PAY_BASE, TRAE_PROVIDER, TRAE_PROVIDERS, TRAE_PROVIDER_DISPLAY_NAMES, TRAE_RAW_CHAT_V1_PATH, TRAE_RAW_CHAT_V2_PATH, TRAE_REASONING_EFFORTS, TRAE_REGIONS, TRAE_REGION_PARAM, TRAE_SETTINGS_NS, TRAE_SOLO_CHAT_PATH, TRAE_SOLO_FUNCTION, TRAE_SOLO_MODELS_PATH, TRAE_SOLO_REMOTE_BASE, TRAE_STREAM_IDLE_TIMEOUT_MS, TRAE_USAGE_PATH, TRAE_VERSION_CODE_FALLBACK, TraeCatalog, TraeCredentialStore, TraeDelegatingUpstreamClient, TraeFallbackUpstreamClient, TraeGatedUpstreamClient, TraeRawCapabilityController, TraeRawCapabilityState, TraeRawChatUpstreamClient, TraeSoloBridge, TraeSoloRemoteCatalogClient, TraeSoloUpstreamClient, TraeUsageClient, UnconfiguredTraeUpstreamClient, apply, applyContextBudgets, applyImageSelection, applyReasoningEffort, asVolatile, bridgeTraeSoloStream, buildTraeAgentTaskBody, buildTraeCnHeaders, buildTraeFusionRawChatEnvelope, buildTraeModelDetailRequest, buildTraeRawChatDraft, buildTraeRawChatRuntimeConfig, classifyTraeRawChatFailure, createTraeAdapter, createTraeRawGateway, createTraeShim, decodeRawChatChunk, decodeTraeEvent, decryptTraeStorageValue, deriveCatalog, discoveredCatalog, fallbackModelsFor, hashTraeRawChatArg, identityHeaders, inject, legacyTraeOwnAuthPath, mergeTraeModelSources, name, nextRegionEnabled, nextRegionSlots, normalizeTraeCredential, normalizeTraeVersionCode, parseObservedModelConfig, parseReasoningCapability, parseTraeAuthValue, parseTraeCachedModel, parseTraeModelExtraConfigLogLine, parseTraeRawChatBehaviorConfig, parseTraeRemoteModel, parseTraeStorageDocument, pickTraeStorageIdentity, prepareSoloBody, probeTraeRawChatCapability, rawCapabilityDiagnostic, rawCapabilityFingerprint, readTraeCachedModel, readTraeCliIdentity, readTraeIdentity, refreshTraeCredential, regionEnabled, regionEnabledOf, regionOfCredential, regionOfEdition, regionOfHost, regionOfTraeProvider, regionOfTraeStatusUrl, regionOfUserRegion, regionStateOf, registerTraeUsageRoute, resolveTraeIdentity, resolveTraeRawRuntime, sanitizeCatalog, traeEndpoint, traeInputModalities, traeModelDisplayName, traeOwnAuthPath, traeRawChatExtraInfo, traeStorageCandidates, traeWebUsage, unwrapVolatile, unwrapVolatileDeep, withTraeRegion };