@flue/sdk 0.3.5 → 0.3.6

package/dist/internal.d.mts

@@ -1,5 +1,5 @@
-import { S as SessionData, T as SessionStore } from "./types-T8pE1xIS.mjs";
-import "./mcp-BVF-sOBZ.mjs";
+import { S as SessionData, T as SessionStore } from "./types-CItTrBsU.mjs";
+import "./mcp-EZy-Vb5M.mjs";
 import { FlueContextConfig, FlueContextInternal, createFlueContext } from "./client.mjs";
 import { bashFactoryToSessionEnv } from "./sandbox.mjs";
 import { getModel } from "@mariozechner/pi-ai";
@@ -14,6 +14,267 @@ 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.
@@ -26,4 +287,4 @@ declare class InMemorySessionStore implements SessionStore {
  */
 declare function resolveModel(modelString: string): ReturnType<typeof getModel>;
 //#endregion
-export { type FlueContextConfig, type FlueContextInternal, InMemorySessionStore, bashFactoryToSessionEnv, createFlueContext, resolveModel };
+export { AgentNotFoundError, type FlueContextConfig, type FlueContextInternal, InMemorySessionStore, InvalidRequestError, MethodNotAllowedError, RouteNotFoundError, bashFactoryToSessionEnv, createFlueContext, parseJsonBody, resolveModel, toHttpResponse, toSseData, validateAgentRequest };