palbase 0.3.3 → 0.5.0

package/types/ai/src/tools.d.ts

@@ -0,0 +1,167 @@
+import type { ai as wire } from '../../internal/src/modules/index.js';
+type AgentDefinition = wire.AgentDefinition;
+type ToolContent = wire.ToolContent;
+type ToolRef = wire.ToolRef;
+import { type ToolResult } from '../../internal/src/tool-output.js';
+import type { Infer, StandardSchema } from './schema.js';
+/** A role, or a catalogue model as provider:model. */
+type Model = 'fast' | 'default' | 'strong' | (string & {});
+/** The chat a tool call or a turn is of, as the platform names it in its signed call. */
+export interface ChatContext {
+    /** The chat; '' for a call of a one-shot answer's (ai.ask with tools), which is of no chat. */
+    chatId: string;
+    /** The agent's name in the chat. */
+    agent: string;
+    /** The member whose message the turn answers; null: the project's server, or a turn nobody wrote. */
+    user: {
+        id: string;
+        name: string;
+    } | null;
+    /**
+     * The chat's own labels — set by whoever started it, and a user may start
+     * one: what they say is the caller's word, not an authority (never a name
+     * of something they may then reach).
+     */
+    metadata: Record<string, string>;
+    /** Ended when the platform stops waiting for the answer. */
+    signal: AbortSignal;
+}
+export interface ToolContext extends ChatContext {
+    /** The call's id: the same call is the same id, whatever copy of the machine it reaches. */
+    callId: string;
+}
+export type AgentContext = ChatContext;
+export interface BackendToolOptions<S extends StandardSchema> {
+    /** What the agent calls it by: letters, digits, _ and -, starting with a letter, at most 64. */
+    name: string;
+    /** What it does: the agent reads it to choose. */
+    description: string;
+    /** What it takes: a zod (valibot, arktype) object schema — the agent is shown it, and its input is checked against it. */
+    input: S;
+    /**
+     * What the call does: a string, an object (said as JSON), pictures
+     * (`{ mediaType, bytes }`), or a list of them — 4 MiB at most in all. A
+     * throw is the tool's failure: a ToolError's message (or the framework's
+     * own refusals', NotFound('…')) is told to the agent, anything else as
+     * "The tool failed".
+     */
+    run(input: Infer<S>, ctx: ToolContext): ToolResult | Promise<ToolResult>;
+    /** Every call waits for a person's yes (a member of the chat, or the server). */
+    approval?: boolean;
+    /** The project's machine it runs on (default backend). */
+    machine?: string;
+}
+export interface BackendTool<S extends StandardSchema = StandardSchema> {
+    readonly source: 'backend';
+    readonly name: string;
+    readonly description: string;
+    readonly input: S;
+    /** The input's JSON Schema, as the agent is shown it. */
+    readonly parameters: Record<string, unknown>;
+    readonly approval: boolean;
+    readonly machine?: string;
+    /** The run, its input checked first: what the framework answers the platform's call with. */
+    call(input: unknown, ctx: ToolContext): Promise<{
+        output: ToolContent[];
+        is_error: boolean;
+    }>;
+}
+export interface ClientToolOptions<S extends StandardSchema> {
+    name: string;
+    description: string;
+    /** What it takes; none: an empty object. */
+    input?: S;
+    approval?: boolean;
+}
+/** A tool the app's code answers (pb.ai.chat(id).tools({ name: fn })): the turn waits for its answer. */
+export interface ClientTool {
+    readonly source: 'client';
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly approval: boolean;
+}
+/** An HTTPS tool the project put (ai.endpoints.put(name, { kind: 'https', … })). */
+export interface HttpsToolRef {
+    source: 'https';
+    name: string;
+    approval?: boolean;
+}
+/** An MCP server the project put: its tools, or the ones named in only. */
+export interface McpToolRef {
+    source: 'mcp';
+    name: string;
+    only?: string[];
+    approval?: boolean;
+}
+export type Tool = BackendTool<StandardSchema> | ClientTool | HttpsToolRef | McpToolRef;
+export interface SubagentDefinition {
+    /** Unique among the agent's subagents. */
+    name: string;
+    /** What it is for: the agent reads it to choose. */
+    description: string;
+    instructions?: string;
+    model?: Model;
+    tools?: Tool[];
+    /** The turn fails if this subagent's part fails. */
+    required?: boolean;
+}
+/** What an agent is for a turn. */
+export interface AgentDefinitionInput {
+    instructions?: string;
+    model?: Model;
+    /** 64 at most, with its MCP servers'. */
+    tools?: Tool[];
+    /** 16 at most. */
+    subagents?: SubagentDefinition[];
+    /** How many tool calls a turn makes at most (1–200): past it the agent is told it has no tools left and answers. */
+    maxToolCalls?: number;
+    /** A named agent's: the app's users start chats with it themselves (when the project lets them). Left out, the server's alone. */
+    clients?: boolean;
+}
+/** What a backend's agent is for one turn: whether users reach it is the named agent's, said when it is put. */
+export type TurnDefinition = Omit<AgentDefinitionInput, 'clients'>;
+/** An agent the backend defines at each turn's start: put with ai.agents.put(agent), its chats' turns ask its machine. */
+export interface BackendAgent {
+    readonly kind: 'agent';
+    readonly name: string;
+    /** The project's machine that defines it (default backend). */
+    readonly machine?: string;
+    /** The app's users start chats with it themselves (put with it). */
+    readonly clients: boolean;
+    /** The definition for a turn, said as the platform takes it, with the backend tools it hands out. */
+    resolve(ctx: AgentContext): Promise<{
+        definition: AgentDefinition;
+        tools: BackendTool[];
+    }>;
+}
+/** What this process declared, for the framework to serve. */
+export interface DeclaredAI {
+    tools: Map<string, BackendTool>;
+    agents: Map<string, BackendAgent>;
+    /** Names declared twice (tool:<name>, agent:<name>): the framework refuses to start with one. */
+    twice: Set<string>;
+}
+/**
+ * A tool's failure in its own words: thrown from run, its message is what
+ * the agent — and the chat's members, who see the call — are told. Any other
+ * throw is told as "The tool failed" (a library's or the database's words
+ * may name what the chat is not to read); the whole of it is in the app's log.
+ */
+export declare class ToolError extends Error {
+    constructor(message: string);
+}
+export declare const AGENT_NAME: RegExp;
+/** The input's JSON Schema: an object, written out (no references), as a provider takes a tool's parameters. */
+export declare function parametersOf(schema: StandardSchema | undefined, what: string): Record<string, unknown>;
+export declare function backendTool<S extends StandardSchema>(o: BackendToolOptions<S>): BackendTool<S>;
+export declare function clientTool<S extends StandardSchema>(o: ClientToolOptions<S>): ClientTool;
+export declare function backendAgent(name: string, define: (ctx: AgentContext) => TurnDefinition | Promise<TurnDefinition>, options?: {
+    machine?: string;
+    clients?: boolean;
+}): BackendAgent;
+/** A tool as the platform takes it (ToolRef). */
+export declare function toolRef(t: Tool, what: string): ToolRef;
+/** A definition as the platform takes it (AgentDefinition). */
+export declare function definitionOf(d: AgentDefinitionInput, what: string): AgentDefinition;
+export {};

package/types/backend/src/container.d.ts

@@ -24,8 +24,10 @@ export declare class Container {
     readonly eventProviders: Ctor[];
     /** The providers that are @Webhook classes: their @On take a third party's. */
     readonly webhooks: Ctor[];
-    /** The providers that are @Job classes: the platform runs them on their schedules. */
-    readonly jobProviders: Ctor[];
+    /** The providers that are @Cron classes: the platform runs them on their schedules. */
+    readonly cronProviders: Ctor[];
+    /** The providers that are @Task classes: the platform runs them as their tasks come due. */
+    readonly taskProviders: Ctor[];
     /** The providers that are @Room classes. */
     readonly rooms: Ctor[];
     constructor(modules: Function[]);

package/types/backend/src/decorators.d.ts

@@ -83,7 +83,8 @@ export declare const INJECTABLE: unique symbol;
 export declare const MODULE: unique symbol;
 export declare const EVENTS: unique symbol;
 export declare const WEBHOOK: unique symbol;
-export declare const JOBS: unique symbol;
+export declare const CRONS: unique symbol;
+export declare const TASKS: unique symbol;
 export declare function declared(): Set<Function>;
 export declare const RESERVED: Set<string>;
 export declare function Controller(basePath: string, options?: ControllerOptions): ClassDecorator;
@@ -179,49 +180,63 @@ export declare const isFileEvent: (event: string) => boolean;
  * offers, and each types its handler (EventHandler).
  */
 export declare function On<E extends EventType | (string & {})>(event: E, options?: OnOptions): <F extends EventHandler<E>>(target: object, key: string | symbol, descriptor: TypedPropertyDescriptor<F>) => void;
-export interface JobOptions {
+export interface CronOptions {
     /**
      * What its runs are kept under (Studio, the CLI) and the platform calls it
      * by: letters, digits, '.', '_' and '-', at most 64. Renaming it starts a
-     * new job.
+     * new cron.
      */
     name: string;
-    /** Five fields of cron's — minute hour day-of-month month day-of-week — in UTC, like "0 3 * * *". */
+    /** Five fields of cron's — minute hour day-of-month month day-of-week — like "0 3 * * *", on the clocks of timeZone. */
     schedule: string;
-    /** Seconds one run may take before it is a failed attempt: 1–300 (30). */
+    /**
+     * The time zone whose clocks the schedule is on, by its IANA name
+     * ("Europe/Istanbul", "America/New_York"): UTC when none. Where its clocks
+     * change, a time they skip is not run, and a time they show twice is run
+     * the first time only.
+     */
+    timeZone?: string;
+    /** Seconds one run may take before it is a failed attempt: 1–900 (30). */
     timeout?: number;
     /** Attempts after a failed one, 10 s, 20 s, … five minutes apart: 0–10 (5). */
     retry?: number;
 }
-export interface JobDeclaration {
+export interface CronDeclaration {
     name: string;
     schedule: string;
+    timeZone: string;
     timeout: number;
     retries: number;
 }
-/** One run of a job, as the platform calls it: what its run(meta) is given. */
-export interface JobMeta {
+/** One run of a cron, as the platform calls it: what its run(meta) is given. */
+export interface CronMeta {
     /** The app's environment variables, as it started (its keys left out). */
     env: Record<string, string>;
     /** The project the app belongs to (its id). */
     environmentId: string;
-    job: string;
-    /** The run's id: the same for each attempt of one run — what a job keys its work on to do it once. */
+    /** The cron's name. */
+    cron: string;
+    /** The run's id: the same for each attempt of one run — what a cron keys its work on to do it once. */
     runId: string;
-    /** The minute it was due. */
+    /** The minute it was due (or was asked to run now). */
     scheduledAt: Date;
     /** 1 for the first, then one more each time a failed attempt is made again. */
     attempt: number;
 }
+export declare const PLATFORM_NAME: RegExp;
+/** Why a time zone is not one the platform reads its clocks of, or undefined when it is. */
+export declare function zoneProblem(zone: string): string | undefined;
 /**
- * A provider the platform runs on `schedule` — five fields of cron's, in UTC
- * — by calling its run(meta), on the machine: woken for it if asleep, one of
- * its copies called, one run of a job at a time. A throw is a failed attempt,
- * made again; a return is done. It runs in a transaction of its own, as the
+ * A provider the platform runs on `schedule` — five fields of cron's, on the
+ * clocks of its time zone (UTC unless it names one) — by calling its
+ * run(meta), on the machine: woken for it if asleep, one of its copies
+ * called, one run of a cron at a time. A throw is a failed attempt, made
+ * again; a return is done. It runs in a transaction of its own, as the
  * service role: no one called it but the app. Off the platform nothing calls
- * it. Its module lists it in its providers, as any other.
+ * it. Its module lists it in its providers, as any other. Studio and the CLI
+ * pause it, resume it and run it now.
  */
-export declare function Job(options: JobOptions): ClassDecorator;
+export declare function Cron(options: CronOptions): ClassDecorator;
 /** The senders whose signing scheme is known by name. */
 export type WebhookProvider = 'stripe' | 'github' | 'twilio' | 'sendgrid' | 'slack' | 'discord' | 'livekit';
 /** A signature scheme spelled out, for a sender with no preset: an HMAC of `signs`, in `header`. */

package/types/backend/src/engine.d.ts

@@ -1,6 +1,7 @@
 import { type PalbaseServer, type TokenUser, type TokenVerifier, type WebhookEvent } from '../../server/src/index.js';
 import { type AuthSpec, type RateLimitConfig } from './decorators.js';
 import { type ContractOptions } from './openapi.js';
+import { type StringsTable } from './i18n.js';
 import type { RequestTelemetry } from './requests.js';
 /** The signed-in user, as @User() gives it. */
 export interface UserT {
@@ -66,6 +67,12 @@ export interface AppOptions {
         app: RequestDatabases;
         requests: 'caller' | 'service';
     };
+    /**
+     * The app's strings (palbase/strings/, loadStringsTable): t() answers each request in the first of its
+     * Accept-Language's languages the table has, the source language otherwise, and the answer says which
+     * (Content-Language) and that it depends on them (Vary: Accept-Language).
+     */
+    strings?: StringsTable;
     /**
      * Built to write its contract and nothing else (PALBASE_CONTRACT_OUT): its
      * webhooks' secrets are not read, and whether it declares a database says
@@ -84,13 +91,22 @@ export interface AppOptions {
      * missing_signature, malformed_signature, stale_timestamp or
      * signature_mismatch. The factory gives it the machine's
      * PALBASE_PLATFORM_SECRET; unset here, none is served (404). They are:
-     * - the app's @Job classes: GET /_palbase/jobs lists them (the platform asks
-     *   once a version is up), POST /_palbase/jobs/<name> runs one — its body
-     *   {job, run_id, scheduled_at, attempt} is what the signature covers —
-     *   and answers 204, or the failure the platform tries again;
+     * - the app's @Cron classes: GET /_palbase/crons lists them (the platform
+     *   asks once a version is up), POST /_palbase/crons/<name> runs one — its
+     *   body {cron, run_id, scheduled_at, attempt} is what the signature covers
+     *   — and answers 204, or the failure the platform tries again;
+     * - its @Task classes: GET /_palbase/tasks lists them (asked with the
+     *   crons), POST /_palbase/tasks/<name> runs one attempt of a task — {task,
+     *   id, attempt, payload, created_at} — and answers 204, 422 for a task
+     *   never to be done (TaskFailure, or a payload its schema refuses), or the
+     *   failure the platform tries again;
      * - its @Upload routes' two steps, from storage (upload.ts), and its
      *   @Room classes' joins, messages and moments, from realtime (rooms.ts):
-     *   platform-calls.ts.
+     *   platform-calls.ts;
+     * - its ai tools and agents (@palbase/ai's ai.tool and ai.agent), from the
+     *   ai module: POST /_palbase/ai/tools runs the tool an agent called (its
+     *   body's tool), POST /_palbase/ai/agents answers the definition of the
+     *   agent a turn is of (its body's agent) — ai-calls.ts.
      */
     platform?: {
         secret: string;

package/types/backend/src/env.d.ts

@@ -11,7 +11,7 @@ export interface PalbaseConnection {
      * The key the platform signs its own calls to this machine with —
      * PALBASE_PLATFORM_SECRET, which the platform starts every machine with.
      * Off the platform there is none, and what only the platform calls (the
-     * app's jobs, /_palbase/jobs) is not served.
+     * app's crons and tasks, /_palbase/crons and /_palbase/tasks) is not served.
      */
     platformSecret?: string;
 }

package/types/backend/src/i18n.d.ts

@@ -1,14 +1,13 @@
-/** The app's strings: its source language, its languages, and each key's cell per language. */
+/**
+ * The app's strings (palbase/strings/, loadStringsTable): its source language, the languages it has files for, and
+ * each key's translation by language — an empty one is not translated yet, and the key itself answers.
+ */
 export interface StringsTable {
-    version: 1;
     source: string;
     locales: string[];
-    strings: Record<string, Record<string, {
-        value: string;
-        state: 'translated' | 'needs_review' | 'missing';
-    }>>;
+    strings: Record<string, Record<string, string>>;
 }
-/** The languages a request asks for, best first — each tag and then its base language — and the source last. */
+/** The languages a request asks for, best first — each tag, then the shorter ones a table may name — and the source last. */
 export declare function chainFromAcceptLanguage(header: string | null, source: string | undefined): string[];
 /** The key's text in the first language of the chain that has it — the key itself in the source language. */
 export declare function lookup(table: StringsTable, key: string, chain: readonly string[]): {
@@ -17,5 +16,7 @@ export declare function lookup(table: StringsTable, key: string, chain: readonly
 };
 /** {{name}} filled from vars ({{{name}}} left as it is); a value not given is empty. */
 export declare function interpolate(text: string, vars?: Record<string, unknown>): string;
+/** The app started without a table at `root`'s palbase/strings: the first t() says so. */
+export declare function stringsMissingAt(root: string | undefined): void;
 /** The sentence `key` (written in the source language) in the caller's language, {{name}} filled. */
 export declare function t(key: string, vars?: Record<string, string | number | boolean | null | undefined>): string;

package/types/backend/src/index.d.ts

@@ -1,5 +1,6 @@
 import 'reflect-metadata';
-export { Body, Client, Controller, Delete, Get, getRegisteredControllers, getRoutes, Headers, Injectable, Job, Module, On, OptionalUser, Param, Patch, Post, Put, Query, QueryParams, Req, RequestId, Resolve, TraceId, User, Webhook, type AuthConfig, type AuthSpec, type ControllerOptions, type EventHandler, type JobMeta, type JobOptions, type ModuleDef, type OnOptions, type ParamResolver, type RateLimitConfig, type ResolveContext, type RouteInfo, type RouteOptions, type SignatureSpec, type StandardSchemaV1, type Token, type WebhookOptions, type WebhookProvider, } from './decorators.js';
+export { Body, Client, Controller, Delete, Get, getRegisteredControllers, getRoutes, Headers, Cron, Injectable, Module, On, OptionalUser, Param, Patch, Post, Put, Query, QueryParams, Req, RequestId, Resolve, TraceId, User, Webhook, type AuthConfig, type AuthSpec, type ControllerOptions, type EventHandler, type CronMeta, type CronOptions, type ModuleDef, type OnOptions, type ParamResolver, type RateLimitConfig, type ResolveContext, type RouteInfo, type RouteOptions, type SignatureSpec, type StandardSchemaV1, type Token, type WebhookOptions, type WebhookProvider, } from './decorators.js';
+export { Task, TaskFailure, Tasks, type EnqueueOptions, type PayloadOf, type QueuedTask, type TaskClass, type TaskMeta, type TaskOptions, type TasksService } from './tasks.js';
 export { Upload, UploadedObject, type UploadConfig } from './upload.js';
 export { OnAuthorize, OnEmpty, OnFirst, OnJoin, OnLeave, OnMessage, Room, type RoomAuthorizeContext, type RoomContext, type RoomGrant, type RoomMessageContext, type RoomOptions, type RoomUser, } from './rooms.js';
 export { getWebhookManifest, type WebhookEventHandler, type WebhookMeta } from './webhooks.js';

package/types/backend/src/strings-files.d.ts

@@ -1,3 +1,30 @@
 import type { StringsTable } from './i18n.js';
-/** The table under `root` (the app's directory), or undefined when it has none. */
+export declare const STRINGS_DIR = "palbase/strings";
+/** The format this writes and the running app reads. */
+export declare const STRINGS_FORMAT = 3;
+/** A language tag as Intl writes it (en, en-US, zh-Hans): the form a request's languages are matched in. */
+export declare function canonicalLanguage(tag: string): string | undefined;
+/** The files as they are: their format, the source language, and each language's translations by key. */
+export interface StringsFiles {
+    format: number;
+    source: string;
+    languages: Map<string, Map<string, string>>;
+}
+/**
+ * palbase/strings/ under `root` read as it is — this format, or the earlier one (its cells' values; a missing one
+ * is empty) — every file checked: a file that breaks a rule is named, with the rule. Undefined when there is none.
+ */
+export declare function readStringsFiles(root: string, formats?: readonly number[]): Promise<StringsFiles | undefined>;
+/** The table under `root` (the app's directory) the running app answers t() from, or undefined when it has none. */
 export declare function loadStringsTable(root: string): Promise<StringsTable | undefined>;
+/** One language file's text: its sentences in order, each with its translation, as JSON written for people to edit. */
+export declare function stringsFileText(translations: ReadonlyMap<string, string>, order: readonly string[]): string;
+/**
+ * palbase/strings/ under `root` written as `source` and `languages` (each with every key of `order`, in that
+ * order), each file written beside itself and renamed into place, a language file no longer in `languages`
+ * removed. A run cut short leaves a table the next one reads: a new table's _meta.json is written first (its
+ * language files come with it), an existing one's last (a conversion from the earlier format reads the files it
+ * already wrote — readStringsFiles takes a plain translation there too). The files whose text changed, by name;
+ * a file that differs only in its line endings (a checkout's CRLF) is not one.
+ */
+export declare function writeStringsFiles(root: string, source: string, languages: ReadonlyMap<string, ReadonlyMap<string, string>>, order: readonly string[]): Promise<string[]>;

package/types/backend/src/tasks.d.ts

@@ -0,0 +1,168 @@
+import { type StandardSchemaV1 } from './decorators.js';
+export interface TaskOptions {
+    /**
+     * The task's type: what its tasks are put on the queue under, kept under
+     * (Studio, the CLI) and called by — letters, digits, '.', '_' and '-', at
+     * most 64.
+     */
+    name: string;
+    /** Seconds one attempt may take before it is a failed one: 1–900 (60). */
+    timeout?: number;
+    /** Attempts after a failed one, 10 s, 20 s, … an hour apart at most: 0–20 (5). */
+    retry?: number;
+    /** How many of its tasks the machine runs at once, however many copies it has: 1–50 (5). */
+    concurrency?: number;
+    /**
+     * What a task carries, checked before run() is called: a task that does
+     * not hold to it can never be done, and fails at once — it is not tried
+     * again. run() is given what the schema gives.
+     */
+    payload?: StandardSchemaV1;
+}
+export interface TaskDeclaration {
+    name: string;
+    timeout: number;
+    retries: number;
+    concurrency: number;
+    payload?: StandardSchemaV1;
+}
+/** One attempt of a task, as the platform calls it: what its run(payload, meta) is given beside what it carries. */
+export interface TaskMeta {
+    /** The app's environment variables, as it started (its keys left out). */
+    env: Record<string, string>;
+    /** The project the app belongs to (its id). */
+    environmentId: string;
+    /** The task's type. */
+    task: string;
+    /** The task's id: the same for each of its attempts — what it keys its work on to do it once. */
+    id: string;
+    /** 1 for the first, then one more each time a failed attempt is made again. */
+    attempt: number;
+    /** When it was put on the queue. */
+    createdAt: Date;
+}
+/**
+ * Thrown by a task's run(): the task can never be done — what it carries is
+ * not what it needs, the thing it works on is gone — and fails now, not to
+ * be tried again. Any other throw is an attempt that failed, made again.
+ */
+export declare class TaskFailure extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A provider whose run(payload, meta) does tasks of its type: put on the
+ * queue with Tasks.enqueue(TheClass, payload), each run once its time
+ * comes — on the platform, which wakes the machine for it; off it, in this
+ * process. A return is done; a throw an attempt that failed, made again
+ * later (a TaskFailure: failed for good). It runs in a transaction of its
+ * own, as the service role: no one called it but the app. Its module lists
+ * it in its providers, as any other.
+ */
+export declare function Task(options: TaskOptions): ClassDecorator;
+/** A @Task class: its constructor takes what it was written to take, its run() a payload and the meta. */
+export type TaskClass = abstract new (...args: never[]) => {
+    run(payload: never, meta: TaskMeta): unknown;
+};
+/** What a @Task class's run() takes as its payload. */
+export type PayloadOf<C> = C extends abstract new (...args: never[]) => {
+    run(payload: infer P, ...rest: never[]): unknown;
+} ? P : never;
+export interface EnqueueOptions {
+    /** Due this many seconds from now (30 days at most). */
+    delay?: number;
+    /** Due at this time (30 days from now at most; a time past is now). */
+    runAt?: Date;
+    /**
+     * Put once under this key: another task of its type under the same key,
+     * while the first is held — until a day after it is over — is not put,
+     * and the first is answered (duplicate: true).
+     */
+    key?: string;
+}
+/** A task on the queue, as it was put. */
+export interface QueuedTask {
+    id: string;
+    task: string;
+    state: 'waiting' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+    attempt: number;
+    /** When it is due (RFC 3339): JSON as it is, so a handler can answer with the task. */
+    runAt: string;
+    key?: string;
+    reason?: string;
+    /** Put already under its key: this is that task, and nothing new was put. */
+    duplicate: boolean;
+}
+/** The queue the app puts its tasks on: the platform's, or its own off the platform. */
+export interface TaskQueue {
+    enqueue(task: string, payload: unknown, options: EnqueueOptions & {
+        machine?: string;
+    }): Promise<QueuedTask>;
+    cancel(id: string, machine?: string): Promise<QueuedTask>;
+    get(id: string, machine?: string): Promise<QueuedTask>;
+}
+export interface TasksService {
+    /**
+     * Put a task of this @Task class on the machine's queue, carrying payload
+     * — what its run() takes, checked as it is written.
+     */
+    enqueue<C extends TaskClass>(task: C, payload: PayloadOf<C>, options?: EnqueueOptions): Promise<QueuedTask>;
+    /** Put a task of a type by its name — of another of the project's machines, with machine. */
+    enqueue(task: string, payload?: unknown, options?: EnqueueOptions & {
+        machine?: string;
+    }): Promise<QueuedTask>;
+    /** Take a task that is waiting off the queue: it is not run. */
+    cancel(id: string, options?: {
+        machine?: string;
+    }): Promise<QueuedTask>;
+    /** A task on the queue, as it is now. */
+    get(id: string, options?: {
+        machine?: string;
+    }): Promise<QueuedTask>;
+}
+/** The machine's task queue. */
+export declare const Tasks: TasksService;
+/** The platform's queue of the machine this app runs on (PALBASE_MACHINE), or of another of the project's. */
+export declare function platformQueue(machine: string | undefined): TaskQueue;
+/** How the app does one attempt of a task: what the platform's call would answer. */
+export type RunTask = (call: {
+    task: string;
+    id: string;
+    attempt: number;
+    payload: unknown;
+    createdAt: Date;
+}, signal: AbortSignal) => Promise<{
+    status: number;
+    message?: string;
+}>;
+/**
+ * The app's own queue, off the platform: its tasks run in this process, as
+ * the platform would run them — when due, each type no more at once than its
+ * concurrency, an attempt that failed made again later, a key held a day
+ * after its task is over. Nothing of it outlives the process.
+ */
+export declare class LocalQueue implements TaskQueue {
+    private readonly types;
+    private readonly run;
+    private readonly now;
+    private readonly tasks;
+    private readonly running;
+    private readonly idle;
+    constructor(types: ReadonlyMap<string, TaskDeclaration>, run: RunTask, now?: () => number);
+    enqueue(task: string, payload: unknown, o: EnqueueOptions & {
+        machine?: string;
+    }): Promise<QueuedTask>;
+    cancel(id: string): Promise<QueuedTask>;
+    get(id: string): Promise<QueuedTask>;
+    /** Resolves once no task is waiting to run now, nor running: what a test waits for after putting one. */
+    settled(): Promise<void>;
+    private quiet;
+    private known;
+    private view;
+    private schedule;
+    private pump;
+    private attempt;
+    private finish;
+    private wake;
+}