@flue/sdk 0.3.11 → 0.4.1

package/dist/internal.d.mts

@@ -1,7 +1,10 @@
-import { O as SessionStore, S as ProvidersConfig, T as SessionData, v as ModelConfig } from "./types-DGpyKMFm.mjs";
+import { A as SessionStore, D as SessionData, v as ModelConfig } from "./types-BAmV4f3Q.mjs";
 import { FlueContextConfig, FlueContextInternal, createFlueContext } from "./client.mjs";
+import { a as AgentHandler, c as RunHandlerFn, l as StartWebhookFn, n as configureFlueRuntime, o as CreateContextFn, r as createDefaultFlueApp, s as HandleAgentOptions, t as FlueRuntime, u as handleAgentRequest } from "./flue-app-CG8i4wNG.mjs";
 import { bashFactoryToSessionEnv } from "./sandbox.mjs";
-import { getModel } from "@mariozechner/pi-ai";
+import { Api, Model } from "@mariozechner/pi-ai";
+import { AgentMessage } from "@mariozechner/pi-agent-core";
+
 //#region src/session.d.ts
 /** In-memory session store. Sessions persist for the lifetime of the process. */
 declare class InMemorySessionStore implements SessionStore {
@@ -11,277 +14,11 @@ declare class InMemorySessionStore implements SessionStore {
   delete(id: string): Promise<void>;
 }
 //#endregion
-//#region src/errors.d.ts
-/**
- * Concrete error classes thrown by Flue.
- *
- * This file is the *vocabulary* of errors in Flue. Every error the framework
- * throws has a class here. The framework scaffolding (base class, renderers,
- * type guards, request-parsing helpers) lives in `error-utils.ts`.
- *
- * ──── Why this file exists ────────────────────────────────────────────────
- *
- * Concentrating every error in one file is deliberate. When all errors are
- * visible together, it's easy to:
- *
- *   - Keep message tone and detail level consistent across the codebase.
- *   - Notice duplicates ("oh, we already have an error for this case").
- *   - Establish norms by example — when adding a new error, look at the
- *     neighbors above and copy the pattern.
- *
- * Application code throughout the codebase should reach for one of these
- * classes rather than constructing a `FlueError` ad hoc. If no existing class
- * fits, add one here. That's the entire convention.
- *
- * ──── Two audiences: caller vs. developer ─────────────────────────────────
- *
- * The reader of an error message is one of two distinct audiences:
- *
- *   - The *caller*: an HTTP client. Possibly third-party, possibly hostile,
- *     possibly an end user who shouldn't even know we're built on Flue.
- *     Sees `message` and `details` always.
- *
- *   - The *developer*: the human running the service (`flue dev`, `flue run`,
- *     local debugging). Sees `dev` in addition, but only when the server is
- *     running in local/dev mode (gated by `FLUE_MODE=local`).
- *
- * Every error class must classify its prose by audience. The required-but-
- * possibly-empty shape of both `details` and `dev` is the discipline:
- * forgetting either field is a TypeScript error, and writing `''` is a
- * deliberate "I have nothing for that audience" decision.
- *
- * Concretely:
- *
- *   - `message`     One sentence. Caller-safe. Always rendered.
- *   - `details`     Longer caller-safe prose. About the request itself, the
- *                   contract, what the caller can do to fix it. Always
- *                   rendered. NEVER includes:
- *                     - sibling/neighbor enumeration (leaks namespace)
- *                     - filesystem paths or "agents/" / "skills/" / etc.
- *                       (leaks framework internals)
- *                     - source-code-level fix instructions ("add ... to your
- *                       agent definition") (caller can't act on these)
- *                     - build-time or runtime mechanics
- *   - `dev`         Longer dev-audience prose. Available alternatives,
- *                   filesystem layout, framework guidance, source-code-level
- *                   fix instructions. Rendered ONLY when FLUE_MODE=local.
- *
- * When in doubt, put information in `dev`. The default is conservative.
- *
- * ──── Conventions for new error classes ───────────────────────────────────
- *
- *   - Class name: PascalCase, suffixed with `Error`. E.g. `AgentNotFoundError`.
- *   - The class owns its `type` constant (snake_case). Set once in the
- *     subclass constructor, never passed by callers. Renaming the wire type
- *     is then a one-line change.
- *   - Constructor takes ONLY structured input data (the values used to build
- *     the message). The constructor assembles `message`, `details`, and
- *     `dev` from that data, so call sites never reinvent phrasing.
- *   - `details` and `dev` are both required strings. Pass `''` only when
- *     there's genuinely nothing more to say for that audience.
- *   - For HTTP errors, the class sets its own `status` (and `headers` where
- *     relevant). Callers do not pick HTTP status codes ad-hoc.
- *
- * Worked example (matches `AgentNotFoundError` below):
- *
- *     new AgentNotFoundError({ name, available });
- *     // builds:
- *     //   message: `Agent "foo" is not registered.`
- *     //   details: `Verify the agent name is correct.`
- *     //   dev:     `Available agents: "echo", "greeter". Agents are
- *     //            loaded from the workspace's "agents/" directory at
- *     //            build time. ...`
- *
- * The wire response in production omits `dev`; in `flue dev` / `flue run`
- * it includes `dev`. That separation is what lets the dev field be richly
- * helpful without leaking namespace state to public callers.
- *
- * Counter-example to avoid:
- *
- *     class AgentNotFoundError extends FlueHttpError {
- *       constructor(message: string) {                       // ✗ free-form
- *         super({                                            // ✗ wrong type
- *           type: 'agent_error',
- *           message,
- *           details: 'Available: "x", "y", "z"',             // ✗ leaks names
- *           dev: '',                                         // ✗ wasted channel
- *           status: 500,                                     // ✗ wrong status
- *         });
- *       }
- *     }
- *
- * The structured-constructor pattern below is what prevents that drift.
- */
-interface FlueErrorOptions {
-  /**
-   * Stable, machine-readable identifier (snake_case). Set once per subclass.
-   * Callers don't pass this — the subclass constructor does.
-   */
-  type: string;
-  /**
-   * One-sentence summary of what went wrong. Caller-safe — always rendered
-   * on the wire.
-   */
-  message: string;
-  /**
-   * Caller-audience longer-form explanation. Always rendered on the wire.
-   *
-   * Must be safe to expose to any HTTP client, including third-party or
-   * hostile callers. Do NOT include sibling enumeration, filesystem paths,
-   * framework-internal mechanics, or source-code fix instructions — those
-   * belong in `dev`.
-   *
-   * Required: pass `''` only when there's genuinely nothing more to say to
-   * the caller. The required-but-possibly-empty shape is intentional — it
-   * forces a deliberate decision rather than a thoughtless omission.
-   */
-  details: string;
-  /**
-   * Developer-audience longer-form explanation. Rendered on the wire ONLY
-   * when the server is running in local/dev mode (FLUE_MODE=local).
-   *
-   * Use this for everything that helps the developer running the service
-   * but shouldn't reach a public caller: available alternatives, filesystem
-   * paths, framework guidance, source-code fix instructions, configuration
-   * hints.
-   *
-   * Required: pass `''` only when there's genuinely nothing dev-specific
-   * to add (e.g. a malformed-JSON error has nothing to say to the dev that
-   * isn't already in `details`).
-   */
-  dev: string;
-  /**
-   * Optional structured machine-readable data. Use only when downstream
-   * tooling genuinely benefits — most errors should leave this unset.
-   */
-  meta?: Record<string, unknown>;
-  /**
-   * The underlying error, when wrapping. Logged server-side; never sent
-   * over the wire.
-   */
-  cause?: unknown;
-}
-/**
- * Base class for every error Flue throws. Do not instantiate directly in
- * application code — extend it via a subclass below. If a use case isn't
- * covered, add a new subclass here rather than throwing a raw `FlueError`.
- */
-declare class FlueError extends Error {
-  readonly type: string;
-  readonly details: string;
-  readonly dev: string;
-  readonly meta: Record<string, unknown> | undefined;
-  readonly cause: unknown;
-  constructor(options: FlueErrorOptions);
-}
-interface FlueHttpErrorOptions extends FlueErrorOptions {
-  /** HTTP status code (4xx or 5xx). */
-  status: number;
-  /** Additional response headers (e.g. `Allow` for 405). */
-  headers?: Record<string, string>;
-}
-/**
- * Base class for HTTP-layer errors. Adds `status` and optional `headers`.
- * Subclasses set these in the `super({...})` call so the call site doesn't
- * have to think about HTTP semantics.
- */
-declare class FlueHttpError extends FlueError {
-  readonly status: number;
-  readonly headers: Record<string, string> | undefined;
-  constructor(options: FlueHttpErrorOptions);
-}
-declare class MethodNotAllowedError extends FlueHttpError {
-  constructor({
-    method,
-    allowed
-  }: {
-    method: string;
-    allowed: readonly string[];
-  });
-}
-declare class AgentNotFoundError extends FlueHttpError {
-  constructor({
-    name,
-    available
-  }: {
-    name: string;
-    available: readonly string[];
-  });
-}
-declare class RouteNotFoundError extends FlueHttpError {
-  constructor({
-    method,
-    path
-  }: {
-    method: string;
-    path: string;
-  });
-}
-declare class InvalidRequestError extends FlueHttpError {
-  constructor({
-    reason
-  }: {
-    reason: string;
-  });
-}
-//#endregion
-//#region src/error-utils.d.ts
-/**
- * Render any thrown value into a `Response` with the canonical Flue error
- * envelope. Unknown / non-Flue errors are logged in full and rendered as a
- * generic 500 with no message leaked.
- */
-declare function toHttpResponse(err: unknown): Response;
-/**
- * Render any thrown value into a JSON string suitable for the `data:` line of
- * an SSE `error` event. Same envelope as `toHttpResponse`. Unknown / non-Flue
- * errors are logged and replaced with a generic envelope.
- */
-declare function toSseData(err: unknown): string;
-/**
- * Parse a request body as JSON. Returns `{}` for genuinely empty bodies
- * (Content-Length: 0 or missing) so that webhook agents which don't accept
- * a payload can be invoked without one.
- *
- * Throws `UnsupportedMediaTypeError` if a body is present without
- * `application/json` content-type, and `InvalidJsonError` if the body is
- * present but unparseable.
- */
-declare function parseJsonBody(request: Request): Promise<unknown>;
-/**
- * Validate that a request targeting `/agents/<name>/<id>` is well-formed:
- * method is POST, agent name is registered, and (optionally) the agent is
- * webhook-accessible. Throws the appropriate FlueHttpError on any failure.
- *
- * Path/id validation is light: we reject empty or whitespace-only segments
- * but otherwise let the URL parser's segment splitting be the source of
- * truth. The Cloudflare partyserver layer additionally enforces shape via
- * `routeAgentRequest`; the Node Hono layer via route patterns.
- */
-interface ValidateAgentRequestOptions {
-  method: string;
-  name: string;
-  id: string;
-  registeredAgents: readonly string[];
-  webhookAgents: readonly string[];
-  /**
-   * If true, skip the webhook-accessibility check. Used by `flue run` /
-   * dev local mode where trigger-less agents are also invokable.
-   */
-  allowNonWebhook?: boolean;
-}
-declare function validateAgentRequest(opts: ValidateAgentRequestOptions): void;
-//#endregion
 //#region src/internal.d.ts
 /**
- * Resolve a `provider/model-id` string into a pi-ai `Model` object.
- * Lives here (rather than in the generated entry point) so that user
- * projects don't have to declare `@mariozechner/pi-ai` as a direct
- * dependency — wrangler's bundler resolves bare specifiers from the entry
- * file's location, which on pnpm-isolated installs doesn't see Flue's
- * transitive deps. Centralizing the resolver here keeps `_entry.ts`
- * dependency-free apart from `@flue/sdk/*`.
+ * Resolve `provider/model-id` to a pi-ai Model. Registered URL prefixes win
+ * over pi-ai's catalog; configureProvider settings patch the resolved Model.
  */
-declare function resolveModel(model: ModelConfig | undefined, providers?: ProvidersConfig): ReturnType<typeof getModel> | undefined;
+declare function resolveModel(model: ModelConfig | undefined): Model<Api> | undefined;
 //#endregion
-export { AgentNotFoundError, type FlueContextConfig, type FlueContextInternal, InMemorySessionStore, InvalidRequestError, MethodNotAllowedError, RouteNotFoundError, bashFactoryToSessionEnv, createFlueContext, parseJsonBody, resolveModel, toHttpResponse, toSseData, validateAgentRequest };
+export { type AgentHandler, type CreateContextFn, type FlueContextConfig, type FlueContextInternal, type FlueRuntime, type HandleAgentOptions, InMemorySessionStore, type RunHandlerFn, type StartWebhookFn, bashFactoryToSessionEnv, configureFlueRuntime, createDefaultFlueApp, createFlueContext, handleAgentRequest, resolveModel };