@kelloggt/dsh-program-agents 0.0.0-stage → 0.1.0

package/dist/monitoring/tailer.js

@@ -0,0 +1,210 @@
+import { open, stat, mkdir, rename } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { JsonlDecoder, MAX_LOG_LINE_BYTES } from './standard.js';
+/** Bounded file reads, inode-aware rotation, truncation and partial-line handling. */
+export class LogTailer {
+    options;
+    ready;
+    path;
+    handle;
+    identity;
+    offset = 0;
+    committed = 0;
+    cursor;
+    first = true;
+    closed = false;
+    timer;
+    work = Promise.resolve();
+    decoder;
+    records = [];
+    constructor(options) {
+        this.options = options;
+        if (options.pollMs !== undefined && (!Number.isSafeInteger(options.pollMs) || options.pollMs < 1))
+            throw new Error('Invalid polling interval');
+        this.path = resolve(options.logsPath);
+        this.decoder = new JsonlDecoder((record, offset) => this.records.push({ record, offset }));
+        this.ready = this.start();
+    }
+    report(error) { try {
+        this.options.onError?.(error);
+    }
+    catch { } }
+    async start() {
+        try {
+            if ((await stat(this.path)).isDirectory())
+                this.path = resolve(this.path, 'app-log.jsonl');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            if (!/\.jsonl$/i.test(this.path))
+                this.path = resolve(this.path, 'app-log.jsonl');
+        }
+        if (this.options.cursorPath) {
+            try {
+                const handle = await open(resolve(this.options.cursorPath), 'r');
+                try {
+                    if ((await handle.stat()).size > 8192)
+                        throw new Error('Oversize log cursor');
+                    const cursor = JSON.parse(await handle.readFile('utf8'));
+                    if (cursor.version === 1 && cursor.path === this.path && Number.isSafeInteger(cursor.dev) && Number.isSafeInteger(cursor.ino) && Number.isSafeInteger(cursor.offset) && cursor.offset >= 0)
+                        this.cursor = cursor;
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        await this.poll();
+        if (!this.closed) {
+            this.timer = setInterval(() => { void this.poll().catch(error => this.report(error)); }, this.options.pollMs ?? 250);
+            this.timer.unref();
+        }
+    }
+    /** Exposed for deterministic shutdown/tests; overlapping polls serialize. */
+    poll() {
+        this.work = this.work.then(() => this.closed ? undefined : this.tick());
+        this.work = this.work.catch(error => { this.report(error); throw error; });
+        // Preserve a recoverable queue after transient filesystem/callback failures.
+        const result = this.work;
+        this.work = result.catch(() => { });
+        return result;
+    }
+    async attach() {
+        let handle;
+        try {
+            handle = await open(this.path, 'r');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                this.first = false;
+                return false;
+            }
+            throw error;
+        }
+        const info = await handle.stat();
+        if (!info.isFile()) {
+            await handle.close();
+            return false;
+        }
+        this.handle = handle;
+        this.identity = { dev: info.dev, ino: info.ino };
+        const cursorMatches = this.cursor && this.cursor.dev === info.dev && this.cursor.ino === info.ino && this.cursor.offset <= info.size;
+        this.offset = cursorMatches ? this.cursor.offset : this.first && !this.options.readExisting ? info.size : 0;
+        this.committed = this.offset;
+        this.first = false;
+        this.decoder.reset();
+        if (this.offset > 0 && !cursorMatches) {
+            const last = Buffer.alloc(1);
+            await handle.read(last, 0, 1, this.offset - 1);
+            if (last[0] !== 10)
+                this.decoder.discardPartialLine();
+        }
+        return true;
+    }
+    async readAvailable() {
+        const handle = this.handle;
+        const info = await handle.stat();
+        if (info.size < this.offset) {
+            this.offset = 0;
+            this.committed = 0;
+            this.decoder.reset();
+        }
+        const chunk = Buffer.alloc(MAX_LOG_LINE_BYTES);
+        // Maximum 512 KiB per poll, regardless of file size.
+        for (let i = 0; i < 8; i++) {
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, this.offset);
+            if (!bytesRead)
+                return true;
+            const start = this.offset;
+            this.decoder.push(chunk.subarray(0, bytesRead), start);
+            this.offset += bytesRead;
+            const records = this.records;
+            this.records = [];
+            try {
+                for (const { record, offset } of records)
+                    await this.options.onRecord(record, { path: this.path, offset, ...(this.options.run ? { run: this.options.run } : {}) });
+            }
+            catch (error) {
+                // Replay this bounded chunk on callback failure; event_id consumers dedup.
+                this.offset = this.committed;
+                this.decoder.reset();
+                throw error;
+            }
+            // Commit through the last newline, including malformed/oversize lines.
+            const newline = chunk.subarray(0, bytesRead).lastIndexOf(10);
+            if (newline >= 0)
+                this.committed = start + newline + 1;
+            await this.persistCursor();
+            if (bytesRead < chunk.length)
+                return true;
+        }
+        return false;
+    }
+    async persistCursor() {
+        if (!this.options.cursorPath || !this.identity)
+            return;
+        const target = resolve(this.options.cursorPath);
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        const temp = `${target}.tmp-${process.pid}`;
+        const handle = await open(temp, 'w', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify({ version: 1, path: this.path, ...this.identity, offset: this.committed }));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        // Target is the resolved configured cursor path.
+        await rename(temp, target);
+    }
+    async tick() {
+        if (!this.handle && !await this.attach())
+            return;
+        const eof = await this.readAvailable();
+        let current;
+        try {
+            current = await stat(this.path);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return;
+        }
+        if (this.identity?.dev === current.dev && this.identity.ino === current.ino || !eof)
+            return;
+        await this.handle.close();
+        this.handle = undefined;
+        this.decoder.reset();
+        if (await this.attach())
+            await this.readAvailable();
+    }
+    async close() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        try {
+            await this.ready;
+            await this.poll();
+        }
+        finally {
+            this.closed = true;
+            if (this.timer) {
+                clearInterval(this.timer);
+                this.timer = undefined;
+            }
+            await this.work;
+            if (this.handle) {
+                await this.handle.close();
+                this.handle = undefined;
+            }
+        }
+    }
+}
+export { LogTailer as JsonlMonitor };
+//# sourceMappingURL=tailer.js.map

package/dist/monitoring/tailer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tailer.js","sourceRoot":"","sources":["../../src/monitoring/tailer.ts"],"names":[],"mappings":"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"}

package/dist/requests.d.ts

@@ -0,0 +1,92 @@
+import type { JsonValue } from './types.js';
+/** Selection/creation is performed by the parent router, never by the durable store. */
+export type AgentTarget = string | {
+    id: string;
+} | {
+    name: string;
+    instructions?: string;
+} | {
+    create: {
+        name: string;
+        instructions?: string;
+    };
+};
+/** JSON Schema Draft 2020-12, not the intentionally limited logging schema language. */
+export type JSONSchema = Record<string, JsonValue> | boolean;
+export type ResponseSchema = JSONSchema;
+export type RequestStatus = 'pending' | 'answered' | 'cancelled' | 'expired' | 'failed' | 'dispatch-unknown';
+export interface RequestScope {
+    ownerId: string;
+    program: string;
+}
+export interface ResponseReceipt {
+    id: string;
+    requestId: string;
+    status: 'answered';
+    agentId: string;
+    answeredAt: string;
+}
+export interface RequestRecord {
+    /** Server-generated opaque UUID. The id alias is provided for receipt-style callers. */
+    id: string;
+    requestId: string;
+    ownerId: string;
+    program: string;
+    /** Optional caller-provided idempotency key; this is not the server request identity. */
+    requestKey?: string;
+    target: JsonValue;
+    body: JsonValue;
+    responseSchema: ResponseSchema;
+    prompt?: string;
+    status: RequestStatus;
+    agentId?: string;
+    createdAt: string;
+    deadline: string;
+    dispatchAcceptedAt?: string;
+    answeredAt?: string;
+    closedAt?: string;
+    response?: JsonValue;
+    receipt?: ResponseReceipt;
+    error?: string;
+}
+export interface CreateRequestOptions {
+    /** Idempotency key scoped to ownerId + program; returned requestId is always a UUID. */
+    requestId?: string;
+    requestKey?: string;
+    target: JsonValue;
+    body: JsonValue;
+    responseSchema?: ResponseSchema;
+    prompt?: string;
+    timeoutMs?: number;
+}
+export interface RequestWaitOptions {
+    waitMs?: number;
+}
+export declare const REQUEST_LIMITS: Readonly<{
+    schemaBytes: number;
+    schemaDepth: 32;
+    /** Reserve four nesting levels for request/response and transport envelopes. */
+    payloadDepth: 28;
+    payloadNodes: 9900;
+    bodyBytes: number;
+    requestBytes: number;
+    promptBytes: number;
+    defaultTimeoutMs: 120000;
+    maxTimeoutMs: 3600000;
+    maxWaitMs: 30000;
+    pollMs: 50;
+    maxRequests: 10000;
+    maxPendingPerProgram: 128;
+    maxPending: 1024;
+}>;
+export declare const DEFAULT_RESPONSE_SCHEMA: ResponseSchema;
+export type ResponseValidator = (body: unknown) => void;
+/** Validate payloads before persistence, reserving depth and nodes for bridge framing. */
+export declare function assertRequestPayload(value: unknown): asserts value is JsonValue;
+/**
+ * Compile a real Draft 2020-12 schema. No coercion, default insertion, property
+ * removal, remote loading or format plugins. Unknown formats/keywords fail closed.
+ * Input/schema bounds constrain state, not CPU: trusted program regexes can still
+ * be expensive, and validation is not a sandbox or an execution time guarantee.
+ */
+export declare function createResponseValidator(schema?: ResponseSchema): ResponseValidator;

package/dist/requests.js

@@ -0,0 +1,120 @@
+import * as Ajv2020Module from 'ajv/dist/2020.js';
+import { assertJson, ProgramError } from './runtime/protocol.js';
+export const REQUEST_LIMITS = Object.freeze({
+    schemaBytes: 16 * 1024,
+    schemaDepth: 32,
+    /** Reserve four nesting levels for request/response and transport envelopes. */
+    payloadDepth: 28,
+    payloadNodes: 9900,
+    bodyBytes: 48 * 1024,
+    requestBytes: 56 * 1024,
+    promptBytes: 8 * 1024,
+    defaultTimeoutMs: 120_000,
+    maxTimeoutMs: 3_600_000,
+    maxWaitMs: 30_000,
+    pollMs: 50,
+    maxRequests: 10_000,
+    maxPendingPerProgram: 128,
+    maxPending: 1024,
+});
+export const DEFAULT_RESPONSE_SCHEMA = Object.freeze({ type: 'string' });
+/** Validate payloads before persistence, reserving depth and nodes for bridge framing. */
+export function assertRequestPayload(value) {
+    assertJson(value);
+    // assertJson has already excluded cycles, accessors, sparse arrays and non-JSON.
+    let nodes = 0;
+    const visit = (item, depth) => {
+        if (++nodes > REQUEST_LIMITS.payloadNodes || depth > REQUEST_LIMITS.payloadDepth)
+            throw new ProgramError('LIMIT', 'Request payload complexity exceeds framing-safe limits (depth 28, 9900 nodes)');
+        if (item && typeof item === 'object')
+            for (const child of Object.values(item))
+                visit(child, depth + 1);
+    };
+    visit(value, 0);
+}
+// Ajv is CommonJS in NodeNext. Both native ESM and TS runners expose one of these.
+const Ajv2020 = (Ajv2020Module.default ?? Ajv2020Module.Ajv2020);
+const schemaMaps = new Set(['$defs', 'definitions', 'properties', 'patternProperties', 'dependentSchemas']);
+const schemaArrays = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+const schemaChildren = new Set(['items', 'additionalProperties', 'contains', 'propertyNames', 'unevaluatedProperties', 'unevaluatedItems', 'not', 'if', 'then', 'else', 'contentSchema']);
+function safeMessage(value) {
+    let message;
+    try {
+        message = value instanceof Error ? value.message : String(value);
+    }
+    catch {
+        message = 'Validation failed';
+    }
+    return message.slice(0, 512).replace(/[\u0000-\u001f\u007f]/g, ' ');
+}
+function checkReferences(schema) {
+    if (typeof schema === 'boolean')
+        return;
+    for (const keyword of ['$ref', '$dynamicRef', '$recursiveRef']) {
+        const ref = schema[keyword];
+        if (ref !== undefined && (typeof ref !== 'string' || !ref.startsWith('#')))
+            throw new ProgramError('INVALID_SCHEMA', 'Only local fragment schema references are supported; remote references are not fetched');
+    }
+    if (schema.$async !== undefined)
+        throw new ProgramError('INVALID_SCHEMA', 'Asynchronous response schemas are not supported');
+    for (const [key, value] of Object.entries(schema)) {
+        if (schemaMaps.has(key) && value && typeof value === 'object' && !Array.isArray(value)) {
+            for (const child of Object.values(value))
+                if (typeof child === 'boolean' || child && typeof child === 'object' && !Array.isArray(child))
+                    checkReferences(child);
+        }
+        else if (schemaArrays.has(key) && Array.isArray(value)) {
+            for (const child of value)
+                if (typeof child === 'boolean' || child && typeof child === 'object' && !Array.isArray(child))
+                    checkReferences(child);
+        }
+        else if (schemaChildren.has(key) && (typeof value === 'boolean' || value && typeof value === 'object' && !Array.isArray(value)))
+            checkReferences(value);
+    }
+}
+/**
+ * Compile a real Draft 2020-12 schema. No coercion, default insertion, property
+ * removal, remote loading or format plugins. Unknown formats/keywords fail closed.
+ * Input/schema bounds constrain state, not CPU: trusted program regexes can still
+ * be expensive, and validation is not a sandbox or an execution time guarantee.
+ */
+export function createResponseValidator(schema = DEFAULT_RESPONSE_SCHEMA) {
+    let validate;
+    try {
+        assertJson(schema);
+        if (typeof schema !== 'boolean' && (!schema || typeof schema !== 'object' || Array.isArray(schema)))
+            throw new Error('Expected a JSON Schema object or boolean');
+        if (Buffer.byteLength(JSON.stringify(schema)) > REQUEST_LIMITS.schemaBytes)
+            throw new Error('Response schema exceeds 16 KiB');
+        // assertJson above enforces the shared depth-32 and finite JSON boundaries.
+        checkReferences(schema);
+        const ajv = new Ajv2020({ strict: true, allErrors: false, coerceTypes: false, removeAdditional: false, useDefaults: false, validateFormats: true, addUsedSchema: false });
+        validate = ajv.compile(JSON.parse(JSON.stringify(schema)));
+    }
+    catch (error) {
+        throw new ProgramError('INVALID_SCHEMA', `Invalid response schema: ${safeMessage(error)}`);
+    }
+    return (body) => {
+        try {
+            assertRequestPayload(body);
+            if (Buffer.byteLength(JSON.stringify(body)) > REQUEST_LIMITS.bodyBytes)
+                throw new Error('Response exceeds 48 KiB');
+        }
+        catch (error) {
+            throw new ProgramError('INVALID_RESPONSE', `Invalid response JSON: ${safeMessage(error)}`);
+        }
+        let valid;
+        try {
+            valid = validate(body);
+        }
+        catch (error) {
+            throw new ProgramError('INVALID_RESPONSE', `Response validation failed: ${safeMessage(error)}`);
+        }
+        if (!valid) {
+            const error = validate.errors?.[0];
+            const detail = error ? `${error.instancePath || '/'} ${error.message ?? 'does not match the response schema'}` : 'does not match the response schema';
+            throw new ProgramError('INVALID_RESPONSE', `Response ${safeMessage(detail)}`);
+        }
+    };
+}
+//# sourceMappingURL=requests.js.map

package/dist/requests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requests.js","sourceRoot":"","sources":["../src/requests.ts"],"names":[],"mappings":"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"}

package/dist/runtime/bootstrap.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/bootstrap.js

@@ -0,0 +1,25 @@
+import { pathToFileURL } from 'node:url';
+import { beginRegistration, ChildConnection, endRegistration } from '../sdk/connection.js';
+// This file is the fork target, not a general-purpose REPL. The supervisor alone
+// chooses this already-configured entrypoint; no code or identity comes from tools.
+const entry = process.argv[2];
+const connection = new ChildConnection();
+void connection.execute(async () => {
+    if (!entry)
+        throw new Error('Missing configured program entrypoint');
+    process.argv = [process.execPath, entry, ...process.argv.slice(3)];
+    const registration = beginRegistration();
+    try {
+        const module = await import(pathToFileURL(entry).href);
+        const main = module.default ?? registration.main;
+        if (module.default && registration.main)
+            throw new Error('Use either default main(ctx) or runProgram(main), not both');
+        if (typeof main !== 'function')
+            throw new Error('Program must export default main(ctx)');
+        return main;
+    }
+    finally {
+        endRegistration();
+    }
+});
+//# sourceMappingURL=bootstrap.js.map

package/dist/runtime/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/runtime/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG3F,iFAAiF;AACjF,oFAAoF;AACpF,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAC9B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;AACzC,KAAK,UAAU,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE;IACjC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IACrE,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,MAAM,YAAY,GAAG,iBAAiB,EAAE,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,MAAM,GAA8B,MAAM,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;QAClF,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC;QACjD,IAAI,MAAM,CAAC,OAAO,IAAI,YAAY,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;QACvH,IAAI,OAAO,IAAI,KAAK,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QACzF,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QAAC,eAAe,EAAE,CAAC;IAAC,CAAC;AAClC,CAAC,CAAC,CAAC"}

package/dist/runtime/definitions.d.ts

@@ -0,0 +1,7 @@
+import type { ProgramDefinition, ProgramResource, ProgramUrlDefinition } from '../types.js';
+export declare function normalizeResource(input: unknown, available?: boolean, requireType?: boolean): ProgramResource;
+/** Configured recipes retain metadata without evaluating a listener or browser hostname. */
+export declare function definitionResource(input: ProgramUrlDefinition): ProgramResource;
+/** Definitions execute trusted code, but config/metadata still have bounded exact shapes. */
+export declare function normalizeDefinition(program: string, input: ProgramDefinition): ProgramDefinition;
+export declare function definitionCommand(definition: ProgramDefinition): string[];

package/dist/runtime/definitions.js

@@ -0,0 +1,138 @@
+import { isAbsolute, resolve } from 'node:path';
+import { endpointName, normalizeEndpointPath } from '../endpoints.js';
+import { normalizeSupervision } from '../supervision.js';
+import { exactKeys, isRecord, ProgramError, RUNTIME_LIMITS, validName } from './protocol.js';
+const controls = /[\u0000-\u001f\u007f]/;
+/** Paths are informational descriptors; callers must never turn them into file:// links. */
+function location(value, allowPath) {
+    if (typeof value !== 'string' || !value || value.length > 4096 || controls.test(value))
+        throw new ProgramError('INVALID_URL', 'Resource location must be a bounded HTTP(S) URL or documentation path');
+    if (allowPath && isAbsolute(value))
+        return value;
+    if (!/^https?:\/\//i.test(value) || /\s/.test(value))
+        throw new ProgramError('INVALID_URL', 'Resource URL must be explicit HTTP(S) without whitespace or controls');
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new ProgramError('INVALID_URL', 'Resource URL must be absolute HTTP(S)');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+        throw new ProgramError('INVALID_URL', 'Only HTTP(S) links without credentials may be published');
+    return url.href;
+}
+export function normalizeResource(input, available = false, requireType = false) {
+    if (!isRecord(input) || !exactKeys(input, ['id', 'title', 'url'], ['type', 'docs']) || !validName(input.id) || typeof input.title !== 'string' || input.title.length > 256 || (requireType && input.type === undefined) || (input.type !== undefined && !['ui', 'api', 'docs'].includes(input.type)))
+        throw new ProgramError('INVALID_INPUT', 'Invalid resource');
+    return {
+        id: input.id,
+        title: input.title,
+        url: location(input.url, input.type === 'docs'),
+        ...(input.type === undefined ? {} : { type: input.type }),
+        ...(input.docs === undefined ? {} : { docs: location(input.docs, true) }),
+        available,
+    };
+}
+/** Configured recipes retain metadata without evaluating a listener or browser hostname. */
+export function definitionResource(input) {
+    if (input.endpoint === undefined)
+        return normalizeResource(input);
+    return {
+        id: input.id, title: input.title, type: input.type, url: '',
+        endpoint: input.endpoint, path: input.path ?? '/',
+        ...(input.docs === undefined ? {} : { docs: input.docs }), available: false,
+    };
+}
+function normalizeUrlDefinition(input, endpoints) {
+    if (!isRecord(input) || !exactKeys(input, ['id', 'title', 'type'], ['url', 'endpoint', 'path', 'docs']))
+        throw new ProgramError('INVALID_INPUT', 'Invalid configured resource');
+    if (input.url !== undefined) {
+        if (Object.hasOwn(input, 'endpoint') || Object.hasOwn(input, 'path'))
+            throw new ProgramError('INVALID_INPUT', 'Resource requires a literal URL or an endpoint recipe, not both');
+        const { available: _, ...resource } = normalizeResource(input, false, true);
+        return resource;
+    }
+    if (Object.hasOwn(input, 'url') || !validName(input.id) || typeof input.title !== 'string' || input.title.length > 256 || !['ui', 'api', 'docs'].includes(input.type) || !endpointName(input.endpoint) || !Object.hasOwn(endpoints, input.endpoint))
+        throw new ProgramError('INVALID_INPUT', 'Resource recipe must reference a configured endpoint');
+    return {
+        id: input.id, title: input.title, type: input.type,
+        endpoint: input.endpoint, path: normalizeEndpointPath(input.path),
+        ...(input.docs === undefined ? {} : { docs: location(input.docs, true) }),
+    };
+}
+/** Definitions execute trusted code, but config/metadata still have bounded exact shapes. */
+export function normalizeDefinition(program, input) {
+    if (!validName(program) || !isRecord(input) || !exactKeys(input, [], ['entry', 'command', 'name', 'description', 'urls', 'endpoints', 'logsPath', 'cwd', 'args', 'env', 'allowedCapabilities', 'supervision']))
+        throw new ProgramError('INVALID_CONFIG', 'Invalid program definition');
+    const entry = input.entry;
+    const command = input.command;
+    if ((entry === undefined) === (command === undefined))
+        throw new ProgramError('INVALID_CONFIG', 'Program requires exactly one of entry or command');
+    const text = (value, max, empty = false) => typeof value === 'string' && (empty || value.length > 0) && value.length <= max && !value.includes('\0');
+    const argv = (value) => Array.isArray(value) && value.length <= 256 && Array.from(value).every((item) => text(item, 8192, true)) && Buffer.byteLength(JSON.stringify(value)) <= 64 * 1024;
+    if (entry !== undefined && !text(entry, 4096))
+        throw new ProgramError('INVALID_CONFIG', 'Invalid program entrypoint');
+    if (command !== undefined && (!argv(command) || !command.length || !command[0]))
+        throw new ProgramError('INVALID_CONFIG', 'Command must be a nonempty executable argv array');
+    if (input.args !== undefined && (!argv(input.args) || command !== undefined))
+        throw new ProgramError('INVALID_CONFIG', 'args is only supported with an SDK entrypoint; command already contains argv');
+    if (input.cwd !== undefined && !text(input.cwd, 4096))
+        throw new ProgramError('INVALID_CONFIG', 'Invalid program working directory');
+    if (input.name !== undefined && !text(input.name, 256))
+        throw new ProgramError('INVALID_CONFIG', 'Invalid program name');
+    if (input.description !== undefined && !text(input.description, 4096, true))
+        throw new ProgramError('INVALID_CONFIG', 'Invalid program description');
+    if (input.logsPath !== undefined && (!text(input.logsPath, 4096) || controls.test(input.logsPath)))
+        throw new ProgramError('INVALID_CONFIG', 'Invalid log path');
+    if (input.env !== undefined && (!isRecord(input.env) || Object.keys(input.env).length > 256 || Object.entries(input.env).some(([key, value]) => !key || key.includes('=') || key.includes('\0') || !text(value, 8192, true)) || Buffer.byteLength(JSON.stringify(input.env)) > 64 * 1024))
+        throw new ProgramError('INVALID_CONFIG', 'Invalid explicit program environment');
+    const reserved = new Set(['capabilities.list', 'parent.send', 'status.set', 'resources.publish', 'resources.unpublish']);
+    if (input.allowedCapabilities !== undefined && (!Array.isArray(input.allowedCapabilities) || input.allowedCapabilities.length > 256 || input.allowedCapabilities.some((capability) => !validName(capability) || reserved.has(capability))))
+        throw new ProgramError('INVALID_CONFIG', 'Invalid capability allowlist');
+    if (input.urls !== undefined && (!Array.isArray(input.urls) || input.urls.length > RUNTIME_LIMITS.resources))
+        throw new ProgramError('INVALID_CONFIG', 'Invalid static resource list');
+    if (input.endpoints !== undefined && (!isRecord(input.endpoints) || Object.keys(input.endpoints).length > 16))
+        throw new ProgramError('INVALID_CONFIG', 'At most 16 named endpoints may be configured');
+    const endpoints = {};
+    for (const [id, endpoint] of Object.entries(input.endpoints ?? {})) {
+        if (!endpointName(id) || !isRecord(endpoint) || !exactKeys(endpoint, ['port']) || (endpoint.port !== 'dynamic' && (!Number.isSafeInteger(endpoint.port) || endpoint.port < 1 || endpoint.port > 65535)))
+            throw new ProgramError('INVALID_CONFIG', 'Endpoint requires a bounded name and dynamic or fixed port (1–65535)');
+        endpoints[id] = { port: endpoint.port };
+    }
+    const urls = [];
+    try {
+        for (const item of input.urls ?? []) {
+            const resource = normalizeUrlDefinition(item, endpoints);
+            if (urls.some((other) => other.id === resource.id))
+                throw new ProgramError('INVALID_CONFIG', 'Duplicate static resource id');
+            urls.push(resource);
+        }
+    }
+    catch (error) {
+        throw new ProgramError('INVALID_CONFIG', error instanceof Error ? error.message : 'Invalid static resource');
+    }
+    const cwd = resolve(input.cwd ?? process.cwd());
+    let supervision;
+    try {
+        supervision = normalizeSupervision(input.supervision);
+    }
+    catch (error) {
+        throw new ProgramError('INVALID_CONFIG', error instanceof Error ? error.message : 'Invalid supervision settings');
+    }
+    return {
+        ...input,
+        cwd,
+        ...(entry === undefined ? { command: [...command] } : { entry: resolve(cwd, entry), args: [...(input.args ?? [])] }),
+        env: { ...input.env },
+        allowedCapabilities: [...new Set(input.allowedCapabilities ?? [])],
+        urls,
+        ...(input.endpoints === undefined ? {} : { endpoints }),
+        ...(supervision === undefined ? {} : { supervision }),
+        ...(input.logsPath === undefined ? {} : { logsPath: resolve(cwd, input.logsPath) }),
+    };
+}
+export function definitionCommand(definition) {
+    return definition.command ? [...definition.command] : [process.execPath, definition.entry, ...(definition.args ?? [])];
+}
+//# sourceMappingURL=definitions.js.map