@autonome-research/thread-phase 3.0.0

package/dist/helpers/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/helpers/hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAIjG,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,QAAQ;IACvB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAmCD,wEAAwE;AACxE,wBAAgB,wBAAwB,IAAI,IAAI,CAQ/C;AA8DD,qBAAa,WAAY,YAAW,OAAO,CAAC,OAAO,CAAC;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAGN;IACR,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;gBAE9C,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAQhE;;;OAGG;IACG,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAe/C;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAOtD,6DAA6D;IAC7D,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI;IAO1C,KAAK,IAAI,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;IAerD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAYb,mBAAmB;CAgBlC;AAMD,wBAAgB,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EACrD,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,EACtC,OAAO,GAAE,WAAgB,GACxB,mBAAmB,CAqDrB"}

package/dist/helpers/hook.js

@@ -0,0 +1,244 @@
+/**
+ * `hook` — register a pipeline driven by an inbound HTTP webhook.
+ *
+ *   export default hook({ path: '/webhook/digest' }, async (payload, ctx) => {
+ *     return { ok: true, processed: payload };
+ *   });
+ *
+ * The library maintains one `node:http` server per project — every `hook`
+ * registration adds a new route to the same server. The server starts
+ * lazily on the first `Trigger.start()`. Routes resolve by exact path
+ * match; only POST with a JSON body is supported in v3.0.0.
+ *
+ * The handler is called with the parsed JSON body and ctx. Its return
+ * value is JSON-serialized and sent back as the HTTP response body
+ * (status 200). Throws produce status 500 with `{ error: message }`.
+ *
+ * Server port: `process.env.THREAD_PHASE_HTTP_PORT` if set, else 7777.
+ */
+import { createServer } from 'node:http';
+import { PipelineCache } from '../cache.js';
+import { deriveNameFromCaller } from './caller.js';
+let shared;
+function getSharedServer() {
+    if (shared)
+        return shared;
+    const port = Number(process.env.THREAD_PHASE_HTTP_PORT ?? 7777);
+    const routes = new Map();
+    const server = createServer((req, res) => handleRequest(req, res, routes));
+    shared = { server, routes, started: false, port };
+    return shared;
+}
+/** Test-only: tear down the shared server so each test starts clean. */
+export function _resetHttpServerForTests() {
+    if (!shared)
+        return;
+    try {
+        shared.server.close();
+    }
+    catch {
+        // ignore
+    }
+    shared = undefined;
+}
+async function handleRequest(req, res, routes) {
+    const url = req.url ?? '/';
+    const path = url.split('?')[0] ?? url;
+    const route = routes.get(path);
+    if (!route) {
+        res.statusCode = 404;
+        res.setHeader('content-type', 'application/json');
+        res.end(JSON.stringify({ error: `no hook registered at ${path}` }));
+        return;
+    }
+    if ((req.method ?? '').toUpperCase() !== 'POST') {
+        res.statusCode = 405;
+        res.setHeader('content-type', 'application/json');
+        res.end(JSON.stringify({ error: 'method not allowed' }));
+        return;
+    }
+    let raw = '';
+    for await (const chunk of req) {
+        raw += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+    }
+    let body = undefined;
+    if (raw.length > 0) {
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            res.statusCode = 400;
+            res.setHeader('content-type', 'application/json');
+            res.end(JSON.stringify({ error: 'invalid JSON body' }));
+            return;
+        }
+    }
+    try {
+        const result = await route.dispatch(body);
+        res.statusCode = 200;
+        res.setHeader('content-type', 'application/json');
+        res.end(JSON.stringify(result ?? null));
+    }
+    catch (err) {
+        res.statusCode = 500;
+        res.setHeader('content-type', 'application/json');
+        res.end(JSON.stringify({ error: err.message ?? 'internal error' }));
+    }
+}
+// ---------------------------------------------------------------------------
+// HttpTrigger — one per registered hook. Yields TriggerEvents as inbound
+// requests arrive on its `path`. Production wiring (pipeline + handler)
+// happens via the trigger's consumer (`runTrigger`); the response is
+// settled by `route.dispatch` once the handler has finished.
+// ---------------------------------------------------------------------------
+export class HttpTrigger {
+    name;
+    path;
+    method;
+    /** @internal — exposed for tests asserting the shared-server invariant. */
+    _server;
+    seq = 0;
+    stopped = false;
+    queued = [];
+    waiter = null;
+    shared;
+    /** Map event.id → pending response so the handler's return value can be sent back. */
+    pendingById = new Map();
+    /** Map event.id → user handler's return value (so dispatch can resolve sync). */
+    resultsById = new Map();
+    constructor(opts) {
+        this.name = opts.name;
+        this.path = opts.path;
+        this.method = opts.method;
+        this.shared = getSharedServer();
+        this._server = this.shared.server;
+    }
+    /**
+     * Called by the shared HTTP handler. Enqueues a new event and returns
+     * a promise that resolves with the user handler's return value.
+     */
+    async dispatch(body) {
+        const event = {
+            id: ++this.seq,
+            occurredAt: new Date().toISOString(),
+            input: body,
+        };
+        return new Promise((resolve, reject) => {
+            const pending = { resolve, reject };
+            this.queued.push({ event, pending });
+            this.pendingById.set(event.id, pending);
+            this.waiter?.();
+            this.waiter = null;
+        });
+    }
+    /**
+     * Resolve the pending HTTP response for a given event id. Called by the
+     * helper-generated Phase once the user handler has returned.
+     */
+    resolveResponse(eventId, value) {
+        const pending = this.pendingById.get(eventId);
+        if (!pending)
+            return;
+        this.pendingById.delete(eventId);
+        pending.resolve(value);
+    }
+    /** Reject the pending HTTP response for a given event id. */
+    rejectResponse(eventId, err) {
+        const pending = this.pendingById.get(eventId);
+        if (!pending)
+            return;
+        this.pendingById.delete(eventId);
+        pending.reject(err);
+    }
+    async *start() {
+        await this.ensureServerStarted();
+        while (!this.stopped) {
+            if (this.queued.length === 0) {
+                await new Promise((resolve) => {
+                    this.waiter = resolve;
+                });
+                if (this.stopped)
+                    return;
+            }
+            const item = this.queued.shift();
+            if (!item)
+                continue;
+            yield item.event;
+        }
+    }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.waiter?.();
+        this.waiter = null;
+        for (const pending of this.pendingById.values()) {
+            pending.reject(new Error('hook stopped'));
+        }
+        this.pendingById.clear();
+        this.shared.routes.delete(this.path);
+    }
+    async ensureServerStarted() {
+        this.shared.routes.set(this.path, this);
+        if (this.shared.started)
+            return;
+        if (this.shared.startPromise) {
+            await this.shared.startPromise;
+            return;
+        }
+        this.shared.startPromise = new Promise((resolve, reject) => {
+            this.shared.server.once('error', reject);
+            this.shared.server.listen(this.shared.port, '127.0.0.1', () => {
+                this.shared.started = true;
+                resolve();
+            });
+        });
+        await this.shared.startPromise;
+    }
+}
+// ---------------------------------------------------------------------------
+// hook() — the public entry point.
+// ---------------------------------------------------------------------------
+export function hook(spec, handler, options = {}) {
+    const name = options.name ?? deriveNameFromCaller('hook');
+    const triggerName = `${name}:http`;
+    const method = spec.method ?? 'POST';
+    const trigger = new HttpTrigger({ name: triggerName, path: spec.path, method });
+    const phase = {
+        name,
+        async *run(ctx) {
+            const carrier = ctx;
+            const event = carrier.__triggerEvent;
+            const httpTrig = carrier.__httpTrigger ?? trigger;
+            try {
+                const result = await handler(event?.input, ctx);
+                httpTrig.resolveResponse(event?.id ?? 0, result);
+                yield {
+                    type: 'data',
+                    key: `${name}.result`,
+                    value: result,
+                };
+            }
+            catch (err) {
+                httpTrig.rejectResponse(event?.id ?? 0, err instanceof Error ? err : new Error(String(err)));
+                throw err;
+            }
+        },
+    };
+    const pipelineSpec = {
+        phases: [phase],
+        ctx: (_input, event) => {
+            const ctx = { cache: new PipelineCache() };
+            ctx.__triggerEvent = event;
+            ctx.__httpTrigger = trigger;
+            return ctx;
+        },
+        trigger: triggerName,
+        description: options.description,
+    };
+    return (api) => {
+        api.registerTrigger(triggerName, trigger);
+        api.registerPipeline(name, pipelineSpec);
+    };
+}
+//# sourceMappingURL=hook.js.map

package/dist/helpers/hook.js.map

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

package/dist/helpers/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Convenience helpers — `schedule`, `hook`, `oneShot`.
+ *
+ * Each helper wraps a single handler function into a Phase, then returns
+ * an `ExtensionRegisterFn` `(api) => void` that the CLI auto-loader picks
+ * up via the file's default export. See each helper file for examples.
+ */
+export { oneShot, type OneShotOptions } from './one-shot.js';
+export { schedule, CronTrigger, type ScheduleSpec, type ScheduleOptions, } from './schedule.js';
+export { hook, HttpTrigger, type HookSpec, type HookOptions, } from './hook.js';
+export type { ExtensionRegisterFn, HelperHandler, PipelineSpec, ThreadPhaseAPI, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EACL,QAAQ,EACR,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,IAAI,EACJ,WAAW,EACX,KAAK,QAAQ,EACb,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/helpers/index.js

@@ -0,0 +1,11 @@
+/**
+ * Convenience helpers — `schedule`, `hook`, `oneShot`.
+ *
+ * Each helper wraps a single handler function into a Phase, then returns
+ * an `ExtensionRegisterFn` `(api) => void` that the CLI auto-loader picks
+ * up via the file's default export. See each helper file for examples.
+ */
+export { oneShot } from './one-shot.js';
+export { schedule, CronTrigger, } from './schedule.js';
+export { hook, HttpTrigger, } from './hook.js';
+//# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAuB,MAAM,eAAe,CAAC;AAC7D,OAAO,EACL,QAAQ,EACR,WAAW,GAGZ,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,IAAI,EACJ,WAAW,GAGZ,MAAM,WAAW,CAAC"}

package/dist/helpers/one-shot.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `oneShot` — register a single-handler pipeline with no trigger binding.
+ *
+ * Compresses the common "I have a one-off task I want to invoke via
+ * `thread-phase run <name>`" case to a single function call. The handler
+ * runs as a one-phase pipeline; its return value is captured as a `data`
+ * event with key `${name}.result`.
+ *
+ * Example:
+ *
+ *   export default oneShot(async (ctx) => {
+ *     await fireAndForget();
+ *     return { ok: true };
+ *   });
+ *
+ * If `name` is omitted, the helper derives it from the basename of the
+ * calling file. For production code prefer passing an explicit `name`.
+ */
+import type { ExtensionRegisterFn, HelperHandler } from './types.js';
+export interface OneShotOptions {
+    /** Pipeline name. If omitted, derived from the calling file's basename. */
+    name?: string;
+    /** Free-form description for `thread-phase list`. */
+    description?: string;
+}
+export declare function oneShot<TResult = unknown>(handler: HelperHandler<unknown, TResult>, options?: OneShotOptions): ExtensionRegisterFn;
+//# sourceMappingURL=one-shot.d.ts.map

package/dist/helpers/one-shot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"one-shot.d.ts","sourceRoot":"","sources":["../../src/helpers/one-shot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,OAAO,CAAC,OAAO,GAAG,OAAO,EACvC,OAAO,EAAE,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,EACxC,OAAO,GAAE,cAAmB,GAC3B,mBAAmB,CAwBrB"}

package/dist/helpers/one-shot.js

@@ -0,0 +1,43 @@
+/**
+ * `oneShot` — register a single-handler pipeline with no trigger binding.
+ *
+ * Compresses the common "I have a one-off task I want to invoke via
+ * `thread-phase run <name>`" case to a single function call. The handler
+ * runs as a one-phase pipeline; its return value is captured as a `data`
+ * event with key `${name}.result`.
+ *
+ * Example:
+ *
+ *   export default oneShot(async (ctx) => {
+ *     await fireAndForget();
+ *     return { ok: true };
+ *   });
+ *
+ * If `name` is omitted, the helper derives it from the basename of the
+ * calling file. For production code prefer passing an explicit `name`.
+ */
+import { PipelineCache } from '../cache.js';
+import { deriveNameFromCaller } from './caller.js';
+export function oneShot(handler, options = {}) {
+    const name = options.name ?? deriveNameFromCaller('oneShot');
+    const phase = {
+        name,
+        async *run(ctx) {
+            const result = await handler(undefined, ctx);
+            yield {
+                type: 'data',
+                key: `${name}.result`,
+                value: result,
+            };
+        },
+    };
+    const spec = {
+        phases: [phase],
+        ctx: () => ({ cache: new PipelineCache() }),
+        description: options.description,
+    };
+    return (api) => {
+        api.registerPipeline(name, spec);
+    };
+}
+//# sourceMappingURL=one-shot.js.map

package/dist/helpers/one-shot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"one-shot.js","sourceRoot":"","sources":["../../src/helpers/one-shot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAcnD,MAAM,UAAU,OAAO,CACrB,OAAwC,EACxC,UAA0B,EAAE;IAE5B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAE7D,MAAM,KAAK,GAA+B;QACxC,IAAI;QACJ,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YAC7C,MAAM;gBACJ,IAAI,EAAE,MAAM;gBACZ,GAAG,EAAE,GAAG,IAAI,SAAS;gBACrB,KAAK,EAAE,MAAM;aACd,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,MAAM,IAAI,GAA+C;QACvD,MAAM,EAAE,CAAC,KAAK,CAAC;QACf,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,aAAa,EAAE,EAAE,CAAC;QAC3C,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC;IAEF,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC;AACJ,CAAC"}

package/dist/helpers/schedule.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `schedule` — register a recurring pipeline driven by a timer or cron.
+ *
+ * Two surface forms:
+ *
+ *   schedule({ intervalMs: N }, handler)  // fires every N ms
+ *   schedule({ cron: expr }, handler)     // fires per cron expression
+ *
+ * Both register one Trigger (a `TimerTrigger` for `intervalMs`, a
+ * `CronTrigger` for `cron`) and one Pipeline that binds to it. The
+ * handler runs as a single Phase per fire; its return value is captured
+ * as a `data` event `${name}.result`.
+ *
+ * The `cron` form lazy-loads the optional peer dependency `cron-parser`
+ * at trigger start. Library users who never call the cron form pay
+ * nothing for the dep.
+ */
+import type { Trigger, TriggerEvent } from '../triggers/types.js';
+import type { ExtensionRegisterFn, HelperHandler } from './types.js';
+export type ScheduleSpec = {
+    intervalMs: number;
+} | {
+    cron: string;
+};
+export interface ScheduleOptions {
+    /** Pipeline + trigger base name. Defaults to the calling file's basename. */
+    name?: string;
+    /** Free-form description for `thread-phase list`. */
+    description?: string;
+}
+export declare function schedule<TResult = unknown>(spec: ScheduleSpec, handler: HelperHandler<TriggerEvent<unknown>, TResult>, options?: ScheduleOptions): ExtensionRegisterFn;
+interface CronParserModule {
+    parseExpression(expr: string): {
+        next(): {
+            toDate(): Date;
+        };
+    };
+}
+interface CronTriggerOptions {
+    cron: string;
+    name: string;
+    /** Test-only seam: inject a cron-parser implementation. */
+    _cronParser?: CronParserModule;
+}
+export declare class CronTrigger implements Trigger<void> {
+    readonly name: string;
+    private readonly cron;
+    private readonly injected?;
+    private seq;
+    private stopped;
+    private pendingTimer;
+    private notifyStop;
+    constructor(opts: CronTriggerOptions);
+    start(): AsyncGenerator<TriggerEvent<void>, void>;
+    stop(): Promise<void>;
+    private waitOrStop;
+}
+export {};
+//# sourceMappingURL=schedule.d.ts.map

package/dist/helpers/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/helpers/schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,YAAY,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,QAAQ,CAAC,OAAO,GAAG,OAAO,EACxC,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EACtD,OAAO,GAAE,eAAoB,GAC5B,mBAAmB,CAiDrB;AAQD,UAAU,gBAAgB;IACxB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,IAAI;YAAE,MAAM,IAAI,IAAI,CAAA;SAAE,CAAA;KAAE,CAAC;CAC/D;AAED,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC;AAED,qBAAa,WAAY,YAAW,OAAO,CAAC,IAAI,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAmB;IAE7C,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,UAAU,CAA6B;gBAEnC,IAAI,EAAE,kBAAkB;IAM7B,KAAK,IAAI,cAAc,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IAmBlD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,OAAO,CAAC,UAAU;CASnB"}

package/dist/helpers/schedule.js

@@ -0,0 +1,118 @@
+/**
+ * `schedule` — register a recurring pipeline driven by a timer or cron.
+ *
+ * Two surface forms:
+ *
+ *   schedule({ intervalMs: N }, handler)  // fires every N ms
+ *   schedule({ cron: expr }, handler)     // fires per cron expression
+ *
+ * Both register one Trigger (a `TimerTrigger` for `intervalMs`, a
+ * `CronTrigger` for `cron`) and one Pipeline that binds to it. The
+ * handler runs as a single Phase per fire; its return value is captured
+ * as a `data` event `${name}.result`.
+ *
+ * The `cron` form lazy-loads the optional peer dependency `cron-parser`
+ * at trigger start. Library users who never call the cron form pay
+ * nothing for the dep.
+ */
+import { PipelineCache } from '../cache.js';
+import { TimerTrigger } from '../triggers/timer-trigger.js';
+import { deriveNameFromCaller } from './caller.js';
+export function schedule(spec, handler, options = {}) {
+    const name = options.name ?? deriveNameFromCaller('schedule');
+    const triggerName = `${name}:trigger`;
+    let trigger;
+    if ('intervalMs' in spec) {
+        trigger = new TimerTrigger({
+            intervalMs: spec.intervalMs,
+            name: triggerName,
+        });
+    }
+    else {
+        trigger = new CronTrigger({ cron: spec.cron, name: triggerName });
+    }
+    const phase = {
+        name,
+        async *run(ctx) {
+            const event = ctx
+                .__triggerEvent ?? {
+                id: 0,
+                occurredAt: new Date().toISOString(),
+                input: undefined,
+            };
+            const result = await handler(event, ctx);
+            yield {
+                type: 'data',
+                key: `${name}.result`,
+                value: result,
+            };
+        },
+    };
+    const pipelineSpec = {
+        phases: [phase],
+        ctx: (_input, event) => {
+            const ctx = { cache: new PipelineCache() };
+            ctx.__triggerEvent = event;
+            return ctx;
+        },
+        trigger: triggerName,
+        description: options.description,
+    };
+    return (api) => {
+        api.registerTrigger(triggerName, trigger);
+        api.registerPipeline(name, pipelineSpec);
+    };
+}
+export class CronTrigger {
+    name;
+    cron;
+    injected;
+    seq = 0;
+    stopped = false;
+    pendingTimer = null;
+    notifyStop = null;
+    constructor(opts) {
+        this.name = opts.name;
+        this.cron = opts.cron;
+        this.injected = opts._cronParser;
+    }
+    async *start() {
+        if (this.stopped)
+            return;
+        const parser = this.injected ??
+            (await import('cron-parser'));
+        while (!this.stopped) {
+            const next = parser.parseExpression(this.cron).next().toDate();
+            const delay = Math.max(0, next.getTime() - Date.now());
+            const waited = await this.waitOrStop(delay);
+            if (!waited)
+                return;
+            yield {
+                id: ++this.seq,
+                occurredAt: new Date().toISOString(),
+                input: undefined,
+            };
+        }
+    }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.pendingTimer) {
+            clearTimeout(this.pendingTimer);
+            this.pendingTimer = null;
+        }
+        this.notifyStop?.();
+        this.notifyStop = null;
+    }
+    waitOrStop(ms) {
+        return new Promise((resolve) => {
+            this.pendingTimer = setTimeout(() => {
+                this.pendingTimer = null;
+                resolve(true);
+            }, ms);
+            this.notifyStop = () => resolve(false);
+        });
+    }
+}
+//# sourceMappingURL=schedule.js.map

package/dist/helpers/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.js","sourceRoot":"","sources":["../../src/helpers/schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAgBnD,MAAM,UAAU,QAAQ,CACtB,IAAkB,EAClB,OAAsD,EACtD,UAA2B,EAAE;IAE7B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,oBAAoB,CAAC,UAAU,CAAC,CAAC;IAC9D,MAAM,WAAW,GAAG,GAAG,IAAI,UAAU,CAAC;IAEtC,IAAI,OAAyB,CAAC;IAC9B,IAAI,YAAY,IAAI,IAAI,EAAE,CAAC;QACzB,OAAO,GAAG,IAAI,YAAY,CAAC;YACzB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,IAAI,EAAE,WAAW;SAClB,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,IAAI,WAAW,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,KAAK,GAA+B;QACxC,IAAI;QACJ,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG;YACZ,MAAM,KAAK,GAAI,GAAkD;iBAC9D,cAAc,IAAI;gBACnB,EAAE,EAAE,CAAC;gBACL,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACpC,KAAK,EAAE,SAAS;aACjB,CAAC;YACF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACzC,MAAM;gBACJ,IAAI,EAAE,MAAM;gBACZ,GAAG,EAAE,GAAG,IAAI,SAAS;gBACrB,KAAK,EAAE,MAAM;aACd,CAAC;QACJ,CAAC;KACF,CAAC;IAEF,MAAM,YAAY,GAA+C;QAC/D,MAAM,EAAE,CAAC,KAAK,CAAC;QACf,GAAG,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;YACrB,MAAM,GAAG,GAEL,EAAE,KAAK,EAAE,IAAI,aAAa,EAAE,EAAE,CAAC;YACnC,GAAG,CAAC,cAAc,GAAG,KAAK,CAAC;YAC3B,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO,EAAE,WAAW;QACpB,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC;IAEF,OAAO,CAAC,GAAG,EAAE,EAAE;QACb,GAAG,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC1C,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC3C,CAAC,CAAC;AACJ,CAAC;AAmBD,MAAM,OAAO,WAAW;IACb,IAAI,CAAS;IACL,IAAI,CAAS;IACb,QAAQ,CAAoB;IAErC,GAAG,GAAG,CAAC,CAAC;IACR,OAAO,GAAG,KAAK,CAAC;IAChB,YAAY,GAAyC,IAAI,CAAC;IAC1D,UAAU,GAAwB,IAAI,CAAC;IAE/C,YAAY,IAAwB;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,CAAC,KAAK;QACV,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,MAAM,MAAM,GACV,IAAI,CAAC,QAAQ;YACZ,CAAC,MAAM,MAAM,CAAC,aAAuB,CAAC,CAAiC,CAAC;QAE3E,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,IAAI,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;YAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YACvD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YAC5C,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,MAAM;gBACJ,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG;gBACd,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACpC,KAAK,EAAE,SAAiB;aACzB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAChC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;QACpB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAEO,UAAU,CAAC,EAAU;QAC3B,OAAO,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;YACtC,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC,GAAG,EAAE;gBAClC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;gBACzB,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC,EAAE,EAAE,CAAC,CAAC;YACP,IAAI,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/helpers/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Local types for the helpers package.
+ *
+ * These mirror the shapes of `PipelineSpec` and `ThreadPhaseAPI` from
+ * `@autonome-research/thread-phase-cli` but are redeclared here so the
+ * core package stays free of any dependency on the CLI. The CLI's
+ * `Registry` is structurally compatible with this `ThreadPhaseAPI` —
+ * the helpers' return value plugs straight into the CLI auto-loader.
+ */
+import type { AgentAdapterMeta, AgentRunResult } from '../agents/index.js';
+import type { BasePipelineContext, Phase } from '../phase.js';
+import type { Trigger, TriggerEvent } from '../triggers/types.js';
+/** A registered pipeline definition. Structurally identical to the CLI's. */
+export interface PipelineSpec<TCtx extends BasePipelineContext = BasePipelineContext, TInput = unknown> {
+    phases: ReadonlyArray<Phase<TCtx>> | ((input: TInput, event: TriggerEvent<TInput>) => ReadonlyArray<Phase<TCtx>>);
+    ctx: TCtx | ((input: TInput, event: TriggerEvent<TInput>) => TCtx);
+    trigger?: string;
+    defaultInput?: TInput;
+    description?: string;
+}
+/** Registration surface a helper invokes. Structurally compatible with the CLI's `ThreadPhaseAPI`. */
+export interface ThreadPhaseAPI {
+    registerTrigger<TInput>(name: string, trigger: Trigger<TInput>): void;
+    registerAdapter<TConfig, TResult extends AgentRunResult = AgentRunResult>(name: string, adapter: AgentAdapterMeta<TConfig, TResult>): void;
+    registerPipeline<TCtx extends BasePipelineContext, TInput = unknown>(name: string, spec: PipelineSpec<TCtx, TInput>): void;
+    getPipeline(name: string): PipelineSpec<BasePipelineContext, unknown> | undefined;
+    getAdapter(name: string): AgentAdapterMeta<unknown, AgentRunResult> | undefined;
+    getTrigger(name: string): Trigger<unknown> | undefined;
+}
+/** Extension default export: `(api) => void`. */
+export type ExtensionRegisterFn = (api: ThreadPhaseAPI) => void | Promise<void>;
+/** A user-supplied handler wrapped by a helper into a Phase. */
+export type HelperHandler<TInput, TResult> = (input: TInput, ctx: BasePipelineContext) => Promise<TResult> | TResult;
+//# sourceMappingURL=types.d.ts.map

package/dist/helpers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/helpers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAElE,6EAA6E;AAC7E,MAAM,WAAW,YAAY,CAC3B,IAAI,SAAS,mBAAmB,GAAG,mBAAmB,EACtD,MAAM,GAAG,OAAO;IAEhB,MAAM,EACF,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAC1B,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjF,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sGAAsG;AACtG,MAAM,WAAW,cAAc;IAC7B,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACtE,eAAe,CAAC,OAAO,EAAE,OAAO,SAAS,cAAc,GAAG,cAAc,EACtE,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,GAC1C,IAAI,CAAC;IACR,gBAAgB,CAAC,IAAI,SAAS,mBAAmB,EAAE,MAAM,GAAG,OAAO,EACjE,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,GAC/B,IAAI,CAAC;IACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC,mBAAmB,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAClF,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC,OAAO,EAAE,cAAc,CAAC,GAAG,SAAS,CAAC;IAChF,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;CACxD;AAED,iDAAiD;AACjD,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEhF,gEAAgE;AAChE,MAAM,MAAM,aAAa,CAAC,MAAM,EAAE,OAAO,IAAI,CAC3C,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,mBAAmB,KACrB,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC"}

package/dist/helpers/types.js

@@ -0,0 +1,11 @@
+/**
+ * Local types for the helpers package.
+ *
+ * These mirror the shapes of `PipelineSpec` and `ThreadPhaseAPI` from
+ * `@autonome-research/thread-phase-cli` but are redeclared here so the
+ * core package stays free of any dependency on the CLI. The CLI's
+ * `Registry` is structurally compatible with this `ThreadPhaseAPI` —
+ * the helpers' return value plugs straight into the CLI auto-loader.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/helpers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/helpers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Public API — the v1 stable surface.
+ *
+ * Everything exported from this file is covered by semver:
+ *   - patch (1.0.x): bug fixes, no API changes
+ *   - minor (1.x.0): additive only — new exports, new optional fields
+ *   - major (x.0.0): breaking changes
+ *
+ * Items marked @internal in their own files (e.g. `consumeStream`,
+ * `toOpenAIMessages`) are reachable via deep import for advanced callers
+ * but are NOT part of this stable surface and may change in minor releases.
+ *
+ * Subpath exports (./patterns, ./context, ./session, ./tools) live in their
+ * own index files and are exposed via package.json `exports`. They follow
+ * the same stability policy.
+ */
+export { PipelineCache } from './cache.js';
+export { runPipeline, runPipelineToSummary, type PipelineSummary, } from './orchestrator.js';
+export { requireCtx, type Phase, type BasePipelineContext, type PipelineEvent, } from './phase.js';
+export { type Message, type SystemMessage, type UserMessage, type AssistantMessage, type ToolResultMessage, type ToolCall, type ToolDefinition, type ToolResult, type ToolExecutor, } from './messages.js';
+export { loadInferenceConfig, createInferenceClient, type InferenceConfig, } from './inference.js';
+export { runAgentWithTools, parseJSON, type AgentConfig, type AgentRunnerOptions, type AgentRunResult, type ActivityEntry, type AgentStreamEvent, type FinishReason, type UsageInfo, } from './agent/index.js';
+export { type JobStore, SqliteJobStore, JobRunner, type JobRecord, type EventRecord, type JobStatus, type ListJobsOptions, type LiveEvent, } from './session/index.js';
+export { ToolRegistry, type ToolHandler, type ToolRegistryOptions, } from './tools/index.js';
+export { oneShot, schedule, hook, CronTrigger, HttpTrigger, type OneShotOptions, type ScheduleSpec, type ScheduleOptions, type HookSpec, type HookOptions, type ExtensionRegisterFn, type HelperHandler, type PipelineSpec, type ThreadPhaseAPI, } from './helpers/index.js';
+//# sourceMappingURL=index.d.ts.map