@agentage/extension 0.1.2 → 0.2.1

package/README.md

@@ -1,12 +1,13 @@
 # @agentage/extension
 
-The agentage extension kit. A part module exports only `create(ctx)`; the kit owns the server,
-port, `/health`, the discovery document, the `agcid` correlation id and the response envelope.
-`@agentage/extension/tool` is the build tool behind `agentage extension build`.
+The agentage extension kit. Each part module (pages, api, mcp, worker, cli) exports only
+`create(ctx)`; the kit owns the server, port, `/health`, the discovery document, the `agcid`
+correlation id, the response envelope, the store pool, the scheduler and argument parsing.
+`@agentage/extension/tool` is the tool behind `agentage extension build | up | down | token`.
 
 ```bash
 npm install @agentage/extension express zod
 ```
 
-See the [platform README](https://github.com/agentage/platform#readme) for the api part, the
-manifest, the build tool and how a part image runs.
+See the [platform README](https://github.com/agentage/platform#readme) for every part kind, the
+manifest, the tool and how a part image runs.

package/dist/agcid/current.d.ts

@@ -0,0 +1,7 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+interface RequestScope {
+    agcid: string;
+}
+export declare const requestScope: AsyncLocalStorage<RequestScope>;
+export declare const currentAgcid: () => string | undefined;
+export {};

package/dist/agcid/current.js

@@ -0,0 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+// Apart from the middleware, so code the cli loads (logs, the build tool) never imports express.
+export const requestScope = new AsyncLocalStorage();
+export const currentAgcid = () => requestScope.getStore()?.agcid;

package/dist/agcid/scope.d.ts

@@ -1,4 +1,3 @@
 import { type RequestHandler, type Response } from 'express';
-export declare const currentAgcid: () => string | undefined;
 export declare const agcidMiddleware: RequestHandler;
 export declare const agcidOfResponse: (res: Response) => string;

package/dist/agcid/scope.js

@@ -1,14 +1,12 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import {} from 'express';
 import { AGCID_HEADER, agcidOf } from './agcid.js';
-const scope = new AsyncLocalStorage();
-export const currentAgcid = () => scope.getStore()?.agcid;
+import { requestScope } from './current.js';
 // Keeps a valid incoming agcid, else mints one; echoed on every response and tags every log line.
 export const agcidMiddleware = (req, res, next) => {
     const agcid = agcidOf(req.get(AGCID_HEADER));
     res.locals['agcid'] = agcid;
     res.setHeader(AGCID_HEADER, agcid);
-    scope.run({ agcid }, next);
+    requestScope.run({ agcid }, next);
 };
 export const agcidOfResponse = (res) => {
     const agcid = res.locals['agcid'];

package/dist/auth/route-access.d.ts

@@ -0,0 +1,2 @@
+import { type Access } from './token-check.js';
+export declare const routeAccess: (doc: Record<string, unknown> | null | undefined, method: string, path: string) => Access;

package/dist/auth/route-access.js

@@ -0,0 +1,21 @@
+import { accessOfSecurity } from './token-check.js';
+const PARAM = /^\{.+\}$/;
+const sameShape = (template, path) => {
+    const want = template.split('/');
+    const got = path.split('/');
+    return want.length === got.length && want.every((seg, i) => PARAM.test(seg) || seg === got[i]);
+};
+const params = (template) => template.split('/').filter((seg) => PARAM.test(seg)).length;
+// As OpenAPI matches: a concrete path before a template, then the template with the fewest params.
+const mostSpecific = (templates, path) => templates
+    .filter((template) => sameShape(template, path))
+    .sort((a, b) => params(a) - params(b))[0];
+// The access the committed OpenAPI declares for a request: its operation's, else the document's.
+export const routeAccess = (doc, method, path) => {
+    const paths = (doc?.['paths'] ?? {});
+    const template = mostSpecific(Object.keys(paths), path);
+    const operation = template ? paths[template]?.[method.toLowerCase()] : undefined;
+    if (!operation)
+        return 'read';
+    return accessOfSecurity(operation.security ?? doc?.['security']);
+};

package/dist/auth/token-check.d.ts

@@ -0,0 +1,10 @@
+export type Access = 'public' | 'read' | 'write' | 'admin';
+export interface Caller {
+    sub: string;
+    scopes: readonly string[];
+}
+export type TokenCheck = (authorization: string | undefined, access: Access) => Promise<Caller | null>;
+export declare const setCaller: (request: object, caller: Caller | null) => void;
+export declare const callerOf: (request: object) => Caller | null;
+export declare const strongest: (needed: readonly Access[]) => Access;
+export declare const accessOfSecurity: (security: unknown) => Access;

package/dist/auth/token-check.js

@@ -0,0 +1,18 @@
+// Kit-private until ctx.auth.caller(request) exists (M3): part code never reads it from the request.
+const callers = new WeakMap();
+export const setCaller = (request, caller) => void callers.set(request, caller);
+export const callerOf = (request) => callers.get(request) ?? null;
+const RANK = { public: 0, read: 1, write: 2, admin: 3 };
+export const strongest = (needed) => needed.reduce((top, access) => (RANK[access] > RANK[top] ? access : top), 'public');
+const VERB = /:(read|write|admin)$/;
+// OpenAPI security: [] is public, a scope names the verb; a route that declares nothing needs read.
+export const accessOfSecurity = (security) => {
+    if (Array.isArray(security) && security.length === 0)
+        return 'public';
+    const scopes = (Array.isArray(security) ? security : [])
+        .flatMap((requirement) => Object.values(requirement ?? {}))
+        .flat()
+        .filter((scope) => typeof scope === 'string');
+    const verbs = scopes.map((scope) => VERB.exec(scope)?.[1] ?? 'read');
+    return verbs.length === 0 ? 'read' : strongest(verbs);
+};

package/dist/command/args.d.ts

@@ -0,0 +1,14 @@
+import { type CommandSpec } from '../manifest/manifest.schema.js';
+export type ArgValue = string | number | boolean | undefined;
+export interface ParsedArgs {
+    args: Record<string, ArgValue>;
+    json: boolean;
+    help: boolean;
+}
+type ArgSpec = NonNullable<CommandSpec['args']>[number];
+export declare class UsageError extends Error {
+}
+export declare const isOptional: (arg: ArgSpec) => boolean;
+export declare const parseCommandArgs: (spec: CommandSpec, argv: string[]) => ParsedArgs;
+export declare const usage: (spec: CommandSpec) => string;
+export {};

package/dist/command/args.js

@@ -0,0 +1,60 @@
+import { parseArgs } from 'node:util';
+import {} from '../manifest/manifest.schema.js';
+export class UsageError extends Error {
+}
+export const isOptional = (arg) => arg.optional === true || arg.required === false;
+const coerce = (arg, raw) => {
+    if (arg.type === 'boolean')
+        return raw === true || raw === 'true';
+    if (arg.type === 'string')
+        return String(raw);
+    const value = Number(raw);
+    const ok = arg.type === 'integer' ? Number.isInteger(value) : Number.isFinite(value);
+    if (raw === true || !ok)
+        throw new UsageError(`${arg.name} must be ${arg.type === 'integer' ? 'an integer' : 'a number'}`);
+    return value;
+};
+const config = (spec, argv) => {
+    const options = {
+        json: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+    };
+    for (const arg of spec.args ?? [])
+        options[arg.name] = { type: arg.type === 'boolean' ? 'boolean' : 'string' };
+    return { args: argv, options, allowPositionals: true, strict: true };
+};
+const parse = (spec, argv) => {
+    try {
+        return parseArgs(config(spec, argv));
+    }
+    catch (err) {
+        throw new UsageError(err.message);
+    }
+};
+// Declared args come positional in order or as --name value; --json and --help belong to the kit.
+export const parseCommandArgs = (spec, argv) => {
+    const { values, positionals } = parse(spec, argv);
+    const queue = [...positionals];
+    const args = {};
+    for (const arg of spec.args ?? []) {
+        // A boolean is a flag: absent reads false, so it is never a missing argument.
+        const raw = values[arg.name] ?? (arg.type === 'boolean' ? false : queue.shift());
+        if (raw === undefined && !isOptional(arg))
+            throw new UsageError(`missing argument: ${arg.name}`);
+        args[arg.name] = raw === undefined ? undefined : coerce(arg, raw);
+    }
+    if (queue.length > 0)
+        throw new UsageError(`too many arguments: ${queue.join(' ')}`);
+    return { args, json: values['json'] === true, help: values['help'] === true };
+};
+export const usage = (spec) => {
+    const names = (spec.args ?? []).map((a) => (isOptional(a) ? `[${a.name}]` : `<${a.name}>`));
+    const lines = [
+        `usage: agentage ${[spec.name, ...names].join(' ')} [--json]`,
+        '',
+        `  ${spec.summary}`,
+    ];
+    for (const arg of spec.args ?? [])
+        lines.push(`  ${arg.name.padEnd(12)}${arg.type}${arg.description ? `  ${arg.description}` : ''}`);
+    return lines.join('\n');
+};

package/dist/command/check-cli.d.ts

@@ -0,0 +1 @@
+export declare const checkCli: (dir: string) => Promise<string | null>;

package/dist/command/check-cli.js

@@ -0,0 +1,19 @@
+import { readManifest } from '../manifest/read-manifest.js';
+import { createOut } from './out.js';
+import { contextFor, loadHandlers } from './run-command.js';
+const quiet = () => undefined;
+// null when the cli entry exports create and its handlers are exactly the declared commands.
+export const checkCli = async (dir) => {
+    try {
+        const pkg = await readManifest(dir);
+        const declared = (pkg.agentage.commands ?? []).map((command) => command.name).sort();
+        const out = createOut({ json: false, stdout: quiet, stderr: quiet });
+        const handlers = Object.keys(await loadHandlers(dir, pkg, contextFor(pkg, {}, out))).sort();
+        if (JSON.stringify(handlers) === JSON.stringify(declared))
+            return null;
+        return `cli handlers [${handlers.join(', ')}] differ from commands [${declared.join(', ')}]`;
+    }
+    catch (err) {
+        return err.message;
+    }
+};

package/dist/command/command.types.d.ts

@@ -0,0 +1,14 @@
+import { type Out } from './out.js';
+import { type ArgValue } from './args.js';
+export interface CommandExtension {
+    id: string;
+    version: string;
+    part: 'cli';
+}
+export interface CliContext {
+    readonly extension: Readonly<CommandExtension>;
+    readonly args: Readonly<Record<string, ArgValue>>;
+    readonly out: Out;
+}
+export type CommandHandler = () => unknown;
+export type CliCreate = (ctx: CliContext) => Record<string, CommandHandler>;

package/dist/command/command.types.js

@@ -0,0 +1,2 @@
+import {} from './out.js';
+import {} from './args.js';

package/dist/command/out.d.ts

@@ -0,0 +1,19 @@
+export interface Out {
+    log(...data: unknown[]): void;
+    warn(...data: unknown[]): void;
+    error(...data: unknown[]): void;
+    table(rows: readonly Record<string, unknown>[]): void;
+    json(value: unknown): void;
+    fail(code: number, message: string): void;
+}
+export type Write = (text: string) => void;
+export interface OutOptions {
+    json: boolean;
+    stdout: Write;
+    stderr: Write;
+}
+export interface RecordedOut extends Out {
+    readonly exitCode: number | undefined;
+}
+export declare const tableLines: (rows: readonly Record<string, unknown>[]) => string[];
+export declare const createOut: (options: OutOptions) => RecordedOut;

package/dist/command/out.js

@@ -0,0 +1,32 @@
+import { format } from 'node:util';
+const cell = (value) => (typeof value === 'string' ? value : format('%o', value));
+// Columns padded to the widest cell, a header row from the keys of every row.
+export const tableLines = (rows) => {
+    const keys = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+    const body = rows.map((row) => keys.map((key) => (key in row ? cell(row[key]) : '')));
+    const widths = keys.map((key, i) => Math.max(key.length, ...body.map((cells) => cells[i]?.length ?? 0)));
+    const line = (cells) => cells
+        .map((c, i) => c.padEnd(widths[i] ?? 0))
+        .join('  ')
+        .trimEnd();
+    return [line(keys), ...body.map(line)];
+};
+// Reads like the console; under --json stdout carries out.json only, the rest goes to stderr.
+export const createOut = (options) => {
+    let exitCode;
+    const text = options.json ? options.stderr : options.stdout;
+    return {
+        log: (...data) => text(`${format(...data)}\n`),
+        warn: (...data) => options.stderr(`${format(...data)}\n`),
+        error: (...data) => options.stderr(`${format(...data)}\n`),
+        table: (rows) => text(`${tableLines(rows).join('\n')}\n`),
+        json: (value) => options.stdout(`${JSON.stringify(value, null, 2)}\n`),
+        fail: (code, message) => {
+            exitCode = code;
+            options.stderr(`${message}\n`);
+        },
+        get exitCode() {
+            return exitCode;
+        },
+    };
+};

package/dist/command/run-command.d.ts

@@ -0,0 +1,16 @@
+import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+import { type CliContext, type CommandHandler } from './command.types.js';
+import { type Write } from './out.js';
+export interface RunCommandOptions {
+    dir: string;
+    command: string;
+    argv: string[];
+    stdout?: Write;
+    stderr?: Write;
+}
+export declare const EXIT_OK = 0;
+export declare const EXIT_FAILED = 1;
+export declare const EXIT_USAGE = 2;
+export declare const loadHandlers: (dir: string, pkg: ExtensionPackage, ctx: CliContext) => Promise<Record<string, CommandHandler>>;
+export declare const contextFor: (pkg: ExtensionPackage, args: CliContext["args"], out: CliContext["out"]) => CliContext;
+export declare const runCommand: (o: RunCommandOptions) => Promise<number>;

package/dist/command/run-command.js

@@ -0,0 +1,43 @@
+import { loadCreate } from '../manifest/entry.js';
+import {} from '../manifest/manifest.schema.js';
+import { readManifest } from '../manifest/read-manifest.js';
+import { parseCommandArgs, usage, UsageError } from './args.js';
+import {} from './command.types.js';
+import { createOut } from './out.js';
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+const writeOut = (text) => void process.stdout.write(text);
+const writeErr = (text) => void process.stderr.write(text);
+export const loadHandlers = async (dir, pkg, ctx) => (await loadCreate(dir, pkg, 'cli'))(ctx);
+export const contextFor = (pkg, args, out) => ({
+    extension: Object.freeze({ id: pkg.agentage.id, version: pkg.version, part: 'cli' }),
+    args: Object.freeze(args),
+    out,
+});
+const execute = async (o, pkg, stdout, stderr) => {
+    const spec = pkg.agentage.commands?.find((command) => command.name === o.command);
+    if (!spec)
+        throw new UsageError(`${pkg.agentage.id} has no command ${o.command}`);
+    const parsed = parseCommandArgs(spec, o.argv);
+    if (parsed.help)
+        return (stdout(`${usage(spec)}\n`), EXIT_OK);
+    const out = createOut({ json: parsed.json, stdout, stderr });
+    const handler = (await loadHandlers(o.dir, pkg, contextFor(pkg, parsed.args, out)))[o.command];
+    if (typeof handler !== 'function')
+        throw new Error(`the cli entry has no handler for ${o.command}`);
+    const result = await handler();
+    return out.exitCode ?? (typeof result === 'number' ? result : EXIT_OK);
+};
+// Exit codes: 0 ok, 2 usage, 1 failure (a throw, a missing handler, an invalid manifest).
+export const runCommand = async (o) => {
+    const stdout = o.stdout ?? writeOut;
+    const stderr = o.stderr ?? writeErr;
+    try {
+        return await execute(o, await readManifest(o.dir), stdout, stderr);
+    }
+    catch (err) {
+        stderr(`${err.message}\n`);
+        return err instanceof UsageError ? EXIT_USAGE : EXIT_FAILED;
+    }
+};

package/dist/context/context.d.ts

@@ -1,5 +1,6 @@
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
-import { type Log, type LogFields, type LogLevel } from '../log/log.js';
+import { type Log } from '../log/log.js';
+import { type Store } from '../store/store.types.js';
 export type ServerPartKind = 'pages' | 'api' | 'mcp' | 'worker';
 export type SettingValue = string | number | boolean;
 export interface ExtensionInfo {
@@ -7,30 +8,23 @@ export interface ExtensionInfo {
     version: string;
     part: ServerPartKind;
     origin: string;
+    commit: string;
 }
 export interface PartContext {
     readonly extension: Readonly<ExtensionInfo>;
     readonly log: Log;
     readonly settings: Readonly<Record<string, SettingValue>>;
+    readonly store: Store;
 }
+export declare const NO_STORE: Store;
 export declare const settingDefaults: (pkg: ExtensionPackage) => Record<string, SettingValue>;
 export interface ContextInput {
     pkg: ExtensionPackage;
     part: ServerPartKind;
     origin: string;
+    commit: string;
     log?: Log;
-}
-export declare const createContext: ({ pkg, part, origin, log }: ContextInput) => PartContext;
-export interface LogEntry {
-    level: LogLevel;
-    message: string;
-    fields: LogFields;
-}
-export interface TestContext extends PartContext {
-    readonly logs: LogEntry[];
-}
-export interface TestContextOptions {
-    extension?: Partial<ExtensionInfo>;
     settings?: Record<string, SettingValue>;
+    store?: Store;
 }
-export declare const createTestContext: (options?: TestContextOptions) => TestContext;
+export declare const createContext: (input: ContextInput) => PartContext;

package/dist/context/context.js

@@ -1,29 +1,23 @@
 import {} from '../manifest/manifest.schema.js';
-import { createLog, messageOf } from '../log/log.js';
+import { createLog } from '../log/log.js';
+import {} from '../store/store.types.js';
+// ctx.store is always there; without a store part in the manifest it says so on first use.
+export const NO_STORE = {
+    query: async () => {
+        throw new Error('this extension declares no store: add parts.store to the manifest');
+    },
+};
 export const settingDefaults = (pkg) => Object.fromEntries(Object.entries(pkg.agentage.settings ?? {}).map(([key, setting]) => [key, setting.default]));
-export const createContext = ({ pkg, part, origin, log }) => Object.freeze({
-    extension: Object.freeze({ id: pkg.agentage.id, version: pkg.version, part, origin }),
-    log: log ?? createLog({ extension: pkg.agentage.id, part }),
-    settings: Object.freeze(settingDefaults(pkg)),
-});
-const recordingLog = (logs) => ({
-    info: (message, fields = {}) => void logs.push({ level: 'info', message, fields }),
-    warn: (message, fields = {}) => void logs.push({ level: 'warn', message, fields }),
-    error: (error, fields = {}) => void logs.push({
-        level: 'error',
-        message: messageOf(error),
-        fields: { ...fields, err: error },
-    }),
-});
-// A ctx for unit tests: fixed identity, settings as given, a log that records what it would print.
-export const createTestContext = (options = {}) => {
-    const logs = [];
-    const extension = {
-        id: 'test',
-        version: '0.0.0',
-        part: 'api',
-        origin: 'http://127.0.0.1',
-        ...options.extension,
-    };
-    return { extension, log: recordingLog(logs), settings: { ...options.settings }, logs };
+export const createContext = (input) => {
+    const { pkg, part, origin, commit, store } = input;
+    const extension = Object.freeze({
+        id: pkg.agentage.id,
+        version: pkg.version,
+        part,
+        origin,
+        commit,
+    });
+    const log = input.log ?? createLog({ extension: pkg.agentage.id, part });
+    const settings = Object.freeze({ ...settingDefaults(pkg), ...input.settings });
+    return Object.freeze({ extension, log, settings, store: store ?? NO_STORE });
 };

package/dist/context/settings.d.ts

@@ -0,0 +1,5 @@
+import { type Log } from '../log/log.js';
+import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+import { type Env } from '../runtime/build-info.js';
+import { type SettingValue } from './context.js';
+export declare const settingsFromEnv: (pkg: ExtensionPackage, env: Env, log: Log) => Record<string, SettingValue>;

package/dist/context/settings.js

@@ -0,0 +1,32 @@
+import {} from '../log/log.js';
+import {} from '../manifest/manifest.schema.js';
+import {} from '../runtime/build-info.js';
+import { settingDefaults } from './context.js';
+const fits = (setting, value) => {
+    if (setting.type === 'integer' ? !Number.isInteger(value) : typeof value !== setting.type)
+        return false;
+    return !setting.enum || setting.enum.includes(String(value));
+};
+const parseObject = (text) => {
+    const value = JSON.parse(text);
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error('AGENTAGE_SETTINGS is not a JSON object');
+    }
+    return value;
+};
+// The host's values (AGENTAGE_SETTINGS, JSON) over the defaults; a wrong type stops the start.
+export const settingsFromEnv = (pkg, env, log) => {
+    const declared = pkg.agentage.settings ?? {};
+    const given = env['AGENTAGE_SETTINGS'] ? parseObject(env['AGENTAGE_SETTINGS']) : {};
+    const values = settingDefaults(pkg);
+    for (const [key, value] of Object.entries(given)) {
+        const setting = declared[key];
+        if (!setting)
+            log.warn('setting not declared in the manifest, ignored', { setting: key });
+        else if (fits(setting, value))
+            values[key] = value;
+        else
+            throw new Error(`setting ${key}: ${JSON.stringify(value)} does not fit its declaration`);
+    }
+    return values;
+};

package/dist/context/test-context.d.ts

@@ -0,0 +1,44 @@
+import { type CliContext } from '../command/command.types.js';
+import { type LogFields, type LogLevel } from '../log/log.js';
+import { type ToolEntry, type ToolRegistrar } from '../mcp/tools.js';
+import { type JobRun } from '../worker/runs.js';
+import { type Schedule } from '../worker/scheduler.js';
+import { type ExtensionInfo, type PartContext, type SettingValue } from './context.js';
+import { type ArgValue } from '../command/args.js';
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    fields: LogFields;
+}
+export interface TestContext extends PartContext {
+    readonly logs: LogEntry[];
+    close(): Promise<void>;
+    readonly schedule: Schedule;
+    readonly tool: ToolRegistrar;
+    readonly tools: ToolEntry[];
+    runJob(name: string): Promise<JobRun | undefined>;
+}
+export interface TestCommandContext extends CliContext {
+    readonly output: {
+        stdout: string[];
+        stderr: string[];
+    };
+    readonly exitCode: number | undefined;
+}
+export interface TestContextOptions {
+    extension?: Partial<ExtensionInfo>;
+    settings?: Record<string, SettingValue>;
+    store?: boolean | {
+        dir: string;
+    };
+}
+export interface TestCommandOptions {
+    args: Record<string, ArgValue>;
+    extension?: {
+        id?: string;
+        version?: string;
+    };
+    json?: boolean;
+}
+export declare function createTestContext(options: TestCommandOptions): TestCommandContext;
+export declare function createTestContext(options?: TestContextOptions): TestContext;

package/dist/context/test-context.js

@@ -0,0 +1,75 @@
+import {} from '../command/command.types.js';
+import { createOut } from '../command/out.js';
+import { messageOf } from '../log/log.js';
+import { createToolRegistry } from '../mcp/tools.js';
+import { migrate } from '../store/migrations.js';
+import { createTestStore } from '../store/test-store.js';
+import { runLog } from '../worker/run-log.js';
+import { memoryRuns } from '../worker/runs.js';
+import { createScheduler } from '../worker/scheduler.js';
+import { NO_STORE } from './context.js';
+import {} from '../command/args.js';
+const recordingLog = (logs) => ({
+    info: (message, fields = {}) => void logs.push({ level: 'info', message, fields }),
+    warn: (message, fields = {}) => void logs.push({ level: 'warn', message, fields }),
+    error: (error, fields = {}) => void logs.push({
+        level: 'error',
+        message: messageOf(error),
+        fields: { ...fields, err: error },
+    }),
+});
+const testStore = (option, log) => {
+    if (!option)
+        return undefined;
+    const dir = option === true ? process.cwd() : option.dir;
+    return createTestStore((store) => migrate(store, dir, log));
+};
+const TEST_EXTENSION = {
+    id: 'test',
+    version: '0.0.0',
+    part: 'api',
+    origin: 'http://127.0.0.1',
+    commit: '0'.repeat(40),
+};
+// Jobs run by hand with runJob, tools recorded as the mcp part registers them.
+const recorders = (log) => {
+    const scheduler = createScheduler({ runs: memoryRuns(), log });
+    return { ...createToolRegistry(), schedule: scheduler.schedule, runJob: scheduler.run };
+};
+const serverContext = (options) => {
+    const logs = [];
+    const log = runLog(recordingLog(logs));
+    const store = testStore(options.store, recordingLog([]));
+    return {
+        extension: { ...TEST_EXTENSION, ...options.extension },
+        log,
+        logs,
+        settings: { ...options.settings },
+        store: store ?? NO_STORE,
+        close: async () => store?.close(),
+        ...recorders(log),
+    };
+};
+// One recorded line per line written, the trailing newline dropped.
+const lines = (into) => (text) => void into.push(...text.replace(/\n$/, '').split('\n'));
+const commandContext = (options) => {
+    const output = { stdout: [], stderr: [] };
+    const out = createOut({
+        json: options.json ?? false,
+        stdout: lines(output.stdout),
+        stderr: lines(output.stderr),
+    });
+    const extension = { id: 'test', version: '0.0.0', ...options.extension, part: 'cli' };
+    return {
+        extension,
+        args: { ...options.args },
+        out,
+        output,
+        get exitCode() {
+            return out.exitCode;
+        },
+    };
+};
+export function createTestContext(options = {}) {
+    return 'args' in options ? commandContext(options) : serverContext(options);
+}

package/dist/discovery/discovery.d.ts

@@ -7,7 +7,17 @@ export interface BuildInfo {
 }
 export type PartImages = Partial<Record<ImagePartKind, string>>;
 export declare const DEFAULT_RECORD_FILE = "/run/agentage/agentage-extension.json";
-export declare const recordOf: (pkg: ExtensionPackage, build: BuildInfo, images: PartImages) => ExtensionRecord;
+export interface RecordExtras {
+    openapi?: string;
+    tools?: string[];
+    widgets?: {
+        name: string;
+        element: string;
+        module: string;
+    }[];
+    migrations?: number;
+}
+export declare const recordOf: (pkg: ExtensionPackage, build: BuildInfo, images: PartImages, extras?: RecordExtras) => ExtensionRecord;
 export declare const validateRecord: (value: unknown) => ExtensionRecord;
 export declare const loadRecord: (file: string) => Promise<ExtensionRecord | null>;
 export declare const discoveryDocument: (record: ExtensionRecord, host: string) => {
@@ -29,6 +39,7 @@ export declare const discoveryDocument: (record: ExtensionRecord, host: string)
         } | undefined;
         store?: {
             kind: "postgres" | "git" | "signoz";
+            migrations?: number | undefined;
         } | undefined;
     };
     openapi?: string | undefined;