@rackbops/ac-plugin-contract 2.0.0-alpha.37 → 2.0.0-alpha.39

package/AUTHORING.md

@@ -192,6 +192,11 @@ export const createPlugin: CreatePlugin = (host) => ({
   agent's text with a storage error of your own.
 - **Setting** — read/write with `host.settings.get(key)` / `host.settings.set(key, value)`. Both are async;
   `get` returns the manifest `default` when unset.
+- **Console settings** (#506) — `host.consoleSettings?.get(key)`, read-only, optional. Unlike `Setting`
+  above (per-plugin), this reads the console-WIDE settings an operator edits in Admin's Settings card
+  (`repo_owners`, `layout_file`, `tab_order`, `plan_default_machine`, `repo_pins`) -- but only a key on
+  that editable-settings whitelist; anything else resolves to `undefined`. `plugins/provider-github`
+  is the reference consumer (`repo_owners`/`repo_pins`, its own repo-set resolution).
 
 `createPlugin` must import from `@ac/contract` **type-only** (`import type`), so the compiled `dist/server.js`
 has no runtime imports — see §6.
@@ -371,12 +376,21 @@ it.
 until the operator navigates away: it never remounts one to refresh it. (It used to, on any return to the
 window more than a minute after the panel was opened, which reset every filter, selection and half-typed field
 the panel held, every time.) So a panel whose data goes stale while it is open refreshes it itself, in place,
-into the state already on screen: the Board polls every 15 minutes (with a Refresh now button for a click-
-driven read past the poll, #546), and Issues (`issues-classic`) reads its list
-again when the tab comes back (`focus` on `window`, or `visibilitychange` to visible) more than a minute after
-it opened or last refreshed. A panel that does neither -- Agents, the Admin board's cards -- reads when it is
-opened and after its own actions. Only Home is still refreshed by the shell, which remounts it for Refresh, the
-heartbeat and a return after a minute.
+into the state already on screen: the Board polls every 15 minutes, and Issues (`issues-classic`) reads its
+list again when the tab comes back (`focus` on `window`, or `visibilitychange` to visible) 15 minutes or more
+after its last load or refresh; each also has a Refresh now button for a read on demand (#546, #550).
+Navigating to another console tab does unmount a panel, so a panel that should not reload on every tab change
+keeps its data at module scope: a plugin frontend is one ES module loaded once per page, so module-level state
+outlives the unmount, until a full page reload. The Board, Issues and Home's open-issues card all do this
+(#550). Coming back within 15 minutes of the last load shows the data it already had without reading it
+again, and coming back later reads at once. After a read fails, the Board retries the list or the broken
+card on its next remount; Issues re-reads on a remount only what has had no successful read in the last 15
+minutes, and a return or Refresh now click on Issues restarts its 15 minutes whether or not that read
+succeeds. For Issues, "the last load" is the oldest of its repo list's load and each listed repo's issues
+load, so it is only as fresh as its stalest part. A panel that does neither -- Agents, the Admin board's
+cards -- reads when it is opened and after its own actions. Only Home is still refreshed by the shell,
+which remounts it for Refresh, the heartbeat and a return after a minute; Home's open-issues card keeps
+its count across those remounts, so within 15 minutes of its last load none of them re-reads it (#550).
 
 ### The `@ac/host` browser module
 
@@ -511,7 +525,11 @@ still gets its own `Response` (`.clone()`), so two independent reads of a cache
 already-consumed body. Only `GET` may be cached (`cached` throws on any other method); a rejected fetch is
 never cached — the very next call retries. **A card reads through `cached`, never bare `fetch`, so Refresh
 and the Overview heartbeat (both call `invalidate`) actually reach it** — a card that bypasses `cached` keeps
-serving its own stale response until its own next poll, deaf to both:
+serving its own stale response until its own next poll, deaf to both. A card that deliberately keeps its own
+data across a remount (Home's open-issues card, #550) is a further exception on the other side: both Refresh
+and the heartbeat arrive at it as a remount, and it ignores a remount within 15 minutes of its last load —
+`invalidate()` clears `cached`'s own TTL cache, but the card's own freshness check skips calling `cached` at
+all before it ever gets there.
 
 ```ts
 import { cached, invalidate } from "@ac/host"

package/dist/host-api.d.ts

@@ -14,6 +14,16 @@ export interface SettingsService {
     get<T = unknown>(key: string): Promise<T | undefined>;
     set(key: string, value: unknown): Promise<void>;
 }
+/**
+ * Read-only view of the console-WIDE settings an operator edits in Admin's Settings card (#506) --
+ * distinct from `SettingsService` above, which is per-plugin. Only a key on the editable-settings
+ * whitelist (`settings-schema.ts`) is readable here; any other key resolves to `undefined`, so a
+ * plugin can never reach an arbitrary host-global key through this surface. The value returned is
+ * the EFFECTIVE one (an `AC_<KEY>` env override included), the same value the Settings card shows.
+ */
+export interface ConsoleSettingsService {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+}
 /** Per-plugin durable storage: a SQLite table scoped to the plugin, with atomic JSON helpers. */
 export interface StorageService {
     get<T = unknown>(key: string): Promise<T | undefined>;
@@ -203,6 +213,9 @@ export interface HostApi {
     plugins?: PluginJobsService;
     /** #84: see `SlotRegistry`. */
     slots: SlotRegistry;
+    /** #506: see `ConsoleSettingsService`. Optional so an out-of-repo plugin's own test fake still
+     *  compiles. */
+    consoleSettings?: ConsoleSettingsService;
 }
 /**
  * The context the host passes to `Plugin.runJob` for one job run (#31). `jobId` selects which

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/ac-plugin-contract",
-  "version": "2.0.0-alpha.37",
+  "version": "2.0.0-alpha.39",
   "private": false,
   "type": "module",
   "description": "The artifact-console plugin ABI for out-of-repo plugin authors: HostApi, the acPlugin manifest contribution points, the generated manifest JSON Schema, and the @ac/host ambient browser declaration.",