Add trusted handlers for addressable agent submissions

[FredKSchott]

Problem

Addressable agents currently process every dispatch() input through the coordinator model. Trusted 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 blocks applications that need deterministic orchestration around named subagents. A concrete example is Support Seal proposal generation:

• trusted Worker code hydrates Salesforce and derives verified customer scope;
• bounded router and proposal-writer profiles perform reasoning;
• trusted code must select the exact result schema, tools, retry/repair count, and companion escalation pass;
• image bytes must be attached directly to proposal-writer with session.task(..., { agent, result, tools, images, signal });
• image bytes must not pass through coordinator text, tool output, or persisted JSON commands.

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

Proposed API

Add an optional trusted handler for addressable dispatched submissions, for example:

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

Naming is flexible (onDispatch, handleSubmission, typed command handlers, etc.). Important properties:

1. Runs only in trusted application code, not as a model-callable tool.
2. Receives the initialized submission FlueSession (or a narrower trusted task runner), parsed input, abort signal, and submission/dispatch correlation.
3. Can invoke 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 can retain current model-driven behavior; the handler may initially apply only to dispatch() commands.
6. Handler output is the submission result and is observable through the normal stream/result surfaces.

A narrower alternative would expose a trusted task() runner instead of the full session.

Implementation observation

The internal boundary already exists in processSubmission(): it calls createAgentSubmissionSessionHandler(...), receives the initialized internal session, then calls session.processSubmissionInput(...). The smallest implementation may be to select the configured trusted dispatch handler at this point while preserving the existing onInputApplied, timeout, abort, journal, and settlement callbacks.

Why not an application workaround?

• Encoding base64 images in tool/model text is not multimodal and expands sensitive persistence/telemetry.
• Direct-agent { message, images } attaches images to the coordinator, not the isolated named subagent.
• Adding a workflow only to obtain ctx.init() recreates a workflow primitive the persistent-agent architecture is removing.
• Giving model-callable tools a session handle would weaken the current clean authority boundary.

This would also enable deterministic application command handling beyond images: schema-selected specialist calls, bounded repair loops, routing pipelines, and other agent-native orchestration without forcing a coordinator model turn.