@staix/agent-hub 0.12.14 → 0.12.16

package/src/hub/hub-tools.ts

@@ -41,7 +41,7 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_done", "Mark your task finished. It goes to its reviewer with your summary and refs. When the project configures a check for its class, the hub runs it first and the result comes as a task message: a failed check keeps the task with you.", { id, summary: { type: "string", description: "what changed, why, and the check you ran with its result" }, refs }, ["id", "summary"]),
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
   tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result, and list what is unmet. Two changes_requested in a row move the task to another peer.", { id, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" } }, ["id", "verdict"]),
-  tool("hub_checkpoint", "Answer a checkpoint request from the hub (your quota window is nearly used up): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str }, ["summary"]),
+  tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id }, ["text"]),
 ];
 

package/src/hub/task-sweep.ts

@@ -0,0 +1,59 @@
+import type { Task } from "./board.ts";
+
+export type SweepKind = "unaccepted-assignment" | "idle-owner" | "review-pending";
+export interface SweepRecord {
+  kind: SweepKind;
+  /** Index of the last real activity, distinguishing even events at the same time. */
+  activity: number;
+  step: 1 | 2 | 3;
+  at: number;
+}
+export interface TaskSweepConfig {
+  enabled: boolean;
+  interval_s: number;
+  unaccepted_min: number;
+  idle_min: number;
+  review_min: number;
+  ladder_min: number;
+  auto_reassign: boolean;
+}
+export const DEFAULT_TASK_SWEEP: TaskSweepConfig = {
+  enabled: false, interval_s: 300, unaccepted_min: 60, idle_min: 120, review_min: 120, ladder_min: 30, auto_reassign: false,
+};
+
+/** Config cannot silently enable a sweep or reassignment through a truthy string. */
+export function taskSweepConfig(input: unknown): TaskSweepConfig {
+  if (input === undefined) return { ...DEFAULT_TASK_SWEEP };
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("task_sweep must be an object");
+  const out = { ...DEFAULT_TASK_SWEEP };
+  const values = input as Record<string, unknown>;
+  for (const key of ["enabled", "auto_reassign"] as const) {
+    if (values[key] === undefined) continue;
+    if (typeof values[key] !== "boolean") throw new Error(`task_sweep.${key} must be a boolean`);
+    out[key] = values[key];
+  }
+  for (const key of ["interval_s", "unaccepted_min", "idle_min", "review_min", "ladder_min"] as const) {
+    if (values[key] === undefined) continue;
+    const value = values[key];
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 1 || value * (key === "interval_s" ? 1000 : 60_000) > 2_147_483_647) throw new Error(`task_sweep.${key} must be a bounded number of at least 1`);
+    out[key] = value;
+  }
+  return out;
+}
+
+/** Pure time/kind ladder; Tasks decides whether the responsible peer is available. */
+export function nextSweep(task: Task, config: TaskSweepConfig, now: number): SweepRecord | undefined {
+  if (!config.enabled || !Number.isFinite(now)) return undefined;
+  const kind = task.state === "proposed" && task.owner ? "unaccepted-assignment"
+    : task.state === "in_progress" && task.owner ? "idle-owner"
+      : task.state === "in_review" && task.reviewer ? "review-pending" : undefined;
+  if (!kind) return undefined;
+  let activity = task.history.length - 1;
+  while (activity >= 0 && task.history[activity]?.sweep) activity--;
+  const at = task.history[activity]?.at ?? task.created;
+  const threshold = kind === "unaccepted-assignment" ? config.unaccepted_min : kind === "idle-owner" ? config.idle_min : config.review_min;
+  if (now - at < threshold * 60_000) return undefined;
+  const previous = task.history.flatMap((h) => h.sweep?.kind === kind && h.sweep.activity === activity ? [h.sweep] : []).at(-1);
+  if (previous && (previous.step === 3 || now - previous.at < config.ladder_min * 60_000)) return undefined;
+  return { kind, activity, step: previous ? (previous.step + 1) as 2 | 3 : 1, at: now };
+}

package/src/hub/tasks.ts

@@ -8,6 +8,7 @@ import { assign, detectSignals, LOCAL, PI, predictSplit, type Assignment, type R
 import { ExecutionBudget, type ExecutionBudgetConfig, type ExecutionBudgetDecision, type ExecutionBudgetStatus, type ExecutionUnit } from "./execution-budget.ts";
 import { Cohorts, MAX_REQUESTS, type Cohort, type Completion } from "./cohorts.ts";
 import { realPath } from "./project.ts";
+import { nextSweep, taskSweepConfig, type TaskSweepConfig, type SweepRecord } from "./task-sweep.ts";
 
 export interface TasksDeps {
   board: Board;
@@ -68,6 +69,9 @@ export interface TasksDeps {
   recordSplit?: (task: number, prediction: SplitPrediction, where: "routing" | "cohort") => void;
   /** A cohort formed, changed or was lifted (issue #107), for the record: the benchmark's treatment check reads it. */
   recordCohort?: (cohort: { id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: PeerId[] }) => void;
+  sweep?: TaskSweepConfig;
+  /** Shutdown or coordinator work holds task sweeps too. */
+  sweepHeld?: () => boolean;
 }
 
 const ESCALATE_AFTER = 2;
@@ -80,7 +84,7 @@ const DEMOTE_AT = 1.5;
 const CONTRADICTION_WINDOW_MS = 7 * 86_400_000;
 const OPEN: Task["state"][] = ["proposed", "in_progress", "changes_requested"];
 /** Board events that leave a task where its completion check found it; any other event means it moved on meanwhile. */
-const QUIET_EVENTS = new Set(["answer", "reviewer changed"]);
+const QUIET_EVENTS = new Set(["answer", "reviewer changed", "idle sweep"]);
 
 /** A project path as one spelling (#67): no leading `./`, no repeated or trailing `/`; the root is `.`. */
 export const normPath = (p: string) => p.replace(/^(\.\/)+/, "").replace(/\/{2,}/g, "/").replace(/\/+$/, "") || ".";
@@ -134,8 +138,11 @@ const planText = (plan: TaskPlan = {}) => PLAN_KEYS.filter((k) => plan[k]?.lengt
 export class Tasks {
   /** Turn-free cohorts (issue #107): who works without messages, and who integrates. */
   readonly cohorts: Cohorts;
+  private readonly sweepConfig: TaskSweepConfig;
+  private sweeping = false;
 
   constructor(private readonly d: TasksDeps) {
+    this.sweepConfig = taskSweepConfig(d.sweep);
     this.cohorts = new Cohorts({
       silence: (owners) => this.turnFree() && owners.every((p) => p !== USER && p !== HUB && (this.d.capable?.(p) ?? false)),
       idle: (peer) => this.d.idle?.(peer) ?? false,
@@ -157,6 +164,55 @@ export class Tasks {
 
   isPii = (task: Pick<Task, "signals">) => task.signals.includes("pii") && this.d.routing().constraints.pii === "local_only";
 
+  /** Task-owned, default-off between-turn ladder. Persist before sending so restart cannot repeat a step. */
+  async sweep(now = Date.now()): Promise<{ task: number; finding: SweepRecord }[]> {
+    const recorded: { task: number; finding: SweepRecord }[] = [];
+    if (!this.sweepConfig.enabled || this.sweeping || this.d.sweepHeld?.() || this.d.bus.isRecoveryHeld || this.d.bus.storageError) return recorded;
+    this.sweeping = true;
+    try {
+      for (const task of this.d.board.list()) {
+        if (this.d.sweepHeld?.() || this.d.bus.isRecoveryHeld || this.d.bus.storageError) break;
+        const finding = nextSweep(task, this.sweepConfig, now);
+        if (!finding || this.waitsFor(task).length || this.isChecking(task.id) || this.silentFor(task.id)) continue;
+        const responsible = finding.kind === "review-pending" ? task.reviewer! : task.owner!;
+        if (responsible !== USER && !this.sweepAvailable(responsible)) continue;
+        const title = this.publicTitle(task);
+        const message = `Task ${title}: ${finding.kind}, idle escalation ${finding.step}/3.`;
+        // Only identifiers, kind and step are kept in the ladder event. A crash after this write and before publish
+        // leaves the notice unpublished or uncertain; the durable-delivery journal owns any delivery retries.
+        this.d.board.update(task.id, HUB, "idle sweep", {}, undefined, { sweep: finding });
+        recorded.push({ task: task.id, finding });
+        if (finding.step === 1) {
+          this.sweepNotice(task, responsible, `${message} Check its current state with hub_task_list and accept, complete or review your assigned work.`);
+        } else if (finding.step === 2) {
+          this.d.notify(message);
+          for (const [peer, roles] of Object.entries(this.d.roles ?? {})) {
+            if (peer !== responsible && roles.includes("planner") && this.sweepAvailable(peer)) this.sweepNotice(task, peer, `${message} The assigned ${finding.kind === "review-pending" ? "reviewer" : "owner"} has not recorded fresh task activity; check the board before coordinating.`);
+          }
+        } else {
+          const reviewer = finding.kind === "review-pending";
+          const a = assign(task, this.states(), this.d.routing(), { exclude: [...this.declined(task), responsible], waitsFor: this.waitsFor(task), ...(reviewer ? { candidates: [], notReviewer: task.owner ?? undefined } : {}), ...this.weights(task.class) });
+          const candidate = reviewer ? a.reviewer : a.owner;
+          this.d.notify(`${message} ${reviewer ? "Reviewer" : "Owner"} reassignment suggestion: ${candidate ?? "no eligible peer"}.`);
+          if (!reviewer && candidate && this.sweepConfig.auto_reassign && this.sweepAvailable(candidate)) {
+            await this.assignOwner(this.d.board.get(task.id)!, HUB, { candidates: [candidate], exclude: [responsible], event: "reassigned", note: `idle sweep: ${finding.kind}; from ${responsible}` });
+          }
+        }
+      }
+    } finally { this.sweeping = false; }
+    return recorded;
+  }
+
+  private sweepAvailable(peer: PeerId): boolean {
+    const bus = this.d.bus;
+    return bus.stateOf(peer) === "idle" && (this.d.idle?.(peer) ?? true) && !this.d.held?.()[peer] && !bus.queueSummary(peer).heldBy && !bus.queued(peer) && !bus.hasInFlight(peer);
+  }
+
+  private sweepNotice(task: Task, peer: PeerId, body: string): void {
+    if (peer === USER) this.d.notify(body);
+    else this.d.bus.publish(newEnvelope(HUB, body, { to: [peer], kind: "task", refs: { task: String(task.id) } }));
+  }
+
   configureExecutionBudget = (config: ExecutionBudgetConfig): ExecutionBudgetStatus | undefined => {
     if (!this.d.executionBudget) return undefined;
     if (config.kind === "task" && (!config.taskId || !this.d.board.get(config.taskId))) throw new Error(`task #${config.taskId ?? "?"} does not exist`);

package/src/models/relay.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { isIP } from "node:net";
 import type { OmniRoute, ChatMessage } from "../omniroute/client.ts";
 import { ensureMlx, type MlxHandle, type MlxOptions, type MlxStatus } from "./mlx.ts";
@@ -32,7 +32,9 @@ export interface ModelRelayStatus {
 }
 
 /** Sanitized per-request identity and lifecycle evidence. One record per upstream dispatch attempt
- *  (a fallback dispatch is its own record). Records carry no messages, tools, keys or Access headers.
+ *  (a fallback dispatch is its own record). Records carry no messages, keys or Access headers; with the
+ *  opt-in `observeToolSurface` they additionally carry the bounded `toolSurface` projection (allowlist-
+ *  charset names, a count and an opaque schema hash — never descriptions, arguments or message text).
  *  `identified: false` with `outcome: "cancelled"` is the cancelled-before-identification state; an
  *  observed `actualModel` that differs from the trusted expected served model sets `mismatch`.
  *  Without an explicit expectation, the upstream-configured identifier remains the comparison default.
@@ -47,6 +49,63 @@ export interface RelayUsageObservation {
   totalTokens?: number;
 }
 
+/**
+ * The bounded tool-surface projection of one request's published `tools` array (#183): what the native
+ * declared to the model, reduced to allowlist-charset names (sorted, deduplicated), the raw entry count
+ * and an opaque full structural JSON-schema fingerprint. Schema annotations are omitted, while types,
+ * constraints and literal default/const/enum values are hashed only, never exported.
+ */
+export interface RelayToolSurface {
+  count: number;
+  names: string[];
+  schemaSha256: string;
+  invalidEntries: number;
+  duplicateNames: number;
+  truncated: boolean;
+}
+
+const SURFACE_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+const SURFACE_CAP = 64;
+const SCHEMA_ANNOTATIONS = new Set(["description", "title", "examples", "$comment"]);
+const SCHEMA_MAPS = new Set(["properties", "patternProperties", "$defs", "definitions", "dependentSchemas", "dependentRequired"]);
+
+/** Structural JSON-schema fingerprint, including types, constraints and nested shapes. Annotation text is
+ * omitted; all remaining values enter only the opaque hash. Resource ceilings fail explicitly, never silently
+ * qualify a partial schema. */
+export function toolSurfaceProjection(tools: unknown): RelayToolSurface | undefined {
+  if (!Array.isArray(tools)) return undefined;
+  let invalidEntries = 0, duplicateNames = 0, truncated = tools.length > SURFACE_CAP, nodes = 0;
+  const names = new Set<string>();
+  const canonical = (value: unknown, depth = 0, keyword = "", schemaMap = false, literal = false): unknown => {
+    if (++nodes > 8192 || depth > 20) { truncated = true; return null; }
+    if (value === null || typeof value === "boolean") return value;
+    if (typeof value === "number") { if (Number.isFinite(value)) return value; invalidEntries++; return null; }
+    if (typeof value === "string") { if (value.length > 8192) { truncated = true; return null; } return value; }
+    if (Array.isArray(value)) {
+      if (value.length > 256) truncated = true;
+      const result = value.slice(0, 256).map((v) => canonical(v, depth + 1, "", false, literal || keyword === "enum"));
+      return !literal && (keyword === "required" || keyword === "enum" || keyword === "type") ? result.sort((a, b) => { const x = JSON.stringify(a), y = JSON.stringify(b); return x < y ? -1 : x > y ? 1 : 0; }) : result;
+    }
+    if (value && typeof value === "object") {
+      const keys = Object.keys(value).filter((k) => literal || schemaMap || !SCHEMA_ANNOTATIONS.has(k)).sort();
+      if (keys.length > 256) truncated = true;
+      return Object.fromEntries(keys.slice(0, 256).map((k) => [k, canonical((value as Record<string, unknown>)[k], depth + 1, schemaMap ? "" : k, !literal && !schemaMap && SCHEMA_MAPS.has(k), literal || (!schemaMap && ["default", "const", "enum"].includes(k)))]));
+    }
+    invalidEntries++; return null;
+  };
+  const schema: { name: string; parameters: unknown }[] = [];
+  for (const entry of tools.slice(0, SURFACE_CAP)) {
+    const e = entry as { function?: unknown; name?: unknown; parameters?: unknown } | null;
+    const fn = (e && typeof e === "object" && e.function && typeof e.function === "object" ? e.function : e) as { name?: unknown; parameters?: unknown } | null;
+    const name = typeof fn?.name === "string" && SURFACE_NAME.test(fn.name) ? fn.name : "";
+    if (!name || !fn?.parameters || typeof fn.parameters !== "object" || Array.isArray(fn.parameters)) invalidEntries++;
+    if (name) { if (names.has(name)) duplicateNames++; names.add(name); }
+    schema.push({ name, parameters: canonical(fn?.parameters ?? null) });
+  }
+  schema.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  return { count: tools.length, names: [...names].sort(), schemaSha256: createHash("sha256").update(JSON.stringify(schema)).digest("hex"), invalidEntries, duplicateNames, truncated };
+}
+
 export interface RelayRequestRecord {
   id: string;
   dispatchGroupId?: string;
@@ -68,6 +127,8 @@ export interface RelayRequestRecord {
   usageAvailability?: "known" | "partial" | "missing" | "invalid";
   /** Observed served model; never read back from the backend's mutable last label. */
   actualModel?: string;
+  /** Bounded tool-surface projection of the request's published tools; only when the owner opted in. */
+  toolSurface?: RelayToolSurface;
   identitySource: "header" | "stream" | "configured" | "none";
   // ponytail: the relay cannot see native turn structure, so role stays "unknown"; a native surface
   // that knows primary vs auxiliary work (benchmark wiring, issue #140) is the upgrade path.
@@ -106,6 +167,9 @@ export interface ModelRelayOptions {
   /** Include explicit missing usage/provider metadata and dispatch groups, independently of observers.
    *  Omission preserves the legacy absent-metadata journal schema. */
   observeRequestMetadata?: boolean;
+  /** Journal each request's bounded tool-surface projection (#183). Omission preserves the no-tools
+   *  journal contract. */
+  observeToolSurface?: boolean;
   /** Called exactly once per journaled request, at its terminal close, with a sanitized copy. */
   onRequest?: (record: RelayRequestRecord) => void;
 }
@@ -258,7 +322,12 @@ function sseResponse(response: Response, release: () => void, onModel?: (model:
   });
 }
 
-const copyRecord = (record: RelayRequestRecord): RelayRequestRecord => ({ ...record, ...(record.requestUsage ? { requestUsage: { ...record.requestUsage } } : {}) });
+const copyRecord = (record: RelayRequestRecord): RelayRequestRecord => ({ ...record, ...(record.requestUsage ? { requestUsage: { ...record.requestUsage } } : {}), ...(record.toolSurface ? { toolSurface: { ...record.toolSurface, names: [...record.toolSurface.names] } } : {}) });
+
+/** Pure advertised alias list, also used by no-start launch previews. */
+export function relayModelIds(options: Pick<ModelRelayOptions, "enableHubAuto" | "mlx" | "mlxAlias" | "allowedDGXmodels">): string[] {
+  return [...new Set([...(options.enableHubAuto ? ["hub/auto"] : []), ...(options.mlx ? [options.mlxAlias ?? "mlx/fast"] : []), ...Object.keys(options.allowedDGXmodels)])];
+}
 
 export async function startModelRelay(options: ModelRelayOptions): Promise<ModelRelay> {
   const host = options.host ?? "127.0.0.1";
@@ -267,7 +336,7 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
   const mlxAlias = options.mlxAlias ?? "mlx/fast";
   const dgxMaxInputTokens = options.dgxMaxInputTokens ?? 262_144;
   const defaultBackend = options.defaultBackend ?? (options.mlx ? { kind: "mlx", alias: mlxAlias } : { kind: "dgx", alias: "dgx/coding" });
-  const models = [...new Set([...(options.enableHubAuto ? ["hub/auto"] : []), ...(options.mlx ? [mlxAlias] : []), ...Object.keys(options.allowedDGXmodels)])];
+  const models = relayModelIds(options);
   const autoRoute = options.enableHubAuto ? new AutoRouteSelector(options, defaultBackend, mlxAlias, estimateInputTokens) : undefined;
   let mlx: MlxHandle | undefined;
   let mlxStarting: Promise<MlxHandle> | undefined;
@@ -482,6 +551,12 @@ export async function startModelRelay(options: ModelRelayOptions): Promise<Model
       let primaryDispatchId: string | undefined;
       const dispatch = async (selected: ModelBackend, body: RelayRequest) => {
         const journalEntry = openRequestRecord(aliasOf(selected, mlxAlias), dispatchGroupId);
+        // The surface is a property of the request as admitted: even a failed dispatch keeps what the
+        // native published. A request without a tools array carries no observation, never an empty one.
+        if (options.observeToolSurface) {
+          const surface = toolSurfaceProjection(body.tools);
+          if (surface) journalEntry.record.toolSurface = surface;
+        }
         if (primaryDispatchId) {
           journalEntry.record.fallbackOfId = primaryDispatchId;
           journalEntry.record.dispatchGroupId = dispatchGroupId;

package/src/pi/ceiling.ts

@@ -0,0 +1,54 @@
+/**
+ * The Pi tool-step ceiling signal (#179): the one structured record of the hub extension refusing a
+ * managed tool call at its configured step limit. The trusted extension emits it over the bridge at the
+ * actual rejection boundary; the adapter validates it here before it can classify anything. Free text
+ * that merely resembles a ceiling never parses, and an unparsable or unbound signal leaves the failure
+ * unknown, exactly as before #179.
+ *
+ * Counter semantics (the producer's contract):
+ * - unit `tool-step`: one admitted managed-tool execution attempt — the extension's `execute` entry for
+ *   a hub-registered tool, after execution-budget admission succeeds and before the tool runs.
+ * - The rejected pre-effect invocation IS counted: the counter increments at that boundary, before the
+ *   limit check, so the first rejection reports `count = limit + 1` and the refused call's side effect
+ *   never executes.
+ * - Failed tool calls count: the counter does not observe the outcome. A counted call is an execution
+ *   attempt, never a proven successful effect.
+ * - Calls refused by execution-budget admission (#102) do NOT count: admission precedes the counter.
+ * - Reset: `agent_start` zeroes the counter and opens a new turn generation; it never resets mid-turn
+ *   and never carries across turns.
+ *
+ * The signal carries fixed enums, counts and identity only — never tool arguments, paths, responses or
+ * error text.
+ */
+export const PI_CEILING_KIND = "tool-step-ceiling" as const;
+export const PI_CEILING_UNIT = "tool-step" as const;
+
+export interface PiToolStepCeiling {
+  kind: typeof PI_CEILING_KIND;
+  unit: typeof PI_CEILING_UNIT;
+  /** The producer's counter after counting the rejected pre-effect invocation: always > limit. */
+  count: number;
+  /** The configured ceiling (AGENTHUB_PI_MAX_STEPS). */
+  limit: number;
+  /** The extension's session id and turn generation the rejection belongs to; the adapter binds both. */
+  sessionId: string;
+  generation: number;
+}
+
+/**
+ * Parse and validate a bridge ceiling event. Shape only — finite nonnegative safe-integer counts with
+ * count > limit (a rejection means the counted counter passed the configured limit), the fixed kind and
+ * unit, a non-empty bounded session id and a nonnegative turn generation. Session/turn binding to the
+ * current adapter state is the caller's check, not this function's.
+ */
+export function piToolStepCeiling(value: unknown): PiToolStepCeiling | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const e = value as Record<string, unknown>;
+  if (e.kind !== PI_CEILING_KIND || e.unit !== PI_CEILING_UNIT) return undefined;
+  if (!Number.isSafeInteger(e.count) || (e.count as number) < 1) return undefined;
+  if (!Number.isSafeInteger(e.limit) || (e.limit as number) < 0) return undefined;
+  if ((e.count as number) <= (e.limit as number)) return undefined;
+  if (typeof e.sessionId !== "string" || !e.sessionId || e.sessionId.length > 200) return undefined;
+  if (!Number.isSafeInteger(e.generation) || (e.generation as number) < 0) return undefined;
+  return { kind: PI_CEILING_KIND, unit: PI_CEILING_UNIT, count: e.count as number, limit: e.limit as number, sessionId: e.sessionId, generation: e.generation as number };
+}

package/src/pi/extension.ts

@@ -1,5 +1,6 @@
 import { assistantTokens } from "./usage.ts";
 import { processSignature } from "./process-signature.ts";
+import { PI_CEILING_KIND, PI_CEILING_UNIT } from "./ceiling.ts";
 type ExtensionAPI = any;
 type BudgetUnit = "model_calls" | "tool_calls";
 
@@ -20,6 +21,7 @@ let lastActivity = 0;
 let usageSeq = 0;
 let forcedFailure = "";
 let turnGeneration = 0;
+let sessionId = "";
 const maxSteps = Number(process.env.AGENTHUB_PI_MAX_STEPS ?? 30);
 let shutdown: (() => void) | undefined;
 let runtimeCtx: any;
@@ -103,6 +105,7 @@ export default function(pi: ExtensionAPI): void {
     modelRegistry = ctx.modelRegistry;
     shutdown = ctx.shutdown;
     const state = ctx.sessionManager.getHeader();
+    sessionId = String(state?.id ?? "");
     try {
       const claimed = await post("/event", { type: "session_start", ownerToken, pid: process.pid, signature: processSignature(process.pid), sessionId: state?.id, sessionFile: ctx.sessionManager.getSessionFile() });
       if (claimed?.ok === false) { ctx.shutdown?.(); return; }
@@ -163,9 +166,24 @@ export default function(pi: ExtensionAPI): void {
     if (!raw || typeof raw.name !== "string" || !raw.parameters) continue;
     pi.registerTool({ name: raw.name, label: raw.name, description: raw.description ?? raw.name, parameters: raw.parameters, async execute(toolCallId: string, params: unknown) {
       if (!(await admitBudget("tool_calls")).allowed) return { content: [{ type: "text", text: `error: ${forcedFailure}` }], details: {}, isError: true };
-      if (toolSteps++ >= maxSteps) { const reason = `Pi tool step limit ${maxSteps} reached`; forcedFailure = reason; await post("/event", { type: "agent_end", generation: turnGeneration, failed: true, error: reason }); runtimeCtx?.abort?.(); return { content: [{ type: "text", text: `error: ${reason}` }], details: {}, isError: true }; }
+      if (toolSteps++ >= maxSteps) {
+        const reason = `Pi tool step limit ${maxSteps} reached`;
+        forcedFailure = reason;
+        // #179: the structured ceiling signal at the actual rejection boundary, before the failure
+        // event, so the adapter binds it while the turn still owns it. The counter already counts the
+        // rejected pre-effect invocation (toolSteps++ above); its side effect never executes. The
+        // reason text stays the failure record; the signal adds the validated counts.
+        try { await post("/event", { type: "ceiling", kind: PI_CEILING_KIND, unit: PI_CEILING_UNIT, count: toolSteps, limit: maxSteps, sessionId, generation: turnGeneration }); } catch { /* the agent_end failure below remains authoritative */ }
+        await post("/event", { type: "agent_end", generation: turnGeneration, failed: true, error: reason });
+        runtimeCtx?.abort?.();
+        return { content: [{ type: "text", text: `error: ${reason}` }], details: {}, isError: true };
+      }
       const result = await post("/tool", { name: raw.name, args: params, toolCallId });
-      return { content: [{ type: "text", text: String(result.text ?? result) }], details: {} };
+      const text = String(result.text ?? result);
+      // Pi 1.0.1 reads isError === true alone (#181). The bridge computes `failed` with the
+      // managed-tool failure contract (toolResultFailed); the extension never re-parses the text.
+      // A bridge too old to send `failed` leaves the result unflagged, exactly as before the fix.
+      return { content: [{ type: "text", text }], details: {}, isError: result.failed === true };
     } });
   }
 }

package/src/pi/launch.ts

@@ -0,0 +1,20 @@
+import { join } from "node:path";
+import type { PiOptions, PiModelDescriptor, PiTuiLaunch } from "../adapters/pi.ts";
+
+const modelFor = (backend: PiOptions["backend"], models: PiModelDescriptor[]): string => {
+  const ids = models.map((m) => m.id);
+  const find = (needle: string) => ids.find((id) => id === needle) ?? needle;
+  if (backend === "mlx") return find("mlx/fast");
+  if (backend === "dgx") return find("dgx/coding");
+  if (ids.includes("hub/auto")) return "hub/auto";
+  return find(ids.find((id) => id === "dgx/coding") ? "dgx/coding" : ids.find((id) => id === "mlx/fast") ?? "dgx/coding");
+};
+
+/** Pure native launch; bridge/relay setup and session validation remain with the adapter. */
+export function buildPiLaunch(opts: Pick<PiOptions, "stateDir" | "cmd" | "mode" | "backend" | "model" | "relay" | "tools" | "preamble" | "maxSteps" | "sessionFile" | "sessionId">, inherited: NodeJS.ProcessEnv, extension: string, bridgePort: number | string, bridgeToken: string): PiTuiLaunch {
+  const env: NodeJS.ProcessEnv = { ...inherited, PI_CODING_AGENT_DIR: join(opts.stateDir, "pi"), AGENTHUB_PI_BRIDGE_URL: `http://127.0.0.1:${bridgePort}`, AGENTHUB_PI_BRIDGE_TOKEN: bridgeToken, AGENTHUB_PI_OWNER_TOKEN: bridgeToken, AGENTHUB_PI_RELAY_URL: opts.relay.url, AGENTHUB_PI_RELAY_TOKEN: opts.relay.token, AGENTHUB_PI_MODELS: JSON.stringify(opts.relay.models), AGENTHUB_PI_TOOLS: JSON.stringify(opts.tools), AGENTHUB_PI_MAX_STEPS: String(opts.maxSteps ?? 30) };
+  const args = [ ...(opts.mode === "headless" ? ["--mode", "rpc"] : []), "--provider", "agent-hub-local", "--model", opts.model ?? modelFor(opts.backend, opts.relay.models), "--models", opts.relay.models.map((model) => `agent-hub-local/${model.id}`).join(","), "--no-builtin-tools", "--no-skills", "--no-prompt-templates", "--no-extensions", "--extension", extension, ...(opts.preamble ? ["--append-system-prompt", opts.preamble] : []), "--session-dir", join(opts.stateDir, "pi-sessions")];
+  if (opts.sessionFile) args.push("--session", opts.sessionFile); else if (opts.sessionId) args.push("--session-id", opts.sessionId);
+  const command = opts.cmd ?? ["pi"];
+  return { cmd: command[0]!, args: [...command.slice(1), ...args], env };
+}

package/src/ui/index.html

@@ -205,6 +205,12 @@ function render(snapshot) {
     if (!Object.keys(snapshot.budget).length) return empty(target, 'No usage readings yet. Usage appears when a peer reports it.');
     for (const [peer, budget] of Object.entries(snapshot.budget)) {
       const row = el('div', undefined, 'row'); row.append(el('div', peer, 'label'));
+      const context = budget.context;
+      if (context) {
+        const pct = context.used === null ? null : Math.round(context.used * 100);
+        row.append(el('p', 'Context: ' + (pct === null ? 'unknown' : pct + '% used') + ' (' + context.freshness + ')' + (context.source ? ' / ' + context.source : '') + (context.measuredAt !== null ? ' / measured ' + time(context.measuredAt) : ''), 'meta'));
+        if (pct !== null) { const bar = el('progress'); bar.max = 1; bar.value = context.used; bar.setAttribute('aria-label', peer + ' context usage'); row.append(bar); }
+      }
       if (budget.paused) { const line = el('p', 'Paused: ' + budget.paused.reason + ' / resets ', 'meta'), stamp = el('span'); stamp.dataset.ts = budget.paused.resetsAt; stamp.title = time(budget.paused.resetsAt); stamp.textContent = rel(budget.paused.resetsAt); line.append(stamp); row.append(line); }
       if (!budget.windows.length) row.append(el('p', 'No usage windows reported.', 'meta'));
       for (const window of budget.windows) {