Add pi.runWhenIdle() to schedule work after the agent has fully settled

[ronyrus]

What happened?

The example examples/extensions/reload-runtime.ts demonstrates an LLM-callable tool that queues /reload-runtime via sendUserMessage:

  pi.sendUserMessage("/reload-runtime", { deliverAs: "followUp" });
  return { content: [{ type: "text", text: "Queued /reload-runtime as a follow-up command." }] };

This does not work. The /reload-runtime string is sent to the LLM as a literal user message instead of dispatching the command.

The root cause is that sendUserMessage calls prompt() with expandPromptTemplates: false (agent-session.ts:1178), which skips the command dispatch branch at line 811:

  if (expandPromptTemplates && text.startsWith("/")) {
      const handled = await this._tryExecuteExtensionCommand(text);

Steps to reproduce

1. Enable the shipped reload-runtime example extension
2. Ask the agent to reload its runtime (trigger the reload_runtime tool)
3. Observe that /reload-runtime is sent to the LLM as text, not executed as a command

Expected behavior

/reload-runtime dispatched as a slash commands

Version

0.57.1

[ronyrus]

Related but separate: this bug surfaced while building a session-rollover extension that reacts to agent_end events and needs to call newSession, waitForIdle, etc.
These session-level operations only exist on ExtensionCommandContext (command handlers), not on ExtensionContext (event handlers and tools).

I currently used an ugly workaround of capturing command context refs into closure variables from a prior /rollover invocation, then calling them from event handlers later.
It works, but it's fragile - requires the user manually run a command at least once, and probably not the best context to actually call the API.

Would be great if session-level operations (or a subset) were somehow accessible from event handler or at least the ability to trigger slash command execution.

[badlogic]

Did a quick spike on this. I think what we need is a way for extensions to schedule work for when the agent is truely idle, allowing to mutate the session. I let the clanker summarize the spike results.

What I verified

• The shipped example is broken.
• Repro 1: while streaming, pi.sendUserMessage("/reload-runtime", { deliverAs: "followUp" }) results in command handler calls 0, and the follow-up queue contains literal "/reload-runtime".
• Repro 2: while streaming, session.prompt("/reload-runtime", { streamingBehavior: "followUp" }) results in command handler calls 1, and the follow-up queue stays empty.

Actual root cause

• sendUserMessage() normalizes content, then calls AgentSession.prompt() with expandPromptTemplates: false.
• Extension command dispatch only happens in prompt() via _tryExecuteExtensionCommand() before the streaming queue branch.
• Once a follow-up message is queued, it bypasses prompt() entirely and goes straight into agent.followUp(...), so there is no later chance to dispatch /reload-runtime as a command.
• So this is not just a bad flag. The deeper issue is that there is no safe deferred execution point for extension-side session mutation.
• Flipping expandPromptTemplates to true in sendUserMessage() would be wrong. That would execute the command immediately and ignore follow-up semantics.

What seems missing

• A one-shot deferred API, callable from tools and event handlers, roughly:
  • pi.runWhenIdle(async (ctx) => { ... })
• The callback context should expose the same safe session-control surface as command handlers, or a small IdleContext with the same methods:
  • waitForIdle()
  • newSession()
  • fork()
  • navigateTree()
  • switchSession()
  • reload()
• This solves the original reload example and also the related need from the issue comment, which is doing session-level work from event handlers without ugly command-context capture hacks.

Where the sync point should be

• Not at the agent_end extension event.
• The right insertion point is in AgentSession, after _processAgentEvent() completes, at the tail of _agentEventQueue, followed by a stronger quiescent-state check.
• runWhenIdle() should enqueue callbacks and schedule a drain attempt.
• Drain should also be attempted after every processed agent event and after any internal state transition that might make the session quiescent again.

What "truely idle" needs to mean

• !isStreaming
• !isRetrying
• !isCompacting
• !agent.hasQueuedMessages()
• no scheduled agent.continue() still pending
• pending bash messages flushed before running the callback
• current event-pipeline work already done, meaning _agentEventQueue has drained up to that point

Important trap

• AgentSession currently does deferred agent.continue() calls with setTimeout(...) in retry and auto-compaction paths.
• That creates a false-idle window unless scheduled continuation is tracked explicitly.
• Minimal fix there is not a giant scheduler. It is an explicit helper for continuation scheduling plus state, for example _continueScheduled, and then making idle checks include that state.

Minimal implementation shape

• Keep _agentEventQueue.
• Add an in-memory FIFO for idle callbacks.
• Add explicit scheduled-continuation tracking.
• Add something like:
  • _scheduleContinue(reason)
  • _isTruelyIdle()
  • _scheduleIdleDrain()
  • _drainIdleCallbacks()
• Drain one callback at a time.
• Re-check idle after each callback, because a callback may start new work.
• Route callback errors through the existing extension error plumbing.
• Drop pending idle callbacks on reload, so stale closures from the old runtime do not run after ctx.reload().

Files to read next session to get back up to speed

• packages/coding-agent/src/core/agent-session.ts
  • prompt()
  • _tryExecuteExtensionCommand()
  • sendUserMessage()
  • _handleAgentEvent()
  • _processAgentEvent()
  • _runAutoCompaction()
  • waitForRetry()
  • reload()
  • _flushPendingBashMessages()
• packages/coding-agent/src/core/extensions/types.ts
  • ExtensionAPI
  • ExtensionCommandContext
  • ExtensionActions
  • ExtensionRuntime
• packages/coding-agent/src/core/extensions/loader.ts
  • runtime stubs and pi.* API wiring
• packages/coding-agent/src/core/extensions/runner.ts
  • bindCore() and command-context binding
• packages/coding-agent/examples/extensions/reload-runtime.ts
• packages/coding-agent/examples/extensions/send-user-message.ts
• packages/coding-agent/docs/extensions.md
  • the reload example is currently documenting the broken pattern
• packages/coding-agent/test/agent-session-concurrent.test.ts
• packages/coding-agent/test/utilities.ts

Concretely, I would not implement this as a giant general scheduler for all session inputs. The scoped version above should be enough.

[badlogic]

Also related to #2110

[any-victor]

Another concrete motivating case for this issue: ttttmr/pi-context.

I’ve been analyzing a PR that adds persistent ACM auto-enable on session start:

• ttttmr/pi-context PR #10

The extension has a context_checkout flow that currently depends on a stored ExtensionCommandContext captured from a prior manual /acm invocation. Later, after preparing a branch summary, it uses CommandCtx.navigateTree(...) to switch the active branch.

That works only because the user manually ran /acm first.

The exact failure mode for auto-enable is:

• session_start can load config and activate the ACM guidance
• but session_start only gets ExtensionContext
• it cannot obtain navigateTree() because that exists only on ExtensionCommandContext
• tools also only receive ExtensionContext
• so "auto-enable" is incomplete: context_checkout still cannot fully work without a prior slash command just to capture command context

The repo owner summarized it well in the PR discussion: the design of /acm is mainly to obtain the command ctx, and if we cannot get that automatically, the configuration is not very useful.

That is why this issue looks like the correct home for the fix.

I agree with the direction in the owner spike here: a safe deferred session-mutation API is a better solution than a narrow one-off patch.

In particular, for pi-context, a callback like:

pi.runWhenIdle(async (ctx) => {
  await ctx.navigateTree(targetId, { summarize: false });
});

would be a clean replacement for the current fragile pattern of capturing command context from a manual command and reusing it later from event handlers.

So this issue is not only about the broken reload-runtime example. It also blocks a correct implementation of session-start auto-enable for extensions that need post-turn tree or session mutation.

[cmf]

current fragile pattern of capturing command context

My understanding after working on #2110 is that this pattern is not just fragile, it's also incorrect - it's not safe to use that command context to manipulate the tree unless you're sure that the session is truly idle, which is why the tree manipulation context is not available at points where you might expect it (e.g. after agent_end).