@falari/harness 0.0.0-stage → 0.8.10

package/CHANGELOG.md

@@ -0,0 +1,456 @@
+# Changelog
+
+All notable changes to the Falari Harness bundle. The bundle is installed into a
+DeepSeek Harness profile; version numbers track the delivery milestones in
+[docs/plan.md](docs/plan.md).
+
+## 0.8.10 — 2026-11-10
+
+Documentation and package metadata carry the project identity only.
+
+- Developer is **falari_labs**, project website **https://falari.xyz**; the npm
+  manifest's `author` and `homepage` say so, and the LICENSE reads
+  `Copyright (c) 2026 falari_labs`.
+- Removed a developer machine path from the README install example (it now uses
+  `/path/to/clients/harness`) and dropped `repository` / `bugs` links that pointed
+  at a repository that is not the published channel; the npm package is.
+- No functional change.
+
+## 0.8.9 — 2026-11-10
+
+Any storage term can be typed, and the fee rules match the chain exactly.
+
+- Upload → 存储时长 gains **自定义…**: a number plus days / months / years
+  (days = 24 h, months = 30 days, years = 365 days), converted to whole seconds
+  and sent as the duration. The field echoes the billing in words
+  (`≈ 30 days billed · expires 12/10/2026`), rejects anything under one day, and
+  blocks the upload button while the term is incomplete.
+- Host accepts any whole second count from 0 (permanent) to the chain's
+  `max_intent_duration_seconds` (100 years), and refuses anything outside it.
+  The quote response now carries `billableDays` and `durationLimits`.
+- **Fee rule fixed in the SDK**: `quoteStorageFee` now mirrors
+  `Params.RequiredFee` for long finite terms. Before, a 40-year quote was priced
+  by the day and came out *more expensive than permanent*; the chain switches to
+  the permanent price at 36 years (30-year window + 20% reserve), and the SDK now
+  does the same. Whole-day billing, rounded up, minimum one day, unchanged.
+- SDK `@falari/agent` 0.2.6; new `duration-fee-cap.test.mjs` (4 checks).
+
+## 0.8.8 — 2026-11-10
+
+The panel header wears the original render, not the cut-out.
+
+- `FalariLogoImage` draws the supplied artwork as-is (dark backdrop included),
+  cropped around the cube so it fills the 46 px tile without the empty margin of
+  the 512 px source. It is inlined once as a data URI, so the client bundle stays
+  a single file (~28 KB base64).
+- The sidebar keeps the vector mark: at 20 px a raster loses the `>_` glyph,
+  while the vector stays crisp at any DPI.
+- `icon.png` (plugin list) remains the transparent cut-out from 0.8.5; the header
+  and the icon are intentionally different treatments of the same artwork.
+
+## 0.8.7 — 2026-11-10
+
+The idle-lock window is a real setting, not a fixed number.
+
+- Default stays **60 minutes**; the field now offers presets (15 / 30 / 60 / 120 /
+  240 / never) **plus a free minute input**, so any value from 0 to 10080 (7 days)
+  can be typed. 0 means "never lock until DSH exits".
+- The typed value is echoed in words next to the input (`90 → 1 h 30 min`,
+  `2880 → 2 d`), so a bare number is never ambiguous.
+- The host validates the same range (`lockIdleMinutes` 0–10080, integer) and
+  rejects anything outside it.
+- The security card states the active window: `已解锁 … · 空闲 60 分钟后自动锁定`.
+- Tests: host +3 (90 saved, 10081 rejected, 0 = never), client +4 (duration
+  wording in both languages).
+
+## 0.8.6 — 2026-11-10
+
+The PIN is asked for far less often, and never for a change that did not touch
+the key.
+
+- **A plugin row reload no longer locks.** Saving settings, toggling the bundle
+  or reinstalling constructs a new service in the same process; the decrypted
+  key now lives in a process-wide vault keyed by the sealed record's ciphertext,
+  so the new instance adopts it. A different key, a key re-sealed under a new
+  PIN, `Clear`, `Lock now` and process exit all still drop it.
+- Default idle lock raised from 15 to **60 minutes**, still configurable
+  (`lockIdleMinutes`, 0 = never). The security card now states the real number:
+  `idle 60 min → auto-lock`.
+- New `scripts/unit-vault.mjs` (6 checks): fresh service is locked, unlock works,
+  a reload keeps it, a different key does not inherit it, `Lock now` forgets it.
+
+## 0.8.5 — 2026-11-10
+
+New plugin icon: the rendered cube, cut out to transparency.
+
+- `icon.png` (256×256 RGBA, 48 KB) replaces `icon.svg`; `exports["./icon"]` and
+  `files` point at it, matching the convention other Harness plugins use.
+- The source artwork was a 512×512 image on a dark backdrop. The backdrop is
+  removed by taking the convex hull of the lit faces (which keeps the cube's own
+  black edges and the `>_` glyph), filling it at 4× for a smooth edge, and
+  cropping to the alpha bounds with 6% padding, so the mark is centred at any
+  size.
+- Verified over white and dark backgrounds and at 16/24/32/44/64/128 px.
+
+## 0.8.4 — 2026-11-10
+
+One writer per queue ledger, across processes.
+
+- The SDK takes `<upload-queue>.lock` around every queue pass: a JSON record with
+  `pid`, `host`, a `token` and a heartbeat every 15 s. A second DSH window (or a
+  second machine sharing the profile) defers instead of uploading the same task,
+  which is what produced `code 32: account sequence mismatch` when two drivers
+  signed batch commits at the same sequence.
+- A lock whose heartbeat is older than 90 s, or whose pid is gone on this host,
+  is stale and is reclaimed: a crashed driver must not freeze the queue forever.
+- Release only deletes its own token, so a stale takeover cannot be undone by the
+  slow original owner.
+- `runUploadQueue()` reports `pending: true` while another process owns the
+  ledger, so the timer retries later without spinning.
+- SDK `@falari/agent` 0.2.5, new test `upload-queue-lock.test.mjs` (live holder
+  defers, stale holder is reclaimed, lock released after a pass).
+
+## 0.8.3 — 2026-11-10
+
+Two writers on one queue were racing the account sequence, and the idle lock was
+able to stop a paid upload.
+
+- **One queue writer per process.** A plugin row reload constructs a new service
+  while the previous one may still have an upload tick in flight; both then sign
+  batch commits against the same account sequence and the chain rejects the loser
+  with `code 32`. The service now retires the previous instance before taking
+  over, and the SDK refuses to start a second queue loop while a tick is still
+  running (`uploadQueueRunning`).
+- **Sequence retries widened**: 6 attempts with 200–1200 ms backoff instead of 3
+  attempts at 150–300 ms, enough for a burst of competing transactions to drain.
+- **The idle lock no longer interrupts an upload.** `hasActiveUploads()` reads
+  the live queue, and while anything is `queued`/`uploading` the auto-lock
+  restarts its clock instead of locking. `POST /key/lock` refuses with
+  `upload_in_progress` (423) unless `force: true`; the panel asks before forcing.
+- The security card says when auto-lock is paused for an upload.
+
+## 0.8.2 — 2026-11-10
+
+- The main account balance renders to four decimals (`12.3456 FAR`). It floors
+  rather than rounds, so the card can never claim more than the account holds;
+  the exact value stays in `balanceWei` for any calculation. The formatted
+  string from older Hosts is handled the same way.
+
+## 0.8.1 — 2026-11-10
+
+The panel now wears the wallet's visual language.
+
+Taken from the Android client's `ui/theme` (the frosted-glass D+E theme), adapted
+to a web panel: the palette still resolves to Harness tokens, so light and dark
+follow the host instead of hard-coding colours.
+
+- Token layer in `client.js`: `colors` (ink / hairline / divider / four surfaces /
+  brand + soft fills / three orb hues / glass edge), plus `radius` (20 card, 16
+  dialog, 14 block, 10 field, 12 tile), `space` (22 page, 18 card, 14 section,
+  12 row, 8 inline, 4 tight) and `type` (24 display … 10.5 kicker). Literal font
+  sizes in the page blocks were folded into the scale (58 sites).
+- `Backdrop`: three blurred colour orbs behind the content, which is what makes
+  a translucent panel read as glass.
+- `Card` is the single panel primitive: translucent surface, 1px highlight edge,
+  soft lift, 20px radius. `SectionTitle` gives every block the wallet's small
+  wide-bold label register.
+- Header is one glass bar: the mark in a tinted tile, title + badges, hint below,
+  refresh on the right. Tabs became a floating segmented pill so the row reads as
+  a control, not a page divider.
+- Buttons are gradient CTA / soft secondary / danger; badges are tinted fills
+  rather than outline rings; drop zone is a lifted area with a brand glyph.
+- Data table: uppercase kicker headers, hairline row dividers, tabular numerals,
+  name + shortened intent id (full id in the tooltip).
+- Task row: the intent id is shortened to match the table, the percentage is
+  promoted out of the muted grey.
+
+Verified by rendering both palettes off the real component tree. Tests unchanged:
+25 + 18 + 73 + 58 = 174 checks green.
+
+## 0.8.0 — 2026-11-10
+
+The Agent Key is sealed under a PIN; nothing readable is left on disk.
+
+- New `lib/pin.js`: the `far_` string is encrypted with AES-256-GCM under a key
+  derived by scrypt (N=2^15, per-record 16-byte salt, 12-byte IV). Stored record
+  is `{v:2, kdf:'scrypt', salt, iv, tag, ct}`: no plaintext, and the KDF
+  parameters travel with it so a future change stays readable.
+- **A PIN is mandatory when saving a key.** `POST /key` without one is refused
+  (`missing_pin`), so a profile can never quietly hold a clear-text key.
+- The decrypted key lives only in this process's memory. `POST /key/lock`
+  drops it and stops the queue; `lockIdleMinutes` (default 15, 0 = never)
+  expires it after inactivity. A Host restart starts locked.
+- A profile that already had a plaintext key is reported as `legacy`: the panel
+  flags it, uploads are refused with `pin_required`, and `POST /key/secure`
+  re-seals the same key in place with a PIN (no re-entry, no upload).
+- Wrong PINs are counted: five misses cost a 30-second pause (`pin_blocked`,
+  429). A wrong PIN and a tampered record fail identically, so the error cannot
+  be used as a decryption oracle.
+- Panel: the key card is now a vault (set PIN / unlock / lock now / clear), the
+  upload tab gates itself with an inline PIN field, and the status card shows
+  `Locked` instead of pretending the chain is down.
+- Errors: `agent_key_locked` / `pin_required` → 423, `wrong_pin` → 401,
+  `pin_blocked` → 429. `GET /health` reports `encrypted` and `locked`.
+- Tests: new `scripts/unit-pin.mjs` (18 checks: round trip, wrong PIN, tampered
+  ciphertext/tag, malformed salt, PIN policy, Unicode normalisation), host 73,
+  client 58.
+
+## 0.7.6 — 2026-11-10
+
+Upload authorization on the chunked path (the 0.6.5 fix missed it).
+
+- Every shard goes through the **chunked** upload route (`/upload?offset=…`,
+  `?final=1`) whenever `ChainApi.uploadShardChunk` exists, and 0.6.5 only signed
+  the one-shot `/upload` variant. A miner in enforce mode kept answering
+  `upload auth: upload authorization is missing` for every shard, so a segment
+  never reached its receipt quorum.
+- `ChainApi.uploadShardChunk` now accepts the EIP-712 envelope, and the chunked
+  v3 path attaches it on the direct route as well as the relay route (including
+  the empty final chunk that only reclaims a receipt).
+- SDK `@falari/agent` 0.2.3; new SDK test pins the three headers on a direct
+  chunked upload.
+
+## 0.7.5 — 2026-11-10
+
+The Data tab paints before the chain answers.
+
+- The intent list is cached in `localStorage` (keyed by the master account, so a
+  key or network change never flashes another account's files) and rendered
+  immediately; the chain's answer replaces it when it lands, with
+  `Showing the last snapshot while the chain answers` next to the refresh button.
+- The first open in a profile shows five skeleton rows that pulse
+  (`@keyframes falari-skeleton`), instead of a one-line "loading".
+- Each row's title is the file name plus the intent id
+  (`DBX.app.zip intent_e152ffa100…571d84`); the copy button still copies the full
+  id and a private intent without a readable name shows `Untitled` rather than
+  repeating its id.
+
+## 0.7.4 — 2026-11-10
+
+Audit of the upload and cancel flows; eight interaction defects fixed.
+
+Upload:
+
+- The estimate priced the **sum** of the selected files while every file becomes
+  its own order, so the deposit looked far larger than any single upload. It now
+  prices the largest file and says so when several are selected.
+- A file that queued successfully stayed in the selection, so a retry sent it a
+  second time (a second escrow). Queued files are dropped from the list.
+- The upload button is disabled while the quote says the budget is short, instead
+  of streaming a whole file and failing at the end.
+- The progress line names the file being sent (`Sending 2/3 · name · size`); the
+  streaming phase had no feedback at all.
+- The drop zone is keyboard reachable (role, tabIndex, Enter/Space).
+
+Cancel:
+
+- **Every unfinished upload can now be cancelled**, including `failed` and
+  `needs_source` rows: those hold an escrow but only offered Delete, so the money
+  was unreachable from the UI.
+- A task with no on-chain order gets its own dialog (`Cancel upload`) that states
+  nothing is refunded, instead of a page of 0 FAR rows.
+- A settled (`finalized`) order reports `unavailable: 'finalized'` and explains
+  that cancelling falls back to the early-termination rule, instead of showing a
+  zero escrow as if everything had been refunded.
+- A failed preview read no longer aborts the termination, and a termination the
+  chain has not confirmed yet reports `pending` instead of claiming success.
+- Escape and backdrop clicks are ignored while the cancel transaction is in
+  flight, so the dialog cannot vanish mid-mutation.
+
+Tests: host 56, client 45.
+
+## 0.7.3 — 2026-11-10
+
+Cancelling no longer loses the race against the upload driver.
+
+- The chain rejected the terminate with `code 32: account sequence mismatch,
+  expected 28, got 27`: the upload driver's batch commit consumed the sequence
+  the cancel had signed against. The bundled SDK now rebuilds the unsigned
+  transaction against the fresh sequence and re-signs, up to three attempts, on
+  both the agent (`/tx/exec`) and owner (`/tx/build`) paths.
+- `classifyChainError` reports the race as `sequence_mismatch` /
+  `retryable: true`, so a terminate that still fails is queued for another
+  attempt instead of parking in `failed` with a retry button.
+- SDK version `@falari/agent` 0.2.2; three new SDK tests pin the retry, the
+  no-retry on an unrelated rejection, and the classification.
+
+## 0.7.2 — 2026-11-10
+
+The status card speaks the interface language.
+
+- **Permission tiers** render as 写入数据 / 管理数据 / 转账资金 (`Write data` /
+  `Manage data` / `Transfer funds`) instead of the wire names; an unknown tier
+  still falls back to its wire value, and the list separator follows the locale.
+- **Key state** renders as 正常 / 已过期 / 已吊销 / 已冻结 / 已停用 / 待生效.
+- Wire names stay unchanged in the API and in `falari_status`, so a signature,
+  a log line or a support thread still matches the chain.
+
+## 0.7.1 — 2026-11-10
+
+- The refund dialog prints `0 FAR` instead of `-0 FAR` when a deduction is zero,
+  and the byte formatter keeps one decimal below 100 KiB.
+
+## 0.7.0 — 2026-11-10
+
+Cancelling an upload asks first, and shows the money.
+
+- **Cancel and refund** now opens a dialog instead of terminating on the click:
+  file, status, bytes already uploaded, the escrow the chain holds, the
+  cancellation rate (`voluntary_cancellation_fee_bps`), the withheld
+  compensation, the terminate service fee billed from the main balance, and the
+  amount going back to the main account.
+- The numbers come from the chain, not from a local guess:
+  `GET /api/falari-harness/tasks/:id/refund` reads the intent (`locked_fee_wei`,
+  `uploaded_size`, `refunded_fee_wei`) and `/params`
+  (`voluntary_cancellation_fee_bps`, `min_cancellation_fee`,
+  `service_fees.terminate`) and mirrors `closeUnfinalizedIntent`: the fee is
+  `max(min_cancellation_fee, escrow * bps / 10000)` capped at the escrow, and an
+  intent with no committed receipt is closed without compensation.
+- Confirming posts `/tasks/:id/cancel`, which terminates, then re-reads the
+  intent and shows the amount the chain actually released.
+- `formatFar` / `formatBytes` helpers; the dialog closes on Escape or a backdrop
+  click.
+
+## 0.6.5 — 2026-11-10
+
+Uploads reach miners that enforce the EIP-712 upload authorization.
+
+- The bundled SDK signed the envelope only for relayed shards. A miner with its
+  own HTTP endpoint got a bare `POST /upload` and refused it with
+  `upload auth: upload authorization is missing`, so an upload ended with
+  `only 0/1 segments reached 4 receipts on 3 distinct miners`.
+- `ChainApi.uploadShard` now accepts the envelope, and the v3 upload paths
+  (whole shard, chunk, empty final chunk) sign one per attempt on the direct
+  route as well. The nonce is single-use, so every retry re-signs.
+- SDK: new tests assert the three `X-Falari-Upload-*` headers on a direct upload
+  and that an upload without a signer stays unsigned.
+
+## 0.6.4 — 2026-11-10
+
+The panel paints the last known status instead of waiting for the chain.
+
+- The Host keeps the status view in memory and in
+  `<dataDir>/status-cache.json` (0600, keyed by network + master + agent
+  address). `GET /api/falari-harness/status` answers from that cache immediately
+  and starts one background chain read when the cached view is older than 15
+  seconds; `?refresh=1` forces a read. A failed read keeps the last good numbers
+  and reports the error beside them.
+- The panel and the settings page store the status in `localStorage`, so the
+  card renders before the first request completes, then polls every 5 seconds
+  and shows newer numbers when they arrive. The header shows `Updated HH:MM:SS`
+  and `refreshing…` while a read is in flight.
+- `falari_status` gained `refresh: true` to bypass the cache. Clearing the key
+  removes the cached view on both sides.
+
+## 0.6.3 — 2026-11-10
+
+The status card shows one address.
+
+- The Agent Key's own address is gone from the status view and the panel: the
+  row now reads **Main address / 主地址** with the owner account, which is the
+  account that pays and owns the data.
+- `keyStatusFrom` no longer returns `agentKey.agentAddress`, so the
+  `falari_status` tool result does not carry it either. The key's ordinal, state,
+  tiers, allowance and expiry still identify it.
+
+## 0.6.2 — 2026-11-09
+
+The official Falari mark replaces the placeholder cube.
+
+- `icon.svg` is the real logo: isometric cube measured from the supplied
+  artwork (hexagon, three lit faces, the inner edges drawn as bands inside the
+  faces, the `>_` prompt on the left face) in a 100×100 box.
+- The panel header and the sidebar use the same geometry; a hairline silhouette
+  keeps the white cube readable on white surfaces, and the sidebar's 20px mark
+  uses a bolder stroke and darker faces.
+- Gradient ids are per instance (`useId`), so several marks can render at once.
+
+## 0.6.1 — 2026-11-09
+
+Configuration is reachable from the plugin itself, and the plugin metadata reads
+in both languages.
+
+- The panel gained a fourth tab, **Settings / 设置**, holding the Agent Key form,
+  the status card and the storage configuration — the plugin's own settings
+  surface, independent of the plugin-manager page.
+- The Host now declares `configure({ auto: false })` to the Settings service, so
+  DSH knows this plugin ships its own configuration page instead of expecting a
+  schema-generated form. Skipped when the service is absent.
+- `plugins.bundle.config` and `plugins.row.config` honor `view: 'summary'` with a
+  one-line summary, as the plugin manager expects for compact rows.
+- `locale/*.json` titles and descriptions now carry both languages
+  (`Falari Data / Falari 数据`), so the plugin reads the same in any UI language.
+
+## 0.6.0 — 2026-11-09
+
+The plugin's settings live on its own page, not in the global Settings dialog.
+
+- Removed the `settings.section` registration; the Agent Key form, status and
+  configuration card now render through `plugins.bundle.config` (the bundle page)
+  and `plugins.row.config` (the row's configure page), both keyed by this package.
+- Copy across the panel, the tools and the Host errors now points at
+  *Plugins → Falari Data → Configure* instead of the Settings dialog.
+- Dropped the duplicated page header, since the host heads these pages with the
+  plugin title and description; two locale keys and three checks updated.
+
+## 0.5.0 — 2026-11-09
+
+Settings become editable and the offline test suite is complete.
+
+- `POST /api/falari-harness/config` writes network, default privacy, default
+  duration, upload size limit, download directory and the
+  upload-outside-workspace switch through the profile's config editor. Saving
+  restarts the plugin row, and the panel says so.
+- Field-level validation for every accepted value; unknown fields and empty
+  patches are refused with a reason instead of being dropped.
+- `scripts/unit-host.mjs`: config validation/defaults, file-name sanitizing, HTTP
+  status mapping and error mapping.
+- `docs/test-plan.md`: automated coverage, live testnet steps and panel checks.
+- Removed the placeholder component and 22 unused locale keys; English and
+  Chinese dictionaries stay at 141 keys each.
+
+## 0.4.0 — 2026-11-09
+
+Intent listing and downloads.
+
+- `GET /intents`, `GET /intents/:id`, `POST /downloads`, `GET /downloads/:id`.
+- `falari_list` and `falari_download` Agent tools.
+- Private intent names are decrypted locally when this machine holds the data
+  key; otherwise the intent id is shown.
+- Downloads run as tasks with progress, are written only inside the download
+  directory, and never overwrite an existing file.
+- Upload and download tasks share one list; the panel gained *My data* and
+  *Download* tabs.
+
+## 0.3.0 — 2026-11-09
+
+Uploads.
+
+- `POST /quote`, `POST /uploads` (raw octet-stream, streamed to a 0600 temp file)
+  and the upload queue driven by the SDK's persistent ledger.
+- `falari_quote`, `falari_upload` and `falari_task` tools; uploads from the model
+  are restricted to the session working directory.
+- Upload panel with drag-and-drop, privacy and duration, automatic quote with a
+  budget check, and per-task pause/resume/retry/cancel.
+- Panel routes answer loopback peers only (`allowRemoteRoutes` to change);
+  cross-origin writes are rejected.
+- `scripts/build-sdk.sh` bundles the unpublished `@falari/agent` and
+  `@falari/precompiles` packages into `lib/falari-sdk.cjs`.
+
+## 0.2.0 — 2026-11-09
+
+Agent Key management.
+
+- The key is stored in the DSH credential store as `falari-harness/agent-key`;
+  the browser never receives it and no route returns it.
+- Key validation (format, registration, network) with distinct error codes.
+- `falari_status` tool and the settings page status card: agent address, master,
+  tiers, allowance, balance, expiry, miners.
+
+## 0.1.0 — 2026-11-09
+
+Initial bundle.
+
+- `@falari/harness` bundle manifest, row patch, icon, locale metadata.
+- Host half activates; Web half registers a sidebar entry, a data panel and a
+  settings page.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 falari_labs
+
+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.