@agentage/extension 0.1.2 → 0.2.1

package/dist/tool/up/ports.js

@@ -0,0 +1,22 @@
+import { mustRun } from '../exec.js';
+import { GATEWAY_PORT, ISSUER_PORT } from './gateway.js';
+const FORMAT = '{{.Names}}\t{{.Label "com.docker.compose.project"}}\t{{.Ports}}';
+const runningContainers = async (run) => (await mustRun(run, 'docker', ['ps', '--format', FORMAT]))
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .map((line) => {
+    const [name = '', project = '', ports = ''] = line.split('\t');
+    return { name, project, ports };
+});
+const heldPort = (holder) => [GATEWAY_PORT, ISSUER_PORT].find((port) => holder.ports.includes(`:${port}->`));
+const refusal = (holder, port) => new Error(holder.project
+    ? `localhost:${port} is held by compose project ${holder.project}: run agentage extension down in the working copy that started it, then up again`
+    : `localhost:${port} is held by container ${holder.name}: stop it, then up again`);
+// Before anything starts: the gateway and issuer ports are free, or this working copy's own.
+export const assertPortsFree = async (run, project) => {
+    for (const holder of await runningContainers(run)) {
+        const port = heldPort(holder);
+        if (port !== undefined && holder.project !== project)
+            throw refusal(holder, port);
+    }
+};

package/dist/tool/up/project.d.ts

@@ -0,0 +1,4 @@
+export declare const projectName: (id: string, dir: string) => string;
+export declare const legacyProject: (id: string) => string;
+export declare const workingCopy: (dir?: string) => Promise<string>;
+export declare const renderedProject: (file: string) => Promise<string | undefined>;

package/dist/tool/up/project.js

@@ -0,0 +1,20 @@
+import { createHash } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { readJsonIfExists } from '../../manifest/read-manifest.js';
+// One compose project per working copy: two checkouts of one extension never share containers or data.
+export const projectName = (id, dir) => `agentage-${id}-${createHash('sha256').update(dir).digest('hex').slice(0, 8)}`;
+// Kit 0.2.0 named one project per id, shared by every copy; down still removes it.
+export const legacyProject = (id) => `agentage-${id}`;
+// Absolute, symlinks resolved, so one working copy always gets the same project name.
+export const workingCopy = async (dir = '.') => {
+    const absolute = resolve(dir);
+    return realpath(absolute).catch(() => absolute);
+};
+const RenderedSchema = z.object({ name: z.string().regex(/^[a-z0-9][a-z0-9_-]*$/) });
+// The project a rendered compose file names; down trusts it only when it is this folder's own.
+export const renderedProject = async (file) => {
+    const parsed = RenderedSchema.safeParse(await readJsonIfExists(file).catch(() => undefined));
+    return parsed.success ? parsed.data.name : undefined;
+};

package/dist/tool/up/store-line.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+declare const MigrateSummarySchema: z.ZodObject<{
+    migrations: z.ZodInt;
+    applied: z.ZodInt;
+    seeds: z.ZodInt;
+    seedsBefore: z.ZodDefault<z.ZodInt>;
+}, z.core.$strip>;
+export type MigrateSummary = z.infer<typeof MigrateSummarySchema>;
+export declare const summaryOf: (out: string) => MigrateSummary;
+export declare const storePhrase: (summary: MigrateSummary) => string;
+export {};

package/dist/tool/up/store-line.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { plural } from './lines.js';
+// The migrate entry's last stdout line (migrate.ts); an image on kit 0.2.0 prints no seedsBefore.
+const MigrateSummarySchema = z.object({
+    migrations: z.int().min(0),
+    applied: z.int().min(0),
+    seeds: z.int().min(0),
+    seedsBefore: z.int().min(0).default(0),
+});
+const lastJson = (out) => {
+    try {
+        return JSON.parse(out.trim().split('\n').at(-1) ?? '');
+    }
+    catch {
+        return undefined;
+    }
+};
+export const summaryOf = (out) => {
+    const parsed = MigrateSummarySchema.safeParse(lastJson(out));
+    if (!parsed.success)
+        throw new Error(`the migrate job printed no summary: ${out.slice(-200)}`);
+    return parsed.data;
+};
+const migrationsPhrase = ({ migrations, applied }) => {
+    const already = migrations - applied;
+    if (already === 0)
+        return `${plural(applied, 'migration')} applied`;
+    if (applied === 0)
+        return `${plural(already, 'migration')} already applied`;
+    return `${plural(applied, 'migration')} applied, ${already} already applied`;
+};
+const seedsPhrase = ({ seeds, seedsBefore }) => seeds === 0 && seedsBefore > 0
+    ? `${plural(seedsBefore, 'seed')} already applied`
+    : plural(seeds, 'seed');
+// A kept volume says so: what this run applied, and what an earlier run already had.
+export const storePhrase = (summary) => `${migrationsPhrase(summary)} · ${seedsPhrase(summary)}`;

package/dist/tool/up/token.d.ts

@@ -0,0 +1,6 @@
+export interface TokenOptions {
+    scope: string;
+    issuer?: string;
+    fetch?: typeof fetch;
+}
+export declare const token: (options: TokenOptions) => Promise<string>;

package/dist/tool/up/token.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { TIMEOUTS } from '../timeouts.js';
+import { DEV_ISSUER } from './dev-issuer-app.js';
+const AnswerSchema = z.object({ token: z.string().startsWith('aga_') });
+// A token from the dev issuer of `up`, for calling /api/v1/ and /mcp by hand or from tests.
+export const token = async (options) => {
+    const issuer = options.issuer ?? DEV_ISSUER;
+    const res = await (options.fetch ?? fetch)(`${issuer}/token`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ scope: options.scope }),
+        signal: AbortSignal.timeout(TIMEOUTS.issuer),
+    }).catch((err) => {
+        if (err.name === 'TimeoutError')
+            throw new Error(`the dev issuer at ${issuer} did not answer in ${TIMEOUTS.issuer / 1000} s`);
+        throw new Error(`no dev issuer at ${issuer}: run agentage extension up first`);
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok)
+        throw new Error(`the dev issuer refused: ${JSON.stringify(body)}`);
+    const answer = AnswerSchema.safeParse(body);
+    if (!answer.success)
+        throw new Error('the dev issuer answered without an aga_ token');
+    return answer.data.token;
+};

package/dist/tool/up/up.d.ts

@@ -0,0 +1,16 @@
+import { type ExtensionPackage } from '../../manifest/manifest.schema.js';
+import { type Env } from '../../runtime/build-info.js';
+import { type WaitDeps } from './wait.js';
+export interface UpOptions {
+    dir?: string;
+    env?: Env;
+    onLine?: (line: string) => void;
+}
+export type UpDeps = WaitDeps;
+export interface UpResult {
+    parts: number;
+    seconds: number;
+    project: string;
+}
+export declare const routesOf: (pkg: ExtensionPackage) => string[];
+export declare const up: (options?: UpOptions, deps?: UpDeps) => Promise<UpResult>;

package/dist/tool/up/up.js

@@ -0,0 +1,84 @@
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import {} from '../../manifest/manifest.schema.js';
+import { hasPostgres, imageParts, normalizeParts } from '../../manifest/parts.js';
+import { readManifest } from '../../manifest/read-manifest.js';
+import {} from '../../runtime/build-info.js';
+import { build } from '../build.js';
+import { quietly, runCommand } from '../exec.js';
+import { exists } from '../stage.js';
+import { TIMEOUTS } from '../timeouts.js';
+import { compose } from './compose-run.js';
+import { composeFile, STORE_IMAGE } from './compose.js';
+import { GATEWAY_PORT, gatewayConfig, ISSUER_PORT, PART_PATHS, partPath } from './gateway.js';
+import { plural, stepLine } from './lines.js';
+import { assertDiscoverable, LOCAL_DIR, writeLocalRecord } from './local-record.js';
+import { assertPortsFree } from './ports.js';
+import { projectName, workingCopy } from './project.js';
+import { storePhrase, summaryOf } from './store-line.js';
+import { waitHealthy } from './wait.js';
+const GATEWAY = `http://localhost:${GATEWAY_PORT}`;
+const jsonFile = (file, value) => writeFile(file, `${JSON.stringify(value, null, 2)}\n`);
+const renderFiles = async (s, recordFile, tags) => {
+    const gatewayFile = join(s.dir, LOCAL_DIR, 'gateway.yml');
+    const seeds = join(s.dir, 'seeds');
+    const seedsDir = (await exists(seeds)) ? seeds : undefined;
+    await jsonFile(gatewayFile, gatewayConfig(imageParts(s.pkg), s.pkg.version));
+    const project = s.target.project;
+    await jsonFile(s.target.file, composeFile({ pkg: s.pkg, project, tags, recordFile, gatewayFile, seedsDir }));
+};
+const buildStep = async (s, env) => {
+    const built = await build({ dir: s.dir, env }, { run: s.deps.run });
+    const images = plural(built.images.length, 'image');
+    s.line('build', `${images} from the release recipes`, 'same recipe and tags as a release');
+    const { file, record } = await writeLocalRecord(s.dir, s.pkg, built, s.deps.run);
+    assertDiscoverable(record, GATEWAY);
+    s.line('record', `${LOCAL_DIR}/record.json`, 'discovery valid');
+    await renderFiles(s, file, Object.fromEntries(built.images.map((i) => [i.part, i.tag])));
+};
+// The migrate job runs before any part starts; a kept volume reports what it already had.
+const storeStep = async (s) => {
+    await compose(s.deps.run, s.target, ['up', '-d', 'store'], TIMEOUTS.start);
+    await waitHealthy(s.target, ['store'], s.deps);
+    const run = ['run', '--rm', '--no-deps', 'migrate'];
+    const out = await compose(s.deps.run, s.target, run, TIMEOUTS.migrate).catch((err) => {
+        throw new Error(`the migrate job failed, no part was started: ${err.message}`);
+    });
+    const summary = summaryOf(out);
+    s.line('store', STORE_IMAGE, storePhrase(summary));
+};
+export const routesOf = (pkg) => Object.keys(PART_PATHS)
+    .filter((part) => imageParts(pkg).includes(part))
+    .map((part) => partPath(part, pkg.version));
+const partsStep = async (s) => {
+    await compose(s.deps.run, s.target, ['up', '-d', '--remove-orphans'], TIMEOUTS.start);
+    await waitHealthy(s.target, [...imageParts(s.pkg), 'gateway', 'issuer'], s.deps);
+    s.line('issuer', 'dev tokens', `http://localhost:${ISSUER_PORT}`);
+    s.line('gateway', GATEWAY, routesOf(s.pkg).join(' · '));
+};
+// The cli part has no container: build's check already proved its handlers match the commands.
+const cliParts = (pkg) => normalizeParts(pkg.agentage.parts).code.cli ? 1 : 0;
+const sessionOf = async (options, deps) => {
+    const dir = await workingCopy(options.dir);
+    const pkg = await readManifest(dir);
+    const file = join(dir, LOCAL_DIR, 'compose.json');
+    const target = { file, project: projectName(pkg.agentage.id, dir) };
+    const line = (label, what, detail) => options.onLine?.(stepLine(label, what, detail));
+    return { dir, pkg, target, line, deps: { ...deps, run: quietly(deps.run) } };
+};
+// The laptop shape of a deployment: the release images, a local record, store, issuer, gateway.
+export const up = async (options = {}, deps = { run: runCommand }) => {
+    const started = Date.now();
+    const s = await sessionOf(options, deps);
+    await assertPortsFree(s.deps.run, s.target.project);
+    await buildStep(s, options.env ?? process.env);
+    // Again after the build: another up may have started meanwhile, and the store comes next.
+    await assertPortsFree(s.deps.run, s.target.project);
+    if (hasPostgres(s.pkg))
+        await storeStep(s);
+    await partsStep(s);
+    const parts = imageParts(s.pkg).length + (hasPostgres(s.pkg) ? 1 : 0) + cliParts(s.pkg);
+    const seconds = Math.round((Date.now() - started) / 1000);
+    s.line('ready', `${plural(parts, 'part')} healthy`, `${seconds} s`);
+    return { parts, seconds, project: s.target.project };
+};

package/dist/tool/up/wait.d.ts

@@ -0,0 +1,8 @@
+import { type Run } from '../exec.js';
+import { type ComposeTarget } from './compose-run.js';
+export interface WaitDeps {
+    run: Run;
+    sleep?: (ms: number) => Promise<void>;
+    timeoutMs?: number;
+}
+export declare const waitHealthy: (target: ComposeTarget, services: string[], deps: WaitDeps) => Promise<void>;

package/dist/tool/up/wait.js

@@ -0,0 +1,26 @@
+import {} from '../exec.js';
+import { compose, states } from './compose-run.js';
+const DEFAULT_TIMEOUT_MS = 180_000;
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const broken = (state) => state !== undefined &&
+    (state.health === 'unhealthy' || state.state === 'exited' || state.state === 'dead');
+const logsOf = async (run, target, service) => compose(run, target, ['logs', '--no-color', '--tail', '20', service]).catch(() => '');
+const failure = async (run, target, state, why) => new Error(`${state.service} ${why}\n${(await logsOf(run, target, state.service)).trim()}`);
+// Every named service healthy (its HEALTHCHECK on 127.0.0.1), or the first broken one with its log.
+export const waitHealthy = async (target, services, deps) => {
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const byService = new Map((await states(deps.run, target)).map((s) => [s.service, s]));
+        const bad = services.map((name) => byService.get(name)).find(broken);
+        if (bad)
+            throw await failure(deps.run, target, bad, `is ${bad.health || bad.state}`);
+        if (services.every((name) => byService.get(name)?.health === 'healthy'))
+            return;
+        if (Date.now() > deadline) {
+            const waiting = services.filter((name) => byService.get(name)?.health !== 'healthy');
+            throw new Error(`not healthy after ${Math.round(timeoutMs / 1000)} s: ${waiting.join(', ')}`);
+        }
+        await (deps.sleep ?? pause)(1000);
+    }
+};

package/dist/ui/ui-app.d.ts

@@ -0,0 +1,8 @@
+import { type Express } from 'express';
+import { type PartAppBase } from '../server/app.js';
+export interface UiAppOptions extends PartAppBase {
+    dir: string;
+    devIssuer?: string;
+}
+export declare const devIssuerOrigin: (value: string | undefined) => string | undefined;
+export declare const createUiApp: (options: UiAppOptions) => Express;

package/dist/ui/ui-app.js

@@ -0,0 +1,39 @@
+import cors from 'cors';
+import express, {} from 'express';
+import { createPartApp, PUBLIC_CORS } from '../server/app.js';
+const LOOPBACK = new Set(['localhost', '127.0.0.1']);
+// AGENTAGE_DEV_ISSUER, when set, must be a loopback http origin: anything else stops the start.
+export const devIssuerOrigin = (value) => {
+    if (!value)
+        return undefined;
+    const url = URL.canParse(value) ? new URL(value) : undefined;
+    if (url?.protocol !== 'http:' || !LOOPBACK.has(url.hostname))
+        throw new Error(`AGENTAGE_DEV_ISSUER ${value} is not a loopback http origin`);
+    return url.origin;
+};
+// Widgets reach their own /mcp and /api only; under `up` also the dev issuer.
+const cspFor = (devIssuer) => ({
+    directives: {
+        defaultSrc: ["'self'"],
+        scriptSrc: ["'self'"],
+        styleSrc: ["'self'", "'unsafe-inline'"],
+        connectSrc: devIssuer ? ["'self'", devIssuer] : ["'self'"],
+        imgSrc: ["'self'", 'data:'],
+        upgradeInsecureRequests: null,
+    },
+});
+const IMMUTABLE = 'public, max-age=31536000, immutable';
+// /ui/{version}/: static widget modules, anonymous, cached forever (a version never changes).
+export const createUiApp = (options) => createPartApp({
+    ...options,
+    part: 'ui',
+    helmet: {
+        contentSecurityPolicy: cspFor(devIssuerOrigin(options.devIssuer)),
+        crossOriginResourcePolicy: { policy: 'cross-origin' },
+    },
+    mount: (app) => void app.use(`/ui/${options.pkg.version}`, cors(PUBLIC_CORS), express.static(options.dir, {
+        index: false,
+        fallthrough: true,
+        setHeaders: (res) => res.setHeader('Cache-Control', IMMUTABLE),
+    })),
+});

package/dist/worker/cron.d.ts

@@ -0,0 +1,11 @@
+export interface Cron {
+    readonly expression: string;
+    readonly sets: readonly ReadonlySet<number>[];
+    readonly anyDay: {
+        dom: boolean;
+        dow: boolean;
+    };
+}
+export declare const parseCron: (expression: string) => Cron;
+export declare const matches: (cron: Cron, date: Date) => boolean;
+export declare const nextRun: (cron: Cron, after: Date) => Date;

package/dist/worker/cron.js

@@ -0,0 +1,73 @@
+// Five fields: minute hour day-of-month month day-of-week (0 or 7 is Sunday), in UTC.
+const FIELDS = [
+    { name: 'minute', min: 0, max: 59 },
+    { name: 'hour', min: 0, max: 23 },
+    { name: 'day of month', min: 1, max: 31 },
+    { name: 'month', min: 1, max: 12 },
+    { name: 'day of week', min: 0, max: 7 },
+];
+const toInt = (text, field) => {
+    const value = Number(text);
+    if (!/^[0-9]+$/.test(text) || value < field.min || value > field.max) {
+        throw new Error(`cron ${field.name}: ${text} is not ${field.min}-${field.max}`);
+    }
+    return value;
+};
+const range = (part, field) => {
+    if (part === '*')
+        return [field.min, field.max];
+    const [from = '', to] = part.split('-');
+    return [toInt(from, field), to === undefined ? toInt(from, field) : toInt(to, field)];
+};
+const expand = (part, field) => {
+    const [base = '', stepText] = part.split('/');
+    const step = stepText === undefined ? 1 : Number(stepText);
+    if (!Number.isInteger(step) || step < 1)
+        throw new Error(`cron ${field.name}: bad step in ${part}`);
+    const [from, to] = range(base, field);
+    if (from > to)
+        throw new Error(`cron ${field.name}: ${part} runs backwards`);
+    const values = [];
+    for (let v = from; v <= to; v += step)
+        values.push(v);
+    return values;
+};
+const fieldSet = (text, field) => {
+    const values = text.split(',').flatMap((part) => expand(part, field));
+    return new Set(field.name === 'day of week' ? values.map((v) => v % 7) : values);
+};
+export const parseCron = (expression) => {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5)
+        throw new Error(`cron "${expression}": five fields expected`);
+    const sets = FIELDS.map((field, i) => fieldSet(parts[i] ?? '', field));
+    return { expression, sets, anyDay: { dom: parts[2] === '*', dow: parts[4] === '*' } };
+};
+// Classic cron: with both day fields restricted, either one matching is enough.
+const dayMatches = (cron, date) => {
+    const dom = cron.sets[2]?.has(date.getUTCDate()) ?? false;
+    const dow = cron.sets[4]?.has(date.getUTCDay()) ?? false;
+    if (cron.anyDay.dom && cron.anyDay.dow)
+        return true;
+    if (cron.anyDay.dom)
+        return dow;
+    if (cron.anyDay.dow)
+        return dom;
+    return dom || dow;
+};
+export const matches = (cron, date) => (cron.sets[0]?.has(date.getUTCMinutes()) ?? false) &&
+    (cron.sets[1]?.has(date.getUTCHours()) ?? false) &&
+    (cron.sets[3]?.has(date.getUTCMonth() + 1) ?? false) &&
+    dayMatches(cron, date);
+const MINUTE = 60_000;
+const HORIZON_MINUTES = 5 * 366 * 24 * 60;
+// The first matching minute strictly after `after`.
+export const nextRun = (cron, after) => {
+    let t = Math.floor(after.getTime() / MINUTE) * MINUTE + MINUTE;
+    for (let i = 0; i < HORIZON_MINUTES; i += 1, t += MINUTE) {
+        const date = new Date(t);
+        if (matches(cron, date))
+            return date;
+    }
+    throw new Error(`cron "${cron.expression}" never runs`);
+};

package/dist/worker/job-options.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const JobNameSchema: z.ZodString;
+export declare const JobOptionsSchema: z.ZodOptional<z.ZodObject<{
+    timeout: z.ZodOptional<z.ZodUnion<readonly [z.ZodInt, z.ZodString]>>;
+}, z.core.$strict>>;
+export interface JobOptions {
+    timeout?: number | string;
+}
+export declare const toMs: (duration: number | string) => number;

package/dist/worker/job-options.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+const UNIT_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 };
+const DurationSchema = z.union([
+    z.int().positive(),
+    z.string().regex(/^[0-9]+(ms|s|m|h)$/, { message: 'a duration like 500ms, 30s, 5m or 1h' }),
+]);
+export const JobNameSchema = z
+    .string()
+    .max(48)
+    .regex(/^[a-z][a-z0-9-]*$/, { message: 'job names are lowercase, digits and dashes' });
+export const JobOptionsSchema = z.strictObject({ timeout: DurationSchema.optional() }).optional();
+export const toMs = (duration) => {
+    if (typeof duration === 'number')
+        return duration;
+    const match = /^([0-9]+)(ms|s|m|h)$/.exec(duration);
+    return Number(match?.[1]) * UNIT_MS[(match?.[2] ?? 'ms')];
+};

package/dist/worker/run-log.d.ts

@@ -0,0 +1,9 @@
+import { type Log } from '../log/log.js';
+export declare const LOG_CAP_BYTES: number;
+export interface RunBuffer {
+    text: string;
+    truncated: boolean;
+}
+export declare const withRunBuffer: <T>(buffer: RunBuffer, fn: () => Promise<T>) => Promise<T>;
+export declare const append: (buffer: RunBuffer, line: string) => void;
+export declare const runLog: (base: Log) => Log;

package/dist/worker/run-log.js

@@ -0,0 +1,38 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { messageOf } from '../log/log.js';
+export const LOG_CAP_BYTES = 64 * 1024;
+const TRUNCATED = '\n[log truncated at 64 KB]\n';
+const current = new AsyncLocalStorage();
+export const withRunBuffer = (buffer, fn) => current.run(buffer, fn);
+// Newlines kept; past the cap the rest is dropped and one marker line says so.
+export const append = (buffer, line) => {
+    if (buffer.truncated)
+        return;
+    const next = `${buffer.text}${line}\n`;
+    if (Buffer.byteLength(next) <= LOG_CAP_BYTES - TRUNCATED.length) {
+        buffer.text = next;
+        return;
+    }
+    buffer.text = `${buffer.text}${TRUNCATED}`;
+    buffer.truncated = true;
+};
+const record = (level, message) => {
+    const buffer = current.getStore();
+    if (buffer)
+        append(buffer, `${level} ${message}`);
+};
+// ctx.log for a worker: the usual JSON line, and inside a run also the run's own log.
+export const runLog = (base) => ({
+    info: (message, fields) => {
+        record('info', message);
+        base.info(message, fields);
+    },
+    warn: (message, fields) => {
+        record('warn', message);
+        base.warn(message, fields);
+    },
+    error: (error, fields) => {
+        record('error', messageOf(error));
+        base.error(error, fields);
+    },
+});

package/dist/worker/runs.d.ts

@@ -0,0 +1,20 @@
+import { type Store } from '../store/store.types.js';
+export type RunStatus = 'ok' | 'failed';
+export interface JobRun {
+    job: string;
+    startedAt: Date;
+    endedAt: Date;
+    status: RunStatus;
+    log: string;
+    timeoutMs?: number;
+}
+export interface RunStore {
+    save(run: JobRun): Promise<void>;
+    last(job: string): Promise<JobRun | undefined>;
+}
+export declare const KEEP_RUNS = 50;
+export declare const RUNS_TABLE = "create table if not exists agentage_job_runs (\n  id bigint generated always as identity primary key,\n  job text not null,\n  started_at timestamptz not null,\n  ended_at timestamptz not null,\n  status text not null,\n  log text not null,\n  timeout_ms integer\n)";
+export declare const storeRuns: (store: Store) => RunStore;
+export declare const memoryRuns: () => RunStore & {
+    all(job: string): JobRun[];
+};

package/dist/worker/runs.js

@@ -0,0 +1,59 @@
+import {} from '../store/store.types.js';
+export const KEEP_RUNS = 50;
+export const RUNS_TABLE = `create table if not exists agentage_job_runs (
+  id bigint generated always as identity primary key,
+  job text not null,
+  started_at timestamptz not null,
+  ended_at timestamptz not null,
+  status text not null,
+  log text not null,
+  timeout_ms integer
+)`;
+const INSERT = `insert into agentage_job_runs (job, started_at, ended_at, status, log, timeout_ms)
+  values ($1, $2, $3, $4, $5, $6)`;
+const PRUNE = `delete from agentage_job_runs where job = $1 and id not in
+  (select id from agentage_job_runs where job = $1 order by id desc limit ${KEEP_RUNS})`;
+const fromRow = (row) => ({
+    job: row.job,
+    startedAt: new Date(row.started_at),
+    endedAt: new Date(row.ended_at),
+    status: row.status,
+    log: row.log,
+    ...(row.timeout_ms === null ? {} : { timeoutMs: row.timeout_ms }),
+});
+const LAST = 'select * from agentage_job_runs where job = $1 order by id desc limit 1';
+const valuesOf = (run) => [
+    run.job,
+    run.startedAt,
+    run.endedAt,
+    run.status,
+    run.log,
+    run.timeoutMs ?? null,
+];
+// Runs live in the extension's own store, in a table the kit owns; the last 50 per job are kept.
+export const storeRuns = (store) => {
+    let table;
+    const ready = () => (table ??= store.query(RUNS_TABLE));
+    return {
+        save: async (run) => {
+            await ready();
+            await store.query(INSERT, valuesOf(run));
+            await store.query(PRUNE, [run.job]);
+        },
+        last: async (job) => {
+            await ready();
+            const { rows } = await store.query(LAST, [job]);
+            return rows[0] ? fromRow(rows[0]) : undefined;
+        },
+    };
+};
+// Without a store the runs live in memory, same rule.
+export const memoryRuns = () => {
+    const runs = new Map();
+    const all = (job) => runs.get(job) ?? [];
+    return {
+        save: async (run) => void runs.set(run.job, [...all(run.job), run].slice(-KEEP_RUNS)),
+        last: async (job) => all(job).at(-1),
+        all,
+    };
+};

package/dist/worker/scheduler.d.ts

@@ -0,0 +1,20 @@
+import { type HealthCheck } from '../health/health.js';
+import { type Log } from '../log/log.js';
+import { type JobOptions } from './job-options.js';
+import { type JobRun, type RunStore } from './runs.js';
+export type Job = () => unknown;
+export type Schedule = (name: string, cron: string, job: Job, options?: JobOptions) => void;
+export interface SchedulerDeps {
+    runs: RunStore;
+    log: Log;
+    now?: () => Date;
+}
+export interface Scheduler {
+    schedule: Schedule;
+    start(): void;
+    stop(): void;
+    run(name: string): Promise<JobRun | undefined>;
+    checks(): Record<string, HealthCheck>;
+}
+export declare const LATE_MS = 60000;
+export declare const createScheduler: (deps: SchedulerDeps) => Scheduler;