@jini-ai/http-kit 0.2.1

package/dist/route-registration-guard.js

@@ -0,0 +1,71 @@
+const routeInventorySymbol = Symbol.for('jini.routeRegistrationGuard.inventory');
+const GUARDED_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'options', 'all', 'use'];
+/**
+ * Builds the `METHOD PATH` key used to check `guardedRouteKeys` membership.
+ *
+ * @param method - The Express registration method name (any case; normalized to upper-case in the key).
+ * @param path - The first argument passed to that method. Only a string path can collide — a
+ * RegExp or array-of-paths route is never tracked, matching the inventory's own string-only
+ * recording below.
+ * @param guardedRouteKeys - The set of `METHOD PATH` keys this call installed a duplicate-registration
+ * guard for.
+ * @returns The matching key if `path` is a string and the key is in `guardedRouteKeys`, otherwise `null`.
+ * @complexity O(1) — a single `Set` lookup.
+ * @overallScore 100/100
+ */
+export function guardedRouteKey(method, path, guardedRouteKeys) {
+    if (typeof path !== 'string')
+        return null;
+    const key = `${method.toUpperCase()} ${path}`;
+    return guardedRouteKeys.has(key) ? key : null;
+}
+/**
+ * Monkey-patches `app`'s route-registration methods to record every string-path registration into
+ * a per-app inventory (retrievable via {@link getRouteRegistrationInventory}) and to throw if any
+ * `options.guardedRouteKeys` entry is registered a second time.
+ *
+ * @param app - The Express app to instrument. Must not already have this guard installed (installing
+ * twice would double-wrap every method and double-count the inventory — not guarded against here
+ * since `createLocalNodeDaemon` and every other caller in this codebase calls this exactly once
+ * per app at composition time).
+ * @param options.guardedRouteKeys - See {@link InstallRouteRegistrationGuardOptions}.
+ * @returns Nothing — mutates `app` in place and stashes its inventory under a well-known `Symbol.for` key.
+ * @throws If a `guardedRouteKeys` entry is registered more than once, at the moment of the second registration.
+ * @complexity O(1) setup (patches 8 fixed methods); each wrapped call is O(1) beyond the wrapped original.
+ * @overallScore 100/100
+ */
+export function installRouteRegistrationGuard(app, options = {}) {
+    const guardedRouteKeys = options.guardedRouteKeys ?? new Set();
+    const seen = new Set();
+    const inventory = [];
+    app[routeInventorySymbol] = inventory;
+    for (const method of GUARDED_METHODS) {
+        const original = app[method].bind(app);
+        app[method] = (path, ...handlers) => {
+            if (typeof path === 'string') {
+                inventory.push({ method: method.toUpperCase(), path });
+            }
+            const key = guardedRouteKey(method, path, guardedRouteKeys);
+            if (key) {
+                if (seen.has(key)) {
+                    throw new Error(`duplicate guarded route registration: ${key}`);
+                }
+                seen.add(key);
+            }
+            return original(path, ...handlers);
+        };
+    }
+}
+/**
+ * Reads back every route {@link installRouteRegistrationGuard} recorded for `app`.
+ *
+ * @param app - An app the guard was installed on. Safe to call on an app with no guard installed
+ * (returns an empty array rather than throwing).
+ * @returns A fresh array copy each call — the caller can never mutate the guard's own internal inventory through the returned reference.
+ * @complexity O(n) in the number of routes registered so far.
+ * @overallScore 100/100
+ */
+export function getRouteRegistrationInventory(app) {
+    return [...(app[routeInventorySymbol] ?? [])];
+}
+//# sourceMappingURL=route-registration-guard.js.map

package/dist/route-registration-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-registration-guard.js","sourceRoot":"","sources":["../src/route-registration-guard.ts"],"names":[],"mappings":"AAsBA,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;AAEjF,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAU,CAAC;AAEpG;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,IAAa,EACb,gBAAqC;IAErC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC;IAC9C,OAAO,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC;AAOD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,6BAA6B,CAC3C,GAAY,EACZ,UAAgD,EAAE;IAElD,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,IAAI,GAAG,EAAU,CAAC;IACvE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAwB,EAAE,CAAC;IACzC,GAAsD,CAAC,oBAAoB,CAAC,GAAG,SAAS,CAAC;IAE1F,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAI,GAAkE,CAAC,MAAM,CAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvG,GAAkE,CAAC,MAAM,CAAC,GAAG,CAC5E,IAAa,EACb,GAAG,QAAmB,EACtB,EAAE;YACF,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC7B,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YACzD,CAAC;YACD,MAAM,GAAG,GAAG,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC;YAC5D,IAAI,GAAG,EAAE,CAAC;gBACR,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBAClB,MAAM,IAAI,KAAK,CAAC,yCAAyC,GAAG,EAAE,CAAC,CAAC;gBAClE,CAAC;gBACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAChB,CAAC;YACD,OAAO,QAAQ,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;QACrC,CAAC,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,6BAA6B,CAAC,GAAY;IACxD,OAAO,CAAC,GAAG,CAAE,GAAkE,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAChH,CAAC"}

package/dist/routines.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @module routines
+ *
+ * Routine CRUD + run-history HTTP routes: `GET/POST /api/routines`, `GET/PATCH/DELETE
+ * /api/routines/:id`, `POST /api/routines/:id/run`, `GET /api/routines/:id/runs`. Calls into the
+ * `RoutineStore`/`RoutineService`-shaped ports `@jini-ai/daemon` ships (see that package's
+ * `routines/` module — `routine-store.ts` for the CRUD+history port, `scheduler.ts` for the
+ * scheduling engine) the same way `runs.ts` calls into `RunLifecycle` — no business logic lives
+ * in this file itself.
+ *
+ * Ported from OD's `apps/daemon/src/routes/routine.ts` (348 lines, `refactor/web-memory-slice`
+ * branch) per the decisions in `ADS-memory/reports/proposals/
+ * PROP-http-route-packs-automation-routines-2026-07-21.md` (Finding 2). That proposal identified
+ * two separable gaps blocking this route pack: (1) no scheduler existed anywhere in this repo —
+ * closed by porting `routines.ts` into `@jini-ai/daemon/src/routines/scheduler.ts` this same pass;
+ * (2) no `RoutineStore` persistence port existed for the CRUD side — closed by
+ * `@jini-ai/daemon/src/routines/routine-store.ts`, designed the same way `EventLog` is designed.
+ * This file is the third piece: the actual HTTP routes, now that both ports exist.
+ *
+ * **Confirmed bug fixed while porting** (per the proposal's own finding, not carried forward):
+ * OD's `GET /api/routines/:id`, `DELETE /api/routines/:id`, and `GET /api/routines/:id/runs` (OD
+ * source lines 236/268/292) had no try/catch, unlike every sibling handler in the same file. This
+ * port does not reproduce that gap — but not via a per-route try/catch either: every route here
+ * is mounted through `adapter.ts`'s `mountJsonRoute`, whose own top-level try/catch already wraps
+ * every route's `parse`/`handle` invocation (the same mechanism `runs.ts`/`memory.ts` rely on),
+ * so the bug is structurally impossible to reintroduce rather than merely patched at three call
+ * sites.
+ *
+ * **Deliberately NOT ported** (see the proposal's Finding 1 and the "built-in template scoping"
+ * decision it required a human call on):
+ * - `GET /api/automation-templates` / `GET /api/automation-templates/:id` — these depend on
+ *   `automation-templates.ts`, which is not ported (see below); none of the routine CRUD/run-now/
+ *   run-history routes below need it to function.
+ * - `POST /api/routines/:id/runs/:runId/crystallize` — depends on `ingestAutomationSource`
+ *   (`automation-ingestions.ts`), explicitly scoped by the proposal as "a dedicated follow-up
+ *   task the same size and shape as `@jini-ai/memory`'s own original port," not attempted here.
+ * - `automation-templates.ts` itself, including its CRUD-adjacent lookup machinery: the decision
+ *   already made for this pass is to ship **zero built-in automation templates** (matching this
+ *   repo's established precedent of keeping product-authored content host-owned — `@jini-ai/memory`'s
+ *   prompt-composition, `@jini-ai/deploy`'s config-path resolution, etc.) and, since no route in this
+ *   file needs any part of that module to function, none of it — content or generic shape — is
+ *   ported this pass.
+ * - `automation-proposals.ts` / `automation-ingestions.ts` — untouched, per the proposal's Finding
+ *   1 explicit scoping and this task's brief.
+ *
+ * **Design note — why `target.mode === 'reuse'` project-existence checking is optional, injected
+ * DI, not a hard dependency**: OD's original unconditionally called `getProject(db, projectId)`
+ * to validate a reuse target. This module has no project concept of its own (matching
+ * `active-context.ts`'s `resolveResource` precedent for the same category of coupling), so
+ * `RoutineHttpDeps.projectExists` is an optional injected predicate: a host that has a project
+ * store supplies it and reuse targets are validated against it exactly like OD did; a host with
+ * no such concept (or that wants to defer the check) can omit it, and reuse targets are accepted
+ * without existence-checking rather than forcing every consumer to fabricate one.
+ *
+ * **Design note — why `POST /api/routines/:id/run`'s `run` field can be `null` even on success**:
+ * `RoutineStore` deliberately does not record runs (see `routine-store.ts`'s module doc: run
+ * *writing* stays the scheduler's own separately-injected `RoutinePersistence` concern, matching
+ * OD's own architectural split between the two). This route calls `store.getLatestRun(id)` after
+ * `scheduler.runNow(id)` resolves — accurate only if a host has bridged the scheduler's
+ * `RoutinePersistence.insertRun`/`updateRun` writes into the same store instance (documented,
+ * host-level integration wiring, out of this port's scope, the same way `runs.ts`'s `onStarted`
+ * driver is host-supplied). `projectId`/`conversationId`/`agentRunId` on the response always
+ * reflect the real, just-started run regardless of that wiring, since those come directly from
+ * `scheduler.runNow`'s own return value.
+ */
+import type { Express } from 'express';
+import { type Routine, type RoutineCreateInput, type RoutineRun, type RoutineService, type RoutineStore, type RoutineUpdateInput } from '@jini-ai/daemon';
+import { type AdapterContext } from './adapter.js';
+/** The scheduler surface these routes need — a structural subset of `RoutineService`, matching OD's own `RoutineRoutesService` narrowing (`Pick<RoutineService, 'nextRunAt' | 'rescheduleOne' | 'runNow' | 'unschedule'>`). Wiring a real `RoutineService` in satisfies this with zero adapter code. */
+export type RoutineScheduler = Pick<RoutineService, 'nextRunAt' | 'rescheduleOne' | 'runNow' | 'unschedule'>;
+export interface RoutineHttpDeps {
+    readonly store: RoutineStore;
+    readonly scheduler: RoutineScheduler;
+    /** Validates a `target: {mode: 'reuse', projectId}`'s `projectId` before create/update accept it. Omit to skip existence-checking entirely — see this module's doc comment. */
+    readonly projectExists?: (projectId: string) => boolean | Promise<boolean>;
+}
+interface RoutineUpdateRequest {
+    readonly id: string;
+    readonly patch: RoutineUpdateInput;
+}
+interface RoutineRunsQuery {
+    readonly id: string;
+    readonly limit: number;
+}
+export interface RoutineListResponse {
+    readonly routines: readonly Routine[];
+}
+export declare const routineListRoute: import("./types.js").JsonRouteSpec<void, RoutineListResponse, RoutineHttpDeps>;
+export interface RoutineResponse {
+    readonly routine: Routine;
+}
+export declare const routineCreateRoute: import("./types.js").JsonRouteSpec<RoutineCreateInput, RoutineResponse, RoutineHttpDeps>;
+export declare const routineGetRoute: import("./types.js").JsonRouteSpec<string, RoutineResponse, RoutineHttpDeps>;
+export declare const routineUpdateRoute: import("./types.js").JsonRouteSpec<RoutineUpdateRequest, RoutineResponse, RoutineHttpDeps>;
+export interface RoutineDeleteResponse {
+    readonly ok: true;
+}
+export declare const routineDeleteRoute: import("./types.js").JsonRouteSpec<string, RoutineDeleteResponse, RoutineHttpDeps>;
+export interface RoutineRunNowResponse {
+    readonly routine: Routine | null;
+    readonly run: RoutineRun | null;
+    readonly projectId: string;
+    readonly conversationId: string;
+    readonly agentRunId: string;
+}
+export declare const routineRunNowRoute: import("./types.js").JsonRouteSpec<string, RoutineRunNowResponse, RoutineHttpDeps>;
+export interface RoutineRunsResponse {
+    readonly runs: readonly RoutineRun[];
+}
+export declare const routineRunsListRoute: import("./types.js").JsonRouteSpec<RoutineRunsQuery, RoutineRunsResponse, RoutineHttpDeps>;
+/** Mounts every routine route on `app`. A pack's `http(app, services)` calls this directly. */
+export declare function registerRoutineRoutes(app: Express, deps: RoutineHttpDeps, adapter: AdapterContext): void;
+export {};
+//# sourceMappingURL=routines.d.ts.map

package/dist/routines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routines.d.ts","sourceRoot":"","sources":["../src/routines.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAGL,KAAK,OAAO,EAEZ,KAAK,kBAAkB,EAEvB,KAAK,UAAU,EAEf,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAmC,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAIpF,wSAAwS;AACxS,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,eAAe,GAAG,QAAQ,GAAG,YAAY,CAAC,CAAC;AAE7G,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,+KAA+K;IAC/K,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5E;AA8HD,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;CACpC;AAuDD,UAAU,gBAAgB;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAkBD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CACvC;AAED,eAAO,MAAM,gBAAgB,gFAQ3B,CAAC;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,eAAO,MAAM,kBAAkB,0FAa7B,CAAC;AAMH,eAAO,MAAM,eAAe,8EAU1B,CAAC;AAEH,eAAO,MAAM,kBAAkB,4FAe7B,CAAC;AAEH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;CACnB;AAED,eAAO,MAAM,kBAAkB,oFAU7B,CAAC;AAMH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,kBAAkB,oFAmB7B,CAAC;AAMH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;CACtC;AAED,eAAO,MAAM,oBAAoB,4FAU/B,CAAC;AAEH,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAQxG"}

package/dist/routines.js

@@ -0,0 +1,320 @@
+import { validateSchedule, validateTarget, } from '@jini-ai/daemon';
+import { createApiError } from '@jini-ai/protocol';
+import { defineJsonRoute, mountJsonRoute } from './adapter.js';
+import { validationError } from './request.js';
+import { err, ok } from './types.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Overlays the scheduler's live `nextRunAt` onto a routine fetched from the store — `RoutineStore` itself has no scheduler knowledge (see `routine-store.ts`'s module doc), matching OD's own `routineFromDb` two-step (fetch, then overlay `routineService.nextRunAt`). */
+function attachNextRunAt(routine, scheduler) {
+    return { ...routine, nextRunAt: scheduler.nextRunAt(routine.id)?.getTime() ?? null };
+}
+async function checkTargetProjectExists(target, deps) {
+    if (target.mode !== 'reuse' || !deps.projectExists)
+        return null;
+    const exists = await deps.projectExists(target.projectId);
+    return exists ? null : createApiError('NOT_FOUND', `target project ${target.projectId} not found`);
+}
+function parseRoutineId(input) {
+    const id = input.params.id;
+    return typeof id === 'string' && id.length > 0 ? ok(id) : err(validationError('id must be a non-empty path parameter'));
+}
+function parseNonEmptyString(value, field) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return err(validationError(`${field} is required`, [{ path: field, message: 'required non-empty string' }]));
+    }
+    return ok(value.trim());
+}
+/** Present-but-non-string/empty is rejected; absent (`undefined`) or explicit `null` are both accepted (clearing the field on update). */
+function parseOptionalNullableString(body, field) {
+    const value = body[field];
+    if (value === undefined)
+        return ok(undefined);
+    if (value === null)
+        return ok(null);
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return err(validationError(`${field} must be a non-empty string or null when provided`));
+    }
+    return ok(value);
+}
+function parseSchedule(value) {
+    try {
+        validateSchedule(value);
+    }
+    catch (error) {
+        return err(validationError(errorMessage(error)));
+    }
+    return ok(value);
+}
+function parseTarget(value) {
+    try {
+        validateTarget(value);
+    }
+    catch (error) {
+        return err(validationError(errorMessage(error)));
+    }
+    return ok(value);
+}
+/** Validates and de-duplicates one `context.*` array field, trimming entries and dropping blanks — mirrors OD's `cleanStringList`. */
+function cleanStringList(value, field) {
+    if (!Array.isArray(value))
+        return err(validationError(`${field} must be an array`));
+    const out = [];
+    const seen = new Set();
+    for (const item of value) {
+        if (typeof item !== 'string')
+            return err(validationError(`${field} must contain strings`));
+        const trimmed = item.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return ok(out);
+}
+const CONTEXT_FIELDS = ['skillIds', 'pluginIds', 'mcpServerIds', 'connectorIds'];
+/** Mirrors OD's `normalizeRoutineContext`: an explicitly-empty array for a field is dropped entirely (not kept as `[]`) so a routine's stored context only ever carries fields that actually scope something. */
+function parseContextSelection(value) {
+    if (value === undefined || value === null)
+        return ok({});
+    if (!isRecord(value))
+        return err(validationError('context must be an object'));
+    const context = {};
+    for (const field of CONTEXT_FIELDS) {
+        const raw = value[field];
+        if (raw === undefined)
+            continue;
+        const cleaned = cleanStringList(raw, `context.${field}`);
+        if (!cleaned.ok)
+            return cleaned;
+        if (cleaned.value.length > 0)
+            context[field] = cleaned.value;
+    }
+    return ok(context);
+}
+function parseRoutineCreate(input) {
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const name = parseNonEmptyString(input.body.name, 'name');
+    if (!name.ok)
+        return name;
+    const prompt = parseNonEmptyString(input.body.prompt, 'prompt');
+    if (!prompt.ok)
+        return prompt;
+    const schedule = parseSchedule(input.body.schedule);
+    if (!schedule.ok)
+        return schedule;
+    const target = parseTarget(input.body.target);
+    if (!target.ok)
+        return target;
+    const skillId = parseOptionalNullableString(input.body, 'skillId');
+    if (!skillId.ok)
+        return skillId;
+    const agentId = parseOptionalNullableString(input.body, 'agentId');
+    if (!agentId.ok)
+        return agentId;
+    const context = parseContextSelection(input.body.context);
+    if (!context.ok)
+        return context;
+    const enabled = input.body.enabled;
+    if (enabled !== undefined && typeof enabled !== 'boolean') {
+        return err(validationError('enabled must be a boolean when provided'));
+    }
+    return ok({
+        name: name.value,
+        prompt: prompt.value,
+        schedule: schedule.value,
+        target: target.value,
+        ...(skillId.value !== undefined ? { skillId: skillId.value } : {}),
+        ...(agentId.value !== undefined ? { agentId: agentId.value } : {}),
+        context: context.value,
+        ...(enabled !== undefined ? { enabled } : {}),
+    });
+}
+function parseRoutineUpdate(input) {
+    const idResult = parseRoutineId(input);
+    if (!idResult.ok)
+        return idResult;
+    if (!isRecord(input.body))
+        return err(validationError('body must be a JSON object'));
+    const body = input.body;
+    // `RoutineUpdateInput`'s fields are `readonly` (an immutable port-input contract) — built here
+    // as a mutable local shape field-by-field, then handed back as that readonly type, which is a
+    // safe widening (mutable -> readonly), not the reverse.
+    const patch = {};
+    if (body.name !== undefined) {
+        const name = parseNonEmptyString(body.name, 'name');
+        if (!name.ok)
+            return name;
+        patch.name = name.value;
+    }
+    if (body.prompt !== undefined) {
+        const prompt = parseNonEmptyString(body.prompt, 'prompt');
+        if (!prompt.ok)
+            return prompt;
+        patch.prompt = prompt.value;
+    }
+    if (body.schedule !== undefined) {
+        const schedule = parseSchedule(body.schedule);
+        if (!schedule.ok)
+            return schedule;
+        patch.schedule = schedule.value;
+    }
+    if (body.target !== undefined) {
+        const target = parseTarget(body.target);
+        if (!target.ok)
+            return target;
+        patch.target = target.value;
+    }
+    if (body.skillId !== undefined) {
+        const skillId = parseOptionalNullableString(body, 'skillId');
+        if (!skillId.ok)
+            return skillId;
+        patch.skillId = skillId.value ?? null;
+    }
+    if (body.agentId !== undefined) {
+        const agentId = parseOptionalNullableString(body, 'agentId');
+        if (!agentId.ok)
+            return agentId;
+        patch.agentId = agentId.value ?? null;
+    }
+    if (body.context !== undefined) {
+        const context = parseContextSelection(body.context);
+        if (!context.ok)
+            return context;
+        patch.context = context.value;
+    }
+    if (body.enabled !== undefined) {
+        if (typeof body.enabled !== 'boolean')
+            return err(validationError('enabled must be a boolean when provided'));
+        patch.enabled = body.enabled;
+    }
+    return ok({ id: idResult.value, patch });
+}
+function parseRoutineRunsQuery(input) {
+    const idResult = parseRoutineId(input);
+    if (!idResult.ok)
+        return idResult;
+    const raw = input.query.limit;
+    const rawValue = Array.isArray(raw) ? raw[0] : raw;
+    // Matches OD's own `Math.min(100, Math.max(1, Number(req.query.limit) || 20))` exactly,
+    // including the `|| 20` fallback for NaN/0/negative/absent rather than `?? 20`.
+    const numeric = Number(rawValue) || 20;
+    const limit = Math.min(100, Math.max(1, numeric));
+    return ok({ id: idResult.value, limit });
+}
+export const routineListRoute = defineJsonRoute({
+    method: 'get',
+    path: '/api/routines',
+    parse: () => ok(undefined),
+    handle: async (_input, deps) => {
+        const routines = await deps.store.list();
+        return ok({ routines: routines.map((routine) => attachNextRunAt(routine, deps.scheduler)) });
+    },
+});
+export const routineCreateRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/routines',
+    requireSameOrigin: true,
+    parse: parseRoutineCreate,
+    handle: async (input, deps) => {
+        const targetError = await checkTargetProjectExists(input.target, deps);
+        if (targetError)
+            return err(targetError);
+        const routine = await deps.store.create(input);
+        deps.scheduler.rescheduleOne(routine.id);
+        return ok({ routine: attachNextRunAt(routine, deps.scheduler) });
+    },
+    successStatus: 201,
+});
+// ---------------------------------------------------------------------------
+// GET/PATCH/DELETE /api/routines/:id
+// ---------------------------------------------------------------------------
+export const routineGetRoute = defineJsonRoute({
+    method: 'get',
+    path: '/api/routines/:id',
+    parse: parseRoutineId,
+    handle: async (id, deps) => {
+        const routine = await deps.store.get(id);
+        return routine === null
+            ? err(createApiError('NOT_FOUND', 'routine not found'))
+            : ok({ routine: attachNextRunAt(routine, deps.scheduler) });
+    },
+});
+export const routineUpdateRoute = defineJsonRoute({
+    method: 'patch',
+    path: '/api/routines/:id',
+    requireSameOrigin: true,
+    parse: parseRoutineUpdate,
+    handle: async ({ id, patch }, deps) => {
+        if (patch.target !== undefined) {
+            const targetError = await checkTargetProjectExists(patch.target, deps);
+            if (targetError)
+                return err(targetError);
+        }
+        const routine = await deps.store.update(id, patch);
+        if (routine === null)
+            return err(createApiError('NOT_FOUND', 'routine not found'));
+        deps.scheduler.rescheduleOne(id);
+        return ok({ routine: attachNextRunAt(routine, deps.scheduler) });
+    },
+});
+export const routineDeleteRoute = defineJsonRoute({
+    method: 'delete',
+    path: '/api/routines/:id',
+    requireSameOrigin: true,
+    parse: parseRoutineId,
+    handle: async (id, deps) => {
+        deps.scheduler.unschedule(id);
+        const removed = await deps.store.delete(id);
+        return removed ? ok({ ok: true }) : err(createApiError('NOT_FOUND', 'routine not found'));
+    },
+});
+export const routineRunNowRoute = defineJsonRoute({
+    method: 'post',
+    path: '/api/routines/:id/run',
+    requireSameOrigin: true,
+    parse: parseRoutineId,
+    handle: async (id, deps) => {
+        const existing = await deps.store.get(id);
+        if (existing === null)
+            return err(createApiError('NOT_FOUND', 'routine not found'));
+        const started = await deps.scheduler.runNow(id);
+        const [routine, run] = await Promise.all([deps.store.get(id), deps.store.getLatestRun(id)]);
+        return ok({
+            routine: routine ? attachNextRunAt(routine, deps.scheduler) : null,
+            run,
+            projectId: started.projectId,
+            conversationId: started.conversationId,
+            agentRunId: started.agentRunId,
+        });
+    },
+    successStatus: 202,
+});
+export const routineRunsListRoute = defineJsonRoute({
+    method: 'get',
+    path: '/api/routines/:id/runs',
+    parse: parseRoutineRunsQuery,
+    handle: async ({ id, limit }, deps) => {
+        const existing = await deps.store.get(id);
+        if (existing === null)
+            return err(createApiError('NOT_FOUND', 'routine not found'));
+        const runs = await deps.store.listRuns(id, limit);
+        return ok({ runs });
+    },
+});
+/** Mounts every routine route on `app`. A pack's `http(app, services)` calls this directly. */
+export function registerRoutineRoutes(app, deps, adapter) {
+    mountJsonRoute(app, routineListRoute, deps, adapter);
+    mountJsonRoute(app, routineCreateRoute, deps, adapter);
+    mountJsonRoute(app, routineGetRoute, deps, adapter);
+    mountJsonRoute(app, routineUpdateRoute, deps, adapter);
+    mountJsonRoute(app, routineDeleteRoute, deps, adapter);
+    mountJsonRoute(app, routineRunNowRoute, deps, adapter);
+    mountJsonRoute(app, routineRunsListRoute, deps, adapter);
+}
+//# sourceMappingURL=routines.js.map

package/dist/routines.js.map

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

package/dist/run-stream.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @module run-stream
+ *
+ * An encoder-driven SSE run-stream route: subscribes to a run via `@jini-ai/daemon`'s
+ * `RunLifecycle.stream`, pipes every event through a composition-root-supplied protocol encoder,
+ * and writes each non-null event to the SSE response opened by `createSseResponse`.
+ * `handleRunStreamRequest` is the core
+ * — it only ever touches `node:http`'s `IncomingMessage`/`ServerResponse` — and
+ * `registerRunStreamRoute` below is Express's own thin mounting glue (Express's `Request`/
+ * `Response` already *are* Node's raw `http.IncomingMessage`/`http.ServerResponse`, so resolving
+ * `req.params.runId` and handing the request/response straight through is the whole job).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { RunLifecycle } from '@jini-ai/daemon';
+import type { RunProtocolEvent } from '@jini-ai/protocol';
+import type { Express } from 'express';
+/** Backward-compatible route path used by the AG-UI composition. The handler itself is encoder-agnostic. */
+export declare const RUN_STREAM_ROUTE_PATH = "/api/runs/:runId/agui-stream";
+export interface RunStreamEncoder {
+    encode(event: RunProtocolEvent, context: {
+        readonly runId: string;
+    }): unknown | null;
+}
+export interface RunStreamInternalErrorContext {
+    readonly source: 'encoder' | 'lifecycle' | 'route';
+    readonly runId: string;
+    readonly error: unknown;
+}
+export interface RunStreamDeps {
+    readonly lifecycle: RunLifecycle;
+    /** Protocol adapter supplied by the composition root (for example `createGenUiEncoder()`). */
+    readonly encoder: RunStreamEncoder;
+    /** Host-owned sink for failures that must not escape an async Express handler. Defaults to `console.error`. */
+    readonly onInternalError?: (context: RunStreamInternalErrorContext) => void;
+}
+/**
+ * Handles one encoded SSE run-stream request end to end. Opens the SSE connection immediately (an
+ * SSE endpoint commits to `text/event-stream` headers before it can know whether `runId` is
+ * valid), then subscribes to the run: a replay-then-live-subscribe `unknown-run`/`replay-gap`/
+ * `invalid-cursor` result is reported as one `{ error }` SSE data event before closing (there is
+ * no JSON-status-code channel left once SSE headers are already committed). On the happy path,
+ * every event `RunLifecycle` delivers is encoded and forwarded; the connection closes itself once
+ * the run's own terminal `'end'` event has been forwarded (a driver's contract with
+ * `RunLifecycle` guarantees no further events follow a run's `'end')`, so nothing is lost by
+ * closing right after it). If the client disconnects first, `createSseResponse`'s own
+ * `req.on('close', ...)` fires first, which (via `onClose` here) unsubscribes from the run so a
+ * disconnected client never leaves a dangling `RunLifecycle` subscriber.
+ *
+ * @param req - The raw request `createSseResponse` opens the stream against.
+ * @param res - The raw response `createSseResponse` opens the stream against.
+ * @param runId - The run to stream, already resolved by the caller's transport-specific glue.
+ * @param deps.lifecycle - The `RunLifecycle` to subscribe to.
+ * @param deps.encoder - The protocol adapter chosen by the composition root.
+ * @complexity O(1) plus the supplied encoder's per-event cost and `RunLifecycle.stream`'s replay cost.
+ * @overallScore 100/100
+ */
+export declare function handleRunStreamRequest(req: IncomingMessage, res: ServerResponse, runId: string, deps: RunStreamDeps): Promise<void>;
+/** Mounts the encoder-driven SSE run-stream route on `app`. */
+export declare function registerRunStreamRoute(app: Express, deps: RunStreamDeps): void;
+//# sourceMappingURL=run-stream.d.ts.map

package/dist/run-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-stream.d.ts","sourceRoot":"","sources":["../src/run-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAyB,MAAM,iBAAiB,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAG1D,4GAA4G;AAC5G,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,GAAG,IAAI,CAAC;CACtF;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,+GAA+G;IAC/G,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,6BAA6B,KAAK,IAAI,CAAC;CAC7E;AAwBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CAuCf;AAED,+DAA+D;AAC/D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAiB9E"}