loopengine 0.1.94 → 0.1.97

package/dist/core/ability-sources.js

@@ -0,0 +1,312 @@
+// Private ability sources: where a project's own, unpublished abilities
+// come from, next to the public ones on npm (packages tagged
+// loopengine-ability). Set in the console's Settings and kept in
+// ability-sources.yml in the project root (or the file
+// LOOPENGINE_ABILITY_SOURCES_FILE names):
+//
+//   sources:
+//     - id: github-loopengine-co
+//       type: github          # a GitHub org or user; each ability is a repo
+//       owner: loopengine-co  # with loopengine.ability.json at its root
+//     - id: npm-everymarket
+//       type: npm             # a private registry, for one scope
+//       registry: https://npm.pkg.github.com
+//       scope: "@everymarket"
+//     - id: folder-abilities
+//       type: folder          # a local folder of ability folders
+//       path: ../loopengine-abilities
+//
+// A source's token (a GitHub token that can read the repos, or the
+// registry's auth token) is never in the file: it lives in the project
+// env as LOOPENGINE_ABILITY_SOURCE_<ID>_TOKEN, saved like a model key.
+// It's handed to `npm pack` only while an ability is fetched (see
+// abilityFetchAuth), so an installed ability's recorded spec
+// (github:owner/repo, @scope/name, file:/path) never carries it, and an
+// upgrade fetches the same way.
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { workspaceAbilityAt } from './workspace-abilities.js';
+export class AbilitySourceError extends Error {
+}
+export const ABILITY_SOURCES_FILE_ENV = 'LOOPENGINE_ABILITY_SOURCES_FILE';
+export function abilitySourcesPath() {
+    return resolve(process.cwd(), process.env[ABILITY_SOURCES_FILE_ENV]?.trim() || 'ability-sources.yml');
+}
+/** The env var a source's token lives in. */
+export function sourceTokenVar(id) {
+    return `LOOPENGINE_ABILITY_SOURCE_${id.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_TOKEN`;
+}
+function sourceToken(source) {
+    return source.type === 'folder' ? undefined : process.env[sourceTokenVar(source.id)]?.trim() || undefined;
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+}
+/** Throws AbilitySourceError naming the first problem. An id is made up
+ * from the source when none is given. */
+export function validateAbilitySource(input) {
+    if (!input || typeof input !== 'object')
+        throw new AbilitySourceError('a source must be an object');
+    const raw = input;
+    const str = (key) => (typeof raw[key] === 'string' && raw[key].trim() ? raw[key].trim() : undefined);
+    const givenId = str('id');
+    if (givenId && !/^[a-z0-9][a-z0-9-]{0,39}$/.test(givenId))
+        throw new AbilitySourceError('id must be lowercase letters, digits and hyphens');
+    switch (raw.type) {
+        case 'github': {
+            const owner = str('owner')?.replace(/^https?:\/\/github\.com\//, '').replace(/\/+$/, '');
+            if (!owner || !/^[A-Za-z0-9][A-Za-z0-9-]{0,38}$/.test(owner))
+                throw new AbilitySourceError('owner must be a GitHub org or user name, like loopengine-co');
+            return { id: givenId ?? slug(`github-${owner}`), type: 'github', owner };
+        }
+        case 'npm': {
+            const registry = str('registry')?.replace(/\/+$/, '');
+            if (!registry || !/^https?:\/\/[^/]+/.test(registry))
+                throw new AbilitySourceError('registry must be an http(s) URL, like https://npm.pkg.github.com');
+            const scope = str('scope');
+            // A scope, so only its packages come from this registry; public
+            // abilities keep coming from npm.
+            if (!scope || !/^@[a-z0-9][a-z0-9._-]*$/.test(scope))
+                throw new AbilitySourceError('scope must be an npm scope, like @everymarket');
+            return { id: givenId ?? slug(`npm-${scope}`), type: 'npm', registry, scope };
+        }
+        case 'folder': {
+            const path = str('path');
+            if (!path)
+                throw new AbilitySourceError('path is required for a folder');
+            return { id: givenId ?? slug(`folder-${basename(path)}`), type: 'folder', path };
+        }
+        default:
+            throw new AbilitySourceError('type must be github, npm or folder');
+    }
+}
+export function readAbilitySources() {
+    const path = abilitySourcesPath();
+    if (!existsSync(path))
+        return [];
+    const parsed = parseYaml(readFileSync(path, 'utf8'));
+    if (parsed?.sources !== undefined && !Array.isArray(parsed.sources))
+        throw new AbilitySourceError('sources must be a list');
+    const sources = [];
+    for (const entry of parsed?.sources ?? []) {
+        const source = validateAbilitySource(entry);
+        if (!sources.some((s) => s.id === source.id))
+            sources.push(source);
+    }
+    return sources;
+}
+function writeAbilitySources(sources) {
+    const path = abilitySourcesPath();
+    if (!sources.length) {
+        rmSync(path, { force: true });
+        return;
+    }
+    const header = '# Private ability sources, edited from the console (Settings). Each source\'s\n' +
+        '# token lives in the project env as LOOPENGINE_ABILITY_SOURCE_<ID>_TOKEN.\n';
+    writeFileSync(path, header + stringifyYaml({ sources }));
+}
+/** Adds a source, or replaces the one with the same id. */
+export function saveAbilitySource(input) {
+    const source = validateAbilitySource(input);
+    const sources = readAbilitySources();
+    const index = sources.findIndex((s) => s.id === source.id);
+    if (index === -1)
+        sources.push(source);
+    else
+        sources[index] = source;
+    writeAbilitySources(sources);
+    listCache.delete(source.id);
+    return source;
+}
+export function removeAbilitySource(id) {
+    writeAbilitySources(readAbilitySources().filter((s) => s.id !== id));
+    listCache.delete(id);
+}
+export function describeSource(source) {
+    if (source.type === 'github')
+        return `GitHub ${source.owner}`;
+    if (source.type === 'npm')
+        return `npm ${source.scope} (${new URL(source.registry).host})`;
+    return `Folder ${source.path}`;
+}
+// ---- Listing what a source offers ----
+const LIST_TTL_MS = 5 * 60 * 1000;
+const listCache = new Map();
+/** The abilities a source offers. GitHub and npm listings are cached for
+ * five minutes per token; a folder is read fresh. Throws with a message
+ * fit for the console when the source can't be read. */
+export async function listSourceAbilities(source, options = {}) {
+    if (source.type === 'folder')
+        return listFolder(source);
+    const token = sourceToken(source);
+    const key = JSON.stringify([source, token ?? '']);
+    const cached = listCache.get(source.id);
+    if (cached && cached.key === key && Date.now() - cached.at < LIST_TTL_MS)
+        return cached.abilities;
+    const doFetch = options.fetch ?? fetch;
+    const abilities = source.type === 'github' ? await listGitHub(source, token, doFetch) : await listNpm(source, token, doFetch);
+    listCache.set(source.id, { at: Date.now(), key, abilities });
+    return abilities;
+}
+function readAbilityDir(dir) {
+    if (!existsSync(join(dir, 'loopengine.ability.json')))
+        return undefined;
+    let pkg = {};
+    try {
+        pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    }
+    catch { }
+    return { name: pkg.name || basename(dir), description: pkg.description || '', version: pkg.version || '', spec: `file:${dir}` };
+}
+function listFolder(source) {
+    const root = resolve(process.cwd(), source.path);
+    if (!existsSync(root) || !statSync(root).isDirectory())
+        throw new Error(`${source.path} isn't a folder on this server`);
+    const own = readAbilityDir(root);
+    if (own)
+        return [own];
+    return readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && !d.name.startsWith('.') && d.name !== 'node_modules')
+        .flatMap((d) => readAbilityDir(join(root, d.name)) ?? [])
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+async function githubJson(url, token, doFetch) {
+    const res = await doFetch(url, {
+        headers: { accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', 'user-agent': 'loopengine', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+        signal: AbortSignal.timeout(15_000),
+    });
+    return { status: res.status, body: await res.json().catch(() => null) };
+}
+async function listGitHub(source, token, doFetch) {
+    const owner = source.owner;
+    // An org's repos; for a user, their own (private ones need a token for
+    // that user, through /user/repos).
+    let { status, body } = await githubJson(`https://api.github.com/orgs/${owner}/repos?per_page=100&type=all`, token, doFetch);
+    if (status === 404) {
+        ;
+        ({ status, body } = token
+            ? await githubJson('https://api.github.com/user/repos?per_page=100&affiliation=owner', token, doFetch)
+            : await githubJson(`https://api.github.com/users/${owner}/repos?per_page=100`, token, doFetch));
+    }
+    if (status === 401)
+        throw new Error('GitHub refused the token: check it and that it can read these repos');
+    if (status === 403)
+        throw new Error('GitHub refused the request (rate limit or token permissions); try again later or save a token');
+    if (status === 404)
+        throw new Error(`No GitHub org or user named ${owner}`);
+    if (status !== 200 || !Array.isArray(body))
+        throw new Error(`GitHub answered HTTP ${status}`);
+    const repos = body
+        .filter((r) => !r.archived && (r.owner?.login ?? owner).toLowerCase() === owner.toLowerCase());
+    const found = await Promise.all(repos.map(async (repo) => {
+        const manifest = await githubJson(`https://api.github.com/repos/${owner}/${repo.name}/contents/loopengine.ability.json`, token, doFetch);
+        if (manifest.status !== 200)
+            return undefined;
+        const pkgFile = await githubJson(`https://api.github.com/repos/${owner}/${repo.name}/contents/package.json`, token, doFetch);
+        let pkg = {};
+        const content = pkgFile.body?.content;
+        if (pkgFile.status === 200 && content) {
+            try {
+                pkg = JSON.parse(Buffer.from(content, 'base64').toString('utf8'));
+            }
+            catch { }
+        }
+        return { name: pkg.name || repo.name, description: pkg.description || repo.description || '', version: pkg.version || '', spec: `github:${owner}/${repo.name}` };
+    }));
+    return found.filter((a) => Boolean(a)).sort((a, b) => a.name.localeCompare(b.name));
+}
+async function listNpm(source, token, doFetch) {
+    const url = `${source.registry}/-/v1/search?text=${encodeURIComponent(`keywords:loopengine-ability ${source.scope}`)}&size=100`;
+    const res = await doFetch(url, { headers: token ? { authorization: `Bearer ${token}` } : {}, signal: AbortSignal.timeout(15_000) });
+    if (res.status === 401 || res.status === 403)
+        throw new Error('The registry refused the token');
+    // GitHub Packages, for one, has no search; its abilities can still be
+    // installed by name.
+    if (!res.ok)
+        throw new Error(`This registry can't be searched (HTTP ${res.status}); install its abilities by name instead`);
+    const data = (await res.json());
+    return (data.objects ?? [])
+        .map((o) => o.package)
+        .filter((p) => p.name.startsWith(`${source.scope}/`))
+        .map((p) => ({ name: p.name, description: p.description ?? '', version: p.version, spec: p.name }));
+}
+// ---- Where an installed ability came from ----
+/** Public (npm) or private (a source, a git repo or a local folder), from
+ * the spec it was installed with. */
+export function abilityOrigin(spec, name, sources = safeReadSources()) {
+    const target = spec || name;
+    if (target.startsWith('file:') || target.startsWith('/') || target.startsWith('.')) {
+        const path = target.replace(/^file:/, '');
+        // The workspace's copy (core/workspace-abilities.ts): labelled by where
+        // that copy came from.
+        const copy = workspaceAbilityAt(path);
+        if (copy) {
+            if (copy.source.startsWith('upload:'))
+                return { kind: 'private', label: 'Workspace (uploaded)' };
+            const from = copy.source.startsWith('file:') ? undefined : abilityOrigin(copy.source, copy.name, sources);
+            return { kind: 'private', label: from && from.kind === 'private' ? `Workspace (${from.label})` : 'Workspace' };
+        }
+        const folder = sources.find((s) => s.type === 'folder' && resolve(process.cwd(), s.path) === resolve(path, '..'));
+        return { kind: 'private', label: folder ? describeSource(folder) : `Folder ${path}` };
+    }
+    const github = target.match(/^(?:github:|git\+ssh:\/\/git@github\.com\/|git\+https:\/\/github\.com\/|https:\/\/github\.com\/|git@github\.com:)([^/]+)\/([^/#.]+)/);
+    if (github)
+        return { kind: 'private', label: `GitHub ${github[1]}/${github[2]}` };
+    if (/^(git\+|git:|https?:)/.test(target))
+        return { kind: 'private', label: 'Git' };
+    const scope = target.match(/^(@[^/]+)\//)?.[1];
+    const npmSource = scope ? sources.find((s) => s.type === 'npm' && s.scope === scope) : undefined;
+    if (npmSource)
+        return { kind: 'private', label: describeSource(npmSource) };
+    return { kind: 'public', label: 'npm' };
+}
+function safeReadSources() {
+    try {
+        return readAbilitySources();
+    }
+    catch {
+        return [];
+    }
+}
+// ---- Fetching with a source's token ----
+/** What `npm pack` needs to fetch from the private sources: GitHub tokens
+ * as git URL rewrites (only in the child's env, per owner), and a
+ * temporary npm config adding each private scope's registry and token to
+ * the user's own. `cleanup` removes that file. */
+export function abilityFetchAuth(sources = safeReadSources()) {
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+    const rewrites = [];
+    for (const source of sources) {
+        const token = sourceToken(source);
+        if (source.type !== 'github' || !token)
+            continue;
+        const authed = `https://x-access-token:${token}@github.com/${source.owner}/`;
+        for (const from of [`https://github.com/${source.owner}/`, `git@github.com:${source.owner}/`, `ssh://git@github.com/${source.owner}/`])
+            rewrites.push([`url.${authed}.insteadOf`, from]);
+    }
+    if (rewrites.length) {
+        const start = Number(process.env.GIT_CONFIG_COUNT) || 0;
+        rewrites.forEach(([key, value], i) => {
+            env[`GIT_CONFIG_KEY_${start + i}`] = key;
+            env[`GIT_CONFIG_VALUE_${start + i}`] = value;
+        });
+        env.GIT_CONFIG_COUNT = String(start + rewrites.length);
+    }
+    const npmLines = sources.flatMap((source) => {
+        if (source.type !== 'npm')
+            return [];
+        const token = sourceToken(source);
+        const url = new URL(source.registry);
+        return [`${source.scope}:registry=${source.registry}/`, ...(token ? [`//${url.host}${url.pathname.replace(/\/+$/, '')}/:_authToken=${token}`] : [])];
+    });
+    if (!npmLines.length)
+        return { args: [], env, cleanup: () => { } };
+    const dir = mkdtempSync(join(tmpdir(), 'loopengine-npmrc-'));
+    const userNpmrc = join(homedir(), '.npmrc');
+    const own = existsSync(userNpmrc) ? readFileSync(userNpmrc, 'utf8') + '\n' : '';
+    const file = join(dir, 'npmrc');
+    writeFileSync(file, own + npmLines.join('\n') + '\n', { mode: 0o600 });
+    return { args: ['--userconfig', file], env, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}

package/dist/core/agent-config.d.ts

@@ -219,6 +219,14 @@ export type HttpNotifierConfig = {
         buttons?: boolean;
     };
     events: HttpNotifierEvent[];
+} | {
+    channel: 'telegram';
+    config: {
+        botToken: string;
+        chatId: string;
+        publicUrl?: string;
+    };
+    events: HttpNotifierEvent[];
 } | {
     channel: 'email';
     config: {
@@ -256,7 +264,7 @@ export type HttpNotifierConfig = {
  * export your own `createModelCall` for anything this can't express (a
  * canned/simulated `ModelCall` for a demo, a custom SDK client, a
  * provider this doesn't list). `model` is required for `openai`/
- * `deepseek`/`kimi`/`glm`/`gemini` (no safe hardcoded default — a
+ * `deepseek`/`kimi`/`glm`/`gemini`/`xai`/`meta` (no safe hardcoded default — a
  * flagship model name changes too often to bake one in) but optional for
  * `anthropic` (defaults to `'claude-sonnet-5'`), mirroring each factory's
  * own options exactly. */
@@ -300,6 +308,18 @@ export type AgentModelConfig = {
     apiKey?: string;
     maxTokens?: number;
     baseURL?: string;
+} | {
+    provider: 'xai';
+    model: string;
+    apiKey?: string;
+    maxTokens?: number;
+    baseURL?: string;
+} | {
+    provider: 'meta';
+    model: string;
+    apiKey?: string;
+    maxTokens?: number;
+    baseURL?: string;
 };
 export interface ToolSchema {
     name: string;

package/dist/core/discover-agents.js

@@ -46,6 +46,8 @@ const PROVIDER_KEY_ENV = {
     kimi: 'MOONSHOT_API_KEY',
     glm: 'GLM_API_KEY',
     gemini: 'GEMINI_API_KEY',
+    xai: 'XAI_API_KEY',
+    meta: 'META_API_KEY',
 };
 export async function synthesizeCreateModelCall(model) {
     let build;
@@ -69,10 +71,18 @@ export async function synthesizeCreateModelCall(model) {
         const { createGlmModelCall } = await import('./model-calls/glm-model-call.js');
         build = () => createGlmModelCall(model);
     }
-    else {
+    else if (model.provider === 'gemini') {
         const { createGeminiModelCall } = await import('./model-calls/gemini-model-call.js');
         build = () => createGeminiModelCall(model);
     }
+    else if (model.provider === 'xai') {
+        const { createXaiModelCall } = await import('./model-calls/xai-model-call.js');
+        build = () => createXaiModelCall(model);
+    }
+    else {
+        const { createMetaModelCall } = await import('./model-calls/meta-model-call.js');
+        build = () => createMetaModelCall(model);
+    }
     // Rebuilt when the key it was built with changes, so a key saved or
     // replaced on the console's Models page applies to the next call
     // without a restart. An explicit `apiKey` in the config never changes.

package/dist/core/http-notifier.d.ts

@@ -1,6 +1,6 @@
 import { type Approver } from 'actauth';
 import type { AgentConfig, HttpNotifierConfig, QuestionHandler } from './agent-config.js';
-import { type NotifierFile } from './notifier-file.js';
+import { type NotifierFile, type NotifierFileChannel } from './notifier-file.js';
 interface ResolvedHttpNotifier {
     approver?: Approver;
     questionHandler?: QuestionHandler;
@@ -17,6 +17,12 @@ export declare function describeNotifier(config: AgentConfig): {
     file?: NotifierFile;
     missingSecret?: string;
     error?: string;
+    /** The saved connections that send (the webhook, then the primary
+     * messaging app), and which are held back by a missing secret. */
+    active?: Array<{
+        channel: NotifierFileChannel;
+        missingSecret?: string;
+    }>;
 };
 /** AgentConfig.httpNotifier when the agent sets one in code; otherwise
  * its agents/<name>/messaging.yml (see core/notifier-file.ts), re-read on

package/dist/core/http-notifier.js

@@ -1,11 +1,12 @@
 import { WebhookNotifier, postLifecycleWebhook } from './http-notify-triggers/webhook.js';
 import { SlackNotifier } from './http-notify-triggers/slack.js';
 import { LarkNotifier } from './http-notify-triggers/lark.js';
+import { TelegramNotifier } from './http-notify-triggers/telegram.js';
 import { EmailNotifier } from './http-notify-triggers/email.js';
 import { DatabaseApprover } from './http-notify-triggers/database.js';
 import { RedisQueueApprover } from './http-notify-triggers/redis.js';
 import { agentDirFor, createAgentEnv } from './agent-env.js';
-import { notifierConfigFromFile, readNotifierFile } from './notifier-file.js';
+import { notifierConfigFromFile, readActiveConnections, readNotifierFile } from './notifier-file.js';
 import { recordThread } from './messaging/threads.js';
 const EMPTY = {};
 // Keyed by the AgentConfig object itself, not its httpNotifier field
@@ -48,8 +49,15 @@ export function describeNotifier(config) {
     }
     if (!file)
         return { source: 'none' };
-    const { missingSecret } = notifierConfigFromFile(file, createAgentEnv(config.name, dir), config.name);
-    return { source: missingSecret ? 'none' : 'file', channel: file.channel, events: file.events, file, missingSecret };
+    const env = createAgentEnv(config.name, dir);
+    const active = readActiveConnections(dir).map((c) => {
+        const { missingSecret } = notifierConfigFromFile(c, env, config.name);
+        return missingSecret ? { channel: c.channel, missingSecret } : { channel: c.channel };
+    });
+    const { missingSecret } = notifierConfigFromFile(file, env, config.name);
+    // Sending when any active connection has its secret.
+    const sending = active.some((a) => !a.missingSecret);
+    return { source: sending ? 'file' : 'none', channel: file.channel, events: file.events, file, missingSecret, active };
 }
 /** AgentConfig.httpNotifier when the agent sets one in code; otherwise
  * its agents/<name>/messaging.yml (see core/notifier-file.ts), re-read on
@@ -65,20 +73,61 @@ export function resolveHttpNotifier(config) {
     cache.set(config, resolved);
     return resolved;
 }
+// The webhook (when set up) and the primary messaging app, each built on
+// its own and then combined; one held back by a missing secret is left
+// out.
 function resolveFromFile(config) {
     const dir = agentDirFor(config);
-    let file;
+    let files;
     try {
-        file = readNotifierFile(dir);
+        files = readActiveConnections(dir);
     }
     catch (err) {
         console.error(`[loopengine] ignoring the messaging settings in agents/${config.name}/:`, err instanceof Error ? err.message : err);
         return EMPTY;
     }
-    if (!file)
-        return EMPTY;
-    const { config: httpNotifier } = notifierConfigFromFile(file, createAgentEnv(config.name, dir), config.name);
-    return httpNotifier ? buildResolved(httpNotifier, dir) : EMPTY;
+    const env = createAgentEnv(config.name, dir);
+    const resolved = files.flatMap((file) => {
+        const { config: httpNotifier } = notifierConfigFromFile(file, env, config.name);
+        return httpNotifier ? [buildResolved(httpNotifier, dir)] : [];
+    });
+    return combineResolved(resolved);
+}
+/** Several notifiers as one: each request goes to every one of them under
+ * the first one's request id, so a decision through any of them resolves
+ * the same request; run started/finished go to all. One notifier is
+ * returned as it is. */
+function combineResolved(list) {
+    if (list.length <= 1)
+        return list[0] ?? EMPTY;
+    const approvers = list.map((r) => r.approver).filter((a) => Boolean(a));
+    const questioners = list.map((r) => r.questionHandler).filter((q) => Boolean(q));
+    const starts = list.map((r) => r.onRunStart).filter((f) => Boolean(f));
+    const finishes = list.map((r) => r.onRunFinish).filter((f) => Boolean(f));
+    const fanOutApprover = {
+        requestDurableApproval(tool, args, scope, reason) {
+            const { pendingId } = approvers[0].requestDurableApproval(tool, args, scope, reason);
+            for (const other of approvers.slice(1))
+                other.requestDurableApproval(tool, args, scope, reason, pendingId);
+            return { pendingId };
+        },
+    };
+    const fanOutQuestions = {
+        notifyPendingQuestion(question, options, agent, sessionId) {
+            const { pendingId } = questioners[0].notifyPendingQuestion(question, options, agent, sessionId);
+            for (const other of questioners.slice(1))
+                other.notifyPendingQuestion(question, options, agent, sessionId, pendingId);
+            return { pendingId };
+        },
+    };
+    return {
+        approver: approvers.length === 0 ? undefined : (approvers.length === 1 ? approvers[0] : fanOutApprover),
+        questionHandler: questioners.length === 0 ? undefined : (questioners.length === 1 ? questioners[0] : fanOutQuestions),
+        onRunStart: starts.length ? (context) => { for (const f of starts)
+            f(context); } : undefined,
+        onRunFinish: finishes.length ? (context) => { for (const f of finishes)
+            f(context); } : undefined,
+    };
 }
 /** `agentDir`: where a Slack request's thread is recorded, so replies in
  * it reach the agent (core/messaging/). */
@@ -128,6 +177,16 @@ function buildResolved(httpNotifier, agentDir) {
             };
             break;
         }
+        case 'telegram': {
+            const { botToken, chatId, publicUrl } = httpNotifier.config;
+            const telegram = new TelegramNotifier({ botToken, chatId, publicUrl });
+            return {
+                approver: events.has('approval') ? telegram : undefined,
+                questionHandler: events.has('question') ? telegram : undefined,
+                onRunStart: events.has('run_start') ? (context) => telegram.postMessage(formatChatLifecycleMessage('run_start', context)) : undefined,
+                onRunFinish: events.has('run_finish') ? (context) => telegram.postMessage(formatChatLifecycleMessage('run_finish', context)) : undefined,
+            };
+        }
         case 'email': {
             const { to, sendEmail, resolveBaseUrl, answerBaseUrl, signingSecret, linkTtlMs, publicUrl } = httpNotifier.config;
             const email = new EmailNotifier({ to, sendEmail, resolveBaseUrl, answerBaseUrl, signingSecret, linkTtlMs, publicUrl });

package/dist/core/http-notify-triggers/email.d.ts

@@ -37,10 +37,10 @@ export declare class EmailNotifier implements DurableApprover, DurableQuestionHa
     /** Decision-page mode: one link to decide (or answer) on this server,
      * or where to find the request when the server's address isn't known. */
     private decideHtml;
-    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string, pendingId?: string): {
         pendingId: string;
     };
-    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined): {
+    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined, pendingId?: string): {
         pendingId: string;
     };
     /** Public: core/http-notifier.ts's own onRunStart/onRunFinish lifecycle

package/dist/core/http-notify-triggers/email.js

@@ -108,8 +108,7 @@ export class EmailNotifier {
             return `<p>Open this agent's Messaging tab in the LoopEngine console to ${kind === 'approval' ? 'approve or deny it' : 'answer'}.</p>`;
         return `<p><a href="${base}${decidePath(pendingId, kind)}">${kind === 'approval' ? 'Review and approve or deny' : 'Answer'}</a></p>` + this.expiryNote();
     }
-    requestDurableApproval(tool, args, scope, reason) {
-        const pendingId = randomUUID();
+    requestDurableApproval(tool, args, scope, reason, pendingId = randomUUID()) {
         let links;
         if (this.magic) {
             const { resolveBaseUrl, signingSecret } = this.magic;
@@ -132,8 +131,7 @@ export class EmailNotifier {
         });
         return { pendingId };
     }
-    notifyPendingQuestion(question, options, agent, sessionId) {
-        const pendingId = randomUUID();
+    notifyPendingQuestion(question, options, agent, sessionId, pendingId = randomUUID()) {
         let links;
         if (this.magic) {
             const { answerBaseUrl, signingSecret } = this.magic;

package/dist/core/http-notify-triggers/lark.d.ts

@@ -23,10 +23,10 @@ export declare class LarkNotifier implements DurableApprover, DurableQuestionHan
         buttons?: boolean;
     });
     private decideLine;
-    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string, pendingId?: string): {
         pendingId: string;
     };
-    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined): {
+    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined, pendingId?: string): {
         pendingId: string;
     };
     /** Public, not private: core/http-notifier.ts's own onRunStart/onRunFinish

package/dist/core/http-notify-triggers/lark.js

@@ -81,8 +81,7 @@ export class LarkNotifier {
         const base = publicBaseUrl(this.publicUrl);
         return base ? `\n[${kind === 'approval' ? 'Open to approve or deny' : 'Open to answer'}](${base}${decidePath(pendingId, kind)})` : '';
     }
-    requestDurableApproval(tool, args, scope, reason) {
-        const pendingId = randomUUID();
+    requestDurableApproval(tool, args, scope, reason, pendingId = randomUUID()) {
         void (async () => {
             try {
                 const token = await getTenantAccessToken(this.appId, this.appSecret);
@@ -116,8 +115,7 @@ export class LarkNotifier {
         })();
         return { pendingId };
     }
-    notifyPendingQuestion(question, options, agent, sessionId) {
-        const pendingId = randomUUID();
+    notifyPendingQuestion(question, options, agent, sessionId, pendingId = randomUUID()) {
         const optionButtons = (options ?? []).map((option) => ({
             tag: 'button',
             text: { tag: 'plain_text', content: option },

package/dist/core/http-notify-triggers/slack.d.ts

@@ -36,10 +36,10 @@ export declare class SlackNotifier implements DurableApprover, DurableQuestionHa
     private replyHintBlocks;
     private threadRecorder;
     private decideLine;
-    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string, pendingId?: string): {
         pendingId: string;
     };
-    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined): {
+    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined, pendingId?: string): {
         pendingId: string;
     };
     /** Public, not private: core/http-notifier.ts's own onRunStart/onRunFinish

package/dist/core/http-notify-triggers/slack.js

@@ -66,8 +66,7 @@ export class SlackNotifier {
         const base = publicBaseUrl(this.publicUrl);
         return base ? `\n<${base}${decidePath(pendingId, kind)}|${kind === 'approval' ? 'Open to approve or deny' : 'Open to answer'}>` : '';
     }
-    requestDurableApproval(tool, args, scope, reason) {
-        const pendingId = randomUUID();
+    requestDurableApproval(tool, args, scope, reason, pendingId = randomUUID()) {
         this.postMessage(`Approval requested: ${tool} on ${scope.tenant}/${scope.environment}/${scope.agent}`, [
             {
                 type: 'section',
@@ -92,8 +91,7 @@ export class SlackNotifier {
         ], this.threadRecorder(pendingId, 'approval'));
         return { pendingId };
     }
-    notifyPendingQuestion(question, options, agent, sessionId) {
-        const pendingId = randomUUID();
+    notifyPendingQuestion(question, options, agent, sessionId, pendingId = randomUUID()) {
         // Slack rejects a block whose buttons share an action_id
         // (invalid_blocks), so each option gets its own: answer_option_<n>.
         const optionButtons = (options ?? []).map((option, i) => ({

package/dist/core/http-notify-triggers/telegram.d.ts

@@ -0,0 +1,28 @@
+import type { DurableApprover, Scope } from 'actauth';
+import type { DurableQuestionHandler } from '../agent-config.js';
+import { type DeliveryResult } from './webhook.js';
+/** The Messaging tab's Send test. */
+export declare function sendTestTelegramMessage(botToken: string, chatId: string, text: string): Promise<DeliveryResult>;
+export declare class TelegramNotifier implements DurableApprover, DurableQuestionHandler {
+    private readonly botToken;
+    private readonly chatId;
+    private readonly publicUrl?;
+    /** `publicUrl`: same meaning as SlackNotifier's — each message links to
+     * the decision page when the server's address is known. */
+    constructor(options: {
+        botToken: string;
+        chatId: string;
+        publicUrl?: string;
+    });
+    private decideLine;
+    private send;
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string, pendingId?: string): {
+        pendingId: string;
+    };
+    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined, pendingId?: string): {
+        pendingId: string;
+    };
+    /** A plain announcement (run started/finished, a scheduled task's
+     * result), with nothing to decide. */
+    postMessage(text: string): void;
+}