loopengine 0.2.1 → 0.3.0

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/agent-config.d.ts

@@ -273,6 +273,10 @@ export type AgentModelConfig = {
     model?: string;
     apiKey?: string;
     maxTokens?: number;
+    /** How much Claude thinks before answering; omitted, the model's own
+     * default. See AnthropicModelCallOptions.reasoningEffort
+     * (core/model-calls/anthropic-model-call.ts). */
+    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 } | {
     provider: 'openai';
     model: string;

package/dist/core/model-calls/anthropic-model-call.d.ts

@@ -4,7 +4,14 @@ export interface AnthropicModelCallOptions {
     /** Defaults to the ANTHROPIC_API_KEY env var, same as the SDK itself. */
     apiKey?: string;
     model?: string;
+    /** Defaults to 4096, or 16000 with a reasoning effort set: thinking
+     * counts toward it. */
     maxTokens?: number;
+    /** How much Claude thinks before answering. 'none' turns thinking off;
+     * 'minimal' and 'low' to 'max' turn on adaptive thinking at that effort
+     * (Claude has no 'minimal', so it means 'low'). Omitted, the model's
+     * own default. */
+    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
     /** Inject a pre-configured client instead of building one from apiKey — e.g. to pass a custom `fetch` in tests. */
     client?: Anthropic;
 }

package/dist/core/model-calls/anthropic-model-call.js

@@ -13,7 +13,24 @@
 // Anthropic's own API expects a tool_use to be answered by a matching
 // tool_result. This file's only job is translating between that shape and
 // the SDK's own param/response types — see message-to-param below.
+//
+// With a reasoning effort set, Claude thinks before answering (adaptive
+// thinking at that effort), and its thinking blocks come back signed. The
+// API needs them sent back unchanged with the tool results they led to,
+// so each rides in the conversation as an 'anthropic_thinking' block (the
+// whole block as JSON in `data`), sent back only to Anthropic.
 import Anthropic from '@anthropic-ai/sdk';
+/** The thinking (or redacted thinking) block an 'anthropic_thinking'
+ * block carries, or undefined if its data isn't one. */
+function thinkingBlockParam(block) {
+    try {
+        const parsed = JSON.parse(block.data ?? '');
+        return parsed && (parsed.type === 'thinking' || parsed.type === 'redacted_thinking') ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function toContentBlockParam(block) {
     if (block.type === 'tool_use') {
         return { type: 'tool_use', id: block.id, name: block.name, input: block.input ?? {} };
@@ -29,18 +46,27 @@ function toContentBlockParam(block) {
 function toMessageParam(message) {
     return {
         role: message.role === 'assistant' ? 'assistant' : 'user',
-        // Blocks only another provider can use (another model's reasoning:
-        // 'thinking', 'openai_reasoning') are left out; as text they'd be
-        // empty text blocks, which the API rejects.
+        // Claude's own signed thinking goes back as it came. Blocks only
+        // another provider can use (DeepSeek's 'thinking', 'openai_reasoning')
+        // are left out; as text they'd be empty text blocks, which the API
+        // rejects.
         content: typeof message.content === 'string'
             ? message.content
-            : message.content.filter((block) => ['text', 'tool_use', 'tool_result'].includes(block.type)).map(toContentBlockParam),
+            : message.content.flatMap((block) => {
+                if (block.type === 'anthropic_thinking') {
+                    const thinking = thinkingBlockParam(block);
+                    return thinking ? [thinking] : [];
+                }
+                return ['text', 'tool_use', 'tool_result'].includes(block.type) ? [toContentBlockParam(block)] : [];
+            }),
     };
 }
 export function createAnthropicModelCall(options = {}) {
     const client = options.client ?? new Anthropic({ apiKey: options.apiKey });
     const model = options.model ?? 'claude-sonnet-5';
-    const maxTokens = options.maxTokens ?? 4096;
+    const maxTokens = options.maxTokens ?? (options.reasoningEffort ? 16000 : 4096);
+    const effort = options.reasoningEffort === 'minimal' ? 'low' : options.reasoningEffort;
+    const reasoning = effort === undefined ? {} : effort === 'none' ? { thinking: { type: 'disabled' } } : { thinking: { type: 'adaptive' }, output_config: { effort } };
     return async (messages, system, tools) => {
         const response = await client.messages.create({
             model,
@@ -54,10 +80,13 @@ export function createAnthropicModelCall(options = {}) {
                     input_schema: t.input_schema,
                 }))
                 : undefined,
+            ...reasoning,
         });
         const content = response.content.map((block) => {
             if (block.type === 'text')
                 return { type: 'text', text: block.text };
+            if (block.type === 'thinking' || block.type === 'redacted_thinking')
+                return { type: 'anthropic_thinking', data: JSON.stringify(block) };
             if (block.type === 'tool_use') {
                 return { type: 'tool_use', id: block.id, name: block.name, input: block.input };
             }

package/dist/core/model-calls/openai-model-call.js

@@ -234,7 +234,8 @@ export function fromResponse(response) {
 }
 export function createOpenAIModelCall(options) {
     const client = options.client ?? new OpenAI({ apiKey: options.apiKey });
-    const maxTokens = options.maxTokens ?? 4096;
+    // Reasoning counts toward max_output_tokens.
+    const maxTokens = options.maxTokens ?? (options.reasoningEffort && options.reasoningEffort !== 'none' ? 16000 : 4096);
     return async (messages, system, tools) => {
         const response = await client.responses.create({
             model: options.model,

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/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. */

package/dist/core/system-agents/workflow-planner.js

@@ -17,8 +17,10 @@ How to plan:
 3. 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.
 4. 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.
 5. 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.
-6. 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.
-7. 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.
+6. 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.
+7. 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.
+8. 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.
+9. 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.
 
 Then 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 function workflowPlannerTools(withMcp = false) {
@@ -72,6 +74,17 @@ export function workflowPlannerTools(withMcp = false) {
                     needsApprovals: { type: 'boolean' },
                     skill: { type: 'object', properties: { description: { type: 'string' }, body: { type: 'string' } }, required: ['description', 'body'] },
                     startMessage: { type: 'string' },
+                    notify: {
+                        type: 'object',
+                        description: 'Scheduled workflows: whether each run\'s result goes to the person through the agent\'s messaging app, and why in one short sentence.',
+                        properties: { on: { type: 'boolean' }, reason: { type: 'string' } },
+                        required: ['on', 'reason'],
+                    },
+                    parameters: {
+                        type: 'object',
+                        description: 'Values each run is given, by snake_case name; use $name in startMessage and the skill. Leave out when every run is the same.',
+                        additionalProperties: { type: 'object', properties: { description: { type: 'string' }, required: { type: 'boolean' } } },
+                    },
                     target: { type: 'object', properties: { kind: { type: 'string', enum: ['existing', 'new'] }, agent: { type: 'string' }, reason: { type: 'string' } }, required: ['kind', 'reason'] },
                     newAgent: { type: 'object', properties: { name: { type: 'string' }, systemPrompt: { type: 'string' } }, required: ['name', 'systemPrompt'] },
                     gaps: { type: 'array', items: { type: 'string' } },
@@ -156,6 +169,9 @@ export function validateWorkflowPlan(raw) {
         ])].filter((spec) => !steps.some((s) => s.connection === spec && s.ability !== spec));
     const targetRaw = (r.target ?? {});
     const id = slugify(str(r.id, 60) ?? name);
+    const startMessage = str(r.startMessage, 1000) ?? `Run the "${name}" workflow.`;
+    const gaps = Array.isArray(r.gaps) ? r.gaps.flatMap((g) => (str(g, 400) ? [str(g, 400)] : [])).slice(0, 10) : [];
+    const planned = planParameters(r.parameters, { startMessage, skillBody, scheduled: trigger.kind === 'schedule' });
     return {
         name,
         id,
@@ -167,16 +183,52 @@ export function validateWorkflowPlan(raw) {
         keys: Array.isArray(r.keys) ? [...new Set(r.keys.flatMap((k) => (str(k, 80) ? [str(k, 80)] : [])))] : [],
         needsApprovals: r.needsApprovals === true || steps.some((s) => s.kind === 'ask' || s.kind === 'approval'),
         skill: { description: str(skillRaw.description, 400) ?? summary, body: skillBody },
-        startMessage: str(r.startMessage, 1000) ?? `Run the "${name}" workflow.`,
+        startMessage,
+        parameters: planned.parameters,
+        notify: planNotify(r.notify),
         target: {
             kind: targetRaw.kind === 'existing' && str(targetRaw.agent, 80) ? 'existing' : 'new',
             ...(targetRaw.kind === 'existing' && str(targetRaw.agent, 80) ? { agent: str(targetRaw.agent, 80) } : {}),
             reason: str(targetRaw.reason, 600) ?? '',
         },
         newAgent: { name: slugify(str(agentRaw.name, 60) ?? id, id), systemPrompt },
-        gaps: Array.isArray(r.gaps) ? r.gaps.flatMap((g) => (str(g, 400) ? [str(g, 400)] : [])).slice(0, 10) : [],
+        gaps: [...gaps, ...planned.notes].slice(0, 12),
     };
 }
+/** A plan's notify choice; off when the planner gave none. */
+export function planNotify(raw) {
+    const n = raw && typeof raw === 'object' ? raw : {};
+    return { on: n.on === true, reason: typeof n.reason === 'string' ? n.reason.trim().slice(0, 200) : '' };
+}
+/** 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 function planParameters(raw, context) {
+    const parameters = {};
+    const notes = [];
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        for (const [rawName, spec] of Object.entries(raw)) {
+            const name = rawName.trim().toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^[^a-z_]+/, '').replace(/_+/g, '_').replace(/_$/, '').slice(0, 40);
+            if (!name || parameters[name])
+                continue;
+            const s = spec && typeof spec === 'object' ? spec : {};
+            parameters[name] = { description: typeof s.description === 'string' ? s.description.trim().slice(0, 300) : '', required: s.required === true };
+        }
+    }
+    for (const match of `${context.startMessage}\n${context.skillBody}`.matchAll(/\$([a-z_][a-z0-9_]*)/g)) {
+        parameters[match[1]] ??= { description: '', required: false };
+    }
+    if (context.scheduled) {
+        const required = Object.entries(parameters).filter(([, p]) => p.required);
+        for (const [, p] of required)
+            p.required = false;
+        if (required.length)
+            notes.push(`A schedule can't fill in ${required.map(([n]) => n).join(', ')}, so ${required.length > 1 ? 'they are' : 'it is'} optional; give ${required.length > 1 ? 'them' : 'it'} a value on the schedule, or start runs by hand or from an app.`);
+    }
+    return { parameters, notes };
+}
 /** Runs the planner on a description until it saves a plan. */
 export async function planWorkflowWithModel(modelCall, description, tools) {
     const messages = [{ role: 'user', content: `Plan this workflow:\n\n${description}` }];
@@ -284,7 +336,7 @@ export function workflowTemplate(plan) {
             skills: [{ id: plan.id, description: plan.skill.description, body: plan.skill.body }],
             rules: plan.rules.map((r) => ({ name: slugify(`${plan.id}-${r.tool}`, `${plan.id}-rule`), tool: r.tool, decision: r.decision })),
             ...(plan.trigger.kind === 'schedule' && plan.trigger.every
-                ? { schedule: { every: plan.trigger.every, ...(plan.trigger.at ? { at: plan.trigger.at } : {}), ...(plan.trigger.weekday !== undefined ? { weekday: plan.trigger.weekday } : {}), name: plan.name, message: plan.startMessage } }
+                ? { schedule: { every: plan.trigger.every, ...(plan.trigger.at ? { at: plan.trigger.at } : {}), ...(plan.trigger.weekday !== undefined ? { weekday: plan.trigger.weekday } : {}), name: plan.name, message: plan.startMessage, workflowId: plan.id, ...(plan.notify?.on ? { notify: true } : {}) } }
                 : {}),
             needsApprovals: plan.needsApprovals,
         },

package/dist/core/system-tools/schedule.d.ts

@@ -1,2 +1,6 @@
 import type { ToolDefinition } from '../agent-config.js';
-export declare function createScheduleTools(agentName: string): ToolDefinition[];
+/** `agentDir`: the agent's folder, where its workflows are listed
+ * (workflows.yml). Without it the agent can only schedule messages. */
+export declare function createScheduleTools(agentName: string, options?: {
+    agentDir?: string;
+}): ToolDefinition[];