loopengine 0.1.95 → 0.1.97

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

@@ -0,0 +1,100 @@
+import type { ToolSchema } from '#core/agent-config.js';
+import type { ModelCall } from '#core/run-agent.js';
+import type { StarterTemplate } from './templates.js';
+export type Decision = 'allow' | 'ask' | 'deny';
+export interface WorkflowStep {
+    title: string;
+    /** tool: a tool runs. ask: the agent asks a person (system_ask_user).
+     * approval: a tool that waits for a person's OK (its rule is "ask").
+     * other: the agent's own work, like writing or deciding. */
+    kind: 'tool' | 'ask' | 'approval' | 'other';
+    tool?: string;
+    /** The ability that provides `tool`, as it would be installed. */
+    ability?: string;
+    detail?: string;
+    /** What's missing for this step, when nothing found provides it. */
+    missing?: string;
+    /** For a tool from a connected service (an agent's Composio source, not
+     * an ability): the source's name. It's copied to the agent that runs the
+     * workflow, not installed. */
+    connection?: string;
+}
+export interface WorkflowPlan {
+    name: string;
+    /** lowercase-hyphenated: the workflow's id and its skill's folder. */
+    id: string;
+    summary: string;
+    trigger: {
+        kind: 'schedule' | 'on_request';
+        description: string;
+        /** schedule only: "1h", "24h", "7d". */
+        every?: string;
+        /** schedule only: time of day ("09:00") and weekday (1 = Monday). */
+        at?: string;
+        weekday?: number;
+    };
+    steps: WorkflowStep[];
+    /** Abilities to install, as specs: an npm name, or a workspace ability's file: spec. */
+    abilities: string[];
+    /** Permission each tool the workflow uses should have. */
+    rules: {
+        tool: string;
+        decision: Decision;
+    }[];
+    /** Keys its abilities need (setting names). */
+    keys: string[];
+    /** Whether a person must be reachable (a question or an approval). */
+    needsApprovals: boolean;
+    /** The steps in order, as the agent's instructions. */
+    skill: {
+        description: string;
+        body: string;
+    };
+    /** What the agent receives when the workflow starts. */
+    startMessage: string;
+    target: {
+        kind: 'existing' | 'new';
+        agent?: string;
+        reason: string;
+    };
+    /** For a new agent. */
+    newAgent: {
+        name: string;
+        systemPrompt: string;
+    };
+    /** What the workspace can't do yet, in plain words. */
+    gaps: string[];
+}
+export interface WorkflowPlannerTools {
+    /** Every agent: its tools, installed abilities, rules and messaging. */
+    listAgents(): Promise<unknown>;
+    searchPublicAbilities(query: string): Promise<{
+        name: string;
+        description?: string;
+    }[]>;
+    /** The workspace's private abilities. */
+    listWorkspaceAbilities(): Promise<{
+        name: string;
+        description?: string;
+        spec: string;
+    }[]>;
+    /** An ability's tools (with the decision each ships with) and settings. */
+    abilityDetails(spec: string): Promise<unknown>;
+    listConnections(): Promise<Record<string, 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 (even when an agent already has a connected tool for it), 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 does it: a tool in some agent's connectedTools (a connected service, usually one that needs a person to sign in, like Gmail or HubSpot). Give its exact tool name, set \"connection\" to that source's name and leave \"ability\" empty (it's copied to the agent that runs the workflow). Never put a connection's name in abilities.\n     An ability beats a connected tool even when another agent already has the connected one: it's faster, needs only a key, and travels with the agent. If you chose a connected tool, say why in gaps.\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).\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(): 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;
+export interface WorkflowPlanResult {
+    plan?: WorkflowPlan;
+    /** The planner's last words when it didn't save a plan. */
+    reply?: string;
+}
+/** Runs the planner on a description until it saves a plan. */
+export declare function planWorkflowWithModel(modelCall: ModelCall, description: string, tools: WorkflowPlannerTools): Promise<WorkflowPlanResult>;
+/** A plan as a starter template, for creating it as a new agent. */
+export declare function workflowTemplate(plan: WorkflowPlan): StarterTemplate;

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

@@ -0,0 +1,278 @@
+const MAX_TOOL_ROUNDS = 12;
+export const WORKFLOW_PLANNER_PROMPT = `You turn a workflow a person describes into a plan for a LoopEngine agent.
+
+LoopEngine 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.
+
+How to plan:
+1. 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 (even when an agent already has a connected tool for it), ability_details for any ability you might use (its exact tool names and the settings it needs), and list_connections.
+2. Split the workflow into steps, in order. For each step:
+   - something to fetch or do: kind "tool", with the exact tool name and where it comes from. Pick the source in this order:
+     a. A tool the target agent already has (from list_agents): use it, nothing to install.
+     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.
+     c. Only when no ability does it: a tool in some agent's connectedTools (a connected service, usually one that needs a person to sign in, like Gmail or HubSpot). Give its exact tool name, set "connection" to that source's name and leave "ability" empty (it's copied to the agent that runs the workflow). Never put a connection's name in abilities.
+     An ability beats a connected tool even when another agent already has the connected one: it's faster, needs only a key, and travels with the agent. If you chose a connected tool, say why in gaps.
+   - 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.
+   - 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".
+   - the agent's own work (writing, summarising, choosing): kind "other".
+   - nothing found can do it: set "missing" to what's needed, and add it to gaps.
+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).
+
+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() {
+    const step = {
+        type: 'object',
+        properties: {
+            title: { type: 'string' },
+            kind: { type: 'string', enum: ['tool', 'ask', 'approval', 'other'] },
+            tool: { type: 'string' },
+            ability: { type: 'string' },
+            detail: { type: 'string' },
+            missing: { type: 'string' },
+            connection: { type: 'string' },
+        },
+        required: ['title', 'kind'],
+    };
+    return [
+        { name: 'list_agents', description: "Every agent in the workspace: its tools, installed abilities, permission rules and messaging app.", input_schema: { type: 'object', properties: {} } },
+        { name: 'list_workspace_abilities', description: "The workspace's own private abilities, ready to add to an agent.", input_schema: { type: 'object', properties: {} } },
+        { name: 'search_public_abilities', description: 'Search public LoopEngine abilities on npm, e.g. "web search", "wordpress", "slack".', input_schema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] } },
+        { name: 'ability_details', description: "An ability's exact tool names, what each does, the permission each ships with, and the settings it needs. spec: its npm name or workspace spec.", input_schema: { type: 'object', properties: { spec: { type: 'string' } }, required: ['spec'] } },
+        { name: 'list_connections', description: 'What is set up: model providers with keys, messaging apps per agent.', input_schema: { type: 'object', properties: {} } },
+        {
+            name: 'save_plan',
+            description: 'Save the workflow plan. Call once, at the end.',
+            input_schema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                    id: { type: 'string', description: 'lowercase-hyphenated' },
+                    summary: { type: 'string' },
+                    trigger: {
+                        type: 'object',
+                        properties: {
+                            kind: { type: 'string', enum: ['schedule', 'on_request'] },
+                            description: { type: 'string' },
+                            every: { type: 'string' },
+                            at: { type: 'string' },
+                            weekday: { type: 'number' },
+                        },
+                        required: ['kind', 'description'],
+                    },
+                    steps: { type: 'array', items: step },
+                    abilities: { type: 'array', items: { type: 'string' } },
+                    rules: { type: 'array', items: { type: 'object', properties: { tool: { type: 'string' }, decision: { type: 'string', enum: ['allow', 'ask', 'deny'] } }, required: ['tool', 'decision'] } },
+                    keys: { type: 'array', items: { type: 'string' } },
+                    needsApprovals: { type: 'boolean' },
+                    skill: { type: 'object', properties: { description: { type: 'string' }, body: { type: 'string' } }, required: ['description', 'body'] },
+                    startMessage: { type: 'string' },
+                    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' } },
+                },
+                required: ['name', 'summary', 'trigger', 'steps', 'rules', 'skill', 'startMessage', 'target', 'newAgent'],
+            },
+        },
+    ];
+}
+const str = (value, max = 2000) => (typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : undefined);
+/** lowercase-hyphenated, 2–40 characters. */
+export function slugify(value, fallback = 'workflow') {
+    const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '');
+    return slug.length >= 2 ? slug : fallback;
+}
+const isDecision = (value) => value === 'allow' || value === 'ask' || value === 'deny';
+/** 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 function validateWorkflowPlan(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const name = str(r.name, 80);
+    const summary = str(r.summary, 600);
+    const skillRaw = (r.skill ?? {});
+    const skillBody = str(skillRaw.body, 12000);
+    const agentRaw = (r.newAgent ?? {});
+    const systemPrompt = str(agentRaw.systemPrompt, 8000);
+    if (!name || !summary || !skillBody || !systemPrompt)
+        return undefined;
+    const steps = (Array.isArray(r.steps) ? r.steps : []).flatMap((s) => {
+        const step = (s ?? {});
+        const title = str(step.title, 200);
+        const kind = ['tool', 'ask', 'approval', 'other'].includes(step.kind) ? step.kind : 'other';
+        if (!title)
+            return [];
+        return [{
+                title,
+                kind,
+                ...(str(step.tool, 120) ? { tool: str(step.tool, 120) } : {}),
+                ...(str(step.ability, 300) ? { ability: str(step.ability, 300) } : {}),
+                ...(str(step.detail, 600) ? { detail: str(step.detail, 600) } : {}),
+                ...(str(step.missing, 300) ? { missing: str(step.missing, 300) } : {}),
+                ...(str(step.connection, 120) ? { connection: str(step.connection, 120) } : {}),
+            }];
+    });
+    if (!steps.length)
+        return undefined;
+    const triggerRaw = (r.trigger ?? {});
+    const scheduled = triggerRaw.kind === 'schedule' && typeof triggerRaw.every === 'string' && /^\d+[mhd]$/.test(triggerRaw.every);
+    const trigger = scheduled
+        ? {
+            kind: 'schedule',
+            description: str(triggerRaw.description, 200) ?? `every ${triggerRaw.every}`,
+            every: triggerRaw.every,
+            ...(typeof triggerRaw.at === 'string' && /^\d{1,2}:\d{2}$/.test(triggerRaw.at) ? { at: triggerRaw.at } : {}),
+            ...(typeof triggerRaw.weekday === 'number' && triggerRaw.weekday >= 0 && triggerRaw.weekday <= 7 ? { weekday: triggerRaw.weekday } : {}),
+        }
+        : { kind: 'on_request', description: str(triggerRaw.description, 200) ?? 'when asked' };
+    const rules = (Array.isArray(r.rules) ? r.rules : []).flatMap((x) => {
+        const rule = (x ?? {});
+        const tool = str(rule.tool, 120);
+        return tool && isDecision(rule.decision) && tool !== 'system_ask_user' ? [{ tool, decision: rule.decision }] : [];
+    });
+    // An approval step's tool always asks first.
+    for (const step of steps) {
+        if (step.kind !== 'approval' || !step.tool)
+            continue;
+        const rule = rules.find((x) => x.tool === step.tool);
+        if (rule)
+            rule.decision = 'ask';
+        else
+            rules.push({ tool: step.tool, decision: 'ask' });
+    }
+    const abilities = [...new Set([
+            ...(Array.isArray(r.abilities) ? r.abilities.flatMap((a) => (str(a, 300) ? [str(a, 300)] : [])) : []),
+            ...steps.flatMap((s) => (s.ability ? [s.ability] : [])),
+        ])].filter((spec) => !steps.some((s) => s.connection === spec && s.ability !== spec));
+    const targetRaw = (r.target ?? {});
+    const id = slugify(str(r.id, 60) ?? name);
+    return {
+        name,
+        id,
+        summary,
+        trigger,
+        steps,
+        abilities,
+        rules,
+        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.`,
+        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) : [],
+    };
+}
+/** 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}` }];
+    let nudges = 0;
+    let retries = 0;
+    for (let round = 0; round <= MAX_TOOL_ROUNDS; round++) {
+        let response;
+        try {
+            response = await modelCall(messages, WORKFLOW_PLANNER_PROMPT, workflowPlannerTools());
+        }
+        catch (err) {
+            // A reply cut off part-way (its tool arguments end mid-JSON) usually
+            // means it ran out of room: ask again, for a shorter plan.
+            const message = err instanceof Error ? err.message : String(err);
+            if (retries < 3 && /JSON|Unterminated|Unexpected end/i.test(message)) {
+                retries++;
+                messages.push({ role: 'user', content: 'Your last reply was cut off before it finished. Call save_plan again, shorter: one line per step, and a skill body under 1500 characters.' });
+                continue;
+            }
+            throw err;
+        }
+        const calls = response.content.filter((b) => b.type === 'tool_use');
+        const text = response.content.filter((b) => b.type === 'text' && b.text).map((b) => b.text).join('\n').trim();
+        // An empty reply (no words, no tool calls) is left out: providers
+        // refuse a conversation holding an empty assistant message.
+        if (calls.length || text)
+            messages.push({ role: 'assistant', content: response.content });
+        if (!calls.length) {
+            // Some models answer in words instead of saving: ask for the plan,
+            // with what it has, a couple of times before giving up.
+            if (nudges < 2) {
+                nudges++;
+                messages.push({ role: 'user', content: 'Save the plan now: call save_plan with the whole plan, using what you have found. Note anything you assumed in gaps.' });
+                continue;
+            }
+            return { reply: text || 'The planner stopped without a plan.' };
+        }
+        const results = [];
+        let plan;
+        for (const call of calls) {
+            const input = (call.input ?? {});
+            let output;
+            try {
+                switch (call.name) {
+                    case 'list_agents':
+                        output = await tools.listAgents();
+                        break;
+                    case 'list_workspace_abilities':
+                        output = await tools.listWorkspaceAbilities();
+                        break;
+                    case 'search_public_abilities':
+                        output = await tools.searchPublicAbilities(String(input.query ?? ''));
+                        break;
+                    case 'ability_details':
+                        output = await tools.abilityDetails(String(input.spec ?? ''));
+                        break;
+                    case 'list_connections':
+                        output = await tools.listConnections();
+                        break;
+                    case 'save_plan':
+                        plan = validateWorkflowPlan(input);
+                        output = plan ? 'saved' : 'that plan needs a name, summary, at least one step, a skill body and newAgent.systemPrompt; fix and call again';
+                        break;
+                    default:
+                        output = `unknown tool ${call.name}`;
+                }
+            }
+            catch (err) {
+                output = `error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+            results.push({ type: 'tool_result', tool_use_id: call.id, content: typeof output === 'string' ? output : JSON.stringify(output) });
+        }
+        if (plan)
+            return { plan };
+        messages.push({ role: 'user', content: results });
+    }
+    return { reply: 'The planner ran out of steps before saving a plan. Try describing the workflow more briefly.' };
+}
+/** A plan as a starter template, for creating it as a new agent. */
+export function workflowTemplate(plan) {
+    return {
+        id: `workflow-${plan.id}`,
+        category: 'Workflow',
+        candidate: {
+            title: plan.name,
+            summary: plan.summary,
+            trigger: { kind: plan.trigger.kind === 'schedule' ? 'schedule' : 'on_request', description: plan.trigger.description, ...(plan.trigger.every ? { every: plan.trigger.every } : {}) },
+            hoursPerWeek: 1,
+            fit: 6,
+            risk: plan.rules.some((r) => r.decision === 'allow') && plan.needsApprovals ? 'medium' : 'low',
+            asksFirst: plan.steps.filter((s) => s.kind === 'approval' || s.kind === 'ask').map((s) => s.title),
+            needs: plan.abilities.map((spec) => ({ kind: 'ability', name: spec, description: spec })),
+            agent: { name: plan.newAgent.name, systemPrompt: plan.newAgent.systemPrompt, scheduleMessage: plan.startMessage, exampleMessage: plan.startMessage },
+        },
+        setup: {
+            abilities: plan.abilities,
+            keys: plan.keys,
+            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 } }
+                : {}),
+            needsApprovals: plan.needsApprovals,
+        },
+    };
+}

package/dist/core/workflows.d.ts

@@ -0,0 +1,26 @@
+import type { WorkflowStep } from './system-agents/workflow-planner.js';
+export interface WorkflowRecord {
+    /** lowercase-hyphenated; also its skill's folder name. */
+    id: string;
+    name: string;
+    summary: string;
+    trigger: {
+        kind: 'schedule' | 'on_request';
+        description: string;
+    };
+    steps: WorkflowStep[];
+    /** The message each run starts with. */
+    startMessage: string;
+    /** Its schedule's name, when it has one (the Schedules tab's task_name). */
+    scheduleName?: string;
+    /** What the person wrote, kept for reference. */
+    description?: string;
+    createdAt: string;
+}
+export declare function workflowsPath(agentDir: string): string;
+/** The agent's workflows; none when it has no workflows.yml or it can't be read. */
+export declare function readWorkflows(agentDir: string): WorkflowRecord[];
+/** Adds a workflow, replacing one with the same id. */
+export declare function saveWorkflow(agentDir: string, workflow: WorkflowRecord): void;
+/** Forgets a workflow. Its skill, schedule and rules are left as they are. */
+export declare function removeWorkflow(agentDir: string, id: string): void;

package/dist/core/workflows.js

@@ -0,0 +1,39 @@
+// An agent's workflows: jobs it does, each a skill (its steps), a trigger
+// (a schedule, or a message) and checkpoints (questions, and tools set to
+// "ask"). Recorded in agents/<name>/workflows.yml when one is added from
+// "Describe a workflow", so the agent's Overview can list them; the skill,
+// the schedule and the rules themselves live where they always do.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+export function workflowsPath(agentDir) {
+    return join(agentDir, 'workflows.yml');
+}
+/** The agent's workflows; none when it has no workflows.yml or it can't be read. */
+export function readWorkflows(agentDir) {
+    const path = workflowsPath(agentDir);
+    if (!existsSync(path))
+        return [];
+    try {
+        const parsed = parseYaml(readFileSync(path, 'utf8'));
+        return Array.isArray(parsed?.workflows) ? parsed.workflows.filter((w) => w && typeof w.id === 'string' && typeof w.name === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Adds a workflow, replacing one with the same id. */
+export function saveWorkflow(agentDir, workflow) {
+    const workflows = readWorkflows(agentDir).filter((w) => w.id !== workflow.id);
+    workflows.push(workflow);
+    const header = "# This agent's workflows, added from the console's \"Describe a workflow\". Each one's\n# steps are its skill (skills/<id>/SKILL.md); its schedule and rules are in the Schedules and Permissions tabs.\n";
+    writeFileSync(workflowsPath(agentDir), header + stringifyYaml({ workflows }));
+}
+/** Forgets a workflow. Its skill, schedule and rules are left as they are. */
+export function removeWorkflow(agentDir, id) {
+    const workflows = readWorkflows(agentDir);
+    if (!workflows.some((w) => w.id === id))
+        return;
+    const rest = workflows.filter((w) => w.id !== id);
+    writeFileSync(workflowsPath(agentDir), stringifyYaml({ workflows: rest }));
+}

package/dist/core/workspace-abilities.d.ts

@@ -0,0 +1,31 @@
+export declare const WORKSPACE_ABILITIES_DIR_ENV = "LOOPENGINE_ABILITIES_DIR";
+export interface WorkspaceAbilityRecord {
+    /** The spec it was installed from: github:owner/repo, @scope/name, file:/path. */
+    source: string;
+    version: string;
+    installedAt: string;
+}
+export interface WorkspaceAbility extends WorkspaceAbilityRecord {
+    name: string;
+    description: string;
+    /** What an agent installs it with: file:<its folder>. */
+    spec: string;
+}
+export declare class WorkspaceAbilityError extends Error {
+}
+export declare function workspaceAbilitiesDir(): string;
+/** Every copy in the workspace, by name. A record whose folder is gone is
+ * left out. */
+export declare function listWorkspaceAbilities(): WorkspaceAbility[];
+/** Stores a fetched ability (`fetchedDir`, a package folder holding
+ * loopengine.ability.json) as the workspace's copy, replacing an earlier
+ * one of the same name. `source` is the spec it came from. */
+export declare function addWorkspaceAbility(fetchedDir: string, source: string): WorkspaceAbility;
+/** Removes a copy from the workspace. Agents that installed it keep
+ * their own copies of its files. */
+export declare function removeWorkspaceAbility(name: string): void;
+/** The workspace copy an agent installed from, when `path` (from a
+ * file: spec) is one. */
+export declare function workspaceAbilityAt(path: string): (WorkspaceAbilityRecord & {
+    name: string;
+}) | undefined;

package/dist/core/workspace-abilities.js

@@ -0,0 +1,110 @@
+// The workspace's own copies of private abilities: installed once from a
+// private source (core/ability-sources.ts) on the console's Abilities
+// page, then added to any agent from its Abilities tab. Each copy is a
+// folder under abilities/ in the project root (or the folder
+// LOOPENGINE_ABILITIES_DIR names), and abilities/workspace.json says
+// where each came from:
+//
+//   { "lp-github": { "source": "github:loopengine-co/lp-github",
+//                    "version": "1.0.0", "installedAt": "2026-10-31T..." } }
+//
+// An agent installs a copy as file:<its folder>, so it needs no token
+// and nothing is fetched again; installing it in the workspace again
+// updates the copy, and each agent's Upgrade then picks that up.
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+export const WORKSPACE_ABILITIES_DIR_ENV = 'LOOPENGINE_ABILITIES_DIR';
+export class WorkspaceAbilityError extends Error {
+}
+export function workspaceAbilitiesDir() {
+    return resolve(process.cwd(), process.env[WORKSPACE_ABILITIES_DIR_ENV]?.trim() || 'abilities');
+}
+function recordsPath() {
+    return join(workspaceAbilitiesDir(), 'workspace.json');
+}
+/** A copy's folder name: the package name, with a scope's slash made safe
+ * ("@acme/lp-x" is abilities/@acme+lp-x). */
+function folderFor(name) {
+    return join(workspaceAbilitiesDir(), name.replace('/', '+'));
+}
+function readRecords() {
+    const path = recordsPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeRecords(records) {
+    mkdirSync(workspaceAbilitiesDir(), { recursive: true });
+    writeFileSync(recordsPath(), JSON.stringify(records, null, 2) + '\n');
+}
+/** Every copy in the workspace, by name. A record whose folder is gone is
+ * left out. */
+export function listWorkspaceAbilities() {
+    return Object.entries(readRecords())
+        .flatMap(([name, record]) => {
+        const dir = folderFor(name);
+        if (!existsSync(join(dir, 'loopengine.ability.json')))
+            return [];
+        let description = '';
+        try {
+            description = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).description ?? '';
+        }
+        catch { }
+        return [{ name, description, spec: `file:${dir}`, ...record }];
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Stores a fetched ability (`fetchedDir`, a package folder holding
+ * loopengine.ability.json) as the workspace's copy, replacing an earlier
+ * one of the same name. `source` is the spec it came from. */
+export function addWorkspaceAbility(fetchedDir, source) {
+    if (!existsSync(join(fetchedDir, 'loopengine.ability.json')))
+        throw new WorkspaceAbilityError(`${source} has no loopengine.ability.json, so it isn't a loopengine ability`);
+    let pkg = {};
+    try {
+        pkg = JSON.parse(readFileSync(join(fetchedDir, 'package.json'), 'utf8'));
+    }
+    catch { }
+    if (!pkg.name || !/^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i.test(pkg.name))
+        throw new WorkspaceAbilityError(`${source} has no valid package.json name`);
+    const dir = folderFor(pkg.name);
+    // Copied beside it first, then swapped in, so a failed copy leaves the
+    // earlier one as it was.
+    const staging = `${dir}.installing`;
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(workspaceAbilitiesDir(), { recursive: true });
+    cpSync(fetchedDir, staging, { recursive: true });
+    rmSync(dir, { recursive: true, force: true });
+    renameSync(staging, dir);
+    const records = readRecords();
+    records[pkg.name] = { source, version: pkg.version ?? '', installedAt: new Date().toISOString() };
+    writeRecords(records);
+    return listWorkspaceAbilities().find((a) => a.name === pkg.name);
+}
+/** Removes a copy from the workspace. Agents that installed it keep
+ * their own copies of its files. */
+export function removeWorkspaceAbility(name) {
+    const records = readRecords();
+    if (!records[name])
+        throw new WorkspaceAbilityError(`${name} isn't in the workspace`);
+    delete records[name];
+    rmSync(folderFor(name), { recursive: true, force: true });
+    writeRecords(records);
+}
+/** The workspace copy an agent installed from, when `path` (from a
+ * file: spec) is one. */
+export function workspaceAbilityAt(path) {
+    const root = workspaceAbilitiesDir() + sep;
+    const target = resolve(process.cwd(), path);
+    if (!target.startsWith(root))
+        return undefined;
+    const folder = target.slice(root.length).split(sep)[0];
+    const entry = Object.entries(readRecords()).find(([name]) => name.replace('/', '+') === folder);
+    return entry ? { name: entry[0], ...entry[1] } : undefined;
+}