@keemakr/schedules 0.1.1-dev-20261012160211

package/README.md

@@ -0,0 +1,115 @@
+# @keemakr/schedules
+
+An agent that cannot finish now asks to be brought back later, instead of sleeping inside a run, hammering a closed door, or dropping the work.
+
+Every Pack gets this. `@keemakr/agent-sdk` exposes it as `kee.schedules`, and the `schedules:defer` scope is on every grant — deferring adds no authority, it only moves work the caller may already do to a later minute, as the same principal.
+
+## The rate-limit case
+
+```ts
+import { isRateLimited } from '@keemakr/agent-sdk';
+
+const res = await kee.connections.smartlead.call('leads.add', batch);
+if (isRateLimited(res)) {
+  return kee.schedules.resumeAfter(res, {
+    key: `place:${campaignId}`,
+    reason: 'Smartlead is rate limiting; the rest of this campaign is waiting.',
+    provider: 'smartlead',
+    state: { campaignId, remaining },
+  });
+}
+```
+
+`resumeAfter` reads the provider's own `Retry-After` off the connector result (core returns it as `retryAfter` on a 429, and remembers a per-credential backoff of its own). Nothing guesses a delay.
+
+When the window reopens, core starts a new turn for the same agent, acting as the same person, with your `state` handed back and the attempt number stated.
+
+## A plain deferral
+
+```ts
+await kee.schedules.after('20m', {
+  key: `enrich:${practiceId}`,
+  reason: 'Nothing to enrich until tonight’s sync lands.',
+  state: { practiceId },
+});
+```
+
+Durations are `'90s'`, `'20m'`, `'2h'`, `'1d'`, or a number of seconds. Anything else throws — a delay that silently resolves to zero is a hot loop.
+
+## The rules
+
+| Rule                               | Why                                                                                                                                                 |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `key` collapses repeats            | The same key while one is pending returns the standing deferral. A retry loop that defers on every attempt cannot become a swarm of timers.         |
+| `reason` is required               | It is shown to the tenant beside the pending resume. An agent that cannot say why it is coming back does not come back.                             |
+| `state` is a cursor, not a payload | 8 KB. Keep the data in a Table and the place here.                                                                                                  |
+| Attempts are capped                | A key that has come back ten times stops and raises attention. Retrying is not a plan.                                                              |
+| The horizon is a day               | Past that, the authority that asked for the work is no longer reliably the authority that gets it. Work further out needs a schedule a person owns. |
+| One install, fifty pending         | Over the budget, `after()` refuses and names the count. Something is looping.                                                                       |
+
+## Batching: when the pile is bigger than the door
+
+A connector that takes a hundred a minute and an agent holding five hundred. Retrying the whole set is the same wall five times over — so put the work down and take it back in chunks.
+
+```ts
+const batch = kee.schedules.batch('smartlead.leads.add');
+
+await batch.add(
+  leads.map((l) => ({ key: l.email, payload: l })),
+  {
+    reason: 'Smartlead will not take them all at once.',
+    provider: 'smartlead',
+    maxSize: 100, // drain as soon as this many are waiting
+    maxWait: '1h', // and no later than this, however few there are
+  },
+);
+```
+
+When the drain wakes the agent, it takes chunks and settles them:
+
+```ts
+const chunk = await batch.take(100); // leased to this run
+
+for (const item of chunk) {
+  /* place the lead */
+}
+
+await batch.done(placed.map((i) => i.id)); // landed — rows deleted
+await batch.release(refused.map((i) => i.id)); // door shut again — back in the pile
+await batch.fail([{ id, error: 'address is invalid' }]); // never going to land — kept, with why
+```
+
+Rules worth knowing:
+
+| Rule                             | Why                                                                                                                                                 |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `add` is idempotent per item key | An agent that rebuilds its list after a resume and adds it again does not double the pile.                                                          |
+| `take` leases                    | Two resumes take different work, never the same. A resume that dies mid-chunk returns its items when the lease expires, rather than stranding them. |
+| `done` deletes                   | The record of what happened is where the work landed — a Table, the provider, the trace. A scratch buffer is not an audit trail.                    |
+| An empty pile closes itself      | And its drain is cancelled, so nothing wakes an agent to look at nothing.                                                                           |
+| The drain is one deferral        | A full pile pulls that one forward; it never grows a second. Two drains would take overlapping chunks and each conclude the other had done nothing. |
+| Limits                           | 10,000 items per batch, 1,000 per add, 500 per take, 4 KB per item, 20 open batches per install.                                                    |
+
+If the door shuts again mid-pile, release the chunk you are holding and defer with the same key. What you have not settled stays in the batch.
+
+## What this cannot do
+
+Create a cadence. Standing authority to act on a clock — every Monday, every hour — belongs to a schedule with a named human owner, declared in the Pack's manifest and approved at install. No agent mints one for itself, and no scope an agent carries would let it.
+
+## Wiring it yourself
+
+The package is transport-free. `createSchedules(post)` takes anything that can reach `POST /api/capability/schedules/defer` with the run's grant, so a runtime that is not the agent SDK can expose the same surface:
+
+```ts
+import { createSchedules } from '@keemakr/schedules';
+
+const schedules = createSchedules(async (body) => {
+  const res = await fetch(`${coreUrl}/api/capability/schedules/defer`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${grant}` },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(await res.text());
+  return res.json();
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,184 @@
+/** How long to wait: seconds as a number, or a short duration like '90s', '20m', '2h'. */
+export type Duration = number | `${number}s` | `${number}m` | `${number}h` | `${number}d`;
+/**
+ * Seconds from a duration. Strings are the ergonomic form; a bare number is
+ * already seconds. Anything else throws rather than silently becoming zero — a
+ * deferral that resolves to "now" is an infinite loop wearing a delay.
+ */
+export declare function parseDuration(input: Duration): number;
+/**
+ * The shape core's connection proxy returns when a provider is pacing us — the
+ * same object `kee.connections.<p>.call()` rejects or returns on a 429. Both the
+ * provider's own Retry-After and core's tenant-budget backoff arrive here as
+ * `retryAfter` in whole seconds.
+ */
+export interface RateLimitedResult {
+    code?: string;
+    status?: number;
+    retryAfter?: number;
+    error?: string;
+}
+/** Is this a rate limit, as opposed to any other refusal? */
+export declare function isRateLimited(result: unknown): result is RateLimitedResult;
+/**
+ * How long to wait after a rate-limited result. The provider's own number when
+ * it gave one; otherwise a conservative minute — long enough that the retry is
+ * not part of the problem, short enough that a person waiting notices nothing.
+ */
+export declare const DEFAULT_BACKOFF_SECONDS = 60;
+export declare function backoffFor(result: RateLimitedResult): number;
+export interface DeferOptions {
+    /**
+     * The idempotency key. Asking twice with the same key while one is still
+     * pending returns the standing deferral instead of making a second one — so a
+     * retry loop that defers on every attempt cannot fan out into a swarm of
+     * timers. Key it on the work, not the attempt: `place:${campaignId}`.
+     */
+    key: string;
+    /** One sentence, shown to the tenant beside the pending resume. Required: an agent that cannot say why it is coming back does not come back. */
+    reason: string;
+    /** The cursor handed back on resume. Keep it small — a place, not a payload. */
+    state?: Record<string, unknown>;
+    /** The connector that paced this. `resumeAfter` fills it when you name the provider. */
+    provider?: string | null;
+    /** Which agent of the install resumes. Omit for the install's single agent. */
+    agentKey?: string | null;
+}
+export interface Deferred {
+    deferralId: string;
+    key: string;
+    /** When core will bring the agent back. */
+    resumeAt: Date;
+    /** Which attempt this is for the key. Attempts are capped; the resume says the ceiling. */
+    attempt: number;
+    /** The human the resume will act as, or null for an unattended run. */
+    actsAs: string | null;
+    /** True when an identical key was already pending and this call changed nothing. */
+    deduplicated: boolean;
+}
+export interface Schedules {
+    /** Come back after a delay, carrying `state`. */
+    after(delay: Duration, options: DeferOptions): Promise<Deferred>;
+    /** Come back when a rate-limited provider's window reopens, using its own Retry-After. */
+    resumeAfter(result: RateLimitedResult, options: DeferOptions & {
+        provider?: string | null;
+    }): Promise<Deferred>;
+    /** A named pile of work to put down now and take back in chunks later. */
+    batch(key: string): Batch;
+}
+/** The one call this package makes. Supplied by the host SDK, which owns the grant. */
+export type DeferPost = (body: {
+    key: string;
+    delay_seconds: number;
+    reason: string;
+    state: Record<string, unknown>;
+    provider: string | null;
+    agent_key: string | null;
+}) => Promise<{
+    deferral_id: string;
+    key: string;
+    resume_at: string;
+    attempt: number;
+    acts_as: string | null;
+    deduplicated: boolean;
+}>;
+/**
+ * Build the schedules surface over a caller that can reach
+ * `POST /api/capability/schedules/defer` with the run's grant.
+ *
+ * Transport-free on purpose: `@keemakr/agent-sdk` wires this to its own
+ * authenticated fetch and exposes it as `kee.schedules`, so a Pack gets it
+ * without adding a dependency, and anything else holding a grant can wire the
+ * same surface without inheriting an SDK.
+ */
+export declare function createSchedules(post: DeferPost, batchDeps?: {
+    post: BatchPost;
+    get: BatchGet;
+}): Schedules;
+export interface BatchItemInput {
+    key: string;
+    payload?: Record<string, unknown>;
+}
+export interface BatchDrainOptions {
+    /** Drain when this many are waiting. Default 100. */
+    maxSize?: number;
+    /** Drain no later than this after the batch opened. Default '1h'. */
+    maxWait?: Duration;
+    /** The connector this pile is waiting on — recorded, and shown to the tenant. */
+    provider?: string | null;
+    /** Which agent of the install resumes. Omit for the install's single agent. */
+    agentKey?: string | null;
+}
+export interface BatchAddResult {
+    batchId: string;
+    /** Items this call created. A repeat of the same item key adds nothing. */
+    added: number;
+    pending: number;
+    drainAt: Date | null;
+    /** True when the pile filled and its drain was pulled forward. */
+    drainPulledForward: boolean;
+}
+export interface LeasedItem {
+    /** Pass this back to `done`, `release` or `fail`. */
+    id: string;
+    key: string;
+    payload: Record<string, unknown>;
+    /** How many times this item has been taken. A high count is an item to look at. */
+    attempts: number;
+}
+export interface BatchSettleResult {
+    done: number;
+    released: number;
+    failed: number;
+    remaining: number;
+    /** True when the pile emptied and the batch closed itself. */
+    closed: boolean;
+}
+export interface BatchStatus {
+    batchId: string;
+    key: string;
+    status: 'open' | 'draining' | 'closed';
+    provider: string | null;
+    pending: number;
+    leased: number;
+    failed: number;
+    drainAt: Date | null;
+}
+export interface Batch {
+    /**
+     * Put work down. Idempotent per item key, so an agent that rebuilds its list
+     * after a resume and adds it again does not double the pile.
+     *
+     * `reason` is required — it is what the tenant sees beside the batch.
+     */
+    add(items: BatchItemInput[], options: {
+        reason: string;
+    } & BatchDrainOptions): Promise<BatchAddResult>;
+    /** Take a chunk, leased so a duplicate resume cannot do the same work twice. */
+    take(limit?: number, options?: {
+        leaseSeconds?: number;
+    }): Promise<LeasedItem[]>;
+    /** These landed. The rows are deleted — the record is where the work went. */
+    done(ids: string[]): Promise<BatchSettleResult>;
+    /** The door shut again. Put these back for the next drain. */
+    release(ids: string[]): Promise<BatchSettleResult>;
+    /** These will never land. Kept with the reason, so somebody can see them. */
+    fail(failures: Array<{
+        id: string;
+        error: string;
+    }>): Promise<BatchSettleResult>;
+    /** How much is piled up, and when it drains. Null when there is no live batch. */
+    status(): Promise<BatchStatus | null>;
+    /** Give up on the pile. Items go with it. */
+    close(): Promise<{
+        closed: boolean;
+        discarded: number;
+    }>;
+}
+/** The batch calls, supplied by the host SDK, which owns the grant. */
+export type BatchPost = (body: Record<string, unknown>) => Promise<Record<string, unknown>>;
+export type BatchGet = (key: string) => Promise<Record<string, unknown> | null>;
+export declare function createBatch(deps: {
+    post: BatchPost;
+    get: BatchGet;
+}, key: string): Batch;

package/dist/index.js

@@ -0,0 +1,181 @@
+// @keemakr/schedules — an agent defers its own work.
+//
+// The case this exists for, in full:
+//
+//   const res = await kee.connections.smartlead.call('leads.add', batch);
+//   if (isRateLimited(res)) {
+//     return kee.schedules.resumeAfter(res, {
+//       key: `place:${campaignId}`,
+//       reason: 'Smartlead is rate limiting; the rest of this campaign is waiting.',
+//       state: { campaignId, remaining },
+//     });
+//   }
+//
+// The agent stops, and core brings it back when the window reopens with exactly
+// that state in hand. No sleeping inside a run, no retry loop against a closed
+// door, no work quietly dropped.
+//
+// WHAT THIS IS NOT. It cannot create a cadence. Standing authority to act on a
+// clock — every Monday, every hour — belongs to a schedule a person owns, and no
+// agent mints one for itself. A deferral only moves work the caller may ALREADY
+// do to a later minute, as the same principal; that is why it needs no approval
+// and why the horizon is hours rather than months.
+const UNIT_SECONDS = { s: 1, m: 60, h: 3_600, d: 86_400 };
+/**
+ * Seconds from a duration. Strings are the ergonomic form; a bare number is
+ * already seconds. Anything else throws rather than silently becoming zero — a
+ * deferral that resolves to "now" is an infinite loop wearing a delay.
+ */
+export function parseDuration(input) {
+    if (typeof input === 'number') {
+        if (!Number.isFinite(input) || input < 0) {
+            throw new TypeError(`invalid duration: ${input}`);
+        }
+        return input;
+    }
+    const match = /^(\d+(?:\.\d+)?)([smhd])$/.exec(String(input).trim());
+    if (!match) {
+        throw new TypeError(`invalid duration '${input}' — use seconds, or '90s' / '20m' / '2h' / '1d'`);
+    }
+    return Number(match[1]) * UNIT_SECONDS[match[2]];
+}
+/** Is this a rate limit, as opposed to any other refusal? */
+export function isRateLimited(result) {
+    if (typeof result !== 'object' || result === null)
+        return false;
+    const r = result;
+    if (r.ok === true)
+        return false;
+    return r.code === 'rate_limited' || r.status === 429;
+}
+/**
+ * How long to wait after a rate-limited result. The provider's own number when
+ * it gave one; otherwise a conservative minute — long enough that the retry is
+ * not part of the problem, short enough that a person waiting notices nothing.
+ */
+export const DEFAULT_BACKOFF_SECONDS = 60;
+export function backoffFor(result) {
+    const seconds = result.retryAfter;
+    return typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0
+        ? Math.ceil(seconds)
+        : DEFAULT_BACKOFF_SECONDS;
+}
+/**
+ * Build the schedules surface over a caller that can reach
+ * `POST /api/capability/schedules/defer` with the run's grant.
+ *
+ * Transport-free on purpose: `@keemakr/agent-sdk` wires this to its own
+ * authenticated fetch and exposes it as `kee.schedules`, so a Pack gets it
+ * without adding a dependency, and anything else holding a grant can wire the
+ * same surface without inheriting an SDK.
+ */
+export function createSchedules(post, batchDeps) {
+    async function defer(delaySeconds, options) {
+        const json = await post({
+            key: options.key,
+            delay_seconds: delaySeconds,
+            reason: options.reason,
+            state: options.state ?? {},
+            provider: options.provider ?? null,
+            agent_key: options.agentKey ?? null,
+        });
+        return {
+            deferralId: json.deferral_id,
+            key: json.key,
+            resumeAt: new Date(json.resume_at),
+            attempt: json.attempt,
+            actsAs: json.acts_as,
+            deduplicated: json.deduplicated,
+        };
+    }
+    return {
+        after(delay, options) {
+            return defer(parseDuration(delay), options);
+        },
+        resumeAfter(result, options) {
+            return defer(backoffFor(result), options);
+        },
+        batch(key) {
+            if (!batchDeps) {
+                throw new Error('batching is not wired in this runtime — pass batch transport to createSchedules()');
+            }
+            return createBatch(batchDeps, key);
+        },
+    };
+}
+function settleResult(json) {
+    return {
+        done: Number(json.done ?? 0),
+        released: Number(json.released ?? 0),
+        failed: Number(json.failed ?? 0),
+        remaining: Number(json.remaining ?? 0),
+        closed: json.closed === true,
+    };
+}
+export function createBatch(deps, key) {
+    const settle = async (payload) => settleResult(await deps.post({ op: 'settle', key, ...payload }));
+    return {
+        async add(items, options) {
+            const json = await deps.post({
+                op: 'add',
+                key,
+                items: items.map((i) => ({ key: i.key, payload: i.payload ?? {} })),
+                reason: options.reason,
+                provider: options.provider ?? null,
+                agent_key: options.agentKey ?? null,
+                max_size: options.maxSize ?? 100,
+                max_wait_seconds: parseDuration(options.maxWait ?? '1h'),
+            });
+            return {
+                batchId: String(json.batch_id),
+                added: Number(json.added ?? 0),
+                pending: Number(json.pending ?? 0),
+                drainAt: json.drain_at ? new Date(String(json.drain_at)) : null,
+                drainPulledForward: json.drain_pulled_forward === true,
+            };
+        },
+        async take(limit = 100, options) {
+            const json = await deps.post({
+                op: 'take',
+                key,
+                limit,
+                ...(options?.leaseSeconds ? { lease_seconds: options.leaseSeconds } : {}),
+            });
+            const items = Array.isArray(json.items) ? json.items : [];
+            return items.map((i) => ({
+                id: String(i.id),
+                key: String(i.key),
+                payload: (i.payload ?? {}),
+                attempts: Number(i.attempts ?? 0),
+            }));
+        },
+        done(ids) {
+            return settle({ done: ids });
+        },
+        release(ids) {
+            return settle({ release: ids });
+        },
+        fail(failures) {
+            return settle({ failed: failures });
+        },
+        async status() {
+            const json = await deps.get(key);
+            if (!json)
+                return null;
+            return {
+                batchId: String(json.batch_id),
+                key: String(json.key),
+                status: json.status,
+                provider: (json.provider ?? null),
+                pending: Number(json.pending ?? 0),
+                leased: Number(json.leased ?? 0),
+                failed: Number(json.failed ?? 0),
+                drainAt: json.drain_at ? new Date(String(json.drain_at)) : null,
+            };
+        },
+        async close() {
+            const json = await deps.post({ op: 'close', key });
+            return { closed: json.closed === true, discarded: Number(json.discarded ?? 0) };
+        },
+    };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@keemakr/schedules",
+  "version": "0.1.1-dev-20261012160211",
+  "description": "Let a keemakr agent defer its own work: hit a rate limit, hand back a cursor, and be resumed when the window reopens.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fsztpartners/keemakr.git",
+    "directory": "packages/schedules"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20.9"
+  }
+}