@agentage/extension 0.1.1 → 0.2.0

package/dist/tool/up/gateway.js

@@ -0,0 +1,66 @@
+import {} from '../../manifest/primitives.schema.js';
+export const GATEWAY_PORT = 4280;
+export const ISSUER_PORT = 4281;
+export const PART_PORT = 3000;
+export const TRAEFIK_IMAGE = 'traefik:v3.7.17@sha256:68ae5fe5b64ca166704b746a9e8afcd385e36b3f569a5691401bf652d57b3748';
+// The URL layout of api-standards section 1, as the estate's gateway renders it.
+const RESERVED = 'PathPrefix(`/api/`) || Path(`/mcp`) || PathPrefix(`/mcp/`) || PathPrefix(`/ui/`) || PathPrefix(`/.well-known/`) || PathPrefix(`/git/`) || Path(`/health`)';
+const ROUTED = ['api', 'mcp', 'pages', 'ui'];
+const ruleOf = (part, version) => ({
+    api: 'PathPrefix(`/api/v1/`)',
+    mcp: 'Path(`/mcp`)',
+    ui: `PathPrefix(\`/ui/${version}/\`)`,
+    pages: 'PathPrefix(`/`)',
+    worker: undefined,
+})[part];
+const router = (rule, priority, service) => ({
+    rule,
+    priority,
+    service,
+    entryPoints: ['web'],
+    middlewares: ['gateway-headers'],
+});
+const partRouters = (parts, version) => {
+    const routers = {};
+    for (const part of parts) {
+        const rule = ruleOf(part, version);
+        if (rule)
+            routers[part] = router(rule, part === 'pages' ? 1 : 100, part);
+    }
+    const owner = ROUTED.find((part) => parts.includes(part));
+    if (owner)
+        routers['well-known'] = router('PathPrefix(`/.well-known/`)', 100, owner);
+    return routers;
+};
+// Traefik's file provider: a reserved-prefix miss is Traefik's own 404, like the estate gateway.
+export const gatewayConfig = (parts, version) => {
+    const routed = parts.filter((part) => ROUTED.includes(part));
+    const services = {
+        'gateway-miss': { loadBalancer: { servers: [{ url: 'http://127.0.0.1:8081' }] } },
+    };
+    for (const part of routed)
+        services[part] = { loadBalancer: { servers: [{ url: `http://${part}:${PART_PORT}` }] } };
+    const routers = {
+        reserved: router(RESERVED, 50, 'gateway-miss'),
+        ...partRouters(routed, version),
+    };
+    if (!routed.includes('pages'))
+        routers['host'] = router('PathPrefix(`/`)', 1, 'gateway-miss');
+    const headers = {
+        contentTypeNosniff: true,
+        referrerPolicy: 'strict-origin-when-cross-origin',
+        frameDeny: true,
+    };
+    return { http: { middlewares: { 'gateway-headers': { headers } }, services, routers } };
+};
+export const TRAEFIK_COMMAND = [
+    '--global.checkNewVersion=false',
+    '--global.sendAnonymousUsage=false',
+    '--log.format=json',
+    '--providers.file.filename=/etc/traefik/dynamic.yml',
+    '--entryPoints.web.address=:80',
+    // No routers listen here, so every request it receives gets Traefik's own 404.
+    '--entryPoints.miss.address=:8081',
+    '--entryPoints.ping.address=127.0.0.1:8082',
+    '--ping.entryPoint=ping',
+];

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

@@ -0,0 +1,2 @@
+export declare const stepLine: (label: string, what: string, detail?: string) => string;
+export declare const plural: (n: number, word: string) => string;

package/dist/tool/up/lines.js

@@ -0,0 +1,3 @@
+// What `up` and `down` print: a label, what it is, the detail; the columns line up as in a terminal.
+export const stepLine = (label, what, detail = '') => `${label.padEnd(9)}${what.padEnd(45)}${detail}`.trimEnd();
+export const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;

package/dist/tool/up/local-record.d.ts

@@ -0,0 +1,44 @@
+import { type ExtensionRecord } from '../../discovery/discovery.schema.js';
+import { type ExtensionPackage } from '../../manifest/manifest.schema.js';
+import { type BuildResult } from '../build.js';
+import { type Run } from '../exec.js';
+export declare const LOCAL_DIR = ".agentage";
+export declare const assertDiscoverable: (record: ExtensionRecord, origin: string) => void;
+export declare const writeLocalRecord: (dir: string, pkg: ExtensionPackage, built: BuildResult, run: Run) => Promise<{
+    file: string;
+    record: {
+        id: string;
+        version: string;
+        commit: string;
+        buildTime: string;
+        parts: {
+            pages?: {
+                image: string;
+            } | undefined;
+            ui?: {
+                image: string;
+            } | undefined;
+            api?: {
+                image: string;
+            } | undefined;
+            mcp?: {
+                image: string;
+            } | undefined;
+            worker?: {
+                image: string;
+            } | undefined;
+            store?: {
+                kind: "postgres" | "git" | "signoz";
+                migrations?: number | undefined;
+            } | undefined;
+        };
+        openapi?: string | undefined;
+        tools?: string[] | undefined;
+        widgets?: {
+            name: string;
+            element: string;
+            module: string;
+        }[] | undefined;
+        commands?: string[] | undefined;
+    };
+}>;

package/dist/tool/up/local-record.js

@@ -0,0 +1,28 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { discoveryDocument } from '../../discovery/discovery.js';
+import { DiscoveryDocumentSchema } from '../../discovery/discovery.schema.js';
+import { formatIssues } from '../../manifest/read-manifest.js';
+import {} from '../../manifest/manifest.schema.js';
+import { recordFor } from '../build.js';
+import { mustRun } from '../exec.js';
+export const LOCAL_DIR = '.agentage';
+// A local build has no registry digest; the image id from the daemon stands in for it (Q4).
+const localImage = async (run, built) => {
+    const id = (await mustRun(run, 'docker', ['image', 'inspect', '-f', '{{.Id}}', built.tag])).trim();
+    const repository = built.tag.slice(0, built.tag.lastIndexOf(':'));
+    return { ...built, digest: id, image: `${repository}@${id}` };
+};
+export const assertDiscoverable = (record, origin) => {
+    const result = DiscoveryDocumentSchema.safeParse(discoveryDocument(record, origin));
+    if (!result.success)
+        throw new Error(`discovery would be invalid: ${formatIssues(result.error.issues)}`);
+};
+export const writeLocalRecord = async (dir, pkg, built, run) => {
+    const images = await Promise.all(built.images.map((image) => localImage(run, image)));
+    const record = await recordFor(dir, pkg, built, images);
+    await mkdir(join(dir, LOCAL_DIR), { recursive: true });
+    const file = join(dir, LOCAL_DIR, 'record.json');
+    await writeFile(file, `${JSON.stringify(record, null, 2)}\n`);
+    return { file, record };
+};

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,18 @@
+import { z } from 'zod';
+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 }),
+    }).catch(() => {
+        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)}`);
+    return AnswerSchema.parse(body).token;
+};

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

@@ -0,0 +1,19 @@
+import { type ExtensionPackage } from '../../manifest/manifest.schema.js';
+import { type Env } from '../../runtime/build-info.js';
+import { type Run } from '../exec.js';
+export interface UpOptions {
+    dir?: string;
+    env?: Env;
+    onLine?: (line: string) => void;
+}
+export interface UpDeps {
+    run: Run;
+    sleep?: (ms: number) => Promise<void>;
+    timeoutMs?: number;
+}
+export interface UpResult {
+    parts: number;
+    seconds: number;
+}
+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,81 @@
+import { writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { checkCli } from '../../command/check-cli.js';
+import {} from '../../manifest/manifest.schema.js';
+import { 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 { compose } from './compose-run.js';
+import { composeFile, projectName, STORE_IMAGE } from './compose.js';
+import { GATEWAY_PORT, gatewayConfig, ISSUER_PORT } from './gateway.js';
+import { plural, stepLine } from './lines.js';
+import { assertDiscoverable, LOCAL_DIR, writeLocalRecord } from './local-record.js';
+import { waitHealthy } from './wait.js';
+const GATEWAY = `http://localhost:${GATEWAY_PORT}`;
+const renderFiles = async (s, recordFile, tags) => {
+    const gatewayFile = join(s.dir, LOCAL_DIR, 'gateway.yml');
+    await writeFile(gatewayFile, `${JSON.stringify(gatewayConfig(imageParts(s.pkg), s.pkg.version), null, 2)}\n`);
+    await writeFile(s.target.file ?? '', `${JSON.stringify(composeFile({ pkg: s.pkg, tags, recordFile, gatewayFile }), null, 2)}\n`);
+};
+const buildStep = async (s, env) => {
+    const built = await build({ dir: s.dir, env }, { run: s.run });
+    s.line('build', `${plural(built.images.length, 'image')} from the release recipes`, 'same recipe and tags as a release');
+    const { file, record } = await writeLocalRecord(s.dir, s.pkg, built, s.run);
+    assertDiscoverable(record, GATEWAY);
+    s.line('record', `${LOCAL_DIR}/record.json`, 'discovery valid');
+    await renderFiles(s, file, Object.fromEntries(built.images.map((image) => [image.part, image.tag])));
+};
+// The migrate job runs before any part starts; its last stdout line is the summary.
+const storeStep = async (s) => {
+    await compose(s.run, s.target, ['up', '-d', 'store']);
+    await waitHealthy(s.target, ['store'], s.deps);
+    const out = await compose(s.run, s.target, ['run', '--rm', '--no-deps', 'migrate']);
+    const summary = JSON.parse(out.trim().split('\n').at(-1) ?? '{}');
+    s.line('store', STORE_IMAGE, `${plural(summary.applied ?? 0, 'migration')} applied · ${plural(summary.seeds ?? 0, 'seed')}`);
+};
+const ROUTES = { pages: '/', ui: '/ui/{version}/', api: '/api/v1/', mcp: '/mcp' };
+export const routesOf = (pkg) => Object.keys(ROUTES)
+    .filter((part) => imageParts(pkg).includes(part))
+    .map((part) => ROUTES[part].replace('{version}', pkg.version));
+const partsStep = async (s) => {
+    await compose(s.run, s.target, ['up', '-d', '--remove-orphans']);
+    const services = [...imageParts(s.pkg), 'gateway', 'issuer'];
+    await waitHealthy(s.target, services, s.deps);
+    s.line('issuer', 'dev tokens', `http://localhost:${ISSUER_PORT}`);
+    s.line('gateway', GATEWAY, routesOf(s.pkg).join(' · '));
+};
+const cliStep = async (s) => {
+    if (!normalizeParts(s.pkg.agentage.parts).code.cli)
+        return 0;
+    const problem = await checkCli(s.dir);
+    if (problem)
+        throw new Error(`cli part: ${problem}`);
+    return 1;
+};
+// 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 dir = resolve(options.dir ?? '.');
+    const pkg = await readManifest(dir);
+    const target = { file: join(dir, LOCAL_DIR, 'compose.json'), project: projectName(pkg) };
+    const line = (label, what, detail) => options.onLine?.(stepLine(label, what, detail));
+    const s = {
+        dir,
+        pkg,
+        run: quietly(deps.run),
+        target,
+        line,
+        deps: { ...deps, run: quietly(deps.run) },
+    };
+    await buildStep(s, options.env ?? process.env);
+    const store = normalizeParts(pkg.agentage.parts).store === 'postgres';
+    if (store)
+        await storeStep(s);
+    await partsStep(s);
+    const parts = imageParts(pkg).length + (store ? 1 : 0) + (await cliStep(s));
+    const seconds = Math.round((Date.now() - started) / 1000);
+    line('ready', `${plural(parts, 'part')} healthy`, `${seconds} s`);
+    return { parts, seconds };
+};

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,24 @@
+import {} from '../exec.js';
+import { compose, states } from './compose-run.js';
+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 deadline = Date.now() + (deps.timeoutMs ?? 180_000);
+    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((deps.timeoutMs ?? 180_000) / 1000)} s: ${waiting.join(', ')}`);
+        }
+        await (deps.sleep ?? pause)(1000);
+    }
+};

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

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

package/dist/ui/ui-app.js

@@ -0,0 +1,26 @@
+import cors from 'cors';
+import express, {} from 'express';
+import { createPartApp, PUBLIC_CORS } from '../server/app.js';
+// Widgets reach their own /mcp and /api only; the dev issuer of `up` is the one other origin.
+const CSP = {
+    directives: {
+        defaultSrc: ["'self'"],
+        scriptSrc: ["'self'"],
+        styleSrc: ["'self'", "'unsafe-inline'"],
+        connectSrc: ["'self'", 'http://localhost:4281', 'http://127.0.0.1:4281'],
+        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: CSP, 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 }),
+});
+// 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();
+            const values = [
+                run.job,
+                run.startedAt,
+                run.endedAt,
+                run.status,
+                run.log,
+                run.timeoutMs ?? null,
+            ];
+            await store.query(INSERT, values);
+            await store.query(PRUNE, [run.job]);
+        },
+        last: async (job) => {
+            await ready();
+            const sql = 'select * from agentage_job_runs where job = $1 order by id desc limit 1';
+            const { rows } = await store.query(sql, [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;