@falari/harness 0.0.0-stage → 0.8.9

package/CHANGELOG.md

@@ -0,0 +1,444 @@
+# 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.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
+
+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,213 @@
-# Temporary Holding Version
+# Falari Harness
+
+Falari Data client for **DeepSeek Harness** (DSH): upload files to Falari
+storage and download them back, with an Agent Key as the only credential. The
+same six operations are exposed to the model as tools and to the user as a
+panel.
+
+- Design and milestone log: [docs/plan.md](docs/plan.md)
+- Test plan: [docs/test-plan.md](docs/test-plan.md)
+- Release notes: [CHANGELOG.md](CHANGELOG.md)
+
+The plugin wears the Falari mark: `icon.png` is the rendered logo with a
+transparent background for the plugin list; the panel header shows the original
+render (dark backdrop, cropped to the cube); the sidebar draws crisp vector art
+so the `>_` survives at 20 px.
+
+## Status
+
+| Phase | Scope | State |
+|---|---|---|
+| M0 | Bundle scaffold, install, panel/settings placeholders | done — installed in the `desktop` profile (2026-11-09) |
+| M1 | Agent Key storage, `falari_status` tool, settings page | done (v0.2.0) |
+| M2 | Quotes, upload queue, upload panel, `falari_quote` / `falari_upload` / `falari_task` | done (v0.3.0) |
+| M3 | Intent list, download/decrypt, `falari_list` / `falari_download` | done (v0.4.0) |
+| M4 | Editable settings, unit tests, test plan | done (v0.5.0); live acceptance pending a testnet key |
+| M5 | Repository layout, changelog, license, manifest check | done (v0.5.0) |
+
+Live-chain verification still needs a real testnet Agent Key: the settings page
+and every route/tool path are covered by the offline smoke tests, but nothing
+here has performed a paid upload against the testnet yet.
+
+The full design is in [docs/plan.md](docs/plan.md).
+
+## Install (development)
+
+Open **Plugins → Add** in DeepSeek Harness and point it at this directory, or
+from an agent session call the plugin manager tool:
+
+```text
+plugin_manager action=install_bundle target=/Users/dimash/Documents/code/falari/clients/harness
+```
+
+The bundle is installed as a local link (`link:...`). Host code changes need the
+plugin row to reload (toggle the bundle off/on, or restart DSH); client code
+changes need a page refresh.
+
+Storage duration can be a preset (permanent / 30d / 90d / 1y / 5y / 10y) or any
+custom term in days, months or years. Fees follow the chain's `RequiredFee`:
+whole days rounded up, minimum one day, and any term past 36 years is charged the
+permanent price instead of growing forever.
+
+Cancelling an upload opens a confirmation dialog with the refund breakdown
+(escrow, cancellation rate, withheld compensation, terminate service fee, amount
+returned) read from the chain before anything is signed.
+
+Status reads are cached: the Host answers from `<dataDir>/status-cache.json` and
+refreshes the chain in the background (a 15 s window), and the panel keeps its own
+`localStorage` copy so the card renders before the first request returns.
+
+The Agent Key is stored **encrypted under a PIN**, never in clear text: scrypt
+derives the AES-256-GCM key from the PIN, the decrypted key lives only in memory,
+and the panel locks it on demand or after `lockIdleMinutes` of inactivity
+(default 60, presets or any value from 0 to 10080 minutes). A plugin row reload
+keeps the unlock while the process lives. A
+profile that already holds a plaintext key is flagged and re-sealed in place.
+
+The Agent Key and the storage defaults are configured in the plugin itself, never
+in the global Settings dialog:
+
+- **Falari Data panel → Settings tab** — always available, whatever the plugin
+  page renders.
+- **Plugins → Falari Data** — the bundle page card, or the row's **Configure**
+  control, driven by the `plugins.bundle.config` / `plugins.row.config` slots.
+  Both may take a browser refresh to appear after an install.
+
+## Configuration
+
+The row accepts an optional `config` block (defaults shown). Put overrides in the
+profile patch:
+
+```yaml
+- id: falari-harness
+  name: '@falari/harness'
+  config:
+    network: testnet            # testnet | mainnet (mainnet is not live yet)
+    defaultPrivacy: public      # public | private
+    defaultDuration: permanent  # permanent | 30d | 90d | 1y | 5y | 10y
+    maxFileSizeBytes: 2147483648
+    allowUploadOutsideWorkspace: false
+    allowRemoteRoutes: false     # keep the panel routes on loopback only
+    # gatewayUrl / retrievalUrl / explorerUrl override the network presets
+    # timeoutMs defaults to 60000
+    # dataDir defaults to <DSH_PROFILE_DIR>/falari-harness
+```
+
+The Agent Key is **not** configuration: it lives in the DSH credential store as
+the record `falari-harness/agent-key`.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `falari_status` | Key state, tiers, allowance, balance, miners (`refresh: true` bypasses the cache) |
+| `falari_quote` | Price an upload (`path` or `size_bytes`) and check the budget |
+| `falari_upload` | Queue a workspace file; `wait: true` waits up to two minutes |
+| `falari_task` | Read one task or the recent list |
+| `falari_list` | This account's intents, newest first |
+| `falari_download` | Download one intent, verify roots, decrypt when private |
+
+The plugin configuration page writes these values back through the profile's
+config editor, so saving restarts the plugin row.
+
+Agent uploads are restricted to the Session working directory unless
+`allowUploadOutsideWorkspace` is enabled. Files the user picks in the panel are
+not subject to that guard.
+
+## Build
+
+The Host half bundles the unpublished Falari SDK (`@falari/agent`) and the
+precompiles package into `lib/falari-sdk.cjs`, so installing the bundle needs no
+npm package for them:
+
+```sh
+npm run build:sdk
+```
+
+Run this after pulling a newer `sdk/sdk-agent-ts`.
+
+## Repository
+
+The project lives in this directory and is published as its own repository,
+`github.com/falarichain/harness`; the surrounding Falari checkout only hosts the
+SDK it builds against and the docs it follows.
+
+The package name `@falari/harness` is the bundle identity: `package.json` `name`,
+the Loader row in `cordis.patch.yml` and the `id` passed to
+`window.__ModuleLoader__.load` must all stay equal, because the client-modules
+scan matches the installed manifest name against the Loader specifier.
+
+`package.json` exports `.`, `./client`, `./cordis.patch.yml`, `./package.json`,
+`./locale/*.json` and `./icon`, and ships `index.js`, `client.js`, `lib/**`, the
+patch, locales, icon, README, CHANGELOG and LICENSE. Everything else
+(`scripts/`, `docs/`) is repository-only. `npm pack --dry-run` lists 17 files.
+
+Publishing is a push of this directory to a new repository; nothing else in the
+manifest needs to change.
+
+## Layout
+
+```text
+clients/harness/
+├── .gitignore
+├── CHANGELOG.md          # release notes per milestone
+├── LICENSE               # MIT, © 2026 Falari
+├── README.md
+├── package.json          # dsh.bundle + dsh.client manifest, exports, files
+├── cordis.patch.yml      # inserts the falari-harness row
+├── icon.png
+├── index.js              # Host entry: wiring
+├── client.js             # Web client half: panel, tabs, settings
+├── lib/
+│   ├── config.js         # row config resolution + edit validation
+│   ├── errors.js         # shared error shape and mapping
+│   ├── routes.js         # /api/falari-harness/* (same-origin, loopback)
+│   ├── sdk.js            # loads the bundled SDK
+│   ├── service.js        # FalariDataService: key, quote, budget, uploads, downloads
+│   ├── tools.js          # six falari_* Agent tools
+│   └── falari-sdk.cjs    # generated by npm run build:sdk (committed on purpose)
+├── scripts/
+│   ├── build-sdk.sh      # esbuild bundle of @falari/agent + precompiles
+│   ├── unit-host.mjs     # pure-helper unit tests
+│   ├── smoke-host.mjs    # HTTP route smoke tests against a patched SDK
+│   └── smoke-client.mjs  # client.js render smoke test in a VM
+├── locale/{en,zh}.json   # plugin metadata
+└── docs/
+    ├── plan.md           # v0.1 design and milestone log
+    └── test-plan.md      # automated, live and panel checks
+```
+
+## Test
+
+```sh
+npm test            # unit + Host routes + client render, all offline
+```
+
+| Suite | What it does |
+|---|---|
+| `scripts/unit-host.mjs` | config validation/defaults, name sanitizing, status and error mapping |
+| `scripts/smoke-host.mjs` | patches the SDK client and drives every HTTP route: status, key, quote, raw upload, task actions, intents, download, config save, origin and loopback guards |
+| `scripts/smoke-client.mjs` | loads `client.js` in a VM and server-renders the three slot components |
+
+83 checks pass today. The manual and live testnet steps are in
+[docs/test-plan.md](docs/test-plan.md).
+
+## Security
+
+- The Agent Key is a bearer credential with upload rights. It is stored only in
+  the Host credential store; the browser never receives or persists the raw
+  `far_...` string, and no route returns it.
+- Upload routes accept only same-origin requests; cross-origin writes are
+  rejected with 403.
+- Routes answer loopback peers only unless `allowRemoteRoutes` is enabled, so a
+  listener bound to a wider address cannot be used to change the key or pay for
+  uploads.
+- Browser uploads stream into a 0600 temp file under the plugin data directory
+  and are deleted once the task completes or is cancelled; files older than 24
+  hours are swept at startup.
+- The panel shows a private file's Data Key once the upload completes, because
+  losing it makes the ciphertext unrecoverable.
+- Downloads are written only inside the configured `downloadDir` (default
+  `<dataDir>/downloads`); an `out_path` that escapes it is refused, and an
+  existing file name gains a ` (1)` suffix instead of being overwritten.
 
-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.