akanjs 3.0.0-beta.9 → 3.0.1

package/vendor/use-agentic/AgentGate.ts

@@ -0,0 +1,25 @@
+/**
+ * Whether what a subtree registered is published right now. A gate under another is active only while the one
+ * above it is, so a panel parked inside a page closes with the page.
+ */
+export class AgentGate {
+  #active: boolean;
+  readonly #onChange: () => void;
+  readonly #parent: AgentGate | null;
+
+  constructor(active: boolean, onChange: () => void, parent: AgentGate | null = null) {
+    this.#active = active;
+    this.#onChange = onChange;
+    this.#parent = parent;
+  }
+
+  get active(): boolean {
+    return this.#active && (this.#parent?.active ?? true);
+  }
+
+  set(active: boolean) {
+    if (this.#active === active) return;
+    this.#active = active;
+    this.#onChange();
+  }
+}

package/vendor/use-agentic/AgentProgress.ts

@@ -1,8 +1,20 @@
+export interface AgentProgressStep {
+  id: string;
+  label: string;
+  status: "pending" | "running" | "done" | "error";
+  detail?: string;
+}
+
 export interface AgentProgressReport {
   /** One short line about the step in flight. Read by the user, not the model — keep it prose. */
   message: string;
   done?: number;
   total?: number;
+  /**
+   * The activity of work running somewhere else — a server job, a code worker — that this one call is waiting on.
+   * Each report replaces the list whole, so a relay forwards what it has and never merges.
+   */
+  steps?: AgentProgressStep[];
 }
 
 /**
@@ -19,7 +31,7 @@ export interface AgentProgressReport {
 export class AgentProgress {
   static #sink: ((report: AgentProgressReport) => void) | null = null;
 
-  static report(message: string, amount: { done?: number; total?: number } = {}) {
+  static report(message: string, amount: { done?: number; total?: number; steps?: AgentProgressStep[] } = {}) {
     AgentProgress.#sink?.({ message, ...amount });
   }
 

package/vendor/use-agentic/AgentSession.ts

@@ -2,7 +2,7 @@ import type { AgentProgressReport } from "./AgentProgress";
 import { Compaction, type CompactOptions } from "./Compaction";
 import { Reference } from "./Reference";
 import { ToolOutput } from "./ToolOutput";
-import { type ToolApprovalRequest, ToolRunner } from "./ToolRunner";
+import { type ToolApprovalRequest, type ToolCardAnswer, type ToolCardRequest, ToolRunner } from "./ToolRunner";
 import { Transcript } from "./Transcript";
 import type {
   AgentRunner,
@@ -12,9 +12,13 @@ import type {
   PublishedTool,
   RunnerRequest,
   SurfaceView,
+  ToolActivity,
   ToolCallRequest,
   ToolCallResult,
+  ToolCard,
+  TurnLimits,
   TurnStop,
+  TurnUsage,
 } from "./types";
 
 export interface PendingApproval {
@@ -39,6 +43,20 @@ export interface PendingQuestion {
   dismiss: (reason?: string) => void;
 }
 
+/**
+ * A call parked on a component the app declared with the tool — a form to fill in, a choice no list of strings
+ * could carry. The loop waits on it exactly as it waits on an approval, and `render` is the app's own, so the
+ * framework decides where the card sits and nothing about what it asks.
+ */
+export interface PendingCard {
+  callId: string;
+  name: string;
+  args: Record<string, unknown>;
+  render: ToolCard;
+  submit: (value: unknown) => void;
+  dismiss: (reason?: string) => void;
+}
+
 /**
  * Where a session keeps its transcript across page loads. Storage-neutral: the host decides what backs it, so a
  * server-side transcript is as legal as web storage — which is why every method may answer asynchronously. A
@@ -92,6 +110,21 @@ export interface AgentSessionOptions {
    * duplicate, no error, just messages that never reach the server. Reset the mark here.
    */
   onCompact?: (replaced: readonly ChatMessage[], summary: ChatMessage) => void;
+  /**
+   * Called as each tool call starts and ends — where a host draws what the agent is doing on the page itself.
+   * The session keeps none of it: nothing here is transcript, and holding it would mean a re-render per call for
+   * something no message renders.
+   */
+  onActivity?: (event: ToolActivity) => void | Promise<void>;
+  /**
+   * Called when a turn starts and when it settles — the boundary a host draws the agent's own presence in. The
+   * calls of one turn arrive with model turns between them, seconds long, so anything measured in the gap
+   * between *calls* keeps ending and restarting inside a turn that never stopped.
+   *
+   * Only the conversation loop reports here. `compact` runs under the same flag and drives nothing on screen, so
+   * a host drawing the agent at work would draw it for a summary nobody asked to watch.
+   */
+  onTurn?: (running: boolean) => void;
 }
 
 /**
@@ -134,6 +167,7 @@ export class AgentSession {
   #running = false;
   #pending: PendingApproval | null = null;
   #question: PendingQuestion | null = null;
+  #card: PendingCard | null = null;
   #staged: MessageReference[] = [];
   #inserts: MessageReference[] = [];
   #chats = 0;
@@ -149,8 +183,15 @@ export class AgentSession {
   #history: SessionHistory | undefined;
   #onCompact: AgentSessionOptions["onCompact"];
   #compacting = false;
-  /** Size below which auto-compaction stays out of the way, raised when a summary failed to shrink anything. */
-  #compactFloor = 0;
+  /**
+   * Sizes below which auto-compaction stays out of the way, raised when a summary failed to shrink anything — one
+   * per trigger, since the ceiling reads the transcript and the guard the whole prompt.
+   */
+  #compactFloor = { transcript: 0, prompt: 0 };
+  /** What the backend reported about its model, or what a refusal named — kept for the life of the session. */
+  #limits: TurnLimits = {};
+  /** What the tools, the screen context and the instructions cost the last request, for a host's gauge. */
+  #overhead = 0;
 
   constructor(surface: SurfaceView, runner: AgentRunner, options: AgentSessionOptions = {}) {
     this.#surface = surface;
@@ -158,7 +199,9 @@ export class AgentSession {
     this.#options = options;
     this.#tools = new ToolRunner(surface, {
       approve: (request, signal) => this.#awaitApproval(request, signal),
+      card: (request, signal) => this.#awaitCard(request, signal),
       settle: () => this.#options.settle?.(),
+      activity: (event) => this.#options.onActivity?.(event),
       progress: ({ callId, report }) => {
         if (report) this.#progress = { ...report, callId };
         else if (this.#progress?.callId === callId) this.#progress = null;
@@ -217,6 +260,10 @@ export class AgentSession {
     return this.#question;
   }
 
+  get pendingCard(): PendingCard | null {
+    return this.#card;
+  }
+
   /**
    * What the user has pointed at and not yet sent.
    *
@@ -357,11 +404,13 @@ export class AgentSession {
   async #turn(input: string | ChatMessage[]) {
     const controller = new AbortController();
     this.#controller = controller;
+    this.#options.onTurn?.(true);
     if (typeof input === "string") this.#append({ role: "user", text: input });
     else for (const message of input) this.#append(message);
     const maxTurns = this.#options.maxTurns ?? 12;
     try {
       let budget = maxTurns;
+      let recovered = false;
       for (let turn = 0; ; turn += 1) {
         if (controller.signal.aborted) return;
         if (turn >= budget) {
@@ -375,12 +424,20 @@ export class AgentSession {
           budget = turn + maxTurns;
         }
         await this.#autoCompact(controller.signal);
-        const { toolCalls, stop } = await this.#assistantTurn(controller.signal);
+        const { toolCalls, stop, overflow } = await this.#assistantTurn(controller.signal);
 
         if (controller.signal.aborted) {
           this.#unanswered(toolCalls);
           return;
         }
+        if (overflow) {
+          if (recovered || !(await this.#recover(overflow, controller.signal))) {
+            if (!controller.signal.aborted) this.#fail(overflow.message);
+            return;
+          }
+          recovered = true;
+          continue;
+        }
 
         if (stop === "length") {
 
@@ -408,10 +465,12 @@ export class AgentSession {
       this.#active = null;
       this.#pending = null;
       this.#question = null;
+      this.#card = null;
       this.#progress = null;
 
       const draft = this.#messages[this.#messages.length - 1];
       if (draft?.role === "assistant" && !Transcript.carries(draft)) this.#messages = this.#messages.slice(0, -1);
+      this.#options.onTurn?.(false);
       this.#notify();
     }
   }
@@ -433,7 +492,7 @@ export class AgentSession {
     this.#messages = [];
     this.#staged = [];
     this.#inserts = [];
-    this.#compactFloor = 0;
+    this.#compactFloor = { transcript: 0, prompt: 0 };
     
     if (this.#saveTimer) {
       clearTimeout(this.#saveTimer);
@@ -532,11 +591,28 @@ export class AgentSession {
     }
   };
 
-  /** What the transcript is estimated to cost the next turn, in tokens — the number auto-compaction watches. */
+  /** What the transcript is estimated to cost the next turn, in tokens — the number the `at` ceiling watches. */
   get tokens() {
     return Compaction.tokensOf(this.#messages);
   }
 
+  /**
+   * How close the conversation is to summarizing itself, measured against whichever trigger is nearer: the `at`
+   * ceiling over the transcript, or the window guard over the whole prompt once the backend has reported its
+   * window. Each pair is in its own unit, which is why only the nearer one is answered. No `compactAt` means
+   * nothing will compact it.
+   */
+  get context(): { used: number; compactAt?: number } {
+    const { at, buffer } = this.#compactOptions;
+    const prompt = Compaction.promptTokensOf(this.#messages, () => this.#overhead);
+    if (!at) return { used: prompt };
+    const guard = Compaction.thresholdOf(this.#limits, buffer);
+    const ceiling = Number.isFinite(at) ? { used: Compaction.tokensOf(this.#messages), compactAt: at } : null;
+    const window = Number.isFinite(guard) ? { used: prompt, compactAt: guard } : null;
+    if (ceiling && window) return ceiling.used / ceiling.compactAt >= window.used / window.compactAt ? ceiling : window;
+    return ceiling ?? window ?? { used: prompt };
+  }
+
   /** Records a host-side failure (a prompt fetch, an upload) in the transcript, where every other failure lands. */
   report = (error: string) => {
     this.#append({ role: "assistant", error });
@@ -557,7 +633,7 @@ export class AgentSession {
       if (!summary || signal.aborted) return false;
       const replaced = this.#messages.slice(0, at);
       const message = Compaction.message(summary);
-      this.#messages = [message, ...this.#messages.slice(at)];
+      this.#messages = [message, ...this.#messages.slice(at).map(Transcript.unmeasured)];
       try {
         this.#onCompact?.(replaced, message);
       } catch {
@@ -571,13 +647,21 @@ export class AgentSession {
 
   /**
    * Runs before the turn that would have overflowed rather than after it fails: the provider answers a request
-   * that is too long with a refusal, not with a shorter answer, so there is nothing to recover from afterwards.
-   * Best effort — a summary that cannot be produced leaves the transcript as it stands and the turn goes out as
-   * it would have, since it may well still fit.
+   * that is too long with a refusal, not with a shorter answer, so waiting for one costs a round trip that was
+   * refused. Best effort — a summary that cannot be produced leaves the transcript as it stands and the turn goes
+   * out as it would have, since it may well still fit.
    */
   async #autoCompact(signal: AbortSignal) {
-    const { at = Compaction.defaults.at, keep = Compaction.defaults.keep } = this.#options.compact ?? {};
-    if (!at || Compaction.tokensOf(this.#messages) < Math.max(at, this.#compactFloor)) return;
+    const { at, keep, buffer } = this.#compactOptions;
+    if (!at) return;
+    const guard = Compaction.thresholdOf(this.#limits, buffer);
+    const measure = () => ({
+      transcript: Compaction.tokensOf(this.#messages),
+      prompt: Compaction.promptTokensOf(this.#messages, () => AgentSession.#tokensOfFrame(this.#frame())),
+    });
+    const before = measure();
+    const floor = this.#compactFloor;
+    if (before.transcript < Math.max(at, floor.transcript) && before.prompt <= Math.max(guard, floor.prompt)) return;
     let compacted = false;
     try {
       compacted = await this.#compact(keep, signal);
@@ -586,9 +670,57 @@ export class AgentSession {
       console.warn(`[use-agentic] compaction failed: ${error instanceof Error ? error.message : String(error)}`);
       return;
     }
-    const after = Compaction.tokensOf(this.#messages);
+    const after = measure();
 
-    this.#compactFloor = compacted && after >= at ? after + at : 0;
+    this.#compactFloor = {
+      transcript: compacted && after.transcript >= at ? after.transcript + at : 0,
+      prompt: compacted && after.prompt > guard ? after.prompt + buffer : 0,
+    };
+  }
+
+  /**
+   * Answers a refusal for length the one way a session can: compact, and ask again. Once per send — a transcript
+   * refused again after its own summary is not one another summary will fit — and never where the host turned
+   * automatic compaction off, since that host keeps the window itself.
+   */
+  async #recover(overflow: { limit?: number }, signal: AbortSignal): Promise<boolean> {
+    if (overflow.limit) this.#limits = { ...this.#limits, window: overflow.limit };
+    const { at, keep } = this.#compactOptions;
+    if (!at) return false;
+    const draft = this.#messages[this.#messages.length - 1];
+    if (draft?.role === "assistant" && !Transcript.carries(draft)) this.#messages = this.#messages.slice(0, -1);
+    try {
+      return await this.#compact(keep, signal);
+    } catch (error) {
+      console.warn(`[use-agentic] compaction failed: ${error instanceof Error ? error.message : String(error)}`);
+      return false;
+    }
+  }
+
+  get #compactOptions() {
+    const {
+      at = Compaction.defaults.at,
+      keep = Compaction.defaults.keep,
+      buffer = Compaction.defaults.buffer,
+    } = this.#options.compact ?? {};
+    return { at, keep, buffer };
+  }
+
+  /** What rides every turn beside the transcript. Read per turn, because the screen it describes moves. */
+  #frame(): Omit<RunnerRequest, "messages" | "signal"> {
+    const { tools, guides } = this.#surface.snapshot();
+    const instructions = [this.#options.instructions, ...guides].filter(Boolean).join("\n\n");
+    return {
+      tools: tools.some((tool) => tool.name === AgentSession.askUserTool.name)
+        ? tools
+        : [...tools, AgentSession.askUserTool],
+      context: this.#options.buildContext?.(this.#surface) ?? AgentSession.#defaultContext(this.#surface),
+      ...(instructions ? { instructions } : {}),
+    };
+  }
+
+  static #tokensOfFrame(frame: Omit<RunnerRequest, "messages" | "signal">): number {
+    return Math.ceil(JSON.stringify(frame).length / 4);
   }
 
   /** No tools and no screen context: this turn summarizes the conversation, and must not act on it. */
@@ -609,32 +741,33 @@ export class AgentSession {
     return text;
   }
 
-  async #assistantTurn(signal: AbortSignal): Promise<{ toolCalls: ToolCallRequest[]; stop: TurnStop }> {
-    const { tools, guides } = this.#surface.snapshot();
-    const instructions = [this.#options.instructions, ...guides].filter(Boolean).join("\n\n");
-    const request: RunnerRequest = {
-      messages: Transcript.wire(this.#messages),
-      tools: tools.some((tool) => tool.name === AgentSession.askUserTool.name)
-        ? tools
-        : [...tools, AgentSession.askUserTool],
-      context: this.#options.buildContext?.(this.#surface) ?? AgentSession.#defaultContext(this.#surface),
-      ...(instructions ? { instructions } : {}),
-      signal,
-    };
+  async #assistantTurn(
+    signal: AbortSignal,
+  ): Promise<{ toolCalls: ToolCallRequest[]; stop: TurnStop; overflow?: { message: string; limit?: number } }> {
+    const frame = this.#frame();
+    this.#overhead = AgentSession.#tokensOfFrame(frame);
+    const request: RunnerRequest = { messages: Transcript.wire(this.#messages), ...frame, signal };
     this.#append({ role: "assistant" });
     let text = "";
     const toolCalls: ToolCallRequest[] = [];
     let stop: TurnStop = "end";
+    let usage: TurnUsage | undefined;
     for await (const event of this.#runner.run(request)) {
       if (signal.aborted) break;
       if (event.type === "text") {
         text += event.delta;
         this.#patchLast({ text });
       } else if (event.type === "toolCall") toolCalls.push({ id: event.id, name: event.name, args: event.args });
-      else if (event.type === "done") stop = event.stop;
+      else if (event.type === "done") {
+        stop = event.stop;
+        usage = event.usage;
+        if (event.limits) this.#limits = { ...this.#limits, ...event.limits };
+      } else if (event.overflow)
+        return { toolCalls: [], stop: "end", overflow: { message: event.message, limit: event.overflow.limit } };
       else throw new Error(event.message);
     }
-    if (toolCalls.length) this.#patchLast({ toolCalls });
+    if (toolCalls.length || usage)
+      this.#patchLast({ ...(toolCalls.length ? { toolCalls } : {}), ...(usage ? { usage } : {}) });
     return { toolCalls, stop };
   }
 
@@ -693,6 +826,28 @@ export class AgentSession {
     });
   }
 
+  #awaitCard(request: ToolCardRequest, signal: AbortSignal): Promise<ToolCardAnswer> {
+    return new Promise((resolve) => {
+      const settle = (answer: ToolCardAnswer) => {
+        this.#card = null;
+        signal.removeEventListener("abort", onAbort);
+        this.#notify();
+        resolve(answer);
+      };
+      const onAbort = () => settle({ error: "The user aborted the turn." });
+      signal.addEventListener("abort", onAbort);
+      this.#card = {
+        callId: request.callId,
+        name: request.name,
+        args: request.args,
+        render: request.render,
+        submit: (value) => settle({ result: value }),
+        dismiss: (reason) => settle({ error: reason ?? "The user closed the card without filling it in." }),
+      };
+      this.#notify();
+    });
+  }
+
   #awaitApproval(request: ToolApprovalRequest, signal: AbortSignal): Promise<true | string> {
     return new Promise((resolve) => {
       const settle = (value: true | string) => {

package/vendor/use-agentic/AgenticSurface.ts

@@ -1,3 +1,4 @@
+import { AgentGate } from "./AgentGate";
 import type {
   AgentCall,
   PublishedResource,
@@ -13,6 +14,11 @@ import type {
 
 const SHARED_KEY = Symbol.for("useAgentic.sharedSurface");
 
+interface Registration<E> {
+  entry: E;
+  gate: AgentGate | null;
+}
+
 /**
  * The live registry of what the mounted screen offers an agent: tools, readable resources, and scopes.
  *
@@ -41,10 +47,10 @@ export class AgenticSurface {
     return [...scope.map((part) => AgenticSurface.sanitize(part)), AgenticSurface.sanitize(name)].join(".");
   }
 
-  #tools = new Map<string, ToolEntry[]>();
-  #resources = new Map<string, ResourceEntry[]>();
-  #scopes = new Map<string, ScopeEntry[]>();
-  #guides: { scope: string; text: string }[] = [];
+  #tools = new Map<string, Registration<ToolEntry>[]>();
+  #resources = new Map<string, Registration<ResourceEntry>[]>();
+  #scopes = new Map<string, Registration<ScopeEntry>[]>();
+  #guides: { scope: string; text: string; gate: AgentGate | null }[] = [];
   readonly #calls: AgentCall[] = [];
   #sources = new Set<SurfaceSource>();
   #listeners = new Set<() => void>();
@@ -62,34 +68,37 @@ export class AgenticSurface {
    * argument rather than closing over it: every registration is then interchangeable and last-wins picks an
    * equivalent one. The description is what says so — two registrations that describe the same action to a model
    * are the same declaration twice, and fifty rows are one entry rather than fifty collisions. Two that describe
-   * different actions under one name are a real clash whichever of them mounted last, and warn.
+   * different actions under one name are a real clash whichever of them mounted last, and warn. A clash needs both
+   * published at once, so a registration behind a parked gate, or over only parked ones, never warns.
    */
-  registerTool(scope: string[], entry: ToolEntry) {
+  registerTool(scope: string[], entry: ToolEntry, gate: AgentGate | null = null) {
     const key = AgenticSurface.fullName(scope, entry.name);
-    const stack = this.#tools.get(key);
-    const interchangeable = !stack?.length || stack[stack.length - 1].description === entry.description;
+    const shown = AgenticSurface.#shown(this.#tools.get(key));
+    const clashes = !!shown && AgenticSurface.#isActive(gate) && shown.description !== entry.description;
     return this.#stack(
       this.#tools,
       key,
-      entry,
-      interchangeable ? null : "is registered by two declarations that describe it differently",
+      { entry, gate },
+      clashes ? "is registered by two declarations that describe it differently" : null,
     );
   }
 
-  registerResource(scope: string[], entry: ResourceEntry) {
-    return this.#stack(this.#resources, AgenticSurface.fullName(scope, entry.name), entry);
+  registerResource(scope: string[], entry: ResourceEntry, gate: AgentGate | null = null) {
+    const key = AgenticSurface.fullName(scope, entry.name);
+    return this.#stack(this.#resources, key, { entry, gate }, this.#duplicate(this.#resources, key, gate));
   }
 
-  openScope(parent: string[], scope: ScopeEntry) {
-    return this.#stack(this.#scopes, AgenticSurface.childPath(parent, scope.id).join("."), scope);
+  openScope(parent: string[], scope: ScopeEntry, gate: AgentGate | null = null) {
+    const key = AgenticSurface.childPath(parent, scope.id).join(".");
+    return this.#stack(this.#scopes, key, { entry: scope, gate }, this.#duplicate(this.#scopes, key, gate));
   }
 
   /**
    * Standing guidance for the agent while the registrant is mounted — instructions, not context data. Kept in
    * registration order rather than sorted: guides are prose, and each one must stay a coherent block.
    */
-  registerGuide(scope: string[], text: string) {
-    const entry = { scope: scope.join("."), text };
+  registerGuide(scope: string[], text: string, gate: AgentGate | null = null) {
+    const entry = { scope: scope.join("."), text, gate };
     this.#guides.push(entry);
     this.#notify();
     return () => {
@@ -110,6 +119,36 @@ export class AgenticSurface {
     };
   }
 
+  /** A gate whose every flip re-publishes this surface. Under `parent`, it is active only while the parent is. */
+  gate(active: boolean, parent: AgentGate | null = null) {
+    return new AgentGate(active, () => this.#notify(), parent);
+  }
+
+  /**
+   * This surface for a subtree behind `gate`: what registers through it is published only while the gate is active,
+   * and every other call reaches this surface untouched. A proxy rather than a wrapper class, so a method added to the
+   * surface later is forwarded instead of missing.
+   */
+  gated(gate: AgentGate): AgenticSurface {
+    const registrations: Partial<Record<PropertyKey, unknown>> = {
+      registerTool: (scope: string[], entry: ToolEntry) => this.registerTool(scope, entry, gate),
+      registerResource: (scope: string[], entry: ResourceEntry) => this.registerResource(scope, entry, gate),
+      openScope: (parent: string[], scope: ScopeEntry) => this.openScope(parent, scope, gate),
+      registerGuide: (scope: string[], text: string) => this.registerGuide(scope, text, gate),
+    };
+    
+    const bound = new Map<PropertyKey, unknown>();
+    return new Proxy(this, {
+      get: (target, key) => {
+        if (Object.hasOwn(registrations, key)) return registrations[key];
+        const value = Reflect.get(target, key, target);
+        if (typeof value !== "function") return value;
+        if (!bound.has(key)) bound.set(key, value.bind(target));
+        return bound.get(key);
+      },
+    });
+  }
+
   snapshot(view: string[] = []): SurfaceSnapshot {
     const viewKey = view.join(".");
     const tools = [...this.#activeTools(view)].map(([name, entry]) => AgenticSurface.#publishTool(name, entry));
@@ -118,16 +157,19 @@ export class AgenticSurface {
     );
     const scopes = [...this.#scopes.entries()]
       .filter(([path]) => AgenticSurface.#within(viewKey, path))
-      .map(([path, stack]) => {
-        const scope = stack[stack.length - 1];
-        return { path, ...(scope.label ? { label: scope.label } : {}), ...(scope.kind ? { kind: scope.kind } : {}) };
+      .flatMap(([path, stack]) => {
+        const scope = AgenticSurface.#shown(stack);
+        if (!scope) return [];
+        return [{ path, ...(scope.label ? { label: scope.label } : {}), ...(scope.kind ? { kind: scope.kind } : {}) }];
       });
     
     return {
       tools: tools.sort((a, b) => (a.name < b.name ? -1 : 1)),
       resources: resources.sort((a, b) => (a.name < b.name ? -1 : 1)),
       scopes: scopes.sort((a, b) => (a.path < b.path ? -1 : 1)),
-      guides: this.#guides.filter((guide) => AgenticSurface.#guideApplies(viewKey, guide.scope)).map((g) => g.text),
+      guides: this.#guides
+        .filter((guide) => AgenticSurface.#isActive(guide.gate) && AgenticSurface.#guideApplies(viewKey, guide.scope))
+        .map((g) => g.text),
     };
   }
 
@@ -150,8 +192,8 @@ export class AgenticSurface {
 
   tool(name: string, view: string[] = []): ToolEntry | null {
     const viewKey = view.join(".");
-    const stack = this.#tools.get(name);
-    if (stack?.length && AgenticSurface.#within(viewKey, name)) return stack[stack.length - 1];
+    const shown = AgenticSurface.#shown(this.#tools.get(name));
+    if (shown && AgenticSurface.#within(viewKey, name)) return shown;
     for (const source of this.#sources) {
       const found = source.tools?.(view).find((candidate) => candidate.name === name);
       if (found) return found;
@@ -164,8 +206,7 @@ export class AgenticSurface {
    * what lets a host drop the built-in tools without dropping a screen's own tool that deliberately shadows one.
    */
   declares(name: string, view: string[] = []): boolean {
-    const stack = this.#tools.get(name);
-    return !!stack?.length && AgenticSurface.#within(view.join("."), name);
+    return !!AgenticSurface.#shown(this.#tools.get(name)) && AgenticSurface.#within(view.join("."), name);
   }
 
   /** Every call made through this surface, oldest first. What the dock shows the user to check against the screen. */
@@ -183,6 +224,8 @@ export class AgenticSurface {
     try {
       const verdict = entry.guard?.(args) ?? true;
       if (verdict !== true) throw new Error(verdict);
+      
+      if (!entry.run) throw new Error(`${name} is answered by the user, and this caller cannot ask them.`);
       return await entry.run(args);
     } catch (error) {
       record.error = error instanceof Error ? error.message : String(error);
@@ -231,9 +274,10 @@ export class AgenticSurface {
     const viewKey = view.join(".");
     const seen = new Set<string>();
     for (const [name, stack] of this.#tools) {
-      if (!AgenticSurface.#within(viewKey, name)) continue;
+      const shown = AgenticSurface.#shown(stack);
+      if (!shown || !AgenticSurface.#within(viewKey, name)) continue;
       seen.add(name);
-      yield [name, stack[stack.length - 1]];
+      yield [name, shown];
     }
     for (const source of this.#sources) {
       for (const entry of source.tools?.(view) ?? []) {
@@ -248,9 +292,10 @@ export class AgenticSurface {
     const viewKey = view.join(".");
     const seen = new Set<string>();
     for (const [name, stack] of this.#resources) {
-      if (!AgenticSurface.#within(viewKey, name)) continue;
+      const shown = AgenticSurface.#shown(stack);
+      if (!shown || !AgenticSurface.#within(viewKey, name)) continue;
       seen.add(name);
-      yield [name, stack[stack.length - 1]];
+      yield [name, shown];
     }
     for (const source of this.#sources) {
       for (const entry of source.resources?.(view) ?? []) {
@@ -263,8 +308,8 @@ export class AgenticSurface {
 
   #resource(name: string, view: string[] = []): ResourceEntry | null {
     const viewKey = view.join(".");
-    const stack = this.#resources.get(name);
-    if (stack?.length && AgenticSurface.#within(viewKey, name)) return stack[stack.length - 1];
+    const shown = AgenticSurface.#shown(this.#resources.get(name));
+    if (shown && AgenticSurface.#within(viewKey, name)) return shown;
     for (const source of this.#sources) {
       const found = source.resources?.(view).find((candidate) => candidate.name === name);
       if (found) return found;
@@ -283,23 +328,38 @@ export class AgenticSurface {
     return viewKey.startsWith(`${scopeKey}.`) || scopeKey.startsWith(`${viewKey}.`);
   }
 
-  #stack<E>(map: Map<string, E[]>, key: string, entry: E, clash: string | null = "is registered more than once") {
+  #duplicate<E>(map: Map<string, Registration<E>[]>, key: string, gate: AgentGate | null) {
+    return AgenticSurface.#shown(map.get(key)) && AgenticSurface.#isActive(gate)
+      ? "is registered more than once"
+      : null;
+  }
+
+  #stack<E>(map: Map<string, Registration<E>[]>, key: string, registration: Registration<E>, clash: string | null) {
     const stack = map.get(key) ?? [];
-    if (stack.length && clash && !this.#warned.has(key)) {
+    if (clash && !this.#warned.has(key)) {
       this.#warned.add(key);
       console.warn(`[use-agentic] "${key}" ${clash}; the newest registration wins.`);
     }
-    stack.push(entry);
+    stack.push(registration);
     map.set(key, stack);
     this.#notify();
     return () => {
-      const idx = stack.indexOf(entry);
+      const idx = stack.indexOf(registration);
       if (idx >= 0) stack.splice(idx, 1);
       if (!stack.length) map.delete(key);
       this.#notify();
     };
   }
 
+  /** The newest registration whose gate is active: a parked subtree keeps its place without shadowing anything. */
+  static #shown<E>(stack: Registration<E>[] | undefined): E | undefined {
+    return stack?.findLast((registration) => AgenticSurface.#isActive(registration.gate))?.entry;
+  }
+
+  static #isActive(gate: AgentGate | null) {
+    return gate?.active ?? true;
+  }
+
   #notify() {
     for (const listener of this.#listeners) listener();
   }