Support a user-controlled app/server entrypoint

[FredKSchott]

It would be useful for Flue projects to define their own application entrypoint, such as an app.ts or server.ts, that Flue can build around or mount into.

This would give projects a clear place to add middleware, configure cross-cutting server behavior, and handle concerns like authentication or request preprocessing before agent routes run.

[stainlu]

this feels like the right place for middleware/auth imo.

i would keep it as a composition boundary instead of a large Flue middleware API: user owns the app/server entry, Flue exposes a mount function for generated agent routes + manifest/health.

rough shape:

• user app runs auth / cors / rate limit / logging
• mountFlue(app, { basePath: "/agents" })
• agent handlers get portable request metadata from Pass the Hono request object into agent handlers #55
• generated deploy target still owns DO bindings, session stores, routes, etc.

then Flue does not need to invent app framework features, but users get real server control.

[ketankhairnar]

Strong +1 on the framing here, and on @stainlu's mountFlue(app, opts) shape. Keeps Flue out of the framework business while giving users real composition.

Two pieces of context from the code that I think shape the design:

1. Node and Cloudflare diverge today. Node entry already builds a new Hono() (packages/sdk/src/build-plugin-node.ts), but the Cloudflare entry hand-rolls export default { fetch(request, env) } and dispatches to routeAgentRequest (packages/sdk/src/build-plugin-cloudflare.ts). A "user exports a Hono app" contract is one-liner clean on Node, but requires the CF entry to also adopt Hono. Worth deciding up front, because it's the difference between a portable contract and a target-specific one.
2. The CF entry can't be fully replaced. It's also the host for per-agent DO classes and Sandbox re-exports. So on that target the contract has to be "mount into the generated default export," not "user owns the file."

Suggested ordering:

• Wait for Introduce flue.config.ts #52 (flue.config.ts) to land. That's the natural home for entry: './app.ts'.
• Wait for Pass the Hono request object into agent handlers #55. mountFlue is most useful when handlers have a portable request shape on FlueContext, which Pass the Hono request object into agent handlers #55 defines.
• Then design mountFlue(app, { basePath }) against both targets in one PR.

Happy to draft the design doc once #52 and #55 are in.

[FredKSchott]

tackling this tonight!

[FredKSchott]

Shipped in @flue/sdk@0.4.0: an optional app.ts (also .mts / .js / .mjs) at the source root lets you take over the request pipeline with custom Hono middleware, routes, and auth. Mount Flue's agent handler via app.route('/', flue()).

New @flue/sdk/app subpath export ships:

• flue() — Hono sub-app exposing /agents/:name/:id
• Fetchable — type for the user app's default export
• registerProvider(name, def) — register a new URL-prefix model provider at runtime, with platform env in scope
• configureProvider(slug, settings) — patch baseUrl / apiKey / headers / storeResponses on existing pi-ai catalog providers

Works on both Node and Cloudflare targets. Closing as resolved.