@camplax/plax 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 Camplax. All rights reserved.
+
+This software, including its source code, is proprietary to Camplax. You may
+use it only as part of the Camplax service and under the Camplax Terms of
+Service (https://camplax.dev/legal/terms). No other right to use, copy,
+modify, publish or distribute it, in whole or in part, is granted.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# @camplax/plax
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Plax is the Camplax app framework: a Node server with params and auth-guarded routes, Better Auth sessions, owner-scoped PostgreSQL resources, server-only AI, in-app agents with tools and budgets, a machine-readable manifest, doctor, and codegen.
+
+```ts
+import { createPlaxApp, defineResource, postgresStore, agent, tool } from "@camplax/plax";
+```
+
+Run an app with the `plax` command, the way a Next.js app runs with `next`:
+
+```sh
+plax dev     # run and restart on every change
+plax build   # type-check and confirm the entry
+plax start   # run for production
+```
+
+The entry is `src/server.ts`. `plax start` runs it in the same Node process (no child, no wrapper), on Node 22.18 or newer.
+
+CLI: `camplax create`, `camplax doctor`, `camplax check`, `camplax add resource|agent <name>`, `camplax add --list`.
+
+## Routes
+
+```ts
+const app = createPlaxApp({
+  session: sessionLookup,          // required if any route uses auth: true
+  staticDir: "public",             // static files + index.html SPA fallback
+  routes: {
+    "GET /probe": (req, res) => sendOk(res, { ok: true }),       // public
+    "GET /api/notes/:id": {                                       // authed —
+      auth: true,                                                 // ctx.user guaranteed
+      handler: (req, res, ctx) => sendOk(res, { id: ctx.params.id }),
+    },
+  },
+});
+```
+
+- `:param` segments capture into `ctx.params`; literal routes beat parameterized ones.
+- `{ auth: true }` resolves the session before the handler runs; no `session` lookup at boot = throw. Anonymous → 401.
+- Thrown `PlaxFail`s are sent as-is; other errors log server-side and return a generic 500 — internals never reach the client.
+- `readJsonBody(req)` parses with a 256 KB cap (throws `PayloadTooLargeError`).
+
+## Resources
+
+`defineResource` scopes list, get, update, and delete by `ownerField` (default `userId`) inside the database query. The client cannot set ids or owners; only `fields` are writable; `required` and `validate` gate creates. A row the user cannot read is 404, not 403.
+
+```ts
+export const notes = defineResource<Note>({
+  name: "notes",
+  fields: ["title"],
+  required: ["title"],
+  store: postgresStore<Note>({ client: db, table: "notes", columns: { id: "id", userId: "user_id", title: "title" } }),
+});
+
+routes: { ...notes.routes() }        // GET/POST /api/notes + GET/PATCH/DELETE /api/notes/:id
+resources: [notes],                  // lands in the manifest
+```
+
+`postgresStore` validates configured identifiers and parameterizes every value. `?limit`/`?offset` paginate lists within the store's cap. `memoryStore` backs tests.
+
+## In-app agents
+
+```ts
+const support = agent({
+  name: "support",
+  ai,                                   // createPlaxAi(...)
+  system: "You help users with their orders.",
+  tools: {
+    lookupOrder: tool({
+      args: { id: "string" },
+      run: ({ id }, { user }) => orders.get(user, id),  // owner-scoped — cannot cross users
+    }),
+  },
+  threads: postgresThreads(db),         // tables from `camplax add agent`
+  budget: { capUsdPerDay: 0.10, store: postgresBudget(db) },
+  approval: { refundOrder: "user" },    // named tools pause for approval
+});
+
+routes: { ...support.routes() }          // POST /api/support/chat, stream: true → SSE events
+agents: [support],
+```
+
+The loop: model → tool calls → validated args → run → results → repeat, capped by `maxSteps`. Approval-gated tools return `pendingApprovals`; the client POSTs `approve`/`deny` to resume. Budgets claim atomically before every model call (`429 budget_exceeded` when spent); the project's credit wallet still applies beneath.
+
+With `stream: true` the reply is SSE: `message_delta`/`reasoning_delta` carry tokens and thinking as they generate, `tool_call`/`tool_result` mark each step, and `message` + `done` close it out. `done` carries `usage` — prompt, completion, reasoning and cached tokens plus `costUsd`, summed over every model call in the turn (also on the JSON reply as `usage`). Reasoning is persisted on the thread and replayed to the model on later turns.
+
+`reasoning` sets how hard a reasoning model thinks: an effort (`reasoning: "high"`, `"none"` to switch it off), the full object (`{ max_tokens: 2000 }`, `{ effort: "medium", exclude: true }`), or `(user, input) => …` per request. It is sent on every step, tool calls included.
+
+## Upgrading from 0.0.x
+
+Two contracts changed:
+
+- Route handlers take `ctx` as the third argument, not `url`. Rename `url` → `ctx`; use `ctx.url`, `ctx.params`, and (on `auth: true` routes) `ctx.user`.
+- `resource.create`/`update` return `PlaxResult` (`{ ok: true, data }` or a `bad_request`/`not_found` failure) instead of the row — check `result.ok` before reading fields.
+
+## The manifest
+
+`app.manifest()` returns the app's surface — routes, resources, agents, env needs — as versioned JSON. `writeManifest(app.manifest(), dir)` from `@camplax/plax/inspect` writes `plax.manifest.json`. `camplax check` validates the app against it; coding agents read it instead of parsing source.
+
+## Entry points
+
+- `@camplax/plax` — server runtime (app, resources, sessions, AI, agents, manifest builder)
+- `@camplax/plax/doctor` — `camplax doctor` checks
+- `@camplax/plax/plugin` — component/plugin registry
+- `@camplax/plax/scaffold` — `camplax create` plumbing
+- `@camplax/plax/agents-md` — generated AGENTS.md
+- `@camplax/plax/inspect` — manifest file IO
+
+Platform helpers, also from `@camplax/plax`. None needs a key or a secret set; they use what Camplax injects:
+
+- `verifyCronRequest` — check a cron, one-off or workflow call was signed by Camplax
+- `verifyCamplaxWebhook` — check a project webhook, log drain, alert or status-page call was signed by Camplax
+- `createPlaxEmail` — send mail, claim inboxes and receive what arrives
+- `createPlaxRealtime` — publish to channels and mint tokens for signed-in users
+- `createPlaxEvents` — send events that start or resume workflows
+- `createPlaxKv` — a key/value store on the app's own Postgres
+- `postgresQueues` — durable queues on the app's own Postgres
+
+The package is set up to publish publicly (`publishConfig.access` is `public`). Publish it with pnpm (`pnpm publish --access public`), never npm: npm ignores `publishConfig.exports`. Do not put secrets in client files. A resource the user cannot read or mutate is 404, not 403.

package/bin/plax.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * The `plax` command — `plax dev`, `plax build`, `plax start`.
+ *
+ * Plain JavaScript on purpose: it runs before anything has been type-checked,
+ * from a vendored copy (vendor/plax) as well as the published package, and it
+ * keeps Plax's zero-dependency rule (node: builtins only).
+ *
+ * `plax start` imports the app in this same process instead of spawning a
+ * child, so production runs one Node process — the ~40–50 MB idle footprint
+ * is the reason Plax exists. The pnpm/npm .bin shim `exec`s node, so nothing
+ * else stays resident either.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const ENTRIES = ["src/server.ts", "src/server.js", "server.ts", "server.js"];
+
+const HELP = `Plax — the Camplax app framework.
+
+Usage:
+  plax dev [entry] [--port <n>]   Run the app and restart it when a file changes
+  plax build                      Check the app is ready to deploy (types and entry)
+  plax start [entry]              Run the app for production
+  plax --version                  Print the Plax version
+
+The entry defaults to src/server.ts.`;
+
+function fail(message) {
+  console.error(`plax: ${message}`);
+  process.exit(1);
+}
+
+function version() {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  return String(pkg.version ?? "0.0.0");
+}
+
+/**
+ * Node runs the app's TypeScript by stripping types. That is on by default
+ * from Node 22.18 / 23.6; older versions need a flag Plax cannot add to a
+ * process that is already running.
+ */
+function requireTypeStripping(entry) {
+  if (!entry.endsWith(".ts")) return;
+  if (process.features?.typescript) return;
+  fail(`this app is TypeScript and Node ${process.versions.node} cannot run it. Plax needs Node 22.18 or newer (24 recommended).`);
+}
+
+function parse(argv) {
+  const args = { entry: null, port: null };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--port" || arg === "-p") {
+      const value = argv[++i];
+      if (!value || !/^\d+$/.test(value)) fail("--port needs a number.");
+      args.port = value;
+    } else if (arg.startsWith("--port=")) {
+      const value = arg.slice("--port=".length);
+      if (!/^\d+$/.test(value)) fail("--port needs a number.");
+      args.port = value;
+    } else if (arg.startsWith("-")) {
+      fail(`unknown option ${arg}. Run plax --help.`);
+    } else if (args.entry === null) {
+      args.entry = arg;
+    } else {
+      fail(`unexpected argument ${arg}. Run plax --help.`);
+    }
+  }
+  return args;
+}
+
+function findEntry(cwd, explicit) {
+  if (explicit) {
+    const path = resolve(cwd, explicit);
+    if (!existsSync(path)) fail(`no app entry at ${explicit}.`);
+    return path;
+  }
+  for (const candidate of ENTRIES) {
+    const path = join(cwd, candidate);
+    if (existsSync(path)) return path;
+  }
+  fail(`no app entry found. Plax looks for ${ENTRIES.join(", ")}.`);
+}
+
+/**
+ * The app's own TypeScript compiler script, run with this Node — no .bin
+ * shim and no shell, so it behaves the same on Linux builders and Windows.
+ */
+function findTsc(cwd) {
+  try {
+    const require = createRequire(join(cwd, "package.json"));
+    const pkgPath = require.resolve("typescript/package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.tsc;
+    return bin ? join(dirname(pkgPath), bin) : null;
+  } catch {
+    return null;
+  }
+}
+
+function run(script, args, cwd) {
+  return new Promise((done) => {
+    const child = spawn(process.execPath, [script, ...args], { cwd, stdio: "inherit" });
+    child.on("error", () => done(1));
+    child.on("exit", (code, signal) => done(signal ? 1 : (code ?? 1)));
+  });
+}
+
+async function dev(cwd, argv) {
+  const { entry: explicit, port } = parse(argv);
+  const entry = findEntry(cwd, explicit);
+  requireTypeStripping(entry);
+  const env = { ...process.env };
+  if (port) env.PORT = port;
+  // --watch restarts on any change to a file the app imports.
+  const child = spawn(process.execPath, ["--watch", entry], { cwd, env, stdio: "inherit" });
+  const forward = (signal) => child.kill(signal);
+  process.on("SIGINT", forward);
+  process.on("SIGTERM", forward);
+  child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+}
+
+async function build(cwd, argv) {
+  const { entry: explicit } = parse(argv);
+  const entry = findEntry(cwd, explicit);
+  console.log(`plax: entry ${relative(cwd, entry).replace(/\\/g, "/")}`);
+  if (!existsSync(join(cwd, "tsconfig.json"))) {
+    console.log("plax: no tsconfig.json, skipping the type check.");
+    return;
+  }
+  const tsc = findTsc(cwd);
+  if (!tsc) fail("could not find TypeScript. Add typescript to devDependencies.");
+  console.log("plax: checking types…");
+  const code = await run(tsc, ["--noEmit"], cwd);
+  if (code !== 0) process.exit(code);
+  console.log("plax: ready to deploy.");
+}
+
+async function start(cwd, argv) {
+  const { entry: explicit, port } = parse(argv);
+  if (port) process.env.PORT = port;
+  const entry = findEntry(cwd, explicit);
+  requireTypeStripping(entry);
+  await import(pathToFileURL(entry).href);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+const cwd = process.cwd();
+
+switch (command) {
+  case "dev":
+    await dev(cwd, rest);
+    break;
+  case "build":
+    await build(cwd, rest);
+    break;
+  case "start":
+    await start(cwd, rest);
+    break;
+  case "--version":
+  case "-v":
+    console.log(version());
+    break;
+  case undefined:
+  case "help":
+  case "--help":
+  case "-h":
+    console.log(HELP);
+    break;
+  default:
+    fail(`unknown command ${command}. Run plax --help.`);
+}

package/dist/agent.d.ts

@@ -0,0 +1,316 @@
+import type { PlaxAi, PlaxAiEffort, PlaxAiFailCode, PlaxAiReasoning } from "./ai.ts";
+import type { ToolCallWire } from "./stream.ts";
+import type { PlaxRouteMap } from "./app.ts";
+import { type PlaxResult } from "./errors.ts";
+import type { PlaxUser } from "./session.ts";
+import type { SqlClient } from "./postgres.ts";
+import type { PlaxEvents } from "./events.ts";
+/**
+ * plax.agent() — an in-app agent. One loop: model → tool calls → results →
+ * repeat, capped. Tools run through the app's own resources, so an agent
+ * cannot read another user's rows. Threads are rows in the app's database.
+ * Spend draws the project's prepaid credits, capped per end-user.
+ */
+export type PlaxToolCtx = {
+    user: PlaxUser;
+};
+/** Minimal Standard Schema shape (zod v4, valibot, arktype all expose it). */
+type StandardSchemaLike = {
+    "~standard": {
+        validate: (input: unknown) => {
+            value?: unknown;
+            issues?: {
+                message: string;
+            }[];
+        } | Promise<{
+            value?: unknown;
+            issues?: {
+                message: string;
+            }[];
+        }>;
+    };
+};
+/** Shape map: `{ id: "string", count: "number?" }` — `?` marks optional. */
+export type PlaxToolArgs = Record<string, "string" | "number" | "boolean" | "object" | "array" | `${"string" | "number" | "boolean" | "object" | "array"}?`> | StandardSchemaLike;
+export type PlaxTool<A = Record<string, unknown>> = {
+    description?: string;
+    args?: PlaxToolArgs;
+    /**
+     * Model-facing JSON Schema for the arguments. Required for Standard-Schema
+     * `args` — they validate but cannot describe themselves to the model, so
+     * without this the model sees an empty parameter list and guesses.
+     */
+    parameters?: Record<string, unknown>;
+    run: (args: A, ctx: PlaxToolCtx) => unknown | Promise<unknown>;
+};
+export declare function tool<A = Record<string, unknown>>(spec: PlaxTool<A>): PlaxTool<A>;
+/**
+ * A tool of any argument type — what `agent({ tools })` holds. `run`'s
+ * parameter is contravariant, so `PlaxTool<{ fact: string }>` is not a
+ * `PlaxTool<Record<string, unknown>>`; every `PlaxTool<A>` is a
+ * `PlaxTool<never>`. The agent validates the model's arguments against
+ * `args` before it calls `run`, which is what makes the one cast there safe.
+ */
+export type AnyPlaxTool = PlaxTool<never>;
+export type AgentMessage = {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    toolCalls?: ToolCallWire[];
+    toolCallId?: string;
+    name?: string;
+    /** The model's thinking text for this turn — persisted for display. */
+    reasoning?: string | null;
+    /** Raw reasoning_details, replayed to the model verbatim on later turns. */
+    reasoningDetails?: Record<string, unknown>[] | null;
+};
+export type { ToolCallWire };
+/** An image on a user message: a URL string, or `{ url, detail }`. */
+export type AgentImage = string | {
+    url: string;
+    detail?: "auto" | "low" | "high";
+};
+/** One entry in a user's thread list. */
+export type AgentThreadSummary = {
+    id: string;
+    title: string | null;
+    createdAt: string;
+};
+/** A thread as its owner saw it: user and assistant text only, oldest first. */
+export type AgentThreadView = AgentThreadSummary & {
+    messages: {
+        role: "user" | "assistant";
+        content: string;
+    }[];
+};
+/**
+ * Thread persistence. postgresThreads in production, memoryThreads in tests.
+ * `history` returns the whole thread — long threads grow context and cost, so
+ * apps expecting long sessions should window what they store or send.
+ * `list`/`get`/`delete` take the user and apply the owner clause themselves.
+ */
+export type AgentThreads = {
+    /** Verify the thread belongs to the user. Returns false when not found/owned. */
+    owns(user: PlaxUser, threadId: string): Promise<boolean>;
+    create(user: PlaxUser, title?: string): Promise<string>;
+    append(threadId: string, message: AgentMessage): Promise<void>;
+    history(threadId: string): Promise<AgentMessage[]>;
+} & Partial<AgentThreadHistory>;
+/**
+ * What a store needs for agent.routes() to mount the history routes. The
+ * built-in stores implement it; a custom store that does not still works for
+ * chat and simply gets no history routes.
+ */
+export type AgentThreadHistory = {
+    /** The user's threads, newest first — `limit` defaults to 50, capped at 100. */
+    list(user: PlaxUser, opts?: {
+        limit?: number;
+    }): Promise<AgentThreadSummary[]>;
+    /**
+     * One thread's visible messages (the most recent 500), owner-scoped in the
+     * same lookup. Null when the thread is missing or belongs to someone else.
+     */
+    get(user: PlaxUser, threadId: string): Promise<AgentThreadView | null>;
+    /** Delete an owned thread and its messages. False when missing or not owned. */
+    delete(user: PlaxUser, threadId: string): Promise<boolean>;
+};
+type MemoryThread = {
+    userId: string;
+    title: string | null;
+    createdAt: Date;
+    seq: number;
+    messages: AgentMessage[];
+};
+export declare function memoryThreads(): AgentThreads & AgentThreadHistory & {
+    threads: Map<string, MemoryThread>;
+};
+/**
+ * Threads on the app's own Postgres. Tables come from the `camplax add agent`
+ * migration — this store never creates them, so a missing table fails loudly.
+ */
+export declare function postgresThreads(client: SqlClient, opts?: {
+    threadsTable?: string;
+    messagesTable?: string;
+}): AgentThreads & AgentThreadHistory;
+/** Per-end-user AI spend cap, enforced before each model call. */
+export type AgentBudget = {
+    /** USD already spent by this user in the current window (UTC day). */
+    spentToday(userId: string): Promise<number>;
+    /**
+     * Atomically add `usd` to today's spend under `capUsd`: returns false when
+     * the addition would exceed the cap and nothing is recorded. Check-and-
+     * increment in one operation — concurrent requests cannot both pass.
+     */
+    claim(userId: string, usd: number, capUsd: number): Promise<boolean>;
+    /** Post-hoc adjustment — settles the real cost after `claim` reserved a floor. */
+    record(userId: string, usd: number): Promise<void>;
+};
+export declare function memoryBudget(): AgentBudget;
+/** Budget on `plax_usage(user_id, day, usd)` — created by the agent migration. */
+export declare function postgresBudget(client: SqlClient, opts?: {
+    table?: string;
+}): AgentBudget;
+/**
+ * What one respond() spent, summed over every model call it made. Token
+ * counts come from the provider's usage report; `costUsd` is the provider's
+ * dollar figure (the gateway reports it) — null when no call reported one.
+ */
+export type AgentUsage = {
+    promptTokens: number;
+    completionTokens: number;
+    /** Thinking tokens — billed as completion tokens, reported separately. */
+    reasoningTokens: number;
+    /** Prompt tokens served from the provider's cache. */
+    cachedTokens: number;
+    costUsd: number | null;
+    /** Model calls made. */
+    calls: number;
+};
+export type AgentEvent = {
+    type: "thread";
+    threadId: string;
+} | {
+    type: "message_delta";
+    content: string;
+} | {
+    type: "reasoning_delta";
+    content: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: "tool_result";
+    id: string;
+    name: string;
+    ok: boolean;
+    result: unknown;
+} | {
+    type: "approval_required";
+    calls: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }[];
+} | {
+    type: "message";
+    content: string;
+} | {
+    type: "error";
+    error: string;
+    code: string;
+    href?: string;
+}
+/** Always the last event. `usage` is set once at least one model call ran. */
+ | {
+    type: "done";
+    usage?: AgentUsage;
+};
+export type AgentReply = {
+    threadId: string | null;
+    message: string;
+    toolCalls: {
+        id: string;
+        name: string;
+    }[];
+    /** Set when the loop paused for tool approval — POST back with approve/deny. */
+    pendingApprovals?: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }[];
+    steps: number;
+    /** Tokens and dollars this reply spent; absent when no model call ran. */
+    usage?: AgentUsage;
+};
+export type AgentInput = {
+    threadId?: string;
+    message?: string;
+    /**
+     * Images on this user message, for a vision model: https URLs or
+     * `data:image/…;base64,` URLs, at most 8. Sent with this turn; the thread
+     * keeps the text and an "[N images attached]" note, not the images.
+     */
+    images?: AgentImage[];
+    /** Tool-call ids to approve or deny on a paused loop. */
+    approve?: string[];
+    deny?: string[];
+    /**
+     * Stream the model calls — the client gets `message_delta` and
+     * `reasoning_delta` events as tokens arrive, not one message at the end.
+     * The route sets this from `body.stream`.
+     */
+    stream?: boolean;
+    /** Aborts the run and the in-flight model call (client disconnects, etc.). */
+    signal?: AbortSignal;
+    onEvent?: (event: AgentEvent) => void;
+};
+/**
+ * A value fixed at construction, or computed per request from the signed-in
+ * user and the input — resolved once at the start of each respond().
+ */
+export type AgentPerRequest<T> = T | ((user: PlaxUser, input: AgentInput) => T | Promise<T>);
+export type PlaxAgentOptions = {
+    /** Slug — used for the default route path and manifest. */
+    name: string;
+    /** The server-side AI client from createPlaxAi. */
+    ai: PlaxAi;
+    /**
+     * Model id, or `(user, input) => id` for a per-user choice (a plan or a
+     * feature flag). Default `openai/gpt-4.1-mini`; an empty result falls back to it.
+     */
+    model?: AgentPerRequest<string>;
+    /**
+     * How hard a reasoning model thinks: an effort (`"low"` … `"xhigh"`, or
+     * `"none"` to switch thinking off) or the full reasoning object
+     * (`{ max_tokens: 2000 }`, `{ effort: "high", exclude: true }`). Or
+     * `(user, input) => …` for a per-user choice. Sent on every model call of
+     * the turn, tools included; thinking streams as `reasoning_delta`. Unset,
+     * the model's own default applies. Models that cannot think ignore it.
+     */
+    reasoning?: AgentPerRequest<PlaxAiEffort | PlaxAiReasoning | undefined>;
+    /**
+     * System prompt, or `(user, input) => prompt` — load per-user memory or
+     * preferences here instead of building a new agent on every request.
+     */
+    system?: AgentPerRequest<string>;
+    tools?: Record<string, AnyPlaxTool>;
+    threads?: AgentThreads;
+    budget?: {
+        capUsdPerDay: number;
+        store: AgentBudget;
+    };
+    /** Tools listed here pause for explicit user approval before running. Requires threads. */
+    approval?: Record<string, "user">;
+    /**
+     * Tell Camplax workflows about approvals (createPlaxEvents()). A paused
+     * loop sends `agent.approval_requested` { agent, threadId, userId, calls };
+     * approving or denying sends `agent.approval_resolved` { agent, threadId,
+     * userId, approved, denied }. A workflow waits on the second one — match
+     * `threadId`, time out after a day — instead of polling the thread.
+     * A failed send is logged and never fails the chat reply.
+     */
+    events?: PlaxEvents;
+    /** Max model→tool round trips per message. Default 8. */
+    maxSteps?: number;
+    /**
+     * Byte cap on the chat route's JSON body. Default 256 KB — raise it when
+     * clients POST images as data URLs (a phone photo is several MB).
+     */
+    maxBodyBytes?: number;
+};
+export declare function agent(opts: PlaxAgentOptions): {
+    name: string;
+    respond: (user: PlaxUser, input: AgentInput) => Promise<PlaxResult<AgentReply, "not_found" | "bad_request" | "failed" | "budget_exceeded" | PlaxAiFailCode>>;
+    routes: (path?: string, threadsPath?: string | false) => PlaxRouteMap;
+    manifest: {
+        model: string;
+        tools: string[];
+        budget?: {
+            capUsdPerDay: number;
+        } | undefined;
+        threads?: true | undefined;
+    };
+};
+export type PlaxAgent = ReturnType<typeof agent>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/agents-md.d.ts

@@ -0,0 +1,3 @@
+/** Default AGENTS.md for a Plax app. Coding agents should read this first. */
+export declare function plaxAgentsMd(): string;
+//# sourceMappingURL=agents-md.d.ts.map

package/dist/agents-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md.d.ts","sourceRoot":"","sources":["../src/agents-md.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAE9E,wBAAgB,YAAY,IAAI,MAAM,CA4ErC"}