dsh-workbuddy-xdpool 1.1.0 → 1.2.0

package/lib/index.d.ts

@@ -3,6 +3,167 @@ import { Api, Model } from "@earendil-works/pi-ai";
 import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
 import { Context, Context as Context$1 } from "@deepseek-ai/cordis";
 import { SettingsNamespace } from "@deepseek-ai/dsh-settings";
+//#region src/task-events.d.ts
+/**
+ * The event chains that light up the client-scored daily tasks.
+ *
+ * The task board advertises things like "open an app", "use five templates" or
+ * "summon a platform expert". Those read as actions only a human at the desktop
+ * app can take, but the scorer does not check the app — it checks the event
+ * stream. Replaying the same events, with the same desktop fingerprint, scores
+ * the task. Every chain here was measured against the live upstream.
+ *
+ * Kept apart from the scheduler because a chain is pure data: the scheduler
+ * decides *when* to send one, this module decides *what* one is. A few chains
+ * need a real server-side id first (the expert family), which is why the builder
+ * is allowed to be async and to call the upstream.
+ */
+/**
+ * How a chain reaches the upstream.
+ *
+ * There are three fingerprint families and the scorer keys different tasks to
+ * different ones, so the transport is part of the chain rather than a detail of
+ * the sender: `Buddy_App` needs the desktop fingerprint, while `Library_read` is
+ * only scored when it arrives with the WEB fingerprint.
+ */
+type TaskEventTransport = 'desktop' | 'web';
+/** A ready-to-send chain, plus the channel it must go out on. */
+interface TaskEventChain {
+  transport: TaskEventTransport;
+  /** Desktop chains: the event array. */
+  events?: readonly Record<string, unknown>[];
+  /** Web chains: the single page event to report. */
+  web?: {
+    eventCode: string;
+    pageUrl: string;
+    elementId: string;
+    elementName: string;
+  };
+}
+/**
+ * The app the buddy chain enters.
+ *
+ * One chain lights up two tasks: `Buddy_App` (open any app) and `Buddy_App_QQ`
+ * (the QQ-specific one), because this is a QQ-hosted app. Measured 0/1 → 1/1 on
+ * both from a single chain.
+ */
+export declare const BUDDY_APP_ID = "cb_y5Dy46tPQGGWtueMxXbe";
+export declare const BUDDY_APP_NAME = "企鹅教师助手";
+/**
+ * The buddy-app chain (two tasks).
+ *
+ * Five clicks in the order a user would make them: discover the app, see it,
+ * enter it, confirm the account link, skip the second binding step.
+ */
+export declare function buddyAppChain(): TaskEventChain;
+/**
+ * The design-canvas chain (`create_canvas`, +300 — the joint largest reward).
+ *
+ * The two canvas events ride the same metrics channel as everything else, so no
+ * real canvas is ever created; the chat chain in front supplies the ids they
+ * reference. Measured 1/1 on three accounts.
+ */
+export declare function canvasChain(): TaskEventChain;
+/**
+ * The scheduled-task event (`automation_1`).
+ *
+ * One event is the whole chain — measured 1/1 on two accounts. The name is only
+ * for the server's own records, so a generated one is fine.
+ */
+export declare function automationChain(): TaskEventChain;
+/**
+ * The plain chat chain (`RichMeow_Chat`, and the base of the template chain).
+ *
+ * Measured: this chain alone lights `RichMeow_Chat`.
+ */
+export declare function chatChain(): TaskEventChain;
+/**
+ * The "same as this case" chain (`playbook_prompt`).
+ *
+ * The scorer watches `playbook_prompt_send` — sending the prompt that the
+ * inspiration case pre-fills — not the card impression or the button click, so
+ * the whole click path is replayed for realism but the send is what counts.
+ */
+export declare function playbookChain(caseId?: string, caseName?: string): TaskEventChain;
+/** The inspiration case the reference panel sends a prompt for. */
+export declare const PLAYBOOK_CASE_ID = "pm-gtm-launch-plan";
+export declare const PLAYBOOK_CASE_NAME = "新产品上市 GTM 发布计划一页纸";
+/**
+ * The five templates the reference panel cycles through, as `[id, name]`.
+ *
+ * The upstream does not check that these templates exist — only that five
+ * distinct `template_used` events arrive — so they are the reference set.
+ */
+export declare const TEMPLATE_PRESETS: readonly (readonly [string, string])[];
+/**
+ * One "created a task from a template" chain (`template_5`, +100 for five).
+ *
+ * Each group is a chat chain (which supplies the ids the template events join
+ * on) plus `agent_task_created_with_template` and `template_used`. Measured:
+ * five groups in one report scored 5/5.
+ */
+export declare function templateChain(templateId: string, templateName: string): TaskEventChain;
+/** Every template group, ready to send in order. */
+export declare function templateChains(): readonly TaskEventChain[];
+/**
+ * The library-introduction click (`Library_read`).
+ *
+ * Scored on the WEB fingerprint — the same event posted with the desktop
+ * fingerprint scores nothing — so this chain returns a web transport and the
+ * scheduler routes it through `reportWebEvent`.
+ */
+export declare function libraryReadChain(): TaskEventChain;
+/** The document the library click is reported against. */
+export declare const LIBRARY_DOC_URL = "https://www.workbuddy.cn/space/d/o0KWYeynteVv06UnAZqIFm";
+/** The theme key `Hp_Appearance` is scored on (和平精英激战金秋). */
+export declare const APPEARANCE_THEME_KEY = "theme-tkmw7j";
+/** The skill `skill_1` is scored on. */
+export declare const SKILL_ID = "skill_2097350077599879168";
+export declare const SKILL_NAME = "润泽小馆·日报撰写";
+/** The 腾讯轻量云 expert `Expert_lighthouse` is scored on. */
+export declare const LIGHTHOUSE_EXPERT_ID = "ex_2cvvUZQhDyeJ";
+/**
+ * Build the `skill_1` chain from a REAL conversation.
+ *
+ * Unlike the template and canvas chains, this one is verified against the
+ * conversation it names, so the caller must first open a real chat and hand the
+ * server-side ids in.
+ */
+export declare function skillChain(conversationId: string, requestId: string): TaskEventChain;
+/** The theme-apply event `Hp_Appearance` is scored on. */
+export declare function appearanceChain(themeKey?: string): TaskEventChain;
+/** One expert from the platform's marketplace, as the summon chains need it. */
+interface MarketExpert {
+  expertId: string;
+  expertType: string;
+  displayName: string;
+  profession: string;
+  version: string;
+  categories: readonly string[];
+}
+/**
+ * The three "summon an expert" events (`expert_summon_click` and friends).
+ *
+ * Paid before the conversation, in the order the app emits them.
+ */
+export declare function expertSummonEvents(expert: MarketExpert): Record<string, unknown>[];
+/** `mode` for the `expert_actual_use` payload; the scorer checks it. */
+type ExpertUseMode = 'craft' | 'LOCAL';
+/**
+ * The "an expert really answered" event, which is what the expert tasks count.
+ *
+ * The `requestId` must be the SERVER's id for a real chat: a made-up one scores
+ * nothing, because the scorer looks the conversation up.
+ */
+export declare function expertActualUseEvent(expert: MarketExpert, conversationId: string, requestId: string, mode?: ExpertUseMode): Record<string, unknown>;
+/**
+ * The chat chain for an expert conversation.
+ *
+ * `agent_task_created` carries the expert fields the scorer reads to attribute
+ * the conversation to that expert.
+ */
+export declare function expertChatEvents(expert: MarketExpert, conversationId: string, requestId: string): Record<string, unknown>[];
+//#endregion
 //#region src/upstream.d.ts
 /** Upstream failure classes the shim maps onto distinct HTTP answers. */
 type UpstreamErrorKind = 'hard_credit' | 'soft_rate' | 'session_dead' | 'not_found' | 'server' | 'client';
@@ -103,6 +264,45 @@ export declare function classifyUpstreamError(status: number, body: string): Ups
  */
 export declare function parseRateLimitReset(body: string): number | undefined;
 /** One growth-centre task, flattened from the upstream's loosely-shaped entry. */
+/** One streak tier and what redeeming it pays. */
+interface WorkBuddyStreakTier {
+  /** Tier key, e.g. `7d`. */
+  tier: string;
+  /** Login days the tier needs. */
+  days: number;
+  credit: number;
+  energy: number;
+  cards: number;
+  /** Lottery draws the tier grants. */
+  chances: number;
+  /** `locked` / `unlocked` / `claimed`. */
+  status: string;
+}
+/** The growth streak as a whole: progress, tiers, makeup cards. */
+interface WorkBuddyStreakStatus {
+  /** Current consecutive active days. */
+  days: number;
+  /** Days active this month. */
+  monthTotalDays: number;
+  /** Next tier key, e.g. `7d`. */
+  nextTier: string;
+  /** Days still needed for `nextTier`. */
+  nextTierRemaining: number;
+  /** Makeup cards in hand. */
+  makeupCards: number;
+  tiers: readonly WorkBuddyStreakTier[];
+}
+/** One buddy trip state. */
+interface WorkBuddyTravelState {
+  /** `idle` (can depart) / `traveling` / `arrived` (can claim). */
+  state: string;
+  /** Trip id, required to claim an arrived trip. */
+  recordId: number;
+  /** The once-a-day depart limit has been used. */
+  dailyLimitReached: boolean;
+  /** Credits an arrived trip pays. */
+  rewardCredit: number;
+}
 interface WorkBuddyTask {
   /** Upstream task code; the claim path is built from it. */
   taskCode: string;
@@ -128,6 +328,55 @@ interface WorkBuddyTask {
   /** Upstream marked the task locked (not yet reachable). */
   locked: boolean;
 }
+/**
+ * Flatten one upstream task entry.
+ *
+ * Progress is reported two ways depending on the task: flat `current`/`target`
+ * fields, or a nested `progress: {current, target}`. The nested form wins when
+ * it carries anything, because a task that reports both puts the live counter
+ * there. Entries without a usable `task_code` are dropped — without one the
+ * claim path cannot be built.
+ */
+/**
+ * The event chain that scores the two Buddy-app tasks.
+ *
+ * Both tasks accept the same chain, and the chain is a pure value: building it
+ * needs no client, so callers (and tests) can hold one without a live upstream.
+ *
+ * The task text says "upgrade to the desktop client and open it from the app
+ * launcher". The scorer does not watch the UI — it watches this event sequence
+ * with the desktop fingerprint, which is why the sequence is what gets sent.
+ *
+ * Measured against the live upstream: progress 0/1 → 1/1 claimable in ~8s.
+ */
+/**
+ * A complete "desktop client ran a request successfully" event chain.
+ *
+ * Six events in the order the real client emits them: task created, message
+ * send, request send, message response, message status, request response.
+ * Several tasks are scored off this chain (or one that embeds it), because what
+ * they measure is "a real request completed", which the client only proves
+ * through this exact sequence.
+ *
+ * Measured: this chain alone lights up `RichMeow_Chat`.
+ */
+export declare function desktopChatEvents(conversationId: string, requestId: string, messageId: string, modelId?: string, modelName?: string): Record<string, unknown>[];
+/**
+ * A chat chain plus the two canvas events that score `create_canvas`.
+ *
+ * Worth +300, the joint largest task on the board. The canvas events ride
+ * the same metrics channel as everything else, so no real canvas is needed.
+ *
+ * Measured: three accounts scored 1/1 from this sequence.
+ */
+export declare function desktopCanvasEvents(conversationId: string, requestId: string): Record<string, unknown>[];
+/**
+ * The single event that scores `automation_1` (a scheduled task was created).
+ *
+ * Measured: two accounts lit it with this event alone.
+ */
+export declare function desktopAutomationCreatedEvent(name: string): Record<string, unknown>;
+export declare function buddyAppEvents(buddyId: string, buddyName: string): Record<string, unknown>[];
 export declare class WorkBuddyUpstreamClient {
   private readonly fetchImpl;
   private readonly clientVersion;
@@ -165,17 +414,97 @@ export declare class WorkBuddyUpstreamClient {
   fetchCheckinStatus(credential: WorkBuddyCredential): Promise<WorkBuddyCheckinStatus>;
   /** Claim today's check-in reward. The browser route guards this mutation. */
   claimDailyCheckin(credential: WorkBuddyCredential): Promise<WorkBuddyCheckinClaim>;
+  /**
+   * Public fingerprint fields every desktop event carries.
+   *
+   * The upstream scores a desktop-fingerprinted task only when the event looks
+   * like it came from the desktop client: the same field set, the same stable
+   * device ids, the same build. A partial map is accepted with 200 and scores
+   * nothing, so these are copied wholesale rather than trimmed.
+   *
+   * `machineId`/`sessionId` are DERIVED from the account uid, never random: a
+   * new device id on every call is itself a signal that the traffic is not a
+   * real client.
+   */
+  desktopFingerprint(credential: WorkBuddyCredential): Record<string, unknown>;
+  /**
+   * Send desktop-fingerprinted events to the growth system.
+   *
+   * The body is an ARRAY of events, and every event carries the full desktop
+   * fingerprint plus its own business fields. Different tasks recognise
+   * different fingerprint families (CLI / desktop / web), which is why this is
+   * separate from {@link reportActivity}: they are not interchangeable.
+   *
+   * Business fields win over the fingerprint, so a caller can override a device
+   * id to align with a real install.
+   */
+  reportDesktopEvents(credential: WorkBuddyCredential, events: readonly Record<string, unknown>[]): Promise<void>;
+  /**
+     * Report one chat-activity event to the growth system.
+     *
+     * The body is an ARRAY holding a single `chat_request_send` event, and every
+     * field is filled in: a three-field minimal event is accepted with 200 and
+     * then silently dropped, so the full shape is load-bearing rather than
+     * cosmetic. `userId` is the one field the server actually keys on — without
+     * it the request still answers 200 and scores nothing.
+     *
+     * One report per account per day is the quota the reference panel settled on;
+     * a single report lights the growth streak and unlocks the `first_buddy`
+     * family, which is why this runs before the task-centre pass.
+  
+    /**
+     * Send a WEB-fingerprinted event.
+     *
+     * A third fingerprint family, alongside CLI and desktop: a browser shape
+     * posted to the web origin with x-client-platform: web. Page-behaviour
+     * tasks such as `Library_read` are scored on it. Measured:
+     * `library_doc_intro_click` scored about four seconds after landing.
+     */
+  reportWebEvent(credential: WorkBuddyCredential, eventCode: string, pageUrl: string, elementId: string, elementName: string): Promise<void>;
+  /**
+   * Apply an appearance theme on the account.
+   *
+   * The theme task is scored on the `appearance_skin_apply` event, not on this
+   * call — but the event alone is not enough either. The pair is what a real
+   * client produces: it PATCHes the account's selected skin, then reports the
+   * event as the settings page closes. Measured on the reference panel after
+   * the earlier "the API alone does not score" reading was corrected.
+   */
+  setAppearanceTheme(credential: WorkBuddyCredential, resourceKey: string): Promise<void>;
+  /**
+   * The platform's expert marketplace.
+   *
+   * Needed before any expert can be summoned: the scorer verifies that the
+   * expert id exists on the platform, so a made-up id scores nothing. The
+   * response carries the display fields the summon events replay.
+   */
+  marketExpertList(credential: WorkBuddyCredential, expertType?: 'agent' | 'team' | ''): Promise<readonly MarketExpert[]>;
+  /**
+   * Open a REAL desktop conversation and return the ids the server assigned.
+   *
+   * The expert and skill tasks join their events to a conversation the server
+   * has actually seen, so a locally invented `requestId` scores nothing. This
+   * starts a chat, reads the server's id out of the SSE stream, then drops the
+   * rest of the stream — the answer itself is irrelevant, only its identity is.
+   *
+   * Returns `undefined` instead of throwing when the conversation cannot be
+   * opened or carries no recognisable id, because every caller is a best-effort
+   * task chain.
+   */
+  openConversation(credential: WorkBuddyCredential, expertId?: string, signal?: AbortSignal): Promise<{
+    conversationId: string;
+    requestId: string;
+  } | undefined>;
   /**
    * Report one chat-activity event to the growth system.
    *
-   * The body is an ARRAY holding a single `chat_request_send` event, and every
+   * The body is an ARRAY holding a single chat_request_send event, and every
    * field is filled in: a three-field minimal event is accepted with 200 and
    * then silently dropped, so the full shape is load-bearing rather than
-   * cosmetic. `userId` is the one field the server actually keys on — without
-   * it the request still answers 200 and scores nothing.
+   * cosmetic. userId is the one field the server actually keys on.
    *
-   * One report per account per day is the quota the reference panel settled on;
-   * a single report lights the growth streak and unlocks the `first_buddy`
+   * One report per account per day is the quota the reference panel settled
+   * on; a single report lights the growth streak and unlocks the first_buddy
    * family, which is why this runs before the task-centre pass.
    */
   reportActivity(credential: WorkBuddyCredential, conversationId?: string): Promise<void>;
@@ -199,6 +528,81 @@ export declare class WorkBuddyUpstreamClient {
    * Returns 0 only when the field is genuinely absent.
    */
   growthStreakDays(credential: WorkBuddyCredential): Promise<number>;
+  /**
+   * The full streak picture: days, tier unlock state, and what each tier pays.
+   *
+   * Read before redeeming, because the tier state is the only honest answer to
+   * "is there anything to claim": the redeem endpoint answers 403 for a locked
+   * tier, which is indistinguishable from a real failure once the response is
+   * just an error.
+   */
+  growthStreakFull(credential: WorkBuddyCredential): Promise<WorkBuddyStreakStatus>;
+  /**
+   * Redeem one unlocked streak tier.
+   *
+   * A locked tier answers 403 ("连续登录天数不足"); callers check the status from
+   * {@link growthStreakFull} first, so this only throws for genuine failures.
+   * The client token is the upstream's idempotency key — a fresh one per attempt
+   * keeps a retry from being read as a duplicate of the last one.
+   */
+  redeemStreakTier(credential: WorkBuddyCredential, tier: string): Promise<void>;
+  /** How many lottery draws are available right now. */
+  lotteryChances(credential: WorkBuddyCredential): Promise<number>;
+  /**
+   * Draw the lottery once.
+   *
+   * Returns the raw prize payload: its shape is set by the running campaign, so
+   * it is passed through rather than modelled.
+   */
+  lotteryDraw(credential: WorkBuddyCredential): Promise<unknown>;
+  /**
+   * The buddy profile, or undefined when the account has no buddy yet.
+   *
+   * `data.buddy` is null / absent / an empty object depending on how far the
+   * account got, and all three mean the same thing to a caller: adopt first.
+   */
+  buddyInfo(credential: WorkBuddyCredential): Promise<{
+    instanceId: number;
+    name: string;
+  } | undefined>;
+  /** Agree to the buddy terms. Idempotent upstream. */
+  buddyAgree(credential: WorkBuddyCredential): Promise<void>;
+  /**
+   * Adopt the first buddy.
+   *
+   * Gated upstream on having reported activity that day: without it the answer
+   * is 400 "first_buddy task not completed yet". Callers treat that as "not yet"
+   * rather than an error, which is why it is thrown as-is for them to classify.
+   */
+  buddyAdoptFirst(credential: WorkBuddyCredential): Promise<void>;
+  /** Current travel state for the account's buddy. */
+  buddyTravelStatus(credential: WorkBuddyCredential): Promise<WorkBuddyTravelState>;
+  /**
+   * Send the buddy travelling.
+   *
+   * The location is always 4 (古镇客栈): the four locations have identical
+   * reward and duration ranges, so there is nothing to optimise.
+   */
+  buddyTravelDepart(credential: WorkBuddyCredential, locationId?: number): Promise<void>;
+  /**
+   * Collect an arrived trip's reward.
+   *
+   * `recordId` is required and comes from the status read; the upstream rejects
+   * a claim without it.
+   */
+  buddyTravelClaim(credential: WorkBuddyCredential, recordId: number): Promise<number>;
+  /** Whether yesterday is a gap in the activity heatmap. */
+  heatmapYesterdayMissed(credential: WorkBuddyCredential): Promise<boolean>;
+  /** Spend one makeup card on a date. Idempotent for an already-filled date. */
+  useMakeupCard(credential: WorkBuddyCredential, date: string): Promise<void>;
+  /**
+   * Call a growth-domain endpoint and return its unwrapped `data`.
+   *
+   * These endpoints live on the chat host with the billing header set, and
+   * carry the same envelope as everything else. Centralised here because every
+   * growth call needs the identical envelope check.
+   */
+  private growthJson;
   /** Legacy thin wrapper kept for `status`/`doctor`: returns raw envelope data. */
   credits(credential: WorkBuddyCredential): Promise<{
     ok: true;
@@ -378,6 +782,25 @@ export declare class WorkBuddyAccountPool {
    * lives on the pool and is re-applied from settings after each scan.
    */
   private disabledIds;
+  /**
+   * Per-account credit floor, keyed by account id. 0 (or absent) means "spend
+   * it all".
+   *
+   * A reserved balance is protection, not a hard limit the upstream knows
+   * about: the pool simply stops picking that account once its last known
+   * balance is at or below the floor, so the user keeps a cushion instead of
+   * draining every account to zero.
+   */
+  private creditReserves;
+  /**
+   * Last known credit balance per account, epoch ms aside.
+   *
+   * Refreshed in the background after a successful request, so a pick can
+   * consult it. An account with no reading is treated as usable: refusing to
+   * pick an account just because its balance has not been checked yet would
+   * strand a healthy pool, and the first 402 still cools it as before.
+   */
+  private creditBalances;
   /**
    * Last time each account served a request, epoch ms. Drives the idle term
    * of the priority-mode weighting below: an account that just served loses to
@@ -401,6 +824,8 @@ export declare class WorkBuddyAccountPool {
     exhaustCooldownMs?: number;
     distribution?: AccountDistribution;
     disabledAccountIds?: readonly string[];
+    /** Per-account credit floor, keyed by account id. Absent keeps the current map. */
+    creditReserves?: Readonly<Record<string, number>>;
   }): void;
   /** Rescan the auth directories and merge newly discovered accounts. */
   scan(): Promise<WorkBuddyAccount[]>;
@@ -470,6 +895,33 @@ export declare class WorkBuddyAccountPool {
    * not count as used for the account that was merely tried.
    */
   noteServed(accountId: string): void;
+  /**
+   * Record an account latest known credit balance.
+   *
+   * Called after a request and by the card balance refresh, so the reserve
+   * check has something to compare against. A reading for an unknown account is
+   * dropped: `scan()` rebuilds the account list and a stale id would otherwise
+   * accumulate forever.
+   */
+  noteCredits(accountId: string, balance: number): void;
+  /** Last known balance for one account, or undefined when never read. */
+  creditsOf(accountId: string): number | undefined;
+  /** The credit floor the user set for one account; 0 when unset. */
+  creditReserveOf(accountId: string): number;
+  /**
+   * Replace every reserve. Called from settings on each apply, so the map
+   * mirrors the saved document exactly instead of accumulating old keys.
+   */
+  setCreditReserves(reserves: Readonly<Record<string, number>>): void;
+  /** Every reserve currently in force, keyed by account id. */
+  creditReservesInOrder(): Record<string, number>;
+  /**
+   * Whether an account is held back only by its reserve.
+   *
+   * Separates "resting to protect credits" from every other reason an account
+   * is out of rotation, which is what the card shows the user.
+   */
+  isReserved(accountId: string): boolean;
   /**
    * The account that served the most recent request, if any.
    *
@@ -636,7 +1088,27 @@ interface WorkBuddyAdapter {
 export declare function createWorkBuddyAdapter(options: WorkBuddyAdapterOptions): WorkBuddyAdapter;
 //#endregion
 //#region src/scheduler.d.ts
+/** How often the loop wakes to look for a due job. */
+/**
+ * How long to wait for event scoring to land before re-reading the task list.
+ *
+ * Scoring is asynchronous on the upstream side, so an immediate re-read still
+ * shows the old progress and the claim pass would skip a task that is in fact
+ * now claimable. Measured: the chain is reflected by about eight seconds.
+ */
+export declare const EVENT_SCORE_WAIT_MS = 9000;
+export declare const AUTOMATION_TICK_MS = 60000;
 /** Which jobs the automation runs, and when. */
+/**
+ * The persisted daily earnings ledger.
+ *
+ * `date` is the local day the counters belong to: a ledger from a previous day
+ * is discarded on load rather than carried forward as "today".
+ */
+interface AutomationLedger {
+  date: string;
+  accounts: Record<string, AutomationAccountEarnings>;
+}
 interface AutomationOptions {
   /** Master switch; false stops every job. */
   enabled?: boolean;
@@ -648,12 +1120,27 @@ interface AutomationOptions {
   reportHours?: readonly number[];
   /** Hour list for the streak-redemption job. */
   streakHours?: readonly number[];
+  /** Hour list for the buddy travel job. */
+  travelHours?: readonly number[];
   /** Per-account serial delay, in milliseconds. */
   accountDelayMs?: number;
+  /** Override the gap between expert chains, in milliseconds (tests use 0). */
+  expertGapMs?: number;
+  /** Override the event-scoring wait, in milliseconds (tests use 0). */
+  eventScoreWaitMs?: number;
   /** Override the clock, for tests. */
   now?: () => Date;
   /** Logger; defaults to a no-op so tests stay quiet. */
   logger?: SchedulerLogger;
+  /**
+   * Persist the daily earnings ledger, and restore it on construction.
+   *
+   * The ledger cannot live only in memory: a host restart mid-day would wipe
+   * what the automation already earned, and the card would show nothing for
+   * rewards that really were collected.
+   */
+  loadEarnings?: () => AutomationLedger | undefined;
+  saveEarnings?: (ledger: AutomationLedger) => void;
 }
 /** Logger surface, kept structural so any host logger fits. */
 interface SchedulerLogger {
@@ -679,6 +1166,61 @@ interface AutomationJobState {
   /** Human-readable summary of the last run. */
   message?: string;
 }
+/**
+ * What the automation earned for ONE account today.
+ *
+ * Reset at the local day boundary alongside the per-job "already ran today"
+ * guard, so the card shows today rather than a running total that never
+ * answers "did it do anything for this account recently".
+ */
+interface AutomationAccountEarnings {
+  /** Credits the automation claimed from the task centre today. */
+  credit: number;
+  /** Energy claimed from the task centre today. */
+  energy: number;
+  /** Tasks claimed today. */
+  claimed: number;
+  /**
+   * Credits the automation collected from check-in today.
+   *
+   * Kept separate from `credit` because they are different achievements and the
+   * card shows them on their own lines: "the automation claimed 3 tasks" and
+   * "the automation checked in" are not the same claim to the user.
+   */
+  checkinCredit: number;
+  /** Credits from streak redemption + lottery today. */
+  bonusCredit: number;
+  /** Credits from the buddy adoption / travel loop today. */
+  travelCredit: number;
+  /** Local date the counters belong to. */
+  date: string;
+}
+/** What ONE account gained during a single run. */
+interface AutomationAccountGain {
+  credit: number;
+  energy: number;
+  claimed: number;
+  checkinCredit: number;
+  bonusCredit: number;
+  travelCredit: number;
+}
+/** Totals from running the whole ordered pass at once. */
+interface AutomationRunSummary {
+  /** How many jobs actually ran (a job with no hour is skipped). */
+  jobsRun: number;
+  /** Accounts that finished without error, summed across jobs. */
+  okCount: number;
+  /** Accounts that failed, summed across jobs. */
+  failed: number;
+  credit: number;
+  energy: number;
+  claimed: number;
+  /**
+   * What each account gained during THIS run, keyed by account id. Only
+   * accounts that gained something appear.
+   */
+  accounts: Readonly<Record<string, AutomationAccountGain>>;
+}
 /** Automation snapshot for the status document and the card. */
 interface AutomationStatus {
   enabled: boolean;
@@ -688,15 +1230,48 @@ interface AutomationStatus {
   taskHours: readonly number[];
   reportHours: readonly number[];
   streakHours: readonly number[];
+  travelHours: readonly number[];
   jobs: {
     checkin: AutomationJobState;
     report: AutomationJobState;
     tasks: AutomationJobState;
     streak: AutomationJobState;
+    travel: AutomationJobState;
   };
   /** Claimable tasks seen on the most recent task pass, across accounts. */
   claimableSeen: number;
+  /**
+   * Per-account totals for today, keyed by account id. Only accounts that
+   * actually earned something appear, so the card can render "no earnings"
+   * as an absence rather than a zero it has to explain.
+   */
+  earningsToday: Readonly<Record<string, AutomationAccountEarnings>>;
+  /**
+   * Whether a manual run is in flight right now.
+   *
+   * A run takes tens of seconds (one upstream call per account per job, plus
+   * the scoring wait), which is far too long for the card to hold a request
+   * open. The button starts a run and the panel polls this flag instead.
+   */
+  runInProgress: boolean;
 }
+/** The three plus one job kinds, in a stable order. */
+type AutomationJobKind = 'checkin' | 'tasks' | 'report' | 'streak' | 'travel';
+/** The four jobs in the order a tick runs them: report before tasks, always. */
+export declare const AUTOMATION_JOB_KINDS: readonly AutomationJobKind[];
+/** Reject anything that is not a job kind, so a route cannot name an unknown job. */
+export declare function isAutomationJobKind(value: unknown): value is AutomationJobKind;
+export declare function dayKey(date: Date): string;
+/**
+ * Whether `now`'s local hour is one of `hours`.
+ *
+ * The reference panel computes a `nextFire` instant and sleeps until it; this
+ * loop instead wakes every minute and asks "is any job due now". Both fire at
+ * the top of a configured hour, but the polling form cannot miss a slot to a
+ * suspended process — a laptop that slept through 10:00 still runs the job the
+ * moment it wakes, on the same day.
+ */
+export declare function isFireHour(now: Date, hours: readonly number[]): boolean;
 /**
  * The points automation.
  *
@@ -704,21 +1279,34 @@ interface AutomationStatus {
  * {@link start}, and {@link stop} is idempotent so a plugin teardown that fires
  * twice is harmless.
  */
-declare class WorkBuddyScheduler {
+export declare class WorkBuddyScheduler {
   private readonly pool;
   private readonly client;
   private readonly logger;
   private readonly now;
   private readonly delayMs;
+  /**
+   * How long to wait for event scoring before re-reading the task list.
+   * Tests set 0 so a pass does not spend nine real seconds per account.
+   */
+  private readonly eventScoreWaitMs;
+  /**
+   * Gap between two expert summon chains.
+   * Tests set 0 so a pass does not spend six real seconds per expert.
+   */
+  private readonly expertGapMs;
   private enabled;
   private checkinHours;
   private taskHours;
   private reportHours;
   private streakHours;
+  private travelHours;
   private timer;
   private running;
   /** Guards against a slow run overlapping the next tick. */
   private busy;
+  /** True while a manual run is in flight, so the card can poll it. */
+  private runInFlight;
   /**
    * Set once {@link stop} is called.
    *
@@ -729,8 +1317,36 @@ declare class WorkBuddyScheduler {
   private stopped;
   private readonly states;
   private claimableSeen;
+  /**
+   * Credits/energy/tasks earned per account TODAY, keyed by account id.
+   *
+   * Cleared whenever the day key rolls over, so the card always answers
+   * "what did the automation get for THIS account today".
+   */
+  private earnings;
+  /** Day key the counters above belong to. */
+  private earningsDate;
+  /** Host hooks that persist the ledger across restarts. */
+  private readonly loadEarnings;
+  private saveEarningsFn;
   constructor(pool: WorkBuddyAccountPool, client: WorkBuddyUpstreamClient, options?: AutomationOptions);
   /** Apply a new configuration; safe to call while running. */
+  /**
+   * Install the persistence hook once the host settings service is available.
+   *
+   * Separate from the constructor because the scheduler is built with the pool,
+   * long before the settings section exists; a ledger written before that point
+   * would have nowhere to go.
+   */
+  setEarningsPersistence(save: (ledger: AutomationLedger) => void): void;
+  /**
+   * Fold a previously persisted ledger back in, when it belongs to today.
+   *
+   * Used after the settings document becomes readable, which happens after
+   * construction; a ledger from an earlier day is ignored so the counters never
+   * claim yesterday as today.
+   */
+  applyEarningsLedger(ledger: AutomationLedger): void;
   applyConfig(options: AutomationOptions): void;
   /** Hours for one job, used by the loop and the status document. */
   private hoursOf;
@@ -739,6 +1355,39 @@ declare class WorkBuddyScheduler {
   /** Stop the loop. Idempotent, and safe before `start`. */
   stop(): void;
   /** Snapshot for the status document. */
+  /**
+   * Run one job immediately, regardless of the clock.
+   *
+   * Exists so the automation can be verified from the card without waiting for
+   * its hour. A manual run is recorded exactly like a scheduled one, so the
+   * timer will not repeat it later the same day: every job is idempotent, but a
+   * second pass would still be wasted upstream calls.
+   *
+   * `force` ignores the already-ran-today guard, which is what pressing the
+   * button a second time means.
+   */
+  runNow(kind: AutomationJobKind, force?: boolean): Promise<AutomationJobState>;
+  /**
+   * Run every job once, in the scheduled order.
+   *
+   * Order matters and is not configurable: the activity report has to land
+   * before the task pass reads task progress, or the pass sees counters the
+   * report would have moved. This is what the card's single button calls.
+   */
+  /**
+   * Start a full pass in the background and return immediately.
+   *
+   * A pass takes tens of seconds - one upstream round trip per account per job,
+   * plus the scoring wait - which is far too long to hold the card request open:
+   * the browser or the host web server would time out, and the user would see
+   * a hung button for a run that is actually working.
+   *
+   * Returns whether a run started. A second call while one is in flight is
+   * ignored rather than queued: pressing the button twice means hurry up, and
+   * the run already under way covers it.
+   */
+  startRunAll(): boolean;
+  runAll(): Promise<AutomationRunSummary>;
   status(): AutomationStatus;
   /**
    * One poll: run every due job, serially.
@@ -749,6 +1398,43 @@ declare class WorkBuddyScheduler {
    */
   private tick;
   /** Run one job against every eligible account and record the outcome. */
+  /**
+   * Add one account's take to today's counters, resetting first if the day
+   * rolled over. Called from the task pass, which is the only job that earns.
+   */
+  /**
+   * Today's per-account earnings, as a plain object for the status document.
+   *
+   * Rolls the day first so a status read just after midnight does not report
+   * yesterday's totals under today's date.
+   */
+  private earningsSnapshot;
+  /**
+   * Add one account take to today counters, resetting first if the day rolled
+   * over. Every source is tracked separately so the card can show what earned
+   * what, rather than one opaque total.
+   */
+  private recordEarnings;
+  /** Clear the per-account counters when the local day changes. */
+  private rollEarnings;
+  /**
+   * Write the ledger through the host hook, when one was supplied.
+   *
+   * Best effort on purpose: a failed save must never abort a run that has
+   * already collected rewards, and the in-memory ledger keeps serving the card
+   * for the rest of the session either way.
+   */
+  private persistEarnings;
+  /**
+   * Run one job against every eligible account and record the outcome.
+   *
+   * The task job runs in TWO passes. The first sends the event chains that light
+   * up client-scored tasks; the second collects rewards. They are separate
+   * because scoring lands asynchronously — a chain sent and claimed within the
+   * same breath finds the task still un-scored — and because sending is fast
+   * while claiming wants the whole pool to have been lit up first. Splitting
+   * them costs one shared wait instead of one wait per account.
+   */
   private runJob;
   /** Compose the one-line summary shown on the card. */
   private summarise;
@@ -769,6 +1455,42 @@ declare class WorkBuddyScheduler {
    * exists to avoid.
    */
   private reportOne;
+  private sendEventChains;
+  /**
+   * Send one chain on the channel it was built for.
+   *
+   * The transport is not a detail of the sender: the scorer keys different
+   * tasks to different fingerprint families, so a web-scored event posted as a
+   * desktop event is accepted and then ignored.
+   */
+  private sendChain;
+  /**
+   * Build every chain that scores one task.
+   *
+   * Most tasks need a single chain; `template_5` needs five, because the scorer
+   * counts distinct `template_used` events rather than a boolean. The two tasks
+   * that join a conversation (skill, expert) open a real one first, which is why
+   * this is async.
+   */
+  private chainsFor;
+  /**
+   * The summon-and-use chains for the expert tasks.
+   *
+   * Two steps per expert, and both are load-bearing: the summon events alone are
+   * impressions, and a use event on its own scores nothing because the scorer
+   * looks the conversation up. Only a real chat with `X-Expert-Id` produces an
+   * id it will accept.
+   */
+  private expertChains;
+  /**
+   * The 腾讯轻量云 expert chain.
+   *
+   * Structurally the same as the expert task, with two differences the scorer
+   * checks: `agent_task_created` has to name the expert, and the use event has
+   * to report `mode: 'LOCAL'` with an empty type and zero cost — that is what
+   * the lighthouse criterion looks for.
+   */
+  private lighthouseChains;
   /**
    * The task-centre pass for one account.
    *
@@ -779,15 +1501,28 @@ declare class WorkBuddyScheduler {
    */
   private runTasks;
   /**
-   * Streak redemption and lottery.
+   * Streak redemption plus the lottery it unlocks.
+   *
+   * Tiers unlock on consecutive active days (7/14/28). Redeeming one pays
+   * credits, energy, a makeup card and — the part nothing else grants — lottery
+   * draws, so the draw runs straight after and only for the chances in hand.
    *
-   * Left as a deliberate no-op placeholder: the tier/lottery endpoints need
-   * their own round of probing against the live upstream before they can be
-   * wired safely, and a wrong call here could burn a redemption. The job slot,
-   * scheduling and status plumbing already exist, so filling it in is a
-   * self-contained change.
+   * Everything here is idempotent: a tier already claimed is skipped by its
+   * status, and a draw consumes one chance, so a replay cannot double-spend.
    */
   private redeemStreak;
+  /**
+   * One trip through the buddy travel loop for an account.
+   *
+   * A single pass advances the state machine by at most one step: a trip
+   * that has arrived is collected, and an idle buddy is sent out. A buddy
+   * already travelling is left alone — there is nothing to do until it lands.
+   *
+   * Measured against the live upstream: the departed trip reports
+   * `dailyLimitReached` immediately, so the once-a-day limit needs no local
+   * bookkeeping.
+   */
+  private runTravel;
 }
 //#endregion
 //#region src/status.d.ts
@@ -873,6 +1608,10 @@ export declare const POOL_RESET_COOLDOWN_PATH = "/plugins/dsh-workbuddy-xdpool/c
 export declare const POOL_CHECKIN_PATH = "/plugins/dsh-workbuddy-xdpool/checkin";
 /** Plugin-owned model-selection save endpoint (writes the settings section). */
 export declare const POOL_MODELS_SAVE_PATH = "/plugins/dsh-workbuddy-xdpool/models/save";
+/** Run one automation job immediately, so the card can verify it on demand. */
+export declare const POOL_AUTOMATION_RUN_PATH = "/plugins/dsh-workbuddy-xdpool/automation/run";
+/** Set or clear one account's reserved-credit floor. */
+export declare const POOL_CREDIT_RESERVE_PATH = "/plugins/dsh-workbuddy-xdpool/accounts/credit-reserve";
 /** One pool account's row, token-free. */
 interface PoolWebAccount {
   id: string;
@@ -901,6 +1640,24 @@ interface PoolWebAccount {
    */
   disabled: boolean;
   rateLimitHits: number;
+  /**
+   * Credits the user asked to keep for this account. The pool stops picking the
+   * account once its balance reaches the reserve, so this many credits survive.
+   * 0 means the account may be spent down as before.
+   */
+  creditReserve: number;
+  /**
+   * Whether the account is held back purely by its reserve right now. Kept
+   * distinct from `cooling`: a reserved account is healthy and simply
+   * protected, which is a different thing to tell the user than rate-limited.
+   */
+  reserved: boolean;
+  /**
+   * What the automation earned for this account today. Absent when it earned
+   * nothing (or the automation never ran for it), so the card can stay quiet
+   * instead of printing a row of zeroes.
+   */
+  automationToday?: PoolWebAutomationEarnings;
   /** ISO timestamp of the last successful use (best-effort pool bookkeeping). */
   lastUsedAt?: string;
   /** Aggregated credit summary for the account, read-only. */
@@ -1018,6 +1775,8 @@ interface PoolWebStatus {
   };
   /** Daily-points automation state, so the card can show what ran and when. */
   automation: PoolWebAutomation;
+  /** Per-account credit floors currently in force, keyed by account id. */
+  creditReserves: Readonly<Record<string, number>>;
 }
 /** One automation job's last run, as shown on the card. */
 interface PoolWebAutomationJob {
@@ -1058,9 +1817,38 @@ interface PoolWebAutomation {
     report: PoolWebAutomationJob;
     tasks: PoolWebAutomationJob;
     streak: PoolWebAutomationJob;
+    travel: PoolWebAutomationJob;
   };
   /** Claimable tasks seen on the most recent task pass, across accounts. */
   claimableSeen: number;
+  /**
+   * Whether a manual run is in flight. The card polls this to know when to
+   * stop showing progress and report the result.
+   */
+  runInProgress: boolean;
+  /**
+   * Per-account credits/energy/tasks the automation earned TODAY, keyed by
+   * account id. An account that earned nothing is simply absent, so the card
+   * can say "nothing yet" instead of showing a bare zero.
+   */
+  earningsToday: Readonly<Record<string, PoolWebAutomationEarnings>>;
+}
+/** Today's automation take for one account. */
+interface PoolWebAutomationEarnings {
+  /** Credits claimed from the task centre today. */
+  credit: number;
+  /** Energy claimed from the task centre today. */
+  energy: number;
+  /** Tasks claimed today. */
+  claimed: number;
+  /** Credits collected from check-in today. */
+  checkinCredit: number;
+  /** Credits from streak redemption and the lottery today. */
+  bonusCredit: number;
+  /** Credits from buddy adoption and the travel loop today. */
+  travelCredit: number;
+  /** Local date the counters belong to (YYYY-MM-DD). */
+  date: string;
 }
 /**
  * The two gateways, matching the provider ids the host registers. `cn` is the
@@ -1071,6 +1859,72 @@ type PoolRegion = 'cn' | 'global';
 /** How the pool spreads requests across its accounts. */
 type PoolDistribution = 'priority' | 'round-robin' | 'balanced';
 //#endregion
+//#region src/web-status.d.ts
+/** Constructor dependencies — a narrow slice of the pool runtime. */
+interface PoolStatusRouteOptions {
+  pool: WorkBuddyAccountPool;
+  /** One catalog per region; the card reads the one for its active tab. */
+  catalogs: Readonly<Record<PoolRegion, WorkBuddyCatalog>>;
+  client: WorkBuddyUpstreamClient;
+  /** Lazily resolve the running loopback shim, when it has bound a port. */
+  shim?: () => {
+    running: boolean;
+    baseUrl?: string;
+  };
+  /**
+   * The daily-points automation, when the host half has one.
+   *
+   * Optional so these routes still mount on a profile that assembled a pool
+   * without a scheduler (the CLI and the tests do exactly that); the card then
+   * reports the automation as off instead of showing a broken panel.
+   */
+  scheduler?: () => AutomationStatus;
+  /**
+    /**
+     * Start a manual pass, for the card's "run now" button.
+     *
+     * Returns whether a run STARTED, not its result: a pass takes tens of
+     * seconds, so it runs in the background and the card polls the scheduler
+     * status for progress and earnings.
+     */
+  runAutomation?: (job: string, force: boolean) => boolean;
+  /**
+   * Persist one account's reserved-credit floor. Same settings document as every
+   * other card write, so it survives a restart and is re-applied after a scan.
+   * Absent without a settings service: the route then answers 503.
+   */
+  setCreditReserve?: (accountId: string, reserve: number) => Promise<void> | void;
+  /**
+   * Persist the user's model selection. Provided by the host half, which owns
+   * the settings section; absent when the plugin runs without a settings
+   * service (the save route then reports 503 rather than pretending to work).
+   */
+  /**
+   * Persist one region's selection. The region travels with the payload: the two
+   * gateways advertise different rosters, so the domestic tab and the
+   * international tab each own their list and must never overwrite each other.
+   */
+  saveSelection?: (region: PoolRegion, selection: PoolWebModelSelection) => Promise<void> | void;
+  /**
+   * Persist one account switch. Same settings document as every other card
+   * write, so it survives a restart and is re-applied after each re-scan.
+   * Absent without a settings service: the route then answers 503.
+   */
+  setAccountDisabled?: (accountId: string, disabled: boolean) => Promise<void> | void;
+}
+/**
+ * Assemble the card's status document. Per-account credits and check-in state
+ * are queried live; a failing query degrades to `creditsError` / `checkinError`
+ * rather than failing the whole document. Never throws.
+ */
+export declare function poolWebStatus(deps: PoolStatusRouteOptions, region?: PoolRegion): Promise<PoolWebStatus>;
+/**
+ * Mount the read-only routes on a context where `webServer` is available. The
+ * caller uses `ctx.inject(['webServer'], ...)` so Desktop startup order cannot
+ * make this registration disappear.
+ */
+export declare function registerPoolStatusRoute(ctx: Context$1, deps: PoolStatusRouteOptions): void;
+//#endregion
 //#region src/index.d.ts
 /** Stable Cordis plugin name. */
 export declare const name = "llm-workbuddy-xdpool";
@@ -1092,11 +1946,16 @@ export interface Config {
   /**
    * How the pool spreads requests across accounts.
    *
-   * `priority` (default) drains one account before moving to the next, which
-   * is what a pool of your own accounts is for. `round-robin` splits the
-   * spend evenly instead. Absent reads as `priority`.
+   * - `priority` (default) drains one account before moving to the next, which
+   *   is what a pool of your own accounts is for.
+   * - `round-robin` walks the pool in order, so the spend splits evenly.
+   * - `balanced` draws at random, weighting whichever account has been idle
+   *   longest. Spend still spreads, but without a fixed order, so one unhealthy
+   *   account cannot pin the pool to itself.
+   *
+   * Absent reads as `priority`.
    */
-  distribution?: 'priority' | 'round-robin';
+  distribution?: 'priority' | 'round-robin' | 'balanced';
   /**
    * Account ids switched off on the card. A disabled account is never picked
    * to serve a request, but it stays in the pool and on the card so it can be
@@ -1104,6 +1963,12 @@ export interface Config {
    * survive re-scans (see WorkBuddyAccountPool.disabledIds).
    */
   disabledAccountIds?: string[];
+  /**
+   * Per-account credit floor, keyed by account id. The pool stops picking an
+   * account once its last known balance reaches this value, so the reserved
+   * credits survive. Absent or 0 spends the account down as before.
+   */
+  creditReserves?: Record<string, number>;
   /**
    * Model ids enabled in the picker. Absent means "every model the catalog
    * advertises" — an unconfigured install should never present an empty model
@@ -1136,6 +2001,13 @@ export interface Config {
    * fresh install with background traffic.
    */
   automation?: AutomationConfig;
+  /**
+   * The automation's daily earnings ledger, written by the scheduler itself.
+   *
+   * It lives in settings rather than only in memory so a host restart mid-day
+   * does not wipe what the automation already earned.
+   */
+  automationEarnings?: AutomationLedger;
 }
 /** One region's saved model selection. */
 export interface ModelSelectionConfig {
@@ -1166,6 +2038,8 @@ export interface AutomationConfig {
   taskHours?: number[];
   /** Hours at which streak redemption runs. */
   streakHours?: number[];
+  /** Hours at which the buddy travel loop runs. */
+  travelHours?: number[];
   /** How long an account rests after its credits run out, in milliseconds. */
   exhaustCooldownMs?: number;
 }
@@ -1238,4 +2112,4 @@ export declare function createCore(logger?: {
  */
 export declare function apply(ctx: Context, config?: Config): void;
 //#endregion
-export type { AccountStatus, Context, ModelSelection, PoolWebCheckin, PoolWebCheckinClaim, PoolWebModel, PoolWebModelSelection, PoolWebStatus, UpstreamErrorKind, WorkBuddyAccount, WorkBuddyAdapter, WorkBuddyCredential, WorkBuddyModelInfo, WorkBuddyShim, WorkBuddyStatus };
+export type { AccountStatus, AutomationLedger, AutomationRunSummary, AutomationStatus, Context, ExpertUseMode, MarketExpert, ModelSelection, PoolStatusRouteOptions, PoolWebCheckin, PoolWebCheckinClaim, PoolWebModel, PoolWebModelSelection, PoolWebStatus, SchedulerLogger, TaskEventChain, TaskEventTransport, UpstreamErrorKind, WorkBuddyAccount, WorkBuddyAdapter, WorkBuddyCredential, WorkBuddyModelInfo, WorkBuddyShim, WorkBuddyStatus };