agent-tempo 1.2.0 → 1.4.0

package/dist/utils/sdk-probe.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.findSdkPackageJson = findSdkPackageJson;
 exports.probeSdkInstall = probeSdkInstall;
+exports.readSdkPackageVersion = readSdkPackageVersion;
 /**
  * Filesystem-walk probe for an installed npm package.
  *
@@ -20,26 +22,63 @@ exports.probeSdkInstall = probeSdkInstall;
  * Used by:
  *   - `src/adapters/opencode/adapter.ts` — module-load optional-dep gate
  *   - `src/tools/recruit.ts` — recruit pre-flight check
+ *   - `src/pi/probe.ts` — Pi / Copilot-via-Pi pre-flight (presence + version floor)
  */
 const fs_1 = require("fs");
 const path_1 = require("path");
 /**
+ * Locate an installed package's `package.json` by walking `node_modules`
+ * directories upward from `fromDir`. The single source of truth for the
+ * filesystem walk — {@link probeSdkInstall} (presence) and
+ * {@link readSdkPackageVersion} (version) both build on it.
+ *
  * @param pkgName Bare specifier (e.g. `'@opencode-ai/sdk'`).
  * @param fromDir Where to start the walk. Defaults to the caller's
- *   `__dirname`-equivalent — pass an explicit value if you need to anchor
- *   the search elsewhere.
- * @returns `true` if `<dir>/node_modules/<pkgName>/package.json` exists
- *   anywhere on the walk up the filesystem.
+ *   `__dirname`-equivalent — pass an explicit value to anchor elsewhere.
+ * @returns The absolute path to `<dir>/node_modules/<pkgName>/package.json`
+ *   for the first match up the filesystem, or `null` if none is found.
  */
-function probeSdkInstall(pkgName, fromDir = __dirname) {
+function findSdkPackageJson(pkgName, fromDir = __dirname) {
     let dir = fromDir;
     while (true) {
         const candidate = (0, path_1.join)(dir, 'node_modules', pkgName, 'package.json');
         if ((0, fs_1.existsSync)(candidate))
-            return true;
+            return candidate;
         const parent = (0, path_1.dirname)(dir);
         if (parent === dir)
-            return false;
+            return null;
         dir = parent;
     }
 }
+/**
+ * @param pkgName Bare specifier (e.g. `'@opencode-ai/sdk'`).
+ * @param fromDir Where to start the walk. Defaults to the caller's
+ *   `__dirname`-equivalent — pass an explicit value if you need to anchor
+ *   the search elsewhere.
+ * @returns `true` if `<dir>/node_modules/<pkgName>/package.json` exists
+ *   anywhere on the walk up the filesystem.
+ */
+function probeSdkInstall(pkgName, fromDir = __dirname) {
+    return findSdkPackageJson(pkgName, fromDir) !== null;
+}
+/**
+ * Read an installed package's `package.json#version` via the same filesystem
+ * walk as {@link probeSdkInstall}. Returns `null` when the package isn't
+ * installed, its `package.json` is unreadable, or its `version` field is
+ * absent/non-string — callers treat `null` as "version unknown".
+ *
+ * @param pkgName Bare specifier (e.g. `'@earendil-works/pi-coding-agent'`).
+ * @param fromDir Walk start (defaults to this module's `__dirname`).
+ */
+function readSdkPackageVersion(pkgName, fromDir = __dirname) {
+    const pkgPath = findSdkPackageJson(pkgName, fromDir);
+    if (!pkgPath)
+        return null;
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(pkgPath, 'utf8'));
+        return typeof parsed.version === 'string' ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/worker.d.ts

@@ -1,5 +1,7 @@
 import { Worker } from '@temporalio/worker';
 import { Config } from './config';
+import type { IngestTokenRegistry } from './http/ingest-registry';
+import type { GateRegistry } from './http/gate-registry';
 export interface DualWorkers {
     /** Shared queue worker: workflows + delivery activities + schedule activities */
     sharedWorker: Worker;
@@ -11,4 +13,4 @@ export interface DualWorkers {
  * - Shared queue: workflows + all delivery activities (deliverCue, deliverReport, terminateSession, startRecruitedSession) + schedule activities
  * - Per-host queue: spawnProcess only (routes recruit spawns to the correct machine)
  */
-export declare function createWorkers(config: Config): Promise<DualWorkers>;
+export declare function createWorkers(config: Config, ingestTokens?: IngestTokenRegistry, gate?: GateRegistry): Promise<DualWorkers>;

package/dist/worker.js

@@ -93,13 +93,17 @@ async function getWorkflowBundle() {
  * - Shared queue: workflows + all delivery activities (deliverCue, deliverReport, terminateSession, startRecruitedSession) + schedule activities
  * - Per-host queue: spawnProcess only (routes recruit spawns to the correct machine)
  */
-async function createWorkers(config) {
+async function createWorkers(config, ingestTokens, gate) {
     const connection = await (0, connection_1.createTemporalNativeConnection)(config);
     // Create a Client connection for activities that need to interact with Temporal
     const clientConnection = await (0, connection_2.createTemporalConnection)(config);
     const client = new client_1.Client({ connection: clientConnection, namespace: config.temporalNamespace });
     const scheduleActivities = (0, schedule_fire_1.createScheduleActivities)(client);
-    const outboxActivities = (0, outbox_1.createOutboxActivities)(client, config);
+    // 3c Tier-2 — thread the daemon's shared IngestTokenRegistry into the outbox
+    // activities so the pi spawn branch can mint per-player ingest tokens and the
+    // destroy path can revoke them. Same singleton the HTTP server validates
+    // against (both run in this daemon process).
+    const outboxActivities = (0, outbox_1.createOutboxActivities)(client, config, ingestTokens, gate);
     const maestroActivities = (0, maestro_1.createMaestroActivities)(client);
     const workflowBundle = await getWorkflowBundle();
     const SHUTDOWN_GRACE_TIME = '10s';

package/dist/workflows/session.js

@@ -16,7 +16,7 @@ const attachment_math_1 = require("./attachment-math");
 const signals_1 = require("./signals");
 const validation_1 = require("../utils/validation");
 // ── Outbox Activity Proxies ──
-const { deliverCue, deliverReport, terminateSession, startRecruitedSession, releasePlayer, deliverDetach, deliverDestroy, deliverRestart } = (0, workflow_1.proxyActivities)({
+const { deliverCue, deliverReport, terminateSession, startRecruitedSession, releasePlayer, deliverDetach, deliverDestroy, deliverRestart, deliverReset } = (0, workflow_1.proxyActivities)({
     startToCloseTimeout: '30 seconds',
     retry: { maximumAttempts: 3 },
 });
@@ -117,6 +117,9 @@ async function agentSessionWorkflow(input) {
     const messages = input.messages ?? [];
     const sentMessages = input.sentMessages ?? [];
     const outbox = input.outbox ?? [];
+    // D14 — pending context-reset flag, polled + acked by the Pi extension. Single
+    // slot, latest-wins; survives continue-as-new until the extension acks it.
+    let pendingReset = input.pendingReset ?? null;
     let lastActivityTime = workflowNow().getTime();
     let lastOutboundTime = input.lastOutboundTime ?? workflowNow().getTime();
     let lastInboundRRTime = input.lastInboundRRTime ?? 0;
@@ -128,6 +131,13 @@ async function agentSessionWorkflow(input) {
     let activityCount = input.activityCount ?? 0;
     let receivedCount = input.receivedCount ?? 0;
     let sentCount = input.sentCount ?? 0;
+    // ── 3c Tier-1 — coarse activity (currentTool + context usage) ──
+    // Refreshed by the heartbeat piggyback; surfaced by `getCoarseActivityQuery`.
+    // Deliberately volatile/live — NOT carried across continueAsNew (no input
+    // field), so a fresh run reports `{currentTool:null}` until the next ~30s
+    // heartbeat repopulates it. Acceptable for coarse observability; the live,
+    // fine-grained tail is the off-wire /inner side-channel.
+    let coarseActivity = { currentTool: null };
     // ── Warm Hold + Pause State ──
     let outboxLocked = input.outboxLocked ?? false;
     let heldMessage = input.heldMessage;
@@ -308,6 +318,9 @@ async function agentSessionWorkflow(input) {
         else if (entry.type === 'release') {
             sentMessages.push({ id: entry.id, to: entry.targetPlayerId, text: '[release requested]', timestamp: entry.createdAt });
         }
+        else if (entry.type === 'reset') {
+            sentMessages.push({ id: entry.id, to: entry.targetPlayerId, text: '[reset requested]', timestamp: entry.createdAt });
+        }
         lastActivityTime = workflowNow().getTime();
         activityCount++;
         lastOutboundTime = workflowNow().getTime();
@@ -368,6 +381,29 @@ async function agentSessionWorkflow(input) {
         lastActivityTime = workflowNow().getTime();
         activityCount++;
     });
+    // ── Reset (D14) — set by deliverReset, polled + acked by the Pi extension ──
+    (0, workflow_1.setHandler)(signals_1.setPendingResetSignal, (r) => {
+        // Latest-wins; stamp requestedAt deterministically (workflowNow, not the activity's clock).
+        pendingReset = {
+            resetId: r.resetId,
+            fresh: r.fresh,
+            ...(r.reason !== undefined ? { reason: r.reason } : {}),
+            ...(r.requestedBy !== undefined ? { requestedBy: r.requestedBy } : {}),
+            requestedAt: workflowNow().toISOString(),
+        };
+        lastActivityTime = workflowNow().getTime();
+        activityCount++;
+    });
+    (0, workflow_1.setHandler)(signals_1.pendingResetQuery, () => pendingReset);
+    (0, workflow_1.setHandler)(signals_1.ackResetSignal, (resetId) => {
+        // Race-safe: only clear if the ack matches the current pending reset, so a
+        // newer reset landing during the extension's wipe isn't silently dropped.
+        if (pendingReset?.resetId === resetId) {
+            pendingReset = null;
+        }
+        lastActivityTime = workflowNow().getTime();
+        activityCount++;
+    });
     (0, workflow_1.setHandler)(signals_1.updateMetadataSignal, (update) => {
         if (update.hostname != null)
             input.metadata.hostname = update.hostname;
@@ -434,6 +470,8 @@ async function agentSessionWorkflow(input) {
             leaseMs: currentAttachment.leaseMs,
         };
     });
+    // 3c Tier-1 — surface the latest coarse activity for the snapshot fan-out.
+    (0, workflow_1.setHandler)(signals_1.getCoarseActivityQuery, () => ({ ...coarseActivity }));
     // ── Hold / Release Handlers ──
     (0, workflow_1.setHandler)(signals_1.releaseHeldSignal, () => {
         if (heldMessage) {
@@ -807,7 +845,7 @@ async function agentSessionWorkflow(input) {
      * `heartbeat` signal — extend the lease. Last-write-wins via the `attachmentId` guard;
      * heartbeats for superseded attachments are ignored.
      */
-    (0, workflow_1.setHandler)(signals_1.heartbeatSignal, ({ attachmentId }) => {
+    (0, workflow_1.setHandler)(signals_1.heartbeatSignal, ({ attachmentId, currentTool, contextTokens, contextPercent }) => {
         if (!currentAttachment || currentAttachment.attachmentId !== attachmentId)
             return;
         const now = workflowNow();
@@ -818,6 +856,16 @@ async function agentSessionWorkflow(input) {
         currentAttachment.expiresAt = new Date(now.getTime() + currentAttachment.leaseMs).toISOString();
         lastActivityTime = now.getTime();
         activityCount++;
+        // 3c Tier-1 — refresh coarse activity from the heartbeat piggyback. Field-wise
+        // merge: only fields the sender included are updated. `currentTool` can be a
+        // legitimate `null` (idle), so `!== undefined` distinguishes "sent null" from
+        // "not sent" (a non-reporting sender leaves prior coarse intact).
+        if (currentTool !== undefined)
+            coarseActivity.currentTool = currentTool;
+        if (contextTokens !== undefined)
+            coarseActivity.contextTokens = contextTokens;
+        if (contextPercent !== undefined)
+            coarseActivity.contextPercent = contextPercent;
     });
     /**
      * `requestDetach` signal — adapter-initiated graceful detach. Transitions to `draining`;
@@ -1415,6 +1463,9 @@ async function agentSessionWorkflow(input) {
                             // #131 Phase C — forward to spawnProcess so spawnClaudeApiAdapter
                             // can plumb it into the subprocess env (AGENT_TEMPO_API_MODEL).
                             ...(entry.model !== undefined ? { model: entry.model } : {}),
+                            // Phase 3a / MD-C — forward the headless Pi tool-access policy so
+                            // spawnPiHeadless plumbs AGENT_TEMPO_TOOL_ACCESS into the subprocess.
+                            ...(entry.toolAccess !== undefined ? { toolAccess: entry.toolAccess } : {}),
                         });
                         break;
                     }
@@ -1468,6 +1519,21 @@ async function agentSessionWorkflow(input) {
                         });
                         break;
                     }
+                    case 'reset': {
+                        // D14: operator/conductor CLEAN-WIPE. Sets a pendingReset flag the
+                        // Pi extension polls + acts on (newSession). POLL-delivery, not a
+                        // direct subprocess signal. resetId = this outbox entry id (the
+                        // extension acks with it). Does NOT route through the MD-G gate.
+                        await deliverReset({
+                            ensemble: input.metadata.ensemble,
+                            targetPlayerId: entry.targetPlayerId,
+                            resetId: entry.id,
+                            fresh: entry.fresh ?? true,
+                            ...(entry.reason !== undefined ? { reason: entry.reason } : {}),
+                            requestedBy: entry.invokerPlayerId ?? input.metadata.playerId,
+                        });
+                        break;
+                    }
                     case 'spawn': {
                         // PR-D: forward the pre-claimed attachment token + pinned runId +
                         // resolved adapterId to the spawn activity. The child process picks
@@ -1599,6 +1665,8 @@ async function agentSessionWorkflow(input) {
                 messages: messages.filter((m) => !m.delivered),
                 sentMessages: sentMessages.slice(-50),
                 outbox: outbox.filter((e) => e.status === 'pending' || e.status === 'processing'),
+                // D14 — carry an un-acked pending reset across CAN (omit when null).
+                ...(pendingReset ? { pendingReset } : {}),
                 lastInboundRRTime,
                 lastOutboundTime,
                 // #399 W2 — counters carried across continueAsNew so the

package/dist/workflows/signals.d.ts

@@ -1,5 +1,5 @@
-import type { SessionMetadata, Message, SentMessage, HistoryEntry, OutboxEntry, OutboxEntryInput, QualityGate, WorktreeEntry, StageEntry, AttachmentToken, AttachmentInfo, AdapterClass, DetachReason, OrphanSummary, PlayerStateEntry } from '../types';
-export type { SessionMetadata, SessionInput, Message, Command, PlayerReport, SentMessage, HistoryEntry, OutboxEntry, OutboxEntryInput, OutboxEntryStatus, CueOutboxEntry, RecruitOutboxEntry, ReportOutboxEntry, StopOutboxEntry, ReleaseOutboxEntry, SpawnOutboxEntry, AgentType, QualityGate, QualityGateCriterion, WorktreeEntry, StageEntry, StagePlayerStatus, AttachmentToken, AttachmentInfo, AttachmentPhase, Attachment, AdapterClass, AdapterDescriptor, DetachReason, AdapterDirective, OrphanSummary, PlayerStateEntry, } from '../types';
+import type { SessionMetadata, Message, SentMessage, HistoryEntry, OutboxEntry, OutboxEntryInput, QualityGate, WorktreeEntry, StageEntry, AttachmentToken, AttachmentInfo, AdapterClass, DetachReason, OrphanSummary, PlayerStateEntry, PendingReset } from '../types';
+export type { SessionMetadata, SessionInput, Message, Command, PlayerReport, SentMessage, HistoryEntry, OutboxEntry, OutboxEntryInput, OutboxEntryStatus, CueOutboxEntry, RecruitOutboxEntry, ReportOutboxEntry, StopOutboxEntry, ReleaseOutboxEntry, SpawnOutboxEntry, PendingReset, AgentType, QualityGate, QualityGateCriterion, WorktreeEntry, StageEntry, StagePlayerStatus, AttachmentToken, AttachmentInfo, AttachmentPhase, Attachment, AdapterClass, AdapterDescriptor, DetachReason, AdapterDirective, OrphanSummary, PlayerStateEntry, } from '../types';
 export declare const receiveMessageSignal: import("@temporalio/workflow").SignalDefinition<[{
     from: string;
     text: string;
@@ -34,6 +34,14 @@ export declare const getMetadataQuery: import("@temporalio/workflow").QueryDefin
 export declare const pendingMessagesQuery: import("@temporalio/workflow").QueryDefinition<Message[], [], string>;
 export declare const allMessagesQuery: import("@temporalio/workflow").QueryDefinition<Message[], [], string>;
 export declare const allSentMessagesQuery: import("@temporalio/workflow").QueryDefinition<SentMessage[], [], string>;
+export declare const setPendingResetSignal: import("@temporalio/workflow").SignalDefinition<[{
+    resetId: string;
+    fresh: boolean;
+    reason?: string;
+    requestedBy?: string;
+}], string>;
+export declare const pendingResetQuery: import("@temporalio/workflow").QueryDefinition<PendingReset | null, [], string>;
+export declare const ackResetSignal: import("@temporalio/workflow").SignalDefinition<[string], string>;
 /** Release a held session — unlocks the outbox and delivers the stored initial message. */
 export declare const releaseHeldSignal: import("@temporalio/workflow").SignalDefinition<[], "releaseHeld">;
 /** Query whether the session's outbox is locked (warm hold). */
@@ -138,10 +146,19 @@ export declare const setPreferredHostUpdate: import("@temporalio/common").Update
 /**
  * Liveness heartbeat from the adapter. Resets `lastHeartbeatAt` and extends `expiresAt` to
  * `workflow.now() + leaseMs` iff `attachmentId` matches the current attachment; otherwise ignored.
+ *
+ * 3c Tier-1 (additive, optional, non-breaking): the heartbeat doubles as the
+ * coarse-activity piggyback. `currentTool` (null = idle), `contextTokens`, and
+ * `contextPercent` (Pi `getContextUsage`, pull-only — no token event exists)
+ * refresh the workflow's queryable coarse state read by `getCoarseActivityQuery`.
+ * Omitted by senders that don't report coarse — the handler merges field-wise.
  */
 export declare const heartbeatSignal: import("@temporalio/workflow").SignalDefinition<[{
     attachmentId: string;
     at: string;
+    currentTool?: string | null;
+    contextTokens?: number;
+    contextPercent?: number;
 }], string>;
 /**
  * Adapter-, conductor-, or operator-initiated request to detach gracefully.
@@ -268,6 +285,19 @@ export declare const getLeaseStateQuery: import("@temporalio/workflow").QueryDef
     expiresAt: number | null;
     leaseMs: number | null;
 }, [], string>;
+/**
+ * 3c Tier-1 coarse activity — the player's current tool + context-token usage,
+ * refreshed by the heartbeat piggyback (`heartbeatSignal`). Read by the snapshot
+ * fan-out (`getPlayerWireMeta`) → projected onto `PlayerSummaryV1` → the aggregate
+ * poll/diff emits `player.activity`. `currentTool` is `null` when idle/between
+ * tools; the context fields are absent when Pi can't report usage (e.g. right
+ * after compaction). A live read of volatile state — NOT durable metadata.
+ */
+export declare const getCoarseActivityQuery: import("@temporalio/workflow").QueryDefinition<{
+    currentTool: string | null;
+    contextTokens?: number;
+    contextPercent?: number;
+}, [], string>;
 export declare const testForceContinueAsNewSignal: import("@temporalio/workflow").SignalDefinition<[], "testForceContinueAsNew">;
 export declare const setQualityGateSignal: import("@temporalio/workflow").SignalDefinition<[{
     task: string;

package/dist/workflows/signals.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setStageSignal = exports.worktreesQuery = exports.removeWorktreeSignal = exports.setWorktreeSignal = exports.qualityGatesQuery = exports.evaluateGateCriteriaSignal = exports.setQualityGateSignal = exports.testForceContinueAsNewSignal = exports.getLeaseStateQuery = exports.getActivityStateQuery = exports.getMessagingStateQuery = exports.getRunIdQuery = exports.outboxQuery = exports.submitOutboxUpdate = exports.playerStateKeysQuery = exports.playerStateQuery = exports.clearPlayerStateUpdate = exports.savePlayerStateUpdate = exports.orphanSummaryQuery = exports.attachmentInfoQuery = exports.adapterExitedSignal = exports.requestDetachSignal = exports.heartbeatSignal = exports.setPreferredHostUpdate = exports.enqueueSpawnUpdate = exports.forceDetachUpdate = exports.claimAttachmentUpdate = exports.isDestroyedQuery = exports.destroyUpdate = exports.inFlightMessagesQuery = exports.processingEndUpdate = exports.processingStartUpdate = exports.historyQuery = exports.playerReportSignal = exports.commandSignal = exports.pausedQuery = exports.setPausedSignal = exports.outboxLockedQuery = exports.releaseHeldSignal = exports.allSentMessagesQuery = exports.allMessagesQuery = exports.pendingMessagesQuery = exports.getMetadataQuery = exports.getPartQuery = exports.updateMetadataSignal = exports.setNameSignal = exports.markDeliveredSignal = exports.setPartSignal = exports.recordSentMessageSignal = exports.receiveMessageSignal = void 0;
-exports.stagesQuery = exports.cancelStageSignal = void 0;
+exports.qualityGatesQuery = exports.evaluateGateCriteriaSignal = exports.setQualityGateSignal = exports.testForceContinueAsNewSignal = exports.getCoarseActivityQuery = exports.getLeaseStateQuery = exports.getActivityStateQuery = exports.getMessagingStateQuery = exports.getRunIdQuery = exports.outboxQuery = exports.submitOutboxUpdate = exports.playerStateKeysQuery = exports.playerStateQuery = exports.clearPlayerStateUpdate = exports.savePlayerStateUpdate = exports.orphanSummaryQuery = exports.attachmentInfoQuery = exports.adapterExitedSignal = exports.requestDetachSignal = exports.heartbeatSignal = exports.setPreferredHostUpdate = exports.enqueueSpawnUpdate = exports.forceDetachUpdate = exports.claimAttachmentUpdate = exports.isDestroyedQuery = exports.destroyUpdate = exports.inFlightMessagesQuery = exports.processingEndUpdate = exports.processingStartUpdate = exports.historyQuery = exports.playerReportSignal = exports.commandSignal = exports.pausedQuery = exports.setPausedSignal = exports.outboxLockedQuery = exports.releaseHeldSignal = exports.ackResetSignal = exports.pendingResetQuery = exports.setPendingResetSignal = exports.allSentMessagesQuery = exports.allMessagesQuery = exports.pendingMessagesQuery = exports.getMetadataQuery = exports.getPartQuery = exports.updateMetadataSignal = exports.setNameSignal = exports.markDeliveredSignal = exports.setPartSignal = exports.recordSentMessageSignal = exports.receiveMessageSignal = void 0;
+exports.stagesQuery = exports.cancelStageSignal = exports.setStageSignal = exports.worktreesQuery = exports.removeWorktreeSignal = exports.setWorktreeSignal = void 0;
 const workflow_1 = require("@temporalio/workflow");
 // ── Player Signals ──
 // `isScheduled` + `scheduleName` are set by `src/activities/schedule-fire.ts`
@@ -27,6 +27,14 @@ exports.getMetadataQuery = (0, workflow_1.defineQuery)('getMetadata');
 exports.pendingMessagesQuery = (0, workflow_1.defineQuery)('pendingMessages');
 exports.allMessagesQuery = (0, workflow_1.defineQuery)('allMessages');
 exports.allSentMessagesQuery = (0, workflow_1.defineQuery)('allSentMessages');
+// ── Reset (D14) — context clean-wipe poll-delivery ──
+// `deliverReset` sets the pending flag via `setPendingResetSignal`; the Pi
+// extension polls `pendingResetQuery`, performs the wipe (newSession), then
+// clears it via `ackResetSignal(resetId)`. Single-slot, latest-wins. The
+// workflow stamps `requestedAt` (deterministic). See WIRE-PROTOCOL.md.
+exports.setPendingResetSignal = (0, workflow_1.defineSignal)('setPendingReset');
+exports.pendingResetQuery = (0, workflow_1.defineQuery)('pendingReset');
+exports.ackResetSignal = (0, workflow_1.defineSignal)('ackReset');
 // ── Hold / Release ──
 /** Release a held session — unlocks the outbox and delivers the stored initial message. */
 exports.releaseHeldSignal = (0, workflow_1.defineSignal)('releaseHeld');
@@ -95,6 +103,12 @@ exports.setPreferredHostUpdate = (0, workflow_1.defineUpdate)('setPreferredHost'
 /**
  * Liveness heartbeat from the adapter. Resets `lastHeartbeatAt` and extends `expiresAt` to
  * `workflow.now() + leaseMs` iff `attachmentId` matches the current attachment; otherwise ignored.
+ *
+ * 3c Tier-1 (additive, optional, non-breaking): the heartbeat doubles as the
+ * coarse-activity piggyback. `currentTool` (null = idle), `contextTokens`, and
+ * `contextPercent` (Pi `getContextUsage`, pull-only — no token event exists)
+ * refresh the workflow's queryable coarse state read by `getCoarseActivityQuery`.
+ * Omitted by senders that don't report coarse — the handler merges field-wise.
  */
 exports.heartbeatSignal = (0, workflow_1.defineSignal)('heartbeat');
 /**
@@ -210,6 +224,15 @@ exports.getActivityStateQuery = (0, workflow_1.defineQuery)('getActivityState');
  * boundary.
  */
 exports.getLeaseStateQuery = (0, workflow_1.defineQuery)('getLeaseState');
+/**
+ * 3c Tier-1 coarse activity — the player's current tool + context-token usage,
+ * refreshed by the heartbeat piggyback (`heartbeatSignal`). Read by the snapshot
+ * fan-out (`getPlayerWireMeta`) → projected onto `PlayerSummaryV1` → the aggregate
+ * poll/diff emits `player.activity`. `currentTool` is `null` when idle/between
+ * tools; the context fields are absent when Pi can't report usage (e.g. right
+ * after compaction). A live read of volatile state — NOT durable metadata.
+ */
+exports.getCoarseActivityQuery = (0, workflow_1.defineQuery)('getCoarseActivity');
 // ── Test-only Signals ──
 //
 // **Test-only.** Forces the session workflow's main loop to take the

package/examples/agents/tempo-composer.md

@@ -1,56 +1,56 @@
----
-name: tempo-composer
-description: Software architect — designs system structure, defines interfaces, makes technology decisions. Focuses on the "what" and "why", not implementation.
-model: opus
----
-
-You are the **Composer** of the ensemble — the Software Architect. You design the structure of the system: modules, boundaries, interfaces, data flow, and technical direction. You define *what* gets built and *why*, then hand off the *how* to soloists.
-
-## Responsibilities
-
-- Design system architecture: module boundaries, service decomposition, data flow
-- Define interfaces and contracts between components
-- Make technology choices with clear rationale
-- Analyze dependencies, coupling, and integration points
-- Identify scalability, security, and maintainability risks before they become problems
-- Review proposed designs and implementations for architectural consistency
-- Select API paradigms (REST, GraphQL, RPC) based on use case requirements
-
-## Working Style
-
-- **Understand before proposing**: Read existing code and architecture before suggesting changes. Respect what's already there.
-- **Think in systems**: Focus on boundaries, trade-offs, and data flow — not individual functions.
-- **Document decisions**: Every architectural decision should come with rationale and trade-offs considered. Write ADRs when the decision is significant.
-- **Be opinionated but open**: Have strong views on architecture, loosely held. Change your mind when presented with evidence.
-- **Delegate implementation**: Define the shape of the solution, then hand off to soloists. Don't get pulled into writing production code.
-- **Consider observability**: Design systems that are debuggable. Think about logging, tracing, and error reporting from the start.
-- **Don't over-architect**: Design the simplest structure that meets the known requirements. If you're adding abstraction layers without a concrete, present-tense benefit, remove them. Apply `/simplify` thinking — if a design element can't be justified by a real requirement, it doesn't belong.
-- **Avoid designing for imagined futures**: Add extensibility only where there's evidence you'll need it. Speculative abstractions become maintenance burdens. You can always refactor when the need is real.
-
-## Ensemble Collaboration
-
-- **`ensemble`**: Check who's active before proposing designs that affect multiple players' work. Understand the current state of implementation.
-- **`cue`**: Use to share design decisions, interface definitions, and architectural guidance with soloists. When a soloist asks a design question, respond with structured reasoning: context, options, recommendation, trade-offs.
-- **`report`**: Report to the conductor when:
-  - A design decision is made (so it can be communicated to affected players)
-  - You identify an architectural risk or concern
-  - You need input on requirements before you can finalize a design
-  - A design review is complete (with approve/reject/concerns)
-- **`who_am_i`**: Check your assignment and any type-specific instructions at startup.
-- **`agent_types`**: If you identify a need for a specialist (e.g., security review of your design), suggest the conductor recruit one.
-
-### When other players cue you
-
-- **Soloists asking design questions**: Respond promptly with clear, actionable guidance. Don't send them in circles.
-- **Conductor asking for design review**: Provide structured feedback — approved, changes requested, or concerns flagged — with specific reasoning.
-- **Tuners reporting architectural test gaps**: Acknowledge and adjust the design to improve testability if needed.
-
-## Context Pressure
-
-If you notice your context growing large, you're losing track of earlier instructions, or you find yourself repeating work, report to the conductor immediately with a structured summary:
-
-1. **Current task**: What you're working on right now
-2. **Key findings so far**: Important decisions, completed work, file paths changed
-3. **Recommended next steps**: What remains to be done
-
-This lets the conductor refresh your session with a clean context while preserving continuity.
+---
+name: tempo-composer
+description: Software architect — designs system structure, defines interfaces, makes technology decisions. Focuses on the "what" and "why", not implementation.
+model: opus
+---
+
+You are the **Composer** of the ensemble — the Software Architect. You design the structure of the system: modules, boundaries, interfaces, data flow, and technical direction. You define *what* gets built and *why*, then hand off the *how* to soloists.
+
+## Responsibilities
+
+- Design system architecture: module boundaries, service decomposition, data flow
+- Define interfaces and contracts between components
+- Make technology choices with clear rationale
+- Analyze dependencies, coupling, and integration points
+- Identify scalability, security, and maintainability risks before they become problems
+- Review proposed designs and implementations for architectural consistency
+- Select API paradigms (REST, GraphQL, RPC) based on use case requirements
+
+## Working Style
+
+- **Understand before proposing**: Read existing code and architecture before suggesting changes. Respect what's already there.
+- **Think in systems**: Focus on boundaries, trade-offs, and data flow — not individual functions.
+- **Document decisions**: Every architectural decision should come with rationale and trade-offs considered. Write ADRs when the decision is significant.
+- **Be opinionated but open**: Have strong views on architecture, loosely held. Change your mind when presented with evidence.
+- **Delegate implementation**: Define the shape of the solution, then hand off to soloists. Don't get pulled into writing production code.
+- **Consider observability**: Design systems that are debuggable. Think about logging, tracing, and error reporting from the start.
+- **Don't over-architect**: Design the simplest structure that meets the known requirements. If you're adding abstraction layers without a concrete, present-tense benefit, remove them. Apply `/simplify` thinking — if a design element can't be justified by a real requirement, it doesn't belong.
+- **Avoid designing for imagined futures**: Add extensibility only where there's evidence you'll need it. Speculative abstractions become maintenance burdens. You can always refactor when the need is real.
+
+## Ensemble Collaboration
+
+- **`ensemble`**: Check who's active before proposing designs that affect multiple players' work. Understand the current state of implementation.
+- **`cue`**: Use to share design decisions, interface definitions, and architectural guidance with soloists. When a soloist asks a design question, respond with structured reasoning: context, options, recommendation, trade-offs.
+- **`report`**: Report to the conductor when:
+  - A design decision is made (so it can be communicated to affected players)
+  - You identify an architectural risk or concern
+  - You need input on requirements before you can finalize a design
+  - A design review is complete (with approve/reject/concerns)
+- **`who_am_i`**: Check your assignment and any type-specific instructions at startup.
+- **`agent_types`**: If you identify a need for a specialist (e.g., security review of your design), suggest the conductor recruit one.
+
+### When other players cue you
+
+- **Soloists asking design questions**: Respond promptly with clear, actionable guidance. Don't send them in circles.
+- **Conductor asking for design review**: Provide structured feedback — approved, changes requested, or concerns flagged — with specific reasoning.
+- **Tuners reporting architectural test gaps**: Acknowledge and adjust the design to improve testability if needed.
+
+## Context Pressure
+
+If you notice your context growing large, you're losing track of earlier instructions, or you find yourself repeating work, report to the conductor immediately with a structured summary:
+
+1. **Current task**: What you're working on right now
+2. **Key findings so far**: Important decisions, completed work, file paths changed
+3. **Recommended next steps**: What remains to be done
+
+This lets the conductor refresh your session with a clean context while preserving continuity.