@songsid/agend 2.3.0-beta.1 → 2.3.0-beta.2

package/dist/general-knowledge/skills/credential-profiles/SKILL.md

@@ -189,6 +189,13 @@ A kiro profile that is configured but has never been logged in still gets a row,
 reading **Signed out — run `kiro-cli` to log in**. That is the reminder to go
 and log it in, so report it as such rather than as a missing subscription.
 
+## "Is the prompt cache costing us?"
+
+`get_cache_report({ window?, instance?, top? })` is the dashboard's **Fleet → cache** report.
+- **What a row has:** each instance's cache TTL as written and its 5m/1h write mix, the TTL it really behaves as (`effective_ttl`, with the gap-miss rate it is measured from), its expiry cost, and the keep-warm simulation and recommendation.
+- **When to look:** when someone asks why costs rose, whether to keep caches warm, or whether to set `backend_options.claude-code.prompt_cache_ttl: "1h"`. A row recommending `switch_to_1h` is the answer to the last one.
+- **What you can see:** as General you see every instance and the fleet summary.
+
 ## What to tell the user
 
 - Two agents with the same profile name share one login and one quota.

package/dist/general-knowledge/skills/web-appearance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: web-appearance
-description: How you look on the AgEnD web dashboard — check it, change your own theme, identity card and widgets, preview the result, share it as a mod
+description: How you look on the AgEnD web dashboard — check it, change your own theme, identity card, identity colour and widgets, play Canvas Worker effects in your chat (and offer a Try), preview the result, share it as a mod
 roles: [worker]
 ---
 
@@ -16,8 +16,10 @@ can shape how you look there — **only your own look, and only on the surfaces
 | Your chat | theme: colours, accent, bubbles, font, background picture, working label | `set_web_theme`, `set_web_theme_asset` |
 | Your face and ring | theme picture and accent | `set_web_theme`, `set_web_theme_asset` |
 | Your identity card | portrait, banner, tagline, bio | `set_web_theme` (`card.*`), `set_web_theme_asset` |
+| Your identity colour | the colour people find you by in the sidebar, and where it shows (name, bar, ring) | `set_web_theme` (`identity`) |
 | Your chat header strip and Details page | widgets: small panels of facts the dashboard draws | `set_web_widget`, `remove_web_widget` |
 | A file of your look | a mod: export yours, or propose one for a person | `export_web_mod`, `propose_web_mod` |
+| Effects in your chat | Canvas Worker animations, and Try cards a local admin may start | `upload_web_effect`, `apply_web_effect`, `preview_web_effect`, … (see Effects) |
 
 None of these tools takes a target: they always act on you. You can't change another instance, the dashboard's own
 chrome, a person's sidebar widget, or a person's custom CSS.
@@ -109,6 +111,25 @@ theme stops naming is deleted.
 `card.banner` (asset ids uploaded for those slots). Text is shown as text — never markup or links. A person may set
 their own version of any field; theirs is shown instead of yours.
 
+The card goes **inside `set`**: `set_web_theme({ set: { card: { tagline, bio, portrait, banner } } })` (a top-level
+`card` argument is refused).
+
+## Your identity colour
+
+The colour people find you by in the sidebar, drawn on your name, a bar at your row's left edge and/or the ring around
+your picture. Set yours with `set_web_theme({ set: { identity: { color, show } } })` (see Change your theme).
+
+- **Which colour shows**, first match wins: a **person's** pick for you (⋯ → Colour… or View's Edit profile, also from a
+  temporary public link) > **yours** (`identity.color`, else your theme's `accent`; only for a viewer who shows agents'
+  themes) > your own bot's Discord **role** colour > an **automatic** soft colour chosen from your name (two instances
+  may share one).
+- **Where it shows**: a person's choice for you > yours (`identity.show`; again only while themes are shown) > the
+  host's default (Settings → Web appearance; ring and bar unless changed).
+- The host can **turn colours off** for everyone: nothing is drawn, and every pick, yours included, is kept for when
+  they come back.
+- `get_web_appearance`'s `identity_color` shows what is in force: `color`, `source` (`person`, `agent`, `role`, `auto`),
+  `light` / `dark`, `show`, `show_source` (`person`, `agent`, `host`) and `off`.
+
 ## Widgets
 
 A widget is a small panel of facts the dashboard draws **with its own components**: you send what to show and the
@@ -184,6 +205,8 @@ with the tools above, then `export_web_mod`.
   with `rate_limited` and `retry_after_s`. Only an accepted change counts; a refused or invalid one costs nothing.
 - Widget values (`set_web_widget` with `data` only): at least **10 s** apart, at most **180 an hour**, apart from the
   above.
+- Effects: `apply_web_effect` and `remove_web_effect` are changes; `upload_web_effect` and `propose_web_mod` are uploads.
+  At most 10 effects and 8 MiB of your own, at most two placed in your chat.
 - Plan the whole look, check it in one `set_web_theme`, then preview — don't iterate change by change.
 
 ## A good workflow
@@ -198,6 +221,92 @@ From a shell: `agend-agent theme get|set key=value…|set --json '<patch>'|clear
 `agend-agent widget set <slot> '<spec json>' ['<data json>']|data <slot> '<data json>'|remove [slot]`, and
 `agend-agent mod export <name> <version> [title]|propose <file>`.
 
+## Files in your working directory
+
+Asset uploads, effect directories and mod proposals must be inside your working directory. This includes your own
+AgEnD-managed workspace (`~/.agend/workspaces/<your-instance-name>`), used by ClassicBot and instances without a
+project directory. `web-assets/` and `web-effects/` are convenient staging folders, not required names. Paths are
+checked after resolving symlinks: for the supplied caller identity, another instance's workspace and all other AgEnD
+state remain forbidden, including
+`.env`, databases, `instances/`, `credential-profiles/` and `inbox/`. Symlinks cannot grant access outside your working
+directory or into protected state; uploaded files themselves must not be symlinks. Generated appearance previews and
+mod exports follow the same workspace boundary. The CLI takes its caller name from `AGEND_INSTANCE_NAME` and its
+working directory from the shell; these local checks do not isolate shells running as the same OS user.
+
+## Effects
+
+A Canvas Worker effect is a small animation drawn by code that runs in an isolated Worker: no page, no DOM, no
+network. You place effects **only in your own chat**; a person can place them in the regions an effect's manifest
+allows. None of these tools takes a target.
+
+**The package** (CW1): a directory in your working directory with `effect.json` and `worker.js`, optionally
+`poster.png`, `cursor.png` and `assets/*.png|jpg|jpeg|webp|gif`. No HTML or CSS, at most 20 files and 16 assets. The
+smallest valid `effect.json`:
+
+```json
+{ "v": 1, "kind": "effect", "runtime": "canvas-worker-v1", "worker": "worker.js", "name": "spark", "title": "Spark", "regions": ["chat"], "layer": "behind", "wants": [] }
+```
+
+- Optional fields: `description`, `poster` (`"poster.png"`), `box`, `cursor` (its `hotspot` inside the image) and
+  `params`.
+  - `name`: 1..32 characters, starting with a-z or 0-9, then a-z, 0-9 and -.
+  - `title` (1..40) and `description` (up to 200): one line each, counted in characters as people see them.
+  - `regions`: 1–5 of `chat`, `sidebar`, `header`, `page`, `box`. **Include `chat` to place it in a chat**: applying
+    one without it is refused (`effect_region`), and so is a mod placing it. The other regions are ones a person may
+    choose it for.
+  - `layer`: `behind` (under the content) or `front` (over it).
+  - `wants`: up to 5 of `pointer`, `state`, `reply`, `mention`, `theme`. **`mention` is reserved and never fires in
+    2.3.0** (see Effect event availability).
+  - `params`: up to 16 typed parameters (`number`, `int`, `bool`, `enum`, `color`) a placement may set.
+- `worker.js` (at most 1 MiB, a classic script: static `import` / `export` are refused) draws through the `agend` API:
+  `canvas`, `params`, `asset()`, `on()`, `frame()` and `ready()`. Call `ready()` within 10 s, or it is stopped. Network
+  and dynamic imports are blocked at run time; the upload may warn `network_or_import_api_unsupported`, but don't rely
+  on the warning to catch every use.
+- Size: `effect.json` at most 64 KiB; the whole effect at most 8 MiB as uploaded and **1 MiB normalized**. Pictures:
+  at most 4096 px a side, and **8,388,608 pixels in total** across the assets, poster and cursor together. A cursor is
+  a square PNG of at most 64 px and 32 KiB (after metadata is stripped).
+
+**The tools:**
+
+- `upload_web_effect { dir }` → `{ id, warnings }`. It counts as an upload (3 an hour, shared with pictures and mods).
+  **Your own** copies are at most **10 effects and 8 MiB**; effects a person shared with you don't count.
+- `list_web_effects` — your own effects and those a person shared with you: `id`, `name`, `title`, `regions`, `layer`,
+  `bytes`, `latest_profile`.
+- `apply_web_effect { id, params? }` places one in your chat, **at most two at a time**, with the declared `params`
+  (unknown or out of range → `effect_params`; regions without `chat` → `effect_region`). `remove_web_effect { id? }`
+  takes one out, or all of them. Both are changes (30 s apart, 10 an hour), and are refused while a person has locked
+  your theme (`locked`) or when the fleet turned agent changes off (`theme_editing_off`).
+- `delete_web_effect { id }` deletes your own copy once nothing uses it; a placement, mod, stage or Try offer gives
+  `effect_in_use`. Another's copy is never removed.
+- `profile_web_effect { id }` — how it ran on viewers' pages, per device class: `unmeasured`, or `reported` with
+  records carrying a `verdict` (`ok`, `degraded`, `paused`, `off`) and a `reason` (`host_budget`, `hidden`,
+  `reduced_motion`, `save_data`, `viewer_off`, `clock_unavailable`, `gates_unknown`, or none).
+  `list_web_effects`' `latest_profile` has the latest one. These are best-effort reports of what happened, not live
+  notices. No measurement means unknown, never healthy.
+- `preview_web_effect { id }` offers a Try card in your chat (see Try below).
+- **Sharing is a person's act.** You can't share an effect. You may use one a person shared with you (list, apply,
+  Try, profile, put in a mod) while it is shared. When they unshare it, a placement already in your chat stays
+  eligible for playback (subject to the viewer's and the safety rules); applying, Try, listing, profiling or exporting
+  it again needs your own copy or another share, else `not_found`. A placement is never a grant to export it.
+
+**On a viewer's page:**
+
+- At most **3** effects play at once, at most **2** of them `front` (1 and 1 on a constrained device); the rest wait
+  (`frame_limit`, `front_limit`).
+- Nothing plays in safe mode, over a temporary public link, with reduced motion or save-data, on a hidden page, while
+  the viewer has effects off, or before they consent to previews. A `poster.png` may then show behind the chat (see
+  Static Chat fallback). A visible menu or dialog stops `front` effects; these stops lift by themselves.
+- **Safety pause** — it measures the page's responsiveness, not your Worker's CPU. The page's frame-rate floor is
+  90% of what it measured before the effect started, capped at 55 fps (50 on a constrained device), so a 30 Hz screen
+  has a 27 fps floor. Where the browser reports them, long tasks may take at most 50 ms a second (25 ms constrained);
+  unknown timing doesn't count as free. Overlapping 2-second windows are judged at most once a second after a warm-up,
+  and three bad judgements in a row pause the effect (`host_budget`).
+- Only a viewer's explicit **Resume** restarts a safety-paused effect, and it doesn't clear the history: three such
+  pauses within 24 hours turn the effect **off** for that viewer's browser and device class, across tabs and reloads,
+  and Resume then refuses. It doesn't come back by itself after 24 hours.
+- **Your `front` effects are paused while the viewer's custom CSS is on, loading or unknown**; `behind` effects play
+  once the page's stock layout is proven. A person's placement is exempt. Don't keep re-applying (see below).
+
 ## Owner-level effect selections
 
 The five owner keys `fx.sidebar`, `fx.header`, `fx.page`, `fx.box` and `fx.cursor` are a signed-in person's web
@@ -214,7 +323,7 @@ placed there. A reference is not a sharing or export grant. Do not keep retrying
 
 Owner selectors are available in Settings → Web appearance. With effects and preview consent enabled, personal
 page/header/sidebar/box choices play across supported stock pages in the same pool as local signed-in Chat.
-Appearance offers slot Pause/Resume and unavailable/Clear controls. The personal cursor uses a static PNG on the host shell after the same consent: no Worker/code read or frame slot. It preserves explicit pointer/text/resize cursors, falls back while dragging or on failure, and has status/Clear rather than Worker Pause/Resume. Before revealing paint, the host must prove stock content
+Web appearance offers slot Pause/Resume and unavailable/Clear controls. The personal cursor uses a static PNG on the host shell after the same consent: no Worker/code read or frame slot. It preserves explicit pointer/text/resize cursors, falls back while dragging or on failure, and has status/Clear rather than Worker Pause/Resume. Before revealing paint, the host must prove stock content
 ordering and trust paint coverage. Agent front effects must remain paused when custom CSS is active, loading or
 unknown; a person sees the reason and can open the causing setting. Human placements retain their exemption from
 that agent restriction, and behind effects still require proven ordering. Saving a placement alone is not proof of
@@ -230,7 +339,7 @@ deferred to #1940; do not keep reapplying an agent front while custom CSS is on,
 click by a signed-in **local admin** may start it; never an agent, public link, header token or automatic action.
 The host owns a visible Trial label and Stop control. Closing the panel/sheet, navigating, window blur, or another
 menu/dialog stops it. Custom CSS must be off (on/loading/unknown denies), and the same caps, profiler and safety
-stops apply. Ordinary foreground effects stay suppressed. A volatile offer lasts at most ten minutes; every read
+stops apply. Ordinary foreground effects stay suppressed. A volatile offer lasts at most ten minutes (offering the same effect again keeps that offer and its expiry; a different effect replaces it); every read
 rechecks the originating agent's current own/shared access, with the trial bound to the admin's session and epoch.
 There is no saved placement, claim, share, export or new saved profile record. Cards are memory-only and become inert when expired; a restart never restores them. Try uses manifest defaults and the existing app pool, not a second runtime. Do not treat an offer id or ordinary reply button
 as permission to run or fetch an effect, and do not keep retrying an unavailable Try.

package/dist/outbound-handlers.d.ts

@@ -109,6 +109,8 @@ export interface OutboundContext {
     getInstanceExecutionState?(name: string): "idle" | "working" | "stuck" | "paused" | null;
     /** Subscription provider IDs used by running or paused fleet/Classic instances. */
     getActiveUsageProviderIds?(): ReadonlySet<string>;
+    /** #2001: the cache report as last worked out (CacheService.published) — never a transcript read. */
+    cacheReportPublished?(window: string): Promise<import("./cache-service.js").CacheReport>;
     /** Effective process state used to annotate cross-instance delivery results. */
     getInstanceStatus?(name: string): "running" | "paused" | "stopped" | "crashed";
     /** #1808: whether `backend` takes this model name (the rule /backend applies too); `choices`: what it offers. */

package/dist/outbound-handlers.js

@@ -15,7 +15,7 @@ import { CHAT_PROFILE_LOGIN_BACKENDS, credentialProfileLogin, credentialSwitchCa
 import { kiroEngineCandidates, kiroEngineStatus } from "./kiro-engine-status.js";
 import { noPlaceMarkers, placeRef, renderPlaceRefs, stripPlaceRefs, webRoute } from "./topic-link.js";
 import { formatCrossInstanceInboundMessage, MAX_ASSEMBLED_CROSS_INSTANCE_MESSAGE_BYTES, } from "./cross-instance-envelope.js";
-import { BroadcastArgs, CreateInstanceArgs, CreateTeamArgs, DelegateTaskArgs, DeleteInstanceArgs, DeleteTeamArgs, DeployTemplateArgs, DescribeInstanceArgs, ListDeploymentsArgs, ListInstancesArgs, ListTeamsArgs, ReplaceInstanceArgs, ReportResultArgs, DeliveryStatusArgs, RequestInformationArgs, RestartInstanceArgs, SendToInstanceArgs, PauseInstanceArgs, WakeInstanceArgs, StopInstanceArgs, GetInstanceLogsArgs, GetEffortArgs, ClosePollArgs, KiroEngineStatusArgs, GetUsageArgs, ListModelsArgs, GetFleetConfigArgs, UpdateInstanceConfigArgs, UpdateFleetDefaultsArgs, StartInstanceArgs, TeardownDeploymentArgs, UpdateTeamArgs, validateArgs, } from "./outbound-schemas.js";
+import { BroadcastArgs, CreateInstanceArgs, CreateTeamArgs, DelegateTaskArgs, DeleteInstanceArgs, DeleteTeamArgs, DeployTemplateArgs, DescribeInstanceArgs, ListDeploymentsArgs, ListInstancesArgs, ListTeamsArgs, ReplaceInstanceArgs, ReportResultArgs, DeliveryStatusArgs, RequestInformationArgs, RestartInstanceArgs, SendToInstanceArgs, PauseInstanceArgs, WakeInstanceArgs, StopInstanceArgs, GetInstanceLogsArgs, GetEffortArgs, ClosePollArgs, KiroEngineStatusArgs, GetUsageArgs, GetCacheReportArgs, ListModelsArgs, GetFleetConfigArgs, UpdateInstanceConfigArgs, UpdateFleetDefaultsArgs, StartInstanceArgs, TeardownDeploymentArgs, UpdateTeamArgs, validateArgs, } from "./outbound-schemas.js";
 const HOME_DIR = homedir();
 function formatByteSize(bytes) {
     if (bytes < 1024)
@@ -871,6 +871,39 @@ const getUsage = async (ctx, rawArgs, respond) => {
         respond(null, `Usage fetch failed: ${err.message}`);
     }
 };
+/**
+ * #2001: the prompt-cache report for an agent. From the last scan (cacheReportPublished: in-memory ledgers, reused
+ * for a minute) — no transcript read and no process on the fleet loop. Who sees what: cacheReportScope.
+ */
+const getCacheReport = async (ctx, rawArgs, respond, meta) => {
+    const v = validateArgs(GetCacheReportArgs, rawArgs, "get_cache_report");
+    if (!v.ok) {
+        respond(null, v.error);
+        return;
+    }
+    const caller = meta?.instanceName;
+    if (!caller) {
+        respond(null, "get_cache_report: the calling instance is unknown");
+        return;
+    }
+    if (!ctx.cacheReportPublished) {
+        respond(null, "get_cache_report is unavailable on this fleet");
+        return;
+    }
+    const { resolveToolSet, cacheReportScope } = await import("./tool-permissions.js");
+    const { cacheReportForTool } = await import("./cache-report-tool.js");
+    const scope = cacheReportScope(resolveToolSet(ctx.fleetConfig?.instances[caller], caller));
+    try {
+        const out = cacheReportForTool(await ctx.cacheReportPublished(v.data.window ?? "7d"), { scope, caller, instance: v.data.instance, top: v.data.top });
+        if ("error" in out && typeof out.error === "string")
+            respond(null, out.error);
+        else
+            respond(out);
+    }
+    catch (err) {
+        respond(null, `get_cache_report failed: ${err.message}`);
+    }
+};
 /**
  * Enumerate a backend's models. Read-only and best-effort by design: the
  * catalog is an aid for picking a name, and AgEnD passes model strings through
@@ -1993,6 +2026,7 @@ export const outboundHandlers = new Map([
     ["close_poll", closePoll],
     ["kiro_engine_status", kiroEngineStatusHandler],
     ["get_usage", getUsage],
+    ["get_cache_report", getCacheReport],
     ["list_models", listModels],
     ["get_instance_logs", getInstanceLogs],
     ["get_fleet_config", getFleetConfig],