@agentage/extension 0.1.2 → 0.2.1

package/dist/discovery/discovery.js

@@ -4,21 +4,30 @@ import { normalizeParts } from '../manifest/parts.js';
 import {} from '../manifest/primitives.schema.js';
 import { ExtensionRecordSchema } from './discovery.schema.js';
 export const DEFAULT_RECORD_FILE = '/run/agentage/agentage-extension.json';
-const partsOf = (pkg, images) => {
+const partsOf = (pkg, images, migrations) => {
     const parts = {};
     for (const [kind, image] of Object.entries(images))
         parts[kind] = { image };
     const store = normalizeParts(pkg.agentage.parts).store;
     if (store)
-        parts['store'] = { kind: store };
+        parts['store'] = migrations === undefined ? { kind: store } : { kind: store, migrations };
     return parts;
 };
-// From the manifest, the build and the pushed images by digest; OpenAPI, tools, widgets come later.
-export const recordOf = (pkg, build, images) => {
+// From the manifest, the build, the images by digest and what the code serves; OpenAPI comes later.
+export const recordOf = (pkg, build, images, extras = {}) => {
     const { id, commands } = pkg.agentage;
     const { commit, buildTime } = build;
-    const record = { id, version: pkg.version, commit, buildTime, parts: partsOf(pkg, images) };
-    return commands ? { ...record, commands: commands.map((command) => command.name) } : record;
+    const parts = partsOf(pkg, images, extras.migrations);
+    const record = { id, version: pkg.version, commit, buildTime, parts };
+    if (extras.openapi)
+        record.openapi = extras.openapi;
+    if (extras.tools)
+        record.tools = extras.tools;
+    if (commands)
+        record.commands = commands.map((command) => command.name);
+    if (extras.widgets)
+        record.widgets = extras.widgets;
+    return record;
 };
 export const validateRecord = (value) => {
     const result = ExtensionRecordSchema.safeParse(value);

package/dist/discovery/discovery.schema.d.ts

@@ -1,4 +1,9 @@
 import { z } from 'zod';
+export declare const WidgetSchema: z.ZodObject<{
+    name: z.ZodString;
+    element: z.ZodString;
+    module: z.ZodString;
+}, z.core.$strict>;
 export declare const ExtensionRecordSchema: z.ZodObject<{
     id: z.ZodString;
     version: z.ZodString;
@@ -26,6 +31,7 @@ export declare const ExtensionRecordSchema: z.ZodObject<{
                 git: "git";
                 signoz: "signoz";
             }>;
+            migrations: z.ZodOptional<z.ZodInt>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
     openapi: z.ZodOptional<z.ZodString>;
@@ -65,6 +71,7 @@ export declare const DiscoveryDocumentSchema: z.ZodObject<{
                 git: "git";
                 signoz: "signoz";
             }>;
+            migrations: z.ZodOptional<z.ZodInt>;
         }, z.core.$strict>>;
     }, z.core.$strict>;
     openapi: z.ZodOptional<z.ZodString>;

package/dist/discovery/discovery.schema.js

@@ -13,7 +13,9 @@ const PartsRecordSchema = z
     api: PartImageSchema.optional(),
     mcp: PartImageSchema.optional(),
     worker: PartImageSchema.optional(),
-    store: z.strictObject({ kind: StoreKindSchema }).optional(),
+    store: z
+        .strictObject({ kind: StoreKindSchema, migrations: z.int().min(0).optional() })
+        .optional(),
 })
     .refine((parts) => IMAGE_PART_KINDS.some((kind) => parts[kind] !== undefined), {
     message: 'at least one part with an image',
@@ -22,7 +24,7 @@ const OriginSchema = z
     .string()
     .max(270)
     .regex(/^(https:\/\/[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+|http:\/\/(127\.0\.0\.1|localhost))(:[0-9]{1,5})?$/);
-const WidgetSchema = z.strictObject({
+export const WidgetSchema = z.strictObject({
     name: z.string().regex(/^[a-z][a-z0-9-]*$/),
     element: z.string().regex(/^[a-z][a-z0-9]*-[a-z0-9-]+$/),
     module: z.string().regex(/^\/ui\/[^/]+\/[^/]+\.m?js$/),

package/dist/discovery/openapi.d.ts

@@ -0,0 +1,3 @@
+export declare const OPENAPI_FILE = "openapi.json";
+export declare const OPENAPI_PATH = "/api/v1/openapi.json";
+export declare const readOpenapi: (dir: string) => Promise<Record<string, unknown> | null>;

package/dist/discovery/openapi.js

@@ -0,0 +1,19 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { readJsonIfExists } from '../manifest/read-manifest.js';
+export const OPENAPI_FILE = 'openapi.json';
+export const OPENAPI_PATH = '/api/v1/openapi.json';
+const OpenapiSchema = z.looseObject({
+    openapi: z.string().regex(/^3\.1\.[0-9]+$/, { message: 'OpenAPI 3.1' }),
+    paths: z.record(z.string(), z.unknown()),
+});
+// The api's contract, committed beside package.json (the repo diffs it against its Zod schemas).
+export const readOpenapi = async (dir) => {
+    const value = await readJsonIfExists(join(dir, OPENAPI_FILE));
+    if (value === undefined)
+        return null;
+    const result = OpenapiSchema.safeParse(value);
+    if (!result.success)
+        throw new Error(`${OPENAPI_FILE} is not an OpenAPI 3.1 document`);
+    return result.data;
+};

package/dist/health/health.schema.js

@@ -15,6 +15,6 @@ export const HealthSchema = z.strictObject({
         instance: z.string().regex(/^[0-9a-f]{8,32}$/),
         uptimeSeconds: z.int().min(0),
         checkedAt: z.iso.datetime(),
-        checks: z.record(z.string().regex(/^[a-z][a-z0-9-]*$/), HealthStatusSchema),
+        checks: z.record(z.string().regex(/^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)?$/), HealthStatusSchema),
     }),
 });

package/dist/index.d.ts

@@ -1,13 +1,26 @@
-export { createTestContext, type ExtensionInfo, type LogEntry, type PartContext, type ServerPartKind, type SettingValue, type TestContext, type TestContextOptions, } from './context/context.js';
+export { type ArgValue } from './command/args.js';
+export { type CliContext, type CliCreate, type CommandExtension, type CommandHandler, } from './command/command.types.js';
+export { type Out } from './command/out.js';
+export { type ExtensionInfo, type PartContext, type ServerPartKind, type SettingValue, } from './context/context.js';
+export { createTestContext, type LogEntry, type TestCommandContext, type TestCommandOptions, type TestContext, type TestContextOptions, } from './context/test-context.js';
 export { DiscoveryDocumentSchema, ExtensionRecordSchema, type DiscoveryDocument, type ExtensionRecord, } from './discovery/discovery.schema.js';
+export { AGCID_HEADER, isAgcid } from './agcid/agcid.js';
 export { ERROR_CODES, ERROR_STATUS, type ErrorCode } from './envelope/codes.js';
 export { fail, isFailure, ok, type ErrorDetail, type ErrorEnvelope, type Failure, type FailOptions, type OkEnvelope, } from './envelope/envelope.js';
 export { ErrorEnvelopeSchema, OkEnvelopeSchema } from './envelope/envelope.schema.js';
 export { parse, type ParseSchema } from './envelope/parse.js';
 export { HealthSchema, type HealthBody, type HealthStatus } from './health/health.schema.js';
 export { type Log, type LogFields } from './log/log.js';
-export { PackageSchema, type ExtensionPackage } from './manifest/manifest.schema.js';
+export { PackageSchema, type CommandSpec, type ExtensionPackage, } from './manifest/manifest.schema.js';
 export { imageParts } from './manifest/parts.js';
 export { readManifest, validateManifest } from './manifest/read-manifest.js';
+export { canonical, mcpSnapshot, PROTOCOL_VERSIONS, type McpSnapshot, type ProtocolVersion, } from './mcp/snapshot.js';
+export { type McpContext, type ToolHandler, type ToolRegistrar, type ToolSpec, } from './mcp/tools.js';
+export { versionPage, type PagesContext, type PagesSite } from './pages/pages.js';
 export { type ApiCreate, type ApiHandler, type ApiPart } from './server/part.types.js';
-export { startTestServer, type TestServer, type TestServerOptions } from './testing/test-server.js';
+export { type QueryResult, type Row, type Store } from './store/store.types.js';
+export { startTestMcp, startTestServer, type TestMcpOptions, type TestServer, type TestServerOptions, } from './testing/test-server.js';
+export { type JobOptions } from './worker/job-options.js';
+export { type JobRun, type RunStatus } from './worker/runs.js';
+export { type Job, type Schedule } from './worker/scheduler.js';
+export { type WorkerContext } from './worker/worker.types.js';

package/dist/index.js

@@ -1,13 +1,26 @@
-export { createTestContext, } from './context/context.js';
+export {} from './command/args.js';
+export {} from './command/command.types.js';
+export {} from './command/out.js';
+export {} from './context/context.js';
+export { createTestContext, } from './context/test-context.js';
 export { DiscoveryDocumentSchema, ExtensionRecordSchema, } from './discovery/discovery.schema.js';
+export { AGCID_HEADER, isAgcid } from './agcid/agcid.js';
 export { ERROR_CODES, ERROR_STATUS } from './envelope/codes.js';
 export { fail, isFailure, ok, } from './envelope/envelope.js';
 export { ErrorEnvelopeSchema, OkEnvelopeSchema } from './envelope/envelope.schema.js';
 export { parse } from './envelope/parse.js';
 export { HealthSchema } from './health/health.schema.js';
 export {} from './log/log.js';
-export { PackageSchema } from './manifest/manifest.schema.js';
+export { PackageSchema, } from './manifest/manifest.schema.js';
 export { imageParts } from './manifest/parts.js';
 export { readManifest, validateManifest } from './manifest/read-manifest.js';
+export { canonical, mcpSnapshot, PROTOCOL_VERSIONS, } from './mcp/snapshot.js';
+export {} from './mcp/tools.js';
+export { versionPage } from './pages/pages.js';
 export {} from './server/part.types.js';
-export { startTestServer } from './testing/test-server.js';
+export {} from './store/store.types.js';
+export { startTestMcp, startTestServer, } from './testing/test-server.js';
+export {} from './worker/job-options.js';
+export {} from './worker/runs.js';
+export {} from './worker/scheduler.js';
+export {} from './worker/worker.types.js';

package/dist/log/log.js

@@ -1,4 +1,4 @@
-import { currentAgcid } from '../agcid/scope.js';
+import { currentAgcid } from '../agcid/current.js';
 export const messageOf = (error) => error instanceof Error ? error.message : String(error);
 const errorFields = (error) => {
     if (!(error instanceof Error))

package/dist/manifest/entry.d.ts

@@ -0,0 +1,5 @@
+import { type ExtensionPackage } from './manifest.schema.js';
+import { type ImagePartKind } from './primitives.schema.js';
+export type ImportModule = (file: string) => Promise<unknown>;
+export declare const createOf: (mod: unknown, file: string) => ((ctx: never) => unknown);
+export declare const loadCreate: <C>(dir: string, pkg: ExtensionPackage, part: ImagePartKind | "cli", importModule?: ImportModule) => Promise<(ctx: C) => unknown>;

package/dist/manifest/entry.js

@@ -0,0 +1,29 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {} from './manifest.schema.js';
+import { entryOf } from './parts.js';
+import {} from './primitives.schema.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;
+};
+// The entry itself missing (not a module it imports) means the package was never built.
+const notBuilt = (err, file) => {
+    const missing = err?.code === 'ERR_MODULE_NOT_FOUND';
+    const message = String(err?.message);
+    const named = [file, pathToFileURL(file).href].some((name) => message.includes(`'${name}'`));
+    if (!missing || !named)
+        return err;
+    return new Error(`${file} not found: build the package first (npm run build)`);
+};
+// The one way the kit reaches part code: import the part's entry, take its create(ctx).
+export const loadCreate = async (dir, pkg, part, importModule = importFile) => {
+    const file = join(dir, entryOf(pkg, part));
+    const mod = await importModule(file).catch((err) => {
+        throw notBuilt(err, file);
+    });
+    return createOf(mod, file);
+};

package/dist/manifest/manifest.schema.d.ts

@@ -33,6 +33,22 @@ declare const PartsSchema: z.ZodObject<{
         }>;
     }, z.core.$strict>]>>;
 }, z.core.$strict>;
+declare const CommandSchema: z.ZodObject<{
+    name: z.ZodString;
+    summary: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            integer: "integer";
+        }>;
+        optional: z.ZodOptional<z.ZodBoolean>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
 export declare const PackageSchema: z.ZodObject<{
     name: z.ZodString;
     version: z.ZodString;
@@ -83,6 +99,7 @@ export declare const PackageSchema: z.ZodObject<{
                     boolean: "boolean";
                     integer: "integer";
                 }>;
+                optional: z.ZodOptional<z.ZodBoolean>;
                 required: z.ZodOptional<z.ZodBoolean>;
                 description: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>>;
@@ -102,6 +119,7 @@ export declare const PackageSchema: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$loose>;
 export type CodePart = z.infer<typeof CodePartSchema>;
+export type CommandSpec = z.infer<typeof CommandSchema>;
 export type Parts = z.infer<typeof PartsSchema>;
 export type ExtensionPackage = z.infer<typeof PackageSchema>;
 export {};

package/dist/manifest/manifest.schema.js

@@ -27,6 +27,7 @@ const CommandSchema = z.strictObject({
         .array(z.strictObject({
         name: CommandNameSchema,
         type: ArgTypeSchema,
+        optional: z.boolean().optional(),
         required: z.boolean().optional(),
         description: z.string().min(1).max(200).optional(),
     }))

package/dist/manifest/parts.d.ts

@@ -9,3 +9,4 @@ export interface NormalizedParts {
 export declare const normalizeParts: (parts: Parts) => NormalizedParts;
 export declare const imageParts: (pkg: ExtensionPackage) => ImagePartKind[];
 export declare const entryOf: (pkg: ExtensionPackage, part: ImagePartKind | "cli") => string;
+export declare const hasPostgres: (pkg: ExtensionPackage) => boolean;

package/dist/manifest/parts.js

@@ -22,3 +22,4 @@ export const imageParts = (pkg) => {
     return IMAGE_PART_KINDS.filter((kind) => code[kind] !== undefined);
 };
 export const entryOf = (pkg, part) => normalizeParts(pkg.agentage.parts).code[part]?.entry ?? `./dist/${part}/index.js`;
+export const hasPostgres = (pkg) => normalizeParts(pkg.agentage.parts).store === 'postgres';

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

@@ -0,0 +1,8 @@
+import { type Express } from 'express';
+import { type PartAppBase } from '../server/app.js';
+import { type ToolEntry } from './tools.js';
+export interface McpAppOptions extends PartAppBase {
+    tools: ToolEntry[];
+    listing: 'open' | 'token';
+}
+export declare const createMcpApp: (options: McpAppOptions) => Express;

package/dist/mcp/mcp-app.js

@@ -0,0 +1,94 @@
+import { Readable } from 'node:stream';
+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 { 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 parsed = (body) => {
+    try {
+        return JSON.parse(body.toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+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)) {
+        if (typeof value === 'string')
+            headers.set(key, value);
+    }
+    return new globalThis.Request(`http://${req.get('host') ?? 'mcp'}/mcp`, {
+        method: 'POST',
+        headers,
+        body,
+    });
+};
+const send = async (response, res) => {
+    res.status(response.status);
+    response.headers.forEach((value, key) => void res.setHeader(key, value));
+    if (!response.body)
+        return void res.end();
+    await pipeline(Readable.fromWeb(response.body), res);
+};
+const handle = (handler, options) => async (req, res) => {
+    const body = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
+    const message = parsed(body);
+    await guard(options, req, message);
+    await send(await handler.fetch(webRequest(req, body), { parsedBody: message }), res);
+};
+const methodNotAllowed = (_req, res) => {
+    res.setHeader('Allow', 'POST');
+    res
+        .status(405)
+        .json({ jsonrpc: '2.0', error: { code: -32000, message: 'Method not allowed.' }, id: null });
+};
+// Stateless Streamable HTTP on SDK v2: POST /mcp only, GET and DELETE (sessions) answer 405.
+export const createMcpApp = (options) => {
+    const identity = { id: options.pkg.agentage.id, version: options.pkg.version };
+    const handler = createMcpHandler(serverFactory(identity, options.tools, options.log), {
+        legacy: 'stateless',
+        onerror: (err) => options.log.warn('mcp request refused', { reason: err.message }),
+    });
+    const raw = express.raw({ type: () => true, limit: BODY_LIMIT });
+    return createPartApp({
+        ...options,
+        part: 'mcp',
+        mount: (app) => {
+            app.use('/mcp', cors(MCP_CORS));
+            app.post('/mcp', raw, handle(handler, options));
+            app.all('/mcp', methodNotAllowed);
+        },
+    });
+};

package/dist/mcp/server.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { type Log } from '../log/log.js';
+import { type ToolEntry } from './tools.js';
+export interface ServerIdentity {
+    id: string;
+    version: string;
+}
+export declare const serverFactory: (identity: ServerIdentity, tools: ToolEntry[], log: Log) => () => McpServer;

package/dist/mcp/server.js

@@ -0,0 +1,38 @@
+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) }];
+// 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: agcidOf(currentAgcid()) };
+    return { isError: true, content: text({ error }), structuredContent: { error } };
+};
+const callback = (entry, log) => async (args) => {
+    try {
+        const output = entry.spec.output.parse(await entry.handler(args));
+        return { content: text(output), structuredContent: output };
+    }
+    catch (err) {
+        return errorResult(err, log);
+    }
+};
+// One fresh server per request (stateless); serverInfo agentage-{id} at the package version.
+export const serverFactory = (identity, tools, log) => () => {
+    const server = new McpServer({ name: `agentage-${identity.id}`, version: identity.version });
+    for (const entry of tools) {
+        const config = {
+            description: entry.spec.description,
+            inputSchema: entry.spec.input,
+            outputSchema: entry.spec.output,
+        };
+        server.registerTool(prefixed(identity.id, entry.name), config, callback(entry, log));
+    }
+    return server;
+};

package/dist/mcp/snapshot.d.ts

@@ -0,0 +1,11 @@
+export declare const PROTOCOL_VERSIONS: readonly ["2025-11-25", "2026-07-28"];
+export type ProtocolVersion = (typeof PROTOCOL_VERSIONS)[number];
+export interface McpSnapshot {
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    tools: Record<string, unknown>[];
+}
+export declare const canonical: (value: unknown) => unknown;
+export declare const mcpSnapshot: (url: string, version: ProtocolVersion) => Promise<McpSnapshot>;

package/dist/mcp/snapshot.js

@@ -0,0 +1,69 @@
+export const PROTOCOL_VERSIONS = ['2025-11-25', '2026-07-28'];
+const CLIENT = { name: 'agentage-snapshot', version: '1.0.0' };
+// Key order never counts: the two eras serialize the same schema in different orders.
+export const canonical = (value) => {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    return Object.fromEntries(entries.map(([key, v]) => [key, canonical(v)]));
+};
+// A JSON answer or the stateless legacy leg's one-message SSE stream.
+const payload = async (res) => {
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`mcp answered ${res.status}: ${text.slice(0, 200)}`);
+    const data = (res.headers.get('content-type') ?? '').includes('text/event-stream')
+        ? (text
+            .split('\n')
+            .find((line) => line.startsWith('data:'))
+            ?.slice(5) ?? '{}')
+        : text;
+    const message = JSON.parse(data);
+    if (message['error'])
+        throw new Error(`mcp error: ${JSON.stringify(message['error'])}`);
+    return message['result'];
+};
+const META = {
+    'io.modelcontextprotocol/protocolVersion': '2026-07-28',
+    'io.modelcontextprotocol/clientInfo': CLIENT,
+    'io.modelcontextprotocol/clientCapabilities': {},
+};
+const post = async (url, version, method, params) => {
+    const modern = version === '2026-07-28';
+    const headers = {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+        'mcp-protocol-version': version,
+        ...(modern ? { 'mcp-method': method } : {}),
+    };
+    const body = {
+        jsonrpc: '2.0',
+        id: 1,
+        method,
+        params: modern ? { ...params, _meta: META } : params,
+    };
+    return payload(await fetch(url, { method: 'POST', headers, body: JSON.stringify(body) }));
+};
+const serverInfoOf = async (url, version) => {
+    if (version === '2025-11-25') {
+        const init = await post(url, version, 'initialize', {
+            protocolVersion: version,
+            capabilities: {},
+            clientInfo: CLIENT,
+        });
+        return init['serverInfo'];
+    }
+    const found = await post(url, version, 'server/discover', {});
+    return found['_meta']['io.modelcontextprotocol/serverInfo'];
+};
+// What a client of that protocol version sees: serverInfo and tools/list, canonical; the contract test diffs it.
+export const mcpSnapshot = async (url, version) => {
+    const { name, version: serverVersion } = await serverInfoOf(url, version);
+    const listed = await post(url, version, 'tools/list', {});
+    return canonical({
+        serverInfo: { name, version: serverVersion },
+        tools: listed['tools'],
+    });
+};

package/dist/mcp/tools.d.ts

@@ -0,0 +1,26 @@
+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;
+export interface McpContext extends PartContext {
+    readonly tool: ToolRegistrar;
+}
+export interface ToolEntry {
+    name: string;
+    spec: ToolSpec<ObjectSchema, ObjectSchema>;
+    handler: (args: Record<string, unknown>) => unknown;
+}
+export declare const createToolRegistry: () => {
+    tool: ToolRegistrar;
+    tools: ToolEntry[];
+};
+export declare const prefixed: (id: string, name: string) => string;
+export {};

package/dist/mcp/tools.js

@@ -0,0 +1,21 @@
+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) => {
+        if (!TOOL_NAME.test(name))
+            throw new Error(`tool name ${name}: lowercase, digits, _ and -`);
+        if (tools.some((entry) => entry.name === name))
+            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 };
+};
+export const prefixed = (id, name) => `${id}__${name}`;

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

@@ -0,0 +1,8 @@
+import { type Express } from 'express';
+import { type PartAppBase } from '../server/app.js';
+import { type PagesSite } from './pages.js';
+export interface PagesAppOptions extends PartAppBase {
+    site: PagesSite;
+}
+export declare const NOT_FOUND_PAGE = "<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\"><title>Not found</title></head><body><p>Not found</p></body></html>\n";
+export declare const createPagesApp: (options: PagesAppOptions) => Express;

package/dist/pages/pages-app.js

@@ -0,0 +1,29 @@
+import {} from 'express';
+import { z } from 'zod';
+import { createPartApp } from '../server/app.js';
+import {} from './pages.js';
+const SiteSchema = z.record(z.string().regex(/^\/[A-Za-z0-9._~/-]*$/), z.string());
+export const NOT_FOUND_PAGE = '<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><title>Not found</title></head><body><p>Not found</p></body></html>\n';
+const serve = (site) => (req, res, next) => {
+    const html = site[req.path];
+    if (html === undefined)
+        return next();
+    res.type('html').setHeader('Cache-Control', 'no-cache');
+    res.send(html);
+};
+const missing = (_req, res) => {
+    res.status(404).type('html').send(NOT_FOUND_PAGE);
+};
+// Everything the gateway does not reserve comes here: a page from the site map, or an HTML 404.
+export const createPagesApp = (options) => {
+    const site = SiteSchema.parse(options.site);
+    return createPartApp({
+        ...options,
+        part: 'pages',
+        helmet: { contentSecurityPolicy: { directives: { upgradeInsecureRequests: null } } },
+        mount: (app) => {
+            app.get(/.*/, serve(site));
+            app.get(/.*/, missing);
+        },
+    });
+};

package/dist/pages/pages.d.ts

@@ -0,0 +1,4 @@
+import { type PartContext } from '../context/context.js';
+export type PagesContext = PartContext;
+export type PagesSite = Readonly<Record<string, string>>;
+export declare const versionPage: (ctx: PagesContext) => string;

package/dist/pages/pages.js

@@ -0,0 +1,16 @@
+import {} from '../context/context.js';
+const escape = (value) => value.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const STYLE = 'body{font:16px/1.5 system-ui,sans-serif;margin:3rem;color:#1d1d1f;background:#fff}' +
+    '@media (prefers-color-scheme:dark){body{color:#f5f5f7;background:#111}}code{font-size:.9em}';
+// One static page that names what runs: "{id} {version} · {commit}".
+export const versionPage = (ctx) => {
+    const { id, version, commit } = ctx.extension;
+    const title = escape(id);
+    return [
+        '<!doctype html>',
+        `<html lang="en"><head><meta charset="utf-8"><title>${title}</title>`,
+        `<meta name="viewport" content="width=device-width, initial-scale=1"><style>${STYLE}</style></head>`,
+        `<body><main><h1>${title}</h1><p>${title} ${escape(version)} · <code>${escape(commit)}</code></p></main></body></html>`,
+        '',
+    ].join('\n');
+};