Add trusted handlers for addressable agent submissions

[FredKSchott]

Problem

Addressable agents currently process every dispatch() input through the coordinator model. Application code can configure the agent and expose model-callable tools, but it cannot handle a typed dispatched command with access to the initialized Flue session.

This limits applications that need deterministic orchestration around named subagents. For example, an application may need trusted code to:

• prepare and authorize bounded context before model execution;
• choose the exact specialist, result schema, and dynamic tool set;
• control bounded correction or repair passes;
• attach images directly to a vision-capable specialist with session.task(..., { agent, result, tools, images, signal });
• validate and finalize the specialist result before returning it.

Image bytes in particular should not need to pass through coordinator text, tool output, or persisted JSON commands.

Today, dispatch() accepts JSON-like input, createAgent() initialization receives no session or harness, and custom tools intentionally receive no session handle. Direct HTTP images attach to the coordinator turn and do not automatically propagate to isolated named subagents.

Possible API

Add an optional application-owned handler for addressable dispatched submissions, for example:

export default createAgent<Command, Env>(({ env }) => ({
  model: resolveModel(env),
  subagents: [specialist],
  onDispatch: async ({ input, session, signal, dispatchId }) => {
    const context = await prepareContext(input, env)
    const { data } = await session.task(JSON.stringify(context.args), {
      agent: "specialist",
      result: context.schema,
      tools: context.tools,
      images: context.images,
      signal,
    })
    return await context.finalize(data)
  },
}))

Naming is flexible (onDispatch, handleSubmission, typed command handlers, etc.). Useful properties would be:

1. Runs only in application code, not as a model-callable tool.
2. Receives the initialized submission FlueSession, or a narrower task runner, along with parsed input, an abort signal, and submission/dispatch correlation.
3. Can invoke declared named profiles using existing session.task() options, including structured result schemas, dynamic tools, and images.
4. Uses the existing durable submission lifecycle: admission, FIFO ordering, canonical input application, journaling, interruption handling, and terminal settlement.
5. Direct prompts may retain the current model-driven behavior; the handler could initially apply only to dispatch() commands.
6. The handler output becomes the submission result and remains observable through normal result/event surfaces.

A narrower alternative would expose a trusted task() runner rather than the full session.

Implementation observation

The internal boundary appears close to what is needed: submission processing initializes the agent session before applying the submission input. A possible implementation would select the configured dispatch handler at that boundary while preserving the existing input-application, timeout, abort, journal, recovery, and settlement behavior.

Why not an application workaround?

• Encoding base64 images in tool or model text is not equivalent to multimodal input and increases persistence and telemetry exposure.
• Direct-agent { message, images } attaches images to the coordinator rather than the isolated named subagent.
• Adding a workflow solely to obtain ctx.init() duplicates orchestration infrastructure for applications centered on persistent agents.
• Giving model-callable tools a session handle would weaken the current application/model authority boundary.

This could also support deterministic command handling beyond images: schema-selected specialist calls, bounded repair loops, routing pipelines, and similar orchestration without requiring a coordinator model turn.