Somewhere for work to live. And a safe way to point an agent at a piece of it and walk away.

pnpm add @nightowlsdev/tasks pg
owl install tasks       # ejects tasks_0001 into supabase/migrations/
supabase db push        # you apply it, with your own tooling

import { createInternalTaskStore, createTaskProviderRegistry } from "@nightowlsdev/tasks";
import type { TaskCtx } from "@nightowlsdev/tasks";
import { Pool } from "pg";

declare const orgId: string; // your org's UUID
declare const userId: string;

// You own the Pool (pg is a peer dep). It must OWN the tables or hold BYPASSRLS — they are RLS-on with no
// policy, so an unprivileged role reads zero rows and writes nothing, which looks exactly like an empty board.
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

// The internal pg-backed provider (id "internal") is the default. The registry fans list() across N providers,
// degrading a dead one into a NAMED WARNING rather than failing the whole call.
const internal = createInternalTaskStore({ pool });
const registry = createTaskProviderRegistry({ providers: [internal] });

// Every provider call carries the AUTHENTICATED context — tenant, the FR-055 orgScope, and the acting actor —
// never a model-supplied identity.
const ctx: TaskCtx = { tenantId: orgId, orgScope: "finance/emea", actor: { type: "human", userId, tenantId: orgId } };

// A human task. Reads see org-level rows + the caller's own scope + its ancestors; writes land at one exact scope.
const task = await internal.create(ctx, { title: "Draft the Q3 board deck", priority: "high" });
const board = await registry.list(ctx, { status: ["open", "in_progress"] });

import { createAgentTaskExecutor } from "@nightowlsdev/tasks";
import type { TaskCtx } from "@nightowlsdev/tasks";
import type { Engine, Runner } from "@nightowlsdev/core";

declare const pool: import("pg").Pool;
declare const runner: Runner;      // createBackgroundRunner(...) — enqueue + FR-028 cancel
declare const ctx: TaskCtx;
declare const engineFor: (slug: string) => Engine; // your slug -> engine map

// The executor shares the SAME table config as the store (one Pool, one table).
const executor = createAgentTaskExecutor({ pool });

// startAgentTask is the ONLY entry that runs an agent task. resolveTarget maps the assignee's slug to the engine
// that will run it; the engine MUST advertise cost caps, or the start is REFUSED before anything is enqueued
// (TaskEngineCannotEnforceBudget). Under the hood: an atomic single-winner claim so no task double-starts, and —
// for a MIRRORED task — the attacker-controllable title/detail ride a FENCED envelope in RunInput.context.
const { runId, runEpoch, runCtx, task } = await executor.startAgentTask(ctx, "TK-1A2B3C4D5E", {
  runner,
  resolveTarget: async (_ctx, slug) => {
    const engine = engineFor(slug);
    if (engine.capabilities?.governance?.costCaps !== true) return undefined;
    return { engine, agentSlug: slug };
  },
});

import type { AgentTaskExecutor, StartAgentTaskResult } from "@nightowlsdev/tasks";
import type { Runner, SwarmEvent } from "@nightowlsdev/core";

declare const executor: AgentTaskExecutor;
declare const runner: Runner;
declare const started: StartAgentTaskResult;      // what startAgentTask returned
declare const storage: { events: { subscribe(runId: string): AsyncIterable<SwarmEvent> } };
declare const persisted: { usdSum: number; genSum: number }; // the cumulative you saved, for a restart

const { task, runId, runEpoch, runCtx } = started;

// THE LOAD-BEARING CEILING. One observer per run sums swarm.turn_usage (cost.usd + externalUsd) across ALL
// resume segments and cancels via Runner.cancel on breach. RunInput.budget (per-segment) is defence-in-depth
// only — it cannot bound cumulative spend, because the engine builds a fresh zero-dollar governor on every resume.
const observer = executor.createRunObserver({ runner });
await observer.observe({ task, runId, runEpoch, runCtx, events: storage.events.subscribe(runId) });

// storage.events.subscribe is LIVE-ONLY (it does not replay). On a reconnect / replica failover / process
// restart, pass the persisted cumulative as seed so the ceiling is not silently reset to zero:
await observer.observe({ task, runId, runEpoch, runCtx, events: storage.events.subscribe(runId), seed: persisted });

import type { AgentTaskExecutor, TaskCtx } from "@nightowlsdev/tasks";
import type { CompletionVerifier, Runner } from "@nightowlsdev/core";

declare const executor: AgentTaskExecutor;
declare const ctx: TaskCtx;
declare const runner: Runner;
declare const verifyCompletion: CompletionVerifier;

// The deadline is PERSISTED (deadline_at = started_at + budget.deadlineMs), enforceable whether the run is
// executing or PARKED on a human. The sweep is STATELESS and HOST-SCHEDULED — there is no in-package timer;
// point a cron at it. It cancels the run, then flips the task, across every org's past-deadline agent tasks.
const sweep = await executor.sweepDeadlines({ runner });

// An agent task reaches "done" through ONE path: closeAgentTask records the result, and when the task carries a
// definitionOfDone it runs verifyCompletion FAIL-CLOSED — an absent or throwing judge REFUSES the close (the
// task stays in_progress for a retry), never flips unverified work to done. A run ending never auto-closes it.
const closed = await executor.closeAgentTask(
  ctx,
  "TK-1A2B3C4D5E",
  { summary: "Deck drafted; 12 slides." },
  { verifyCompletion }, // required only when execution.definitionOfDone is set
);

import { mergeQueue } from "@nightowlsdev/tasks";
import type { Task } from "@nightowlsdev/tasks";
import type { PendingApproval } from "@nightowlsdev/core";

declare const tasks: Task[];                 // from registry.list — typically open / in_progress / needs_input / blocked
declare const approvals: PendingApproval[];  // from engine.listOrgPendingApprovals(ctx) — already epoch-stamped
declare const issues: { reference: string; status: string; title: string; occurrences: number; lastSeenAt?: string }[];

// mergeQueue is PURE — no I/O. The route fetches the three operator sources with the authenticated ctx and calls
// it. Each member normalizes its own timestamp into one epoch sortAt; the merge is DESC by sortAt, then ASC by a
// deterministic tieBreak, so the same inputs order identically across runtimes. Omit issues and the queue carries
// no kind "issue"; a single malformed timestamp sorts LAST rather than throwing the whole merge.
const queue = mergeQueue({ tasks, approvals, issues });

// illustrative — the host wires the plane on the runner, then mounts one route per file. The tasks API above
// is compiled against @nightowlsdev/tasks' src; this wiring spans runner-nextjs + host auth/storage, so it is
// shown as-is rather than machine-compiled.
import { createNextjsRunner } from "@nightowlsdev/runner-nextjs";
import { createTaskProviderRegistry, createInternalTaskStore, createAgentTaskExecutor } from "@nightowlsdev/tasks";

const registry = createTaskProviderRegistry({ providers: [createInternalTaskStore({ pool })] });
const executor = createAgentTaskExecutor({ pool });

const runner = createNextjsRunner({
  engine, auth, storage,
  taskPlane: {
    registry,                                      // the only REQUIRED member — a human-only board needs nothing else
    execution: { executor, startDeps, closeDeps }, // unlocks start/close (host supplies the resolver + verifier)
  },
});

// One mount per App Router route file, under /api/swarm:
export const { GET, POST } = runner.taskRoutes().board;   // /api/swarm/tasks       — ADMIN board (adminRouteGate("tasks"))
export const { GET }       = runner.taskRoutes().mine;    // /api/swarm/tasks/mine  — PARTICIPANT, the caller's own rows only
export const { GET }       = runner.taskRoutes().detail;  // /api/swarm/tasks/[ref] — ADMIN, one task + its activity
export const { GET }       = runner.taskRoutes().queue;   // /api/swarm/tasks/queue — ADMIN, the unified queue