dsh-task-time-cost 0.0.0-stage → 0.2.8-beta.2

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Task time and cost estimator",
+    "description": "A reference for the wait: open the clock beside Token statistics for remaining time, elapsed time, Token budgets and cost references. Settings and calibration shows local route samples. No separate estimator call, saved message bodies or statistics uploads by default. Public list prices are not channel invoices; missing stays unknown. Preview for Windows / DSH 0.2.2-rc.2; exact native running-line placement is unsupported.",
+    "detail": "docs/public/DETAIL.md"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "任务耗时与费用预估",
+    "description": "让等待有个参考：在 Token 统计旁点击时钟，查看剩余时间、实际用时、Token 预算和费用参考；在“设置与校准”查看本地路由样本。无需另起估价模型，默认不保存正文或上传统计。公共目录价不代表渠道账单，缺价保持未知。当前为 Windows / DSH 0.2.2-rc.2 公开预览版；精确原生运行状态行内位置尚不支持。",
+    "detail": "docs/public/DETAIL.zh.md"
+  }
+}

package/package.json

@@ -1,6 +1,124 @@
 {
   "name": "dsh-task-time-cost",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.8-beta.2",
+  "type": "module",
+  "description": "Remaining-time, Token budget and reference cost estimates for DeepSeek Harness, calibrated locally without a separate model call.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24",
+    "dsh": "0.2.2-rc.2"
+  },
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "locale",
+    "icon.svg",
+    "data",
+    "scripts/import-public-prices.mjs",
+    "README.md",
+    "README.en.md",
+    "COMPATIBILITY.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "docs/public",
+    "CONTRIBUTING.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/**/*.test.ts",
+    "check": "npm run typecheck && npm test && npm run build",
+    "pack:check": "npm pack --dry-run --ignore-scripts"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "task-estimation",
+    "eta",
+    "cost-estimation",
+    "token-usage",
+    "llm-observability",
+    "dsh",
+    "dsh-bundle",
+    "local-first",
+    "developer-tools"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "external": [
+        "react"
+      ],
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.1.0",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.2-rc.2",
+    "@deepseek-ai/schemastery": "3.19.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.1.0",
+    "@deepseek-ai/dsh-agent": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-api-gateway": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-connection": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-ui-chat": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-config-editor": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-storage-domain": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-storage-json": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-token-meter": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-typert-registry": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.2.2-rc.2",
+    "@deepseek-ai/dsh-user-questions": "0.2.2-rc.2",
+    "@deepseek-ai/schemastery": "3.19.0",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "19.2.0",
+    "esbuild": "0.28.2",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "typescript": "~5.9.3",
+    "zod": "4.6.6"
+  },
+  "author": {
+    "name": "leicheng42",
+    "url": "https://github.com/leicheng42"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leicheng42/dsh-task-time-cost.git"
+  },
+  "homepage": "https://github.com/leicheng42/dsh-task-time-cost#readme",
+  "bugs": {
+    "url": "https://github.com/leicheng42/dsh-task-time-cost/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "beta"
+  }
+}

package/scripts/import-public-prices.mjs

@@ -0,0 +1,35 @@
+// Explicit maintainer import of the public models.dev API. The plugin never
+// fetches it in the background or reads a gateway's settings/credentials.
+import { readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+const input = process.argv[2];
+if (!input) throw new Error('Usage: node scripts/import-public-prices.mjs <models.dev api.json>');
+const bytes = await readFile(input);
+const api = JSON.parse(bytes.toString('utf8'));
+const rows = [];
+let unsupported = 0;
+const prices = cost => {
+  const result = {};
+  for (const [source, target] of [['input', 'inputTokens'], ['output', 'outputTokens'], ['cache_read', 'cacheReadTokens'], ['cache_write_5m', 'cacheWrite5mTokens'], ['cache_write_1h', 'cacheWrite1hTokens']]) {
+    const n = cost?.[source];
+    if (typeof n === 'number' && Number.isFinite(n) && n >= 0) result[target] = n.toLocaleString('en-US', { useGrouping: false, maximumFractionDigits: 12 });
+  }
+  return result;
+};
+for (const [provider, info] of Object.entries(api)) {
+  for (const [model, value] of Object.entries(info.models ?? {})) {
+    const rates = prices(value.cost);
+    if (rates.inputTokens === undefined || rates.outputTokens === undefined) continue;
+    const tiers = value.cost?.tiers ?? [];
+    if (!Array.isArray(tiers) || tiers.some(t => t.tier?.type !== 'context' || !Number.isSafeInteger(t.tier.size) || t.tier.size <= 0)) { unsupported++; continue; }
+    const rules = tiers.map((t, index) => ({ id: `context-${index}`, when: { promptTokensAbove: t.tier.size }, mode: 'whole-request', prices: prices(t) }));
+    // Older API entries provide the same legacy condition without tiers.
+    if (!tiers.length && value.cost?.context_over_200k) rules.push({ id: 'context-200k', when: { promptTokensAbove: 200_000 }, mode: 'whole-request', prices: prices(value.cost.context_over_200k) });
+    rows.push({ provider, model, prices: rates, ...(rules.length ? { rules } : {}) });
+  }
+}
+rows.sort((a, b) => `${a.provider}/${a.model}`.localeCompare(`${b.provider}/${b.model}`, 'en'));
+const retrievedAt = new Date().toISOString();
+const data = { source: 'https://models.dev/api.json', license: 'MIT', retrievedAt, version: `models.dev-${retrievedAt.slice(0, 10)}-${createHash('sha256').update(bytes).digest('hex').slice(0, 12)}`, rows };
+await writeFile(new URL('../data/models-dev-prices.json', import.meta.url), JSON.stringify(data) + '\n');
+console.log(JSON.stringify({ rows: rows.length, unsupportedTierModels: unsupported, version: data.version, retrievedAt }));

package/src/client/INTEGRATION.md

@@ -0,0 +1,61 @@
+# Client 对接与验证报告
+
+范围：仅 `src/client`、`tests/client`。对应共享 task-2。业务 DTO 以 `src/shared/wire.ts` 为准，Client 不修改 DTO、Host 或根构建文件。
+
+## 入口与封装
+
+`src/client/index.tsx` 是普通 TSX 模块，导出：
+
+```ts
+export const inject = ['slots', 'locale', 'remote'];
+export function applyClient(ctx: Context): void;
+export const apply = applyClient;
+```
+
+lead 的 Client factory wrapper 必须先挂载 `remoteContribution`，再调用 `applyClient(ctx)`。唯一 Cordis 引用为真实 `@deepseek-ai/cordis` 的 `import type { Context }`；无包级 remote 读取，无 Harness Client 包运行时导入。Client factory 协议与包 id 由 lead 的 esbuild wrapper 处理。
+
+在 apply 内读取 `ctx.get('remote').taskEstimator`、slots、locale。locale 注册 `task-estimate` 命名空间的 `zh` / `en`；界面随 locale revision 更新。注册：
+
+| 槽 | id | order | 数据位置 |
+|---|---|---:|---|
+| `conversation.composer.dock` | `task-estimate` | 2 | `sessionId` 与 `useProjection('taskEstimator')` |
+| `conversation.chat.turnTail` | `task-estimate` | 10 | `turn.turn` 与 `seq` |
+
+投影业务值直接为 `{ revision: number, currentTurn: number | null } | undefined`。当前回合随 revision 立即刷新；历史尾部按明确 turn 读取，避免每个新事件刷新所有历史回合。
+
+## RPC
+
+所有请求处理外层 `RemoteResult`；管理请求还检查内层 `ManagementResult.ok`。Host 拒绝保留 code/message，网络异常、业务错误、15 秒超时均可见并可重试。卸载或取消会 abort，请求晚到不会覆盖新状态。
+
+| 方法 / action | payload / 参数 | 结果处理 |
+|---|---|---|
+| `snapshot(sessionId, turn, signal)` | session id、明确 turn 或 null | 检查 RemoteResult、EstimatorView.error、snapshot.error |
+| `manage('read', '', signal)` | 空字符串 | data.config / history / ProfileSummary[] / diagnostics / storage |
+| `manage('saveConfig', json, signal)` | 完整配置 JSON 字符串 | 本地对象/有限数字检查，完整业务校验由 Host 执行 |
+| `manage('importBaselines', content, signal)` | JSON 或 CSV 原文 | Host 识别格式，界面显示返回失败 |
+| `manage('export', '', signal)` | 空字符串 | exported 字符串变为 JSON Blob 下载，组件释放 URL |
+| `manage('resetCalibration', '', signal)` | 空字符串 | 用户先展开本地二次确认，再发 RPC |
+
+重置提示与 Host 已确认：重置本地性能、工作量学习；保留任务历史、价表/配置、导入基准及 DSH 会话。
+
+## 显示与生命周期
+
+- dock 空闲时显示低干扰入口；运行时主行显示工作耗时、预计剩余、预计总费用；turnTail 显示结束状态、耗时及已记录费用。
+- 缺价、partial、unavailable 明确说明无法完整估算；已知金额单列，不将局部费用当总额或上限。金额直接格式化十进制字符串，不经过浮点数，不同币种分开。
+- 展开包含 Token 分类/覆盖、性能与来源、样本、初始对照、原因及管理。推理/缓存分类不重复求和。常见 reason code 有中英文说明，未知 code 保留可见。
+- 一个 SnapshotStore 共享 session/turn 请求、inflight 和轮询；运行/排队默认 5 秒轮询，等待用户/结束停止轮询；投影立即更新以覆盖短任务。
+- 独立共享本地时钟默认 1 秒更新文字，不发 RPC。等待用户时冻结工作计时和剩余区间，单独累计暂停时间。重置所有 timer/subscription/AbortController 由组件或 Cordis effect 持有。
+- 所有容器/控件继承字体，颜色只使用已核验 `--dsw-alias-*` tokens。原生 details/summary、带 label 的表单、键盘 focus、真实 pending/error、触屏较大点击区和 reduced-motion 支持均在真实槽组件中实现。
+
+## 验证
+
+2026-11-12：
+
+1. `node --test tests/client/*.test.ts`：**21 passed, 0 failed**（最后一轮约 291ms）。
+2. Client 入口与三个 test 文件的 scoped 严格 TypeScript 检查：**通过**。使用根 tsconfig 同等 target / NodeNext / strict / skipLibCheck / JSX React 参数，引用真实 Cordis Context，未改根配置。
+3. esbuild `bundle:true, platform:'browser', format:'cjs', jsx:'transform', external:['react'], write:false`：**通过**。metafile 断言唯一外部依赖是 `react`；没有写构建产物。
+4. 静态运行时 import 检查：只有 React；Cordis 仅 type import；没有 `any`、Harness Client 运行时依赖、预览 HTML、mock shell 或 React/DOM 仿真。
+
+21 个测试覆盖：零值与 unknown、区间合法性、亚秒延迟、极小金额/大整数精度、多币种、缺价/partial 不假上限、暂停/结束本地计时、中英 key 一致性、配置 JSON 对象校验、RemoteResult 和业务双层失败、原文 payload、超时与 abort、无 message 时仍显示错误 code、共享请求、投影合并和短任务、首次晚到投影、5 秒运行轮询、卸载后过期响应保护、本地时钟不发网络请求与清理。
+
+当前环境 Client Inspect 无页面响应；既有 browser control ENOENT。槽与 locale 使用 lead 已读取的精确合同，TurnLocation 与 locale ids 又由官方固定版本 npm 声明核对。**本报告不宣称真实页面视觉验证通过**。实际 factory 安装/槽渲染、明暗主题、窄屏、完整配置操作及下载交互由 lead 的真实宿主集成验证继续完成。

package/src/client/config.ts

@@ -0,0 +1,24 @@
+import type { MessageKey } from './locale.ts';
+
+export const configFields: ReadonlyArray<{ key: string; label: MessageKey; min: number; max?: number; step: number }> = [
+  { key: 'performanceAlpha', label: 'performanceAlpha', min: 0.01, max: 1, step: 0.01 },
+  { key: 'workloadAlpha', label: 'workloadAlpha', min: 0.01, max: 1, step: 0.01 },
+  { key: 'predictionRefreshMs', label: 'predictionRefreshMs', min: 1, step: 1 },
+  { key: 'timerRefreshMs', label: 'timerRefreshMs', min: 1, step: 1 },
+  { key: 'historyRetentionDays', label: 'historyRetentionDays', min: 1, step: 1 },
+  { key: 'profileStaleDays', label: 'profileStaleDays', min: 1, step: 1 },
+  { key: 'minConditionalSamples', label: 'minConditionalSamples', min: 1, step: 1 },
+  { key: 'heuristicFirstTextMs', label: 'heuristicFirstTextMs', min: 0, step: 1 },
+  { key: 'heuristicVisibleTps', label: 'heuristicVisibleTps', min: 0.01, step: 0.1 },
+  { key: 'heuristicTotalCallMs', label: 'heuristicTotalCallMs', min: 0, step: 1 },
+];
+
+export function parseConfiguration(text: string): Record<string, unknown> {
+  const value: unknown = JSON.parse(text);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('CONFIG_OBJECT_REQUIRED');
+  return value as Record<string, unknown>;
+}
+
+export function numericFields(config: Record<string, unknown>): Record<string, string> {
+  return Object.fromEntries(configFields.map(({ key }) => [key, typeof config[key] === 'number' ? String(config[key]) : '']));
+}

package/src/client/details.tsx

@@ -0,0 +1,126 @@
+import * as React from 'react';
+import type { EstimateSnapshot } from '../shared/wire.ts';
+import { costSummary, formatCoverage, formatDuration, formatEta, formatLatency, formatMoneyRanges, formatNumber, formatOrigin, formatTaskType, formatTokenRange, localTiming } from './format.ts';
+import type { MessageKey, Translate } from './locale.ts';
+
+function Facts({ rows }: { rows: ReadonlyArray<readonly [string, React.ReactNode]> }) {
+  return <dl className="dte-facts">{rows.map(([label, value], index) => <React.Fragment key={`${label}-${index}`}><dt>{label}</dt><dd>{value}</dd></React.Fragment>)}</dl>;
+}
+
+const reasonKeys: Record<string, MessageKey> = {
+  'engineering-assumption': 'reasonHeuristic', 'engineering-workload-template': 'reasonWorkloadTemplate',
+  'local-workload-ewma': 'reasonLocalWorkload', 'public-endpoint-reference': 'reasonPublicEndpoint',
+  'reference-range-not-calibrated-confidence': 'reasonReferenceRange', 'conditional-samples-insufficient': 'reasonFewSamples',
+  'reference-range-exhausted-reassessing': 'reasonReassessing', 'output-budget-exhausted-task-still-running': 'reasonBudgetExhausted',
+  'waiting-for-model-response': 'reasonWaitingModel', 'mixed-route-upstream-unknown': 'reasonMixedRoute',
+  'same-provider-model-fallback': 'reasonRouteFallback', 'visible-speed-still-prior': 'reasonSpeedPrior',
+  'stale-profile-retained-for-audit': 'reasonStale', 'reasoning-mode-unknown': 'reasonReasoningUnknown',
+  'no-matching-price': 'reasonNoPrice', 'billing-identity-unknown': 'reasonBillingUnknown',
+  'future-input-cache-split-unknown': 'reasonCacheUnknown', 'future-reasoning-budget-unknown': 'reasonFutureReasoning',
+  'public-reference-price-not-provider-bill': 'reasonReferencePrice', 'user-explicit-same-as-reference': 'reasonSameAs',
+  'price-multiplier-condition-unknown': 'reasonPriceCondition', 'forecast-scenario-reference': 'reasonForecastScenario',
+  'text-stage-no-repeat-wait': 'reasonNoRepeatWait', 'reasoning-already-in-first-text-wait': 'reasonReasoningIncluded',
+  'first-text-plus-body': 'reasonFirstTextBody', 'same-mode-total-call-fallback': 'reasonTotalFallback',
+  'conditional-observed-remaining-range': 'reasonConditional', 'classification:heuristic': 'reasonClassification',
+  'explicit-artifact-count': 'reasonArtifactCount', 'observable-plan-steps': 'reasonPlanSteps',
+  'file-batch-assumption': 'reasonFileBatch', 'explicit-output-token-budget': 'reasonOutputBudget',
+  'requested-length-token-conversion:heuristic': 'reasonLengthConversion', 'observable-attachments': 'reasonAttachments',
+  'no-classification-match': 'reasonNoClassification', 'task-scope-changed': 'reasonScopeChanged',
+  'workload-data-incomplete': 'reasonIncompleteWorkload', 'request-completed': 'reasonRequestCompleted',
+  'endpoint-identity-unknown': 'reasonEndpointUnknown', 'endpoint-unresolved-mixed-route': 'reasonEndpointUnknown',
+  'continuation-local-task-history': 'reasonContinuationHistory', 'continuation-history-insufficient': 'reasonContinuationUnknown',
+  'ai-workload-plan-reference': 'reasonAiPlan',
+};
+export function reasonText(reason: string, t: Translate): string {
+  if (reasonKeys[reason]) return t(reasonKeys[reason]);
+  if (reason.startsWith('classification-rule:')) return t('reasonClassificationRule', { value: reason.slice('classification-rule:'.length) });
+  return t('reasonCode', { value: reason });
+}
+
+export function EstimateDetails({ snapshot, receivedAt, now, locale, t }: { snapshot: EstimateSnapshot; receivedAt: number; now: number; locale: string; t: Translate }) {
+  const timing = localTiming(snapshot, receivedAt, now);
+  const performance = snapshot.performance;
+  const text = (value: string | null | undefined) => value || t('unknown');
+  const number = (value: number | null | undefined, fraction = 0) => formatNumber(value, locale, t, fraction);
+  const referencePrice = snapshot.reasons.includes('public-reference-price-not-provider-bill');
+  const knownCost = costSummary(snapshot, locale, t);
+  const forecast = snapshot.forecastCostStatus === 'free' ? t('free') : formatMoneyRanges(snapshot.estimatedTotalCost, locale, t);
+  const partial = snapshot.forecastCostStatus === 'partial' || snapshot.forecastCostStatus === 'unavailable' || snapshot.observedCostStatus === 'partial' || snapshot.observedCostStatus === 'unpriced';
+
+  return <section aria-label={t('details')}>
+    <p className="dte-muted dte-small">{t('scope')}</p>
+    <Facts rows={[
+      [t('activeTime'), formatDuration(timing.activeMs, t)], [t('pausedTime'), formatDuration(timing.pausedMs, t)],
+      [t('wallTime'), formatDuration(timing.wallMs, t)], [t('remaining'), formatEta(timing.remaining, t)],
+      [t('estimatedTotal'), formatEta(snapshot.estimatedTotalMs, t)],
+      [t('tokenForecast'), formatTokenRange(snapshot.estimatedTotalTokens, locale, t)],
+      [t('tokenRemainingOutput'), formatTokenRange(snapshot.estimatedRemainingOutputTokens, locale, t)],
+      [t(referencePrice ? 'referenceCost' : 'knownCost'), costSummary(snapshot, locale, t)],
+      [t('estimatedCost'), snapshot.forecastCostStatus === 'partial' ? t('partialKnown', { value: forecast }) : forecast],
+      [t('observedCostStatus'), formatCoverage(snapshot.observedCostStatus, t)], [t('forecastCostStatus'), formatCoverage(snapshot.forecastCostStatus, t)],
+    ]} />
+    {snapshot.estimatedRemainingOutputTokens != null && <p className="dte-muted dte-small">{t('tokenRemainingNote')}</p>}
+    {partial && <p className="dte-warn dte-small">{t('incompleteCostDetail')}</p>}
+    {snapshot.unpricedCalls > 0 && <p className="dte-muted dte-small">{t('noPrice', { count: number(snapshot.unpricedCalls) })}</p>}
+    {snapshot.incompleteForecastUnits > 0 && <p className="dte-muted dte-small">{t('incompleteForecast', { count: number(snapshot.incompleteForecastUnits) })}</p>}
+
+    <details className="dte-subsection">
+      <summary>{t('tokenTotal')}</summary>
+      <Facts rows={[
+        [t('tokenTotal'), number(snapshot.observedTokens)], [t('tokenCoverage'), formatCoverage(snapshot.observedTokenStatus, t)],
+        [t('tokenInput'), number(snapshot.tokens.input)], [t('tokenCacheRead'), number(snapshot.tokens.cacheRead)],
+        [t('tokenCacheWrite'), number(snapshot.tokens.cacheWrite)], [t('tokenOutput'), number(snapshot.tokens.output)],
+        [t('tokenReasoning'), number(snapshot.tokens.reasoning)],
+      ]} />
+      <p className="dte-muted dte-small">{t('tokensNote')}</p>
+    </details>
+    <details className="dte-subsection">
+      <summary>{t('basis')}</summary>
+      <Facts rows={[
+        [t('origin'), formatOrigin(snapshot.estimateOrigin, t)], [t('taskType'), formatTaskType(snapshot.taskType, t)],
+        [t('localSamples'), number(snapshot.localPerformanceSamples)], [t('workloadSamples'), number(snapshot.workloadSamples)],
+        [t('calls'), t('callCounts', { completed: number(snapshot.calls.completed), active: number(snapshot.calls.active), failed: number(snapshot.calls.failed) })],
+        [t('tools'), t('toolCounts', { completed: number(snapshot.tools.completed), active: number(snapshot.tools.active) })],
+        [t('toolTime'), formatDuration(snapshot.tools.workMs, t)], [t('algorithm'), snapshot.algorithmVersion],
+      ]} />
+    </details>
+    <details className="dte-subsection">
+      <summary>{t('performance')}</summary>
+      {!performance ? <p className="dte-muted">{t('notAvailable')}</p> : <>
+        <Facts rows={[
+          [t('provider'), text(performance.providerId)], [t('model'), text(performance.modelId)], [t('endpoint'), text(performance.endpointFingerprint)],
+          [t('requestMode'), text(performance.requestMode)], [t('reasoningEffort'), text(performance.reasoningEffort)], [t('serviceTier'), text(performance.serviceTier)],
+          [t('firstContent'), formatLatency(performance.firstContentMs, locale, t)], [t('firstText'), formatLatency(performance.firstTextMs, locale, t)],
+          [t('visibleSpeed'), performance.visibleTps == null ? t('unknown') : t('tokensPerSecond', { value: number(performance.visibleTps, 2) })],
+          [t('callDuration'), formatLatency(performance.totalCallMs, locale, t)], [t('origin'), text(performance.source)],
+          [t('performanceTrust'), performance.trust === 'observed' ? t('performanceObserved') : t('performanceReference')],
+          [t('firstContentSource'), performance.metricOrigins ? formatOrigin(performance.metricOrigins.firstContent, t) : t('unknown')],
+          [t('firstTextSource'), performance.metricOrigins ? formatOrigin(performance.metricOrigins.firstText, t) : t('unknown')],
+          [t('speedSource'), performance.metricOrigins ? formatOrigin(performance.metricOrigins.speed, t) : t('unknown')],
+          [t('totalSource'), performance.metricOrigins ? formatOrigin(performance.metricOrigins.total, t) : t('unknown')],
+        ]} />
+        {performance.stale && <p className="dte-warn">{t('staleProfile')}</p>}
+      </>}
+    </details>
+    <details className="dte-subsection">
+      <summary>{t('initialComparison')}</summary>
+      <Facts rows={[
+        [t('initialTime'), formatEta(snapshot.initial?.estimatedTotalMs, t)],
+        [t('initialCost'), formatMoneyRanges(snapshot.initial?.estimatedTotalCost, locale, t)],
+        [t('activeTime'), formatDuration(timing.activeMs, t)], [t('knownCost'), knownCost],
+      ]} />
+    </details>
+    <details className="dte-subsection">
+      <summary>{t('priceSources')}</summary>
+      {!snapshot.priceSources.length ? <p className="dte-muted">{t('noPriceSources')}</p> : <ul>{snapshot.priceSources.map((source, index) => {
+        let href: string | null = null;
+        try { const url = new URL(source); if (url.protocol === 'http:' || url.protocol === 'https:') href = url.href; } catch { /* A catalog id is valid source data, not a URL. */ }
+        return <li key={`${index}-${source}`}>{href ? <a href={href} target="_blank" rel="noopener noreferrer">{source}</a> : t('sourceDetail', { value: source })}</li>;
+      })}</ul>}
+    </details>
+    <details className="dte-subsection">
+      <summary>{t('reasons')}</summary>
+      {!snapshot.reasons.length ? <p className="dte-muted">{t('noReasons')}</p> : <ul>{snapshot.reasons.map((reason, index) => <li key={`${index}-${reason}`}>{reasonText(reason, t)}</li>)}</ul>}
+    </details>
+  </section>;
+}

package/src/client/format.ts

@@ -0,0 +1,218 @@
+import type { EstimateSnapshot, Money, MoneyRange, ProfileSummary, Span, TaskState } from '../shared/wire.ts';
+import type { MessageKey, Translate } from './locale.ts';
+
+export function numberLocale(locale: string): string {
+  return locale.startsWith('zh') ? 'zh-CN' : locale || 'en';
+}
+
+export function formatNumber(value: number | null | undefined, locale: string, t: Translate, fractionDigits = 0): string {
+  if (value == null || !Number.isFinite(value) || value < 0) return t('unknown');
+  return new Intl.NumberFormat(numberLocale(locale), { maximumFractionDigits: fractionDigits }).format(value);
+}
+
+/**
+ * Durations use unit letters so every row keeps the same narrow footprint in
+ * both locales; above ten minutes the seconds are dropped because a one-line
+ * ETA is read as "about how long", not as a stopwatch.
+ */
+export function formatDuration(milliseconds: number | null | undefined, t: Translate): string {
+  if (milliseconds == null || !Number.isFinite(milliseconds) || milliseconds < 0) return t('unknown');
+  const seconds = Math.floor(milliseconds / 1_000);
+  if (seconds < 60) return t('durationSeconds', { value: seconds });
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) {
+    const rest = seconds % 60;
+    if (rest === 0) return t('durationMinutesOnly', { value: minutes });
+    return minutes >= 10 ? t('durationMinutesOnly', { value: minutes }) : t('durationMinutes', { value: minutes, seconds: rest });
+  }
+  const hours = Math.floor(minutes / 60);
+  const restMinutes = minutes % 60;
+  if (restMinutes === 0) return t('durationHoursOnly', { value: hours });
+  return hours >= 10 ? t('durationHoursOnly', { value: hours }) : t('durationHours', { value: hours, minutes: restMinutes });
+}
+
+export function formatLatency(milliseconds: number | null | undefined, locale: string, t: Translate): string {
+  if (milliseconds == null || !Number.isFinite(milliseconds) || milliseconds < 0) return t('unknown');
+  if (milliseconds < 1_000) return t('durationMilliseconds', { value: formatNumber(milliseconds, locale, t, 1) });
+  if (milliseconds < 60_000) return t('durationSeconds', { value: formatNumber(milliseconds / 1_000, locale, t, 2) });
+  return formatDuration(milliseconds, t);
+}
+
+export function validSpan(range: Span | null | undefined): range is Span {
+  return !!range && Number.isFinite(range.low) && Number.isFinite(range.high) && range.low >= 0 && range.low <= range.high;
+}
+
+export function formatDurationRange(range: Span | null | undefined, t: Translate): string {
+  if (!validSpan(range)) return t('unknown');
+  const low = formatDuration(range.low, t);
+  const high = formatDuration(range.high, t);
+  return low === high ? low : t('range', { low, high });
+}
+
+/**
+ * Rounding steps for a forecast. An estimate is not a stopwatch: a minute-level
+ * figure such as "8m–30m" is what a reader acts on, while "8m 30s" claims a
+ * precision the model does not have. Bounds deliberately snap outward so the
+ * printed interval never looks narrower than the computed one.
+ */
+const ETA_STEPS: ReadonlyArray<readonly [number, number]> = [
+  [60_000, 15_000], [600_000, 60_000], [3_600_000, 300_000], [Number.POSITIVE_INFINITY, 900_000],
+];
+function roundEta(milliseconds: number, direction: 'down' | 'up'): number {
+  const step = ETA_STEPS.find(([limit]) => milliseconds < limit)![1];
+  const rounded = direction === 'down' ? Math.floor(milliseconds / step) * step : Math.ceil(milliseconds / step) * step;
+  return Math.max(0, rounded);
+}
+/** Coarse duration: whole minutes above a minute, so no bound prints stray seconds. */
+function formatCoarse(ms: number, t: Translate): string {
+  const minutes = Math.round(ms / 60_000);
+  if (ms < 60_000) return t('durationSeconds', { value: Math.round(ms / 1_000) });
+  if (minutes < 60) return t('durationMinutesOnly', { value: minutes });
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return rest === 0 ? t('durationHoursOnly', { value: hours }) : t('durationHours', { value: hours, minutes: rest });
+}
+
+/** Compact ETA for the one-line display: coarse bounds, latin units, stable width. */
+export function formatEta(range: Span | null | undefined, t: Translate): string {
+  if (!validSpan(range)) return t('unknown');
+  const roundedLow = roundEta(range.low, 'down');
+  const low = formatCoarse(roundedLow, t);
+  const high = formatCoarse(roundEta(range.high, 'up'), t);
+  if (range.high > 0 && roundedLow === 0) return t('upTo', { value: high });
+  return low === high ? low : t('range', { low, high });
+}
+
+export function formatTokenRange(range: Span | null | undefined, locale: string, t: Translate): string {
+  if (!validSpan(range)) return t('unknown');
+  const low = formatNumber(range.low, locale, t);
+  const high = formatNumber(range.high, locale, t);
+  return t('tokenCount', { value: low === high ? low : t('range', { low, high }) });
+}
+
+/** Format the decimal string exactly: tiny prices and values above 2^53 never round through Number. */
+export function formatDecimal(amount: string, locale: string): string | null {
+  const match = /^(\d+)(?:\.(\d+))?$/.exec(amount);
+  if (!match) return null;
+  const integer = new Intl.NumberFormat(numberLocale(locale), { maximumFractionDigits: 0 }).format(BigInt(match[1]));
+  const fraction = (match[2] ?? '').replace(/0+$/, '');
+  if (!fraction) return integer;
+  const point = new Intl.NumberFormat(numberLocale(locale)).formatToParts(1.1).find((part) => part.type === 'decimal')?.value ?? '.';
+  return `${integer}${point}${fraction}`;
+}
+
+export function formatMoney(value: Money, locale: string, t: Translate): string {
+  const amount = formatDecimal(value.amount, locale);
+  return amount === null || !value.currency ? t('unknown') : t('money', { currency: value.currency, value: amount });
+}
+
+export function formatMoneyList(values: readonly Money[] | null | undefined, locale: string, t: Translate): string {
+  if (!values?.length) return t('unknown');
+  return values.map((value) => formatMoney(value, locale, t)).join(t('listSeparator'));
+}
+
+export function formatMoneyRanges(values: readonly MoneyRange[] | null | undefined, locale: string, t: Translate): string {
+  if (!values?.length) return t('unknown');
+  return values.map((value) => {
+    const low = formatDecimal(value.range.low, locale);
+    const high = formatDecimal(value.range.high, locale);
+    if (low === null || high === null || !value.currency) return t('unknown');
+    return low === high
+      ? t('money', { currency: value.currency, value: low })
+      : t('moneyRange', { currency: value.currency, low, high });
+  }).join(t('listSeparator'));
+}
+
+export function isLive(state: TaskState): boolean {
+  return state === 'running' || state === 'queued';
+}
+
+export function isTerminal(state: TaskState): boolean {
+  return state === 'completed' || state === 'failed' || state === 'cancelled' || state === 'interrupted';
+}
+
+const states: Record<TaskState, MessageKey> = {
+  queued: 'stateQueued', running: 'stateRunning', waiting_user: 'stateWaiting', completed: 'stateCompleted',
+  failed: 'stateFailed', cancelled: 'stateCancelled', interrupted: 'stateInterrupted',
+};
+export function formatState(state: TaskState, t: Translate): string { return t(states[state]); }
+
+const origins: Record<EstimateSnapshot['estimateOrigin'], MessageKey> = {
+  heuristic: 'originHeuristic', 'public-measured': 'originPublic', 'local-measured': 'originLocal', mixed: 'originMixed',
+};
+export function formatOrigin(origin: EstimateSnapshot['estimateOrigin'], t: Translate): string { return t(origins[origin]); }
+
+const taskTypes: Record<string, MessageKey> = {
+  question: 'taskQuestion', writing: 'taskWriting', 'file-analysis': 'taskFileAnalysis', code: 'taskCode', research: 'taskResearch', unknown: 'taskUnknown',
+};
+export function formatTaskType(type: string, t: Translate): string { return t(taskTypes[type] ?? 'taskUnknown'); }
+
+export function formatCoverage(status: string, t: Translate): string {
+  const keys: Record<string, MessageKey> = { complete: 'costComplete', partial: 'costPartial', unpriced: 'costUnpriced', free: 'free', reference: 'costReference', unavailable: 'costUnavailable', unknown: 'unknown' };
+  return t(keys[status] ?? 'unknown');
+}
+
+/**
+ * True when no price applies at all: nothing observed is priced and nothing
+ * forecast is priced. That is a configuration fact, not a failed calculation,
+ * so the UI must say "prices are not configured" instead of an error sentence.
+ */
+export function costUnconfigured(snapshot: EstimateSnapshot): boolean {
+  if (snapshot.observedCostStatus === 'free' || snapshot.forecastCostStatus === 'free') return false;
+  return snapshot.priceSources.length === 0 && snapshot.knownCost.length === 0 && (snapshot.estimatedTotalCost?.length ?? 0) === 0;
+}
+
+export function costSummary(snapshot: EstimateSnapshot, locale: string, t: Translate): string {
+  if (snapshot.observedCostStatus === 'free') return t('free');
+  if (!snapshot.knownCost.length) return t('unknown');
+  const value = formatMoneyList(snapshot.knownCost, locale, t);
+  return snapshot.observedCostStatus === 'complete' ? value : t('partialKnown', { value });
+}
+
+/** Advance text only between Host snapshots. Waiting freezes active time and the remaining range. */
+export function localTiming(snapshot: EstimateSnapshot, receivedAt: number, now: number) {
+  const delta = Math.max(0, now - receivedAt);
+  const activeDelta = snapshot.state === 'running' ? delta : 0;
+  const wallDelta = isTerminal(snapshot.state) ? 0 : delta;
+  return {
+    activeMs: snapshot.elapsedActiveMs + activeDelta,
+    pausedMs: snapshot.elapsedPausedMs + (snapshot.state === 'waiting_user' ? delta : 0),
+    wallMs: snapshot.elapsedWallMs + wallDelta,
+    remaining: validSpan(snapshot.remainingMs) ? {
+      low: Math.max(0, snapshot.remainingMs.low - activeDelta),
+      high: Math.max(0, snapshot.remainingMs.high - activeDelta),
+    } : null,
+  };
+}
+
+export function remainingSummary(snapshot: EstimateSnapshot, receivedAt: number, now: number, t: Translate): string {
+  const { remaining } = localTiming(snapshot, receivedAt, now);
+  if (!remaining) return t('unknownRemaining');
+  if (snapshot.state === 'running' && remaining.high === 0) return t('overdue');
+  return t('estimatedRemaining', { value: formatDurationRange(remaining, t) });
+}
+
+export function formatDate(time: number, locale: string, t: Translate): string {
+  if (!Number.isFinite(time) || time <= 0) return t('unknown');
+  return new Intl.DateTimeFormat(numberLocale(locale), { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' }).format(time);
+}
+
+export interface ProfileMetricsText { latency: string; speed: string; samples: string; measured: string; source: string }
+
+/**
+ * One calibration row. A metric is printed plainly only when local samples back
+ * it; prior-only values stay visibly marked as reference so a heuristic prior is
+ * never read as a measurement. Missing values remain unknown, never zero.
+ */
+export function formatProfileMetrics(profile: ProfileSummary, locale: string, t: Translate): ProfileMetricsText {
+  const latency = formatLatency(profile.firstTextMs, locale, t);
+  const speedValue = profile.visibleTps == null ? null : t('tokensPerSecond', { value: formatNumber(profile.visibleTps, locale, t, 1) });
+  const priorSpeed = profile.priorVisibleTps == null ? null : t('tokensPerSecond', { value: formatNumber(profile.priorVisibleTps, locale, t, 1) });
+  return {
+    latency: profile.firstTextMs !== null && profile.firstTextSamples === 0 ? t('referenceValue', { value: latency }) : latency,
+    speed: profile.visibleTps != null && profile.speedSamples > 0 ? speedValue! : priorSpeed === null ? t('unknown') : t('referenceValue', { value: priorSpeed }),
+    samples: t('profileSamples', { value: formatNumber(profile.totalCallSamples, locale, t) }),
+    measured: profile.testedAt === null || profile.testedAt <= 0 ? t('profileNotMeasured') : t('profileMeasuredAt', { value: formatDate(profile.testedAt, locale, t) }),
+    source: t('sourceDetail', { value: formatOrigin(profile.sourceKind, t) }),
+  };
+}