@neurosquad/card-sdk 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+All notable changes to `@neurosquad/card-sdk` and to the card contract it speaks
+(`CARD_SDK_CONTRACT_VERSION`) are listed here, newest first. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the package uses
+[Semantic Versioning](https://semver.org/).
+
+Three versions matter to a card author:
+
+- **SDK / contract version** (`SDK_VERSION`, `CARD_SDK_CONTRACT_VERSION`) — the
+  headings below. New methods and events arrive in minor versions.
+- **Wire protocol** (`CARD_PROTOCOL_VERSION`, still **1**) — a card built for a
+  higher protocol is refused by an older app with `PROTOCOL_MISMATCH`.
+- **NeuroSquad app version** — the host. Feature-detect with
+  `card.host.supports('<method>')`, or set `minAppVersion` in
+  `neurosquad-card.json` when the card cannot work without a method.
+
+App versions below are the first public NeuroSquad release that has the change.
+
+## [Unreleased]
+
+### Changed (host, NeuroSquad 0.1.264)
+
+- A card whose page process dies on its own (typically the machine running out
+  of memory) is reloaded automatically instead of staying a grey rectangle; the
+  new frame starts with `launch: 'reloaded'`. After three such reloads within
+  10 minutes the card shows "The card stopped working" with **Reload**.
+  Nothing to do for authors — keep state you need across reloads in
+  `card.storage`.
+
+## [1.2.0] — 2026-10-04
+
+Host: NeuroSquad **0.1.264** or newer (`card.host.supports('agents.timeline')`).
+
+### Added
+
+- `card.agents.timeline(agentId, since, until?)` → `AgentTimeline`: one
+  arrow-connected AI agent's model requests (completion time; send time where
+  the harness's log records it; tokens; tool calls the model asked for), its
+  status as consecutive spans, and its turns — what the official Agent Pulse
+  card draws. `requestTimes` says what the log allows: `start-end`, `end` or
+  `none`. At most 2000 requests (the newest; `truncated`).
+- Types `AgentTimeline`, `AgentRequestSpan`, `AgentTurnSpan`.
+- Mock host: `agentTimeline` option and `setAgentTimeline(agentId, timeline)`.
+
+### Compatibility
+
+- Same permission and scope as `agents.usage`: `usage.read` and an arrow to an
+  AI agent. No new permission.
+- Rate limit 60 calls a minute per card.
+- An older app answers `METHOD_NOT_FOUND`.
+
+## [1.1.0] — 2026-10-04
+
+Host: NeuroSquad **0.1.264** or newer (`card.host.supports('agents.usage')`).
+
+### Added
+
+- `card.agents.usage(agentId, since, until?)` → `AgentUsage`: one
+  arrow-connected AI agent's run inside a window — model requests, tokens by
+  kind (input, output, reasoning, cache read, cache write, total), prompts,
+  working and elapsed time, cost in micro-dollars (rounded up) with
+  `costPartial`, model and provider. What the official Run Stats card shows.
+  Timing comes from the app's own status history, so it is right even while
+  the card's frame was paused.
+- Type `AgentUsage`.
+- Mock host: `agentUsage` option and `setAgentUsage(agentId, usage)`.
+- Contract types for the verified cards catalog (`VerifiedCatalog`,
+  `VerifiedEntry`, `validateVerifiedCatalog`, …) — first published here; they
+  were added to the source after the 1.0.0 package.
+
+### Changed
+
+- A token count that is not reported is `null`, never `0`: a field the
+  harness's log does not carry, a harness without a readable usage log (Amp,
+  Cursor → `usageReadable: false`), a zero cache count from the user's own model
+  server, a zero cache write outside the Anthropic API. Show it as "not
+  reported".
+- A cost of exactly 0 that a harness records for a model on the user's own
+  server means "no price": `costMicroUsd` is `null`, never $0.
+- `prompts` does not count a finished turn without a single model request (a
+  status blip, such as a pasted prompt a CLI showed as busy before it really
+  submitted).
+
+### Compatibility
+
+- Permission `usage.read` (already in 1.0; it now also unlocks this method for
+  agents connected by an arrow). Not connected → `NOT_CONNECTED`; a shell →
+  `INVALID_PARAMS`.
+- Rate limit 60 calls a minute per card.
+- An older app answers `METHOD_NOT_FOUND`. Wire protocol stays 1; cards built
+  with 1.0.0 run unchanged.
+
+### Host changes within contract 1.0 (no SDK version change)
+
+Shipped in NeuroSquad releases between 1.0.0 and 1.1.0; listed because they can
+change what a card sees.
+
+- **0.1.253** — more manifest `name` values are reserved (the Graphify plugin's
+  tool family). **0.1.230** — reserved for the Memory, Context7 and Code Graph
+  plugins. **0.1.160** — for the RTK and caveman plugins. **0.1.141** —
+  `canvas_connect`, `canvas_disconnect`, `canvas_list`. **0.1.138** —
+  `agent_set_model`, `neurosquad_models`. A manifest with such a `name` fails
+  validation.
+- **0.1.214** — `fs.*` refuses writes to more files that run code on the next
+  push or install: GitLab, Jenkins, CircleCI, Buildkite, Travis, Bitbucket,
+  Drone, AppVeyor and Azure Pipelines configs. `workspace.path` of a workspace
+  in WSL is this computer's view of it; for an SSH workspace it is `''` and
+  `fs.*` answers `UNAVAILABLE`. `usage.summary` rounds costs up to whole
+  micro-dollars, so a tiny priced cost never reads as 0. Linking a folder with
+  `neurosquad-card dev` needs developer mode on.
+- **0.1.128** — `agents.lastReply` works for every harness with a readable
+  transcript, not only Claude Code, and an agent's built-in `reply` port
+  sends the final answer for all of them.
+- **0.1.125** — the verified cards catalog (§18 of the spec): "Verified" badge
+  for cards listed at an exact commit and tree hash.
+
+## [1.0.0] — 2026-09-25
+
+Host: NeuroSquad **0.1.123** or newer. First public release.
+
+### Added
+
+- `connect()` → a typed `Card`: `card.call` / `card.on` over the whole
+  contract, plus namespaces for storage, settings, agents, terminals, ports,
+  tools for connected agents (MCP), network proxy, files, clipboard, usage
+  summary, theme, language, lifecycle and card UI (status, badge, overview,
+  attention, toasts, confirm).
+- Manifest `neurosquad-card.json` (`manifestVersion: 1`) with its JSON Schema,
+  permissions with consent text, optional permissions requested at run time.
+- React bindings (`@neurosquad/card-sdk/react`), the optional dark UI kit
+  (`ui.css`, `applyTheme()`), `createTranslator` for en/ru/zh.
+- Mock host for tests (`@neurosquad/card-sdk/testing`).
+- CLI `neurosquad-card`: `create` (vanilla and React templates), `validate`,
+  `pack`, `dev` (live reload into the running app).
+
+[Unreleased]: https://docs.neurosquad.ai/en/card-sdk/changelog
+[1.2.0]: https://docs.neurosquad.ai/en/card-sdk/changelog
+[1.1.0]: https://docs.neurosquad.ai/en/card-sdk/changelog
+[1.0.0]: https://www.npmjs.com/package/@neurosquad/card-sdk/v/1.0.0

package/README.md

@@ -180,7 +180,7 @@ subscribed with the host automatically while a listener exists.
 | `card.ui` | `toast`, `confirm` → boolean, `setMenu([{ id, label, icon, onSelect }])`, `onMenu` |
 | `card.storage` | `get(key, fallback)`, `set`, `delete`, `keys(prefix)`, `clear`, `usage`; `card.storage.package.*` shared by every card of the package; `onChange` |
 | `card.settings` | `values`, `value(key)`, `hasSecret(key)`, `set(values)`, `open()`, `onChange` |
-| `card.agents` | `list`, `get`, `readScreen`, `lastReply`, `prompt(id, text, { whenBusy, submit })`, `onStatus`, `onTurn`, `onChanged`, `onOutput(ids, handler)` |
+| `card.agents` | `list`, `get`, `readScreen`, `lastReply`, `prompt(id, text, { whenBusy, submit })`, `usage(id, since, until?)`, `timeline(id, since, until?)`, `onStatus`, `onTurn`, `onChanged`, `onOutput(ids, handler)` |
 | `card.terminals` | `run(id, command)` → `{ exitCode, output }`, `write(id, text, { submit })` |
 | `card.ports` | `inputs`, `outputs`, `peers`, `emit(output, data)`, `send`, `request`, `read`, `onMessage`, `onRequest(input, handler)`, `onPeersChanged` |
 | `card.tools` | `handle(name, handler)`, `setEnabled` |
@@ -238,6 +238,37 @@ await requestPermissions(card, ...needed.filter((id) => id !== null)) // never t
 await card.ports.emit('summary', text)
 ```
 
+### One agent's run: `card.agents.usage`
+
+Since SDK 1.1 (NeuroSquad 0.1.264): the numbers of one AI agent connected to the
+card by an arrow, inside a time window — model requests and tokens from the
+harness's own log, prompts and working time from the app's status history (so
+they are right for time your frame was off screen). Needs `usage.read`.
+
+```ts
+if (await card.host.supports('agents.usage')) {
+  const run = await card.agents.usage(agentId, startedAt) // until = now
+  run.requests // model requests (API round-trips)
+  run.inputTokens, run.outputTokens, run.cacheReadTokens, run.cacheWriteTokens, run.totalTokens
+  run.prompts, run.workingMs, run.elapsedMs, run.costMicroUsd
+}
+```
+
+A `null` token field means **not reported** by that harness or provider (no
+such field in its log, a local server that sends no cache counts, the OpenAI
+APIs' missing cache writes) — show it as such, never as 0. The official
+[Run Stats](https://github.com/glmn-ai/neurosquad-cards/tree/main/official-cards/run-stats)
+card is built on it.
+
+### Requests on a timeline: `card.agents.timeline`
+
+Since SDK 1.2 (NeuroSquad 0.1.264): the same arrow-connected agent's model
+requests one by one — completion time, send time where the harness's log has
+one (`requestTimes: 'start-end'`, otherwise `'end'`), tokens, tool calls — plus
+its status as consecutive spans and its turns (prompt → finish). Needs
+`usage.read`. The official [Agent Pulse](https://github.com/glmn-ai/neurosquad-cards/tree/main/official-cards/agent-pulse)
+card draws it as swimlanes.
+
 ### Network
 
 ```ts
@@ -366,7 +397,7 @@ permissions, visibility, optionally rate limits) and records everything:
 `calls`, `storage`, `deliveries`, `prompts`, `logs`, `toasts`, `chrome`
 (title/status/badge/overview/menu). Drive the card with `setVisibility`,
 `setLanguage`, `setSettings`, `setSecret`, `sendPortMessage`, `requestPort`,
-`callTool`, `setAgentStatus`, `agentOutput`, `suspend`, `touchFile`. The same
+`callTool`, `setAgentStatus`, `setAgentUsage`, `setAgentTimeline`, `agentOutput`, `suspend`, `touchFile`. The same
 mock powers the templates' browser preview when the page is opened outside the
 app.
 
@@ -378,7 +409,7 @@ that the value fits the input's schema; `permissions.request` fails with
 `NOT_VISIBLE` off screen; `fs.write` refuses the protected paths above. Options:
 `settings` (initial values), `secrets` (`{ key: value }` for `secret`
 settings — `{{secret:key}}` headers are filled, a missing one is
-`INVALID_PARAMS`), `enforceRateLimits` (per-method throttles; off by default so
+`INVALID_PARAMS`), `agentUsage` / `agentTimeline` (what `agents.usage` / `agents.timeline` return per agent, or a function of the call), `enforceRateLimits` (per-method throttles; off by default so
 tests stay deterministic).
 
 **Test in the app too.** The mock runs in your page, not in the sandboxed
@@ -426,6 +457,10 @@ New methods and events arrive within a protocol version; check with
 `card.host.supports('method.name')`. A card built for a newer protocol is
 refused by an older app with `PROTOCOL_MISMATCH`.
 
+What changed in each version — new methods, the NeuroSquad version they need,
+permissions, migration notes — is in [CHANGELOG.md](./CHANGELOG.md) (also on
+the docs site: https://docs.neurosquad.ai/en/card-sdk/changelog).
+
 ## License
 
 MIT

package/dist/card-sdk.js

@@ -1,8 +1,8 @@
-/*! @neurosquad/card-sdk 1.0.0 | MIT */
+/*! @neurosquad/card-sdk 1.2.0 | MIT */
 
 // src/contract/version.ts
 var CARD_PROTOCOL_VERSION = 1;
-var CARD_SDK_CONTRACT_VERSION = "1.0.0";
+var CARD_SDK_CONTRACT_VERSION = "1.2.0";
 var MANIFEST_FILE = "neurosquad-card.json";
 var MANIFEST_VERSION = 1;
 var CARD_SCHEME = "nscard";
@@ -1756,7 +1756,10 @@ var PROTECTED_DIRS = /* @__PURE__ */ new Set([
   ".kilocode",
   ".windsurf",
   ".continue",
-  ".devcontainer"
+  ".devcontainer",
+  // CI that runs whatever the config says on the next push.
+  ".circleci",
+  ".buildkite"
 ]);
 var PROTECTED_FILES = /* @__PURE__ */ new Set([
   ".git",
@@ -1776,7 +1779,15 @@ var PROTECTED_FILES = /* @__PURE__ */ new Set([
   ".npmrc",
   ".yarnrc",
   ".yarnrc.yml",
-  ".pnpmfile.cjs"
+  ".pnpmfile.cjs",
+  ".gitlab-ci.yml",
+  "azure-pipelines.yml",
+  "jenkinsfile",
+  ".travis.yml",
+  "bitbucket-pipelines.yml",
+  ".drone.yml",
+  "appveyor.yml",
+  ".appveyor.yml"
 ]);
 function protectedWriteReason(normalized) {
   if (normalized === "") return null;
@@ -2036,11 +2047,19 @@ var RESERVED_NAMES = /* @__PURE__ */ new Set([
   "squad",
   "mcp",
   "skill",
+  "rtk",
+  "caveman",
+  "mem0",
+  "codegraph",
+  "graphify",
+  "context7",
+  "memory",
   "official"
 ]);
 var BUILTIN_MCP_TOOL_NAMES = [
   "agent_read",
   "agent_send",
+  "agent_set_model",
   "agent_wait",
   "browser_click",
   "browser_history",
@@ -2049,14 +2068,47 @@ var BUILTIN_MCP_TOOL_NAMES = [
   "browser_screenshot",
   "browser_snapshot",
   "browser_type",
+  "canvas_connect",
+  "canvas_disconnect",
+  "canvas_list",
   "canvas_remove_card",
   "canvas_spawn_card",
+  "codegraph_check_index_coverage",
+  "codegraph_detect_changes",
+  "codegraph_get_architecture",
+  "codegraph_get_code_snippet",
+  "codegraph_get_file_outline",
+  "codegraph_get_graph_schema",
+  "codegraph_index_status",
+  "codegraph_query_graph",
+  "codegraph_reindex",
+  "codegraph_search_code",
+  "codegraph_search_graph",
+  "codegraph_trace_path",
+  "context7_query_docs",
+  "context7_resolve_library_id",
+  "graphify_affected",
+  "graphify_community",
+  "graphify_god_nodes",
+  "graphify_neighbors",
+  "graphify_node",
+  "graphify_path",
+  "graphify_query",
+  "graphify_reindex",
+  "graphify_stats",
   "kanban_add",
   "kanban_move",
   "kanban_read",
   "kanban_remove",
   "kanban_write",
+  "memory_add",
+  "memory_delete",
+  "memory_get",
+  "memory_list",
+  "memory_search",
+  "memory_update",
   "neurosquad_connections",
+  "neurosquad_models",
   "note_append",
   "note_read",
   "note_write",
@@ -2593,6 +2645,13 @@ var CARD_VISIBILITIES = [
   "overview",
   "hidden"
 ];
+var CARD_AGENT_STATUSES = [
+  "working",
+  "needs-input",
+  "finished",
+  "idle",
+  "exited"
+];
 var EVENT_TOPICS = [
   "agents.status",
   "agents.turn",
@@ -3011,6 +3070,32 @@ var METHOD_SPECS = {
     permission: "usage.read",
     params: obj({ period: { enum: ["today", "7d", "30d"] } }, ["period"]),
     perMinute: 6
+  },
+  // Contract 1.1. Only agents connected to the card by an arrow (NOT_CONNECTED otherwise).
+  "agents.usage": {
+    permission: "usage.read",
+    params: obj(
+      {
+        agentId: ID,
+        since: { type: "integer", minimum: 0, maximum: 864e10 },
+        until: { type: "integer", minimum: 0, maximum: 864e10 }
+      },
+      ["agentId", "since"]
+    ),
+    perMinute: 60
+  },
+  // Contract 1.2. Same scope as agents.usage: an arrow-connected AI agent.
+  "agents.timeline": {
+    permission: "usage.read",
+    params: obj(
+      {
+        agentId: ID,
+        since: { type: "integer", minimum: 0, maximum: 864e10 },
+        until: { type: "integer", minimum: 0, maximum: 864e10 }
+      },
+      ["agentId", "since"]
+    ),
+    perMinute: 60
   }
 };
 var CARD_METHOD_NAMES = Object.keys(METHOD_SPECS);
@@ -3030,7 +3115,7 @@ function permissionStates(declared, granted, resolveReason) {
 }
 
 // src/version.ts
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "1.2.0";
 
 // src/client/base64.ts
 function bytesToBase64(bytes) {
@@ -4434,6 +4519,36 @@ var CardAgents = class {
   lastReply(agentId) {
     return this.card.call("agents.lastReply", { agentId });
   }
+  /**
+   * One connected AI agent's run since `since` (epoch ms) — `usage.read`,
+   * contract 1.1: check `card.host.supports('agents.usage')` first. Model
+   * requests and tokens come from the harness's own log (the app's Usage
+   * data), prompts and working time from the app's status history, so the
+   * numbers are right even for time the card was off screen. A `null`
+   * token field is not reported by that harness or provider — show it as
+   * such, never as 0.
+   */
+  usage(agentId, since, until) {
+    return this.card.call("agents.usage", {
+      agentId,
+      since,
+      ...until !== void 0 ? { until } : {}
+    });
+  }
+  /**
+   * One connected AI agent's model requests and statuses since `since` —
+   * `usage.read`, contract 1.2: check `card.host.supports('agents.timeline')`.
+   * Each request has its completion time, its send time where the harness's
+   * log records one (`requestTimes: 'start-end'`), tokens and tool calls;
+   * statuses are consecutive spans and turns carry prompt / finish times.
+   */
+  timeline(agentId, since, until) {
+    return this.card.call("agents.timeline", {
+      agentId,
+      since,
+      ...until !== void 0 ? { until } : {}
+    });
+  }
   /**
    * Sends a prompt to a connected AI agent (`agents.prompt`, 6 per minute).
    * While the agent works it is queued (`whenBusy: 'queue'`, default),
@@ -5131,6 +5246,7 @@ export {
   BUILTIN_CARD_PORTS,
   BUILTIN_MCP_TOOL_NAMES,
   BUILTIN_PEER_KINDS,
+  CARD_AGENT_STATUSES,
   CARD_ERROR_CODES,
   CARD_EVENT_NAMES,
   CARD_HOST_ID_RE,

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-/*! @neurosquad/card-sdk 1.0.0 | MIT */
+/*! @neurosquad/card-sdk 1.2.0 | MIT */
 
 // src/version.ts
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "1.2.0";
 
 // src/cli/create.ts
 import {
@@ -1421,11 +1421,19 @@ var RESERVED_NAMES = /* @__PURE__ */ new Set([
   "squad",
   "mcp",
   "skill",
+  "rtk",
+  "caveman",
+  "mem0",
+  "codegraph",
+  "graphify",
+  "context7",
+  "memory",
   "official"
 ]);
 var BUILTIN_MCP_TOOL_NAMES = [
   "agent_read",
   "agent_send",
+  "agent_set_model",
   "agent_wait",
   "browser_click",
   "browser_history",
@@ -1434,14 +1442,47 @@ var BUILTIN_MCP_TOOL_NAMES = [
   "browser_screenshot",
   "browser_snapshot",
   "browser_type",
+  "canvas_connect",
+  "canvas_disconnect",
+  "canvas_list",
   "canvas_remove_card",
   "canvas_spawn_card",
+  "codegraph_check_index_coverage",
+  "codegraph_detect_changes",
+  "codegraph_get_architecture",
+  "codegraph_get_code_snippet",
+  "codegraph_get_file_outline",
+  "codegraph_get_graph_schema",
+  "codegraph_index_status",
+  "codegraph_query_graph",
+  "codegraph_reindex",
+  "codegraph_search_code",
+  "codegraph_search_graph",
+  "codegraph_trace_path",
+  "context7_query_docs",
+  "context7_resolve_library_id",
+  "graphify_affected",
+  "graphify_community",
+  "graphify_god_nodes",
+  "graphify_neighbors",
+  "graphify_node",
+  "graphify_path",
+  "graphify_query",
+  "graphify_reindex",
+  "graphify_stats",
   "kanban_add",
   "kanban_move",
   "kanban_read",
   "kanban_remove",
   "kanban_write",
+  "memory_add",
+  "memory_delete",
+  "memory_get",
+  "memory_list",
+  "memory_search",
+  "memory_update",
   "neurosquad_connections",
+  "neurosquad_models",
   "note_append",
   "note_read",
   "note_write",

package/dist/react.js

@@ -1,4 +1,4 @@
-/*! @neurosquad/card-sdk 1.0.0 | MIT */
+/*! @neurosquad/card-sdk 1.2.0 | MIT */
 
 // src/react/index.tsx
 import {

package/dist/testing.js

@@ -1,4 +1,4 @@
-/*! @neurosquad/card-sdk 1.0.0 | MIT */
+/*! @neurosquad/card-sdk 1.2.0 | MIT */
 
 // src/testing/mockHost.ts
 import {
@@ -422,6 +422,18 @@ var MockHost = class {
     this.emit("tools.cancel", { callId });
     pending?.reject(new HostError("USER_CANCELLED", "cancelled"));
   }
+  /** What `agents.timeline` returns for this agent from now on (merged over an empty timeline). */
+  setAgentTimeline(agentId, timeline) {
+    const current = this.options.agentTimeline;
+    const table = typeof current === "object" && current !== null ? current : {};
+    this.options.agentTimeline = { ...table, [agentId]: timeline };
+  }
+  /** What `agents.usage` returns for this agent from now on (merged over an all-zero run). */
+  setAgentUsage(agentId, usage) {
+    const current = this.options.agentUsage;
+    const table = typeof current === "object" && current !== null ? current : {};
+    this.options.agentUsage = { ...table, [agentId]: usage };
+  }
   /**
    * Changes an agent's status; the card gets `agents.status` if subscribed,
    * and `agents.turn` by the app's rule: `start` on entering `working`,
@@ -854,6 +866,64 @@ var MockHost = class {
       case "clipboard.writeText":
         this.clipboard.push(str("text"));
         return void 0;
+      case "agents.usage": {
+        const agent = this.connectedAgent(str("agentId"));
+        if (agent.kind !== "ai") fail("INVALID_PARAMS", `${agent.name} is not an AI agent`);
+        const since = p["since"];
+        const until = p["until"] ?? Date.now();
+        if (since > until) fail("INVALID_PARAMS", '"since" is after "until"');
+        const source = this.options.agentUsage;
+        const given = typeof source === "function" ? source(agent.id, since, until) : source?.[agent.id] ?? {};
+        const base = {
+          agentId: agent.id,
+          harness: agent.harness,
+          since,
+          until,
+          status: agent.status,
+          usageReadable: true,
+          requests: 0,
+          inputTokens: 0,
+          outputTokens: 0,
+          cacheReadTokens: 0,
+          cacheWriteTokens: 0,
+          reasoningTokens: 0,
+          totalTokens: 0,
+          costMicroUsd: null,
+          costPartial: false,
+          ...agent.model ? { model: agent.model } : {},
+          prompts: 0,
+          workingMs: 0,
+          firstPromptAt: null,
+          lastFinishedAt: null,
+          elapsedMs: null,
+          timingComplete: true,
+          scannedAt: Date.now()
+        };
+        return { ...base, ...given };
+      }
+      case "agents.timeline": {
+        const agent = this.connectedAgent(str("agentId"));
+        if (agent.kind !== "ai") fail("INVALID_PARAMS", `${agent.name} is not an AI agent`);
+        const since = p["since"];
+        const until = p["until"] ?? Date.now();
+        if (since > until) fail("INVALID_PARAMS", '"since" is after "until"');
+        const source = this.options.agentTimeline;
+        const given = typeof source === "function" ? source(agent.id, since, until) : source?.[agent.id] ?? {};
+        const base = {
+          agentId: agent.id,
+          harness: agent.harness,
+          since,
+          until,
+          usageReadable: true,
+          requestTimes: "start-end",
+          requests: [],
+          truncated: false,
+          statuses: [{ status: agent.status, from: since, to: until }],
+          turns: [],
+          scannedAt: Date.now()
+        };
+        return { ...base, ...given };
+      }
       case "usage.summary":
         return this.options.usage ?? {
           period: str("period"),

package/dist/types/client/card.d.ts

@@ -1,4 +1,4 @@
-import { type AgentInfo, type CardEventName, type CardEvents, type CardInstanceInfo, type CardMethodName, type CardSize, type CardTone, type CardVisibility, type EventTopic, type FsEntry, type FsStat, type HostContext, type HostIconName, type I18nSnapshot, type JsonValue, type MenuItem, type MethodParams, type MethodResult, type OverviewContent, type PeerInfo, type PermissionId, type PermissionState, type PortInfo, type SettingsSnapshot, type SettingValue, type ThemeSnapshot, type ToolResultPayload, type UsageSummary, type WorkspaceInfo } from '../contract/index.js';
+import { type AgentInfo, type AgentTimeline, type AgentUsage, type CardEventName, type CardEvents, type CardInstanceInfo, type CardMethodName, type CardSize, type CardTone, type CardVisibility, type EventTopic, type FsEntry, type FsStat, type HostContext, type HostIconName, type I18nSnapshot, type JsonValue, type MenuItem, type MethodParams, type MethodResult, type OverviewContent, type PeerInfo, type PermissionId, type PermissionState, type PortInfo, type SettingsSnapshot, type SettingValue, type ThemeSnapshot, type ToolResultPayload, type UsageSummary, type WorkspaceInfo } from '../contract/index.js';
 import type { CallOptions, Channel } from './channel.js';
 import { CardResponse, ChunkQueue, type CardFetchInit } from './net.js';
 import { type ThemeTarget } from './theme.js';
@@ -415,6 +415,24 @@ export declare class CardAgents {
         text: string | null;
         at: number | null;
     }>;
+    /**
+     * One connected AI agent's run since `since` (epoch ms) — `usage.read`,
+     * contract 1.1: check `card.host.supports('agents.usage')` first. Model
+     * requests and tokens come from the harness's own log (the app's Usage
+     * data), prompts and working time from the app's status history, so the
+     * numbers are right even for time the card was off screen. A `null`
+     * token field is not reported by that harness or provider — show it as
+     * such, never as 0.
+     */
+    usage(agentId: string, since: number, until?: number): Promise<AgentUsage>;
+    /**
+     * One connected AI agent's model requests and statuses since `since` —
+     * `usage.read`, contract 1.2: check `card.host.supports('agents.timeline')`.
+     * Each request has its completion time, its send time where the harness's
+     * log records one (`requestTimes: 'start-end'`), tokens and tool calls;
+     * statuses are consecutive spans and turns carry prompt / finish times.
+     */
+    timeline(agentId: string, since: number, until?: number): Promise<AgentTimeline>;
     /**
      * Sends a prompt to a connected AI agent (`agents.prompt`, 6 per minute).
      * While the agent works it is queued (`whenBusy: 'queue'`, default),

package/dist/types/contract/api.d.ts

@@ -17,6 +17,8 @@ export type CardVisibility =
  | 'hidden';
 export declare const CARD_VISIBILITIES: readonly CardVisibility[];
 export type AgentStatus = 'working' | 'needs-input' | 'finished' | 'idle' | 'exited';
+/** Every AgentStatus. Append only: main persists statuses by their index here. */
+export declare const CARD_AGENT_STATUSES: readonly AgentStatus[];
 export interface CardInstanceInfo {
     /** The card's id on the canvas (the Agent record id). */
     instanceId: string;
@@ -216,6 +218,119 @@ export interface UsageSummary {
     /** Some rows had no price and are not in the total. */
     partial: boolean;
 }
+/**
+ * One agent's run inside a time window — `agents.usage` (spec §8.6.1). The
+ * token numbers are the model requests the harness itself logged (the Usage
+ * section's data), the timing comes from the app's status history.
+ *
+ * A token field is `null` when it is **not reported**: the harness's log has
+ * no such field, or the provider sends none (a local or custom server that
+ * reports no cache, the OpenAI APIs that have no cache writes) — never a 0
+ * that would read as a measurement. Every number is an integer.
+ */
+export interface AgentUsage {
+    agentId: string;
+    harness: string;
+    /** The window: epoch ms, `since` inclusive. `until` is now unless the call gave one. */
+    since: number;
+    until: number;
+    /** The agent's status at `until`, as far as the app's history knows. */
+    status: AgentStatus;
+    /** False when the app reads no usage log for this harness (Amp, Cursor): every token field is null. */
+    usageReadable: boolean;
+    /**
+     * Model requests (API round-trips) the harness logged in the window. Null
+     * when its log keeps running totals rather than requests (Hermes, Factory
+     * Droid) or when usage is not readable.
+     */
+    requests: number | null;
+    /** Uncached input (prompt) tokens. */
+    inputTokens: number | null;
+    /** Output tokens, reasoning included. */
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+    /** The reasoning part of `outputTokens`. */
+    reasoningTokens: number | null;
+    /** input + output + cache read + cache write (the reported ones). */
+    totalTokens: number | null;
+    /** Micro-dollars, rounded up; null when no request in the window has a known price. */
+    costMicroUsd: number | null;
+    /** Some requests had no known price and are not in `costMicroUsd`. */
+    costPartial: boolean;
+    /** The model of the newest request in the window (else the agent's configured one). */
+    model?: string;
+    /** Who served it: `anthropic`, `openai`, `openrouter`, a custom provider's name… */
+    provider?: string;
+    /** Turns the agent was given (a permission answer continues the same turn). */
+    prompts: number;
+    /** Time spent working inside the window (waiting on the user excluded). */
+    workingMs: number;
+    firstPromptAt: number | null;
+    lastFinishedAt: number | null;
+    /** First prompt → latest finish (→ `until` while a turn is under way); null before the first prompt. */
+    elapsedMs: number | null;
+    /**
+     * False when the app's status history starts after `since` (the agent or
+     * the app was started later, or old history was trimmed): the timing counts
+     * only what the app saw.
+     */
+    timingComplete: boolean;
+    /** When the usage logs were last read (epoch ms). */
+    scannedAt: number;
+}
+/** One model request on an agent's timeline (`agents.timeline`). */
+export interface AgentRequestSpan {
+    /** When the response completed (epoch ms) — always known. */
+    endedAt: number;
+    /** When the request was sent; null when the harness's log does not say (`AgentTimeline.requestTimes`). */
+    startedAt: number | null;
+    model?: string;
+    /** Same "not reported" rules as AgentUsage, per request. */
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+    /** Tool calls the model asked for in this response, in order (where the log names them). */
+    tools?: string[];
+}
+/** A turn (a prompt and what the agent did with it) on the timeline. */
+export interface AgentTurnSpan {
+    start: number;
+    /** Null while under way. */
+    end: number | null;
+    endedAs?: AgentStatus;
+    /** False for a turn that ended without one model request (a status blip; not a prompt). */
+    counted: boolean;
+}
+/**
+ * One connected agent's requests and statuses inside a window —
+ * `agents.timeline` (spec §8.6.2): every model request with its start, end,
+ * tokens and tool calls (from the harness's own log), the agent's status as
+ * consecutive spans and its turns (from the app's status history).
+ */
+export interface AgentTimeline {
+    agentId: string;
+    harness: string;
+    since: number;
+    until: number;
+    usageReadable: boolean;
+    /**
+     * `start-end`: requests carry their send time (bars); `end`: completion
+     * times only (ticks); `none`: no readable request log.
+     */
+    requestTimes: 'start-end' | 'end' | 'none';
+    /** Oldest first; at most 2000 (the newest are kept and `truncated` is set). */
+    requests: AgentRequestSpan[];
+    truncated: boolean;
+    statuses: {
+        status: AgentStatus;
+        from: number;
+        to: number;
+    }[];
+    turns: AgentTurnSpan[];
+    scannedAt: number;
+}
 export type EventTopic = 'agents.status' | 'agents.turn' | 'agents.changed' | 'agents.output' | 'storage.changed';
 export declare const EVENT_TOPICS: readonly EventTopic[];
 /** Permission each subscribable topic needs. */
@@ -686,6 +801,24 @@ export interface CardMethods {
         };
         result: UsageSummary;
     };
+    /** Added within protocol 1 (contract 1.1): check `card.host.supports('agents.usage')`. */
+    'agents.usage': {
+        params: {
+            agentId: string;
+            since: number;
+            until?: number;
+        };
+        result: AgentUsage;
+    };
+    /** Added within protocol 1 (contract 1.2): check `card.host.supports('agents.timeline')`. */
+    'agents.timeline': {
+        params: {
+            agentId: string;
+            since: number;
+            until?: number;
+        };
+        result: AgentTimeline;
+    };
 }
 export type CardMethodName = keyof CardMethods;
 export type MethodParams<M extends CardMethodName> = CardMethods[M]['params'];

package/dist/types/contract/source.d.ts

@@ -96,7 +96,8 @@ export declare function isGitInternalPath(normalized: string): boolean;
  * agents or developer tools run commands without a build step (MC-10): agent
  * hooks and MCP configs (`.claude/`, `.mcp.json`, …), agent instructions
  * (`CLAUDE.md`, `AGENTS.md`, …: persistent prompt injection), editor tasks
- * (`.vscode/`), git hooks managers (`.husky/`), CI (`.github/workflows/`),
+ * (`.vscode/`), git hooks managers (`.husky/`), CI (`.github/workflows/`,
+ * `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/`, …),
  * direnv and package-manager rc files. Case-insensitive.
  */
 export declare function protectedWriteReason(normalized: string): string | null;

package/dist/types/contract/verified.d.ts

@@ -0,0 +1,136 @@
+import type { CardLanguage } from './localized.js';
+import { type PermissionId } from './permissions.js';
+export declare const VERIFIED_SCHEMA_VERSION = 1;
+/** Where the catalog lives (a public repository of the official organization). */
+export declare const VERIFIED_REPO: {
+    owner: string;
+    repo: string;
+    file: string;
+};
+export declare const VERIFIED_CATEGORIES: readonly ["agents", "productivity", "dev-tools", "data", "integrations", "fun", "other"];
+export type VerifiedCategory = (typeof VERIFIED_CATEGORIES)[number];
+export declare const VERIFIED_LIMITS: {
+    readonly fileBytes: number;
+    readonly entries: 5000;
+    readonly id: 64;
+    readonly name: 80;
+    readonly description: 600;
+    readonly notes: 1000;
+    readonly author: 100;
+    readonly reviewer: 100;
+    readonly license: 64;
+    readonly url: 500;
+    readonly version: 64;
+    readonly tag: 32;
+    readonly tags: 16;
+    readonly hosts: 32;
+    readonly screenshots: 8;
+    /** How many skipped entries are reported (the rest are only counted). */
+    readonly reportedSkips: 50;
+};
+/** Text in the app's three languages; `en` is required and the fallback. */
+export type VerifiedText = {
+    en: string;
+} & Partial<Record<Exclude<CardLanguage, 'en'>, string>>;
+export interface VerifiedEntry {
+    /** Catalog slug, unique: `[a-z0-9-]{2,64}`. */
+    id: string;
+    /** The package's manifest `name` (checked against the downloaded manifest at install). */
+    packageId: string;
+    name: VerifiedText;
+    description: VerifiedText;
+    author: {
+        name: string;
+        github?: string;
+    };
+    /** `owner/repo`, lowercased (GitHub names are case-insensitive). */
+    repo: string;
+    /** Package folder inside the repository (POSIX, case kept); absent = the root. */
+    path?: string;
+    /** Manifest version that was reviewed. */
+    version: string;
+    /** The reviewed commit (40 hex). */
+    commit: string;
+    /** sha256 hex of the package folder at that commit (the installer's tree hash). */
+    treeHash: string;
+    permissions: PermissionId[];
+    optionalPermissions: PermissionId[];
+    networkHosts: string[];
+    tags: string[];
+    category: VerifiedCategory;
+    license: string;
+    homepage?: string;
+    /** Paths inside the package. */
+    icon?: string;
+    screenshots: string[];
+    minAppVersion?: string;
+    /** Informational: the entry says it is the team's own card (the Official badge is still earned from GitHub). */
+    official: boolean;
+    /** `YYYY-MM-DD` or an ISO date-time. */
+    verifiedAt: string;
+    reviewer: string;
+    notes?: VerifiedText;
+}
+export interface VerifiedCatalog {
+    schemaVersion: 1;
+    updatedAt?: string;
+    cards: VerifiedEntry[];
+}
+export interface VerifiedSkip {
+    index: number;
+    id?: string;
+    reason: string;
+}
+export type VerifiedParseResult = {
+    ok: true;
+    catalog: VerifiedCatalog;
+    skipped: VerifiedSkip[];
+    skippedCount: number;
+} | {
+    ok: false;
+    code: 'too-large' | 'not-json' | 'bad-shape' | 'unsupported-version';
+    error: string;
+};
+/** Removes control, bidi and invisible characters and trims. */
+export declare function cleanVerifiedText(text: string, multiline?: boolean): string;
+/**
+ * Validates a parsed `verified.json`. Invalid entries, a second entry with
+ * the same id and a second entry for the same source (repo + path) are
+ * skipped; the rest is kept.
+ */
+export declare function validateVerifiedCatalog(raw: unknown): VerifiedParseResult;
+/** Parses the file's text (size-checked) and validates it. */
+export declare function parseVerifiedText(textValue: string): VerifiedParseResult;
+/** `owner/repo[/path]` — owner and repo lowercased, the path as written. */
+export declare function verifiedSourceKey(repo: string, path?: string): string;
+/** The catalog entry for a GitHub package source, if any. */
+export declare function findVerifiedEntry(entries: readonly VerifiedEntry[], source: {
+    owner: string;
+    repo: string;
+    subdir?: string;
+}): VerifiedEntry | undefined;
+/**
+ * How an installed package relates to its catalog entry:
+ * - `verified`: same commit and the installed files hash to the reviewed tree hash
+ * - `mismatch`: same commit, different files (never shown as verified)
+ * - `update`: the catalog points at a newer version
+ * - `other-version`: another commit that is not newer (e.g. a branch head)
+ */
+export type VerifiedStatus = 'verified' | 'mismatch' | 'update' | 'other-version';
+export declare function verifiedStatusFor(entry: VerifiedEntry, installed: {
+    commit: string | null;
+    treeHash: string;
+    version: string;
+}): VerifiedStatus;
+/** What "Install" resolves: the entry's repo and folder pinned to the reviewed commit. */
+export declare function verifiedInstallInput(entry: VerifiedEntry): string;
+/** SemVer precedence of the release part (pre-release sorts before the release). */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Local search: every word of the query must appear somewhere (names in all
+ * three languages, descriptions, tags, author); entries whose name matches
+ * come first, otherwise the catalog order is kept.
+ */
+export declare function searchVerified(entries: readonly VerifiedEntry[], query: string, category?: VerifiedCategory | null): VerifiedEntry[];
+/** The entry's text in `language`, falling back to English. */
+export declare function verifiedText(value: VerifiedText | undefined, language: CardLanguage): string;

package/dist/types/contract/version.d.ts

@@ -1,7 +1,7 @@
 /** Major version of the wire protocol. A card built for a higher one is refused with PROTOCOL_MISMATCH. */
 export declare const CARD_PROTOCOL_VERSION = 1;
 /** Version of this contract (and of `@neurosquad/card-sdk`'s protocol layer). */
-export declare const CARD_SDK_CONTRACT_VERSION = "1.0.0";
+export declare const CARD_SDK_CONTRACT_VERSION = "1.2.0";
 /** The manifest at the root of every card package. */
 export declare const MANIFEST_FILE = "neurosquad-card.json";
 /** `manifestVersion` this app reads. */

package/dist/types/testing/mockHost.d.ts

@@ -1,4 +1,4 @@
-import { type AgentInfo, type CardEvents, type CardEventName, type CardLanguage, type CardManifest, type CardMethodName, type CardSize, type CardVisibility, type EventTopic, type HostContext, type JsonValue, type MethodParams, type MethodResult, type NormalizedManifest, type PeerInfo, type PermissionId, type PortInfo, type SettingValue, type ThemeSnapshot, type ToolResultPayload, type UsageSummary, type Card, type ConnectOptions } from '../index.js';
+import { type AgentInfo, type AgentTimeline, type AgentUsage, type CardEvents, type CardEventName, type CardLanguage, type CardManifest, type CardMethodName, type CardSize, type CardVisibility, type EventTopic, type HostContext, type JsonValue, type MethodParams, type MethodResult, type NormalizedManifest, type PeerInfo, type PermissionId, type PortInfo, type SettingValue, type ThemeSnapshot, type ToolResultPayload, type UsageSummary, type Card, type ConnectOptions } from '../index.js';
 /** A peer card in the mock: its description plus optional behaviour. */
 export interface MockPeer extends PeerInfo {
     /** Retained output values (`ports.read`). */
@@ -66,6 +66,13 @@ export interface MockHostOptions {
     enforceRateLimits?: boolean;
     /** Usage summary for `usage.summary`. */
     usage?: UsageSummary;
+    /**
+     * What `agents.usage` returns per agent id (merged over an all-zero run of
+     * that agent), or a function of the call. Change it later with `setAgentUsage`.
+     */
+    /** What `agents.timeline` returns per agent id (merged over an empty timeline), or a function of the call. */
+    agentTimeline?: Record<string, Partial<AgentTimeline>> | ((agentId: string, since: number, until: number) => Partial<AgentTimeline>);
+    agentUsage?: Record<string, Partial<AgentUsage>> | ((agentId: string, since: number, until: number) => Partial<AgentUsage>);
     /**
      * Initial setting values (as if the user had saved them in the host form).
      * Same as calling `setSettings(values)` before `connect()`.
@@ -268,6 +275,10 @@ export declare class MockHost {
     };
     /** Cancels a running tool call (`tools.cancel`); the promise from callTool rejects. */
     cancelTool(callId: string): void;
+    /** What `agents.timeline` returns for this agent from now on (merged over an empty timeline). */
+    setAgentTimeline(agentId: string, timeline: Partial<AgentTimeline>): void;
+    /** What `agents.usage` returns for this agent from now on (merged over an all-zero run). */
+    setAgentUsage(agentId: string, usage: Partial<AgentUsage>): void;
     /**
      * Changes an agent's status; the card gets `agents.status` if subscribed,
      * and `agents.turn` by the app's rule: `start` on entering `working`,

package/dist/types/version.d.ts

@@ -1,2 +1,2 @@
 /** Version of `@neurosquad/card-sdk` (sent to the host in `host.ready`). Kept equal to package.json by a test. */
-export declare const SDK_VERSION = "1.0.0";
+export declare const SDK_VERSION = "1.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neurosquad/card-sdk",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Build custom cards for NeuroSquad: a typed client for the card API, React hooks, an optional dark UI kit and the neurosquad-card CLI (create, dev, validate, pack).",
   "license": "MIT",
   "author": "NeuroSquad",
@@ -39,13 +39,14 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "neurosquad-card": "./dist/cli.js"
+    "neurosquad-card": "dist/cli.js"
   },
   "files": [
     "dist",
     "templates",
     "schema",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {