@agentage/extension 0.2.0 → 0.2.1

package/dist/server/app.js

@@ -2,6 +2,8 @@ import cors, {} from 'cors';
 import express, {} from 'express';
 import helmet, {} from 'helmet';
 import { agcidMiddleware } from '../agcid/scope.js';
+import { routeAccess } from '../auth/route-access.js';
+import { setCaller } from '../auth/token-check.js';
 import { discoveryDocument, recordOf, } from '../discovery/discovery.js';
 import {} from '../discovery/discovery.schema.js';
 import { createHealthHandler } from '../health/health.js';
@@ -51,6 +53,14 @@ export const createPartApp = (options) => {
 };
 // The committed OpenAPI document, bare JSON and anonymous like discovery (api-standards section 1).
 const openapiHandler = (doc) => (_req, res) => void res.json(doc);
+// Before the body is read: each request checked for the access its OpenAPI operation declares.
+const routeGuard = (options) => async (req, _res, next) => {
+    if (!options.tokenCheck)
+        return next();
+    const access = routeAccess(options.openapi, req.method, `/api/v1${req.path}`);
+    setCaller(req, await options.tokenCheck(req.get('authorization'), access));
+    next();
+};
 export const createApiApp = (options) => createPartApp({
     ...options,
     part: 'api',
@@ -58,6 +68,7 @@ export const createApiApp = (options) => createPartApp({
         app.use('/api/v1', cors(PUBLIC_CORS));
         if (options.openapi)
             app.get('/api/v1/openapi.json', openapiHandler(options.openapi));
-        app.use('/api/v1', express.json({ limit: BODY_LIMIT }), options.router);
+        const json = express.json({ limit: BODY_LIMIT });
+        app.use('/api/v1', routeGuard(options), json, options.router);
     },
 });

package/dist/store/migrate.js

@@ -3,12 +3,16 @@ import { createLog } from '../log/log.js';
 import { readManifest } from '../manifest/read-manifest.js';
 import { migrate } from './migrations.js';
 import { createStore } from './store.js';
+// A migration may rewrite a table: minutes, not a request's seconds; the job itself has no retry.
+const MIGRATE_TIMEOUTS = { connectMs: 10_000, statementMs: 300_000 };
 // The api image's migrate entry (`node dist/store/migrate.js` in /app), run as a job before a rollout.
-const log = createLog({ extension: 'unknown', part: 'migrate' });
+// Until the manifest is read the id is unknown; every line after it carries the extension.
+let log = createLog({ extension: 'unknown', part: 'migrate' });
 try {
     const pkg = await readManifest(process.cwd());
-    const store = createStore(process.env, log);
-    const result = await migrate(store, process.cwd(), createLog({ extension: pkg.agentage.id, part: 'migrate' }));
+    log = createLog({ extension: pkg.agentage.id, part: 'migrate' });
+    const store = createStore(process.env, log, MIGRATE_TIMEOUTS);
+    const result = await migrate(store, process.cwd(), log);
     process.stdout.write(`${JSON.stringify(result)}\n`);
     await store.end();
 }

package/dist/store/migrations.d.ts

@@ -5,6 +5,8 @@ export interface MigrateResult {
     migrations: number;
     applied: number;
     seeds: number;
+    seedsBefore: number;
 }
 export declare const sqlFiles: (dir: string) => Promise<string[]>;
+export declare const SEEDS_OWED = "seeds:owed";
 export declare const migrate: (store: Store, dir: string, log: Log) => Promise<MigrateResult>;

package/dist/store/migrations.js

@@ -1,6 +1,6 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import {} from '../log/log.js';
+import { messageOf } from '../log/log.js';
 import {} from './store.types.js';
 export const SQL_FILE = /^[0-9]{3}-[a-z0-9-]+\.sql$/;
 // Filename order; anything else in the folder is refused, so a typo never silently skips a file.
@@ -23,6 +23,14 @@ const LEDGER = `create table if not exists _migrations (
   name text primary key,
   applied_at timestamptz not null default now()
 )`;
+const SEED = 'seed:';
+// Written by the first run on an empty store, removed once the seeds ran: a failed first run still seeds later.
+export const SEEDS_OWED = 'seeds:owed';
+// Tables other than the kit's own: a store holding any (a restored dump) never gets the seeds.
+const USER_TABLES = `select count(*)::int as n from information_schema.tables
+  where table_schema not in ('pg_catalog', 'information_schema')
+  and table_name not in ('_migrations', 'agentage_job_runs')`;
+const isEmpty = async (store, done) => done.size === 0 && ((await store.query(USER_TABLES)).rows[0]?.n ?? 0) === 0;
 const appliedNames = async (store) => {
     await store.query(LEDGER);
     const { rows } = await store.query('select name from _migrations');
@@ -31,7 +39,14 @@ const appliedNames = async (store) => {
 // One string, one round trip: the file and its ledger row commit together or not at all.
 const applyFile = async (store, file, name) => {
     const sql = await readFile(file, 'utf8');
-    await store.query(`begin;\n${sql}\n;insert into _migrations (name) values ('${name}');\ncommit;`);
+    try {
+        await store.query(`begin;\n${sql}\n;insert into _migrations (name) values ('${name}');\ncommit;`);
+    }
+    catch (err) {
+        await store.query('rollback').catch(() => undefined);
+        const kind = name.startsWith(SEED) ? 'seed' : 'migration';
+        throw new Error(`${kind} ${name.replace(SEED, '')} failed: ${messageOf(err)}`, { cause: err });
+    }
 };
 const applyAll = async (store, dir, prefix, done) => {
     let count = 0;
@@ -44,12 +59,23 @@ const applyAll = async (store, dir, prefix, done) => {
     }
     return count;
 };
-// Migrations in order, each once; seeds once, only when the store had no ledger row before.
+const seedOnce = async (store, dir, done) => {
+    const seeds = await applyAll(store, join(dir, 'seeds'), SEED, done);
+    await store.query(`delete from _migrations where name = '${SEEDS_OWED}'`);
+    return seeds;
+};
+// Migrations in order, each once; seeds once, only on a store with no ledger row and no user table.
 export const migrate = async (store, dir, log) => {
     const done = await appliedNames(store);
+    const empty = await isEmpty(store, done);
+    if (empty)
+        await store.query(`insert into _migrations (name) values ('${SEEDS_OWED}')`);
+    const owed = empty || done.has(SEEDS_OWED);
     const migrations = (await sqlFiles(join(dir, 'migrations'))).length;
     const applied = await applyAll(store, join(dir, 'migrations'), '', done);
-    const seeds = done.size === 0 ? await applyAll(store, join(dir, 'seeds'), 'seed:', done) : 0;
-    log.info('migrated', { migrations, applied, seeds });
-    return { migrations, applied, seeds };
+    const seeds = owed ? await seedOnce(store, dir, done) : 0;
+    const seedsBefore = [...done].filter((name) => name.startsWith(SEED)).length;
+    const result = { migrations, applied, seeds, seedsBefore };
+    log.info('migrated', { ...result });
+    return result;
 };

package/dist/store/store.d.ts

@@ -5,6 +5,12 @@ import { type Store } from './store.types.js';
 export interface PoolStore extends Store {
     end(): Promise<void>;
 }
+export interface StoreTimeouts {
+    connectMs: number;
+    statementMs: number;
+}
+export declare const PART_TIMEOUTS: StoreTimeouts;
 export declare const storeUrl: (env: Env, read?: (file: string) => string) => string | undefined;
-export declare const createStore: (env: Env, log: Log) => PoolStore;
+export declare const isOutage: (err: unknown) => boolean;
+export declare const createStore: (env: Env, log: Log, timeouts?: StoreTimeouts) => PoolStore;
 export declare const storeCheck: (store: Store) => HealthCheck;

package/dist/store/store.js

@@ -1,9 +1,13 @@
 import { readFileSync } from 'node:fs';
 import pg from 'pg';
+import { fail } from '../envelope/envelope.js';
 import {} from '../health/health.js';
-import {} from '../log/log.js';
+import { messageOf } from '../log/log.js';
 import {} from '../runtime/build-info.js';
 import {} from './store.types.js';
+// A part's query is bounded by the server and, if the network itself hangs, by the client too.
+export const PART_TIMEOUTS = { connectMs: 5_000, statementMs: 10_000 };
+const CLIENT_SLACK_MS = 2_000;
 // The host sets the connection: AGENTAGE_STORE_URL, a secret file named by _FILE, else libpq PG* env.
 export const storeUrl = (env, read = (file) => readFileSync(file, 'utf8')) => {
     const file = env['AGENTAGE_STORE_URL_FILE'];
@@ -11,13 +15,39 @@ export const storeUrl = (env, read = (file) => readFileSync(file, 'utf8')) => {
         return read(file).trim();
     return env['AGENTAGE_STORE_URL'] || undefined;
 };
-export const createStore = (env, log) => {
-    const pool = new pg.Pool({ connectionString: storeUrl(env), max: 5, idleTimeoutMillis: 30_000 });
+// Connection classes 08 and 57P01-03 (shutdown), 57014 (statement timeout), socket errors, pg's own timeouts.
+const OUTAGE_SQLSTATE = /^(08|57P0[1-3]$|57014$)/;
+const OUTAGE_SOCKET = /^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|EHOSTUNREACH|EPIPE)$/;
+const OUTAGE_MESSAGE = /timeout exceeded when trying to connect|Query read timeout|Connection terminated/;
+export const isOutage = (err) => {
+    const code = err?.code;
+    if (typeof code === 'string' && (OUTAGE_SQLSTATE.test(code) || OUTAGE_SOCKET.test(code)))
+        return true;
+    return OUTAGE_MESSAGE.test(messageOf(err));
+};
+// A store that cannot answer is UNAVAILABLE (503, Retry-After), never an INTERNAL 500; no retry here.
+const guarded = (pool, log) => async function query(text, params) {
+    try {
+        return await pool.query(text, params);
+    }
+    catch (err) {
+        if (!isOutage(err))
+            throw err;
+        log.warn('store unavailable', { reason: messageOf(err) });
+        throw fail('UNAVAILABLE', 'The store is unavailable');
+    }
+};
+export const createStore = (env, log, timeouts = PART_TIMEOUTS) => {
+    const pool = new pg.Pool({
+        connectionString: storeUrl(env),
+        max: 5,
+        idleTimeoutMillis: 30_000,
+        connectionTimeoutMillis: timeouts.connectMs,
+        statement_timeout: timeouts.statementMs,
+        query_timeout: timeouts.statementMs + CLIENT_SLACK_MS,
+    });
     pool.on('error', (err) => log.error(err, { store: 'pool' }));
-    return {
-        query: async (text, params) => pool.query(text, params),
-        end: () => pool.end(),
-    };
+    return { query: guarded(pool, log), end: () => pool.end() };
 };
 export const storeCheck = (store) => async () => {
     await store.query('select 1');

package/dist/tool/build.d.ts

@@ -33,6 +33,4 @@ export interface BuildResult {
 }
 export declare const imageTag: (registry: string, pkg: ExtensionPackage, part: ImagePartKind) => string;
 export declare const recordFor: (dir: string, pkg: ExtensionPackage, info: BuildInfo, images: BuiltImage[]) => Promise<ExtensionRecord>;
-declare const writeRecord: (dir: string, record: ExtensionRecord, file?: string) => Promise<string>;
 export declare const build: (options?: BuildOptions, deps?: BuildDeps) => Promise<BuildResult>;
-export { writeRecord };

package/dist/tool/build.js

@@ -8,17 +8,19 @@ import {} from '../manifest/primitives.schema.js';
 import { readManifest } from '../manifest/read-manifest.js';
 import {} from '../runtime/build-info.js';
 import { resolveBuildInfo } from './build-info.js';
+import { assertConforms } from './check.js';
 import { createDocker } from './docker.js';
 import { mustRun, runCommand } from './exec.js';
 import { labelsOf } from './labels.js';
 import { recordExtras } from './record-extras.js';
 import { RECORD_FILE, stageContext } from './stage.js';
+import { TIMEOUTS } from './timeouts.js';
 export const DEFAULT_REGISTRY = 'ghcr.io/agentage';
 export const imageTag = (registry, pkg, part) => `${registry}/${pkg.agentage.id}-${part}:${pkg.version}`;
 const compile = async (dir, pkg, run) => {
     const scripts = pkg.scripts;
     if (typeof scripts?.['build'] === 'string')
-        await mustRun(run, 'npm', ['run', 'build'], { cwd: dir });
+        await mustRun(run, 'npm', ['run', 'build'], { cwd: dir, timeoutMs: TIMEOUTS.compile });
 };
 const buildImage = async (job, docker, tmpRoot) => {
     const context = await stageContext(job.dir, job.pkg, job.part, tmpRoot);
@@ -60,16 +62,16 @@ const buildParts = async (base, options, deps) => {
     }
     return images;
 };
-// Validate, compile, one image per part from the kit recipe; --push pushes and writes the record.
+// Validate, compile, check, one image per part from the kit recipe; --push pushes, writes the record.
 export const build = async (options = {}, deps = { run: runCommand }) => {
     const dir = resolve(options.dir ?? '.');
     const pkg = await readManifest(dir);
     const info = await resolveBuildInfo(dir, options.env ?? process.env, deps.run);
     await compile(dir, pkg, deps.run);
+    await assertConforms({ dir, pkg });
     const images = await buildParts({ dir, pkg, info }, options, deps);
     const result = { id: pkg.agentage.id, version: pkg.version, ...info, images };
     if (!options.push)
         return result;
     return { ...result, recordFile: await writeRecord(dir, await recordFor(dir, pkg, info, images)) };
 };
-export { writeRecord };

package/dist/tool/check.d.ts

@@ -0,0 +1,16 @@
+import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+export interface CheckInput {
+    dir: string;
+    pkg: ExtensionPackage;
+}
+export interface CheckRule {
+    name: string;
+    run(input: CheckInput): Promise<string[]>;
+}
+export interface CheckProblem {
+    rule: string;
+    problem: string;
+}
+export declare const RULES: readonly CheckRule[];
+export declare const check: (input: CheckInput, rules?: readonly CheckRule[]) => Promise<CheckProblem[]>;
+export declare const assertConforms: (input: CheckInput, rules?: readonly CheckRule[]) => Promise<void>;

package/dist/tool/check.js

@@ -0,0 +1,30 @@
+import { checkCli } from '../command/check-cli.js';
+import {} from '../manifest/manifest.schema.js';
+import { imageParts, normalizeParts } from '../manifest/parts.js';
+import { assertBuilt } from './stage.js';
+const problemsOf = (work) => work.then(() => [], (err) => [err.message]);
+// Every image part built where its image looks for it; the cli handlers are exactly the commands.
+const entries = {
+    name: 'entries',
+    run: async ({ dir, pkg }) => {
+        const built = imageParts(pkg).map((part) => problemsOf(assertBuilt(dir, pkg, part)));
+        const cli = normalizeParts(pkg.agentage.parts).code.cli ? await checkCli(dir) : null;
+        return [...(await Promise.all(built)).flat(), ...(cli ? [`cli part: ${cli}`] : [])];
+    },
+};
+// Kit 0.2 has the entries rule; M4 adds manifest, surface, stack, store and sealing beside it.
+export const RULES = [entries];
+export const check = async (input, rules = RULES) => {
+    const found = [];
+    for (const rule of rules)
+        for (const problem of await rule.run(input))
+            found.push({ rule: rule.name, problem });
+    return found;
+};
+// What build runs after the compile and before any image: one failure stops everything.
+export const assertConforms = async (input, rules = RULES) => {
+    const problems = await check(input, rules);
+    if (problems.length === 0)
+        return;
+    throw new Error(`check failed: ${problems.map((p) => `${p.rule}: ${p.problem}`).join('; ')}`);
+};

package/dist/tool/docker.js

@@ -1,4 +1,5 @@
 import { mustRun } from './exec.js';
+import { TIMEOUTS } from './timeouts.js';
 const PLATFORM = 'linux/amd64';
 const flags = (flag, values) => Object.entries(values).flatMap(([key, value]) => [flag, `${key}=${value}`]);
 // No provenance attestation: the pushed digest is then the image itself, as the record expects.
@@ -21,7 +22,7 @@ export const digestOf = (pushOutput) => {
 };
 export const createDocker = (run) => ({
     build: async (options) => {
-        await mustRun(run, 'docker', buildArgsOf(options));
+        await mustRun(run, 'docker', buildArgsOf(options), { timeoutMs: TIMEOUTS.build });
     },
-    push: async (tag) => digestOf(await mustRun(run, 'docker', ['push', tag], { echo: true })),
+    push: async (tag) => digestOf(await mustRun(run, 'docker', ['push', tag], { echo: true, timeoutMs: TIMEOUTS.push })),
 });

package/dist/tool/exec.d.ts

@@ -3,6 +3,7 @@ export interface RunOptions {
     echo?: boolean;
     quiet?: boolean;
     env?: Record<string, string | undefined>;
+    timeoutMs?: number;
 }
 export interface RunResult {
     code: number;

package/dist/tool/exec.js

@@ -1,24 +1,51 @@
 import { spawn } from 'node:child_process';
 import {} from 'node:stream';
-// stdout is captured (and echoed to stderr with `echo`); stderr streams through as progress.
-export const runCommand = (command, args, options = {}) => new Promise((resolve, reject) => {
-    const stdio = ['ignore', 'pipe', options.quiet ? 'pipe' : 'inherit'];
-    const env = options.env ? { ...process.env, ...options.env } : process.env;
-    const child = spawn(command, args, {
-        cwd: options.cwd,
-        stdio: [...stdio],
-        env,
-    });
-    let stdout = '';
-    let stderr = '';
+import { KILL_GRACE_MS, TIMEOUTS } from './timeouts.js';
+const spawnFor = (command, args, options) => spawn(command, args, {
+    cwd: options.cwd,
+    stdio: ['ignore', 'pipe', options.quiet ? 'pipe' : 'inherit'],
+    env: options.env ? { ...process.env, ...options.env } : process.env,
+});
+// Resolves true once the command is past its time and has been told to stop.
+const expiry = (child, ms) => {
+    let timer;
+    const expired = { value: false };
+    timer = setTimeout(() => {
+        expired.value = true;
+        child.kill('SIGTERM');
+        timer = setTimeout(() => child.kill('SIGKILL'), KILL_GRACE_MS).unref();
+    }, ms).unref();
+    return { expired, clear: () => clearTimeout(timer) };
+};
+const timedOut = (command, args, ms) => new Error(`${command} ${args[0] ?? ''} did not finish in ${Math.round(ms / 1000)} s`);
+// stdout is captured (and echoed to stderr with `echo`); a piped stderr is captured too.
+const collect = (child, echo) => {
+    const out = { stdout: '', stderr: '' };
     child.stdout.on('data', (chunk) => {
-        stdout += chunk.toString();
-        if (options.echo)
+        out.stdout += chunk.toString();
+        if (echo)
             process.stderr.write(chunk);
     });
-    child.stderr?.on('data', (chunk) => void (stderr += chunk.toString()));
-    child.on('error', (err) => reject(err.code === 'ENOENT' ? new Error(`${command} is not installed or not on PATH`) : err));
-    child.on('close', (code) => resolve({ code: code ?? 1, stdout, ...(options.quiet ? { stderr } : {}) }));
+    child.stderr?.on('data', (chunk) => void (out.stderr += chunk.toString()));
+    return out;
+};
+// stderr streams through as progress unless `quiet`; past its timeout the command is killed.
+export const runCommand = (command, args, options = {}) => new Promise((resolve, reject) => {
+    const child = spawnFor(command, args, options);
+    const ms = options.timeoutMs ?? TIMEOUTS.command;
+    const timer = expiry(child, ms);
+    const out = collect(child, options.echo);
+    child.on('error', (err) => {
+        timer.clear();
+        reject(err.code === 'ENOENT' ? new Error(`${command} is not installed or not on PATH`) : err);
+    });
+    child.on('close', (code) => {
+        timer.clear();
+        if (timer.expired.value)
+            return reject(timedOut(command, args, ms));
+        const stderr = options.quiet ? { stderr: out.stderr } : {};
+        resolve({ code: code ?? 1, stdout: out.stdout, ...stderr });
+    });
 });
 const tail = (text) => text ? `\n${text.trim().split('\n').slice(-15).join('\n')}` : '';
 export const mustRun = async (run, command, args, options) => {

package/dist/tool/main.js

@@ -1,4 +1,6 @@
 import { parseArgs } from 'node:util';
+import { UsageError } from '../command/args.js';
+import { EXIT_FAILED, EXIT_OK, EXIT_USAGE } from '../command/run-command.js';
 import { build } from './build.js';
 import { buildLines } from './format.js';
 import { down } from './up/down.js';
@@ -14,10 +16,10 @@ const USAGE = `usage: agentage-extension <build|up|down|token> [options]
   token      a dev token: --scope <id>:<verb> [--issuer <url>]
   --dir      the extension package folder (default: the current folder)`;
 const defaultDeps = {
-    build: (options) => build(options),
-    up: (options) => up(options),
-    down: (options) => down(options),
-    token: (options) => token(options),
+    build,
+    up,
+    down,
+    token,
     out: (line) => void process.stdout.write(`${line}\n`),
     err: (line) => void process.stderr.write(`${line}\n`),
 };
@@ -31,8 +33,6 @@ const OPTIONS = {
     help: { type: 'boolean', short: 'h' },
 };
 const parse = (argv) => parseArgs({ args: argv, allowPositionals: true, options: OPTIONS });
-class UsageError extends Error {
-}
 const COMMANDS = {
     build: async (v, deps) => {
         for (const line of buildLines(await deps.build({ push: v.push, dir: v.dir, registry: v.registry })))
@@ -49,34 +49,33 @@ const COMMANDS = {
 const runOne = async (name, values, deps) => {
     try {
         await COMMANDS[name]?.(values, deps);
-        return 0;
+        return EXIT_OK;
     }
     catch (err) {
-        deps.err(err instanceof UsageError
-            ? `${err.message}\n${USAGE}`
-            : `${name} failed: ${err.message}`);
-        return err instanceof UsageError ? 2 : 1;
+        const usage = err instanceof UsageError;
+        deps.err(usage ? `${err.message}\n${USAGE}` : `${name} failed: ${err.message}`);
+        return usage ? EXIT_USAGE : EXIT_FAILED;
     }
 };
-// Exit codes: 0 ok, 1 the step failed, 2 usage.
-export const main = async (argv, deps = defaultDeps) => {
-    let parsed;
+const parsedOrUsage = (argv, deps) => {
     try {
-        parsed = parse(argv);
+        return parse(argv);
     }
     catch (err) {
         deps.err(`${err.message}\n${USAGE}`);
-        return 2;
+        return null;
     }
+};
+// Exit codes: 0 ok, 1 the step failed, 2 usage.
+export const main = async (argv, deps = defaultDeps) => {
+    const parsed = parsedOrUsage(argv, deps);
+    if (!parsed)
+        return EXIT_USAGE;
     const { positionals, values } = parsed;
-    if (values.help) {
-        deps.out(USAGE);
-        return 0;
-    }
+    if (values.help)
+        return (deps.out(USAGE), EXIT_OK);
     const name = positionals[0] ?? '';
-    if (!(name in COMMANDS) || positionals.length !== 1) {
-        deps.err(USAGE);
-        return 2;
-    }
+    if (!(name in COMMANDS) || positionals.length !== 1)
+        return (deps.err(USAGE), EXIT_USAGE);
     return runOne(name, values, deps);
 };

package/dist/tool/record-extras.js

@@ -1,19 +1,18 @@
 import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import { createContext } from '../context/context.js';
 import {} from '../discovery/discovery.js';
+import { WidgetSchema } from '../discovery/discovery.schema.js';
 import { OPENAPI_PATH, readOpenapi } from '../discovery/openapi.js';
 import { createLog } from '../log/log.js';
+import { loadCreate } from '../manifest/entry.js';
 import { readJsonIfExists } from '../manifest/read-manifest.js';
 import {} from '../manifest/manifest.schema.js';
-import { entryOf, normalizeParts } from '../manifest/parts.js';
+import { hasPostgres, normalizeParts } from '../manifest/parts.js';
 import { createToolRegistry, prefixed } from '../mcp/tools.js';
 import { sqlFiles } from '../store/migrations.js';
 import {} from '../store/store.types.js';
-const WidgetsSchema = z
-    .array(z.strictObject({ name: z.string(), element: z.string(), module: z.string() }))
-    .min(1);
+const WidgetsSchema = z.array(WidgetSchema).min(1);
 const noStore = {
     query: async () => {
         throw new Error('the store is not open while the build lists tools');
@@ -31,10 +30,7 @@ export const toolNames = async (dir, pkg) => {
         log: silent,
         store: noStore,
     });
-    const mod = (await import(pathToFileURL(join(dir, entryOf(pkg, 'mcp'))).href));
-    if (typeof mod.create !== 'function')
-        throw new Error('the mcp entry does not export create(ctx)');
-    await mod.create({ ...base, tool: registry.tool });
+    await (await loadCreate(dir, pkg, 'mcp'))({ ...base, tool: registry.tool });
     return registry.tools.map((tool) => prefixed(pkg.agentage.id, tool.name));
 };
 const widgetsOf = async (dir) => {
@@ -43,7 +39,7 @@ const widgetsOf = async (dir) => {
 };
 // What the code serves, for the record: tools, widgets and the migration count.
 export const recordExtras = async (dir, pkg) => {
-    const { code, store } = normalizeParts(pkg.agentage.parts);
+    const { code } = normalizeParts(pkg.agentage.parts);
     const extras = {};
     if (code.mcp) {
         const tools = await toolNames(dir, pkg);
@@ -54,7 +50,7 @@ export const recordExtras = async (dir, pkg) => {
         extras.widgets = await widgetsOf(dir);
     if (code.api && (await readOpenapi(dir)))
         extras.openapi = OPENAPI_PATH;
-    if (store === 'postgres')
+    if (hasPostgres(pkg))
         extras.migrations = (await sqlFiles(join(dir, 'migrations'))).length;
     return extras;
 };

package/dist/tool/stage.d.ts

@@ -3,6 +3,7 @@ import { type ImagePartKind } from '../manifest/primitives.schema.js';
 export declare const RECORD_FILE = "agentage-extension.json";
 export declare const MIGRATE_SHIM = "// Generated by @agentage/extension build.\nimport '@agentage/extension/migrate';\n";
 export declare const localTarballs: (pkg: ExtensionPackage) => string[];
+export declare const exists: (path: string) => Promise<boolean>;
 export declare const appPaths: (dir: string, pkg: ExtensionPackage, part: ImagePartKind) => Promise<string[]>;
 export declare const assertBuilt: (dir: string, pkg: ExtensionPackage, part: ImagePartKind) => Promise<void>;
 export declare const stageContext: (dir: string, pkg: ExtensionPackage, part: ImagePartKind, tmpRoot?: string) => Promise<string>;

package/dist/tool/stage.js

@@ -2,7 +2,7 @@ import { access, cp, mkdir, mkdtemp, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, normalize, sep } from 'node:path';
 import {} from '../manifest/manifest.schema.js';
-import { entryOf, normalizeParts } from '../manifest/parts.js';
+import { entryOf, hasPostgres } from '../manifest/parts.js';
 import {} from '../manifest/primitives.schema.js';
 import { OPENAPI_FILE } from '../discovery/openapi.js';
 import { serverPartRecipe } from './recipe.js';
@@ -25,7 +25,7 @@ export const localTarballs = (pkg) => dependencySpecs(pkg)
     }
     return path;
 });
-const exists = (path) => access(path).then(() => true, () => false);
+export const exists = (path) => access(path).then(() => true, () => false);
 const copyInto = async (from, to) => {
     await mkdir(dirname(to), { recursive: true });
     await cp(from, to, { recursive: true });
@@ -39,25 +39,23 @@ const copyDeps = async (dir, root, pkg) => {
     for (const path of localTarballs(pkg))
         await copyInto(join(dir, path), join(root, 'deps', path));
 };
-// What a part image carries: its own dist/{part}, the shared dist/lib, and for api the store files.
+// The api image runs the migrate job, so it alone carries the migrations; seeds never ship.
+const migrates = (pkg, part) => part === 'api' && hasPostgres(pkg);
+// What a part image carries: its own dist/{part}, the shared dist/lib, and for api the migrations.
 export const appPaths = async (dir, pkg, part) => {
     const paths = ['package.json', join('dist', part)];
     if (part === 'api' && (await exists(join(dir, OPENAPI_FILE))))
         paths.push(OPENAPI_FILE);
     if (await exists(join(dir, 'dist', 'lib')))
         paths.push(join('dist', 'lib'));
-    const postgres = normalizeParts(pkg.agentage.parts).store === 'postgres';
-    if (part === 'api' && postgres) {
-        for (const folder of ['migrations', 'seeds'])
-            if (await exists(join(dir, folder)))
-                paths.push(folder);
-    }
+    if (migrates(pkg, part) && (await exists(join(dir, 'migrations'))))
+        paths.push('migrations');
     return paths;
 };
 const copyApp = async (dir, root, pkg, part) => {
     for (const path of await appPaths(dir, pkg, part))
         await copyInto(join(dir, path), join(root, 'app', path));
-    if (part === 'api' && normalizeParts(pkg.agentage.parts).store === 'postgres') {
+    if (migrates(pkg, part)) {
         await mkdir(join(root, 'app', 'dist', 'store'), { recursive: true });
         await writeFile(join(root, 'app', 'dist', 'store', 'migrate.js'), MIGRATE_SHIM);
     }

package/dist/tool/timeouts.d.ts

@@ -0,0 +1,10 @@
+export declare const TIMEOUTS: {
+    readonly command: 120000;
+    readonly compile: 600000;
+    readonly build: 1200000;
+    readonly push: 600000;
+    readonly start: 600000;
+    readonly migrate: 300000;
+    readonly issuer: 5000;
+};
+export declare const KILL_GRACE_MS = 5000;

package/dist/tool/timeouts.js

@@ -0,0 +1,19 @@
+// Every outbound call the tool makes and its bound; none retries, since a re-run is safe.
+export const TIMEOUTS = {
+    // git rev-parse, docker image inspect, compose ps, logs and down, the port check
+    command: 120_000,
+    // the package's own npm run build
+    compile: 600_000,
+    // docker build: a cold cache pulls the node base image and runs npm ci
+    build: 1_200_000,
+    // docker push to the registry
+    push: 600_000,
+    // compose up: the store and gateway images are pulled on first use
+    start: 600_000,
+    // compose run migrate: the store's migrations and seeds
+    migrate: 300_000,
+    // POST /token to the dev issuer
+    issuer: 5_000,
+};
+// SIGTERM first; a command that ignores it is killed this long after.
+export const KILL_GRACE_MS = 5_000;

package/dist/tool/up/compose-run.d.ts

@@ -9,6 +9,7 @@ export interface ServiceState {
     health: string;
     exitCode: number;
 }
-export declare const compose: (run: Run, target: ComposeTarget, args: string[]) => Promise<string>;
+export declare const composeArgs: (target: ComposeTarget, args: string[]) => string[];
+export declare const compose: (run: Run, target: ComposeTarget, args: string[], timeoutMs?: number) => Promise<string>;
 export declare const parsePs: (stdout: string) => ServiceState[];
 export declare const states: (run: Run, target: ComposeTarget) => Promise<ServiceState[]>;