dsh-realtimeavatar 0.1.1

Fixes for defects found by an adversarial review of the 0.1.0 performance pass.

Fixed

• The page cache could serve a stale page for up to a minute: when two overlapping revalidations of the same URL were answered by different CDN nodes during a docs deploy, a late 304 for the old validator wrote the old body back over the new one. Cache writes are now ordered by issue number, and a 304 whose validator has been superseded returns the newer body.
• Cache freshness and the request deadline are measured on a monotonic clock. A backwards wall-clock step (NTP, VM restore) no longer pins a cached page as fresh or stretches a request budget.
• retryable: false from the server is honoured. A 502 or 503 that says it will not get better is no longer retried.
• Retry-After is only parsed as a date when it is a well-formed HTTP-date. Malformed values, and the comma-joined form a duplicate header produces, no longer become an immediate retry that overrides recommended_retry_ms.
• The first attempt keeps the whole timeout budget, so the plugin's own explanatory timeout wins against a harness deadline of the same length instead of racing it.
• rta_avatars again documents its real ordering, most recently updated first, not newest first.

Changed

• The tool:rta prompt section fits under 1000 characters in every variant the plugin renders, including readOnly (which now reads disabled: readOnly).

Tests

• The quickstart fetch-budget test observes the fetch's own abort signal, so it proves the 3500 ms budget instead of an assertion that could not fail.
• The retry timeout-sharing test is deterministic rather than dependent on a 200 ms scheduling window.

Found by an adversarial review of the 0.1.0 performance pass: 8 confirmed findings, 6 refuted.

npm: https://www.npmjs.com/package/dsh-realtimeavatar (signed provenance from GitHub Actions)

dsh-realtimeavatar 0.1.0

Performance

• Docs pages are cached with their ETag and revalidated with If-None-Match: a repeat read inside 60 s costs no request, and afterwards a bodyless 304 instead of the 10–40 KB page. rta_docs followed by rta_quickstart on the same page is one request.
• Tool descriptions and parameter schemas trimmed by 15% (12194 → 10372 characters, about 455 tokens on every turn); enumerated parameters no longer repeat their values in prose. A budget test pins the cost.
• Idempotent requests (every GET, plus session release) are retried once after a per-key rate limit, a 502, a 503 or a dropped socket, honouring Retry-After / recommended_retry_ms, capped at 5 s and never past the request's own timeout. Queue and concurrency 429s are never retried.
• Skill descriptions shortened to under 220 characters each (the catalog lists all five on every turn) and the tool:rta prompt section cut from 1248 to 983 characters.
• The slowest test (a real 3.5 s wait) now ticks mocked timers and runs in milliseconds.

Added

• Eighteen Cordis tools for the DeepSeek Harness over the public Realtime Avatar
  REST API (https://realtimeavatar.ai/api/v1): eleven reads (rta_status,
  rta_balance, rta_capacity, rta_avatars, rta_avatar, rta_clips,
  rta_assets, rta_usage, the free idempotent rta_session_release,
  rta_docs, rta_quickstart), three write-free tools (rta_asset_remote,
  rta_avatar_update, rta_avatar_delete) and four credit-spending tools
  (rta_avatar_create, rta_loop_set, rta_clips_set, rta_session_mint).
• A tools/pre-execute gate by tier: reads and, under writeApproval:false,
  free writes are passed down the harness chain with next() so later policy
  plugins still see them (the plugin never force-allows); write-free tools ask
  for approval by default; credit-spending tools always ask; for an ask a
  downstream deny wins; readOnly:true denies every write immediately, with a
  second refusal at execute time.
• The API key as a credential reference (apiKeyEnv, default
  REALTIME_AVATAR_API_KEY) resolved per call through the harness credential
  store — launch environment (read-only) over $DSH_HOME/.credentials.yaml
  over the project and user .env files — or, without a store, the launch
  environment. Never part of the config (a value starting with tic_ is
  rejected), never resolved at boot, never rendered. Coded key errors
  (RTA_KEY_MISSING, RTA_KEY_INVALID, RTA_KEY_SHADOWED,
  RTA_KEY_STORE_UNAVAILABLE); the missing-key message says to run
  /rta setup in the web UI or export the variable before launching dsh.
• The /rta command (setup, key, key clear, status, prompt,
  docs [page], help) for interactive profiles. It runs without the model and
  is registered with recordInput:false, so a pasted key is not recorded in the
  session log and is never shown to the model. /rta key clear removes only the
  credential-file entry and reports what still supplies the key afterwards.
• Five skills carrying a dated snapshot of the 14 public documentation pages:
  realtimeavatar-quickstart, realtimeavatar-integrate,
  realtimeavatar-avatars, realtimeavatar-calls, realtimeavatar-api (the
  last embeds the operation table).
• A short system-prompt section (tool:rta) naming the tools and skills, the
  key-handling rule, the public example avatar seed-rin-ashfall, the tools that
  spend credits, and the obligation to release minted sessions.
• Redaction of every tic_live_… / tic_test_… shaped token and every Bearer
  value in errors, rendered output, approval reasons and command results;
  upstream error bodies are parsed, never echoed raw. 403 answers distinguish a
  missing scope, an inactive workspace and the clip_library_not_enabled
  rollout gate.
• rta_session_mint takes voiceId (sent as voice_id) or a full voice
  object, clientMetadata (≤16 pairs, keys ≤64 / values ≤200 chars) and an
  https transcriptWebhook (url ≤500 chars); caps maxSessionSeconds by config
  (default 300 s, at most 1800); returns a capacity-full answer as queued
  rather than an error; and withholds the participant token unless
  includeToken:true, which returns and renders it.
• rta_avatar_update with closed llmProvider and stylePreset enums and a
  separate portrait-swap lane (sourceAssetId, exclusive of everything but
  anchorTimeMs). rta_clips_set validates clipId, whenHint and
  durationSeconds locally, accepts an empty array to retire the library, and
  caps it at 12 entries. rta_loop_set and rta_clips_set send an
  Idempotency-Key (≤180 header-safe chars when supplied). rta_usage rows
  carry activeSeconds, avatarName and endUserId; totals cover settled rows
  only. rta_capacity is informational and never gates a mint.
• Every tool forwards the harness cancellation signal to the HTTP request;
  cancelled calls settle as dsh's ABORTED outcome.
• rta_docs fetches only the closed public page set (14 pages, index =
  llms.txt, openapi = operation table) with a per-call and per-config output
  cap; rta_quickstart falls back to the shipped snapshot offline.
• Release tooling: npm run sync-docs regenerates skills/ from the live
  public pages — validating each page's shape, refusing on OpenAPI operation
  drift, running the leak gate, writing via temp file and rename — and
  --check reports snapshot drift; npm run leak-gate scans the packed tarball
  with generic public patterns plus a salted-digest private-vocabulary list;
  prepublishOnly and CI run it.
• Zero runtime dependencies; MIT license.

npm: https://www.npmjs.com/package/dsh-realtimeavatar (signed provenance from GitHub Actions)