operon-agents 0.1.0-alpha.0

package/dist/app-server/server.js

@@ -0,0 +1,274 @@
+import { errorToBody, failure, notification, request as makeRequest, RpcError, success, toWireSafe, } from "./codec.js";
+import { ErrorCode, INVOKABLE_METHODS, Method, PROTOCOL_VERSION, } from "./protocol.js";
+const INVOKABLE = new Set(INVOKABLE_METHODS);
+export class AppServer {
+    harness;
+    transport;
+    serverInfo;
+    log;
+    initialized = false;
+    clientApproval = false;
+    clientQuestion = false;
+    wired = new Map();
+    reversePending = new Map();
+    reverseSeq = 0;
+    constructor(opts) {
+        this.harness = opts.harness;
+        this.transport = opts.transport;
+        this.serverInfo = opts.serverInfo ?? { name: "operon-app-server", version: "0.0.0" };
+        this.log = opts.log ?? (() => undefined);
+    }
+    /** Run the dispatch loop until the transport closes. */
+    async serve() {
+        for await (const message of this.transport.incoming()) {
+            // Fire-and-forget: a long-running `session/prompt` must not block reading the
+            // next message (cancel / steer / reverse-RPC answers arrive concurrently).
+            void this.handleMessage(message);
+        }
+        await this.shutdown();
+    }
+    async shutdown() {
+        for (const pending of this.reversePending.values()) {
+            pending.reject(new RpcError(ErrorCode.RequestCancelled, "transport closed"));
+        }
+        this.reversePending.clear();
+        for (const { unsubscribe } of this.wired.values())
+            unsubscribe();
+        this.wired.clear();
+        await this.harness.close();
+    }
+    // ── Dispatch ────────────────────────────────────────────────────────────────
+    async handleMessage(message) {
+        if (typeof message !== "object" || message === null)
+            return;
+        const m = message;
+        const hasMethod = typeof m.method === "string";
+        const hasId = typeof m.id === "string" || typeof m.id === "number";
+        // A response (no method, has id) is the host answering one of our reverse requests.
+        if (!hasMethod && hasId) {
+            this.resolveReverse(message);
+            return;
+        }
+        if (hasMethod && hasId) {
+            await this.handleRequest(message);
+            return;
+        }
+        if (hasMethod) {
+            this.handleNotification(m.method, m.params);
+            return;
+        }
+    }
+    async handleRequest(req) {
+        try {
+            const result = await this.route(req.method, req.params);
+            this.transport.send(success(req.id, toWireSafe(result)));
+        }
+        catch (error) {
+            this.transport.send(failure(req.id, errorToBody(error)));
+        }
+    }
+    handleNotification(method, params) {
+        // The host can tell us it dropped its end (rare); nothing else expected inbound.
+        this.log(`ignoring notification: ${method}${params === undefined ? "" : ""}`);
+    }
+    async route(method, params) {
+        if (method === Method.Initialize)
+            return this.onInitialize(params);
+        if (!this.initialized)
+            throw new RpcError(ErrorCode.NotInitialized, "call initialize first");
+        switch (method) {
+            case Method.SessionNew:
+                return this.onSessionNew((params ?? {}));
+            case Method.SessionResume:
+                return this.onSessionResume(params);
+            case Method.SessionFork:
+                return this.onSessionFork(params);
+            case Method.SessionList:
+                return this.harness.listSessions();
+            case Method.SessionClose:
+                return this.onSessionClose(params);
+            case Method.SessionPrompt:
+                return this.onSessionPrompt(params);
+            case Method.SessionSnapshot:
+                return this.onSessionSnapshot(params);
+            case Method.SessionRespond:
+                return this.onSessionRespond(params);
+            case Method.SessionSteer:
+                return this.onSessionSteer(params);
+            case Method.SessionFollowUp:
+                return this.onSessionFollowUp(params);
+            case Method.SessionCancel:
+                return this.onSessionCancel(params);
+            case Method.SessionInvoke:
+                return this.onSessionInvoke(params);
+            default:
+                throw new RpcError(ErrorCode.MethodNotFound, `unknown method: ${method}`);
+        }
+    }
+    // ── Handshake ─────────────────────────────────────────────────────────────
+    onInitialize(params) {
+        if (typeof params?.protocolVersion !== "number") {
+            throw new RpcError(ErrorCode.InvalidParams, "protocolVersion (number) required");
+        }
+        this.clientApproval = params.clientCapabilities?.approval ?? false;
+        this.clientQuestion = params.clientCapabilities?.question ?? false;
+        this.initialized = true;
+        return {
+            protocolVersion: PROTOCOL_VERSION,
+            serverInfo: this.serverInfo,
+            permissionModes: ["manual", "workspace", "yolo"],
+            invokableMethods: INVOKABLE_METHODS,
+        };
+    }
+    // ── Fleet ───────────────────────────────────────────────────────────────────
+    async onSessionNew(params) {
+        const session = await this.harness.createSession({
+            ...(params.workDir !== undefined ? { workDir: params.workDir } : {}),
+            ...(params.title !== undefined ? { title: params.title } : {}),
+        });
+        if (params.model !== undefined)
+            session.setModel(params.model);
+        this.wireSession(session);
+        return { sessionId: session.id, workDir: session.workDir };
+    }
+    async onSessionResume(params) {
+        const session = await this.harness.resumeSession(this.requireId(params));
+        this.wireSession(session);
+        return { sessionId: session.id, workDir: session.workDir };
+    }
+    async onSessionFork(params) {
+        const session = await this.harness.forkSession(this.requireId(params), {
+            ...(params.title !== undefined ? { title: params.title } : {}),
+        });
+        this.wireSession(session);
+        return { sessionId: session.id, workDir: session.workDir };
+    }
+    async onSessionClose(params) {
+        const id = this.requireId(params);
+        this.wired.get(id)?.unsubscribe();
+        this.wired.delete(id);
+        this.rejectReverseForSession(id, "session closed");
+        await this.harness.closeSession(id);
+        return {};
+    }
+    // ── Run driving ─────────────────────────────────────────────────────────────
+    async onSessionPrompt(params) {
+        const session = this.requireSession(params);
+        // Returns when the run completes; events stream meanwhile. Concurrent prompts
+        // queue on the session's run lock (one run at a time) and each gets its own reply.
+        return session.prompt(params.input);
+    }
+    onSessionSnapshot(params) {
+        const session = this.requireSession(params);
+        // Synchronous on purpose: the response is written into the same ordered stdout stream
+        // as `session/event` notifications, so events notified before it are in the snapshot
+        // and events after it are not — the exact-seam contract documented on the protocol type.
+        return session.snapshot({
+            ...(params.addresses !== undefined ? { addresses: params.addresses } : {}),
+            ...(params.maxMessages !== undefined ? { maxMessages: params.maxMessages } : {}),
+        });
+    }
+    async onSessionRespond(params) {
+        const session = this.requireSession(params);
+        // Continue a run that durably interrupted for approval: apply the answers and resume.
+        // Like prompt, resolves when the run reaches its next stop (which may interrupt again).
+        return session.resume(params.answers);
+    }
+    onSessionSteer(params) {
+        const session = this.requireSession(params);
+        return { accepted: true, steerId: session.steer(params.text) };
+    }
+    onSessionFollowUp(params) {
+        const session = this.requireSession(params);
+        const steerId = session.followUp(params.text);
+        return steerId === null ? { accepted: false } : { accepted: true, steerId };
+    }
+    onSessionCancel(params) {
+        const session = this.requireSession(params);
+        session.cancel();
+        // Any in-flight approval/question for this session can never be answered now.
+        this.rejectReverseForSession(session.id, "run cancelled");
+        return {};
+    }
+    async onSessionInvoke(params) {
+        const session = this.requireSession(params);
+        if (typeof params.method !== "string" || !INVOKABLE.has(params.method)) {
+            throw new RpcError(ErrorCode.MethodNotFound, `not invokable: ${String(params.method)}`);
+        }
+        const fn = session[params.method];
+        if (typeof fn !== "function") {
+            throw new RpcError(ErrorCode.MethodNotFound, `not a method: ${params.method}`);
+        }
+        const args = Array.isArray(params.args) ? params.args : [];
+        const value = await fn.apply(session, args);
+        return { value: toWireSafe(value) };
+    }
+    // ── Per-session wiring: events out, reverse-RPC for approvals/questions ──────
+    wireSession(session) {
+        if (this.wired.has(session.id))
+            return;
+        const unsubscribe = session.onEvent((event) => {
+            this.transport.send(notification(Method.SessionEvent, event));
+        });
+        if (this.clientApproval) {
+            session.setApprovalHandler((req) => this.callClient(Method.ClientRequestApproval, session.id, { sessionId: session.id, request: req }));
+        }
+        if (this.clientQuestion) {
+            session.setQuestionHandler((req, options) => this.callClient(Method.ClientRequestQuestion, session.id, { sessionId: session.id, request: req }, options?.signal));
+        }
+        this.wired.set(session.id, { session, unsubscribe });
+    }
+    // ── Reverse-RPC (server → host request) ─────────────────────────────────────
+    callClient(method, sessionId, params, signal) {
+        if (signal?.aborted)
+            return Promise.reject(new RpcError(ErrorCode.RequestCancelled, "already aborted"));
+        const id = `rev-${++this.reverseSeq}`;
+        return new Promise((resolve, reject) => {
+            this.reversePending.set(id, { sessionId, resolve, reject });
+            if (signal) {
+                const onAbort = () => {
+                    if (!this.reversePending.has(id))
+                        return;
+                    this.reversePending.delete(id);
+                    this.transport.send(notification(Method.ClientCancelRequest, { id }));
+                    reject(new RpcError(ErrorCode.RequestCancelled, "cancelled"));
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            this.transport.send(makeRequest(id, method, params));
+        });
+    }
+    resolveReverse(response) {
+        const pending = this.reversePending.get(response.id);
+        if (!pending)
+            return;
+        this.reversePending.delete(response.id);
+        if ("error" in response)
+            pending.reject(new RpcError(response.error.code, response.error.message, response.error.data));
+        else
+            pending.resolve(response.result);
+    }
+    rejectReverseForSession(sessionId, reason) {
+        for (const [id, pending] of this.reversePending) {
+            if (pending.sessionId !== sessionId)
+                continue;
+            this.reversePending.delete(id);
+            this.transport.send(notification(Method.ClientCancelRequest, { id }));
+            pending.reject(new RpcError(ErrorCode.RequestCancelled, reason));
+        }
+    }
+    // ── Helpers ──────────────────────────────────────────────────────────────────
+    requireId(ref) {
+        if (!ref || typeof ref.sessionId !== "string")
+            throw new RpcError(ErrorCode.InvalidParams, "sessionId required");
+        return ref.sessionId;
+    }
+    requireSession(ref) {
+        const id = this.requireId(ref);
+        const session = this.harness.getSession(id);
+        if (!session)
+            throw new RpcError(ErrorCode.SessionNotFound, `session not found: ${id}`);
+        return session;
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/core.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Mode 1 — low-level primitives (the engine, assemble-it-yourself).
+ *
+ * `import { Runner, defineAgent, defineModel } from 'operon-agents/core'`
+ *
+ * Everything the core engine exposes: Runner / Session / Agent / capabilities /
+ * machines / tools. Pass no machine and omit file tools to run a stateless,
+ * no-filesystem agent (a `NullMachine` refuses any stray I/O). For the
+ * batteries-included facade, import from `operon-agents` instead.
+ */
+export * from "operon-agents-core";
+//# sourceMappingURL=core.d.ts.map

package/dist/core.js

@@ -0,0 +1,12 @@
+/**
+ * Mode 1 — low-level primitives (the engine, assemble-it-yourself).
+ *
+ * `import { Runner, defineAgent, defineModel } from 'operon-agents/core'`
+ *
+ * Everything the core engine exposes: Runner / Session / Agent / capabilities /
+ * machines / tools. Pass no machine and omit file tools to run a stateless,
+ * no-filesystem agent (a `NullMachine` refuses any stray I/O). For the
+ * batteries-included facade, import from `operon-agents` instead.
+ */
+export * from "operon-agents-core";
+//# sourceMappingURL=core.js.map

package/dist/cron/clock.d.ts

@@ -0,0 +1,11 @@
+export interface ClockSources {
+    wallNow(): number;
+    monoNowMs(): number;
+}
+export declare const SYSTEM_CLOCKS: ClockSources;
+export interface MutableClock extends ClockSources {
+    set(ms: number): void;
+    advance(deltaMs: number): void;
+}
+export declare function mutableClock(initialMs: number): MutableClock;
+//# sourceMappingURL=clock.d.ts.map

package/dist/cron/clock.js

@@ -0,0 +1,19 @@
+const systemMonoNowMs = () => Number(process.hrtime.bigint() / 1000000n);
+export const SYSTEM_CLOCKS = {
+    wallNow: () => Date.now(),
+    monoNowMs: systemMonoNowMs,
+};
+export function mutableClock(initialMs) {
+    let wall = initialMs;
+    return {
+        wallNow: () => wall,
+        monoNowMs: systemMonoNowMs,
+        set: (ms) => {
+            wall = ms;
+        },
+        advance: (deltaMs) => {
+            wall += deltaMs;
+        },
+    };
+}
+//# sourceMappingURL=clock.js.map

package/dist/cron/cron-expr.d.ts

@@ -0,0 +1,15 @@
+export interface ParsedCronExpression {
+    readonly raw: string;
+    readonly minutes: ReadonlySet<number>;
+    readonly hours: ReadonlySet<number>;
+    readonly daysOfMonth: ReadonlySet<number>;
+    readonly months: ReadonlySet<number>;
+    readonly daysOfWeek: ReadonlySet<number>;
+    readonly daysOfMonthWildcard: boolean;
+    readonly daysOfWeekWildcard: boolean;
+}
+export declare function parseCronExpression(expr: string): ParsedCronExpression;
+export declare function computeNextCronRun(expr: ParsedCronExpression, fromMs: number): number | null;
+export declare function hasFireWithinYears(expr: ParsedCronExpression, years: number, fromMs: number): boolean;
+export declare function cronToHuman(expr: ParsedCronExpression): string;
+//# sourceMappingURL=cron-expr.d.ts.map

package/dist/cron/cron-expr.js

@@ -0,0 +1,267 @@
+const MINUTE_RANGE = { min: 0, max: 59 };
+const HOUR_RANGE = { min: 0, max: 23 };
+const DOM_RANGE = { min: 1, max: 31 };
+const MONTH_RANGE = { min: 1, max: 12 };
+const DOW_RANGE = { min: 0, max: 7 }; // 7 → 0 fold after parse
+const MS_PER_MINUTE = 60_000;
+export function parseCronExpression(expr) {
+    if (typeof expr !== "string")
+        throw new TypeError("cron expression must be a string");
+    const trimmed = expr.trim();
+    if (trimmed === "")
+        throw new Error("cron expression is empty");
+    const fields = trimmed.split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error(`cron expression must have exactly 5 fields (minute hour day-of-month month day-of-week); got ${fields.length}`);
+    }
+    const [minField, hourField, domField, monthField, dowField] = fields;
+    const minutes = parseField(minField, MINUTE_RANGE.min, MINUTE_RANGE.max, "minute");
+    const hours = parseField(hourField, HOUR_RANGE.min, HOUR_RANGE.max, "hour");
+    const daysOfMonth = parseField(domField, DOM_RANGE.min, DOM_RANGE.max, "day-of-month");
+    const months = parseField(monthField, MONTH_RANGE.min, MONTH_RANGE.max, "month");
+    const dowRaw = parseField(dowField, DOW_RANGE.min, DOW_RANGE.max, "day-of-week");
+    const daysOfWeek = new Set();
+    for (const v of dowRaw)
+        daysOfWeek.add(v === 7 ? 0 : v);
+    return {
+        raw: trimmed,
+        minutes,
+        hours,
+        daysOfMonth,
+        months,
+        daysOfWeek,
+        daysOfMonthWildcard: isWildcard(domField),
+        daysOfWeekWildcard: isWildcard(dowField),
+    };
+}
+function isWildcard(field) {
+    // Only bare `*` suppresses the dom/dow OR rule; `*/n` is a restriction (cron tradition).
+    return field === "*";
+}
+function parseField(field, min, max, name) {
+    if (field === "")
+        throw new Error(`cron ${name} field is empty`);
+    const out = new Set();
+    for (const term of field.split(",")) {
+        if (term === "")
+            throw new Error(`cron ${name} field has empty term in list`);
+        addTerm(out, term, min, max, name);
+    }
+    if (out.size === 0)
+        throw new Error(`cron ${name} field matches no values`);
+    return out;
+}
+// Cron numeric fields are digit-only; `Number(...)` would otherwise accept '', '1e1',
+// '0x10', '+5', '  3  ' — none valid cron. Gate before conversion to machine typos.
+const DIGIT_ONLY = /^\d+$/;
+function parseCronInt(raw, name, role) {
+    if (!DIGIT_ONLY.test(raw)) {
+        throw new Error(`cron ${name} ${role} must be a non-negative integer with digits only (got ${JSON.stringify(raw)})`);
+    }
+    return Number.parseInt(raw, 10);
+}
+function addTerm(out, term, min, max, name) {
+    let rangePart = term;
+    let step = 1;
+    const slash = term.indexOf("/");
+    if (slash !== -1) {
+        rangePart = term.slice(0, slash);
+        const stepStr = term.slice(slash + 1);
+        if (stepStr === "")
+            throw new Error(`cron ${name} step is empty in "${term}"`);
+        const parsedStep = parseCronInt(stepStr, name, "step");
+        if (parsedStep <= 0)
+            throw new Error(`cron ${name} step must be a positive integer (got "${stepStr}")`);
+        step = parsedStep;
+        if (rangePart === "")
+            throw new Error(`cron ${name} step needs a range or "*" before "/" in "${term}"`);
+    }
+    let lo;
+    let hi;
+    if (rangePart === "*") {
+        lo = min;
+        hi = max;
+    }
+    else {
+        const dash = rangePart.indexOf("-");
+        if (dash === -1) {
+            const single = parseCronInt(rangePart, name, "value");
+            if (single < min || single > max)
+                throw new Error(`cron ${name} value ${single} out of range ${min}..${max}`);
+            // A bare single value with a step (`5/10`) = "from value through max stepping by N".
+            if (slash !== -1) {
+                lo = single;
+                hi = max;
+            }
+            else {
+                out.add(single);
+                return;
+            }
+        }
+        else {
+            const loStr = rangePart.slice(0, dash);
+            const hiStr = rangePart.slice(dash + 1);
+            lo = parseCronInt(loStr, name, "range lower bound");
+            hi = parseCronInt(hiStr, name, "range upper bound");
+            if (lo < min || hi > max || lo > hi) {
+                throw new Error(`cron ${name} range ${lo}-${hi} out of bounds (must be ${min}..${max}, ascending)`);
+            }
+        }
+    }
+    for (let v = lo; v <= hi; v += step)
+        out.add(v);
+}
+export function computeNextCronRun(expr, fromMs) {
+    return nextRunWithinMinutes(expr, fromMs, 5 * 366 * 24 * 60);
+}
+export function hasFireWithinYears(expr, years, fromMs) {
+    const cap = Math.max(1, Math.floor(years * 366 * 24 * 60));
+    return nextRunWithinMinutes(expr, fromMs, cap) !== null;
+}
+function nextRunWithinMinutes(expr, fromMs, capMinutes) {
+    // Seek strictly into the next minute so we never return `fromMs` itself.
+    const start = new Date(fromMs);
+    start.setSeconds(0, 0);
+    const date = new Date(start.getTime() + MS_PER_MINUTE);
+    const deadlineMs = fromMs + capMinutes * MS_PER_MINUTE;
+    let iterations = 0;
+    const HARD_ITERATION_CAP = 10_000_000;
+    while (date.getTime() <= deadlineMs && iterations++ < HARD_ITERATION_CAP) {
+        if (!expr.months.has(date.getMonth() + 1)) {
+            advanceMonth(date);
+            continue;
+        }
+        if (!dayMatches(expr, date)) {
+            advanceDay(date);
+            continue;
+        }
+        if (!expr.hours.has(date.getHours())) {
+            advanceHour(date);
+            continue;
+        }
+        if (!expr.minutes.has(date.getMinutes())) {
+            advanceMinute(date);
+            continue;
+        }
+        return date.getTime();
+    }
+    return null;
+}
+function dayMatches(expr, date) {
+    const domOk = expr.daysOfMonth.has(date.getDate());
+    const dowOk = expr.daysOfWeek.has(date.getDay());
+    if (expr.daysOfMonthWildcard && expr.daysOfWeekWildcard)
+        return true;
+    if (expr.daysOfMonthWildcard)
+        return dowOk;
+    if (expr.daysOfWeekWildcard)
+        return domOk;
+    return domOk || dowOk; // both restricted → cron-style OR
+}
+function advanceMonth(date) {
+    date.setDate(1);
+    date.setHours(0, 0, 0, 0);
+    date.setMonth(date.getMonth() + 1);
+}
+function advanceDay(date) {
+    date.setHours(0, 0, 0, 0);
+    date.setDate(date.getDate() + 1);
+}
+function advanceHour(date) {
+    date.setMinutes(0, 0, 0);
+    date.setHours(date.getHours() + 1);
+}
+function advanceMinute(date) {
+    date.setSeconds(0, 0);
+    date.setMinutes(date.getMinutes() + 1);
+}
+const MONTH_NAMES = [
+    "January", "February", "March", "April", "May", "June",
+    "July", "August", "September", "October", "November", "December",
+];
+const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+export function cronToHuman(expr) {
+    const allMin = isFullRange(expr.minutes, 0, 59);
+    const allHour = isFullRange(expr.hours, 0, 23);
+    const allDom = expr.daysOfMonthWildcard;
+    const allMonth = isFullRange(expr.months, 1, 12);
+    const allDow = expr.daysOfWeekWildcard;
+    if (allHour && allDom && allMonth && allDow) {
+        const step = detectStep(expr.minutes, 0, 59);
+        if (step !== null && step > 1)
+            return `every ${step} minutes`;
+        if (allMin)
+            return "every minute";
+        if (expr.minutes.size === 1)
+            return `at minute ${[...expr.minutes][0]} of every hour`;
+    }
+    if (expr.minutes.size === 1 && allDom && allMonth && allDow) {
+        const m = [...expr.minutes][0];
+        const step = detectStep(expr.hours, 0, 23);
+        if (step !== null && step > 1)
+            return `every ${step} hours at minute ${pad(m)}`;
+    }
+    if (expr.minutes.size === 1 && expr.hours.size === 1 && allDom && allMonth) {
+        const h = [...expr.hours][0];
+        const m = [...expr.minutes][0];
+        if (allDow)
+            return `at ${pad(h)}:${pad(m)} every day`;
+        const dowStr = formatDows(expr.daysOfWeek);
+        if (dowStr !== null)
+            return `at ${pad(h)}:${pad(m)} on ${dowStr}`;
+    }
+    if (expr.minutes.size === 1 &&
+        expr.hours.size === 1 &&
+        expr.daysOfMonth.size === 1 &&
+        !expr.daysOfMonthWildcard &&
+        expr.months.size === 1 &&
+        allDow) {
+        const h = [...expr.hours][0];
+        const m = [...expr.minutes][0];
+        const d = [...expr.daysOfMonth][0];
+        const mo = [...expr.months][0];
+        return `at ${pad(h)}:${pad(m)} on day ${d} of ${MONTH_NAMES[mo - 1]}`;
+    }
+    return expr.raw;
+}
+function isFullRange(set, min, max) {
+    if (set.size !== max - min + 1)
+        return false;
+    for (let v = min; v <= max; v++)
+        if (!set.has(v))
+            return false;
+    return true;
+}
+function detectStep(set, min, max) {
+    const values = [...set].toSorted((a, b) => a - b);
+    if (values.length < 2)
+        return null;
+    if (values[0] !== min)
+        return null;
+    const step = values[1] - values[0];
+    if (step <= 0)
+        return null;
+    let expected = min;
+    for (const v of values) {
+        if (v !== expected)
+            return null;
+        expected += step;
+    }
+    if (expected - step > max)
+        return null;
+    return step;
+}
+function formatDows(set) {
+    const values = [...set].toSorted((a, b) => a - b);
+    if (values.length === 0)
+        return null;
+    if (values.length === 5 && values.every((v, i) => v === i + 1))
+        return "weekdays";
+    if (values.length === 2 && values[0] === 0 && values[1] === 6)
+        return "weekends";
+    return values.map((v) => DAY_NAMES[v]).join(", ");
+}
+function pad(n) {
+    return n < 10 ? `0${n}` : String(n);
+}
+//# sourceMappingURL=cron-expr.js.map

package/dist/cron/extension.d.ts

@@ -0,0 +1,25 @@
+/**
+ * cron as an EXTENSION — the first capability migrated out of the engine. It rides the four
+ * generic seams (registerCommand / emitEvent / expose / state, plus steer metadata), so a host
+ * gets `/cron`, cron events and a programmatic handle by ATTACHING it — no wiring. The local
+ * deployment profile attaches it; a server host simply doesn't, which makes Invariant 7
+ * ("cron is local-only") structural instead of an option someone must remember to pass.
+ */
+import type { ExtensionDefinition } from "../extensions/types.ts";
+import { CronManager, type CronManagerOptions } from "./manager.ts";
+import type { SessionCronTaskInit } from "./session-store.ts";
+import type { CronTask } from "./types.ts";
+/** The host-facing control surface (`session.extensionHandle<CronHandle>("cron")`) — what the
+ *  old `session.createCronTask/…` facade became. */
+export interface CronHandle {
+    addTask(input: SessionCronTaskInit): CronTask;
+    listTasks(): readonly CronTask[];
+    removeTask(id: string): boolean;
+    tick(): void;
+    getNextFireTime(taskId?: string): number | null;
+}
+/** Host-path validation (the tools carry their own): trims/caps the input, refuses expressions
+ *  that never fire within 5 years, enforces the per-session job cap. */
+export declare function normalizeCronTaskInput(manager: CronManager, input: SessionCronTaskInit): SessionCronTaskInit;
+export declare function cronExtension(options?: CronManagerOptions): ExtensionDefinition;
+//# sourceMappingURL=extension.d.ts.map