@agentage/extension 0.2.0 → 0.3.0

package/dist/mcp/mcp-app.js

@@ -3,15 +3,17 @@ import { pipeline } from 'node:stream/promises';
 import cors from 'cors';
 import express, {} from 'express';
 import { createMcpHandler } from '@modelcontextprotocol/server';
+import { strongest } from '../auth/token-check.js';
 import { fail } from '../envelope/envelope.js';
 import { BODY_LIMIT, createPartApp, PUBLIC_CORS } from '../server/app.js';
 import { serverFactory } from './server.js';
-import {} from './tools.js';
+import { prefixed } from './tools.js';
 const MCP_HEADERS = ['Mcp-Protocol-Version', 'Mcp-Method', 'Mcp-Name', 'Accept'];
 const MCP_CORS = {
     ...PUBLIC_CORS,
     allowedHeaders: [...PUBLIC_CORS.allowedHeaders, ...MCP_HEADERS],
 };
+const PARSE_ERROR = { jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' }, id: null };
 const parsed = (body) => {
     try {
         return JSON.parse(body.toString('utf8'));
@@ -20,7 +22,28 @@ const parsed = (body) => {
         return undefined;
     }
 };
-const isListing = (body) => (Array.isArray(body) ? body : [body]).some((message) => message?.method === 'tools/list');
+const messagesOf = (body) => (Array.isArray(body) ? body : [body]);
+const isListing = (body) => messagesOf(body).some((message) => message?.method === 'tools/list');
+// Each tools/call needs its tool's declared scope (read when it declares none).
+const callAccess = (options, body) => messagesOf(body)
+    .filter((message) => message?.method === 'tools/call')
+    .map((message) => {
+    const id = options.pkg.agentage.id;
+    const entry = options.tools.find((t) => prefixed(id, t.name) === message?.params?.name);
+    return entry?.spec.scope ?? 'read';
+});
+// Tokens off: calls stay anonymous and a closed listing refuses every tools/list (nothing can verify).
+const guard = async (options, req, body) => {
+    const listing = options.listing === 'token' && isListing(body) ? ['read'] : [];
+    const needed = [...listing, ...callAccess(options, body)];
+    if (!options.tokenCheck) {
+        if (listing.length > 0)
+            throw fail('UNAUTHORIZED', 'tools/list needs a token');
+        return;
+    }
+    if (needed.length > 0)
+        await options.tokenCheck(req.get('authorization'), strongest(needed));
+};
 const webRequest = (req, body) => {
     const headers = new Headers();
     for (const [key, value] of Object.entries(req.headers)) {
@@ -40,12 +63,13 @@ const send = async (response, res) => {
         return void res.end();
     await pipeline(Readable.fromWeb(response.body), res);
 };
-// The kit verifies no token yet, so a closed listing refuses every tools/list.
-const handle = (handler, listing) => async (req, res) => {
+const handle = (handler, options) => async (req, res) => {
     const body = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
     const message = parsed(body);
-    if (listing === 'token' && isListing(message))
-        throw fail('UNAUTHORIZED', 'tools/list needs a token');
+    // The SDK reads a body again when given none (a BOM, say): it must only run what guard read.
+    if (message === undefined)
+        return void res.status(400).json(PARSE_ERROR);
+    await guard(options, req, message);
     await send(await handler.fetch(webRequest(req, body), { parsedBody: message }), res);
 };
 const methodNotAllowed = (_req, res) => {
@@ -67,7 +91,7 @@ export const createMcpApp = (options) => {
         part: 'mcp',
         mount: (app) => {
             app.use('/mcp', cors(MCP_CORS));
-            app.post('/mcp', raw, handle(handler, options.listing));
+            app.post('/mcp', raw, handle(handler, options));
             app.all('/mcp', methodNotAllowed);
         },
     });

package/dist/mcp/server.js

@@ -1,21 +1,35 @@
 import { McpServer } from '@modelcontextprotocol/server';
+import { agcidOf } from '../agcid/agcid.js';
 import { currentAgcid } from '../agcid/current.js';
 import { fail, isFailure } from '../envelope/envelope.js';
 import {} from '../log/log.js';
 import { prefixed } from './tools.js';
-const text = (value) => [{ type: 'text', text: JSON.stringify(value) }];
+const text = (value) => [{ type: 'text', text: value }];
 // A failed tool is isError with the REST error shape; anything unexpected is a generic INTERNAL.
+// Outside a request (no agcid in scope) the error still carries a valid one, minted here.
 const errorResult = (err, log) => {
     const failure = isFailure(err) ? err : fail('INTERNAL', 'Internal error');
     if (failure.status >= 500)
         log.error(err);
-    const error = { code: failure.code, message: failure.message, agcid: currentAgcid() ?? '' };
-    return { isError: true, content: text({ error }), structuredContent: { error } };
+    const error = { code: failure.code, message: failure.message, agcid: agcidOf(currentAgcid()) };
+    return { isError: true, content: text(error.message), structuredContent: { error } };
+};
+// The kit, not the SDK, refuses bad arguments (C7): the SDK lists the schema, passes all through.
+const listedOnly = (input) => ({
+    '~standard': { ...input['~standard'], validate: (value) => ({ value }) },
+});
+const argsOf = (entry, args) => {
+    const parsed = entry.spec.input.safeParse(args);
+    if (parsed.success)
+        return parsed.data;
+    const fields = new Set(parsed.error.issues.map((issue) => issue.path.join('.') || '(root)'));
+    throw fail('VALIDATION_ERROR', `Invalid arguments: ${[...fields].join(', ')}`);
 };
 const callback = (entry, log) => async (args) => {
     try {
-        const output = entry.spec.output.parse(await entry.handler(args));
-        return { content: text(output), structuredContent: output };
+        const output = entry.spec.output.parse(await entry.handler(argsOf(entry, args)));
+        const content = text(JSON.stringify(output));
+        return { content, structuredContent: output };
     }
     catch (err) {
         return errorResult(err, log);
@@ -27,7 +41,7 @@ export const serverFactory = (identity, tools, log) => () => {
     for (const entry of tools) {
         const config = {
             description: entry.spec.description,
-            inputSchema: entry.spec.input,
+            inputSchema: listedOnly(entry.spec.input),
             outputSchema: entry.spec.output,
         };
         server.registerTool(prefixed(identity.id, entry.name), config, callback(entry, log));

package/dist/mcp/tools.d.ts

@@ -1,10 +1,12 @@
 import { type z } from 'zod';
+import { type Access } from '../auth/token-check.js';
 import { type PartContext } from '../context/context.js';
 type ObjectSchema = z.ZodObject;
 export interface ToolSpec<I extends ObjectSchema, O extends ObjectSchema> {
     description: string;
     input: I;
     output: O;
+    scope?: Access;
 }
 export type ToolHandler<I extends ObjectSchema, O extends ObjectSchema> = (args: z.output<I>) => z.input<O> | Promise<z.input<O>>;
 export type ToolRegistrar = <I extends ObjectSchema, O extends ObjectSchema>(name: string, spec: ToolSpec<I, O>, handler: ToolHandler<I, O>) => void;

package/dist/mcp/tools.js

@@ -1,6 +1,8 @@
 import {} from 'zod';
+import {} from '../auth/token-check.js';
 import {} from '../context/context.js';
 const TOOL_NAME = /^[a-z][a-z0-9_-]*$/;
+const SCOPES = ['public', 'read', 'write', 'admin'];
 export const createToolRegistry = () => {
     const tools = [];
     const tool = (name, spec, handler) => {
@@ -10,6 +12,8 @@ export const createToolRegistry = () => {
             throw new Error(`tool ${name} is registered twice`);
         if (!spec.description)
             throw new Error(`tool ${name} needs a description: it routes the model`);
+        if (spec.scope !== undefined && !SCOPES.includes(spec.scope))
+            throw new Error(`tool ${name} scope ${String(spec.scope)}: one of ${SCOPES.join(', ')}`);
         tools.push({ name, spec, handler: handler });
     };
     return { tool, tools };

package/dist/runtime/part-runners.d.ts

@@ -1,20 +1,21 @@
 import { type Express } from 'express';
 import { type PartContext } from '../context/context.js';
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+import { type ImportModule } from '../manifest/entry.js';
 import { type ImagePartKind } from '../manifest/primitives.schema.js';
 import { type PartAppBase } from '../server/app.js';
+import { type Env } from './build-info.js';
 export interface RunnerInput {
     dir: string;
     pkg: ExtensionPackage;
-    ctx: PartContext;
+    env: Env;
+    ctx: () => PartContext;
     base: PartAppBase;
-    importModule?: (file: string) => Promise<unknown>;
+    openapi: Record<string, unknown> | null;
+    importModule?: ImportModule;
 }
 export interface Running {
     app: Express;
     stop?: () => void;
 }
-type PartCreate = (ctx: never) => unknown;
-export declare const createOf: (mod: unknown, file: string) => PartCreate;
 export declare const RUNNERS: Record<ImagePartKind, (input: RunnerInput) => Promise<Running>>;
-export {};

package/dist/runtime/part-runners.js

@@ -1,57 +1,50 @@
 import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
 import {} from 'express';
 import {} from '../context/context.js';
-import { readOpenapi } from '../discovery/openapi.js';
 import {} from '../manifest/manifest.schema.js';
-import { entryOf, normalizeParts } from '../manifest/parts.js';
+import { loadCreate } from '../manifest/entry.js';
+import { hasPostgres } from '../manifest/parts.js';
 import {} from '../manifest/primitives.schema.js';
 import { createMcpApp } from '../mcp/mcp-app.js';
 import { createToolRegistry } from '../mcp/tools.js';
 import { createPagesApp } from '../pages/pages-app.js';
 import { createApiApp, createPartApp } from '../server/app.js';
 import {} from '../server/part.types.js';
+import {} from './build-info.js';
 import { createUiApp } from '../ui/ui-app.js';
 import { runLog } from '../worker/run-log.js';
 import { memoryRuns, storeRuns } from '../worker/runs.js';
 import { createScheduler } from '../worker/scheduler.js';
-const importFile = (file) => import(pathToFileURL(file).href);
-export const createOf = (mod, file) => {
-    const create = mod?.create;
-    if (typeof create !== 'function')
-        throw new Error(`${file} does not export create(ctx)`);
-    return create;
-};
-// Imports the part's entry and calls its create(ctx); ui has no code to run.
-const callCreate = async (input, part, ctx) => {
-    const file = join(input.dir, entryOf(input.pkg, part));
-    const mod = await (input.importModule ?? importFile)(file);
-    return createOf(mod, file)(ctx);
-};
+// ui has no code to run; every other part is its create(ctx).
+const callCreate = async (input, part, ctx) => (await loadCreate(input.dir, input.pkg, part, input.importModule))(ctx);
 const api = async (input) => {
-    const router = (await callCreate(input, 'api', input.ctx));
-    const openapi = await readOpenapi(input.dir);
-    return { app: createApiApp({ ...input.base, router, openapi }) };
+    const router = (await callCreate(input, 'api', input.ctx()));
+    return { app: createApiApp({ ...input.base, router, openapi: input.openapi }) };
 };
 const mcp = async (input) => {
     const registry = createToolRegistry();
-    await callCreate(input, 'mcp', { ...input.ctx, tool: registry.tool });
-    const listing = input.ctx.settings['mcp.listing'] === 'token' ? 'token' : 'open';
+    const ctx = input.ctx();
+    await callCreate(input, 'mcp', { ...ctx, tool: registry.tool });
+    const listing = ctx.settings['mcp.listing'] === 'token' ? 'token' : 'open';
     return { app: createMcpApp({ ...input.base, tools: registry.tools, listing }) };
 };
 const pages = async (input) => {
-    const site = (await callCreate(input, 'pages', input.ctx));
+    const site = (await callCreate(input, 'pages', input.ctx()));
     return { app: createPagesApp({ ...input.base, site }) };
 };
 const ui = async (input) => ({
-    app: createUiApp({ ...input.base, dir: join(input.dir, 'dist', 'ui') }),
+    app: createUiApp({
+        ...input.base,
+        dir: join(input.dir, 'dist', 'ui'),
+        devIssuer: input.env['AGENTAGE_DEV_ISSUER'],
+    }),
 });
 const worker = async (input) => {
-    const log = runLog(input.ctx.log);
-    const hasStore = normalizeParts(input.pkg.agentage.parts).store === 'postgres';
-    const runs = hasStore ? storeRuns(input.ctx.store) : memoryRuns();
+    const ctx = input.ctx();
+    const log = runLog(ctx.log);
+    const runs = hasPostgres(input.pkg) ? storeRuns(ctx.store) : memoryRuns();
     const scheduler = createScheduler({ runs, log });
-    await callCreate(input, 'worker', { ...input.ctx, log, schedule: scheduler.schedule });
+    await callCreate(input, 'worker', { ...ctx, log, schedule: scheduler.schedule });
     const checks = { ...input.base.checks, ...scheduler.checks() };
     scheduler.start();
     return {

package/dist/runtime/run-part.d.ts

@@ -1,14 +1,14 @@
 import { type Server } from 'node:http';
+import { type ImportModule } from '../manifest/entry.js';
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
 import { type ImagePartKind } from '../manifest/primitives.schema.js';
 import { type ServeOptions } from '../server/serve.js';
 import { type Env } from './build-info.js';
-export { createOf } from './part-runners.js';
 export interface RunPartOptions {
     dir: string;
     part: string;
     env: Env;
-    importModule?: (file: string) => Promise<unknown>;
+    importModule?: ImportModule;
     serve?: Pick<ServeOptions, 'signals' | 'exit'>;
 }
 export declare const partOf: (pkg: ExtensionPackage, part: string) => ImagePartKind;

package/dist/runtime/run-part.js

@@ -2,17 +2,21 @@ import {} from 'node:http';
 import { createContext } from '../context/context.js';
 import { settingsFromEnv } from '../context/settings.js';
 import { DEFAULT_RECORD_FILE, loadRecord } from '../discovery/discovery.js';
-import {} from '../health/health.js';
+import {} from '../discovery/discovery.schema.js';
+import { declaredScopes, partAuth } from '../auth/part-auth.js';
+import { readOpenapi } from '../discovery/openapi.js';
 import { createLog } from '../log/log.js';
+import {} from '../manifest/entry.js';
 import {} from '../manifest/manifest.schema.js';
-import { imageParts, normalizeParts } from '../manifest/parts.js';
+import { hasPostgres, imageParts } from '../manifest/parts.js';
 import {} from '../manifest/primitives.schema.js';
 import { readManifest } from '../manifest/read-manifest.js';
+import {} from '../server/app.js';
 import { serve } from '../server/serve.js';
 import { createStore, storeCheck } from '../store/store.js';
+import {} from '../store/store.types.js';
 import { buildInfoFromEnv, portFromEnv } from './build-info.js';
 import { RUNNERS } from './part-runners.js';
-export { createOf } from './part-runners.js';
 const recordFor = async (env, log) => {
     const file = env['AGENTAGE_RECORD_FILE'] || DEFAULT_RECORD_FILE;
     const record = await loadRecord(file);
@@ -27,34 +31,56 @@ export const partOf = (pkg, part) => {
     return part;
 };
 // ui serves files and gets no ctx; every other part gets the store when the manifest has postgres.
-const storeFor = (pkg, part, env, log) => part !== 'ui' && normalizeParts(pkg.agentage.parts).store === 'postgres'
-    ? createStore(env, log)
-    : undefined;
-const inputFor = async (options, pkg, part, log) => {
-    const { env } = options;
-    const origin = env['AGENTAGE_ORIGIN'] || undefined;
-    const build = buildInfoFromEnv(env);
-    const store = storeFor(pkg, part, env, log);
-    const settings = settingsFromEnv(pkg, env, log);
-    const ctxOrigin = origin ?? `http://127.0.0.1:${portFromEnv(env)}`;
-    const ctxPart = (part === 'ui' ? 'pages' : part);
-    const ctx = createContext({
+const storeFor = ({ pkg, part, env, log }) => part !== 'ui' && hasPostgres(pkg) ? createStore(env, log) : undefined;
+const contextFor = (start, part, store) => createContext({
+    pkg: start.pkg,
+    part,
+    origin: start.env['AGENTAGE_ORIGIN'] || `http://127.0.0.1:${portFromEnv(start.env)}`,
+    commit: buildInfoFromEnv(start.env).commit,
+    log: start.log,
+    settings: settingsFromEnv(start.pkg, start.env, start.log),
+    store,
+});
+// Built on first use, so the ui runner, which never asks, has no ctx at all.
+const lazyContext = (start, store) => {
+    let ctx;
+    return () => {
+        if (start.part === 'ui')
+            throw new Error('the ui part gets no ctx');
+        return (ctx ??= contextFor(start, start.part, store));
+    };
+};
+const guardFor = async (start, openapi, record) => {
+    if (start.part !== 'api' && start.part !== 'mcp')
+        return { checks: {} };
+    const { id } = start.pkg.agentage;
+    return partAuth(start.env, id, start.log, declaredScopes(id, openapi, record?.tools));
+};
+const baseFor = async (start, store, openapi) => {
+    const { pkg, env, log } = start;
+    const record = await recordFor(env, log);
+    const guard = await guardFor(start, openapi, record);
+    return {
         pkg,
-        part: ctxPart,
-        origin: ctxOrigin,
-        commit: build.commit,
         log,
-        settings,
-        store,
-    });
-    const record = await recordFor(env, log);
-    const checks = store ? { store: storeCheck(store) } : {};
-    const base = { pkg, build, log, record, origin, ownImage: env['AGENTAGE_IMAGE'], checks };
+        record,
+        ...guard,
+        checks: { ...(store ? { store: storeCheck(store) } : {}), ...guard.checks },
+        build: buildInfoFromEnv(env),
+        origin: env['AGENTAGE_ORIGIN'] || undefined,
+        ownImage: env['AGENTAGE_IMAGE'],
+    };
+};
+const inputFor = async (options, start) => {
+    const store = storeFor(start);
+    const openapi = await readOpenapi(options.dir);
     return {
         dir: options.dir,
-        pkg,
-        ctx,
-        base,
+        pkg: start.pkg,
+        env: start.env,
+        ctx: lazyContext(start, store),
+        base: await baseFor(start, store, openapi),
+        openapi,
         importModule: options.importModule,
     };
 };
@@ -62,7 +88,8 @@ export const runPart = async (options) => {
     const pkg = await readManifest(options.dir);
     const part = partOf(pkg, options.part);
     const log = createLog({ extension: pkg.agentage.id, part });
-    const { app, stop } = await RUNNERS[part](await inputFor(options, pkg, part, log));
+    const start = { pkg, part, env: options.env, log };
+    const { app, stop } = await RUNNERS[part](await inputFor(options, start));
     if (stop)
         for (const signal of options.serve?.signals ?? ['SIGTERM', 'SIGINT'])
             process.once(signal, stop);

package/dist/server/app.d.ts

@@ -1,6 +1,7 @@
 import { type CorsOptions } from 'cors';
 import { type Express } from 'express';
 import { type HelmetOptions } from 'helmet';
+import { type TokenCheck } from '../auth/token-check.js';
 import { type BuildInfo } from '../discovery/discovery.js';
 import { type ExtensionRecord } from '../discovery/discovery.schema.js';
 import { type HealthCheck } from '../health/health.js';
@@ -16,6 +17,8 @@ export interface PartAppBase {
     ownImage?: string;
     origin?: string;
     checks?: Record<string, HealthCheck>;
+    tokenCheck?: TokenCheck;
+    resource?: Record<string, unknown>;
 }
 export interface PartAppOptions extends PartAppBase {
     part: ImagePartKind;

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';
@@ -43,6 +45,9 @@ export const createPartApp = (options) => {
     if (options.part !== 'worker') {
         app.use('/.well-known', cors(PUBLIC_CORS));
         app.get('/.well-known/agentage-extension.json', discoveryHandler(options));
+        const { resource } = options;
+        if (resource)
+            app.get('/.well-known/oauth-protected-resource', (_req, res) => void res.json(resource));
     }
     options.mount(app);
     app.use(notFound);
@@ -51,6 +56,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 +71,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/server/errors.js

@@ -25,5 +25,7 @@ export const errorHandler = (log) => (err, _req, res, _next) => {
         log.error(err);
     if (failure.retryAfter !== undefined)
         res.setHeader('Retry-After', String(failure.retryAfter));
+    for (const [name, value] of Object.entries(failure.headers ?? {}))
+        res.setHeader(name, value);
     res.status(failure.status).json(errorEnvelope(failure, agcidOfResponse(res)));
 };

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');