loopengine 0.1.59 → 0.1.60

package/dist/bin/ability-manager.d.ts

@@ -26,6 +26,17 @@ export interface AbilityEnvDecl {
      * env-admin.ts's own serializeEnvValue doc comment). Omit for anything
      * genuinely single-line. */
     multiline?: boolean;
+    /** True when this setting is meaningfully different per agent (e.g.
+     * which Slack channel to post to) rather than one real shared
+     * credential every installed copy should agree on (e.g. an API key
+     * for the one external service they all call). The Admin UI's
+     * Environment tab then also offers a per-agent override — a second,
+     * separate var named `<AGENT_NAME>_<this name>` (env-admin.ts's own
+     * agentScopedEnvVarName) — that an ability's own tool code can check
+     * first, falling back to this bare name when the override isn't set.
+     * Omit (the default, false) for anything that's actually fine shared
+     * across every agent that installs this ability. */
+    perAgent?: boolean;
 }
 /** `name`/`version` deliberately aren't declared here — they're read off
  * the ability's own sibling `package.json` instead (see readManifest),

package/dist/core/gateway-tools.d.ts

@@ -35,6 +35,25 @@ export type GatewayToolEntry = ComposioGatewayToolEntry;
  * module's own registry read/writes do, rather than re-deriving it (e.g.
  * from process.cwd()) and risking the two drifting apart. */
 export declare function agentDir(agentName: string): string;
+/** agentDir's own inverse, for a tool file that needs to know which
+ * agent it was installed under without an env var to tell it — an
+ * ability's own tool file (copied to agents/<name>/tools/<file>.ts by
+ * add-ability) calls this with its own `import.meta.url`, and gets
+ * `<name>` back, by walking back up from the file's real on-disk
+ * location rather than trusting anything passed in (there's nothing
+ * else to trust: this runs from inside the tool file itself, before
+ * any agent-scoped state exists). Returns undefined for a tool file
+ * that isn't actually at that expected agents/<name>/tools/ depth (a
+ * test harness loading the file from somewhere else, say) — a caller
+ * needing a default when this can't be determined should fall back
+ * explicitly, not treat undefined as a crash. Mirrors the inferAgentName
+ * helper lp-task-scheduler's own tool files (schedule_task.ts et al.)
+ * already hand-duplicate per the ability system's own "no shared
+ * modules between tool files" rule — this is the one place that's
+ * actually safe to centralize, since every ability's tool file already
+ * imports real functions from this package (see e.g. lp-task-scheduler's
+ * own createCheckpointStore/runAgent imports), just not yet this. */
+export declare function inferAgentNameFromToolUrl(toolFileUrl: string): string | undefined;
 /** `dir` is the agent's real folder — `agents/<name>` for a top-level
  * agent, or the nested `agents/<parent>/subagents/<child>` a subagent
  * actually lives in (see run-agent.ts's resolveSubagentConfig, which

package/dist/core/gateway-tools.js

@@ -8,7 +8,8 @@
 // the only intended writer of that file; loadGatewayToolsFromDir is what
 // run-agent.ts calls to actually resolve it into ToolDefinitions.
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { parse as parseYaml, parseDocument, stringify as stringifyYaml } from 'yaml';
@@ -34,6 +35,36 @@ function gatewayToolsPath(dir) {
 export function agentDir(agentName) {
     return join(agentsRootDir, agentName);
 }
+/** agentDir's own inverse, for a tool file that needs to know which
+ * agent it was installed under without an env var to tell it — an
+ * ability's own tool file (copied to agents/<name>/tools/<file>.ts by
+ * add-ability) calls this with its own `import.meta.url`, and gets
+ * `<name>` back, by walking back up from the file's real on-disk
+ * location rather than trusting anything passed in (there's nothing
+ * else to trust: this runs from inside the tool file itself, before
+ * any agent-scoped state exists). Returns undefined for a tool file
+ * that isn't actually at that expected agents/<name>/tools/ depth (a
+ * test harness loading the file from somewhere else, say) — a caller
+ * needing a default when this can't be determined should fall back
+ * explicitly, not treat undefined as a crash. Mirrors the inferAgentName
+ * helper lp-task-scheduler's own tool files (schedule_task.ts et al.)
+ * already hand-duplicate per the ability system's own "no shared
+ * modules between tool files" rule — this is the one place that's
+ * actually safe to centralize, since every ability's tool file already
+ * imports real functions from this package (see e.g. lp-task-scheduler's
+ * own createCheckpointStore/runAgent imports), just not yet this. */
+export function inferAgentNameFromToolUrl(toolFileUrl) {
+    try {
+        const toolsDir = dirname(fileURLToPath(toolFileUrl));
+        const agentDir = dirname(toolsDir);
+        if (basename(dirname(agentDir)) !== 'agents')
+            return undefined;
+        return basename(agentDir);
+    }
+    catch {
+        return undefined;
+    }
+}
 /** `dir` is the agent's real folder — `agents/<name>` for a top-level
  * agent, or the nested `agents/<parent>/subagents/<child>` a subagent
  * actually lives in (see run-agent.ts's resolveSubagentConfig, which

package/dist/core/system-skills/system-skills/composio-large-outputs/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: composio-large-outputs
+description: How to retrieve a gateway tool's real output when its result says storedInFile is true instead of returning the data inline.
+---
+
+# Gateway tools with a large result
+
+Some gateway tools (Composio-sourced ones in particular) return a small
+pointer object instead of their real output when the actual result is
+too large to return inline:
+
+```
+{
+  "successful": true,
+  "storedInFile": true,
+  "tokenCount": 10234,
+  "outputFilePath": "/tmp/.../SOME_TOOL_OUTPUT_xxxxx.json"
+}
+```
+
+When you see `storedInFile: true` in a tool result, the real data is
+**not** in that object — it's in the file at `outputFilePath`. Call
+`system_read_file` with that exact path to retrieve the actual content
+before answering. Don't guess at an answer, summarize from the pointer
+alone, or claim you don't have the data — read the file first.

package/dist/index.d.ts

@@ -36,7 +36,7 @@ export { LLMSummarizer } from './core/llm-summarizer.js';
 export type { LLMSummarizerOptions } from './core/llm-summarizer.js';
 export { createCheckpointStore } from './core/durable-approvals.js';
 export type { TurnCheckpoint, CheckpointStore, OutstandingItem } from './core/durable-approvals.js';
-export { addGatewayTool, agentDir, disconnectComposioAccount, describeGatewayTools, listComposioConnections, listComposioTools, loadGatewayToolsFromDir, removeGatewayTool, removeGatewayToolSlug, GatewayToolExistsError, GatewayToolNotFoundError, } from './core/gateway-tools.js';
+export { addGatewayTool, agentDir, inferAgentNameFromToolUrl, disconnectComposioAccount, describeGatewayTools, listComposioConnections, listComposioTools, loadGatewayToolsFromDir, removeGatewayTool, removeGatewayToolSlug, GatewayToolExistsError, GatewayToolNotFoundError, } from './core/gateway-tools.js';
 export type { GatewayToolEntry, GatewayToolDecision } from './core/gateway-tools.js';
 export { connectComposioSource } from './core/mcpplug.js';
 export type { ToolSource, ComposioSourceOptions } from './core/mcpplug.js';
@@ -55,7 +55,7 @@ export { globalConfigPageHtml } from './web/global-config-page.js';
 export { playgroundHtml } from './web/playground.js';
 export { readSkill, writeSkill, deleteSkill, SkillInvalidIdError, SkillNotFoundError } from './web/skills-admin.js';
 export type { SkillContent } from './web/skills-admin.js';
-export { listDeclaredEnvVars, setEnvVar, unsetEnvVar, EnvVarNameError } from './web/env-admin.js';
+export { listDeclaredEnvVars, setEnvVar, unsetEnvVar, agentScopedEnvVarName, EnvVarNameError } from './web/env-admin.js';
 export type { DeclaredEnvVar } from './web/env-admin.js';
 export { readActauthConfig, addActauthRule, updateActauthRule, removeActauthRule, setDefaultDecision, ActauthRuleExistsError, ActauthRuleNotFoundError, } from './web/actauth-admin.js';
 export type { ActauthRuleInput, ActauthConfigView } from './web/actauth-admin.js';

package/dist/index.js

@@ -35,7 +35,7 @@ export { resumeAgent, loadRules, loadDefaultTools, loadSubagentAsTools, systemTo
 export { Compactor, TruncatingSummarizer } from './core/compaction.js';
 export { LLMSummarizer } from './core/llm-summarizer.js';
 export { createCheckpointStore } from './core/durable-approvals.js';
-export { addGatewayTool, agentDir, disconnectComposioAccount, describeGatewayTools, listComposioConnections, listComposioTools, loadGatewayToolsFromDir, removeGatewayTool, removeGatewayToolSlug, GatewayToolExistsError, GatewayToolNotFoundError, } from './core/gateway-tools.js';
+export { addGatewayTool, agentDir, inferAgentNameFromToolUrl, disconnectComposioAccount, describeGatewayTools, listComposioConnections, listComposioTools, loadGatewayToolsFromDir, removeGatewayTool, removeGatewayToolSlug, GatewayToolExistsError, GatewayToolNotFoundError, } from './core/gateway-tools.js';
 export { connectComposioSource } from './core/mcpplug.js';
 export { ToolLane, buildLanes, runLanes } from './core/toollane.js';
 export { WebhookNotifier } from './core/http-notify-triggers/webhook.js';
@@ -50,7 +50,7 @@ export { agentsListPageHtml } from './web/agents-list-page.js';
 export { globalConfigPageHtml } from './web/global-config-page.js';
 export { playgroundHtml } from './web/playground.js';
 export { readSkill, writeSkill, deleteSkill, SkillInvalidIdError, SkillNotFoundError } from './web/skills-admin.js';
-export { listDeclaredEnvVars, setEnvVar, unsetEnvVar, EnvVarNameError } from './web/env-admin.js';
+export { listDeclaredEnvVars, setEnvVar, unsetEnvVar, agentScopedEnvVarName, EnvVarNameError } from './web/env-admin.js';
 export { readActauthConfig, addActauthRule, updateActauthRule, removeActauthRule, setDefaultDecision, ActauthRuleExistsError, ActauthRuleNotFoundError, } from './web/actauth-admin.js';
 export { installAbility, upgradeAbility, listInstalledAbilities, backfillDependencies, AbilityManifestError, AbilityVersionError, AbilityCollisionError, AbilityAlreadyInstalledError, AbilityNotInstalledError, } from './bin/ability-manager.js';
 export { searchPublicAbilities, fetchLatestAbilityVersion } from './web/abilities-admin.js';

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

@@ -48,6 +48,16 @@ export interface DeclaredEnvVar {
  * live off `process.env`, not cached, so it reflects whatever the last
  * `setEnvVar` call — or a plain restart picking up `.env` — actually
  * did. */
+/** `varName`'s own per-agent override name (see AbilityEnvDecl.perAgent)
+ * — `<AGENT_NAME>_<varName>`, with `agentName` upper-cased and anything
+ * that isn't `[A-Z0-9_]` (a hyphen, most likely — agent directory names
+ * are kebab-case) turned into `_`, same alphabet ENV_VAR_NAME_PATTERN
+ * already requires. Guards against a result starting with a digit (a
+ * from-digits agent name, or an agent name that's entirely punctuation)
+ * the same way that pattern would otherwise reject — by prefixing one
+ * more `_` — though in practice agent names are never actually bare
+ * digits. */
+export declare function agentScopedEnvVarName(agentName: string, varName: string): string;
 export declare function listDeclaredEnvVars(agentName: string): DeclaredEnvVar[];
 /** Upserts `NAME=VALUE` into the project's `.env` file — preserving
  * every other line (comments, blank lines, unrelated keys) — and

package/dist/web/env-admin.js

@@ -41,33 +41,61 @@ function provenancePath(agentName) {
  * live off `process.env`, not cached, so it reflects whatever the last
  * `setEnvVar` call — or a plain restart picking up `.env` — actually
  * did. */
+/** `varName`'s own per-agent override name (see AbilityEnvDecl.perAgent)
+ * — `<AGENT_NAME>_<varName>`, with `agentName` upper-cased and anything
+ * that isn't `[A-Z0-9_]` (a hyphen, most likely — agent directory names
+ * are kebab-case) turned into `_`, same alphabet ENV_VAR_NAME_PATTERN
+ * already requires. Guards against a result starting with a digit (a
+ * from-digits agent name, or an agent name that's entirely punctuation)
+ * the same way that pattern would otherwise reject — by prefixing one
+ * more `_` — though in practice agent names are never actually bare
+ * digits. */
+export function agentScopedEnvVarName(agentName, varName) {
+    const prefix = agentName.toUpperCase().replace(/[^A-Z0-9_]/g, '_');
+    return `${/^[0-9]/.test(prefix) ? '_' : ''}${prefix}_${varName}`;
+}
 export function listDeclaredEnvVars(agentName) {
     const path = provenancePath(agentName);
     if (!existsSync(path))
         return [];
     const provenance = JSON.parse(readFileSync(path, 'utf8'));
     const byName = new Map();
+    function upsert(name, abilityName, decl, description) {
+        const existing = byName.get(name);
+        if (existing) {
+            existing.abilityNames.push(abilityName);
+            existing.secret = existing.secret || decl.secret === true;
+            if (existing.secret)
+                existing.value = undefined;
+            return;
+        }
+        const rawValue = process.env[name];
+        byName.set(name, {
+            name,
+            description,
+            secret: decl.secret === true,
+            abilityNames: [abilityName],
+            set: rawValue !== undefined,
+            value: decl.secret === true ? undefined : rawValue,
+            options: decl.options,
+            multiline: decl.multiline,
+        });
+    }
     for (const [abilityName, record] of Object.entries(provenance)) {
         for (const decl of record.env) {
-            const existing = byName.get(decl.name);
-            if (existing) {
-                existing.abilityNames.push(abilityName);
-                existing.secret = existing.secret || decl.secret === true;
-                if (existing.secret)
-                    existing.value = undefined;
-                continue;
+            upsert(decl.name, abilityName, decl, decl.description);
+            // A perAgent var also gets its own separate, independently
+            // set/unset row for this one agent's override — see
+            // AbilityEnvDecl.perAgent's own doc comment for why this is a
+            // second row, not a replacement for the shared one above (an
+            // ability's own tool code checks the override first and falls
+            // back to the shared value, so both need to stay independently
+            // visible and settable here).
+            if (decl.perAgent) {
+                const scopedName = agentScopedEnvVarName(agentName, decl.name);
+                const overrideDescription = `Overrides ${decl.name} for this agent only — if unset, falls back to the shared value above.${decl.description ? ` ${decl.description}` : ''}`;
+                upsert(scopedName, abilityName, decl, overrideDescription);
             }
-            const rawValue = process.env[decl.name];
-            byName.set(decl.name, {
-                name: decl.name,
-                description: decl.description,
-                secret: decl.secret === true,
-                abilityNames: [abilityName],
-                set: rawValue !== undefined,
-                value: decl.secret === true ? undefined : rawValue,
-                options: decl.options,
-                multiline: decl.multiline,
-            });
         }
     }
     return [...byName.values()];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.59",
+  "version": "0.1.60",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",