@agentage/extension 0.2.0 → 0.3.0

package/dist/agcid/scope.d.ts

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

package/dist/agcid/scope.js

@@ -1,7 +1,6 @@
 import {} from 'express';
 import { AGCID_HEADER, agcidOf } from './agcid.js';
 import { requestScope } from './current.js';
-export { currentAgcid } 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));

package/dist/auth/part-auth.d.ts

@@ -0,0 +1,18 @@
+import { type Log } from '../log/log.js';
+import { type Env } from '../runtime/build-info.js';
+export declare const covers: (audience: string, host: string) => boolean;
+export declare const partAuth: (env: Env, id: string, log: Log, scopes: string[]) => Promise<{
+    tokenCheck: import("./token-check.js").TokenCheck;
+    resource: {
+        resource: string;
+        authorization_servers: string[];
+        scopes_supported: string[];
+        bearer_methods_supported: string[];
+    };
+    checks: {
+        auth: import("../health/health.js").HealthCheck;
+    };
+}>;
+export declare const declaredScopes: (id: string, openapi: Record<string, unknown> | null, tools?: readonly {
+    scope: string;
+}[]) => string[];

package/dist/auth/part-auth.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { OriginSchema } from '../discovery/discovery.schema.js';
+import { messageOf } from '../log/log.js';
+import { formatIssues } from '../manifest/read-manifest.js';
+import {} from '../runtime/build-info.js';
+import { createRevokedList, REVOKED_POLL_MS } from './revoked.js';
+import { accessOfSecurity, scopeOf } from './token-check.js';
+import { createTokenCheck, remoteKeys } from './verify-token.js';
+// *.{a domain of two labels or more}, or one host, as a deployment's origin may name it.
+const isAudience = (audience) => {
+    const host = audience.startsWith('*.') ? audience.slice(2) : audience;
+    return ['https', 'http'].some((scheme) => OriginSchema.safeParse(`${scheme}://${host}`).success);
+};
+const AuthEnvSchema = z.object({
+    AGENTAGE_ISSUER: z
+        .url()
+        .refine((url) => URL.canParse(url) && new URL(url).origin === url, 'an origin, no path'),
+    AGENTAGE_AUDIENCE: z.string().refine(isAudience, '*.{domain} or one host'),
+    AGENTAGE_ORIGIN: z.url(),
+});
+// *.agentage.io covers the domain and every host under it at any depth; else one exact host.
+export const covers = (audience, host) => audience.startsWith('*.')
+    ? host === audience.slice(2) || host.endsWith(audience.slice(1))
+    : host === audience;
+const settingsOf = (env) => {
+    const parsed = AuthEnvSchema.safeParse(env);
+    if (!parsed.success)
+        throw new Error(`no token check, no start: ${formatIssues(parsed.error.issues)}`);
+    const { AGENTAGE_ISSUER: issuer, AGENTAGE_AUDIENCE: audience } = parsed.data;
+    const { origin, hostname } = new URL(parsed.data.AGENTAGE_ORIGIN);
+    if (!covers(audience, hostname))
+        throw new Error(`the host ${hostname} is not under the audience ${audience}`);
+    return { issuer, audience, origin };
+};
+// Keys and revoked list read once before the part serves; an issuer down at start is no stop.
+export const partAuth = async (env, id, log, scopes) => {
+    const { issuer, audience, origin } = settingsOf(env);
+    const { keys, read } = remoteKeys(issuer);
+    const revoked = createRevokedList(issuer, log);
+    const unread = (err) => log.warn('key set not read', { reason: messageOf(err) });
+    await Promise.all([read().catch(unread), revoked.refresh()]);
+    setInterval(() => void revoked.refresh(), REVOKED_POLL_MS).unref();
+    return {
+        tokenCheck: createTokenCheck({ issuer, audience, id, origin, keys, revoked }),
+        resource: {
+            resource: origin,
+            authorization_servers: [issuer],
+            scopes_supported: scopes,
+            bearer_methods_supported: ['header'],
+        },
+        checks: { auth: revoked.check },
+    };
+};
+export const declaredScopes = (id, openapi, tools = []) => {
+    const routes = Object.values(openapi?.['paths'] ?? {})
+        .flatMap((item) => Object.values(item))
+        .filter((op) => typeof op === 'object' && !Array.isArray(op))
+        .map((op) => scopeOf(id, accessOfSecurity(op.security ?? openapi?.['security'])));
+    const scopes = new Set([...routes, ...tools.map((tool) => tool.scope)]);
+    return [...scopes].filter((scope) => scope !== 'public').sort();
+};

package/dist/auth/revoked.d.ts

@@ -0,0 +1,9 @@
+import { type HealthCheck } from '../health/health.js';
+import { type Log } from '../log/log.js';
+export declare const REVOKED_POLL_MS = 30000;
+export declare const createRevokedList: (issuer: string, log: Log, now?: () => number) => {
+    has: (jti: string) => boolean;
+    loaded: () => boolean;
+    refresh: () => Promise<void>;
+    check: HealthCheck;
+};

package/dist/auth/revoked.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import {} from '../health/health.js';
+import { messageOf } from '../log/log.js';
+import { retryOnce } from './token-check.js';
+export const REVOKED_POLL_MS = 30_000;
+const STALE_MS = 5 * 60_000;
+const RevokedSchema = z.object({
+    revoked: z.array(z.object({ jti: z.string(), exp: z.number() })),
+    generatedAt: z.string(),
+});
+const readList = async (url) => {
+    const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+    if (!res.ok)
+        throw new Error(`the issuer answered ${res.status}`);
+    return new Set(RevokedSchema.parse(await res.json()).revoked.map((entry) => entry.jti));
+};
+// The issuer's revoked ids, read every 30 s so a revoke holds within 60 s (api-standards 5).
+export const createRevokedList = (issuer, log, now = Date.now) => {
+    let ids = new Set();
+    let readAt;
+    const refresh = async () => {
+        try {
+            ids = await retryOnce(() => readList(`${issuer}/.well-known/agentage-revoked`));
+            readAt = now();
+        }
+        catch (err) {
+            log.warn('revoked list not read', { reason: messageOf(err) });
+        }
+    };
+    const loaded = () => readAt !== undefined;
+    const fresh = () => readAt !== undefined && now() - readAt <= STALE_MS;
+    const check = async () => (fresh() ? 'ok' : 'degraded');
+    return { has: (jti) => ids.has(jti), loaded, refresh, check };
+};

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, strongest } from './token-check.js';
+const PARAM = /^\{.+\}$/;
+// As Express routes: without case, and one trailing slash ignored.
+const sameShape = (template, path) => {
+    const want = template.toLowerCase().split('/');
+    const got = path
+        .toLowerCase()
+        .replace(/(.)\/$/, '$1')
+        .split('/');
+    return want.length === got.length && want.every((seg, i) => PARAM.test(seg) || seg === got[i]);
+};
+// The strongest access any matching operation declares: Express may run another path's handler.
+export const routeAccess = (doc, method, path) => {
+    const paths = (doc?.['paths'] ?? {});
+    const operations = Object.keys(paths)
+        .filter((template) => sameShape(template, path))
+        .flatMap((template) => paths[template]?.[method.toLowerCase()] ?? []);
+    if (operations.length === 0)
+        return 'read';
+    return strongest(operations.map((op) => accessOfSecurity(op.security ?? doc?.['security'])));
+};

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

@@ -0,0 +1,13 @@
+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 RANK: Record<Access, number>;
+export declare const scopeOf: (id: string, access?: Access) => string;
+export declare const strongest: (needed: readonly Access[]) => Access;
+export declare const accessOfSecurity: (security: unknown) => Access;
+export declare const retryOnce: <T>(read: () => Promise<T>, retries?: (_err: unknown) => boolean) => Promise<T>;

package/dist/auth/token-check.js

@@ -0,0 +1,26 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+const callers = new WeakMap();
+export const setCaller = (request, caller) => void callers.set(request, caller);
+export const callerOf = (request) => callers.get(request) ?? null;
+export const RANK = { public: 0, read: 1, write: 2, admin: 3 };
+export const scopeOf = (id, access = 'read') => access === 'public' ? 'public' : `${id}:${access}`;
+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);
+};
+// security.md: a failed read of the issuer is tried once more before it counts as an outage.
+export const retryOnce = (read, retries = (_err) => true) => read().catch(async (err) => {
+    if (!retries(err))
+        throw err;
+    await sleep(1000);
+    return read();
+});

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

@@ -0,0 +1,18 @@
+import { type JWTVerifyGetKey } from 'jose';
+import { type TokenCheck } from './token-check.js';
+export interface TokenCheckDeps {
+    issuer: string;
+    audience: string;
+    id: string;
+    origin: string;
+    keys: JWTVerifyGetKey;
+    revoked: {
+        has(jti: string): boolean;
+        loaded(): boolean;
+    };
+}
+export declare const remoteKeys: (issuer: string) => {
+    keys: JWTVerifyGetKey<Uint8Array<ArrayBufferLike> | import("node:crypto").webcrypto.CryptoKey>;
+    read: () => Promise<void>;
+};
+export declare const createTokenCheck: (deps: TokenCheckDeps) => TokenCheck;

package/dist/auth/verify-token.js

@@ -0,0 +1,68 @@
+import { createRemoteJWKSet, errors, jwtVerify } from 'jose';
+import { z } from 'zod';
+import { fail, isFailure } from '../envelope/envelope.js';
+import { RANK, retryOnce, scopeOf } from './token-check.js';
+const VERIFY = { algorithms: ['EdDSA'], requiredClaims: ['exp'] };
+const ClaimsSchema = z.object({
+    sub: z.string().min(1),
+    aud: z.string(),
+    scope: z.string(),
+    jti: z.string().optional(),
+});
+const unavailable = (message) => fail('UNAVAILABLE', message, { retryAfter: 5 });
+const invalid = (origin, message = 'Invalid token') => fail('UNAUTHORIZED', message, {
+    headers: {
+        'WWW-Authenticate': `Bearer resource_metadata="${origin}/.well-known/oauth-protected-resource"`,
+    },
+});
+const forbidden = (scope) => fail('FORBIDDEN', `Needs ${scope}`, {
+    headers: { 'WWW-Authenticate': `Bearer error="insufficient_scope", scope="${scope}"` },
+});
+const outage = (err) => !(err instanceof errors.JWKSNoMatchingKey);
+// A key set that cannot be read is an outage, never a 401; a kid it lacks is a bad token.
+const keysOrOutage = (keys) => async (header, token) => {
+    if (!header.kid)
+        throw new errors.JWKSNoMatchingKey();
+    return retryOnce(async () => keys(header, token), outage).catch((err) => {
+        throw outage(err) ? unavailable('Token keys unavailable') : err;
+    });
+};
+// Read at start and again only for an unknown kid, so a known key outlives an issuer outage.
+export const remoteKeys = (issuer) => {
+    const set = createRemoteJWKSet(new URL(`${issuer}/.well-known/jwks.json`), {
+        timeoutDuration: 3000,
+        cacheMaxAge: Infinity,
+    });
+    return { keys: keysOrOutage(set), read: () => retryOnce(set.reload) };
+};
+const claimsOf = async (authorization, deps) => {
+    const [scheme = '', credential = '', ...rest] = authorization.split(' ');
+    const bearer = scheme.toLowerCase() === 'bearer' && rest.length === 0;
+    const jwt = bearer && credential.startsWith('aga_') ? credential : '';
+    const options = { ...VERIFY, issuer: deps.issuer, audience: deps.audience };
+    const verified = await jwtVerify(jwt.slice(4), deps.keys, options).catch((err) => {
+        throw isFailure(err) ? err : invalid(deps.origin);
+    });
+    const claims = ClaimsSchema.safeParse(verified.payload);
+    if (!claims.success || verified.protectedHeader.typ !== 'at+jwt')
+        throw invalid(deps.origin);
+    return claims.data;
+};
+const grants = (scope, id, access) => {
+    const held = new Set(scope.split(' '));
+    return ['read', 'write', 'admin'].some((verb) => RANK[verb] >= RANK[access] && held.has(`${id}:${verb}`));
+};
+export const createTokenCheck = (deps) => async (authorization, access) => {
+    if (access === 'public')
+        return null;
+    if (!authorization)
+        throw invalid(deps.origin, 'Missing token');
+    const { sub, scope, jti } = await claimsOf(authorization, deps);
+    if (jti !== undefined && !deps.revoked.loaded())
+        throw unavailable('Revoked list unavailable');
+    if (jti !== undefined && deps.revoked.has(jti))
+        throw invalid(deps.origin, 'Token revoked');
+    if (!grants(scope, deps.id, access))
+        throw forbidden(scopeOf(deps.id, access));
+    return { sub, scopes: scope.split(' ') };
+};

package/dist/command/check-cli.js

@@ -1,6 +1,6 @@
 import { readManifest } from '../manifest/read-manifest.js';
-import { loadHandlers } from './run-command.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) => {
@@ -8,12 +8,7 @@ export const checkCli = async (dir) => {
         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 ctx = {
-            extension: { id: pkg.agentage.id, version: pkg.version, part: 'cli' },
-            args: {},
-            out,
-        };
-        const handlers = Object.keys(await loadHandlers(dir, pkg, ctx)).sort();
+        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(', ')}]`;

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

@@ -12,4 +12,5 @@ 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

@@ -1,7 +1,5 @@
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { loadCreate } from '../manifest/entry.js';
 import {} from '../manifest/manifest.schema.js';
-import { entryOf } from '../manifest/parts.js';
 import { readManifest } from '../manifest/read-manifest.js';
 import { parseCommandArgs, usage, UsageError } from './args.js';
 import {} from './command.types.js';
@@ -11,14 +9,8 @@ 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) => {
-    const file = join(dir, entryOf(pkg, 'cli'));
-    const mod = (await import(pathToFileURL(file).href));
-    if (typeof mod.create !== 'function')
-        throw new Error(`${file} does not export create(ctx)`);
-    return mod.create(ctx);
-};
-const contextFor = (pkg, args, out) => ({
+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,
@@ -28,10 +20,8 @@ const execute = async (o, pkg, stdout, stderr) => {
     if (!spec)
         throw new UsageError(`${pkg.agentage.id} has no command ${o.command}`);
     const parsed = parseCommandArgs(spec, o.argv);
-    if (parsed.help) {
-        stdout(`${usage(spec)}\n`);
-        return EXIT_OK;
-    }
+    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')

package/dist/context/context.d.ts

@@ -1,3 +1,4 @@
+import { type Caller } from '../auth/token-check.js';
 import { type ExtensionPackage } from '../manifest/manifest.schema.js';
 import { type Log } from '../log/log.js';
 import { type Store } from '../store/store.types.js';
@@ -12,6 +13,9 @@ export interface ExtensionInfo {
 }
 export interface PartContext {
     readonly extension: Readonly<ExtensionInfo>;
+    readonly auth: {
+        caller(request: object): Caller | null;
+    };
     readonly log: Log;
     readonly settings: Readonly<Record<string, SettingValue>>;
     readonly store: Store;

package/dist/context/context.js

@@ -1,3 +1,4 @@
+import { callerOf } from '../auth/token-check.js';
 import {} from '../manifest/manifest.schema.js';
 import { createLog } from '../log/log.js';
 import {} from '../store/store.types.js';
@@ -19,5 +20,6 @@ export const createContext = (input) => {
     });
     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 });
+    const auth = Object.freeze({ caller: callerOf });
+    return Object.freeze({ extension, auth, log, settings, store: store ?? NO_STORE });
 };

package/dist/context/test-context.js

@@ -24,33 +24,39 @@ const testStore = (option, log) => {
     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 extension = {
-        id: 'test',
-        version: '0.0.0',
-        part: 'api',
-        origin: 'http://127.0.0.1',
-        commit: '0'.repeat(40),
-        ...options.extension,
-    };
     const store = testStore(options.store, recordingLog([]));
-    const scheduler = createScheduler({ runs: memoryRuns(), log });
-    const { tool, tools } = createToolRegistry();
-    const base = { extension, log, settings: { ...options.settings }, logs, tool, tools };
-    const close = async () => store?.close();
+    const extension = { ...TEST_EXTENSION, ...options.extension };
+    const caller = { sub: 'usr_test', scopes: [`${extension.id}:read`] };
     return {
-        ...base,
+        extension,
+        auth: { caller: () => caller },
+        log,
+        logs,
+        settings: { ...options.settings },
         store: store ?? NO_STORE,
-        close,
-        schedule: scheduler.schedule,
-        runJob: scheduler.run,
+        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 lines = (into) => (text) => void into.push(...text.replace(/\n$/, '').split('\n'));
     const out = createOut({
         json: options.json ?? false,
         stdout: lines(output.stdout),

package/dist/discovery/discovery.d.ts

@@ -9,7 +9,10 @@ export type PartImages = Partial<Record<ImagePartKind, string>>;
 export declare const DEFAULT_RECORD_FILE = "/run/agentage/agentage-extension.json";
 export interface RecordExtras {
     openapi?: string;
-    tools?: string[];
+    tools?: {
+        name: string;
+        scope: string;
+    }[];
     widgets?: {
         name: string;
         element: string;
@@ -43,7 +46,10 @@ export declare const discoveryDocument: (record: ExtensionRecord, host: string)
         } | undefined;
     };
     openapi?: string | undefined;
-    tools?: string[] | undefined;
+    tools?: {
+        name: string;
+        scope: string;
+    }[] | undefined;
     widgets?: {
         name: string;
         element: string;

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

@@ -1,4 +1,10 @@
 import { z } from 'zod';
+export declare const OriginSchema: z.ZodString;
+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;
@@ -30,7 +36,10 @@ export declare const ExtensionRecordSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>;
     openapi: z.ZodOptional<z.ZodString>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        scope: z.ZodString;
+    }, z.core.$strict>>>;
     widgets: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         element: z.ZodString;
@@ -70,7 +79,10 @@ export declare const DiscoveryDocumentSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>;
     openapi: z.ZodOptional<z.ZodString>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        scope: z.ZodString;
+    }, z.core.$strict>>>;
     widgets: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         element: z.ZodString;

package/dist/discovery/discovery.schema.js

@@ -20,15 +20,19 @@ const PartsRecordSchema = z
     .refine((parts) => IMAGE_PART_KINDS.some((kind) => parts[kind] !== undefined), {
     message: 'at least one part with an image',
 });
-const OriginSchema = z
+export 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$/),
 });
+const ToolRecordSchema = z.strictObject({
+    name: PrefixedToolNameSchema,
+    scope: z.string().regex(/^(public|[a-z][a-z0-9-]*:(read|write|admin))$/),
+});
 const recordShape = {
     id: ExtensionIdSchema,
     version: VersionSchema,
@@ -39,7 +43,7 @@ const recordShape = {
         .string()
         .regex(/^\/api\/v[1-9][0-9]*\/openapi\.json$/)
         .optional(),
-    tools: z.array(PrefixedToolNameSchema).min(1).optional(),
+    tools: z.array(ToolRecordSchema).min(1).optional(),
     widgets: z.array(WidgetSchema).min(1).optional(),
     commands: z.array(CommandNameSchema).min(1).optional(),
 };

package/dist/envelope/envelope.d.ts

@@ -23,10 +23,12 @@ export interface Failure extends Error {
     readonly status: number;
     readonly details?: ErrorDetail[];
     readonly retryAfter?: number;
+    readonly headers?: Readonly<Record<string, string>>;
 }
 export interface FailOptions {
     details?: ErrorDetail[];
     retryAfter?: number;
+    headers?: Record<string, string>;
 }
 export declare const ok: <T>(data: T, meta?: Record<string, unknown>) => OkEnvelope<T>;
 export declare const fail: (code: ErrorCode, message: string, options?: FailOptions) => Failure;

package/dist/envelope/envelope.js

@@ -14,6 +14,7 @@ export const fail = (code, message, options = {}) => Object.assign(new Error(mes
     status: ERROR_STATUS[code],
     details: options.details,
     retryAfter: retryAfterOf(code, options.retryAfter),
+    headers: options.headers,
 });
 export const isFailure = (err) => err instanceof Error && err[FAILURE] === true;
 export const errorEnvelope = (failure, agcid) => {

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