@aryacode/dsh-aryacode-polish 0.0.0-stage → 0.3.4

package/CHANGELOG.md

@@ -0,0 +1,165 @@
+# Changelog
+
+## [0.3.4] - 2026-10-27
+
+### Added
+
+- **The bundle says which Harness it runs on.** `dsh.engines.dsh` is now declared
+  (`^0.2.1-rc.3`, the revision the two surfaces were verified against), so the
+  market can read the requirement instead of labelling the card "Host requirement
+  unknown", and an install onto an older Host can be refused rather than failing
+  at mount time. `test/manifests.spec.mjs` keeps the field present and semver.
+
+## [0.3.3] - 2026-10-27
+
+### Fixed
+
+- **The balance read could wait forever.** When the Host withheld the
+  `account/watch` grant, the read's promise never settled: the callback never
+  ran, so nothing resolved and the line silently stayed empty for the life of the
+  page. The read now carries a timeout and also starts its call before the
+  effect's yielded disposer, so an effect runner that stops at the first yield
+  still performs it. `test/account.spec.mjs` pins all seven refusal paths.
+
+### Changed
+
+- The read itself moved into `client/account.js`, beside `client/money.js`, for
+  the same reason: the build inlines it into the browser bundle and the spec
+  imports the same source.
+
+## [0.3.2] - 2026-10-27
+
+### Changed
+
+- **The balance decisions are testable.** Which wallet a line shows, and how the
+  amount is rendered (currency symbol, two decimals, unparseable values shown
+  verbatim), moved into `client/money.js`. The build inlines that file into
+  `lib/client.js`, so `test/money.spec.mjs` covers the exact source the browser
+  runs instead of a copy.
+
+## [0.3.1] - 2026-10-27
+
+### Fixed
+
+- **The balance line had no observable mount point.** When the account exposed no
+  wallet it rendered `null`, which is correct for the user but indistinguishable
+  from "the surface was never registered" for anyone verifying the build. The
+  component now always renders its wrapper (`data-polish-balance="empty"`, hidden)
+  and fills it with the amount only when the Host returns one.
+
+## [0.3.0] - 2026-10-27
+
+### Added
+
+- **Remaining account balance in the sidebar foot.** A line above the account row
+  shows the account's own wallet (`$17.33`), read once through a
+  `remoteAccess.whenAccess('account/watch', …)` grant so the call is allowed and
+  the grant is released as soon as the read settles. It renders nothing at all
+  when the switch is off, when the Host exposes no wallet, or when the read is
+  refused — an empty line beats a number the Host did not give us.
+- **A second switch, `accountBalance`.** It is declared once in
+  `entries/registry.js` and once in `client/switches.json`, exactly like the cost
+  switch, so the Configure page grows it automatically.
+
+### Notes
+
+- The line sits in `sidebar.footer.action`, the one documented seat in the
+  sidebar foot. It renders *above* the account row, because
+  `SidebarRoot.tsx:405-411` puts `footerActions` before `settingsArea`; the only
+  seat below the login would be `settings.launcher`, which means shadowing the
+  account row and its whole menu.
+
+## [0.2.4] - 2026-10-27
+
+### Changed
+
+- **The card leads with the number it is about.** It now opens with the
+  "Estimated session cost" heading and the live `≈$…` amount, then a stacked bar
+  showing how the session's tokens split between cached input, uncached input,
+  cache writes and output, then the rows: cache hit, tokens, model, provider,
+  requests, and the estimate again above the footnote. Model and provider are
+  always named (they were only listed when a session had more than one), so a
+  first look says which route the money was spent on.
+
+## [0.2.3] - 2026-10-27
+
+### Fixed
+
+- **A sub-cent turn no longer reads `≈$0`.** `formatMoney` rounded to three
+  decimals, so a real 22.1K-token turn whose actual cost was about $0.000095
+  showed as zero. Amounts under a cent now keep two significant digits
+  (`≈$0.000095`), cents keep three decimals, and dollars keep two.
+
+## [0.2.2] - 2026-10-27
+
+### Fixed
+
+- The pill's `≈` was stored as cp1252 mojibake (`≈`), so a real turn rendered
+  `≈$0.003` instead of `≈$0.003`. Same cause as the two strings repaired in
+  0.2.1 — a PowerShell round-trip over the face source — and the last of that
+  damage. Verified against a real turn in Dev AryaCode.
+
+## [0.2.1] - 2026-10-27
+
+### Fixed
+
+- **The Configure page found no form.** The page body asked
+  `configForms.get('<package>#<row>')`, but the Plugins page builds a row's form
+  from the **row id** alone (`PluginManagerPage.tsx:1735` passes
+  `form={formFor(openRow.rowId)}`, and `formFor` matches `view.ns === id`). The
+  lookup now asks for `polish`, so the row's page reads the live form instead of
+  saying the row has no configuration to change. The `plugins.row.config`
+  registration key is unchanged: that one is still `<package>#<row>`.
+- Two strings that a PowerShell round-trip had written as cp1252 mojibake
+  (`Loading configuration…`, `Saving…`, and an em dash) are back to UTF-8.
+
+## [0.2.0] - 2026-10-27
+
+### Added
+
+- **Estimated session cost.** A composer-dock pill (`≈$0.39`) that opens a
+  breakdown card: cache hit, uncached input, cached input, output, requests, and
+  the estimate itself, with the same "your provider's bill is authoritative"
+  footnote. The money is computed **host-side**: `entries/usage.js` folds
+  model-attributed usage out of the durable session log, and `entries/cost.js`
+  registers a `polishCost` projection whose wire view is already priced at the
+  published DeepSeek rates (off-peak table, peak at 2×, cache writes billed as
+  misses). The browser half only formats numbers, so no rate table ships to the
+  client and an unknown model or provider leaves the estimate marked incomplete
+  instead of quietly reporting a wrong number.
+- **`test/cost.spec.mjs`.** Fold and pricing coverage: peak/off-peak, cache
+  rates, cache writes as misses, unknown route handling, retry accounting, and
+  the empty-session wire view.
+
+## [0.1.1] - 2026-10-27
+
+### Added
+
+- **The row's Configure page.** `lib/client.js` is the bundle's browser face: it
+  registers the `polish` row's configuration page, so the row now has a page of
+  its own that reads the row's live config form and writes it back with the
+  Host's revision. With no feature landed yet the page states that plainly
+  instead of showing a switch that toggles nothing.
+- **`client/switches.json`.** The browser half of the feature seam: one entry per
+  switch, and `test/client-face.spec.mjs` fails when it and `entries/registry.js`
+  disagree in either direction.
+
+## [0.1.0] - 2026-10-27
+
+### Added
+
+- **AryaCode Polish bundle.** One package, one row (`polish`), one switch per
+  quality-of-life feature, so each refinement can be turned off from its
+  Configure page without uninstalling the bundle.
+- **Feature seam.** `entries/registry.js` is the single list of features, and the
+  row's config schema is derived from it: a new entry gains its volatile switch
+  with no second registration, and switching a feature off disposes its host
+  half instead of merely hiding it.
+- **`docs/parked-spellcheck.md`.** Records why right-click spelling corrections
+  cannot be a plugin, and the exact shell change that would restore them.
+
+### Not shipped
+
+- Right-click spelling corrections. The candidates came from Chromium's
+  spellchecker through the Electron main process; the shell no longer reads
+  them, and no plugin contract can reach that menu. Parked with evidence.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KonnectSuite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# AryaCode Polish
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One install for the small things that make AryaCode feel finished.
+
+AryaCode Polish is a plugin **bundle**: it adds surfaces to the app it is
+installed into and patches nothing. It is one package, one Plugins row, and one
+switch per feature, so a refinement that turns out to be wrong for a machine can
+be turned off without uninstalling anything.
+
+Status: **0.2.0.** One feature shipped: the estimated session cost pill.
+
+## What it is
+
+- **One row.** The bundle inserts a single row, id `polish`, into the profile's
+  composition (`cordis.patch.yml`). That row is the install surface: it mounts
+  the host half of every enabled feature and names the bare package specifier so
+  the Shell can find the browser face.
+- **One switch per feature.** Every feature is gated by its own boolean in the
+  row's Configure page, on by default. Turning it off disposes that feature only.
+- **Additive.** No fork of the shell, no edits to `app.asar`, no patched
+  installed app, no DOM hacks against private class names.
+
+## Switches
+
+Row: **AryaCode Polish** (`polish`).
+
+Each entry in `entries/registry.js` becomes one volatile boolean in this
+Configure page automatically.
+
+| Switch | Default | What it does |
+| --- | --- | --- |
+| **Estimated session cost** (`sessionCost`) | On | A `≈$0.39` pill in the composer dock that opens a breakdown card — cache hit, uncached input, cached input, output, requests, and the estimate — priced from the session's recorded usage at the published DeepSeek rates. |
+| **Account balance** (`accountBalance`) | On | The account's remaining wallet (`$17.33`) in the sidebar foot, above the account row. Renders nothing when the Host exposes no wallet, so it never shows a number nobody gave it. |
+
+### How the cost is computed
+
+The numbers come from the Host, never from the browser:
+
+- `entries/usage.js` folds model-attributed provider usage out of the durable
+  session log, one row per provider, model, and hour, and tags each band as peak
+  or off-peak (Beijing weekdays 09–12 and 14–18 are billed at 2×).
+- `entries/cost.js` registers the `polishCost` projection and prices that fold:
+  cache reads at the cache rate, uncached input and cache writes at the miss
+  rate, output at the output rate. The wire view is already money, so no rate
+  table reaches the client.
+- An unknown provider, model, or rate period keeps its tokens and marks the
+  estimate **incomplete** — the pill says so rather than reporting a number it
+  cannot stand behind.
+- The rate table is dated and lives in one place. When DeepSeek changes prices,
+  append a period; do not edit history.
+
+## Declaring a feature
+
+`entries/registry.js` is the single list of features. One entry is one feature:
+
+```js
+{
+  id: 'spellcheck',              // becomes the config field and the switch
+  label: 'Spelling corrections',
+  description: 'Right-click a misspelled word to pick a correction.',
+  defaultOn: true,
+  mount: spellcheck,             // optional host half: a Cordis plugin
+}
+```
+
+The row's `Config` schema is derived from that list, so a new entry gains its
+volatile switch with no second registration. `mount` is plugged in when the
+switch is on and disposed when it is off, so a disabled feature stops costing the
+app rather than merely hiding. A feature that only draws UI omits `mount` and
+contributes a client face instead.
+
+## Parked
+
+**Right-click spelling corrections** — investigated and not shipped. The
+candidates you saw in AryaAI came from Chromium's spellchecker through the
+Electron main process, which the AryaCode shell no longer reads; a plugin cannot
+reach it. The finding, the exact 10-line shell change that would restore it, and
+why the plugin alternatives were rejected are in
+[`docs/parked-spellcheck.md`](docs/parked-spellcheck.md).
+
+## Install
+
+From the AryaCode Plugins market: open the market, find **AryaCode Polish**,
+install, then quit and reopen AryaCode — the market registry is cached in the
+running process.
+
+Manual, for development only:
+
+```bash
+node --import tsx/esm apps/cli/src/bin.ts plugin --profile web add <path-to-tgz>
+```
+
+## Requirements
+
+- AryaCode `^0.2.1-rc.3` (declared as `dsh.engines.dsh`; the revision both
+  surfaces were verified against).
+- AryaCode with the Cordis plugin API (`@deepseek-ai/cordis ~4.0.4`).
+- Node `^22.19.0 || >=24.0.0` to build from source.
+
+## Development
+
+```bash
+pnpm install
+pnpm test        # patch shape, config accessors, feature seam, docs parity
+pnpm pack        # produces aryacode-dsh-aryacode-polish-<version>.tgz
+```
+
+Test on **Dev AryaCode** (`%LOCALAPPDATA%\AryaCode-dev\home`), never on the
+installed app.
+
+## Layout
+
+```
+cordis.patch.yml     one insert, one row
+entries/polish.js    the row: Config derived from the registry, apply()
+entries/registry.js  the feature list — the one place a feature is declared
+entries/usage.js     the fold: model-attributed usage out of the session log
+entries/cost.js      the polishCost projection: rates, pricing, host mount
+entries/features/    one module per feature
+entries/config.js    volatile-reference accessors (resolve/flag/list/text)
+lib/index.js         mount point re-exporting the row
+client/face.js       browser face source: the Configure page and every surface
+client/switches.json the browser half of the seam — one entry per switch
+scripts/build-client.mjs  wraps client/face.js into lib/client.js
+lib/client.js        generated: the bundle the Shell loads
+locale/              card title and description (en, zh)
+docs/                parked investigations
+test/                node --test specs
+```
+
+The Configure page is generated, not hand-maintained: `lib/client.js` is built
+from `client/face.js` and `client/switches.json` by `pnpm build:client` (which
+`pnpm pack` runs), and `test/client-face.spec.mjs` fails when `switches.json` and
+`entries/registry.js` disagree in either direction.
+
+## Licence
+
+MIT © KonnectSuite

package/client/account.js

@@ -0,0 +1,96 @@
+/**
+ * Reading the account balance from a plugin face.
+ *
+ * The account Remote methods are gated, so the read runs inside a
+ * `remoteAccess.whenAccess('account/watch', …)` grant and the grant is released
+ * as soon as the read settles. Every failure — no service in this Shell, a
+ * refused grant, a failed call — resolves to `undefined` instead of throwing: a
+ * sidebar line is never worth breaking the shell over, and a line that stays
+ * empty is honest about a number it never received.
+ *
+ * This module is inlined into `lib/client.js` by `scripts/build-client.mjs` and
+ * imported directly by `test/account.spec.mjs`, so the tested source is the one
+ * the browser runs.
+ */
+
+/**
+ * Build the account request identity for one balance read.
+ *
+ * The shipped account bundle inlines `DSH_CLIENT_VERSION` at build time; a plugin
+ * bundle has no such define, so the build stamps this package's own version and
+ * prefers the shell's value when one is inlined.
+ *
+ * @param version - the version this build stamps.
+ * @returns the metadata the account Remote methods carry.
+ */
+export function clientMetadata(version) {
+  const stamped = typeof process !== 'undefined' && process.env !== undefined ? process.env.DSH_CLIENT_VERSION : undefined
+  return {
+    version: typeof stamped === 'string' && stamped !== '' ? stamped : version,
+    locale: typeof navigator !== 'undefined' && typeof navigator.language === 'string' && navigator.language !== ''
+      ? navigator.language
+      : 'en',
+    timezoneOffsetSeconds: -new Date().getTimezoneOffset() * 60,
+  }
+}
+
+/**
+ * Build the one-shot balance reader.
+ *
+ * @param ctx - the browser plugin context; `ctx.get` resolves an optional service.
+ * @param version - the version this build stamps into the account metadata.
+ * @returns a reader that resolves to the balance view, or undefined when unavailable.
+ */
+export function makeBalanceReader(ctx, version, { timeoutMs = 10000 } = {}) {
+  const service = name => {
+    try {
+      return ctx.get(name)
+    } catch {
+      return undefined
+    }
+  }
+  return async () => {
+    const access = service('remoteAccess')
+    const remote = service('remote')
+    if (access === undefined || remote === undefined) return undefined
+    const metadata = clientMetadata(version)
+    return await new Promise(resolve => {
+      let settled = false
+      let stop
+      const timer = setTimeout(() => finish(undefined), timeoutMs)
+      const finish = value => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        resolve(value)
+        if (typeof stop === 'function') {
+          try {
+            stop()
+          } catch {
+            /* the grant may already have been released */
+          }
+        }
+      }
+      // The read starts before the yield so an effect runner that stops at the
+      // first yielded disposer still performs the call.
+      stop = access.whenAccess('account/watch', function* () {
+        void (async () => {
+          try {
+            const result = await remote.account.getBalance(metadata)
+            const value = result !== undefined && result.ok === true ? result.value : undefined
+            finish(value !== undefined && value.status === 'ready' ? value : undefined)
+          } catch {
+            finish(undefined)
+          }
+        })()
+        yield () => {
+          if (!settled) {
+            settled = true
+            clearTimeout(timer)
+            resolve(undefined)
+          }
+        }
+      })
+    })
+  }
+}