loopengine 0.2.2 → 0.3.1

package/README.md

@@ -121,7 +121,7 @@ code changes or redeploy needed for most of it:
 | **Tools** | Your hand-written tools, tools from integrations (e.g. [Composio](https://composio.dev)) and subagents, with whether each call runs on its own, asks first, or is denied. Build an HTTP tool or connect an integration without touching a file. |
 | **Skills** | Create, edit, and delete `SKILL.md` files for this agent directly in the browser — write the body, preview the rendered markdown, save. |
 | **Permissions** | Add, edit, and delete permission rules (actauth) — who, tool, decision — and choose what happens when no rule matches. |
-| **Schedules** | Messages the agent receives on a timer — once at a set time, or every N minutes/hours/days. Run now, pause, resume, cancel, see each run's result, and optionally send results through the agent's notifier. |
+| **Schedules** | One of the agent's workflows (with values for its parameters), or a custom message, run on a timer — once at a set time, or every N minutes/hours/days. A workflow schedule starts each run with the workflow's start message and steps as they are then. Run now, pause, resume, cancel, see each run's result, and optionally send results through the agent's notifier. |
 | **Environment** | Every setting an installed ability reads, with its project-wide value and this agent's own value side by side, and which one the agent actually uses. A secret is never shown again once set. |
 
 Models and Integrations in the sidebar show which model providers have a

package/dist/core/run-agent.js

@@ -302,7 +302,7 @@ async function buildTurnContext(config, modelCall, options) {
     // Bound to this agent: it can schedule, list and cancel only its own
     // tasks (see core/system-tools/schedule.ts). AgentConfig.selfScheduling
     // false leaves them out.
-    const scheduleTools = config.selfScheduling === false ? [] : createScheduleTools(config.name);
+    const scheduleTools = config.selfScheduling === false ? [] : createScheduleTools(config.name, { agentDir: agentDirFor(config) });
     const tools = dedupeToolsByName([
         ...systemTools,
         askUserTool,
@@ -423,6 +423,11 @@ async function buildTurnContext(config, modelCall, options) {
                         type: 'string',
                         description: 'Optional arguments for the skill body — substituted for $ARGUMENTS/$1/$2 placeholders.',
                     },
+                    params: {
+                        type: 'object',
+                        description: 'Optional named values for a skill that takes them, e.g. { "order_number": "4821" }: each fills that $name in the skill body.',
+                        additionalProperties: { type: 'string' },
+                    },
                 },
                 required: ['skill'],
             },
@@ -618,7 +623,11 @@ async function runLoop(ctx, messages, newMessages, starterMessage) {
             // scheduling — but it's still a tool_use block the model emitted,
             // so it still needs a tool_result to answer it, same as any other.
             if (block.name === 'Skill' && skillGarden) {
-                const body = skillGarden.invoke(block.input.skill, block.input?.args);
+                const rawParams = block.input?.params;
+                const params = rawParams && typeof rawParams === 'object' && !Array.isArray(rawParams)
+                    ? Object.fromEntries(Object.entries(rawParams).filter(([, v]) => v !== undefined && v !== null).map(([k, v]) => [k, String(v)]))
+                    : undefined;
+                const body = skillGarden.invoke(block.input.skill, block.input?.args, params);
                 log({ type: 'skill:loaded', skill: block.input.skill });
                 resultBlocks.push({ type: 'tool_result', tool_use_id: block.id, content: body });
                 continue;

package/dist/core/run-callbacks.d.ts

@@ -0,0 +1,39 @@
+export declare class CallbackUrlError extends Error {
+}
+export type RunCallbackEvent = 'run.done' | 'run.failed' | 'run.awaiting_approval';
+/** Whether an IP address is private, loopback, link-local or otherwise
+ * not on the public internet. */
+export declare function isPrivateAddress(address: string): boolean;
+/** Checks a callback URL as given; returns it normalised. Throws
+ * CallbackUrlError saying what's wrong. */
+export declare function checkCallbackUrl(raw: unknown): string;
+/** The workspace's callback secret: LOOPENGINE_CALLBACK_SECRET, or one
+ * made once and kept in the scheduler's folder. */
+export declare function callbackSecret(): string;
+/** The signature header for a body sent at `timestamp` (unix seconds). */
+export declare function signCallback(body: string, timestamp: number, secret?: string): string;
+export interface CallbackDelivery {
+    event: RunCallbackEvent;
+    delivered: boolean;
+    attempts: number;
+    status_code?: number;
+    error?: string;
+    at: string;
+}
+export interface DeliverOptions {
+    /** Waits between attempts, in ms; its length + 1 is the attempts made. */
+    backoffMs?: number[];
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/** Posts `payload` to `url` for `event`, retrying a failed attempt (an
+ * error, or a status other than 2xx) after each wait in backoffMs. The
+ * host is looked up first, and a private address is refused (unless
+ * local callbacks are allowed), so a public name can't lead inward. */
+export declare function deliverCallback(url: string, event: RunCallbackEvent, payload: unknown, options?: DeliverOptions): Promise<CallbackDelivery>;
+/** What a run's callback carries: the event and the run's record, without
+ * its session id, its first message or past callback deliveries. */
+export declare function runCallbackPayload(event: RunCallbackEvent, run: object): {
+    event: RunCallbackEvent;
+    run: Record<string, unknown>;
+};

package/dist/core/run-callbacks.js

@@ -0,0 +1,125 @@
+// Callbacks for workflow runs started over the API: a run started with
+// "callback_url" has its record posted there when it finishes, fails, or
+// stops for an approval or a question (core/workflow-runs.ts calls
+// deliverRunCallback for each of those).
+//
+// Each POST carries
+//   X-LoopEngine-Event: run.done | run.failed | run.awaiting_approval
+//   X-LoopEngine-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">
+// signed with the workspace's callback secret: LOOPENGINE_CALLBACK_SECRET,
+// or one made once and kept in the scheduler's folder
+// (GET /runs/callback-secret shows it). A receiver checks the signature
+// and that t is recent.
+//
+// Only https URLs on public addresses are accepted, so a run can't be
+// pointed at the workspace's own network. LOOPENGINE_ALLOW_LOCAL_CALLBACKS=1
+// also allows http and local addresses, for development.
+import { createHmac, randomBytes } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isIP } from 'node:net';
+import path from 'node:path';
+export class CallbackUrlError extends Error {
+}
+function allowLocal() {
+    return process.env.LOOPENGINE_ALLOW_LOCAL_CALLBACKS === '1';
+}
+/** Whether an IP address is private, loopback, link-local or otherwise
+ * not on the public internet. */
+export function isPrivateAddress(address) {
+    const ip = address.toLowerCase().replace(/^\[|\]$/g, '');
+    const v4 = ip.startsWith('::ffff:') ? ip.slice(7) : ip;
+    if (isIP(v4) === 4) {
+        const [a, b] = v4.split('.').map(Number);
+        return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254) ||
+            (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || a >= 224;
+    }
+    if (isIP(ip) === 6) {
+        return ip === '::' || ip === '::1' || /^f[cd]/.test(ip) || /^fe[89ab]/.test(ip) || ip.startsWith('ff');
+    }
+    return false;
+}
+/** Checks a callback URL as given; returns it normalised. Throws
+ * CallbackUrlError saying what's wrong. */
+export function checkCallbackUrl(raw) {
+    if (typeof raw !== 'string' || !raw.trim())
+        throw new CallbackUrlError('callback_url must be a URL, e.g. "https://example.com/hooks/loopengine"');
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        throw new CallbackUrlError(`callback_url "${raw}" isn't a URL`);
+    }
+    const host = url.hostname.toLowerCase();
+    const local = host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.internal') || host.endsWith('.local') || isPrivateAddress(host);
+    if (url.protocol !== 'https:' && !(allowLocal() && url.protocol === 'http:'))
+        throw new CallbackUrlError('callback_url must use https');
+    if (local && !allowLocal())
+        throw new CallbackUrlError('callback_url must be a public address, not a local or private one');
+    if (url.username || url.password)
+        throw new CallbackUrlError('callback_url must not carry a username or password; check the signature instead');
+    return url.toString();
+}
+/** The workspace's callback secret: LOOPENGINE_CALLBACK_SECRET, or one
+ * made once and kept in the scheduler's folder. */
+export function callbackSecret() {
+    if (process.env.LOOPENGINE_CALLBACK_SECRET)
+        return process.env.LOOPENGINE_CALLBACK_SECRET;
+    const dir = process.env.LOOPENGINE_SCHEDULER_DIR || path.join(process.cwd(), '.scheduler');
+    const file = path.join(dir, 'callback-secret');
+    if (existsSync(file))
+        return readFileSync(file, 'utf8').trim();
+    mkdirSync(dir, { recursive: true });
+    const secret = randomBytes(32).toString('hex');
+    writeFileSync(file, secret + '\n', { mode: 0o600 });
+    return secret;
+}
+/** The signature header for a body sent at `timestamp` (unix seconds). */
+export function signCallback(body, timestamp, secret = callbackSecret()) {
+    return `t=${timestamp},v1=${createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')}`;
+}
+/** Posts `payload` to `url` for `event`, retrying a failed attempt (an
+ * error, or a status other than 2xx) after each wait in backoffMs. The
+ * host is looked up first, and a private address is refused (unless
+ * local callbacks are allowed), so a public name can't lead inward. */
+export async function deliverCallback(url, event, payload, options = {}) {
+    const backoff = options.backoffMs ?? [2_000, 10_000, 30_000];
+    const doFetch = options.fetch ?? fetch;
+    const body = JSON.stringify(payload);
+    let last = { event, delivered: false, attempts: 0, at: new Date().toISOString() };
+    for (let attempt = 0; attempt <= backoff.length; attempt++) {
+        if (attempt > 0)
+            await new Promise((r) => setTimeout(r, backoff[attempt - 1]));
+        const at = new Date().toISOString();
+        try {
+            if (!allowLocal()) {
+                const addresses = await lookup(new URL(url).hostname, { all: true });
+                if (addresses.some((a) => isPrivateAddress(a.address))) {
+                    return { event, delivered: false, attempts: attempt + 1, error: 'The callback address leads to a private network.', at };
+                }
+            }
+            const timestamp = Math.floor(Date.now() / 1000);
+            const response = await doFetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'x-loopengine-event': event, 'x-loopengine-signature': signCallback(body, timestamp), 'user-agent': 'LoopEngine-Callback/1' },
+                body,
+                signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+                redirect: 'manual',
+            });
+            last = { event, delivered: response.ok, attempts: attempt + 1, status_code: response.status, at, ...(response.ok ? {} : { error: `It answered ${response.status}.` }) };
+            if (response.ok)
+                return last;
+        }
+        catch (err) {
+            last = { event, delivered: false, attempts: attempt + 1, error: err instanceof Error ? err.message : String(err), at };
+        }
+    }
+    return last;
+}
+/** What a run's callback carries: the event and the run's record, without
+ * its session id, its first message or past callback deliveries. */
+export function runCallbackPayload(event, run) {
+    const { session_id: _session, message: _message, callbacks: _callbacks, ...rest } = run;
+    return { event, run: rest };
+}

package/dist/core/scheduler.d.ts

@@ -20,7 +20,15 @@ export interface ScheduledTask {
     task_id: string;
     task_name?: string;
     agent: string;
+    /** What the agent receives each run. Empty for a workflow task, which
+     * sends its workflow's start message instead. */
     message: string;
+    /** Set on a workflow task: each run starts this workflow of the
+     * agent's (core/workflows.ts) as it is at run time, so editing the
+     * workflow changes what the next run does. */
+    workflow_id?: string;
+    /** The workflow's parameters for every run of this task. */
+    params?: Record<string, string>;
     schedule: Schedule;
     status: ScheduledTaskStatus;
     created_at: string;
@@ -74,9 +82,20 @@ export declare class FileSchedulerStore implements SchedulerStore {
  * LOOPENGINE_SCHEDULER_DIR. */
 export declare function getSchedulerStore(): SchedulerStore;
 export declare function setSchedulerStore(next: SchedulerStore): void;
+/** The message a workflow run starts with, worked out at run time;
+ * undefined when the agent has no such workflow (any more). It may throw
+ * when the task's params no longer fit the workflow. Supplied by the
+ * server, which knows where agents' workflows are kept. */
+export type ResolveWorkflowMessage = (agent: string, workflowId: string, params: Record<string, string>) => string | undefined | Promise<string | undefined>;
 export interface CreateScheduledTaskInput {
     agent: string;
-    message: string;
+    /** A custom message, or… */
+    message?: string;
+    /** …one of the agent's workflows, by id. Exactly one of the two. The
+     * caller checks the workflow exists and the params fit it; the
+     * scheduler only stores them. */
+    workflow_id?: string;
+    params?: Record<string, string>;
     /** `start_at` (with `every` only): when the first run is, and so the
      * time of day / day of week every later run keeps, e.g. every "1d"
      * from "2026-11-02T09:00:00+08:00" runs daily at 9:00. A start in the
@@ -105,6 +124,9 @@ export declare function getScheduledTask(taskId: string): Promise<ScheduledTask
  * approval isn't retracted. */
 export declare function cancelScheduledTask(taskId: string): Promise<ScheduledTask>;
 export declare function pauseScheduledTask(taskId: string): Promise<ScheduledTask>;
+/** Turns sending each run's result through the agent's notifier on or
+ * off, from the next run. */
+export declare function setScheduledTaskNotify(taskId: string, notify: boolean): Promise<ScheduledTask>;
 export declare function resumeScheduledTask(taskId: string, nowMs?: number): Promise<ScheduledTask>;
 /** Fires the task on the next tick, without changing its schedule. A
  * finished one-off task runs once more. */
@@ -135,12 +157,14 @@ export type FireTask = (task: ScheduledTask, sessionId: string) => Promise<{
 }>;
 export declare class Scheduler {
     private readonly fire;
+    private readonly resolveWorkflowMessage?;
     private readonly tickMs;
     private readonly onSettled?;
     private readonly inFlight;
     private timer?;
     constructor(options: {
         fire: FireTask;
+        resolveWorkflowMessage?: ResolveWorkflowMessage;
         tickMs?: number;
         onSettled?: (task: ScheduledTask, run: ScheduledTaskRun) => void;
     });
@@ -154,6 +178,10 @@ export declare class Scheduler {
      * request calls it directly). */
     tick(nowMs?: number): Promise<number>;
     private run;
+    /** The task as it fires: a workflow task gets its workflow's start
+     * message as it is now. A workflow that's gone fails the run, rather
+     * than sending a stale or empty message. */
+    private withMessage;
     /** A paused run resumed after a decision (adapters/http.ts calls this
      * from the resolve path): settle it, or record the next decision it's
      * now waiting on. */

package/dist/core/scheduler.js

@@ -141,8 +141,12 @@ export function setSchedulerStore(next) {
 export async function createScheduledTask(input, nowMs = Date.now()) {
     if (!input.agent)
         throw new ScheduleError('agent is required');
-    if (!input.message?.trim())
-        throw new ScheduleError('message is required');
+    const message = typeof input.message === 'string' ? input.message : '';
+    const workflowId = typeof input.workflow_id === 'string' ? input.workflow_id.trim() : '';
+    if (message.trim() && workflowId)
+        throw new ScheduleError('give either a message or a workflow_id, not both');
+    if (!message.trim() && !workflowId)
+        throw new ScheduleError('message or workflow_id is required');
     let schedule;
     let nextRunMs;
     const timeZone = workspaceTimeZone();
@@ -197,7 +201,9 @@ export async function createScheduledTask(input, nowMs = Date.now()) {
         task_id: randomUUID(),
         task_name: input.task_name?.trim() || undefined,
         agent: input.agent,
-        message: input.message,
+        message: workflowId ? '' : message,
+        ...(workflowId ? { workflow_id: workflowId } : {}),
+        ...(workflowId && input.params && Object.keys(input.params).length ? { params: input.params } : {}),
         schedule,
         status: 'scheduled',
         created_at: new Date(nowMs).toISOString(),
@@ -228,6 +234,11 @@ export async function cancelScheduledTask(taskId) {
 export async function pauseScheduledTask(taskId) {
     return mustExist(await getSchedulerStore().update(taskId, (t) => (t && t.status === 'scheduled' ? { ...t, status: 'paused', next_run_at: undefined } : t)), taskId);
 }
+/** Turns sending each run's result through the agent's notifier on or
+ * off, from the next run. */
+export async function setScheduledTaskNotify(taskId, notify) {
+    return mustExist(await getSchedulerStore().update(taskId, (t) => t && { ...t, notify: notify || undefined }), taskId);
+}
 export async function resumeScheduledTask(taskId, nowMs = Date.now()) {
     return mustExist(await getSchedulerStore().update(taskId, (t) => {
         if (!t || t.status !== 'paused')
@@ -343,12 +354,14 @@ async function importLegacyAbilityTasks() {
 }
 export class Scheduler {
     fire;
+    resolveWorkflowMessage;
     tickMs;
     onSettled;
     inFlight = new Set();
     timer;
     constructor(options) {
         this.fire = options.fire;
+        this.resolveWorkflowMessage = options.resolveWorkflowMessage;
         this.tickMs = options.tickMs ?? (Number(process.env.LOOPENGINE_SCHEDULER_TICK_MS) || 10_000);
         this.onSettled = options.onSettled;
     }
@@ -392,7 +405,7 @@ export class Scheduler {
             return;
         const sessionId = `sched-${taskId.slice(0, 8)}-${claimed.run_count + 1}-${Date.now().toString(36)}`;
         try {
-            const outcome = await this.fire(claimed, sessionId);
+            const outcome = await this.fire(await this.withMessage(claimed), sessionId);
             if (outcome.kind === 'pending') {
                 await getSchedulerStore().update(taskId, (t) => t && {
                     ...t,
@@ -410,6 +423,17 @@ export class Scheduler {
             await this.settle(taskId, ranAt, { status: 'error', error: err instanceof Error ? err.message : String(err), session_id: sessionId });
         }
     }
+    /** The task as it fires: a workflow task gets its workflow's start
+     * message as it is now. A workflow that's gone fails the run, rather
+     * than sending a stale or empty message. */
+    async withMessage(task) {
+        if (!task.workflow_id)
+            return task;
+        const message = this.resolveWorkflowMessage ? await this.resolveWorkflowMessage(task.agent, task.workflow_id, task.params ?? {}) : undefined;
+        if (!message?.trim())
+            throw new ScheduleError(`The workflow "${task.workflow_id}" is no longer on ${task.agent}; cancel this schedule or schedule another workflow.`);
+        return { ...task, message };
+    }
     /** A paused run resumed after a decision (adapters/http.ts calls this
      * from the resolve path): settle it, or record the next decision it's
      * now waiting on. */

package/dist/core/skillgarden/loader.d.ts

@@ -23,7 +23,11 @@ export declare class SkillGarden {
     load(name: string): LoadedSkill;
     /** Load + substitute placeholders, ready to inject into a running
      * conversation. */
-    invoke(name: string, args?: string): string;
+    /** A skill's body for the model, with `params` filled into its
+     * `$name` placeholders (those its front matter declares under
+     * `parameters` become empty when not given) and `args` into
+     * `$ARGUMENTS`/`$1`… */
+    invoke(name: string, args?: string, params?: Record<string, string>): string;
     /** Filters index entries down to skills eligible given files touched
      * so far in the session. Skills with no `paths` restriction are always
      * eligible. */

package/dist/core/skillgarden/loader.js

@@ -3,7 +3,7 @@ import { matchesActivationPaths } from './activation.js';
 import { buildBudgetedIndex, estimateTokens } from './budget.js';
 import { discoverSkillFiles } from './discovery.js';
 import { parseSkillFile } from './frontmatter.js';
-import { substituteArguments } from './substitute.js';
+import { substituteArguments, substituteParameters } from './substitute.js';
 /** Phase 1: scan + parse frontmatter only, budget-capped — this is what
  * stays loaded in context at all times. Phase 2 (`load`/`invoke`) reads
  * the full body lazily, only for a skill actually being invoked. */
@@ -52,9 +52,16 @@ export class SkillGarden {
     }
     /** Load + substitute placeholders, ready to inject into a running
      * conversation. */
-    invoke(name, args) {
+    /** A skill's body for the model, with `params` filled into its
+     * `$name` placeholders (those its front matter declares under
+     * `parameters` become empty when not given) and `args` into
+     * `$ARGUMENTS`/`$1`… */
+    invoke(name, args, params) {
         const skill = this.load(name);
-        return substituteArguments(skill.body, args);
+        const declaredSpec = skill.frontmatter.parameters;
+        const declared = declaredSpec && typeof declaredSpec === 'object' && !Array.isArray(declaredSpec) ? Object.keys(declaredSpec) : [];
+        const named = params || declared.length ? substituteParameters(skill.body, params ?? {}, { declared }) : skill.body;
+        return substituteArguments(named, args);
     }
     /** Filters index entries down to skills eligible given files touched
      * so far in the session. Skills with no `paths` restriction are always

package/dist/core/skillgarden/substitute.d.ts

@@ -1,4 +1,18 @@
 /** Replaces `$ARGUMENTS` with the raw args string, and `$1`/`$2`/... with
  * whitespace-split positional args — the same placeholder convention
- * skill authors already expect from Claude Code's own Skill tool. */
+ * skill authors already expect from Claude Code's own Skill tool.
+ *
+ * A `$N` is filled only when that argument was given: with two args, `$1`
+ * and `$2` are, while `$3` and a dollar amount like `$50` stay as
+ * written; with none, nothing positional changes. `$$1` is a literal
+ * "$1", for a skill that takes args and mentions one. One pass, so an
+ * argument's own text is never filled in again. */
 export declare function substituteArguments(body: string, args?: string): string;
+/** Replaces `$name` placeholders (lowercase, e.g. `$order_number`) with
+ * named parameters. A name in `declared` that wasn't given becomes empty
+ * text; any other `$word` is left as it is, so `$ARGUMENTS`, `$1` and
+ * dollar amounts are untouched. Names it fills are added to `used`. */
+export declare function substituteParameters(body: string, params: Record<string, string>, options?: {
+    declared?: string[];
+    used?: Set<string>;
+}): string;

package/dist/core/skillgarden/substitute.js

@@ -1,13 +1,35 @@
 /** Replaces `$ARGUMENTS` with the raw args string, and `$1`/`$2`/... with
  * whitespace-split positional args — the same placeholder convention
- * skill authors already expect from Claude Code's own Skill tool. */
+ * skill authors already expect from Claude Code's own Skill tool.
+ *
+ * A `$N` is filled only when that argument was given: with two args, `$1`
+ * and `$2` are, while `$3` and a dollar amount like `$50` stay as
+ * written; with none, nothing positional changes. `$$1` is a literal
+ * "$1", for a skill that takes args and mentions one. One pass, so an
+ * argument's own text is never filled in again. */
 export function substituteArguments(body, args) {
     const argString = args ?? '';
-    let result = body.replaceAll('$ARGUMENTS', argString);
     const positional = argString.split(/\s+/).filter(Boolean);
-    result = result.replace(/\$(\d+)/g, (_match, indexStr) => {
-        const index = Number(indexStr);
-        return positional[index - 1] ?? '';
+    return body.replace(/\$(\$(?=\d)|ARGUMENTS|\d+)/g, (match, token) => {
+        if (token === '$')
+            return '$';
+        if (token === 'ARGUMENTS')
+            return argString;
+        const index = Number(token);
+        return index >= 1 && index <= positional.length ? positional[index - 1] : match;
+    });
+}
+/** Replaces `$name` placeholders (lowercase, e.g. `$order_number`) with
+ * named parameters. A name in `declared` that wasn't given becomes empty
+ * text; any other `$word` is left as it is, so `$ARGUMENTS`, `$1` and
+ * dollar amounts are untouched. Names it fills are added to `used`. */
+export function substituteParameters(body, params, options = {}) {
+    const declared = new Set(options.declared ?? []);
+    return body.replace(/\$([a-z_][a-z0-9_]*)/g, (match, name) => {
+        if (Object.prototype.hasOwnProperty.call(params, name)) {
+            options.used?.add(name);
+            return params[name];
+        }
+        return declared.has(name) ? '' : match;
     });
-    return result;
 }

package/dist/core/system-agents/templates.d.ts

@@ -21,6 +21,11 @@ export interface TemplateSchedule {
     name: string;
     /** What the agent receives on each run. */
     message: string;
+    /** Set when the template comes from a workflow: the schedule runs that
+     * workflow (its start message at run time) rather than `message`. */
+    workflowId?: string;
+    /** Send each run's result through the agent's notifier. */
+    notify?: boolean;
 }
 /** An app (core/mcp-apps.ts) a template works through, and the server
  * tools it relies on: switched on when the agent is created, if the app is

package/dist/core/system-agents/workflow-planner.d.ts

@@ -1,4 +1,5 @@
 import type { ToolSchema } from '#core/agent-config.js';
+import type { WorkflowParameter } from '#core/workflows.js';
 import type { ModelCall } from '#core/run-agent.js';
 import type { StarterTemplate, TemplateApp } from './templates.js';
 export type Decision = 'allow' | 'ask' | 'deny';
@@ -76,6 +77,15 @@ export interface WorkflowPlan {
     };
     /** What the agent receives when the workflow starts. */
     startMessage: string;
+    /** Values a run is given, filled into $name in the start message and
+     * steps (core/workflows.ts). Empty when every run is the same. */
+    parameters: Record<string, WorkflowParameter>;
+    /** Whether each scheduled run's result is sent to the person through
+     * the agent's messaging app, and why (shown on the review screen). */
+    notify: {
+        on: boolean;
+        reason: string;
+    };
     target: {
         kind: 'existing' | 'new';
         agent?: string;
@@ -115,13 +125,28 @@ export interface WorkflowPlannerTools {
     /** A server's tools, when it can be listed without a key (or with one already set). */
     mcpServerTools?(id: string): Promise<unknown>;
 }
-export declare const WORKFLOW_PLANNER_PROMPT = "You turn a workflow a person describes into a plan for a LoopEngine agent.\n\nLoopEngine agents call tools. Tools come from abilities (installable packages: public ones on npm, or the workspace's own private ones) or are built in. Each tool has a permission: allow (runs on its own), ask (waits for a person to approve, edit or deny it) or deny. When nobody is in Chat, questions and approvals go to the agent's messaging app (Slack, Telegram, Lark or email) and the run waits, for days if needed, then carries on.\n\nHow to plan:\n1. Look before you plan: list_agents (what exists, and what each agent's tools and rules are), list_workspace_abilities, search_public_abilities for each kind of step, ability_details for any ability you might use (its exact tool names and the settings it needs), and list_connections.\n2. Split the workflow into steps, in order. For each step:\n   - something to fetch or do: kind \"tool\", with the exact tool name and where it comes from. Pick the source in this order:\n     a. A tool the target agent already has (from list_agents): use it, nothing to install.\n     b. An ability: a workspace ability (list_workspace_abilities) or a public one (search_public_abilities, e.g. \"firecrawl\" or \"web search\" for searching and reading the web). Set \"ability\" to its install spec (the npm name, or a workspace ability's spec) and use the exact tool name from ability_details.\n     c. Only when no ability can do it, and search_mcp_servers is available: an app's MCP server. Search for the app (e.g. \"linear\", \"stripe\"), pick the app's own server (official), else a saved or verified one, then call mcp_server_tools. Set \"mcp\" to the server's id, and \"tool\" to its exact tool name when mcp_server_tools lists them (leave \"tool\" empty when it needs a key first, and say in \"detail\" what the step does). It's set up as a private ability when the workflow is created, which picks its tools and their permissions, so add no rules for MCP tools.\n   - the person chooses or answers (\"ask me which\", \"let me pick\"): kind \"ask\", tool \"system_ask_user\" (built in, no ability). Say what options are offered. It reaches them through the agent's messaging app by itself, so don't add a separate step to post to Slack or another chat first, and don't install a chat ability just to ask.\n   - the person reviews or approves before something happens (\"let me review it\", \"before it's sent\"): kind \"approval\", on the tool that does that thing; its rule becomes \"ask\".\n   - the agent's own work (writing, summarising, choosing): kind \"other\".\n   - nothing found can do it: set \"missing\" to what's needed, and add it to gaps.\n3. Rules: every tool the workflow uses gets one. Reading and searching: allow. Anything a person should see first (sending, publishing, paying, creating something others see): ask. Never set deny unless asked.\n4. Skill: the steps in order, as numbered instructions the agent follows, naming the tools and saying exactly when to stop and ask. Write it so the agent keeps going after each answer or decision.\n5. Trigger: a schedule (\"every Monday at 9\" is every \"7d\", at \"09:00\", weekday 1) or on_request (started from Chat or a message). startMessage is what the agent receives when it starts.\n6. Target: an existing agent only when it already has (or can install) the tools, none of the workflow's rules would change a decision it already has, and the same people would approve. Otherwise a new agent, with a short lowercase-hyphenated name and a system prompt saying who it is and what it's for. Give the reason either way.\n7. keys: the setting names its abilities need that list_connections or the agents don't show as set (from ability_details settings). Not for MCP servers: their keys are asked for on the plan.\n\nThen call save_plan once, with the whole plan. Don't ask the person questions: if something is unclear, plan the most reasonable version and note the assumption in gaps.";
+export declare const WORKFLOW_PLANNER_PROMPT = "You turn a workflow a person describes into a plan for a LoopEngine agent.\n\nLoopEngine agents call tools. Tools come from abilities (installable packages: public ones on npm, or the workspace's own private ones) or are built in. Each tool has a permission: allow (runs on its own), ask (waits for a person to approve, edit or deny it) or deny. When nobody is in Chat, questions and approvals go to the agent's messaging app (Slack, Telegram, Lark or email) and the run waits, for days if needed, then carries on.\n\nHow to plan:\n1. Look before you plan: list_agents (what exists, and what each agent's tools and rules are), list_workspace_abilities, search_public_abilities for each kind of step, ability_details for any ability you might use (its exact tool names and the settings it needs), and list_connections.\n2. Split the workflow into steps, in order. For each step:\n   - something to fetch or do: kind \"tool\", with the exact tool name and where it comes from. Pick the source in this order:\n     a. A tool the target agent already has (from list_agents): use it, nothing to install.\n     b. An ability: a workspace ability (list_workspace_abilities) or a public one (search_public_abilities, e.g. \"firecrawl\" or \"web search\" for searching and reading the web). Set \"ability\" to its install spec (the npm name, or a workspace ability's spec) and use the exact tool name from ability_details.\n     c. Only when no ability can do it, and search_mcp_servers is available: an app's MCP server. Search for the app (e.g. \"linear\", \"stripe\"), pick the app's own server (official), else a saved or verified one, then call mcp_server_tools. Set \"mcp\" to the server's id, and \"tool\" to its exact tool name when mcp_server_tools lists them (leave \"tool\" empty when it needs a key first, and say in \"detail\" what the step does). It's set up as a private ability when the workflow is created, which picks its tools and their permissions, so add no rules for MCP tools.\n   - the person chooses or answers (\"ask me which\", \"let me pick\"): kind \"ask\", tool \"system_ask_user\" (built in, no ability). Say what options are offered. It reaches them through the agent's messaging app by itself, so don't add a separate step to post to Slack or another chat first, and don't install a chat ability just to ask.\n   - the person reviews or approves before something happens (\"let me review it\", \"before it's sent\"): kind \"approval\", on the tool that does that thing; its rule becomes \"ask\".\n   - the agent's own work (writing, summarising, choosing): kind \"other\".\n   - nothing found can do it: set \"missing\" to what's needed, and add it to gaps.\n3. Rules: every tool the workflow uses gets one. Reading and searching: allow. Anything a person should see first (sending, publishing, paying, creating something others see): ask. Never set deny unless asked.\n4. Skill: the steps in order, as numbered instructions the agent follows, naming the tools and saying exactly when to stop and ask. Write it so the agent keeps going after each answer or decision.\n5. Trigger: a schedule (\"every Monday at 9\" is every \"7d\", at \"09:00\", weekday 1) or on_request (started from Chat or a message). startMessage is what the agent receives when it starts.\n6. Notify (scheduled workflows): whether each run's result is sent to the person through the agent's messaging app. true when the result is for them and no step already delivers it (\"tell me\", \"send me\", \"let me know\", a summary or findings that no step posts or emails). false when a step already sends it (posting to a channel, emailing a report): it would arrive twice. false when the work itself is the outcome (answering emails, filing tasks), where a message every run is noise; questions and approvals reach them either way. Say why in one short sentence.\n7. Parameters: if the job is about something that changes from run to run (an order, a ticket, an alert, a customer, a date range), declare it as a parameter: a short snake_case name, a one-line description, and required when a run makes no sense without it. Write $name wherever its value goes, in startMessage and in the skill (\"Check the refund request for order $order_number.\"). Apps and people fill them in when they start a run. A scheduled job that finds its own work (\"check the inbox every 10 minutes\", \"last week's sales\") needs none. Don't make fixed settings, such as the repository or the channel, parameters: write them into the skill.\n8. Target: an existing agent only when it already has (or can install) the tools, none of the workflow's rules would change a decision it already has, and the same people would approve. Otherwise a new agent, with a short lowercase-hyphenated name and a system prompt saying who it is and what it's for. Give the reason either way.\n9. keys: the setting names its abilities need that list_connections or the agents don't show as set (from ability_details settings). Not for MCP servers: their keys are asked for on the plan.\n\nThen call save_plan once, with the whole plan. Don't ask the person questions: if something is unclear, plan the most reasonable version and note the assumption in gaps.";
 export declare function workflowPlannerTools(withMcp?: boolean): ToolSchema[];
 /** lowercase-hyphenated, 2–40 characters. */
 export declare function slugify(value: string, fallback?: string): string;
 /** A plan from the model's save_plan input, or undefined when it lacks a
  * name, steps, a skill or a new-agent prompt. Fills in what can be derived. */
 export declare function validateWorkflowPlan(raw: unknown): WorkflowPlan | undefined;
+/** A plan's notify choice; off when the planner gave none. */
+export declare function planNotify(raw: unknown): WorkflowPlan['notify'];
+/** A plan's parameters, tidied: names made snake_case (or dropped), a
+ * $name the start message or skill uses but doesn't declare added as an
+ * optional one, and, for a scheduled workflow, required ones made
+ * optional (a schedule has no one to fill them in), with a note saying
+ * so. Also used on a plan edited before Create. */
+export declare function planParameters(raw: unknown, context: {
+    startMessage: string;
+    skillBody: string;
+    scheduled: boolean;
+}): {
+    parameters: Record<string, WorkflowParameter>;
+    notes: string[];
+};
 export interface WorkflowPlanResult {
     plan?: WorkflowPlan;
     /** The planner's last words when it didn't save a plan. */