@cybernetyx1/atlasflow-runtime 0.1.0

package/dist/node/index.d.ts

@@ -0,0 +1,65 @@
+import { ExecFileOptions } from 'node:child_process';
+import { C as Command, a as CommandExecutor, S as SandboxNetworkPolicy, b as SandboxFactory } from '../command-kxrqWIH7.js';
+import { Hono } from 'hono';
+
+type CommandOptions = ExecFileOptions;
+declare function defineCommand(name: string): Command;
+declare function defineCommand(name: string, options: CommandOptions): Command;
+declare function defineCommand(name: string, execute: CommandExecutor): Command;
+
+/**
+ * Local sandbox — host-mounted just-bash by default, or explicit host shell.
+ *
+ * SECURITY: raw host mode gives the agent direct access to the host machine's
+ * shell and filesystem. Use it only in development or in an already-isolated
+ * environment (container, VM, CI runner). For untrusted workloads use the
+ * default virtual mode or an isolated sandbox provider.
+ */
+
+interface LocalSandboxOptions {
+    /**
+     * "host" executes commands with the OS shell. "virtual" mounts `cwd` into
+     * just-bash at `mountPath` and supports scoped `defineCommand` grants.
+     * Defaults to "virtual".
+     */
+    mode?: "host" | "virtual";
+    cwd?: string;
+    env?: Record<string, string>;
+    /**
+     * Environment inherited from the host. Defaults to a small non-secret
+     * allowlist. Set true only inside an already-isolated environment.
+     */
+    inheritEnv?: boolean | string[];
+    /** Shell executable used for commands. Defaults to /bin/bash when present. */
+    shell?: string;
+    /** Maximum combined stdout/stderr retained before the command is killed. */
+    maxOutputBytes?: number;
+    /** Virtual path used when `mode: "virtual"`. Defaults to /workspace. */
+    mountPath?: string;
+    /**
+     * Network policy for virtual local mode. Host mode rejects this option because
+     * AtlasFlow cannot enforce network isolation around an OS shell.
+     */
+    network?: SandboxNetworkPolicy;
+    /**
+     * Required for raw host mode. It is intentionally separate from mode:"host"
+     * so accidental host-shell exposure fails closed.
+     */
+    allowHostAccess?: boolean;
+}
+declare function local(options?: LocalSandboxOptions): SandboxFactory;
+declare function localVirtual(options?: Omit<LocalSandboxOptions, "mode">): SandboxFactory;
+
+/** Start a Node HTTP server for an AtlasFlow app. */
+
+interface ServeOptions {
+    port?: number;
+    hostname?: string;
+    backlog?: number;
+}
+declare function serve(app: Hono, options?: ServeOptions): {
+    port: number;
+    close: () => void;
+};
+
+export { type CommandOptions, type LocalSandboxOptions, type ServeOptions, defineCommand, local, localVirtual, serve };

package/dist/node/index.js

@@ -0,0 +1,251 @@
+import {
+  BaseSandboxEnv,
+  bashFactoryToSessionEnv,
+  createCwdSessionEnv,
+  resolveSandboxNetworkPolicy
+} from "../chunk-4DU4GJ2X.js";
+import {
+  normalizeCommandExecutor
+} from "../chunk-S7RZJMCF.js";
+
+// src/node/define-command.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+var DEFAULT_ENV = {
+  PATH: process.env.PATH,
+  HOME: process.env.HOME,
+  USER: process.env.USER,
+  USERNAME: process.env.USERNAME,
+  LOGNAME: process.env.LOGNAME,
+  HOSTNAME: process.env.HOSTNAME,
+  SHELL: process.env.SHELL,
+  LANG: process.env.LANG,
+  LC_ALL: process.env.LC_ALL,
+  LC_CTYPE: process.env.LC_CTYPE,
+  TERM: process.env.TERM,
+  TMPDIR: process.env.TMPDIR,
+  TMP: process.env.TMP,
+  TEMP: process.env.TEMP
+};
+function defineCommand(name, arg) {
+  if (typeof arg === "function") return { name, execute: normalizeCommandExecutor(arg) };
+  const options = arg ?? {};
+  const env = { ...DEFAULT_ENV, ...options.env ?? {} };
+  const execute = async (args, signal) => {
+    const { stdout, stderr } = await execFileAsync(name, args, {
+      maxBuffer: 50 * 1024 * 1024,
+      ...options,
+      env,
+      signal
+    });
+    return { stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), exitCode: 0 };
+  };
+  return { name, execute: normalizeCommandExecutor(execute) };
+}
+
+// src/node/local-sandbox.ts
+import { spawn } from "child_process";
+import * as fsSync from "fs";
+import * as fs from "fs/promises";
+import * as nodePath from "path";
+import { Bash, InMemoryFs, MountableFs, ReadWriteFs } from "just-bash";
+var DEFAULT_ENV_ALLOWLIST = [
+  "PATH",
+  "HOME",
+  "USER",
+  "USERNAME",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "LANG",
+  "LC_ALL",
+  "TERM",
+  "SHELL",
+  "SystemRoot",
+  "ComSpec"
+];
+var DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+var DEFAULT_VIRTUAL_NETWORK = {
+  dangerouslyAllowFullInternetAccess: true,
+  denyPrivateRanges: true
+};
+var LocalSandboxEnv = class extends BaseSandboxEnv {
+  cwd;
+  #env;
+  #inheritEnv;
+  #shell;
+  #maxOutputBytes;
+  constructor(options) {
+    super();
+    this.cwd = options.cwd ?? process.cwd();
+    this.#env = options.env ?? {};
+    this.#inheritEnv = options.inheritEnv ?? DEFAULT_ENV_ALLOWLIST;
+    this.#shell = options.shell ?? defaultShell();
+    this.#maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  }
+  exec(command, options) {
+    const cwd = options?.cwd ?? this.cwd;
+    const env = { ...filteredEnv(this.#inheritEnv), ...this.#env, ...options?.env };
+    const child = spawn(this.#shell, ["-c", command], { cwd, env, detached: process.platform !== "win32", signal: options?.signal });
+    return new Promise((resolve, reject) => {
+      let stdout = "";
+      let stderr = "";
+      let outputBytes = 0;
+      let timer;
+      let timedOut = false;
+      let outputCapped = false;
+      if (options?.timeoutMs)
+        timer = setTimeout(() => {
+          timedOut = true;
+          killProcessTree(child.pid, "SIGKILL");
+        }, options.timeoutMs);
+      const append = (stream, chunk) => {
+        if (outputCapped) return;
+        outputBytes += chunk.byteLength;
+        if (outputBytes > this.#maxOutputBytes) {
+          outputCapped = true;
+          const note = `
+[command output exceeded ${this.#maxOutputBytes} bytes; process killed]`;
+          if (stream === "stdout") stdout += note;
+          else stderr += note;
+          killProcessTree(child.pid, "SIGKILL");
+          return;
+        }
+        if (stream === "stdout") stdout += chunk.toString();
+        else stderr += chunk.toString();
+      };
+      child.stdout.on("data", (d) => append("stdout", d));
+      child.stderr.on("data", (d) => append("stderr", d));
+      child.on("error", (err) => {
+        if (timer) clearTimeout(timer);
+        reject(err);
+      });
+      child.on("close", (code, sig) => {
+        if (timer) clearTimeout(timer);
+        if (timedOut) resolve({ stdout, stderr: `${stderr}
+[command timed out after ${options?.timeoutMs}ms]`.trim(), exitCode: 124 });
+        else if (outputCapped) resolve({ stdout, stderr, exitCode: code ?? (sig ? 137 : 1) });
+        else resolve({ stdout, stderr, exitCode: code ?? (sig ? 137 : 1) });
+      });
+    });
+  }
+  readFile(path) {
+    return fs.readFile(this.resolvePath(path), "utf8");
+  }
+  async readFileBuffer(path) {
+    return new Uint8Array(await fs.readFile(this.resolvePath(path)));
+  }
+  async writeFile(path, data) {
+    const resolved = this.resolvePath(path);
+    await fs.mkdir(nodePath.dirname(resolved), { recursive: true }).catch(() => {
+    });
+    await fs.writeFile(resolved, data);
+  }
+  async stat(path) {
+    const s = await fs.lstat(this.resolvePath(path));
+    return { isFile: s.isFile(), isDirectory: s.isDirectory(), isSymbolicLink: s.isSymbolicLink(), size: s.size, mtimeMs: s.mtimeMs };
+  }
+  readdir(path) {
+    return fs.readdir(this.resolvePath(path));
+  }
+  async mkdir(path, options) {
+    await fs.mkdir(this.resolvePath(path), { recursive: options?.recursive ?? true });
+  }
+  async rm(path, options) {
+    await fs.rm(this.resolvePath(path), { recursive: options?.recursive ?? false, force: options?.force ?? false });
+  }
+  resolvePath(path) {
+    return nodePath.isAbsolute(path) ? path : nodePath.join(this.cwd, path);
+  }
+};
+function local(options = {}) {
+  return {
+    async createSessionEnv(opts) {
+      const mode = options.mode ?? "virtual";
+      if (mode === "virtual") return createVirtualLocalSessionEnv(options, opts.cwd, opts.env);
+      if (options.network) {
+        throw new Error(
+          'local({ mode: "host" }) does not support sandbox network policy or credential brokering. Use the default virtual sandbox, local({ mode: "virtual" }), or an isolated provider that enforces network policy.'
+        );
+      }
+      if (options.allowHostAccess !== true) {
+        throw new Error(
+          'local({ mode: "host" }) requires allowHostAccess: true. Raw host mode has direct access to the host shell and filesystem; use local() or local({ mode: "virtual" }) for the safer default.'
+        );
+      }
+      return new LocalSandboxEnv(options);
+    }
+  };
+}
+function localVirtual(options = {}) {
+  return local({ ...options, mode: "virtual" });
+}
+async function createVirtualLocalSessionEnv(options, cwd, envVars) {
+  const hostRoot = options.cwd ?? process.cwd();
+  const mountPath = normalizeMountPath(options.mountPath ?? "/workspace");
+  const rwfs = new ReadWriteFs({ root: hostRoot });
+  const mounted = new MountableFs({ base: new InMemoryFs() });
+  mounted.mount(mountPath, rwfs);
+  const network = resolveSandboxNetworkPolicy(options.network, envVars) ?? DEFAULT_VIRTUAL_NETWORK;
+  const env = await bashFactoryToSessionEnv(
+    () => new Bash({
+      fs: mounted,
+      cwd: mountPath,
+      env: { ...filteredEnv(options.inheritEnv ?? DEFAULT_ENV_ALLOWLIST), ...options.env },
+      network
+    })
+  );
+  return cwd ? createCwdSessionEnv(env, cwd) : env;
+}
+function filteredEnv(inherit) {
+  if (inherit === true) return { ...process.env };
+  if (inherit === false) return {};
+  const out = {};
+  for (const key of inherit) {
+    const value = process.env[key];
+    if (typeof value === "string") out[key] = value;
+  }
+  return out;
+}
+function defaultShell() {
+  if (process.platform === "win32") return "bash";
+  for (const candidate of ["/bin/bash", "/usr/bin/bash", "/usr/local/bin/bash"]) {
+    if (fsSync.existsSync(candidate)) return candidate;
+  }
+  return "bash";
+}
+function normalizeMountPath(path) {
+  if (!path.startsWith("/")) throw new Error(`local({ mode: "virtual" }) mountPath must be absolute: ${path}`);
+  const normalized = nodePath.posix.normalize(path);
+  if (normalized === "/") throw new Error('local({ mode: "virtual" }) mountPath cannot be "/"; use "/workspace" or another subdirectory.');
+  return normalized.replace(/\/+$/, "");
+}
+function killProcessTree(pid, signal) {
+  if (!pid) return;
+  try {
+    if (process.platform !== "win32") process.kill(-pid, signal);
+    else process.kill(pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+    }
+  }
+}
+
+// src/node/serve.ts
+import { createAdaptorServer } from "@hono/node-server";
+var DEFAULT_LISTEN_BACKLOG = 1024;
+function serve(app, options = {}) {
+  const port = options.port ?? 4577;
+  const server = createAdaptorServer({ fetch: app.fetch, hostname: options.hostname });
+  server.listen({ port, host: options.hostname, backlog: options.backlog ?? DEFAULT_LISTEN_BACKLOG });
+  return { port, close: () => server.close() };
+}
+export {
+  defineCommand,
+  local,
+  localVirtual,
+  serve
+};

package/dist/providers.d.ts

@@ -0,0 +1,40 @@
+import { Api, Model } from '@earendil-works/pi-ai';
+export { ApiProvider, getApiProvider, getApiProviders, registerApiProvider, unregisterApiProviders } from '@earendil-works/pi-ai';
+
+/**
+ * Provider extension surface.
+ *
+ * AtlasFlow keeps model execution behind AgentEngine, but the default PI engine
+ * can resolve both pi-ai catalog providers and module-scoped provider
+ * registrations declared by application code.
+ */
+
+interface ProviderRegistration {
+    /** pi-ai wire protocol slug. Required when providerId is not in the catalog. */
+    api?: Api;
+    /** Provider endpoint root. Required when providerId is not in the catalog. */
+    baseUrl?: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    contextWindow?: number;
+    maxTokens?: number;
+    /** Per-model metadata overrides keyed by model id. */
+    models?: Record<string, {
+        contextWindow?: number;
+        maxTokens?: number;
+        name?: string;
+    }>;
+    /** Reserved for OpenAI Responses-style providers that support remote item storage. */
+    storeResponses?: boolean;
+}
+declare class ProviderRegistrationError extends Error {
+    constructor(providerId: string);
+}
+declare function registerProvider(providerId: string, registration: ProviderRegistration): void;
+declare function resetProvidersForTests(): void;
+declare function hasRegisteredProvider(providerId: string): boolean;
+declare function getRegisteredApiKey(providerId: string): string | undefined;
+declare function getRegisteredStoreResponses(providerId: string): boolean;
+declare function resolveRegisteredModel(providerId: string, modelId: string): Model<Api> | undefined;
+
+export { type ProviderRegistration, ProviderRegistrationError, getRegisteredApiKey, getRegisteredStoreResponses, hasRegisteredProvider, registerProvider, resetProvidersForTests, resolveRegisteredModel };

package/dist/providers.js

@@ -0,0 +1,26 @@
+import {
+  ProviderRegistrationError,
+  getApiProvider,
+  getApiProviders,
+  getRegisteredApiKey,
+  getRegisteredStoreResponses,
+  hasRegisteredProvider,
+  registerApiProvider,
+  registerProvider,
+  resetProvidersForTests,
+  resolveRegisteredModel,
+  unregisterApiProviders
+} from "./chunk-HO6QHSUS.js";
+export {
+  ProviderRegistrationError,
+  getApiProvider,
+  getApiProviders,
+  getRegisteredApiKey,
+  getRegisteredStoreResponses,
+  hasRegisteredProvider,
+  registerApiProvider,
+  registerProvider,
+  resetProvidersForTests,
+  resolveRegisteredModel,
+  unregisterApiProviders
+};

package/dist/routing/index.d.ts

@@ -0,0 +1,256 @@
+import { MiddlewareHandler, Hono } from 'hono';
+import { C as CreatedAgent, A as AgentEngine, a as AgentProfile, W as WorkflowDef, b as ChannelDefinition, I as InvokeResult, D as DurableExecutionRunner } from '../channel-Dv3Hv1ee.js';
+import { P as PersistenceAdapter, A as AtlasEvent } from '../index-UFTgKRK4.js';
+import 'valibot';
+import '../command-kxrqWIH7.js';
+
+/**
+ * HTTP routing — a Hono app that mounts agents and admin routes.
+ *
+ *   GET  /health                       liveness probe (always open)
+ *   GET  /agents                       agent manifest
+ *   POST /agents/:name/:id             invoke an agent interactively
+ *   POST /sessions/:id/messages        invoke the single deployed agent interactively
+ *   POST /runs                         dispatch the single deployed agent
+ *   POST /runs/:name                   dispatch a durable run (agent or workflow; ?wait=result blocks for agents)
+ *   GET  /runs/:runId                  public run metadata
+ *   GET  /runs/:runId/events           resumable run event stream (SSE) or JSON replay
+ *   PUT  /streams/*                    create a public writable durable stream
+ *   GET  /streams/*                    read a public durable stream
+ *   POST /streams/*                    append to or close a public durable stream
+ *   POST /runs/:runId/approve          decide a workflow gate or tool approval
+ *   POST /workflows/:name              deprecated alias of POST /runs/:name
+ *   GET  /admin/agents                 list registered agents
+ *   GET  /admin/runs                   list runs
+ *   GET  /admin/runs/:runId            get a run record
+ *   GET  /admin/runs/:runId/events     run event log (JSON)
+ *
+ * POST /agents/:name/:id response modes:
+ *   - `Accept: text/event-stream`  → live SSE events + terminal `result` event
+ *   - `x-webhook: true` header     → fire-and-forget: 202 + runId immediately
+ *   - otherwise                    → synchronous JSON
+ */
+
+interface AgentTriggers {
+    webhook?: boolean;
+    cron?: string;
+    crons?: string[];
+}
+/**
+ * Handed to custom route mounts and scheduled handlers: invoke/dispatch are
+ * pre-wired with the app's agents, persistence, AGENTS.md, and shared
+ * subagents, so a webhook handler is one call.
+ */
+interface AtlasRouteContext {
+    agents: Record<string, CreatedAgent>;
+    persistence: PersistenceAdapter;
+    invoke(name: string, opts?: RouteInvokeOptions): Promise<InvokeResult>;
+    dispatch(name: string, opts?: RouteInvokeOptions): Promise<{
+        runId: string;
+        done: Promise<void>;
+    }>;
+}
+interface RouteInvokeOptions {
+    instanceId?: string;
+    message?: string;
+    payload?: unknown;
+    env?: Record<string, unknown>;
+    signal?: AbortSignal;
+    runId?: string;
+    /** Receive live events — build custom streaming endpoints (SSE, websockets). */
+    onEvent?: (event: AtlasEvent) => void;
+}
+/** An authored workflow plus the context its steps resolve against. */
+interface WorkflowMount {
+    def: WorkflowDef;
+    skills?: {
+        name: string;
+        description: string;
+        body: string;
+    }[];
+    defaultModel?: string;
+    /** Persona executing slot-less steps (the workflow's owner). */
+    defaultPersona?: string;
+    profiles?: AgentProfile[];
+    /** Deploy-time role-slot rebinding. */
+    bindings?: Record<string, string>;
+}
+interface AppOptions {
+    agents: Record<string, CreatedAgent>;
+    /** Override the default model engine for app-managed invocations. */
+    engine?: AgentEngine;
+    persistence?: PersistenceAdapter;
+    /** Middleware applied to /agents/*, /runs/*, /workflows/* and /admin/*. */
+    auth?: MiddlewareHandler;
+    /** Trigger metadata per agent (shown in the manifest; cron drives schedules). */
+    triggers?: Record<string, AgentTriggers>;
+    /** Prepended to every agent's instructions (e.g. workspace AGENTS.md). */
+    baseInstructions?: string;
+    /** Personas available to every agent's task tool (e.g. workspace roles/). */
+    personas?: AgentProfile[];
+    /** @deprecated Use `personas`. */
+    subagents?: AgentProfile[];
+    /** Authored workflows (gated, role-slotted) dispatchable via POST /runs/:name. */
+    workflows?: Record<string, WorkflowDef | WorkflowMount>;
+    /**
+     * First-class ingress handlers. A channel owns external webhook parsing and
+     * maps each event to a continuationToken, which becomes the AtlasFlow session id.
+     */
+    channels?: Record<string, ChannelDefinition>;
+    /**
+     * Mount project routes (webhooks, operator endpoints) on the app. These are
+     * NOT behind `auth` unless mounted under a gated prefix — webhook handlers
+     * do their own signature verification (HMAC etc.). Registered before the
+     * built-in routes, so custom paths win.
+     */
+    routes?: (app: Hono, atlas: AtlasRouteContext) => void;
+    /** Wrap durable/background agent execution in a platform primitive. */
+    durability?: DurableExecutionRunner;
+    /** Optional browser CORS policy. Disabled by default. */
+    cors?: CorsOptions | false | ((env: Record<string, string | undefined>) => CorsOptions | false | undefined);
+    /** Optional per-isolate rate limit for public and authenticated HTTP routes. */
+    rateLimit?: RateLimitSource | false;
+    /** Optional in-process runtime metrics surfaced on the authenticated /admin/metrics route. */
+    metrics?: {
+        snapshot(): unknown;
+    };
+}
+interface CorsOptions {
+    /** Allowed browser origins. Use "*" only for non-credentialed public/dev APIs. */
+    origins: "*" | string[];
+    methods?: string[];
+    headers?: string[];
+    exposeHeaders?: string[];
+    credentials?: boolean;
+    maxAgeSeconds?: number;
+}
+interface RateLimitOptions {
+    /** Bucket namespace. Generated apps default to "default"; custom apps can set this to isolate tenants. */
+    scope?: string;
+    /** Requests allowed per window for each derived client key. Defaults to 120. */
+    limit?: number;
+    /** Window length in milliseconds. Defaults to 60 seconds. */
+    windowMs?: number;
+    /** Token-bucket burst capacity. Defaults to min(limit, 30). */
+    burst?: number;
+    /** Maximum tracked client keys before old buckets are pruned. Defaults to 10,000. */
+    maxKeys?: number;
+    /** Override the default key of client IP + presented auth/channel token + route group. */
+    key?: (input: RateLimitKeyInput) => string | undefined;
+}
+interface RateLimitKeyInput {
+    request: Request;
+    url: URL;
+    env: Record<string, string | undefined>;
+    route: string;
+    clientIp: string;
+    tokenHash: string;
+}
+type RateLimitSource = RateLimitOptions | ((env: Record<string, string | undefined>) => RateLimitOptions | false | undefined);
+interface ScopedTokenClaims {
+    v: 1;
+    exp: number;
+    iat?: number;
+    sub?: string;
+    aud?: string;
+    scopes?: string[];
+    agents?: string[];
+    instanceIds?: string[];
+}
+interface ScopedTokenMintOptions {
+    /** Server-side signing secret. Do not send this value to browsers. */
+    secret: string;
+    ttlSeconds?: number;
+    expiresAt?: number | Date;
+    subject?: string;
+    audience?: string;
+    scopes?: string[];
+    agents?: string[];
+    instanceIds?: string[];
+    now?: () => number;
+}
+interface ScopedTokenAuthOptions {
+    /** Defaults to ATLASFLOW_BROWSER_TOKEN_SECRET, then ATLASFLOW_API_KEY. */
+    secret?: string;
+    audience?: string;
+    leewaySeconds?: number;
+    now?: () => number;
+}
+interface ApiKeyAuthOptions {
+    token?: string;
+    header?: string;
+    allowUnconfigured?: boolean | ((env: Record<string, string | undefined>) => boolean);
+    scopedTokens?: boolean | ScopedTokenAuthOptions | false | ((env: Record<string, string | undefined>) => boolean | ScopedTokenAuthOptions | false | undefined);
+}
+/**
+ * Auth middleware: require a bearer token. The expected token is resolved from
+ * `options.token`, else the `ATLASFLOW_API_KEY` env/secret.
+ *
+ * Secure by default: if no token can be resolved the gate fails CLOSED (503).
+ * `allowUnconfigured` opts into an open gate — pass `true`, or a predicate on
+ * the request env (e.g. only when ATLASFLOW_MODE=local).
+ */
+declare function requireApiKey(options?: ApiKeyAuthOptions): MiddlewareHandler;
+/** Mint a browser-safe short-lived token. Call this only from trusted server code. */
+declare function mintScopedToken(options: ScopedTokenMintOptions): Promise<string>;
+/**
+ * Helper for generated apps: browser scoped tokens stay disabled unless the
+ * deployment sets ATLASFLOW_BROWSER_TOKEN_SECRET or ATLASFLOW_BROWSER_TOKENS=true.
+ */
+declare function scopedTokensFromEnv(env?: Record<string, string | undefined>): ScopedTokenAuthOptions | false;
+/** Helper for generated apps: comma-separated ATLASFLOW_CORS_ORIGINS enables CORS. */
+declare function corsFromEnv(env?: Record<string, string | undefined>): CorsOptions | false;
+/**
+ * Helper for generated apps. Rate limiting is enabled by default for built
+ * servers and can be tuned or disabled with environment variables:
+ *   ATLASFLOW_RATE_LIMIT_ENABLED=false
+ *   ATLASFLOW_RATE_LIMIT_RPM=120
+ *   ATLASFLOW_RATE_LIMIT_BURST=30
+ *   ATLASFLOW_RATE_LIMIT_WINDOW_MS=60000
+ */
+declare function rateLimitFromEnv(env?: Record<string, string | undefined>): RateLimitOptions | false;
+declare function rateLimit(source?: RateLimitSource): MiddlewareHandler;
+/**
+ * Keep a background promise alive past the response. On Cloudflare the request
+ * context is torn down once the response is sent, cancelling stray promises —
+ * waitUntil is the supported escape hatch. On Node accessing executionCtx
+ * throws; background promises simply keep running there. Use this in custom
+ * routes after `atlas.dispatch(...)`.
+ */
+declare function keepAlive(c: {
+    executionCtx?: {
+        waitUntil?: (p: Promise<unknown>) => void;
+    };
+}, promise: Promise<unknown>): void;
+declare function createApp(options: AppOptions): Hono;
+/**
+ * Startup recovery for everything durable: re-dispatch interrupted agent runs
+ * AND resume interrupted workflow runs from their persisted cursor. Runs
+ * parked at a gate (waiting_approval) stay parked — they wait on a human.
+ */
+declare function recoverAppRuns(options: AppOptions, env?: Record<string, unknown>): Promise<string[]>;
+interface ScheduledHandlerOptions extends Pick<AppOptions, "agents" | "engine" | "triggers" | "baseInstructions" | "personas" | "subagents" | "durability"> {
+    /** Resolve persistence from the per-invocation env (e.g. a Durable Object binding). */
+    persistenceFor?: (env: Record<string, unknown>) => PersistenceAdapter | undefined;
+}
+interface ScheduledEvent {
+    /** The cron expression that fired (provided by Cloudflare). */
+    cron?: string;
+    scheduledTime?: number;
+}
+/**
+ * Build a `scheduled(event, env, ctx)` handler that dispatches a durable
+ * run for every agent whose trigger metadata is due. Older generated apps use
+ * `triggers.cron`; folder-first apps may use `triggers.crons` when one agent
+ * has multiple schedule files. Background work is registered with `ctx.waitUntil`.
+ */
+declare function createScheduledHandler(options: ScheduledHandlerOptions): (event: ScheduledEvent, env?: Record<string, unknown>, ctx?: {
+    waitUntil?: (p: Promise<unknown>) => void;
+}) => Promise<{
+    dispatched: {
+        agent: string;
+        runId: string;
+    }[];
+}>;
+
+export { type AgentTriggers, type ApiKeyAuthOptions, type AppOptions, type AtlasRouteContext, type CorsOptions, type RateLimitKeyInput, type RateLimitOptions, type RateLimitSource, type RouteInvokeOptions, type ScheduledEvent, type ScheduledHandlerOptions, type ScopedTokenAuthOptions, type ScopedTokenClaims, type ScopedTokenMintOptions, type WorkflowMount, corsFromEnv, createApp, createScheduledHandler, keepAlive, mintScopedToken, rateLimit, rateLimitFromEnv, recoverAppRuns, requireApiKey, scopedTokensFromEnv };