@empyria/restate 0.4.0 → 0.4.6

package/AGENTS.md

@@ -45,6 +45,9 @@ Journal discipline is enforced by the library, not left to each agent: step meta
 only (never prompt or reply text), and tool arguments/results have byte caps (`Tools.js`). Keep both
 true when touching `Loop.js` or `Tools.js`.
 
+Block tools take `key(args, meta)` and `input(args, meta)` hooks (`meta.idempotencyKey` is unique per tool call); both must be
+total, because an exception there is a non-terminal error that Restate would retry forever.
+
 `defineAgent`'s `tools` may be a function of the request; it is evaluated outside `ctx.run` on every
 replay, so it must stay pure. `test/agent/fakes.js`'s result helpers use the AI SDK's v4 result shape
 (`finishReason: {unified, raw}`); the older plain-string form makes `generateText` report no finish reason.
@@ -75,6 +78,13 @@ may observe an already-mocked value. See `test/Admin.test.js`.
 ports, installs process-wide `SIGTERM`/`SIGINT` handlers, and its returned `forceClose` calls
 `process.exit()` — none of which are safe to exercise in-process in a test run.
 
+## Cron jobs
+
+`CronJob.ensure` is the idempotent entry point (`ensureCronJob` is its ingress client). Never make a boot-time scheduler
+with `CronJobInitiator.create`: it generates a new random job ID on every call, so each restart would add another copy.
+`ensure` compares the normalised request (`cronExpression`, `service`, `method`, `key`, `payload`) and only reschedules
+when it changed. A change here must keep `initiate`, `execute` and `cancel` behaving as before.
+
 ## Zero-dependency preference
 
 Cron parsing uses `croner` (zero dependencies), not `cron-parser` (pulls in `luxon`). If you

package/README.md

@@ -106,6 +106,21 @@ export const triage = defineAgent({
 | [lib/agent/Errors.js](./lib/agent/Errors.js) | `toRestateLLMError` (AI SDK error → terminal / `RetryableError` / transient) and the default retry policies for LLM steps, tool steps and the agent invocation.                                                                                                                                             |
 | [lib/agent/Model.js](./lib/agent/Model.js)   | `createModel` — AI SDK model for an OpenAI-compatible endpoint (e.g. Bifrost).                                                                                                                                                                                                                              |
 
+### Recurring jobs
+
+`cronJob` (a virtual object) runs a target handler on a cron schedule: each run sends the target, then schedules the
+next one from the current time, so a restart or an outage never causes a backlog of runs. Register `cronJob` on your
+endpoint, then create jobs with either:
+
+- `cronJobInitiator.create(request)`: a new job with a random ID each call (good for jobs created by users);
+- `ensureCronJob({restateURL, id, cronExpression, service, method, key?, payload?})`: **idempotent, for code that
+  starts with the application.** The job has the stable `id` you give it, so calling it on every start never adds a second
+  job: the same request changes nothing, and a changed request (another schedule, target or payload) replaces the pending
+  run under the same ID. Call it once the endpoint has registered, e.g. from `setupRestate`'s `registrationCallbackFn`.
+
+Cron expressions are `croner` patterns (five fields, or six with seconds for tests). The target handler is sent the
+`payload` as its input, or no input when there is none.
+
 ### Shaping an agent
 
 `defineAgent` options beyond the basics:
@@ -117,6 +132,13 @@ export const triage = defineAgent({
 | `label(input)`           | A terminal failure then reads `[label] message`, so a failed run says what it was working on. Code and metadata are kept; cancellations, timeouts and retryable errors are untouched.                                                      |
 | `limits.maxInputBytes`   | Largest request (JSON bytes, default 64 KB); a larger one is refused terminally (413).                                                                                                                                                     |
 
+**Keying block tools.** A block tool calls another Restate building block. Its `key(args, meta)` and `input(args, meta)`
+hooks decide the target key and the parameter from the model's arguments and a per-call idempotency key
+(`meta.idempotencyKey`, unique for every tool call). A key that is the same for several calls (e.g. `lock:<resource>`)
+makes a virtual object run those calls one at a time and queue the rest durably; a key built from the idempotency key
+makes every call independent. `input` adds what the model must not control, such as the caller or the allowed folder.
+Both hooks must not throw: validate before the run, not inside them.
+
 **Size caps on tool calls.** Tool arguments and results are journaled and replayed, so each tool has
 `maxInputBytes` (default 16 KB) and `maxOutputBytes` (default 32 KB). Oversized arguments are not run and
 the model is told why; an oversized result is replaced by an error the model sees. For an `execute` tool the

package/lib/Cron.js

@@ -1,6 +1,7 @@
 import * as restate from '@restatedev/restate-sdk'
 import { TerminalError, serde } from '@restatedev/restate-sdk'
 import { Cron } from 'croner'
+import { sendMessage } from './Admin.js'
 
 let JOB_STATE_NAME = 'empyria-job-state'
 
@@ -32,6 +33,24 @@ export const cronJob = restate.object({
 
 			return await scheduleNextExecution(ctx, request)
 		},
+		/**
+		 * Makes sure this job exists and runs the given request: an idempotent `initiate`, meant for
+		 * code that starts with the application and cannot know whether the job was created before.
+		 *
+		 * - no job yet: schedules it, as `initiate` does;
+		 * - the same request already scheduled: changes nothing and returns the current state;
+		 * - a different request (another schedule, target or payload): cancels the pending run and
+		 *   schedules the new request under the same job ID.
+		 */
+		ensure: async (ctx, request) => {
+			const wanted = normalizeRequest(request)
+			const jobState = await ctx.get(JOB_STATE_NAME)
+
+			if (jobState && sameRequest(jobState.request, wanted)) return jobState
+			if (jobState) ctx.cancel(jobState.next_execution_id)
+
+			return await scheduleNextExecution(ctx, wanted)
+		},
 		execute: async (ctx) => {
 			const jobState = await ctx.get(JOB_STATE_NAME)
 			if (!jobState) {
@@ -76,6 +95,25 @@ export const cronJob = restate.object({
 	},
 })
 
+const REQUEST_FIELDS = ['cronExpression', 'service', 'method', 'key', 'payload']
+
+/** Keeps only the fields a job request has, and checks the required ones. */
+function normalizeRequest(request) {
+	const out = {}
+	for (const field of REQUEST_FIELDS)
+		if (request?.[field] !== undefined) out[field] = request[field]
+	for (const field of ['cronExpression', 'service', 'method']) {
+		if (typeof out[field] !== 'string' || out[field].trim() === '') {
+			throw new TerminalError(`A cron job needs a non-empty "${field}".`, { errorCode: 400 })
+		}
+	}
+	return out
+}
+
+const sameRequest = (a, b) =>
+	JSON.stringify(REQUEST_FIELDS.map((f) => a?.[f] ?? null)) ===
+	JSON.stringify(REQUEST_FIELDS.map((f) => b?.[f] ?? null))
+
 const scheduleNextExecution = async (ctx, request) => {
 	// Parse cron expression
 	// Persist current date in Restate for deterministic replay
@@ -106,4 +144,30 @@ const scheduleNextExecution = async (ctx, request) => {
 	return jobState
 }
 
+/**
+ * Makes sure a recurring job exists, from outside Restate (typically right after the service registered).
+ * Safe to call on every start: the job has a stable ID, so a repeat call changes nothing and a changed
+ * request replaces the old schedule instead of adding a second job.
+ *
+ * Needs the `CronJob` object registered on an endpoint.
+ * @param {{restateURL: string, id: string, cronExpression: string, service: string, method: string, key?: string, payload?: any}} params
+ *   `id` names the job (letters, digits, `.`, `_`, `:`, `-`); `service`/`method`/`key` are the target the
+ *   job calls on each run, with `payload` as its input (none when omitted).
+ * @returns {Promise<{request: object, next_execution_time: string, next_execution_id: string}>}
+ */
+export async function ensureCronJob({ restateURL, id, ...request }) {
+	if (typeof id !== 'string' || !/^[A-Za-z0-9._:-]+$/.test(id)) {
+		throw new TypeError(
+			'ensureCronJob needs an id made of letters, digits, ".", "_", ":" and "-"',
+		)
+	}
+	return sendMessage({
+		restateURL,
+		name: 'CronJob',
+		message: 'ensure',
+		key: id,
+		payload: request,
+	})
+}
+
 export { JOB_STATE_NAME }

package/lib/agent/Tools.js

@@ -40,7 +40,13 @@ export const jsonBytes = (value) => Buffer.byteLength(JSON.stringify(value) ?? '
  * @property {object} inputSchema JSON Schema of the tool's arguments, shown to the model.
  * @property {string|{name: string}} block Target service/object/workflow, by name or definition.
  * @property {string} handler Target handler.
- * @property {(args: any) => string} [key] Virtual object / workflow key, derived from the arguments.
+ * @property {(args: any, meta: {idempotencyKey: string}) => string} [key] Virtual object / workflow key, derived from
+ *   the model's arguments and a per-call idempotency key (`<invocation id>:<step>.<index>`, unique for every tool
+ *   call). A key that is the same for several calls makes those calls run one at a time; a key built from
+ *   `meta.idempotencyKey` makes every call its own key, so they run in parallel. Must not throw.
+ * @property {(args: any, meta: {idempotencyKey: string}) => any} [input] Builds the parameter sent to the target
+ *   handler from the model's arguments, for adding what the model must not control (who the caller is, which
+ *   folder is allowed) or the idempotency key. Default: the arguments as they are. Must not throw.
  * @property {ApprovalSpec} [approval]
  * @property {number} [maxInputBytes] Largest accepted arguments (JSON bytes). Default
  *   {@link DEFAULT_TOOL_MAX_INPUT_BYTES}. A larger call is not made; the model is told why.
@@ -88,6 +94,11 @@ export function assertToolSpecs(tools) {
 		if (isBlock && typeof spec.handler !== 'string') {
 			throw new TypeError(`Block tool '${name}' needs a 'handler'`)
 		}
+		for (const hook of ['key', 'input']) {
+			if (spec[hook] !== undefined && typeof spec[hook] !== 'function') {
+				throw new TypeError(`Tool '${name}': ${hook} must be a function`)
+			}
+		}
 		for (const cap of ['maxInputBytes', 'maxOutputBytes']) {
 			if (spec[cap] !== undefined && !(Number.isInteger(spec[cap]) && spec[cap] > 0)) {
 				throw new TypeError(`Tool '${name}': ${cap} must be a positive integer`)
@@ -187,14 +198,12 @@ export async function executeTool(ctx, call, { tools, loadSkill, step, index })
 			}
 		}
 
+		const meta = { idempotencyKey: `${ctx.request().id}:${stepId}` }
 		const value = spec.execute
 			? await ctx.run(
 					`tool:${call.toolName}-${stepId}`,
 					async () => {
-						const result =
-							(await spec.execute(call.input, {
-								idempotencyKey: `${ctx.request().id}:${stepId}`,
-							})) ?? null
+						const result = (await spec.execute(call.input, meta)) ?? null
 						assertOutputSize(call.toolName, result, maxOut)
 						return result
 					},
@@ -203,8 +212,8 @@ export async function executeTool(ctx, call, { tools, loadSkill, step, index })
 			: await ctx.genericCall({
 					service: targetName(spec.block),
 					method: spec.handler,
-					key: spec.key?.(call.input),
-					parameter: call.input,
+					key: spec.key?.(call.input, meta),
+					parameter: spec.input ? spec.input(call.input, meta) : call.input,
 					inputSerde: serde.json,
 					outputSerde: serde.json,
 				})

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@empyria/restate",
-	"version": "0.4.0",
+	"version": "0.4.6",
 	"description": "Restate.dev helpers for the Empyria nanoservice framework",
 	"license": "MIT",
 	"author": "Imre Fazekas <imre.fazekas@icloud.com>",

package/test/Cron.test.js

@@ -1,5 +1,11 @@
-import { describe, test, expect } from 'bun:test'
-import { cronJobInitiator, cronJob, setJobStateName, JOB_STATE_NAME } from '../lib/Cron.js'
+import { afterEach, describe, test, expect } from 'bun:test'
+import {
+	cronJobInitiator,
+	cronJob,
+	ensureCronJob,
+	setJobStateName,
+	JOB_STATE_NAME,
+} from '../lib/Cron.js'
 import { TerminalError } from '@restatedev/restate-sdk'
 
 describe('setJobStateName', () => {
@@ -30,8 +36,11 @@ describe('cronJobInitiator.create', () => {
 // wiring; this factory keeps the mocked context consistent across tests.
 function makeSchedulingCtx({ existing } = {}) {
 	const sets = []
+	const cancelled = []
 	return {
 		sets,
+		cancelled,
+		cancel: (invocationId) => cancelled.push(invocationId),
 		get: async () => existing,
 		date: { now: async () => Date.now() },
 		key: 'job-1',
@@ -149,3 +158,136 @@ describe('cronJob.getInfo', () => {
 		expect(await cronJob.object.getInfo(ctx)).toEqual({ request: {} })
 	})
 })
+
+describe('cronJob.ensure', () => {
+	const request = { cronExpression: '* * * * *', service: 'ReportService', method: 'refresh' }
+
+	test('schedules a job that does not exist yet', async () => {
+		const ctx = makeSchedulingCtx()
+		const state = await cronJob.object.ensure(ctx, request)
+		expect(state.request).toEqual(request)
+		expect(state.next_execution_id).toBe('exec-inv-1')
+		expect(ctx.sets).toEqual([[JOB_STATE_NAME, state]])
+		expect(ctx.cancelled).toEqual([])
+	})
+
+	test('the same request again changes nothing: no second schedule, no cancel', async () => {
+		const existing = { request, next_execution_time: 'T', next_execution_id: 'inv-old' }
+		const ctx = makeSchedulingCtx({ existing })
+		expect(await cronJob.object.ensure(ctx, request)).toBe(existing)
+		expect(ctx.sets).toEqual([])
+		expect(ctx.cancelled).toEqual([])
+	})
+
+	test('unknown fields and field order do not make a request "different"', async () => {
+		const existing = { request, next_execution_time: 'T', next_execution_id: 'inv-old' }
+		const ctx = makeSchedulingCtx({ existing })
+		const same = {
+			method: 'refresh',
+			extra: 'ignored',
+			service: 'ReportService',
+			cronExpression: '* * * * *',
+		}
+		expect(await cronJob.object.ensure(ctx, same)).toBe(existing)
+		expect(ctx.sets).toEqual([])
+	})
+
+	test('a changed schedule cancels the pending run and schedules the new one under the same job', async () => {
+		const existing = { request, next_execution_time: 'T', next_execution_id: 'inv-old' }
+		const ctx = makeSchedulingCtx({ existing })
+		const state = await cronJob.object.ensure(ctx, {
+			...request,
+			cronExpression: '*/5 * * * *',
+		})
+		expect(ctx.cancelled).toEqual(['inv-old'])
+		expect(state.request.cronExpression).toBe('*/5 * * * *')
+		expect(ctx.sets).toHaveLength(1)
+	})
+
+	test('a changed target or payload also replaces the job', async () => {
+		const existing = { request, next_execution_time: 'T', next_execution_id: 'inv-old' }
+		for (const change of [{ method: 'other' }, { payload: { a: 1 } }, { key: 'k' }]) {
+			const ctx = makeSchedulingCtx({ existing })
+			await cronJob.object.ensure(ctx, { ...request, ...change })
+			expect(ctx.cancelled).toEqual(['inv-old'])
+		}
+	})
+
+	test('a request without a schedule, service or method is refused (400)', async () => {
+		for (const bad of [
+			{},
+			{ ...request, cronExpression: '' },
+			{ ...request, service: undefined },
+			{ ...request, method: 3 },
+		]) {
+			const error = await cronJob.object.ensure(makeSchedulingCtx(), bad).catch((e) => e)
+			expect(error).toBeInstanceOf(TerminalError)
+			expect(error.code).toBe(400)
+		}
+	})
+
+	test('an invalid cron expression is a terminal error and leaves an existing job alone', async () => {
+		const ctx = makeSchedulingCtx()
+		await expect(
+			cronJob.object.ensure(ctx, { ...request, cronExpression: 'not a cron' }),
+		).rejects.toThrow(TerminalError)
+		expect(ctx.sets).toEqual([])
+	})
+})
+
+describe('ensureCronJob', () => {
+	const realFetch = globalThis.fetch
+	afterEach(() => {
+		globalThis.fetch = realFetch
+	})
+
+	test('calls CronJob/<id>/ensure through the ingress with the request as the body', async () => {
+		const calls = []
+		globalThis.fetch = async (url, init) => {
+			calls.push([url, JSON.parse(init.body)])
+			return new Response(JSON.stringify({ next_execution_time: 'T' }), { status: 200 })
+		}
+		const state = await ensureCronJob({
+			restateURL: 'http://restate:8080',
+			id: 'reports:refresh',
+			cronExpression: '* * * * *',
+			service: 'ReportService',
+			method: 'refresh',
+		})
+		expect(state).toEqual({ next_execution_time: 'T' })
+		expect(calls).toEqual([
+			[
+				'http://restate:8080/CronJob/reports:refresh/ensure',
+				{ cronExpression: '* * * * *', service: 'ReportService', method: 'refresh' },
+			],
+		])
+	})
+
+	test('refuses an id that is not safe in a URL path', async () => {
+		for (const id of ['', 'a/b', 'a b', 'a?b', undefined]) {
+			await expect(
+				ensureCronJob({
+					restateURL: 'http://x',
+					id,
+					cronExpression: '* * * * *',
+					service: 's',
+					method: 'm',
+				}),
+			).rejects.toThrow(TypeError)
+		}
+	})
+
+	test('a failed call is an error for the caller', async () => {
+		globalThis.fetch = async () =>
+			new Response('nope', { status: 500, statusText: 'Internal Server Error' })
+		await expect(
+			ensureCronJob({
+				restateURL: 'http://x',
+				id: 'j',
+				cronExpression: '* * * * *',
+				service: 's',
+				method: 'm',
+			}),
+		).rejects.toThrow('500')
+	})
+})

package/test/agent/Tools.test.js

@@ -334,3 +334,64 @@ describe('tool size caps', () => {
 		})
 	})
 })
+
+describe('block tool key and input hooks', () => {
+	const base = { description: 'd', inputSchema: schema, block: 'Runner', handler: 'run' }
+
+	test('key and input receive the arguments and a per-call idempotency key', async () => {
+		const ctx = fakeCtx({ onCall: () => ({ ok: true }) })
+		const seen = []
+		const tools = {
+			t: {
+				...base,
+				key: (args, meta) => (seen.push(['key', args, meta]), `lock:${args.folder}`),
+				input: (args, meta) => (
+					seen.push(['input', args, meta]),
+					{ ...args, idempotencyKey: meta.idempotencyKey, who: 'caller' }
+				),
+			},
+		}
+
+		await executeTool(ctx, call('t', { folder: '/a' }), { tools, ...at })
+
+		expect(ctx.calls[0].key).toBe('lock:/a')
+		expect(ctx.calls[0].parameter).toEqual({
+			folder: '/a',
+			idempotencyKey: 'inv-1:2.1',
+			who: 'caller',
+		})
+		expect(seen.map(([name]) => name)).toEqual(['key', 'input'])
+		expect(seen[0][2]).toEqual({ idempotencyKey: 'inv-1:2.1' })
+	})
+
+	test('a key built from the idempotency key is different for every call', async () => {
+		const ctx = fakeCtx({ onCall: () => null })
+		const tools = { t: { ...base, key: (_, meta) => `idem:${meta.idempotencyKey}` } }
+		await executeTool(ctx, call('t'), { tools, step: 0, index: 0 })
+		await executeTool(ctx, call('t'), { tools, step: 0, index: 1 })
+		await executeTool(ctx, call('t'), { tools, step: 1, index: 0 })
+		expect(new Set(ctx.calls.map((c) => c.key)).size).toBe(3)
+	})
+
+	test('a key shared by several calls is the same key', async () => {
+		const ctx = fakeCtx({ onCall: () => null })
+		const tools = { t: { ...base, key: (args) => `skill:${args.skill}` } }
+		await executeTool(ctx, call('t', { skill: 'a' }), { tools, step: 0, index: 0 })
+		await executeTool(ctx, call('t', { skill: 'a' }), { tools, step: 1, index: 0 })
+		expect(ctx.calls[0].key).toBe(ctx.calls[1].key)
+	})
+
+	test('without hooks, behaviour is unchanged: arguments are the parameter, no key', async () => {
+		const ctx = fakeCtx({ onCall: () => null })
+		await executeTool(ctx, call('t', { x: 1 }), { tools: { t: base }, ...at })
+		expect(ctx.calls[0]).toMatchObject({ key: undefined, parameter: { x: 1 } })
+	})
+
+	test('assertToolSpecs rejects hooks that are not functions', () => {
+		expect(() => assertToolSpecs({ t: { ...base, key: 'x' } })).toThrow(TypeError)
+		expect(() => assertToolSpecs({ t: { ...base, input: {} } })).toThrow(TypeError)
+		expect(() =>
+			assertToolSpecs({ t: { ...base, key: () => 'k', input: (a) => a } }),
+		).not.toThrow()
+	})
+})