@pellux/goodvibes-daemon-sdk 0.33.37 → 0.33.38

package/dist/route-helpers.d.ts

@@ -1,30 +1,153 @@
+/** A plain JSON object (record of string keys to unknown values). */
 export type JsonRecord = Record<string, unknown>;
+/** Alias for `JsonRecord` used for request/response body shapes. */
 export type JsonBody = JsonRecord;
+/** A named parse schema for a daemon route request body. */
 export interface RouteBodySchema<T> {
+    /** Identifies which route this schema belongs to (for error messages). */
     readonly routeId: string;
+    /** Parse a raw JSON body into `T`, or return an error `Response` on validation failure. */
     readonly parse: (body: JsonRecord) => T | Response;
 }
+/**
+ * Create a typed `RouteBodySchema` from a route id and a parse function.
+ *
+ * @param routeId - Route identifier for error context.
+ * @param parse - Function that validates and transforms a `JsonRecord` to `T`, or returns an error `Response`.
+ * @returns A `RouteBodySchema<T>` ready to use in route handlers.
+ */
 export declare function createRouteBodySchema<T>(routeId: string, parse: (body: JsonRecord) => T | Response): RouteBodySchema<T>;
+/**
+ * Create a typed registry of route body schemas, inferring the full map type.
+ *
+ * @param schemas - Map of route ids to `RouteBodySchema` instances.
+ * @returns The same map with its literal type preserved.
+ */
 export declare function createRouteBodySchemaRegistry<const TSchemaMap extends Record<string, RouteBodySchema<unknown>>>(schemas: TSchemaMap): TSchemaMap;
+/** Type guard that returns `true` when `value` is a non-null, non-array plain object. */
 export declare function isJsonRecord(value: unknown): value is JsonRecord;
+/**
+ * Recursively convert a value to a JSON-safe representation, replacing circular
+ * references with `{ $ref: '<json-path>' }` entries.
+ *
+ * @param value - The value to serialize.
+ * @returns A JSON-safe copy of `value`.
+ */
 export declare function toSerializableJson(value: unknown, stack?: Map<object, string>, path?: string): unknown;
+/**
+ * Create a JSON `Response` from any value, safely handling circular references.
+ *
+ * @param body - The value to serialize as the response body.
+ * @param init - Optional `ResponseInit` (status, headers, etc.).
+ * @returns A `Response` with `Content-Type: application/json`.
+ */
 export declare function serializableJsonResponse(body: unknown, init?: ResponseInit): Response;
+/** Options for bounded integer parsing from query parameters or request bodies. */
 export interface BoundedIntegerOptions {
+    /** Default value to use when the input is absent or invalid. */
     readonly fallback: number;
+    /** Inclusive lower bound. Defaults to `0`. */
     readonly min?: number | undefined;
+    /** Inclusive upper bound. Defaults to `1000`. */
     readonly max?: number | undefined;
 }
+/**
+ * Parse an integer from a raw query-parameter string, clamping to `[min, max]` and
+ * falling back to `options.fallback` when the value is absent or non-finite.
+ *
+ * @param raw - The raw string value (or `null` if the parameter was absent).
+ * @param options - Bounds and fallback configuration.
+ * @returns A clamped integer within `[min, max]`.
+ */
 export declare function readBoundedInteger(raw: string | null, options: BoundedIntegerOptions): number;
+/**
+ * Parse a positive integer (min=1) from a query-parameter string.
+ *
+ * @param raw - The raw string value (or `null`).
+ * @param fallback - Default when absent or invalid.
+ * @param max - Upper bound; defaults to `1000`.
+ * @returns A clamped integer in `[1, max]`.
+ */
 export declare function readBoundedPositiveInteger(raw: string | null, fallback: number, max?: number): number;
+/**
+ * Parse a bounded integer from a parsed JSON body value.
+ *
+ * @param value - The raw body value (should be `number`).
+ * @param fallback - Default when absent or non-finite.
+ * @param max - Inclusive upper bound.
+ * @param min - Inclusive lower bound; defaults to `1`.
+ * @returns A clamped integer in `[min, max]`.
+ */
 export declare function readBoundedBodyInteger(value: unknown, fallback: number, max: number, min?: number): number;
+/**
+ * Parse an optional bounded integer from a query-parameter string.
+ * Returns `undefined` when the parameter is absent or non-finite.
+ *
+ * @param raw - The raw string value (or `null`).
+ * @param min - Inclusive lower bound.
+ * @param max - Inclusive upper bound.
+ * @returns A clamped integer or `undefined`.
+ */
 export declare function readOptionalBoundedInteger(raw: string | null, min: number, max: number): number | undefined;
+/**
+ * Read a non-empty trimmed string from a JSON body field, returning `undefined` if absent or blank.
+ *
+ * @param body - The parsed request body.
+ * @param key - The field key to read.
+ * @returns The trimmed string, or `undefined`.
+ */
 export declare function readOptionalStringField(body: JsonRecord, key: string): string | undefined;
+/**
+ * Read an array of non-empty trimmed strings from a JSON body field.
+ * Entries that are not strings or are blank are skipped. Returns `undefined` when
+ * the field is absent, not an array, or all entries were invalid.
+ *
+ * @param body - The parsed request body.
+ * @param key - The field key to read.
+ * @param max - Maximum number of entries to include; defaults to `128`.
+ * @returns A non-empty string array, or `undefined`.
+ */
 export declare function readStringArrayField(body: JsonRecord, key: string, max?: number): string[] | undefined;
+/**
+ * Test whether a single granted scope string covers the required scope.
+ * Supports exact match, wildcard `'*'`, and prefix wildcard (e.g. `'sessions:*'`).
+ *
+ * @param granted - A scope string held by the caller.
+ * @param required - The scope the operation requires.
+ * @returns `true` if `granted` covers `required`.
+ */
 export declare function scopeMatches(granted: string, required: string): boolean;
+/**
+ * Return `true` if the caller holds at least one of the required scopes.
+ *
+ * @param grantedScopes - Scopes held by the caller (or `undefined` for no scopes).
+ * @param requiredScopes - Scopes to check against.
+ */
 export declare function hasAnyScope(grantedScopes: readonly string[] | undefined, requiredScopes: readonly string[]): boolean;
+/**
+ * Return the subset of `requiredScopes` not covered by `grantedScopes`.
+ *
+ * @param grantedScopes - Scopes held by the caller (or `undefined` for no scopes).
+ * @param requiredScopes - The full set of required scopes.
+ * @returns An array of scope strings that are missing; empty if all are satisfied.
+ */
 export declare function missingScopes(grantedScopes: readonly string[] | undefined, requiredScopes: readonly string[]): string[];
+/** The set of lifecycle action strings accepted by channel lifecycle endpoints. */
 export type ChannelLifecycleAction = 'inspect' | 'setup' | 'retest' | 'connect' | 'disconnect' | 'start' | 'stop' | 'login' | 'logout' | 'wait_login';
+/** The conversation kind values accepted by channel conversation endpoints. */
 export type ChannelConversationKind = 'direct' | 'group' | 'channel' | 'thread' | 'service';
+/**
+ * Validate and narrow an unknown value to `ChannelLifecycleAction`.
+ *
+ * @param value - The raw input (typically from a URL path segment or body field).
+ * @returns The typed action string, or `null` if the value is not a valid action.
+ */
 export declare function readChannelLifecycleAction(value: unknown): ChannelLifecycleAction | null;
+/**
+ * Validate and narrow an unknown value to `ChannelConversationKind`.
+ *
+ * @param value - The raw input (typically from a URL path segment or body field).
+ * @returns The typed kind string, or `null` if the value is not a valid kind.
+ */
 export declare function readChannelConversationKind(value: unknown): ChannelConversationKind | null;
 //# sourceMappingURL=route-helpers.d.ts.map

package/dist/route-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../src/route-helpers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC;AAElC,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,CAAC,GAAG,QAAQ,CAAC;CACpD;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,CAAC,GAAG,QAAQ,GACxC,eAAe,CAAC,CAAC,CAAC,CAEpB;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,EACjE,OAAO,EAAE,UAAU,GAAG,UAAU,CAEjC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,sBAA4B,EAAE,IAAI,SAAM,GAAG,OAAO,CAiBzG;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,QAAQ,CAErF;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAS7F;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAQ,GAAG,MAAM,CAEpG;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,CAGrG;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK3G;AAMD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzF;AAGD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAWnG;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMvE;AAED,wBAAgB,WAAW,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAGpH;AAED,wBAAgB,aAAa,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAGvH;AAED,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,OAAO,GACP,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,OAAO,GACP,MAAM,GACN,OAAO,GACP,QAAQ,GACR,YAAY,CAAC;AAEjB,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5F,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,GAAG,IAAI,CAaxF;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,GAAG,IAAI,CAI1F"}
+{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../src/route-helpers.ts"],"names":[],"mappings":"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"}

package/dist/route-helpers.js

@@ -1,12 +1,33 @@
+/**
+ * Create a typed `RouteBodySchema` from a route id and a parse function.
+ *
+ * @param routeId - Route identifier for error context.
+ * @param parse - Function that validates and transforms a `JsonRecord` to `T`, or returns an error `Response`.
+ * @returns A `RouteBodySchema<T>` ready to use in route handlers.
+ */
 export function createRouteBodySchema(routeId, parse) {
     return { routeId, parse };
 }
+/**
+ * Create a typed registry of route body schemas, inferring the full map type.
+ *
+ * @param schemas - Map of route ids to `RouteBodySchema` instances.
+ * @returns The same map with its literal type preserved.
+ */
 export function createRouteBodySchemaRegistry(schemas) {
     return schemas;
 }
+/** Type guard that returns `true` when `value` is a non-null, non-array plain object. */
 export function isJsonRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Recursively convert a value to a JSON-safe representation, replacing circular
+ * references with `{ $ref: '<json-path>' }` entries.
+ *
+ * @param value - The value to serialize.
+ * @returns A JSON-safe copy of `value`.
+ */
 export function toSerializableJson(value, stack = new Map(), path = '$') {
     if (!value || typeof value !== 'object')
         return value;
@@ -24,9 +45,24 @@ export function toSerializableJson(value, stack = new Map(), path = '$') {
         toSerializableJson(entry, next, `${path}.${key}`),
     ]));
 }
+/**
+ * Create a JSON `Response` from any value, safely handling circular references.
+ *
+ * @param body - The value to serialize as the response body.
+ * @param init - Optional `ResponseInit` (status, headers, etc.).
+ * @returns A `Response` with `Content-Type: application/json`.
+ */
 export function serializableJsonResponse(body, init) {
     return Response.json(toSerializableJson(body), init);
 }
+/**
+ * Parse an integer from a raw query-parameter string, clamping to `[min, max]` and
+ * falling back to `options.fallback` when the value is absent or non-finite.
+ *
+ * @param raw - The raw string value (or `null` if the parameter was absent).
+ * @param options - Bounds and fallback configuration.
+ * @returns A clamped integer within `[min, max]`.
+ */
 export function readBoundedInteger(raw, options) {
     const min = options.min ?? 0;
     const max = options.max ?? 1_000;
@@ -39,14 +75,40 @@ export function readBoundedInteger(raw, options) {
         return clampInteger(options.fallback, min, max);
     return clampInteger(value, min, max);
 }
+/**
+ * Parse a positive integer (min=1) from a query-parameter string.
+ *
+ * @param raw - The raw string value (or `null`).
+ * @param fallback - Default when absent or invalid.
+ * @param max - Upper bound; defaults to `1000`.
+ * @returns A clamped integer in `[1, max]`.
+ */
 export function readBoundedPositiveInteger(raw, fallback, max = 1_000) {
     return readBoundedInteger(raw, { fallback, min: 1, max });
 }
+/**
+ * Parse a bounded integer from a parsed JSON body value.
+ *
+ * @param value - The raw body value (should be `number`).
+ * @param fallback - Default when absent or non-finite.
+ * @param max - Inclusive upper bound.
+ * @param min - Inclusive lower bound; defaults to `1`.
+ * @returns A clamped integer in `[min, max]`.
+ */
 export function readBoundedBodyInteger(value, fallback, max, min = 1) {
     if (typeof value !== 'number' || !Number.isFinite(value))
         return clampInteger(fallback, min, max);
     return clampInteger(value, min, max);
 }
+/**
+ * Parse an optional bounded integer from a query-parameter string.
+ * Returns `undefined` when the parameter is absent or non-finite.
+ *
+ * @param raw - The raw string value (or `null`).
+ * @param min - Inclusive lower bound.
+ * @param max - Inclusive upper bound.
+ * @returns A clamped integer or `undefined`.
+ */
 export function readOptionalBoundedInteger(raw, min, max) {
     if (raw === null || raw.trim() === '')
         return undefined;
@@ -58,11 +120,27 @@ export function readOptionalBoundedInteger(raw, min, max) {
 function clampInteger(value, min, max) {
     return Math.min(max, Math.max(min, Math.trunc(value)));
 }
+/**
+ * Read a non-empty trimmed string from a JSON body field, returning `undefined` if absent or blank.
+ *
+ * @param body - The parsed request body.
+ * @param key - The field key to read.
+ * @returns The trimmed string, or `undefined`.
+ */
 export function readOptionalStringField(body, key) {
     const value = body[key];
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
 }
-// `max` defaults to 128, with call sites free to pass tighter domain-specific limits.
+/**
+ * Read an array of non-empty trimmed strings from a JSON body field.
+ * Entries that are not strings or are blank are skipped. Returns `undefined` when
+ * the field is absent, not an array, or all entries were invalid.
+ *
+ * @param body - The parsed request body.
+ * @param key - The field key to read.
+ * @param max - Maximum number of entries to include; defaults to `128`.
+ * @returns A non-empty string array, or `undefined`.
+ */
 export function readStringArrayField(body, key, max = 128) {
     const value = body[key];
     if (!Array.isArray(value))
@@ -78,6 +156,14 @@ export function readStringArrayField(body, key, max = 128) {
     }
     return output.length > 0 ? output : undefined;
 }
+/**
+ * Test whether a single granted scope string covers the required scope.
+ * Supports exact match, wildcard `'*'`, and prefix wildcard (e.g. `'sessions:*'`).
+ *
+ * @param granted - A scope string held by the caller.
+ * @param required - The scope the operation requires.
+ * @returns `true` if `granted` covers `required`.
+ */
 export function scopeMatches(granted, required) {
     if (granted === '*' || granted === required)
         return true;
@@ -86,14 +172,33 @@ export function scopeMatches(granted, required) {
     }
     return false;
 }
+/**
+ * Return `true` if the caller holds at least one of the required scopes.
+ *
+ * @param grantedScopes - Scopes held by the caller (or `undefined` for no scopes).
+ * @param requiredScopes - Scopes to check against.
+ */
 export function hasAnyScope(grantedScopes, requiredScopes) {
     const granted = grantedScopes ?? [];
     return requiredScopes.some((required) => granted.some((entry) => scopeMatches(entry, required)));
 }
+/**
+ * Return the subset of `requiredScopes` not covered by `grantedScopes`.
+ *
+ * @param grantedScopes - Scopes held by the caller (or `undefined` for no scopes).
+ * @param requiredScopes - The full set of required scopes.
+ * @returns An array of scope strings that are missing; empty if all are satisfied.
+ */
 export function missingScopes(grantedScopes, requiredScopes) {
     const granted = grantedScopes ?? [];
     return requiredScopes.filter((required) => !granted.some((entry) => scopeMatches(entry, required)));
 }
+/**
+ * Validate and narrow an unknown value to `ChannelLifecycleAction`.
+ *
+ * @param value - The raw input (typically from a URL path segment or body field).
+ * @returns The typed action string, or `null` if the value is not a valid action.
+ */
 export function readChannelLifecycleAction(value) {
     return value === 'inspect'
         || value === 'setup'
@@ -108,6 +213,12 @@ export function readChannelLifecycleAction(value) {
         ? value
         : null;
 }
+/**
+ * Validate and narrow an unknown value to `ChannelConversationKind`.
+ *
+ * @param value - The raw input (typically from a URL path segment or body field).
+ * @returns The typed kind string, or `null` if the value is not a valid kind.
+ */
 export function readChannelConversationKind(value) {
     return value === 'direct' || value === 'group' || value === 'channel' || value === 'thread' || value === 'service'
         ? value

package/dist/runtime-automation-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-automation-routes.d.ts","sourceRoot":"","sources":["../src/runtime-automation-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAuB1E,wBAAgB,0CAA0C,CACxD,OAAO,EAAE,yBAAyB,GACjC,oCAAoC,CAoBtC"}
+{"version":3,"file":"runtime-automation-routes.d.ts","sourceRoot":"","sources":["../src/runtime-automation-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AA4B1E,wBAAgB,0CAA0C,CACxD,OAAO,EAAE,yBAAyB,GACjC,oCAAoC,CAoBtC"}

package/dist/runtime-automation-routes.js

@@ -1,11 +1,14 @@
 import { withAdmin } from './auth-helpers.js';
 import { jsonErrorResponse } from './error-response.js';
-import { createRouteBodySchema, createRouteBodySchemaRegistry, readBoundedBodyInteger, readOptionalStringField, readStringArrayField, } from './route-helpers.js';
+import { hasPaginationParams, paginateItems } from './pagination.js';
+import { createRouteBodySchema, createRouteBodySchemaRegistry, readBoundedBodyInteger, readBoundedPositiveInteger, readOptionalStringField, readStringArrayField, } from './route-helpers.js';
+const DEFAULT_AUTOMATION_LIST_LIMIT = 100;
+const MAX_AUTOMATION_LIST_LIMIT = 500;
 export function createDaemonRuntimeAutomationRouteHandlers(context) {
     return {
-        getAutomationJobs: () => Response.json({ jobs: context.automationManager.listJobs() }),
+        getAutomationJobs: (url) => handleGetAutomationJobs(context, url),
         postAutomationJob: async (request) => withAdmin(context, request, () => handlePostSchedule(context, request)),
-        getAutomationRuns: () => Response.json({ runs: context.automationManager.listRuns() }),
+        getAutomationRuns: (url) => handleGetAutomationRuns(context, url),
         getAutomationRun: (runId) => handleGetAutomationRun(context, runId),
         getAutomationHeartbeat: () => Response.json({ pending: [] }),
         postAutomationHeartbeat: async (request) => withAdmin(context, request, () => handlePostAutomationHeartbeat(context, request)),
@@ -200,3 +203,55 @@ function findAutomationJob(context, id) {
     // exact-match only — prefix match was non-deterministic when multiple ids share a prefix.
     return context.automationManager.listJobs().find((entry) => entry.id === id);
 }
+/**
+ * Handle GET /api/automation/jobs.
+ *
+ * Without pagination params (`?limit=` / `?cursor=`): returns `{ jobs: [...] }` (backward compat).
+ * With pagination params: returns `PaginatedResponse<AutomationJobLike>` as `{ items, nextCursor, hasMore }`.
+ *
+ * ### Deletion recovery
+ * `AutomationJobLike` exposes only `{ id: string }` at the SDK boundary — there is
+ * no stable timestamp field on jobs.  Insertion-point recovery on mid-walk deletion
+ * is therefore **not available** for this endpoint; if the cursor item is deleted,
+ * the walk restarts from index 0.  If a timestamp is added to `AutomationJobLike`
+ * in the future, thread it as `getCreatedAt` here.
+ */
+function handleGetAutomationJobs(context, url) {
+    const jobs = context.automationManager.listJobs();
+    if (!url || !hasPaginationParams(url)) {
+        return Response.json({ jobs });
+    }
+    const limit = readBoundedPositiveInteger(url.searchParams.get('limit'), DEFAULT_AUTOMATION_LIST_LIMIT, MAX_AUTOMATION_LIST_LIMIT);
+    const rawCursor = url.searchParams.get('cursor');
+    const result = paginateItems(jobs, limit, rawCursor, (j) => j.id);
+    if ('error' in result) {
+        return jsonErrorResponse({ error: result.error }, { status: 400 });
+    }
+    return Response.json(result);
+}
+/**
+ * Handle GET /api/automation/runs.
+ *
+ * Without pagination params (`?limit=` / `?cursor=`): returns `{ runs: [...] }` (backward compat).
+ * With pagination params: returns `PaginatedResponse<AutomationRunLike>` as `{ items, nextCursor, hasMore }`.
+ *
+ * ### Deletion recovery
+ * `AutomationRunLike` carries a required `queuedAt: number` field which serves as
+ * the stable creation-time timestamp.  Insertion-point recovery on mid-walk
+ * deletion is **active** for this endpoint via `getCreatedAt: (r) => r.queuedAt`.
+ * Runs are listed in descending `queuedAt` order (newest first), so
+ * `descending: true` is passed to `paginateItems` for correct recovery.
+ */
+function handleGetAutomationRuns(context, url) {
+    const runs = context.automationManager.listRuns();
+    if (!url || !hasPaginationParams(url)) {
+        return Response.json({ runs });
+    }
+    const limit = readBoundedPositiveInteger(url.searchParams.get('limit'), DEFAULT_AUTOMATION_LIST_LIMIT, MAX_AUTOMATION_LIST_LIMIT);
+    const rawCursor = url.searchParams.get('cursor');
+    const result = paginateItems(runs, limit, rawCursor, (r) => r.id, (r) => r.queuedAt, { descending: true });
+    if ('error' in result) {
+        return jsonErrorResponse({ error: result.error }, { status: 400 });
+    }
+    return Response.json(result);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-daemon-sdk",
-  "version": "0.33.37",
+  "version": "0.33.38",
   "engines": {
     "bun": "1.3.10",
     "node": ">=22.0.0"
@@ -157,8 +157,8 @@
     "control-plane"
   ],
   "dependencies": {
-    "@pellux/goodvibes-contracts": "0.33.37",
-    "@pellux/goodvibes-errors": "0.33.37"
+    "@pellux/goodvibes-contracts": "0.33.38",
+    "@pellux/goodvibes-errors": "0.33.38"
   },
   "publishConfig": {
     "access": "public"