@runappsai/sdk 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RunJobs
+
+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,275 @@
-# Temporary Holding Version
+# RunApps SDK for JavaScript / TypeScript
 
-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.
+The client for building apps on [RunApps](https://www.runapps.ai): call any model (Claude, GPT, Gemini, DeepSeek, Qwen, MiniMax, GLM, Grok), generate images, audio and video, keep per-user files, and let the platform handle sign-in and billing. Zero runtime dependencies — native `fetch`, `FormData` and `ReadableStream` (browsers, Node 18+, Deno, Bun).
+
+Two ways to use it:
+
+- **In an app you publish on RunApps** — a static bundle served at `<slug>.runapps.dev`. Users sign in with their RunApps account and pay for their own usage; you never hold a key. This is what `authProvider: "runapps"` is for.
+- **From your own code** — server, script or CLI — with a personal API key (`rk_…`).
+
+## Install
+
+```bash
+npm install @runappsai/sdk
+```
+
+Or as a script tag:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@runappsai/sdk/dist/sdk.umd.js"></script>
+<script>
+  const client = new RunApps({ authProvider: "runapps" });
+</script>
+```
+
+## Building an app
+
+### 1. Create the app, then develop against it
+
+An app gets its slug the moment you create it on the dashboard (Creator → Publish) — no zip needed yet. Pass that slug as `project` and your dev server runs against the real platform:
+
+```ts
+import { RunApps } from "@runappsai/sdk";
+
+const client = new RunApps({
+  authProvider: "runapps",   // sign-in, token, refresh — all handled
+  project: "my-tool",        // the draft's slug; unchanged after you upload
+});
+
+const resp = await client.chat.create({
+  model: "Claude Sonnet 4.6",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+console.log(resp.choices[0].message.content);
+```
+
+- Sign-in works from `http://localhost:<any port>`; the first call redirects to the RunApps grant page and back.
+- Calls are billed to the signed-in user — while developing, that is you.
+- Files and private prompts already use the app's real namespace, so nothing moves when you upload.
+
+When the app is ready, build it, zip it, and upload it to the same app. Set it private (reachable by link) or submit it for review to be listed in the library.
+
+### 2. Sign-in details
+
+```ts
+await client.chat.create({ ... });   // redirects to the grant page on first use
+
+client.signIn();                     // force the redirect
+client.signOut();                    // clear the cached token (sticky across reloads)
+client.user;                         // { id, name } | null
+client.auth?.onTokenChange(t => {}); // subscribe to (re)acquisition
+client.auth?.hasFreshToken();        // avoid showing a "sign in" button needlessly
+```
+
+`showIdentityBadge` (default `true`) draws a small activity badge; `badgePosition` places it.
+
+`project` is optional on `*.runapps.dev` — the origin already says which app it is. It is required on localhost and when the client runs on a personal key (see below). Sign-in only works on the app's own `*.runapps.dev` address and on `http://localhost`. In Node, `authProvider: "runapps"` is a no-op; use `apiKey`.
+
+### 3. Private prompts
+
+Anything in your frontend can be read in the browser. Name your prompt files in a `bundle.json` at the root of your zip — `{"prompts": {"outline": "prompts/outline.md"}}` — or put them under `.runapps/prompts/<id>.md`. The platform never serves `bundle.json`, the files it names, or any dot folder; call the prompts by id:
+
+```ts
+await client.chat.create({
+  model: "Claude Sonnet 4.6",
+  messages: [{ role: "user", content: "A detective in a lighthouse." }],
+  prompt: { id: "outline", vars: { genre: "mystery" } },   // {{genre}} in the file
+});
+```
+
+The gateway prepends the prompt as the system message and asks the model to keep it confidential; a reply that repeats 30+ characters of it verbatim is withheld (`finish_reason: "content_filter"`). While developing locally, before a bundle exists, send the text inline as `prompt.template` — accepted only from the app's creator — and keep it out of production builds with `import.meta.env.DEV`.
+
+### 4. Per-user files
+
+Every app gets a file space per signed-in user, addressed by POSIX-style paths. `FileObject.url` is a stable public address you can drop into `<img src>`.
+
+```ts
+// Write. body: Blob | File | ArrayBuffer | Uint8Array | ReadableStream | string
+const obj = await client.files.put("assets/logo.png", pngBlob, { contentType: "image/png" });
+await client.files.putString("notes.md", "# hello");
+await client.files.putFromURL("cache/cat.jpg", "https://example.com/cat.jpg"); // gateway fetches it
+
+// Read.
+const blob = await client.files.get("assets/logo.png");
+const meta = await client.files.stat("assets/logo.png");   // size, etag, last_modified, url
+await client.files.exists("assets/logo.png");
+
+// List, with an optional shell glob (*, **, ?, [abc]) matched against the whole path.
+const page = await client.files.list({ prefix: "assets/", glob: "**/*.png", limit: 100 });
+// page.next_cursor → pass as cursor for the next page
+
+// Mutate.
+await client.files.move("draft.md", "published.md");
+await client.files.copy("template.md", "instances/today.md");
+await client.files.del("old.log");
+await client.files.deleteMany({ prefix: "tmp/" });
+await client.files.deleteMany({ glob: "**/*.tmp" });
+
+// Several ops in one round trip; each result has its own ok/error.
+await client.files.batch([
+  { op: "put_url", path: "a.jpg", src_url: "https://example.com/a.jpg" },
+  { op: "copy", from: "a.jpg", to: "b.jpg" },
+  { op: "del", path: "a.jpg" },
+]);
+```
+
+**Keeping app state in a file** — read, modify, write, without overwriting another tab's save. Every read carries the file's ETag; `ifMatch` makes the write fail (412) if the file changed since:
+
+```ts
+const { value, etag } = await client.files.readJSON<{ score: number }>("state.json");
+const next = { ...(value ?? { score: 0 }), score: (value?.score ?? 0) + 1 };
+try {
+  await client.files.put("state.json", JSON.stringify(next), {
+    contentType: "application/json",
+    ...(etag ? { ifMatch: etag } : { ifNoneMatch: true }),   // first save: must not exist
+  });
+} catch (e) {
+  if (e instanceof APIError && e.statusCode === 412) { /* re-read, merge, retry */ }
+}
+```
+
+`files.read(path)` is `get` plus the ETag for non-JSON files. `ifNoneMatch: true` refuses to overwrite (409).
+
+## From your own code
+
+```ts
+import { RunApps, APIError } from "@runappsai/sdk";
+
+const client = new RunApps({ apiKey: "rk_…" });   // Dashboard → API Keys
+
+const resp = await client.chat.create({
+  model: "Gemini 3 Flash",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+console.log(resp.usage.total_cost);   // USD
+```
+
+The base URL is `https://www.runapps.ai` in both modes; `baseURL` overrides it.
+
+**Files with a personal key** — a personal key has no app of its own, so name the app: `new RunApps({ apiKey, project: "my-tool" })`. You get your own files in that app, the same ones the app sees for you, provided you have added the app or created it.
+
+**Any OpenAI-compatible SDK works too.** Point it at the platform with your `rk_…` key:
+
+```python
+from openai import OpenAI
+client = OpenAI(api_key="rk_...", base_url="https://www.runapps.ai/v1")
+client.chat.completions.create(model="Claude Sonnet 4.6", messages=[{"role": "user", "content": "Hello!"}])
+```
+
+Browse `GET /v1/models` (no auth) for the live catalogue and per-model prices.
+
+## Chat
+
+OpenAI-compatible, streaming or not. The final streamed chunk carries `usage`.
+
+```ts
+for await (const chunk of client.chat.stream({ model: "Gemini 3 Flash", messages })) {
+  for (const c of chunk.choices) process.stdout.write(c.delta.content ?? "");
+  if (chunk.usage) console.log("\ncost", chunk.usage.total_cost);
+}
+```
+
+**Images, video and audio in messages** — check the model first with `acceptsModality(model, "video")`; the gateway rejects unsupported parts with a 400 before billing:
+
+```ts
+import { userMessageParts, textPart, imagePart, videoPart, audioPart } from "@runappsai/sdk";
+
+await client.chat.create({
+  model: "Gemini 3 Vision",
+  messages: [userMessageParts(textPart("Summarise this clip"), videoPart("https://example.com/clip.mp4"))],
+});
+```
+
+**Your own tools** — pass `tools: [{ type: "function", function: { name, description, parameters } }]`, read `choices[0].message.tool_calls`, answer with `toolResultMessage(toolCallId, output)` on the next turn.
+
+**Server tools** — the platform searches and reads the web for the model, looping until it answers; your code only sees the result. Combine freely with your own `tools`.
+
+```ts
+import { ServerTools } from "@runappsai/sdk";
+
+const resp = await client.chat.create({
+  model: "Claude Sonnet 4.6",
+  messages: [{ role: "user", content: "What is the latest stable Go version?" }],
+  server_tools: [ServerTools.WebSearch, ServerTools.WebFetch],
+  max_server_iterations: 5,                 // default 5, max 10
+});
+for (const t of resp.usage.tool_costs ?? []) console.log(t.name, t.count, t.cost);
+```
+
+`WebSearch` and `TwitterSearch` are priced per call, `WebFetch` is free; `usage.total_cost` includes tools and tokens. With `stream: true` the tool rounds run silently and the final answer streams.
+
+Message builders: `userMessage`, `systemMessage`, `assistantMessage`, `toolResultMessage`, `userMessageParts`, `textPart`, `imagePart`, `videoPart`, `audioPart`.
+
+## Models
+
+```ts
+const all = await client.models.list();
+const video = await client.models.list({ capability: "video_generation" });
+```
+
+Prices are in pips per million tokens (1 USD = 1,000,000 pips). Each model carries `capability_tags` (stable ids such as `t2v`, `i2v`, `voice_clone`, `timestamps` — filter with `hasCapabilityTag`), chat models carry `input_modalities` (`acceptsModality`), and every model exposes its input contract through `getOptionsSchema(model)`: accepted fields, bounds, enums, cross-field constraints, and a catalogue of voices or emotions. `validateRequest(schema, body)` returns every problem at once for a form to show.
+
+## Image, audio, video, embeddings
+
+```ts
+// Image — data: URI (sync) or hosted blob URL (async); decodeMediaUrl() gives bytes.
+const img = await client.image.generate("MiniMax Image-01", {
+  prompt: "a developer at a laptop, anime style",
+  resolution: "2K", aspect_ratio: "16:9",        // or size: "WxH"
+  reference_image_urls: ["https://…"],
+});
+await client.image.edit("GPT Image", { image: { data: bytes, filename: "photo.png" }, prompt: "add a party hat" });
+// generateAsync / submitGenerate + getAsyncStatus for jobs longer than ~100 s
+
+// Speech.
+const speech = await client.audio.speech("MiniMax Speech 2.6 HD", { input: "Hello", voice: "English_radiant_girl", emotion: "happy" });
+const text = await client.audio.transcribe("OpenAI/Whisper", { file: { data: audioBytes, filename: "a.mp3" } });
+// speechAsync / transcribeAsync for long jobs; voices and emotions are in getOptionsSchema(model).catalog
+
+// Video — always async.
+const task = await client.video.generate("MiniMax Hailuo 2.3", { prompt: "a gentle ocean wave", duration: 5 });
+const status = await client.video.wait(task.id, { pollIntervalMs: 5000 });
+if (status.status === "succeeded") await client.video.getContent(task.id);
+
+// Embeddings.
+const e = await client.embeddings.create("text-embedding-3-small", { input: ["alpha", "beta"] });
+```
+
+`VideoGenerateParams` covers keyframes (`first_frame_url` / `last_frame_url`), reference inputs, source video/image/audio drivers, `service_tier: "flex"`, and more; every `*_url` accepts `https://` or a `data:` URI (`encodeImageUrl(bytes)`).
+
+## Errors and cancellation
+
+```ts
+try {
+  await client.chat.create({ ... }, { signal: controller.signal });
+} catch (e) {
+  if (e instanceof APIError) console.error(e.statusCode, e.type, e.message);
+  else throw e;   // network errors are the fetch rejection
+}
+```
+
+Every call takes `{ signal }`. In browser-auth mode a 401 is retried once after refreshing the token.
+
+## API reference
+
+| Service | Methods |
+|---|---|
+| `client.chat` | `create`, `stream` |
+| `client.models` | `list` |
+| `client.files` | `put`, `putString`, `putFromURL`, `get`, `read`, `readJSON`, `stat`, `exists`, `list`, `del`, `deleteMany`, `move`, `copy`, `batch` |
+| `client.image` | `generate`, `edit`, `generateAsync`, `submitGenerate`, `getAsyncStatus` |
+| `client.audio` | `speech`, `speechAsync`, `transcribe`, `transcribeAsync` |
+| `client.video` | `generate`, `getStatus`, `wait`, `getContent` |
+| `client.embeddings` | `create` |
+
+Browser auth: `client.signIn()`, `client.signOut()`, `client.user`, `client.auth`.
+
+Helpers: `hasCapabilityTag`, `acceptsModality`, `getOptionsSchema`, `acceptsField`, `requiresField`, `allowedValuesFor`, `validateRequest`, `supportsVoiceClone`, `supportsInstructText`, `defaultVoice`, `encodeImageUrl`, `decodeMediaUrl`, the message builders, `ServerTools`.
+
+## Compatibility
+
+Browsers (any modern), Node 18+, Deno, Bun. Never ship an `rk_…` key to a browser — an app published on RunApps uses `authProvider: "runapps"` instead, and the user pays for their own usage.
+
+## License
+
+MIT

package/dist/activity-tracker.d.ts

@@ -0,0 +1,113 @@
+/**
+ * In-memory session-scoped activity index — turns the raw event
+ * stream from `SDKEvents` into the snapshot the badge UI reads each
+ * frame: which calls are in flight, what just finished, what the
+ * running session cost is.
+ *
+ * Memory bounded:
+ *   - `active` map shrinks on every end/error (calls don't accumulate
+ *     past their settle event).
+ *   - `recent` is a bounded ring of the last RECENT_MAX completions.
+ *   - tokens/sec windows hold only `RATE_WINDOW_MS` worth of deltas;
+ *     stale samples get dropped on every push.
+ *
+ * Snapshot pattern (vs. emitting another event per change): the
+ * badge re-renders on `requestAnimationFrame` while it's open, so
+ * a pull-snapshot API matches that cadence — pushing on every
+ * delta would over-paint and cost battery on token-heavy streams.
+ */
+import type { SDKCapability, SDKEvents } from "./events.js";
+/** One LLM call currently in flight. */
+export interface ActiveCall {
+    id: string;
+    model: string;
+    capability: SDKCapability;
+    startedAt: number;
+    /** True for stream:true. Drives the pulsing-ring animation. */
+    streaming: boolean;
+    /** Cumulative completion tokens (0 until first delta). */
+    tokensSoFar: number;
+    /** Tokens per second over the last RATE_WINDOW_MS. 0 until the
+     *  window has 2+ samples. */
+    tokensPerSec: number;
+    /** Internal sample buffer — exposed for tests; UI ignores. */
+    rateSamples: Array<{
+        t: number;
+        tokens: number;
+    }>;
+}
+/** One LLM call that already finished (success OR failure). */
+export interface CompletedCall {
+    id: string;
+    model: string;
+    capability: SDKCapability;
+    latencyMs: number;
+    totalTokens: number;
+    costUSD?: number;
+    finishReason?: string;
+    /** false for RequestErrorEvent settles. */
+    ok: boolean;
+    /** Error message when ok=false. */
+    errorMessage?: string;
+    /** Wall clock at settle — drives the "30s ago" relative display. */
+    endedAt: number;
+}
+/** Running session totals — shown in the popover's footer. */
+export interface SessionStats {
+    totalCalls: number;
+    totalCostUSD: number;
+    errorCount: number;
+    /** Wall clock when the tracker first saw an event. Drives the
+     *  "session lasted N minutes" string. */
+    startedAt: number;
+}
+/** Pull-snapshot of the tracker — taken once per badge re-render. */
+export interface ActivitySnapshot {
+    active: ActiveCall[];
+    recent: CompletedCall[];
+    session: SessionStats;
+    /** Highest-priority status colour for the LED dot:
+     *    "error"   → recent failure within ERROR_HIGHLIGHT_MS
+     *    "active"  → at least one in-flight call
+     *    "idle"    → nothing happening
+     *  The badge's CSS uses this as a class. */
+    status: "idle" | "active" | "error";
+}
+export declare class ActivityTracker {
+    private active;
+    private recent;
+    private session;
+    /** Track most recent error wall-clock so the LED stays red for
+     *  ERROR_HIGHLIGHT_MS even after the error scrolls out of recent. */
+    private lastErrorAt;
+    /** "Snapshot changed" listeners. Fired AFTER every event handler
+     *  runs (start / delta / end / error), letting UIs re-render in
+     *  push-mode instead of polling. Without this hook, the badge's
+     *  ring/LED stayed idle until the user opened the popover —
+     *  events landed in the tracker but nobody told the DOM. */
+    private changeListeners;
+    /**
+     * Subscribe the tracker to a bus. Returns a single disposer that
+     * unsubscribes all four handlers — callers (BrowserAuth in our
+     * case) attach this on construction and dispose on teardown.
+     */
+    attach(events: SDKEvents): () => void;
+    /**
+     * Subscribe to "snapshot may have changed" notifications. Fires
+     * synchronously after each event handler runs — typical consumer
+     * is the badge's `requestRedraw()` which coalesces multiple
+     * notifications into one rAF paint.
+     *
+     * Returns a disposer; call to unsubscribe.
+     */
+    onChange(handler: () => void): () => void;
+    private notify;
+    /** O(active+recent) — small in practice, fine on every frame. */
+    snapshot(): ActivitySnapshot;
+    private onStart;
+    private onDelta;
+    private onEnd;
+    private onError;
+    private pushRecent;
+}
+//# sourceMappingURL=activity-tracker.d.ts.map

package/dist/activity-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-tracker.d.ts","sourceRoot":"","sources":["../src/activity-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAKV,aAAa,EACb,SAAS,EACV,MAAM,aAAa,CAAC;AAYrB,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,aAAa,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB;iCAC6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,WAAW,EAAE,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnD;AAED,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,aAAa,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,EAAE,EAAE,OAAO,CAAC;IACZ,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB;6CACyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB;;;;gDAI4C;IAC5C,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;CACrC;AAOD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,OAAO,CAKb;IACF;yEACqE;IACrE,OAAO,CAAC,WAAW,CAAK;IACxB;;;;gEAI4D;IAC5D,OAAO,CAAC,eAAe,CAAyB;IAEhD;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,IAAI;IAYrC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKzC,OAAO,CAAC,MAAM;IAWd,iEAAiE;IACjE,QAAQ,IAAI,gBAAgB;IAiB5B,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,OAAO;IAkBf,OAAO,CAAC,KAAK;IAkBb,OAAO,CAAC,OAAO;IAkBf,OAAO,CAAC,UAAU;CAKnB"}

package/dist/activity-tracker.js

@@ -0,0 +1,176 @@
+/**
+ * In-memory session-scoped activity index — turns the raw event
+ * stream from `SDKEvents` into the snapshot the badge UI reads each
+ * frame: which calls are in flight, what just finished, what the
+ * running session cost is.
+ *
+ * Memory bounded:
+ *   - `active` map shrinks on every end/error (calls don't accumulate
+ *     past their settle event).
+ *   - `recent` is a bounded ring of the last RECENT_MAX completions.
+ *   - tokens/sec windows hold only `RATE_WINDOW_MS` worth of deltas;
+ *     stale samples get dropped on every push.
+ *
+ * Snapshot pattern (vs. emitting another event per change): the
+ * badge re-renders on `requestAnimationFrame` while it's open, so
+ * a pull-snapshot API matches that cadence — pushing on every
+ * delta would over-paint and cost battery on token-heavy streams.
+ */
+/** Sliding window for tokens/sec — 1.5s gives a snappy display
+ *  without jittering on every chunk arrival (most providers emit
+ *  ~5-30 deltas/s). */
+const RATE_WINDOW_MS = 1500;
+/** Cap on the recent-completion ring buffer. The popover lists the
+ *  last 5 by default but we keep a few extra so a future "show more"
+ *  UI doesn't need a refactor. */
+const RECENT_MAX = 20;
+/** Window during which a recent error keeps the LED red. 30s is
+ *  long enough to grab attention but short enough that an old
+ *  failure doesn't dominate when subsequent calls succeed. */
+const ERROR_HIGHLIGHT_MS = 30_000;
+export class ActivityTracker {
+    active = new Map();
+    recent = [];
+    session = {
+        totalCalls: 0,
+        totalCostUSD: 0,
+        errorCount: 0,
+        startedAt: Date.now(),
+    };
+    /** Track most recent error wall-clock so the LED stays red for
+     *  ERROR_HIGHLIGHT_MS even after the error scrolls out of recent. */
+    lastErrorAt = 0;
+    /** "Snapshot changed" listeners. Fired AFTER every event handler
+     *  runs (start / delta / end / error), letting UIs re-render in
+     *  push-mode instead of polling. Without this hook, the badge's
+     *  ring/LED stayed idle until the user opened the popover —
+     *  events landed in the tracker but nobody told the DOM. */
+    changeListeners = new Set();
+    /**
+     * Subscribe the tracker to a bus. Returns a single disposer that
+     * unsubscribes all four handlers — callers (BrowserAuth in our
+     * case) attach this on construction and dispose on teardown.
+     */
+    attach(events) {
+        const offs = [
+            events.on("request:start", (e) => { this.onStart(e); this.notify(); }),
+            events.on("request:streamDelta", (e) => { this.onDelta(e); this.notify(); }),
+            events.on("request:end", (e) => { this.onEnd(e); this.notify(); }),
+            events.on("request:error", (e) => { this.onError(e); this.notify(); }),
+        ];
+        return () => {
+            for (const o of offs)
+                o();
+        };
+    }
+    /**
+     * Subscribe to "snapshot may have changed" notifications. Fires
+     * synchronously after each event handler runs — typical consumer
+     * is the badge's `requestRedraw()` which coalesces multiple
+     * notifications into one rAF paint.
+     *
+     * Returns a disposer; call to unsubscribe.
+     */
+    onChange(handler) {
+        this.changeListeners.add(handler);
+        return () => this.changeListeners.delete(handler);
+    }
+    notify() {
+        for (const h of this.changeListeners) {
+            try {
+                h();
+            }
+            catch (err) {
+                // eslint-disable-next-line no-console
+                console.error("[runjobs sdk] ActivityTracker onChange listener threw:", err);
+            }
+        }
+    }
+    /** O(active+recent) — small in practice, fine on every frame. */
+    snapshot() {
+        const now = Date.now();
+        return {
+            active: Array.from(this.active.values()),
+            recent: this.recent.slice(),
+            session: { ...this.session },
+            status: now - this.lastErrorAt < ERROR_HIGHLIGHT_MS
+                ? "error"
+                : this.active.size > 0
+                    ? "active"
+                    : "idle",
+        };
+    }
+    // ─── handlers ─────────────────────────────────────────────────
+    onStart(e) {
+        this.active.set(e.id, {
+            id: e.id,
+            model: e.model,
+            capability: e.capability,
+            startedAt: e.startedAt,
+            streaming: e.streaming,
+            tokensSoFar: 0,
+            tokensPerSec: 0,
+            rateSamples: [],
+        });
+    }
+    onDelta(e) {
+        const call = this.active.get(e.id);
+        if (!call)
+            return; // delta after end — drop
+        call.tokensSoFar = e.totalTokens;
+        const now = Date.now();
+        call.rateSamples.push({ t: now, tokens: e.deltaTokens });
+        // Drop samples older than the window.
+        const cutoff = now - RATE_WINDOW_MS;
+        while (call.rateSamples.length > 0 && call.rateSamples[0].t < cutoff) {
+            call.rateSamples.shift();
+        }
+        if (call.rateSamples.length >= 2) {
+            const sumTokens = call.rateSamples.reduce((s, x) => s + x.tokens, 0);
+            const spanMs = now - call.rateSamples[0].t;
+            call.tokensPerSec = spanMs > 0 ? (sumTokens * 1000) / spanMs : 0;
+        }
+    }
+    onEnd(e) {
+        const call = this.active.get(e.id);
+        this.active.delete(e.id);
+        this.pushRecent({
+            id: e.id,
+            model: e.model,
+            capability: e.capability,
+            latencyMs: e.latencyMs,
+            totalTokens: e.totalTokens || call?.tokensSoFar || 0,
+            ...(e.costUSD !== undefined && { costUSD: e.costUSD }),
+            ...(e.finishReason !== undefined && { finishReason: e.finishReason }),
+            ok: true,
+            endedAt: Date.now(),
+        });
+        this.session.totalCalls += 1;
+        if (e.costUSD !== undefined)
+            this.session.totalCostUSD += e.costUSD;
+    }
+    onError(e) {
+        const call = this.active.get(e.id);
+        this.active.delete(e.id);
+        this.pushRecent({
+            id: e.id,
+            model: e.model,
+            capability: e.capability,
+            latencyMs: e.latencyMs,
+            totalTokens: call?.tokensSoFar || 0,
+            ok: false,
+            errorMessage: e.error.message,
+            endedAt: Date.now(),
+        });
+        this.session.totalCalls += 1;
+        this.session.errorCount += 1;
+        this.lastErrorAt = Date.now();
+    }
+    pushRecent(c) {
+        // Newest first — popover renders top-to-bottom newest→oldest.
+        this.recent.unshift(c);
+        if (this.recent.length > RECENT_MAX)
+            this.recent.length = RECENT_MAX;
+    }
+}
+//# sourceMappingURL=activity-tracker.js.map

package/dist/activity-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-tracker.js","sourceRoot":"","sources":["../src/activity-tracker.ts"],"names":[],"mappings":"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"}