@agentage/extension 0.1.1 → 0.1.2

package/dist/agcid/agcid.d.ts

@@ -1,4 +1,5 @@
 export declare const AGCID_HEADER = "agcid";
+export declare const AGCID_PATTERN: RegExp;
 export declare const isAgcid: (value: unknown) => value is string;
 export declare const uuidv7: (now?: number, random?: Buffer) => string;
 export declare const agcidOf: (incoming: unknown) => string;

package/dist/agcid/agcid.js

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 export const AGCID_HEADER = 'agcid';
-const AGCID = /^[A-Za-z0-9._:-]{8,128}$/;
-export const isAgcid = (value) => typeof value === 'string' && AGCID.test(value);
+export const AGCID_PATTERN = /^[A-Za-z0-9._:-]{8,128}$/;
+export const isAgcid = (value) => typeof value === 'string' && AGCID_PATTERN.test(value);
 const hyphenate = (hex) => [hex.slice(0, 8), hex.slice(8, 12), hex.slice(12, 16), hex.slice(16, 20), hex.slice(20)].join('-');
 // RFC 9562 UUIDv7: 48-bit unix ms, version 7, variant 10, the rest random.
 export const uuidv7 = (now = Date.now(), random = randomBytes(10)) => {

package/dist/context/context.js

@@ -1,5 +1,5 @@
 import {} from '../manifest/manifest.schema.js';
-import { createLog } from '../log/log.js';
+import { createLog, messageOf } from '../log/log.js';
 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 }),
@@ -9,9 +9,13 @@ export const createContext = ({ pkg, part, origin, log }) => Object.freeze({
 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: String(error), fields: { ...fields, err: error } }),
+    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 instead of printing.
+// 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 = {

package/dist/discovery/discovery.js

@@ -1,14 +1,9 @@
-import { readFile } from 'node:fs/promises';
-import { formatIssues } from '../manifest/read-manifest.js';
+import { formatIssues, readJsonIfExists } from '../manifest/read-manifest.js';
 import {} from '../manifest/manifest.schema.js';
 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 commandNames = (pkg) => {
-    const names = (pkg.agentage.commands ?? []).map((command) => command.name);
-    return names.length > 0 ? names : undefined;
-};
 const partsOf = (pkg, images) => {
     const parts = {};
     for (const [kind, image] of Object.entries(images))
@@ -20,15 +15,10 @@ const partsOf = (pkg, images) => {
 };
 // From the manifest, the build and the pushed images by digest; OpenAPI, tools, widgets come later.
 export const recordOf = (pkg, build, images) => {
-    const record = {
-        id: pkg.agentage.id,
-        version: pkg.version,
-        commit: build.commit,
-        buildTime: build.buildTime,
-        parts: partsOf(pkg, images),
-        commands: commandNames(pkg),
-    };
-    return JSON.parse(JSON.stringify(record));
+    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;
 };
 export const validateRecord = (value) => {
     const result = ExtensionRecordSchema.safeParse(value);
@@ -36,15 +26,10 @@ export const validateRecord = (value) => {
         return result.data;
     throw new Error(`invalid extension record: ${formatIssues(result.error.issues)}`);
 };
+// No file means no record is mounted; any other read error stops the part from starting.
 export const loadRecord = async (file) => {
-    let text;
-    try {
-        text = await readFile(file, 'utf8');
-    }
-    catch {
-        return null; // no record mounted: discovery lists the part's own image by tag
-    }
-    return validateRecord(JSON.parse(text));
+    const record = await readJsonIfExists(file);
+    return record === undefined ? null : validateRecord(record);
 };
 export const discoveryDocument = (record, host) => {
     const { id, version, commit, buildTime, ...rest } = record;

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

@@ -1,30 +1,4 @@
 import { z } from 'zod';
-export declare const ImageDigestRefSchema: z.ZodString;
-export declare const PartsRecordSchema: z.ZodObject<{
-    pages: z.ZodOptional<z.ZodObject<{
-        image: z.ZodString;
-    }, z.core.$strict>>;
-    ui: z.ZodOptional<z.ZodObject<{
-        image: z.ZodString;
-    }, z.core.$strict>>;
-    api: z.ZodOptional<z.ZodObject<{
-        image: z.ZodString;
-    }, z.core.$strict>>;
-    mcp: z.ZodOptional<z.ZodObject<{
-        image: z.ZodString;
-    }, z.core.$strict>>;
-    worker: z.ZodOptional<z.ZodObject<{
-        image: z.ZodString;
-    }, z.core.$strict>>;
-    store: z.ZodOptional<z.ZodObject<{
-        kind: z.ZodEnum<{
-            postgres: "postgres";
-            git: "git";
-            signoz: "signoz";
-        }>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-export declare const OriginSchema: z.ZodString;
 export declare const ExtensionRecordSchema: z.ZodObject<{
     id: z.ZodString;
     version: z.ZodString;

package/dist/discovery/discovery.schema.js

@@ -1,12 +1,12 @@
 import { z } from 'zod';
 import { CommandNameSchema, CommitSchema, ExtensionIdSchema, IMAGE_PART_KINDS, PrefixedToolNameSchema, StoreKindSchema, VersionSchema, } from '../manifest/primitives.schema.js';
 // registry host[:port]/owner/{id}-{part}@sha256: deployed by digest, a version's images never change.
-export const ImageDigestRefSchema = z
+const ImageDigestRefSchema = z
     .string()
     .max(256)
     .regex(/^[a-z0-9][a-z0-9.-]*(:[0-9]{1,5})?\/[a-z0-9][a-z0-9-]*\/[a-z][a-z0-9-]*-(pages|ui|api|mcp|worker)@sha256:[0-9a-f]{64}$/);
 const PartImageSchema = z.strictObject({ image: ImageDigestRefSchema });
-export const PartsRecordSchema = z
+const PartsRecordSchema = z
     .strictObject({
     pages: PartImageSchema.optional(),
     ui: PartImageSchema.optional(),
@@ -18,7 +18,7 @@ export const PartsRecordSchema = z
     .refine((parts) => IMAGE_PART_KINDS.some((kind) => parts[kind] !== undefined), {
     message: 'at least one part with an image',
 });
-export const OriginSchema = z
+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})?$/);

package/dist/envelope/envelope.js

@@ -1,4 +1,5 @@
 import { DEFAULT_RETRY_AFTER_SECONDS, ERROR_STATUS, RETRY_AFTER_CODES, } from './codes.js';
+// A registry symbol, so a failure thrown through a second copy of the kit is still recognised.
 const FAILURE = Symbol.for('agentage.extension.failure');
 export const ok = (data, meta) => meta === undefined ? { success: true, data } : { success: true, data, meta };
 const retryAfterOf = (code, given) => {

package/dist/envelope/envelope.schema.d.ts

@@ -1,8 +1,4 @@
 import { z } from 'zod';
-export declare const AgcidSchema: z.ZodString;
-export declare const ErrorCodeSchema: z.ZodEnum<{
-    [x: string]: string;
-}>;
 export declare const ErrorEnvelopeSchema: z.ZodObject<{
     success: z.ZodLiteral<false>;
     error: z.ZodObject<{

package/dist/envelope/envelope.schema.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+import { AGCID_PATTERN } from '../agcid/agcid.js';
 import { ERROR_CODES } from './codes.js';
-export const AgcidSchema = z.string().regex(/^[A-Za-z0-9._:-]{8,128}$/);
-export const ErrorCodeSchema = z.enum(ERROR_CODES);
+const AgcidSchema = z.string().regex(AGCID_PATTERN);
+const ErrorCodeSchema = z.enum(ERROR_CODES);
 export const ErrorEnvelopeSchema = z.strictObject({
     success: z.literal(false),
     error: z.strictObject({

package/dist/health/health.d.ts

@@ -1,10 +1,11 @@
 import { type RequestHandler } from 'express';
 import { type BuildInfo } from '../discovery/discovery.js';
+import { type ImagePartKind } from '../manifest/primitives.schema.js';
 import { type HealthBody, type HealthStatus } from './health.schema.js';
 export type HealthCheck = () => Promise<HealthStatus>;
 export interface HealthOptions {
     extension: string;
-    part: 'api' | 'mcp' | 'worker' | 'pages' | 'ui';
+    part: ImagePartKind;
     version: string;
     build: BuildInfo;
     checks?: Record<string, HealthCheck>;
@@ -13,6 +14,8 @@ export interface HealthOptions {
     now?: () => Date;
 }
 export declare const worstOf: (statuses: HealthStatus[]) => HealthStatus;
+export declare const CHECK_TIMEOUT_MS = 1000;
 export declare const isLoopback: (address: string | undefined) => boolean;
-export declare const healthBody: (options: HealthOptions) => Promise<HealthBody>;
+export type ResolvedHealth = HealthOptions & Required<Pick<HealthOptions, 'instance' | 'startedAt'>>;
+export declare const healthBody: (options: ResolvedHealth) => Promise<HealthBody>;
 export declare const createHealthHandler: (options: HealthOptions) => RequestHandler;

package/dist/health/health.js

@@ -2,25 +2,40 @@ import { randomBytes } from 'node:crypto';
 import {} from 'express';
 import {} from '../discovery/discovery.js';
 import { fail } from '../envelope/envelope.js';
+import {} from '../manifest/primitives.schema.js';
+import { isoSeconds } from '../runtime/build-info.js';
 import {} from './health.schema.js';
 const RANK = { ok: 0, degraded: 1, unavailable: 2 };
 export const worstOf = (statuses) => statuses.reduce((worst, s) => (RANK[s] > RANK[worst] ? s : worst), 'ok');
+// Under the recipe's HEALTHCHECK --timeout=3s: a hung check reads unavailable, never a hung probe.
+export const CHECK_TIMEOUT_MS = 1000;
+const settle = async (check) => {
+    let timer;
+    const expiry = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('unavailable'), CHECK_TIMEOUT_MS).unref();
+    });
+    try {
+        return await Promise.race([check(), expiry]);
+    }
+    catch {
+        return 'unavailable';
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
 const runChecks = async (checks) => {
-    const entries = await Promise.all(Object.entries(checks).map(async ([name, check]) => {
-        const status = await check().catch(() => 'unavailable');
-        return [name, status];
-    }));
+    const entries = await Promise.all(Object.entries(checks).map(async ([name, check]) => [name, await settle(check)]));
     return Object.fromEntries(entries);
 };
-const isoSeconds = (date) => `${date.toISOString().slice(0, 19)}Z`;
 export const isLoopback = (address) => address !== undefined && /^(127\.|::1$|::ffff:127\.)/.test(address);
 export const healthBody = async (options) => {
     const now = (options.now ?? (() => new Date()))();
     const checks = await runChecks(options.checks ?? {});
     const status = worstOf(Object.values(checks));
-    const { extension, part, version, build } = options;
-    const uptimeSeconds = Math.max(0, Math.floor((now.getTime() - (options.startedAt ?? 0)) / 1000));
-    const data = { status, extension, part, version, ...build, instance: options.instance ?? '' };
+    const { extension, part, version, build, instance } = options;
+    const uptimeSeconds = Math.max(0, Math.floor((now.getTime() - options.startedAt) / 1000));
+    const data = { status, extension, part, version, ...build, instance };
     return {
         success: status !== 'unavailable',
         data: { ...data, uptimeSeconds, checkedAt: isoSeconds(now), checks },

package/dist/health/health.schema.d.ts

@@ -1,17 +1,9 @@
 import { z } from 'zod';
-export declare const HealthStatusSchema: z.ZodEnum<{
+declare const HealthStatusSchema: z.ZodEnum<{
     ok: "ok";
     degraded: "degraded";
     unavailable: "unavailable";
 }>;
-export declare const DeployedPartKindSchema: z.ZodEnum<{
-    pages: "pages";
-    ui: "ui";
-    api: "api";
-    mcp: "mcp";
-    worker: "worker";
-    store: "store";
-}>;
 export declare const HealthSchema: z.ZodObject<{
     success: z.ZodBoolean;
     data: z.ZodObject<{
@@ -44,3 +36,4 @@ export declare const HealthSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type HealthStatus = z.infer<typeof HealthStatusSchema>;
 export type HealthBody = z.infer<typeof HealthSchema>;
+export {};

package/dist/health/health.schema.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { ExtensionIdSchema, VersionSchema } from '../manifest/primitives.schema.js';
-export const HealthStatusSchema = z.enum(['ok', 'degraded', 'unavailable']);
-export const DeployedPartKindSchema = z.enum(['pages', 'ui', 'api', 'mcp', 'worker', 'store']);
+const HealthStatusSchema = z.enum(['ok', 'degraded', 'unavailable']);
+const DeployedPartKindSchema = z.enum(['pages', 'ui', 'api', 'mcp', 'worker', 'store']);
 // GET /health of every part container (api-standards section 7); never hostnames, IPs or env values.
 export const HealthSchema = z.strictObject({
     success: z.boolean(),

package/dist/index.d.ts

@@ -1,19 +1,13 @@
-export { AGCID_HEADER, agcidOf, isAgcid, uuidv7 } from './agcid/agcid.js';
-export { currentAgcid } from './agcid/scope.js';
-export { createContext, createTestContext, type ExtensionInfo, type LogEntry, type PartContext, type ServerPartKind, type SettingValue, type TestContext, type TestContextOptions, } from './context/context.js';
-export { DEFAULT_RECORD_FILE, discoveryDocument, loadRecord, recordOf, validateRecord, type BuildInfo, type PartImages, } from './discovery/discovery.js';
+export { createTestContext, type ExtensionInfo, type LogEntry, type PartContext, type ServerPartKind, type SettingValue, type TestContext, type TestContextOptions, } from './context/context.js';
 export { DiscoveryDocumentSchema, ExtensionRecordSchema, type DiscoveryDocument, type ExtensionRecord, } from './discovery/discovery.schema.js';
 export { ERROR_CODES, ERROR_STATUS, type ErrorCode } from './envelope/codes.js';
-export { errorEnvelope, fail, isFailure, ok, type ErrorDetail, type ErrorEnvelope, type Failure, type FailOptions, type OkEnvelope, } from './envelope/envelope.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 { createHealthHandler, type HealthCheck, type HealthOptions } from './health/health.js';
 export { HealthSchema, type HealthBody, type HealthStatus } from './health/health.schema.js';
-export { createLog, type Log, type LogFields } from './log/log.js';
+export { type Log, type LogFields } from './log/log.js';
 export { PackageSchema, type ExtensionPackage } from './manifest/manifest.schema.js';
-export { entryOf, imageParts, normalizeParts } from './manifest/parts.js';
+export { imageParts } from './manifest/parts.js';
 export { readManifest, validateManifest } from './manifest/read-manifest.js';
-export { createApiApp, PUBLIC_CORS, type ApiAppOptions } from './server/app.js';
-export { serve, type ServeOptions } from './server/serve.js';
-export { startTestServer, type TestServer, type TestServerOptions } from './testing/test-server.js';
 export { type ApiCreate, type ApiHandler, type ApiPart } from './server/part.types.js';
+export { startTestServer, type TestServer, type TestServerOptions } from './testing/test-server.js';

package/dist/index.js

@@ -1,19 +1,13 @@
-export { AGCID_HEADER, agcidOf, isAgcid, uuidv7 } from './agcid/agcid.js';
-export { currentAgcid } from './agcid/scope.js';
-export { createContext, createTestContext, } from './context/context.js';
-export { DEFAULT_RECORD_FILE, discoveryDocument, loadRecord, recordOf, validateRecord, } from './discovery/discovery.js';
+export { createTestContext, } from './context/context.js';
 export { DiscoveryDocumentSchema, ExtensionRecordSchema, } from './discovery/discovery.schema.js';
 export { ERROR_CODES, ERROR_STATUS } from './envelope/codes.js';
-export { errorEnvelope, fail, isFailure, ok, } from './envelope/envelope.js';
+export { fail, isFailure, ok, } from './envelope/envelope.js';
 export { ErrorEnvelopeSchema, OkEnvelopeSchema } from './envelope/envelope.schema.js';
 export { parse } from './envelope/parse.js';
-export { createHealthHandler } from './health/health.js';
 export { HealthSchema } from './health/health.schema.js';
-export { createLog } from './log/log.js';
+export {} from './log/log.js';
 export { PackageSchema } from './manifest/manifest.schema.js';
-export { entryOf, imageParts, normalizeParts } from './manifest/parts.js';
+export { imageParts } from './manifest/parts.js';
 export { readManifest, validateManifest } from './manifest/read-manifest.js';
-export { createApiApp, PUBLIC_CORS } from './server/app.js';
-export { serve } from './server/serve.js';
-export { startTestServer } from './testing/test-server.js';
 export {} from './server/part.types.js';
+export { startTestServer } from './testing/test-server.js';

package/dist/log/log.d.ts

@@ -10,4 +10,5 @@ export interface LogTags {
     part: string;
 }
 export type LogWrite = (line: string) => void;
+export declare const messageOf: (error: unknown) => string;
 export declare const createLog: (tags: LogTags, write?: LogWrite) => Log;

package/dist/log/log.js

@@ -1,21 +1,20 @@
 import { currentAgcid } from '../agcid/scope.js';
+export const messageOf = (error) => error instanceof Error ? error.message : String(error);
 const errorFields = (error) => {
     if (!(error instanceof Error))
         return { err: { message: String(error) } };
     return { err: { type: error.name, message: error.message, stack: error.stack } };
 };
+// Spread twice: the key order stays, and a field never overwrites time, level, msg, tags or agcid.
 const line = (level, message, tags, fields) => {
     const agcid = currentAgcid();
-    const entry = { time: new Date().toISOString(), level, msg: message, ...tags, ...fields };
-    return `${JSON.stringify(agcid ? { ...entry, agcid } : entry)}\n`;
+    const own = { time: new Date().toISOString(), level, msg: message, ...tags };
+    const fixed = agcid ? { ...own, agcid } : own;
+    return `${JSON.stringify({ ...fixed, ...fields, ...fixed })}\n`;
 };
 const stderrWrite = (text) => void process.stderr.write(text);
-// JSON lines on stderr, tagged with extension, part and the request's agcid.
 export const createLog = (tags, write = stderrWrite) => ({
     info: (message, fields = {}) => write(line('info', message, tags, fields)),
     warn: (message, fields = {}) => write(line('warn', message, tags, fields)),
-    error: (error, fields = {}) => {
-        const message = error instanceof Error ? error.message : String(error);
-        write(line('error', message, tags, { ...errorFields(error), ...fields }));
-    },
+    error: (error, fields = {}) => write(line('error', messageOf(error), tags, { ...fields, ...errorFields(error) })),
 });

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

@@ -2,7 +2,7 @@ import { z } from 'zod';
 declare const CodePartSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
     entry: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>]>;
-export declare const PartsSchema: z.ZodObject<{
+declare const PartsSchema: z.ZodObject<{
     pages: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
         entry: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>]>>;
@@ -33,93 +33,6 @@ export declare const PartsSchema: z.ZodObject<{
         }>;
     }, z.core.$strict>]>>;
 }, z.core.$strict>;
-export 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";
-        }>;
-        required: z.ZodOptional<z.ZodBoolean>;
-        description: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-}, z.core.$strict>;
-export declare const SettingSchema: z.ZodObject<{
-    type: z.ZodEnum<{
-        string: "string";
-        number: "number";
-        boolean: "boolean";
-        integer: "integer";
-    }>;
-    default: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
-    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    description: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export declare const AgentageSchema: z.ZodObject<{
-    id: z.ZodString;
-    parts: z.ZodObject<{
-        pages: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        ui: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        api: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        mcp: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        worker: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        cli: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-            entry: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
-        store: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
-            postgres: "postgres";
-            git: "git";
-            signoz: "signoz";
-        }>, z.ZodObject<{
-            kind: z.ZodEnum<{
-                postgres: "postgres";
-                git: "git";
-                signoz: "signoz";
-            }>;
-        }, z.core.$strict>]>>;
-    }, z.core.$strict>;
-    commands: z.ZodOptional<z.ZodArray<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";
-            }>;
-            required: z.ZodOptional<z.ZodBoolean>;
-            description: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>>;
-    }, z.core.$strict>>>;
-    settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        type: z.ZodEnum<{
-            string: "string";
-            number: "number";
-            boolean: "boolean";
-            integer: "integer";
-        }>;
-        default: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
-        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        description: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>>;
-    secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>;
 export declare const PackageSchema: z.ZodObject<{
     name: z.ZodString;
     version: z.ZodString;
@@ -190,6 +103,5 @@ export declare const PackageSchema: z.ZodObject<{
 }, z.core.$loose>;
 export type CodePart = z.infer<typeof CodePartSchema>;
 export type Parts = z.infer<typeof PartsSchema>;
-export type Agentage = z.infer<typeof AgentageSchema>;
 export type ExtensionPackage = z.infer<typeof PackageSchema>;
 export {};

package/dist/manifest/manifest.schema.js

@@ -6,7 +6,7 @@ const CodePartSchema = z.union([
 ]);
 const StorePartSchema = z.union([StoreKindSchema, z.strictObject({ kind: StoreKindSchema })]);
 const ROUTED = ['pages', 'ui', 'api', 'mcp'];
-export const PartsSchema = z
+const PartsSchema = z
     .strictObject({
     pages: CodePartSchema.optional(),
     ui: CodePartSchema.optional(),
@@ -20,7 +20,7 @@ export const PartsSchema = z
     message: 'at least one routed part (pages, ui, api or mcp)',
 });
 const ArgTypeSchema = z.enum(['string', 'integer', 'number', 'boolean']);
-export const CommandSchema = z.strictObject({
+const CommandSchema = z.strictObject({
     name: CommandNameSchema,
     summary: z.string().min(1).max(120),
     args: z
@@ -32,7 +32,7 @@ export const CommandSchema = z.strictObject({
     }))
         .optional(),
 });
-export const SettingSchema = z
+const SettingSchema = z
     .strictObject({
     type: ArgTypeSchema,
     default: z.union([z.string(), z.number(), z.boolean()]),
@@ -41,6 +41,9 @@ export const SettingSchema = z
 })
     .refine((setting) => defaultFits(setting.type, setting.default), {
     message: 'default does not match type',
+})
+    .refine((setting) => !setting.enum || setting.enum.includes(String(setting.default)), {
+    message: 'default is not one of enum',
 });
 const AgentageBaseSchema = z.strictObject({
     id: ExtensionIdSchema,
@@ -49,7 +52,7 @@ const AgentageBaseSchema = z.strictObject({
     settings: z.record(SettingKeySchema, SettingSchema).optional(),
     secrets: z.array(SecretNameSchema).optional(),
 });
-export const AgentageSchema = AgentageBaseSchema.superRefine(crossFieldRules);
+const AgentageSchema = AgentageBaseSchema.superRefine(crossFieldRules);
 export const PackageSchema = z
     .looseObject({
     name: PackageNameSchema,

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

@@ -13,6 +13,7 @@ export declare const StoreKindSchema: z.ZodEnum<{
     git: "git";
     signoz: "signoz";
 }>;
+export declare const FULL_SHA: RegExp;
 export declare const CommitSchema: z.ZodString;
 export declare const PrefixedToolNameSchema: z.ZodString;
 export declare const IMAGE_PART_KINDS: readonly ["pages", "ui", "api", "mcp", "worker"];

package/dist/manifest/primitives.schema.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+// Platform names and cli verbs, plus Windows device names: an id is a folder name on machines.
 const RESERVED_IDS = 'auth|www|api|sync|mail|mcp|ui|git|setup|status|update|extension|add|remove|help|con|prn|aux|nul|com[0-9]|lpt[0-9]';
 export const ExtensionIdSchema = z
     .string()
@@ -44,7 +45,8 @@ export const PackagePathSchema = z
     .max(256)
     .regex(/^\.\/[A-Za-z0-9._/-]+$/);
 export const StoreKindSchema = z.enum(['postgres', 'git', 'signoz']);
-export const CommitSchema = z.string().regex(/^[0-9a-f]{40}$/, { message: 'full 40-hex git sha' });
+export const FULL_SHA = /^[0-9a-f]{40}$/;
+export const CommitSchema = z.string().regex(FULL_SHA, { message: 'full 40-hex git sha' });
 export const PrefixedToolNameSchema = z
     .string()
     .max(64)

package/dist/manifest/read-manifest.d.ts

@@ -2,4 +2,5 @@ import { type z } from 'zod';
 import { type ExtensionPackage } from './manifest.schema.js';
 export declare const formatIssues: (issues: readonly z.core.$ZodIssue[]) => string;
 export declare const validateManifest: (value: unknown) => ExtensionPackage;
+export declare const readJsonIfExists: (file: string) => Promise<unknown>;
 export declare const readManifest: (dir: string) => Promise<ExtensionPackage>;

package/dist/manifest/read-manifest.js

@@ -11,9 +11,32 @@ export const validateManifest = (value) => {
         return result.data;
     throw new Error(`invalid agentage manifest in package.json: ${formatIssues(result.error.issues)}`);
 };
+const parseJson = (text, file) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`${file} is not valid JSON: ${err.message}`);
+    }
+};
+// undefined only for a missing file (JSON never parses to it); any other read error is thrown.
+export const readJsonIfExists = async (file) => {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+    return parseJson(text, file);
+};
 // The manifest is the `agentage` block of package.json, read as data without running code.
 export const readManifest = async (dir) => {
-    const file = join(dir, 'package.json');
-    const text = await readFile(file, 'utf8');
-    return validateManifest(JSON.parse(text));
+    const pkg = await readJsonIfExists(join(dir, 'package.json'));
+    if (pkg === undefined) {
+        throw new Error(`no package.json in ${dir}: run it in an extension package folder`);
+    }
+    return validateManifest(pkg);
 };

package/dist/runtime/build-info.d.ts

@@ -1,4 +1,5 @@
 import { type BuildInfo } from '../discovery/discovery.js';
 export type Env = Readonly<Record<string, string | undefined>>;
+export declare const isoSeconds: (date: Date) => string;
 export declare const buildInfoFromEnv: (env: Env, now?: Date) => BuildInfo;
 export declare const portFromEnv: (env: Env, fallback?: number) => number;

package/dist/runtime/build-info.js

@@ -1,11 +1,11 @@
 import {} from '../discovery/discovery.js';
+import { FULL_SHA } from '../manifest/primitives.schema.js';
 const UNKNOWN_COMMIT = '0'.repeat(40);
-const isoSeconds = (date) => `${date.toISOString().slice(0, 19)}Z`;
+export const isoSeconds = (date) => `${date.toISOString().slice(0, 19)}Z`;
+const commitOf = (sha = '') => (FULL_SHA.test(sha) ? sha : UNKNOWN_COMMIT);
 // COMMIT_SHA and BUILD_TIME are baked into every image by the recipe; a bare dev run shows zeros.
 export const buildInfoFromEnv = (env, now = new Date()) => ({
-    commit: env['COMMIT_SHA'] && /^[0-9a-f]{40}$/.test(env['COMMIT_SHA'])
-        ? env['COMMIT_SHA']
-        : UNKNOWN_COMMIT,
+    commit: commitOf(env['COMMIT_SHA']),
     buildTime: env['BUILD_TIME'] || isoSeconds(now),
 });
 export const portFromEnv = (env, fallback = 3000) => {

package/dist/runtime/main.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
+import { createLog } from '../log/log.js';
 import { runPart } from './run-part.js';
 // Image entry: `node node_modules/@agentage/extension/dist/runtime/main.js api` in /app.
+const part = process.argv[2] ?? 'api';
 try {
-    await runPart({ dir: process.cwd(), part: process.argv[2] ?? 'api', env: process.env });
+    await runPart({ dir: process.cwd(), part, env: process.env });
 }
 catch (err) {
-    process.stderr.write(`${JSON.stringify({ level: 'error', msg: String(err) })}\n`);
+    // The manifest may be what failed, so the id is not known here; the line keeps the stack.
+    createLog({ extension: 'unknown', part }).error(err);
     process.exit(1);
 }

package/dist/runtime/run-part.js

@@ -5,6 +5,7 @@ import { createContext } from '../context/context.js';
 import { DEFAULT_RECORD_FILE, loadRecord } from '../discovery/discovery.js';
 import { createLog } from '../log/log.js';
 import { entryOf } from '../manifest/parts.js';
+import {} from '../manifest/manifest.schema.js';
 import { readManifest } from '../manifest/read-manifest.js';
 import { createApiApp } from '../server/app.js';
 import {} from '../server/part.types.js';
@@ -24,7 +25,12 @@ const recordFor = async (env, log) => {
         log.warn('no release record mounted; discovery lists this image by tag', { file });
     return record;
 };
-// The image entry for a server part: manifest, ctx, create(ctx), then the kit's own server.
+const createRouter = async (options, ctx, pkg) => {
+    const file = join(options.dir, entryOf(pkg, 'api'));
+    const mod = await (options.importModule ?? importFile)(file);
+    return createOf(mod, file)(ctx);
+};
+const contextFor = (pkg, origin, port, log) => createContext({ pkg, part: 'api', origin: origin ?? `http://127.0.0.1:${port}`, log });
 export const runPart = async (options) => {
     if (options.part !== 'api')
         throw new Error(`part ${options.part} is not served by kit 0.1`);
@@ -33,25 +39,10 @@ export const runPart = async (options) => {
     const log = createLog({ extension: pkg.agentage.id, part: 'api' });
     const port = portFromEnv(env);
     const origin = env['AGENTAGE_ORIGIN'] || undefined;
-    const ctx = createContext({
-        pkg,
-        part: 'api',
-        origin: origin ?? `http://127.0.0.1:${port}`,
-        log,
-    });
-    const file = join(options.dir, entryOf(pkg, 'api'));
-    const mod = await (options.importModule ?? importFile)(file);
-    const router = await createOf(mod, file)(ctx);
+    const router = await createRouter(options, contextFor(pkg, origin, port, log), pkg);
     const build = buildInfoFromEnv(env);
     const record = await recordFor(env, log);
-    const app = createApiApp({
-        pkg,
-        build,
-        router,
-        log,
-        record,
-        origin,
-        ownImage: env['AGENTAGE_IMAGE'],
-    });
+    const ownImage = env['AGENTAGE_IMAGE'];
+    const app = createApiApp({ pkg, build, router, log, record, origin, ownImage });
     return serve({ app, port, log, ...options.serve });
 };

package/dist/server/app.d.ts

@@ -1,4 +1,3 @@
-import { type CorsOptions } from 'cors';
 import { type Express } from 'express';
 import { type BuildInfo } from '../discovery/discovery.js';
 import { type ExtensionRecord } from '../discovery/discovery.schema.js';
@@ -14,5 +13,4 @@ export interface ApiAppOptions {
     ownImage?: string;
     origin?: string;
 }
-export declare const PUBLIC_CORS: CorsOptions;
 export declare const createApiApp: (options: ApiAppOptions) => Express;

package/dist/server/app.js

@@ -10,7 +10,7 @@ import {} from '../manifest/manifest.schema.js';
 import { errorHandler, notFound } from './errors.js';
 import {} from './part.types.js';
 // api-standards section 6: CORS * without credentials on /.well-known/ and /api/.
-export const PUBLIC_CORS = {
+const PUBLIC_CORS = {
     origin: '*',
     credentials: false,
     allowedHeaders: ['Authorization', 'Content-Type', 'agcid', 'traceparent', 'If-Match'],
@@ -31,10 +31,9 @@ const healthHandler = (options) => createHealthHandler({
     version: options.pkg.version,
     build: options.build,
 });
-// The kit owns the app: agcid, helmet, CORS, /health, discovery, the body limit, 404 and errors.
 export const createApiApp = (options) => {
     const app = express();
-    app.disable('x-powered-by');
+    // The gateway calls parts over a private network; its X-Forwarded-Proto then sets req.protocol.
     app.set('trust proxy', 'loopback, linklocal, uniquelocal');
     app.use(agcidMiddleware, helmet());
     app.get('/health', healthHandler(options));

package/dist/server/errors.d.ts

@@ -1,6 +1,4 @@
 import { type ErrorRequestHandler, type RequestHandler } from 'express';
-import { type Failure } from '../envelope/envelope.js';
 import { type Log } from '../log/log.js';
-export declare const toFailure: (err: unknown) => Failure;
 export declare const notFound: RequestHandler;
 export declare const errorHandler: (log: Log) => ErrorRequestHandler;

package/dist/server/errors.js

@@ -11,7 +11,7 @@ const bodyParserFailure = (err) => {
     return null;
 };
 // Anything that is not a kit failure is an INTERNAL 500 with a generic message; the log has it whole.
-export const toFailure = (err) => {
+const toFailure = (err) => {
     if (isFailure(err))
         return err;
     return bodyParserFailure(err) ?? fail('INTERNAL', 'Internal error');

package/dist/server/serve.d.ts

@@ -5,7 +5,6 @@ export interface ServeOptions {
     app: Express;
     port: number;
     log: Log;
-    graceMs?: number;
     exit?: (code: number) => void;
     signals?: NodeJS.Signals[];
 }

package/dist/server/serve.js

@@ -2,6 +2,7 @@ import {} from 'node:http';
 import {} from 'node:net';
 import {} from 'express';
 import {} from '../log/log.js';
+const GRACE_MS = 10_000;
 export const listen = (app, port, host) => new Promise((resolve, reject) => {
     const done = (err) => (err ? reject(err) : resolve(server));
     const server = host === undefined ? app.listen(port, done) : app.listen(port, host, done);
@@ -13,7 +14,7 @@ export const shutdownOn = (server, options) => {
         options.log.info('shutting down');
         server.close(() => exit(0));
         server.closeIdleConnections();
-        setTimeout(() => exit(0), options.graceMs ?? 10_000).unref();
+        setTimeout(() => exit(0), GRACE_MS).unref();
     };
     for (const signal of options.signals ?? ['SIGTERM', 'SIGINT'])
         process.once(signal, stop);

package/dist/tool/build-info.js

@@ -1,8 +1,7 @@
 import {} from '../discovery/discovery.js';
-import {} from '../runtime/build-info.js';
+import { FULL_SHA } from '../manifest/primitives.schema.js';
+import { isoSeconds } from '../runtime/build-info.js';
 import { mustRun } from './exec.js';
-const FULL_SHA = /^[0-9a-f]{40}$/;
-const isoSeconds = (date) => `${date.toISOString().slice(0, 19)}Z`;
 const commitOf = async (dir, env, run) => {
     const given = env['COMMIT_SHA'] || env['GITHUB_SHA'];
     if (given)

package/dist/tool/build.d.ts

@@ -3,14 +3,11 @@ import { type ImagePartKind } from '../manifest/primitives.schema.js';
 import { type Env } from '../runtime/build-info.js';
 import { type Docker } from './docker.js';
 import { type Run } from './exec.js';
-export declare const DEFAULT_REGISTRY = "ghcr.io/agentage";
-export declare const SUPPORTED_PARTS: readonly ImagePartKind[];
 export interface BuildOptions {
     dir?: string;
     push?: boolean;
     registry?: string;
     env?: Env;
-    now?: Date;
 }
 export interface BuildDeps {
     run: Run;

package/dist/tool/build.js

@@ -11,8 +11,8 @@ import { createDocker } from './docker.js';
 import { mustRun, runCommand } from './exec.js';
 import { labelsOf } from './labels.js';
 import { RECORD_FILE, stageContext } from './stage.js';
-export const DEFAULT_REGISTRY = 'ghcr.io/agentage';
-export const SUPPORTED_PARTS = ['api'];
+const DEFAULT_REGISTRY = 'ghcr.io/agentage';
+const SUPPORTED_PARTS = ['api'];
 export const imageTag = (registry, pkg, part) => `${registry}/${pkg.agentage.id}-${part}:${pkg.version}`;
 const partsToBuild = (pkg) => {
     const parts = imageParts(pkg);
@@ -58,25 +58,24 @@ const writeRecord = async (dir, pkg, info, images) => {
     await writeFile(file, `${JSON.stringify(record, null, 2)}\n`);
     return file;
 };
-const buildParts = async (base, options, deps) => {
+const buildParts = async (base, parts, options, deps) => {
     const docker = deps.docker ?? createDocker(deps.run);
     const registry = options.registry ?? DEFAULT_REGISTRY;
     const images = [];
-    for (const part of partsToBuild(base.pkg)) {
+    for (const part of parts) {
         const job = { ...base, part, tag: imageTag(registry, base.pkg, part) };
         await buildImage(job, docker, deps.tmpRoot);
         images.push(options.push ? await pushImage(job, docker) : { part, tag: job.tag });
     }
     return images;
 };
-// One image per server part from the kit recipe; with push, the digests go into the build record.
 export const build = async (options = {}, deps = { run: runCommand }) => {
     const dir = resolve(options.dir ?? '.');
     const pkg = await readManifest(dir);
-    partsToBuild(pkg);
-    const info = await resolveBuildInfo(dir, options.env ?? process.env, deps.run, options.now);
+    const parts = partsToBuild(pkg);
+    const info = await resolveBuildInfo(dir, options.env ?? process.env, deps.run);
     await compile(dir, pkg, deps.run);
-    const images = await buildParts({ dir, pkg, info }, options, deps);
+    const images = await buildParts({ dir, pkg, info }, parts, options, deps);
     const recordFile = options.push ? await writeRecord(dir, pkg, info, images) : undefined;
     const result = { id: pkg.agentage.id, version: pkg.version, ...info, images };
     return recordFile ? { ...result, recordFile } : result;

package/dist/tool/docker.d.ts

@@ -9,7 +9,6 @@ export interface Docker {
     build(options: DockerBuild): Promise<void>;
     push(tag: string): Promise<string>;
 }
-export declare const PLATFORM = "linux/amd64";
 export declare const buildArgsOf: (options: DockerBuild) => string[];
 export declare const digestOf: (pushOutput: string) => string;
 export declare const createDocker: (run: Run) => Docker;

package/dist/tool/docker.js

@@ -1,6 +1,7 @@
 import { mustRun } from './exec.js';
-export const PLATFORM = 'linux/amd64';
+const PLATFORM = 'linux/amd64';
 const flags = (flag, values) => Object.entries(values).flatMap(([key, value]) => [flag, `${key}=${value}`]);
+// No provenance attestation: the pushed digest is then the image itself, as the record expects.
 export const buildArgsOf = (options) => [
     'build',
     '--platform',

package/dist/tool/exec.d.ts

@@ -1,6 +1,5 @@
 export interface RunOptions {
     cwd?: string;
-    env?: NodeJS.ProcessEnv;
     echo?: boolean;
 }
 export interface RunResult {

package/dist/tool/exec.js

@@ -1,18 +1,14 @@
 import { spawn } from 'node:child_process';
 // stdout is captured (and echoed to stderr with `echo`); stderr streams through as progress.
 export const runCommand = (command, args, options = {}) => new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
-        cwd: options.cwd,
-        env: options.env ?? process.env,
-        stdio: ['ignore', 'pipe', 'inherit'],
-    });
+    const child = spawn(command, args, { cwd: options.cwd, stdio: ['ignore', 'pipe', 'inherit'] });
     let stdout = '';
     child.stdout.on('data', (chunk) => {
         stdout += chunk.toString();
         if (options.echo)
             process.stderr.write(chunk);
     });
-    child.on('error', reject);
+    child.on('error', (err) => reject(err.code === 'ENOENT' ? new Error(`${command} is not installed or not on PATH`) : err));
     child.on('close', (code) => resolve({ code: code ?? 1, stdout }));
 });
 export const mustRun = async (run, command, args, options) => {

package/dist/tool/index.d.ts

@@ -1,11 +1,2 @@
-export { build, DEFAULT_REGISTRY, imageTag, SUPPORTED_PARTS, type BuildDeps, type BuildOptions, type BuildResult, type BuiltImage, } from './build.js';
-export { resolveBuildInfo } from './build-info.js';
-export { createDocker, PLATFORM, type Docker, type DockerBuild } from './docker.js';
-export { runCommand, type Run, type RunOptions, type RunResult } from './exec.js';
+export { build, type BuildDeps, type BuildOptions, type BuildResult, type BuiltImage, } from './build.js';
 export { buildLines } from './format.js';
-export { labelsOf } from './labels.js';
-export { main as runTool, USAGE as TOOL_USAGE } from './main.js';
-export { PART_PORT, serverPartRecipe } from './recipe.js';
-export { RECORD_FILE, stageContext } from './stage.js';
-export { readManifest, validateManifest } from '../manifest/read-manifest.js';
-export { type ExtensionPackage } from '../manifest/manifest.schema.js';

package/dist/tool/index.js

@@ -1,11 +1,2 @@
-export { build, DEFAULT_REGISTRY, imageTag, SUPPORTED_PARTS, } from './build.js';
-export { resolveBuildInfo } from './build-info.js';
-export { createDocker, PLATFORM } from './docker.js';
-export { runCommand } from './exec.js';
+export { build, } from './build.js';
 export { buildLines } from './format.js';
-export { labelsOf } from './labels.js';
-export { main as runTool, USAGE as TOOL_USAGE } from './main.js';
-export { PART_PORT, serverPartRecipe } from './recipe.js';
-export { RECORD_FILE, stageContext } from './stage.js';
-export { readManifest, validateManifest } from '../manifest/read-manifest.js';
-export {} from '../manifest/manifest.schema.js';

package/dist/tool/main.d.ts

@@ -4,5 +4,4 @@ export interface MainDeps {
     out: (line: string) => void;
     err: (line: string) => void;
 }
-export declare const USAGE = "usage: agentage-extension build [--push] [--dir <path>] [--registry <host/owner>]\n\n  build      one image per server part from the kit recipe\n  --push     push the images and write dist/agentage-extension.json with their digests\n  --dir      the extension package folder (default: the current folder)\n  --registry image registry and owner (default: ghcr.io/agentage)";
 export declare const main: (argv: string[], deps?: MainDeps) => Promise<number>;

package/dist/tool/main.js

@@ -1,7 +1,7 @@
 import { parseArgs } from 'node:util';
 import { build } from './build.js';
 import { buildLines } from './format.js';
-export const USAGE = `usage: agentage-extension build [--push] [--dir <path>] [--registry <host/owner>]
+const USAGE = `usage: agentage-extension build [--push] [--dir <path>] [--registry <host/owner>]
 
   build      one image per server part from the kit recipe
   --push     push the images and write dist/agentage-extension.json with their digests
@@ -22,6 +22,17 @@ const parse = (argv) => parseArgs({
         help: { type: 'boolean', short: 'h' },
     },
 });
+const runBuild = async (options, deps) => {
+    try {
+        for (const line of buildLines(await deps.build(options)))
+            deps.out(line);
+        return 0;
+    }
+    catch (err) {
+        deps.err(`build failed: ${err.message}`);
+        return 1;
+    }
+};
 // Exit codes: 0 ok, 1 the build failed, 2 usage.
 export const main = async (argv, deps = defaultDeps) => {
     let parsed;
@@ -33,22 +44,13 @@ export const main = async (argv, deps = defaultDeps) => {
         return 2;
     }
     const { positionals, values } = parsed;
-    if (values.help)
-        return (deps.out(USAGE), 0);
-    if (positionals[0] !== 'build' || positionals.length !== 1)
-        return (deps.err(USAGE), 2);
-    try {
-        const result = await deps.build({
-            push: values.push,
-            dir: values.dir,
-            registry: values.registry,
-        });
-        for (const line of buildLines(result))
-            deps.out(line);
+    if (values.help) {
+        deps.out(USAGE);
         return 0;
     }
-    catch (err) {
-        deps.err(`build failed: ${err.message}`);
-        return 1;
+    if (positionals[0] !== 'build' || positionals.length !== 1) {
+        deps.err(USAGE);
+        return 2;
     }
+    return runBuild({ push: values.push, dir: values.dir, registry: values.registry }, deps);
 };

package/dist/tool/recipe.d.ts

@@ -1,3 +1,2 @@
 import { type ImagePartKind } from '../manifest/primitives.schema.js';
-export declare const PART_PORT = 3000;
 export declare const serverPartRecipe: (part: ImagePartKind) => string;

package/dist/tool/recipe.js

@@ -1,9 +1,9 @@
 import {} from '../manifest/primitives.schema.js';
-export const PART_PORT = 3000;
+const PART_PORT = 3000;
+// 503 passes: a restart cannot fix a dependency outage, so only a dead or 404 part is unhealthy.
 const HEALTH_PROBE = `fetch('http://127.0.0.1:${PART_PORT}/health')` +
     '.then((r) => process.exit(r.status === 200 || r.status === 503 ? 0 : 1), () => process.exit(1))';
-// The one recipe for a Node server part; the staged context holds deps/ (npm ci) and app/ (code).
-export const serverPartRecipe = (part) => [
+const RECIPE = [
     '# syntax=docker/dockerfile:1',
     '# Generated by @agentage/extension build. Extension authors never write a Dockerfile.',
     'FROM node:26-alpine AS deps',
@@ -27,6 +27,10 @@ export const serverPartRecipe = (part) => [
     'USER node',
     `EXPOSE ${PART_PORT}`,
     `HEALTHCHECK --interval=10s --timeout=3s --start-period=15s --retries=3 CMD ["node", "-e", "${HEALTH_PROBE}"]`,
+];
+// The one recipe for a Node server part; the staged context holds deps/ (npm ci) and app/ (code).
+export const serverPartRecipe = (part) => [
+    ...RECIPE,
     `CMD ["node", "node_modules/@agentage/extension/dist/runtime/main.js", "${part}"]`,
     '',
 ].join('\n');

package/dist/tool/stage.js

@@ -1,7 +1,8 @@
 import { access, cp, mkdir, mkdtemp, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { basename, dirname, isAbsolute, join, normalize } from 'node:path';
+import { basename, dirname, isAbsolute, join, normalize, sep } from 'node:path';
 import {} from '../manifest/manifest.schema.js';
+import { entryOf } from '../manifest/parts.js';
 import {} from '../manifest/primitives.schema.js';
 import { serverPartRecipe } from './recipe.js';
 export const RECORD_FILE = 'agentage-extension.json';
@@ -36,14 +37,26 @@ const copyDeps = async (dir, root, pkg) => {
 };
 const copyApp = async (dir, root) => {
     await copyInto(join(dir, 'package.json'), join(root, 'app', 'package.json'));
-    await mkdir(join(root, 'app'), { recursive: true });
     await cp(join(dir, 'dist'), join(root, 'app', 'dist'), {
         recursive: true,
         filter: (source) => basename(source) !== RECORD_FILE,
     });
 };
+// The image carries dist/ only, so an entry outside it, or never built, would not start.
+const assertBuiltEntry = async (dir, pkg, part) => {
+    const entry = normalize(entryOf(pkg, part));
+    if (!entry.startsWith(`dist${sep}`))
+        throw new Error(`the ${part} entry ${entry} is not in dist/`);
+    try {
+        await access(join(dir, entry));
+    }
+    catch {
+        throw new Error(`${entry} not found: the package build must write the ${part} entry there`);
+    }
+};
 // A clean build context per part: only the manifest, the lockfile, local tarballs and dist/.
 export const stageContext = async (dir, pkg, part, tmpRoot = tmpdir()) => {
+    await assertBuiltEntry(dir, pkg, part);
     const root = await mkdtemp(join(tmpRoot, `agentage-${pkg.agentage.id}-${part}-`));
     await copyDeps(dir, root, pkg);
     await copyApp(dir, root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentage/extension",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The agentage extension kit: create(ctx) per part, the server, /health, discovery, the envelope, and the build tool",
   "type": "module",
   "license": "MIT",