loopengine 0.1.92 → 0.1.94

package/dist/web/templates-admin.d.ts

@@ -1,6 +1,33 @@
-import { type CandidatePreview, type CreateDeps, type CreatedAgent } from './interview-admin.js';
+import { type StarterTemplate, type TemplateSchedule } from '../core/system-agents/templates.js';
 export declare class TemplateError extends Error {
 }
+export interface TemplateCreateDeps {
+    agentExists(name: string): boolean;
+    /** Writes agents/<name>/index.ts, as Agents → + New does, without loading it. */
+    scaffoldAgent(name: string, systemPrompt: string): Promise<void>;
+    /** Loads the finished agent into the running server. */
+    registerAgent(name: string): Promise<void>;
+    /** Installs an ability (an npm spec) into the agent. Absent where
+     * installing isn't allowed (no admin login): the abilities then head the
+     * checklist instead. */
+    installAbility?: (name: string, spec: string) => Promise<void>;
+    /** A setting as the agent sees it (its own, else the shared one). */
+    envValue(name: string, variable: string): string | undefined;
+    /** Whether approval requests from the agent reach anyone. */
+    messagingConfigured(name: string): boolean;
+}
+/** What a project's adapters/http.ts from before full template setups
+ * (create-loopengine 0.1.74) passes: one call that writes and loads the
+ * agent. Still accepted, so upgrading loopengine alone doesn't break the
+ * Templates page; it just can't install abilities before the agent loads. */
+export interface LegacyTemplateCreateDeps {
+    agentExists(name: string): boolean;
+    createAgent(name: string, systemPrompt: string): Promise<void>;
+}
+export interface TemplateChecklistItem {
+    label: string;
+    href?: string;
+}
 /** A template as the page's cards show it. */
 export interface TemplateSummary {
     id: string;
@@ -9,11 +36,59 @@ export interface TemplateSummary {
     summary: string;
     trigger: string;
     asksFirst: string[];
-    needs: string[];
-    schedule: boolean;
+    abilities: string[];
+    schedule: string | null;
+}
+export interface TemplatePreview {
+    name: string;
+    systemPrompt: string;
+    abilities: string[];
+    skills: string[];
+    rules: {
+        tool: string;
+        decision: string;
+    }[];
+    keys: {
+        names: string[];
+        set: boolean;
+    }[];
+    settings: Record<string, string>;
+    schedule: string | null;
+    needsApprovals: boolean;
+    notes: string[];
+}
+export interface CreatedTemplateAgent {
+    name: string;
+    abilities: {
+        installed: string[];
+        failed: {
+            name: string;
+            error: string;
+        }[];
+    };
+    checklist: TemplateChecklistItem[];
+    exampleMessage?: string;
+    schedule?: {
+        description: string;
+        timeZone?: string;
+        next_run_at?: string;
+    };
+    /** Set when the schedule couldn't be created; the agent still was. */
+    scheduleError?: string;
+    /** Set when the agent was written but couldn't be loaded. */
+    loadError?: string;
 }
+/** A failed install, in a line the checklist can show: npm's own output
+ * runs to many lines of command and log paths. */
+export declare function installFailureReason(err: unknown): string;
+export declare function describeTemplateSchedule(schedule: TemplateSchedule): string;
 export declare function listTemplates(): TemplateSummary[];
-export declare function previewTemplate(id: string, deps: Pick<CreateDeps, 'agentExists'>): CandidatePreview;
-/** Creates a new agent from the template, under the first free name, so
- * the same template can be used more than once. */
-export declare function createFromTemplate(id: string, deps: CreateDeps): Promise<CreatedAgent>;
+export declare function previewTemplate(id: string, deps: Pick<TemplateCreateDeps, 'agentExists'> & Partial<Pick<TemplateCreateDeps, 'envValue'>>): TemplatePreview;
+/** What's left once the agent exists, each linked to where it's done. */
+export declare function templateChecklist(template: StarterTemplate, name: string, deps: Pick<TemplateCreateDeps, 'envValue' | 'messagingConfigured'>, failed?: {
+    name: string;
+    error: string;
+}[]): TemplateChecklistItem[];
+/** Creates a new agent from the template, with its whole setup, under the
+ * first free name, so the same template can be used more than once. */
+export declare function createFromTemplate(id: string, deps: TemplateCreateDeps | LegacyTemplateCreateDeps): Promise<CreatedTemplateAgent>;

package/dist/web/templates-admin.js

@@ -1,37 +1,228 @@
 // Backs the console's Templates page (/templates): the ready-made agents
-// in core/system-agents/templates.ts, previewed and created the same way
-// as a "Find your first agent" suggestion (web/interview-admin.ts), so a
-// template agent starts exactly like one: its instructions, every tool
-// asking first, a paused schedule when it runs on a timer, and a Finish
-// setup checklist. Unlike the interview it needs no model call, so it
-// works before any agent has a model or key.
-import { STARTER_TEMPLATES, starterTemplate } from '../core/system-agents/templates.js';
-import { createAgentFromCandidate, describeCandidate } from './interview-admin.js';
+// in core/system-agents/templates.ts, previewed and created with their
+// whole setup in one go — instructions, permission rules, abilities,
+// skills, settings and a paused schedule — before the agent first loads,
+// so nothing needs a restart. What only the person can do (their keys,
+// where approvals go, turning the schedule on) becomes the checklist.
+//
+// Every agent made from a template asks before anything not covered by a
+// rule. Its template's rules are written before its abilities' own, so
+// they take precedence where both name the same tool.
+import { createScheduledTask, pauseScheduledTask } from '../core/scheduler.js';
+import { workspaceTimeZone } from '../core/time-zone.js';
+import { STARTER_TEMPLATES, starterTemplate, templateScheduleStart } from '../core/system-agents/templates.js';
+import { ActauthRuleExistsError, addActauthRule, setDefaultDecision } from './actauth-admin.js';
+import { setAgentEnvVar } from './env-admin.js';
+import { freeAgentName } from './interview-admin.js';
+import { writeSkill } from './skills-admin.js';
 export class TemplateError extends Error {
 }
+/** A failed install, in a line the checklist can show: npm's own output
+ * runs to many lines of command and log paths. */
+export function installFailureReason(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    if (/E404|404 Not Found|is not in this registry/i.test(text))
+        return "it isn't published on npm yet";
+    if (/ENOTFOUND|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN/.test(text))
+        return 'npm could not be reached; try again from the Abilities tab';
+    const line = text.split('\n').map((l) => l.trim()).find((l) => l && !/^Command failed:/.test(l)) ?? text.split('\n')[0];
+    return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+}
 function templateAt(id) {
     const template = starterTemplate(id);
     if (!template)
         throw new TemplateError('No such template');
     return template;
 }
+const UNITS = { s: ['second', 'seconds'], m: ['minute', 'minutes'], h: ['hour', 'hours'], d: ['day', 'days'] };
+const WEEKDAYS = ['Sundays', 'Mondays', 'Tuesdays', 'Wednesdays', 'Thursdays', 'Fridays', 'Saturdays'];
+export function describeTemplateSchedule(schedule) {
+    if (schedule.at && schedule.weekday !== undefined && schedule.every === '7d')
+        return `${WEEKDAYS[schedule.weekday]} at ${schedule.at}`;
+    if (schedule.at && schedule.every === '1d')
+        return `daily at ${schedule.at}`;
+    const match = /^(\d+)([smhd])$/.exec(schedule.every);
+    if (!match)
+        return `every ${schedule.every}`;
+    const n = Number(match[1]);
+    const [one, many] = UNITS[match[2]];
+    return `every ${n === 1 ? one : `${n} ${many}`}${schedule.at ? `, from ${schedule.at}` : ''}`;
+}
 export function listTemplates() {
-    return STARTER_TEMPLATES.map(({ id, category, candidate: c }) => ({
+    return STARTER_TEMPLATES.map(({ id, category, candidate: c, setup }) => ({
         id,
         category,
         title: c.title,
         summary: c.summary,
-        trigger: c.trigger.description,
+        trigger: setup.schedule ? describeTemplateSchedule(setup.schedule) : c.trigger.description,
         asksFirst: c.asksFirst,
-        needs: c.needs.map((n) => (n.kind === 'key' ? n.description : n.name ?? n.description)),
-        schedule: c.trigger.kind === 'schedule',
+        abilities: setup.abilities,
+        schedule: setup.schedule ? describeTemplateSchedule(setup.schedule) : null,
     }));
 }
+function keyGroups(template) {
+    return template.setup.keys.map((k) => (Array.isArray(k) ? k : [k]));
+}
 export function previewTemplate(id, deps) {
-    return describeCandidate(templateAt(id).candidate, deps);
+    const template = templateAt(id);
+    const name = freeAgentName(template.candidate.agent.name, deps.agentExists);
+    const envValue = deps.envValue ?? (() => undefined);
+    const { setup } = template;
+    return {
+        name,
+        systemPrompt: template.candidate.agent.systemPrompt,
+        abilities: setup.abilities,
+        skills: (setup.skills ?? []).map((s) => s.id),
+        rules: setup.rules.map((r) => ({ tool: r.tool, decision: r.decision })),
+        // A key set for the whole project already counts for a new agent.
+        keys: keyGroups(template).map((names) => ({ names, set: names.some((n) => Boolean(envValue(name, n))) })),
+        settings: setup.env ?? {},
+        schedule: setup.schedule ? `${describeTemplateSchedule(setup.schedule)} (created paused)` : null,
+        needsApprovals: setup.needsApprovals,
+        notes: setup.notes ?? [],
+    };
 }
-/** Creates a new agent from the template, under the first free name, so
- * the same template can be used more than once. */
+/** What's left once the agent exists, each linked to where it's done. */
+export function templateChecklist(template, name, deps, failed = []) {
+    const tab = (t) => `/agents/config?agent=${encodeURIComponent(name)}&tab=${t}`;
+    const items = [];
+    for (const f of failed)
+        items.push({ label: `Install the ${f.name} ability (it couldn't be installed: ${f.error})`, href: tab('abilities') });
+    const missing = keyGroups(template).filter((names) => !names.some((n) => deps.envValue(name, n)));
+    const single = missing.filter((g) => g.length === 1).map((g) => g[0]);
+    if (single.length)
+        items.push({ label: `Add ${single.length === 1 ? 'its key' : 'its keys'}: ${single.join(', ')}`, href: tab('env') });
+    for (const group of missing.filter((g) => g.length > 1)) {
+        items.push({ label: `Add one of ${group.slice(0, -1).join(', ')} or ${group.at(-1)}`, href: tab('env') });
+    }
+    if (template.setup.needsApprovals && !deps.messagingConfigured(name)) {
+        items.push({ label: 'Choose where approval requests go: Slack, email, Lark or a webhook', href: tab('messaging') });
+    }
+    for (const note of template.setup.notes ?? [])
+        items.push({ label: note });
+    if (template.setup.schedule) {
+        items.push({ label: `Turn on its schedule (${describeTemplateSchedule(template.setup.schedule)}) once it works in Chat`, href: tab('schedules') });
+    }
+    return items;
+}
+/** Creates a new agent from the template, with its whole setup, under the
+ * first free name, so the same template can be used more than once. */
 export async function createFromTemplate(id, deps) {
-    return createAgentFromCandidate(templateAt(id).candidate, deps);
+    if (!('scaffoldAgent' in deps))
+        return createFromTemplateLegacy(id, deps);
+    const template = templateAt(id);
+    const { candidate, setup } = template;
+    const name = freeAgentName(candidate.agent.name, deps.agentExists);
+    // 1. The agent, and its permissions: everything asks unless a rule says
+    //    otherwise, and the template's rules come first.
+    await deps.scaffoldAgent(name, candidate.agent.systemPrompt);
+    setDefaultDecision(name, 'ask');
+    for (const rule of setup.rules) {
+        try {
+            addActauthRule(name, { name: rule.name, scope: '*/*', tool: rule.tool, decision: rule.decision });
+        }
+        catch (err) {
+            if (!(err instanceof ActauthRuleExistsError))
+                throw err;
+        }
+    }
+    // 2. Abilities: their tools, skills and rules. One failing doesn't stop
+    //    the rest; it heads the checklist.
+    const installed = [];
+    const failed = [];
+    for (const spec of setup.abilities) {
+        if (!deps.installAbility) {
+            failed.push({ name: spec, error: 'installing abilities needs LOOPENGINE_ADMIN_AUTH set on the server' });
+            continue;
+        }
+        try {
+            await deps.installAbility(name, spec);
+            installed.push(spec);
+        }
+        catch (err) {
+            failed.push({ name: spec, error: installFailureReason(err) });
+        }
+    }
+    // 3. Its own skills and non-secret settings.
+    for (const skill of setup.skills ?? [])
+        writeSkill(name, skill.id, { description: skill.description, body: skill.body });
+    for (const [variable, value] of Object.entries(setup.env ?? {}))
+        await setAgentEnvVar(name, variable, value);
+    // 4. Load it, now that everything is in place.
+    let loadError;
+    try {
+        await deps.registerAgent(name);
+    }
+    catch (err) {
+        loadError = err instanceof Error ? err.message : String(err);
+    }
+    // 5. Its schedule, paused until the person turns it on.
+    let schedule;
+    let scheduleError;
+    if (setup.schedule) {
+        try {
+            const startAt = templateScheduleStart(setup.schedule);
+            const task = await createScheduledTask({
+                agent: name,
+                message: setup.schedule.message,
+                schedule: { every: setup.schedule.every, ...(startAt ? { start_at: startAt } : {}) },
+                task_name: setup.schedule.name,
+            });
+            await pauseScheduledTask(task.task_id);
+            schedule = { description: describeTemplateSchedule(setup.schedule), timeZone: workspaceTimeZone(), ...(startAt ? { next_run_at: startAt } : {}) };
+        }
+        catch (err) {
+            scheduleError = err instanceof Error ? err.message : String(err);
+        }
+    }
+    return {
+        name,
+        abilities: { installed, failed },
+        checklist: templateChecklist(template, name, deps, failed),
+        ...(candidate.agent.exampleMessage ? { exampleMessage: candidate.agent.exampleMessage } : {}),
+        ...(schedule ? { schedule } : {}),
+        ...(scheduleError ? { scheduleError } : {}),
+        ...(loadError ? { loadError } : {}),
+    };
+}
+/** An older project adapter's create: the agent with its instructions,
+ * permissions and paused schedule, as before; its abilities head the
+ * checklist with how to get them installed automatically. */
+async function createFromTemplateLegacy(id, deps) {
+    const template = templateAt(id);
+    const { candidate, setup } = template;
+    const name = freeAgentName(candidate.agent.name, deps.agentExists);
+    await deps.createAgent(name, candidate.agent.systemPrompt);
+    setDefaultDecision(name, 'ask');
+    for (const rule of setup.rules) {
+        try {
+            addActauthRule(name, { name: rule.name, scope: '*/*', tool: rule.tool, decision: rule.decision });
+        }
+        catch (err) {
+            if (!(err instanceof ActauthRuleExistsError))
+                throw err;
+        }
+    }
+    const failed = setup.abilities.map((spec) => ({ name: spec, error: "this project's server is from an older LoopEngine template; update it from Settings → Upgrade to have templates install abilities" }));
+    let schedule;
+    let scheduleError;
+    if (setup.schedule) {
+        try {
+            const startAt = templateScheduleStart(setup.schedule);
+            const task = await createScheduledTask({ agent: name, message: setup.schedule.message, schedule: { every: setup.schedule.every, ...(startAt ? { start_at: startAt } : {}) }, task_name: setup.schedule.name });
+            await pauseScheduledTask(task.task_id);
+            schedule = { description: describeTemplateSchedule(setup.schedule), timeZone: workspaceTimeZone(), ...(startAt ? { next_run_at: startAt } : {}) };
+        }
+        catch (err) {
+            scheduleError = err instanceof Error ? err.message : String(err);
+        }
+    }
+    return {
+        name,
+        abilities: { installed: [], failed },
+        checklist: templateChecklist(template, name, { envValue: () => undefined, messagingConfigured: () => false }, failed),
+        ...(candidate.agent.exampleMessage ? { exampleMessage: candidate.agent.exampleMessage } : {}),
+        ...(schedule ? { schedule } : {}),
+        ...(scheduleError ? { scheduleError } : {}),
+    };
 }

package/dist/web/templates-page.js

@@ -63,23 +63,32 @@ ${consoleShellScript}
     }).join('') + '</ul>';
   }
 
+  var canInstall = true;
+  var DECISIONS = { allow: 'runs on its own', ask: 'asks you first', deny: 'never' };
+  var CHECK = String.fromCharCode(10003);
+
   function cardHtml(t) {
     return '<div class="tp-card" data-id="' + esc(t.id) + '">' +
       '<span class="tp-cat">' + esc(t.category) + '</span>' +
       '<h3>' + esc(t.title) + '</h3>' +
       '<div>' + esc(t.summary) + '</div>' +
       '<div class="meta">' +
-        '<div><strong>Starts:</strong> ' + esc(t.trigger) + '</div>' +
+        '<div><strong>Runs:</strong> ' + esc(t.trigger) + '</div>' +
         (t.asksFirst.length ? '<div><strong>Asks you first:</strong> ' + esc(t.asksFirst.join(', ')) + '</div>' : '') +
-        (t.needs.length ? '<div><strong>Needs:</strong> ' + esc(t.needs.join(', ')) + '</div>' : '') +
+        '<div><strong>Installs:</strong> ' + t.abilities.map(function (a) { return '<code>' + esc(a) + '</code>'; }).join(' ') + '</div>' +
       '</div>' +
       '<div class="row"><button type="button" class="primary tp-use">Use this template</button></div>' +
       '<div class="tp-slot"></div></div>';
   }
 
+  function listHtml(items) {
+    return '<ul style="margin:4px 0 0;padding-left:18px">' + items.join('') + '</ul>';
+  }
+
   function show() {
     api('GET', '/starter-templates').then(function (r) {
       if (!r.ok) { page.innerHTML = '<p class="error">' + esc(r.body.error || 'Could not load the templates') + '</p>'; return; }
+      canInstall = r.body.canInstallAbilities !== false;
       page.innerHTML = '<div class="tp-grid">' + r.body.templates.map(cardHtml).join('') + '</div>' +
         '<p class="hint" style="margin-top:16px">Not what you need? <a href="/interview">Find your first agent</a> suggests one from your own work, or <a href="/agents?new=1">start from a blank agent</a>.</p>';
       Array.prototype.forEach.call(page.querySelectorAll('.tp-use'), function (btn) {
@@ -95,24 +104,40 @@ ${consoleShellScript}
     api('GET', '/starter-templates/' + encodeURIComponent(id) + '/preview').then(function (r) {
       if (!r.ok) { slot.innerHTML = '<p class="error">' + esc(r.body.error || 'Could not prepare it') + '</p>'; return; }
       var p = r.body;
+      var settings = Object.keys(p.settings || {});
       slot.innerHTML = '<div class="tp-preview">' +
         '<div><strong>Agent:</strong> <code>' + esc(p.name) + '</code></div>' +
         '<div><strong>Instructions</strong> <span class="hint">(edit them later in its Overview tab)</span><pre>' + esc(p.systemPrompt) + '</pre></div>' +
-        '<div><strong>Permissions:</strong> ' + esc(p.permissions) + '</div>' +
+        '<div><strong>Installs</strong> <span class="hint">(abilities: their tools, skills and permission rules)</span>' +
+          listHtml(p.abilities.map(function (a) { return '<li><code>' + esc(a) + '</code></li>'; })) +
+          (canInstall ? '' : '<p class="error" style="margin:4px 0 0">Installing abilities needs <code>LOOPENGINE_ADMIN_AUTH</code> set on the server. Without it, the agent is created and its abilities head the checklist.</p>') + '</div>' +
+        '<div><strong>Permissions</strong> <span class="hint">(anything not listed asks you first)</span>' +
+          listHtml(p.rules.map(function (rule) { return '<li><code>' + esc(rule.tool) + '</code>: ' + esc(DECISIONS[rule.decision] || rule.decision) + '</li>'; })) + '</div>' +
+        '<div><strong>Keys it needs</strong>' +
+          listHtml(p.keys.map(function (k) {
+            var names = k.names.length > 1 ? 'one of ' + k.names.join(', ') : k.names[0];
+            return '<li>' + esc(names) + (k.set ? ' <span class="hint">' + CHECK + ' already set</span>' : '') + '</li>';
+          })) + '</div>' +
+        (settings.length ? '<div><strong>Settings filled in:</strong> ' + settings.map(function (s) { return '<code>' + esc(s) + '=' + esc(p.settings[s]) + '</code>'; }).join(', ') + '</div>' : '') +
         (p.schedule ? '<div><strong>Schedule:</strong> ' + esc(p.schedule) + '</div>' : '') +
-        '<div><strong>Then, to finish setup:</strong>' + checklistHtml(p.checklist) + '</div>' +
+        (p.needsApprovals ? '<div><strong>Approvals:</strong> requests reach you wherever its Messaging tab sends them (Slack, email, Lark or a webhook).</div>' : '') +
+        (p.notes.length ? '<div><strong>You also</strong>' + listHtml(p.notes.map(function (n) { return '<li>' + esc(n) + '</li>'; })) + '</div>' : '') +
         '<div class="row"><button type="button" class="primary tp-create">Create it</button><button type="button" class="tp-cancel">Cancel</button></div>' +
         '<div class="hint tp-status"></div></div>';
       slot.querySelector('.tp-cancel').addEventListener('click', function () { slot.innerHTML = ''; });
       slot.querySelector('.tp-create').addEventListener('click', function (ev) {
         var btn = ev.currentTarget;
         btn.disabled = true;
-        slot.querySelector('.tp-status').textContent = 'Creating' + ELLIPSIS;
+        slot.querySelector('.tp-status').textContent = 'Creating it and installing its abilities' + ELLIPSIS + ' (this can take a minute)';
         api('POST', '/starter-templates/' + encodeURIComponent(id) + '/create').then(function (r2) {
           if (!r2.ok) { btn.disabled = false; slot.querySelector('.tp-status').textContent = r2.body.error || 'Could not create it'; return; }
           var c = r2.body;
+          var installed = c.abilities.installed.map(function (a) { return '<code>' + esc(a) + '</code>'; }).join(' ');
           slot.innerHTML = '<div class="tp-preview">' +
-            '<div><strong>Created <code>' + esc(c.name) + '</code>.</strong> It asks you before every tool until you change that in its Permissions tab.</div>' +
+            '<div><strong>Created <code>' + esc(c.name) + '</code>.</strong> Anything its permissions don' + String.fromCharCode(8217) + 't cover asks you first.</div>' +
+            (installed ? '<div>' + CHECK + ' Installed ' + installed + '</div>' : '') +
+            (c.schedule ? '<div>' + CHECK + ' Schedule created, paused: ' + esc(c.schedule.description) + (c.schedule.next_run_at ? ' (first run ' + esc(new Date(c.schedule.next_run_at).toLocaleString(undefined, c.schedule.timeZone ? { timeZone: c.schedule.timeZone, timeZoneName: 'short' } : undefined)) + ' once turned on)' : '') + '</div>' : '') +
+            (c.loadError ? '<div class="error">It was written but couldn' + String.fromCharCode(8217) + 't be loaded: ' + esc(c.loadError) + '</div>' : '') +
             (c.scheduleError ? '<div class="error">Its schedule wasn' + String.fromCharCode(8217) + 't created: ' + esc(c.scheduleError) + '. Add one in its Schedules tab.</div>' : '') +
             '<div><strong>Finish setup:</strong>' + checklistHtml(c.checklist) + '</div>' +
             (c.exampleMessage ? '<div><strong>Try it</strong> in Chat with: <em>' + esc(c.exampleMessage) + '</em></div>' : '') +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -46,6 +46,8 @@
     "dist/core/trusted-proxy.d.ts",
     "dist/core/usage.js",
     "dist/core/usage.d.ts",
+    "dist/core/email-senders.js",
+    "dist/core/email-senders.d.ts",
     "dist/core/notifier-file.js",
     "dist/core/notifier-file.d.ts",
     "dist/core/notifier-deliveries.js",
@@ -55,6 +57,8 @@
     "dist/core/messaging",
     "dist/core/scheduler.js",
     "dist/core/scheduler.d.ts",
+    "dist/core/time-zone.js",
+    "dist/core/time-zone.d.ts",
     "dist/core/session-store.js",
     "dist/core/session-store.d.ts",
     "dist/core/vector-index.js",