@agentage/extension 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentage Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @agentage/extension
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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`.
+
+```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.

package/dist/agcid/agcid.d.ts

@@ -0,0 +1,4 @@
+export declare const AGCID_HEADER = "agcid";
+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

@@ -0,0 +1,15 @@
+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);
+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)) => {
+    const bytes = Buffer.alloc(16);
+    bytes.writeUIntBE(now, 0, 6);
+    random.copy(bytes, 6, 0, 10);
+    bytes.writeUInt8((bytes.readUInt8(6) & 0x0f) | 0x70, 6);
+    bytes.writeUInt8((bytes.readUInt8(8) & 0x3f) | 0x80, 8);
+    return hyphenate(bytes.toString('hex'));
+};
+export const agcidOf = (incoming) => (isAgcid(incoming) ? incoming : uuidv7());

package/dist/agcid/scope.d.ts

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,16 @@
+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;
+// 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);
+};
+export const agcidOfResponse = (res) => {
+    const agcid = res.locals['agcid'];
+    return typeof agcid === 'string' ? agcid : agcidOf(undefined);
+};

package/dist/context/context.d.ts

@@ -0,0 +1,36 @@
+import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+import { type Log, type LogFields, type LogLevel } from '../log/log.js';
+export type ServerPartKind = 'pages' | 'api' | 'mcp' | 'worker';
+export type SettingValue = string | number | boolean;
+export interface ExtensionInfo {
+    id: string;
+    version: string;
+    part: ServerPartKind;
+    origin: string;
+}
+export interface PartContext {
+    readonly extension: Readonly<ExtensionInfo>;
+    readonly log: Log;
+    readonly settings: Readonly<Record<string, SettingValue>>;
+}
+export declare const settingDefaults: (pkg: ExtensionPackage) => Record<string, SettingValue>;
+export interface ContextInput {
+    pkg: ExtensionPackage;
+    part: ServerPartKind;
+    origin: 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>;
+}
+export declare const createTestContext: (options?: TestContextOptions) => TestContext;

package/dist/context/context.js

@@ -0,0 +1,25 @@
+import {} from '../manifest/manifest.schema.js';
+import { createLog } 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 }),
+    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: String(error), fields: { ...fields, err: error } }),
+});
+// A ctx for unit tests: fixed identity, settings as given, a log that records instead of printing.
+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 };
+};

package/dist/discovery/discovery.d.ts

@@ -0,0 +1,47 @@
+import { type ExtensionPackage } from '../manifest/manifest.schema.js';
+import { type ImagePartKind } from '../manifest/primitives.schema.js';
+import { type ExtensionRecord } from './discovery.schema.js';
+export interface BuildInfo {
+    commit: string;
+    buildTime: string;
+}
+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 declare const validateRecord: (value: unknown) => ExtensionRecord;
+export declare const loadRecord: (file: string) => Promise<ExtensionRecord | null>;
+export declare const discoveryDocument: (record: ExtensionRecord, host: string) => {
+    parts: {
+        pages?: {
+            image: string;
+        } | undefined;
+        ui?: {
+            image: string;
+        } | undefined;
+        api?: {
+            image: string;
+        } | undefined;
+        mcp?: {
+            image: string;
+        } | undefined;
+        worker?: {
+            image: string;
+        } | undefined;
+        store?: {
+            kind: "postgres" | "git" | "signoz";
+        } | undefined;
+    };
+    openapi?: string | undefined;
+    tools?: string[] | undefined;
+    widgets?: {
+        name: string;
+        element: string;
+        module: string;
+    }[] | undefined;
+    commands?: string[] | undefined;
+    id: string;
+    version: string;
+    commit: string;
+    buildTime: string;
+    host: string;
+};

package/dist/discovery/discovery.js

@@ -0,0 +1,52 @@
+import { readFile } from 'node:fs/promises';
+import { formatIssues } 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))
+        parts[kind] = { image };
+    const store = normalizeParts(pkg.agentage.parts).store;
+    if (store)
+        parts['store'] = { kind: store };
+    return parts;
+};
+// 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));
+};
+export const validateRecord = (value) => {
+    const result = ExtensionRecordSchema.safeParse(value);
+    if (result.success)
+        return result.data;
+    throw new Error(`invalid extension record: ${formatIssues(result.error.issues)}`);
+};
+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));
+};
+export const discoveryDocument = (record, host) => {
+    const { id, version, commit, buildTime, ...rest } = record;
+    return { id, version, commit, buildTime, host, ...rest };
+};

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

@@ -0,0 +1,106 @@
+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;
+    commit: z.ZodString;
+    buildTime: z.ZodISODateTime;
+    parts: 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>;
+    openapi: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    widgets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        element: z.ZodString;
+        module: z.ZodString;
+    }, z.core.$strict>>>;
+    commands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const DiscoveryDocumentSchema: z.ZodObject<{
+    host: z.ZodString;
+    id: z.ZodString;
+    version: z.ZodString;
+    commit: z.ZodString;
+    buildTime: z.ZodISODateTime;
+    parts: 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>;
+    openapi: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    widgets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        element: z.ZodString;
+        module: z.ZodString;
+    }, z.core.$strict>>>;
+    commands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ExtensionRecord = z.infer<typeof ExtensionRecordSchema>;
+export type DiscoveryDocument = z.infer<typeof DiscoveryDocumentSchema>;

package/dist/discovery/discovery.schema.js

@@ -0,0 +1,56 @@
+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
+    .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
+    .strictObject({
+    pages: PartImageSchema.optional(),
+    ui: PartImageSchema.optional(),
+    api: PartImageSchema.optional(),
+    mcp: PartImageSchema.optional(),
+    worker: PartImageSchema.optional(),
+    store: z.strictObject({ kind: StoreKindSchema }).optional(),
+})
+    .refine((parts) => IMAGE_PART_KINDS.some((kind) => parts[kind] !== undefined), {
+    message: 'at least one part with an image',
+});
+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({
+    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 recordShape = {
+    id: ExtensionIdSchema,
+    version: VersionSchema,
+    commit: CommitSchema,
+    buildTime: z.iso.datetime(),
+    parts: PartsRecordSchema,
+    openapi: z
+        .string()
+        .regex(/^\/api\/v[1-9][0-9]*\/openapi\.json$/)
+        .optional(),
+    tools: z.array(PrefixedToolNameSchema).min(1).optional(),
+    widgets: z.array(WidgetSchema).min(1).optional(),
+    commands: z.array(CommandNameSchema).min(1).optional(),
+};
+const imagesNameTheirExtension = (doc) => IMAGE_PART_KINDS.every((kind) => {
+    const image = doc.parts[kind]?.image;
+    return image === undefined || image.includes(`/${doc.id}-${kind}@sha256:`);
+});
+const IMAGE_RULE = { message: 'every image is {id}-{part}', path: ['parts'] };
+// The build record: written by `build --push` into the package and the release asset; no host.
+export const ExtensionRecordSchema = z
+    .strictObject(recordShape)
+    .refine(imagesNameTheirExtension, IMAGE_RULE);
+// What a deployment serves at /.well-known/agentage-extension.json: the record plus its host.
+export const DiscoveryDocumentSchema = z
+    .strictObject({ ...recordShape, host: OriginSchema })
+    .refine(imagesNameTheirExtension, IMAGE_RULE);

package/dist/envelope/codes.d.ts

@@ -0,0 +1,16 @@
+export declare const ERROR_STATUS: {
+    readonly VALIDATION_ERROR: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly CONFLICT: 409;
+    readonly PRECONDITION_FAILED: 412;
+    readonly PAYLOAD_TOO_LARGE: 413;
+    readonly RATE_LIMITED: 429;
+    readonly INTERNAL: 500;
+    readonly UNAVAILABLE: 503;
+};
+export type ErrorCode = keyof typeof ERROR_STATUS;
+export declare const ERROR_CODES: ErrorCode[];
+export declare const RETRY_AFTER_CODES: readonly ErrorCode[];
+export declare const DEFAULT_RETRY_AFTER_SECONDS = 30;

package/dist/envelope/codes.js

@@ -0,0 +1,15 @@
+export const ERROR_STATUS = {
+    VALIDATION_ERROR: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    PRECONDITION_FAILED: 412,
+    PAYLOAD_TOO_LARGE: 413,
+    RATE_LIMITED: 429,
+    INTERNAL: 500,
+    UNAVAILABLE: 503,
+};
+export const ERROR_CODES = Object.keys(ERROR_STATUS);
+export const RETRY_AFTER_CODES = ['RATE_LIMITED', 'UNAVAILABLE'];
+export const DEFAULT_RETRY_AFTER_SECONDS = 30;

package/dist/envelope/envelope.d.ts

@@ -0,0 +1,34 @@
+import { type ErrorCode } from './codes.js';
+export interface ErrorDetail {
+    field: string;
+    message: string;
+}
+export interface OkEnvelope<T> {
+    success: true;
+    data: T;
+    meta?: Record<string, unknown>;
+}
+export interface ErrorBody {
+    code: ErrorCode;
+    message: string;
+    agcid: string;
+    details?: ErrorDetail[];
+}
+export interface ErrorEnvelope {
+    success: false;
+    error: ErrorBody;
+}
+export interface Failure extends Error {
+    readonly code: ErrorCode;
+    readonly status: number;
+    readonly details?: ErrorDetail[];
+    readonly retryAfter?: number;
+}
+export interface FailOptions {
+    details?: ErrorDetail[];
+    retryAfter?: number;
+}
+export declare const ok: <T>(data: T, meta?: Record<string, unknown>) => OkEnvelope<T>;
+export declare const fail: (code: ErrorCode, message: string, options?: FailOptions) => Failure;
+export declare const isFailure: (err: unknown) => err is Failure;
+export declare const errorEnvelope: (failure: Failure, agcid: string) => ErrorEnvelope;

package/dist/envelope/envelope.js

@@ -0,0 +1,23 @@
+import { DEFAULT_RETRY_AFTER_SECONDS, ERROR_STATUS, RETRY_AFTER_CODES, } from './codes.js';
+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) => {
+    if (given !== undefined)
+        return given;
+    return RETRY_AFTER_CODES.includes(code) ? DEFAULT_RETRY_AFTER_SECONDS : undefined;
+};
+// Returned, not thrown, so a route reads `throw fail(...)`; the kit turns it into the envelope.
+export const fail = (code, message, options = {}) => Object.assign(new Error(message), {
+    [FAILURE]: true,
+    code,
+    status: ERROR_STATUS[code],
+    details: options.details,
+    retryAfter: retryAfterOf(code, options.retryAfter),
+});
+export const isFailure = (err) => err instanceof Error && err[FAILURE] === true;
+export const errorEnvelope = (failure, agcid) => {
+    const error = { code: failure.code, message: failure.message, agcid };
+    if (failure.details && failure.details.length > 0)
+        error.details = failure.details;
+    return { success: false, error };
+};

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

@@ -0,0 +1,24 @@
+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<{
+        code: z.ZodEnum<{
+            [x: string]: string;
+        }>;
+        message: z.ZodString;
+        agcid: z.ZodString;
+        details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            field: z.ZodString;
+            message: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const OkEnvelopeSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: z.ZodUnknown;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;

package/dist/envelope/envelope.schema.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+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);
+export const ErrorEnvelopeSchema = z.strictObject({
+    success: z.literal(false),
+    error: z.strictObject({
+        code: ErrorCodeSchema,
+        message: z.string().min(1),
+        agcid: AgcidSchema,
+        details: z.array(z.strictObject({ field: z.string(), message: z.string() })).optional(),
+    }),
+});
+export const OkEnvelopeSchema = z.strictObject({
+    success: z.literal(true),
+    data: z.unknown(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+});

package/dist/envelope/parse.d.ts

@@ -0,0 +1,17 @@
+interface Issue {
+    readonly path: readonly PropertyKey[];
+    readonly message: string;
+}
+export interface ParseSchema<T> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: readonly Issue[];
+        };
+    };
+}
+export declare const parse: <T>(schema: ParseSchema<T>, value: unknown, message?: string) => T;
+export {};

package/dist/envelope/parse.js

@@ -0,0 +1,12 @@
+import { fail } from './envelope.js';
+const detailsOf = (issues) => issues.map((issue) => ({
+    field: issue.path.map((segment) => String(segment)).join('.') || '(root)',
+    message: issue.message,
+}));
+// Structural over Zod's safeParse, so an author's own zod copy works with the kit's.
+export const parse = (schema, value, message = 'Invalid request') => {
+    const result = schema.safeParse(value);
+    if (result.success)
+        return result.data;
+    throw fail('VALIDATION_ERROR', message, { details: detailsOf(result.error.issues) });
+};

package/dist/health/health.d.ts

@@ -0,0 +1,18 @@
+import { type RequestHandler } from 'express';
+import { type BuildInfo } from '../discovery/discovery.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';
+    version: string;
+    build: BuildInfo;
+    checks?: Record<string, HealthCheck>;
+    instance?: string;
+    startedAt?: number;
+    now?: () => Date;
+}
+export declare const worstOf: (statuses: HealthStatus[]) => HealthStatus;
+export declare const isLoopback: (address: string | undefined) => boolean;
+export declare const healthBody: (options: HealthOptions) => Promise<HealthBody>;
+export declare const createHealthHandler: (options: HealthOptions) => RequestHandler;

package/dist/health/health.js

@@ -0,0 +1,43 @@
+import { randomBytes } from 'node:crypto';
+import {} from 'express';
+import {} from '../discovery/discovery.js';
+import { fail } from '../envelope/envelope.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');
+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];
+    }));
+    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 ?? '' };
+    return {
+        success: status !== 'unavailable',
+        data: { ...data, uptimeSeconds, checkedAt: isoSeconds(now), checks },
+    };
+};
+// Answers only on loopback: the container HEALTHCHECK and an operator on the node, never the gateway.
+export const createHealthHandler = (options) => {
+    const resolved = {
+        ...options,
+        instance: options.instance ?? randomBytes(4).toString('hex'),
+        startedAt: options.startedAt ?? Date.now(),
+    };
+    return async (req, res) => {
+        if (!isLoopback(req.socket.localAddress))
+            throw fail('NOT_FOUND', 'Not found');
+        const body = await healthBody(resolved);
+        res.setHeader('Cache-Control', 'no-store');
+        res.status(body.data.status === 'unavailable' ? 503 : 200).json(body);
+    };
+};