loopengine 0.1.61 → 0.1.62

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

@@ -1,3 +1,4 @@
+import type { EnvScope } from '../core/agent-env.js';
 export declare class AbilityManifestError extends Error {
 }
 export declare class AbilityVersionError extends Error {
@@ -26,16 +27,21 @@ 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. */
+    /** How this var is shared across the agents that install this
+     * ability (see core/agent-env.ts's EnvScope), read by tools through
+     * ToolContext.env:
+     * - `shared` (default): one project-wide value — e.g. an API key for
+     *   the one external service every installed copy calls.
+     * - `overridable`: an agent may set its own value (agents/<name>/.env),
+     *   falling back to the shared one — e.g. which chat to post to.
+     * - `agent`: every agent must set its own; never falls back — e.g. a
+     *   bot token, where silently sharing one would make two agents speak
+     *   as the same bot.
+     * The Admin UI's Environment tab shows a shared row, a per-agent row,
+     * or both, to match. */
+    scope?: EnvScope;
+    /** @deprecated Use `scope: 'overridable'` — still accepted, and means
+     * exactly that when `scope` is unset. */
     perAgent?: boolean;
 }
 /** `name`/`version` deliberately aren't declared here — they're read off

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

@@ -289,8 +289,29 @@ export interface ToolSchema {
     /** JSON schema sent to the model so it knows how to call the tool. */
     input_schema: Record<string, unknown>;
 }
+/** An agent's view of its environment — see core/agent-env.ts's
+ * createAgentEnv for the exact lookup order (this agent's own
+ * agents/<name>/.env first, then the project-wide value, unless the
+ * declaring ability marked the var `scope: 'agent'`). */
+export interface AgentEnv {
+    get(name: string): string | undefined;
+    /** Same as `get`, but throws a clear "not set for agent X" error
+     * instead of returning undefined. */
+    require(name: string): string;
+}
+/** Passed as `execute`'s second argument on every call runAgent (and a
+ * durable approval's resume) makes — so a tool shared across several
+ * agents, typically one an ability installed, can tell which agent it's
+ * running for and read that agent's own settings via `env`, instead of
+ * working it out from its own file path or a prefixed env var name. */
+export interface ToolContext {
+    agentName: string;
+    tenant: string;
+    sessionId?: string;
+    env: AgentEnv;
+}
 export interface ToolDefinition extends ToolSchema {
-    execute: (input: Record<string, unknown>) => Promise<unknown>;
+    execute: (input: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
     /** Safe to run in ToolLane's parallel lane alongside other safe calls —
      * true for a read-only tool with no side effects and no shared mutable
      * state (a lookup, a search), false/omitted for anything that mutates

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

@@ -0,0 +1,41 @@
+import type { AgentConfig, AgentEnv } from '#core/agent-config.js';
+/** How a declared ability env var (AbilityEnvDecl.scope) is shared
+ * across the agents that install the ability:
+ * - `shared`: one project-wide value, from the project .env only.
+ * - `overridable`: an agent may set its own value; falls back to the
+ *   shared one when it doesn't.
+ * - `agent`: every agent must set its own; never falls back, so an agent
+ *   that hasn't set it gets a clear error instead of silently borrowing
+ *   another agent's value (e.g. a bot token, which decides *who* the
+ *   agent speaks as). */
+export type EnvScope = 'shared' | 'overridable' | 'agent';
+/** `perAgent: true` predates `scope` and means exactly `overridable` —
+ * still accepted so abilities published before `scope` existed keep
+ * working unchanged. */
+export declare function envScopeOf(decl: {
+    scope?: EnvScope;
+    perAgent?: boolean;
+}): EnvScope;
+/** The pre-`scope` per-agent override name — `<AGENT_NAME>_<varName>`,
+ * `agentName` upper-cased with anything outside `[A-Z0-9_]` turned into
+ * `_`, prefixed with one more `_` if that would start with a digit.
+ * Still read as a fallback by createAgentEnv (an agent's own .env wins
+ * over it) so a project already configured this way keeps working. */
+export declare function agentScopedEnvVarName(agentName: string, varName: string): string;
+export declare function agentEnvFilePath(dir: string): string;
+/** Parsed with Node's own --env-file parser (util.parseEnv), so a value
+ * web/env-admin.ts's serializeEnvValue writes reads back exactly the way
+ * it does from the project .env. Read fresh on every call, not cached —
+ * it's a few lines, read at most a handful of times per tool call, and
+ * this way an edit (from the Admin UI or by hand) is seen immediately. */
+export declare function readAgentEnvFile(dir: string): Record<string, string>;
+export declare function setAgentDir(config: AgentConfig, dir: string): void;
+export declare function agentDirFor(config: AgentConfig): string;
+/** Lookup order for `get(name)`:
+ * 1. `name` in this agent's own `<dir>/.env`
+ * 2. the legacy prefixed project var (agentScopedEnvVarName)
+ * 3. `process.env[name]` — skipped when an installed ability declared
+ *    `name` with `scope: 'agent'`
+ * An undeclared name (a hand-written tool's own var) goes through the
+ * same order, so it can be overridden per agent too. */
+export declare function createAgentEnv(agentName: string, dir: string): AgentEnv;

package/dist/core/agent-env.js

@@ -0,0 +1,100 @@
+// Per-agent environment for tools (ToolContext.env — see
+// core/agent-config.ts). One project shares a single .env/process.env,
+// but several agents can install the same ability and each need their
+// own value for some of its settings (a Telegram bot token, a default
+// chat ID). Rather than every ability's tool code deriving a prefixed
+// name (`<AGENT>_<VAR>`) itself, the runtime resolves it here, from an
+// agent-private agents/<name>/.env file layered over the project's own.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseEnv } from 'node:util';
+import { agentDir } from './gateway-tools.js';
+/** `perAgent: true` predates `scope` and means exactly `overridable` —
+ * still accepted so abilities published before `scope` existed keep
+ * working unchanged. */
+export function envScopeOf(decl) {
+    return decl.scope ?? (decl.perAgent ? 'overridable' : 'shared');
+}
+/** The pre-`scope` per-agent override name — `<AGENT_NAME>_<varName>`,
+ * `agentName` upper-cased with anything outside `[A-Z0-9_]` turned into
+ * `_`, prefixed with one more `_` if that would start with a digit.
+ * Still read as a fallback by createAgentEnv (an agent's own .env wins
+ * over it) so a project already configured this way keeps working. */
+export function agentScopedEnvVarName(agentName, varName) {
+    const prefix = agentName.toUpperCase().replace(/[^A-Z0-9_]/g, '_');
+    return `${/^[0-9]/.test(prefix) ? '_' : ''}${prefix}_${varName}`;
+}
+export function agentEnvFilePath(dir) {
+    return join(dir, '.env');
+}
+/** Parsed with Node's own --env-file parser (util.parseEnv), so a value
+ * web/env-admin.ts's serializeEnvValue writes reads back exactly the way
+ * it does from the project .env. Read fresh on every call, not cached —
+ * it's a few lines, read at most a handful of times per tool call, and
+ * this way an edit (from the Admin UI or by hand) is seen immediately. */
+export function readAgentEnvFile(dir) {
+    const path = agentEnvFilePath(dir);
+    if (!existsSync(path))
+        return {};
+    return parseEnv(readFileSync(path, 'utf8'));
+}
+/** Every env var name an ability installed in `dir` declared as
+ * `scope: 'agent'` — the ones createAgentEnv must never fall back to the
+ * project-wide value for. */
+function agentOnlyVarNames(dir) {
+    const path = join(dir, '.loopengine-abilities.json');
+    const names = new Set();
+    if (!existsSync(path))
+        return names;
+    const provenance = JSON.parse(readFileSync(path, 'utf8'));
+    for (const record of Object.values(provenance)) {
+        for (const decl of record.env ?? []) {
+            if (envScopeOf(decl) === 'agent')
+                names.add(decl.name);
+        }
+    }
+    return names;
+}
+// A subagent's config only carries its bare name, not the nested
+// agents/<parent>/subagents/<child>/ folder it was loaded from (see
+// run-agent.ts's resolveSubagentConfig) — that function records the
+// real folder here so its tools read *its* .env, not a same-named
+// top-level agent's. Keyed by object identity: agentAsTool hands the
+// exact same config object on to runAgent.
+const agentDirs = new WeakMap();
+export function setAgentDir(config, dir) {
+    agentDirs.set(config, dir);
+}
+export function agentDirFor(config) {
+    return agentDirs.get(config) ?? agentDir(config.name);
+}
+/** Lookup order for `get(name)`:
+ * 1. `name` in this agent's own `<dir>/.env`
+ * 2. the legacy prefixed project var (agentScopedEnvVarName)
+ * 3. `process.env[name]` — skipped when an installed ability declared
+ *    `name` with `scope: 'agent'`
+ * An undeclared name (a hand-written tool's own var) goes through the
+ * same order, so it can be overridden per agent too. */
+export function createAgentEnv(agentName, dir) {
+    function get(name) {
+        const own = readAgentEnvFile(dir)[name];
+        if (own !== undefined)
+            return own;
+        const legacy = process.env[agentScopedEnvVarName(agentName, name)];
+        if (legacy !== undefined)
+            return legacy;
+        if (agentOnlyVarNames(dir).has(name))
+            return undefined;
+        return process.env[name];
+    }
+    return {
+        get,
+        require(name) {
+            const value = get(name);
+            if (value === undefined) {
+                throw new Error(`${name} is not set for agent '${agentName}' — set it in the Admin UI's Environment tab, or in ${agentEnvFilePath(dir)}.`);
+            }
+            return value;
+        },
+    };
+}

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

@@ -35,7 +35,11 @@ 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
+/** @deprecated A tool can read `ctx.agentName` (ToolContext, passed as
+ * execute's second argument) instead — which, unlike this, is also
+ * right for a subagent's tools.
+ *
+ * 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

package/dist/core/gateway-tools.js

@@ -35,7 +35,11 @@ function gatewayToolsPath(dir) {
 export function agentDir(agentName) {
     return join(agentsRootDir, agentName);
 }
-/** agentDir's own inverse, for a tool file that needs to know which
+/** @deprecated A tool can read `ctx.agentName` (ToolContext, passed as
+ * execute's second argument) instead — which, unlike this, is also
+ * right for a subagent's tools.
+ *
+ * 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

package/dist/core/run-agent.js

@@ -14,6 +14,7 @@ import { Compactor } from './compaction.js';
 import { ToolLane } from './toollane.js';
 import { Recovery } from './recovery.js';
 import { collectKnownUrls, correctToolUseInput, recordKnownUrlsFromResult } from './known-urls.js';
+import { agentDirFor, createAgentEnv, setAgentDir } from './agent-env.js';
 import { loadAgentModule } from './discover-agents.js';
 import { agentAsTool } from './agent-as-tool.js';
 import { loadGatewayToolsFromDir } from './gateway-tools.js';
@@ -223,6 +224,7 @@ async function resolveSubagentConfig(config, dir) {
     if (resolved.skillsDirs === undefined) {
         resolved.skillsDirs = [join(dir, 'skills')];
     }
+    setAgentDir(resolved, dir);
     return resolved;
 }
 /** Auto-loads agents/<name>/subagents/<child>/index.{ts,js} — each one a
@@ -443,6 +445,12 @@ async function buildTurnContext(config, modelCall, options) {
         askUserTool,
         questionHandler,
         httpNotifier,
+        toolContext: {
+            agentName: config.name,
+            tenant: scope.tenant,
+            sessionId: options.sessionId,
+            env: createAgentEnv(config.name, agentDirFor(config)),
+        },
     };
 }
 /** The turn's actual ReAct loop — shared by runAgent (a fresh turn, its
@@ -454,7 +462,7 @@ async function buildTurnContext(config, modelCall, options) {
  * fresh in each case) but mutated here via pushMessage, same as the
  * single function this was split out of always did. */
 async function runLoop(ctx, messages, newMessages, starterMessage) {
-    const { modelCall, log, scope, sessionId, skillGarden, toolsByName, systemToolInstances, toolSchemas, systemPrompt, budgetTracker, compactor, gate, toolLane, maxTurns, tailMessages, askUserTool, questionHandler } = ctx;
+    const { modelCall, log, scope, sessionId, skillGarden, toolsByName, systemToolInstances, toolSchemas, systemPrompt, budgetTracker, compactor, gate, toolLane, maxTurns, tailMessages, askUserTool, questionHandler, toolContext } = ctx;
     function pushMessage(message) {
         messages.push(message);
         newMessages.push(message);
@@ -636,7 +644,7 @@ async function runLoop(ctx, messages, newMessages, starterMessage) {
                 approvedCalls.push({
                     id: block.id,
                     name: block.name,
-                    execute: () => toolsByName.get(block.name).execute(block.input ?? {}),
+                    execute: () => toolsByName.get(block.name).execute(block.input ?? {}, toolContext),
                 });
                 continue;
             }
@@ -657,7 +665,7 @@ async function runLoop(ctx, messages, newMessages, starterMessage) {
                 approvedCalls.push({
                     id: block.id,
                     name: block.name,
-                    execute: () => toolsByName.get(block.name).execute(block.input ?? {}),
+                    execute: () => toolsByName.get(block.name).execute(block.input ?? {}, toolContext),
                 });
             }
             else if (decision.decision === 'pending') {

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export { runAgent } from '#core/run-agent.js';
 export { storageSigners } from '#core/storage-signers/index.js';
 export type { SignRequest, StorageSigner } from '#core/storage-signers/types.js';
 export type { Message, ModelCall, ModelContentBlock, ModelResponse, RunAgentOptions, RunAgentResult, } from '#core/run-agent.js';
-export type { AgentConfig, AgentModelConfig, ToolSchema, ToolDefinition } from '#core/agent-config.js';
+export type { AgentConfig, AgentModelConfig, ToolSchema, ToolDefinition, ToolContext, AgentEnv } from '#core/agent-config.js';
+export { createAgentEnv, agentDirFor, envScopeOf, type EnvScope } from '#core/agent-env.js';
 export type * from './core/loop-events.js';
 export { streamMessage, streamMessageWithCallbacks, sendMessage, approveCall, denyCall, answerQuestion, getSessionHistory, } from './core/client.js';
 export type { RequestOptions, SendMessageResult, PendingApprovalResult, PendingQuestionResult, PendingResult, MessageResult, StreamMessageCallbacks, } from './core/client.js';
@@ -55,7 +56,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, agentScopedEnvVarName, EnvVarNameError } from './web/env-admin.js';
+export { listDeclaredEnvVars, setEnvVar, unsetEnvVar, setAgentEnvVar, unsetAgentEnvVar, 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

@@ -5,6 +5,7 @@
 // "Using loopengine as a library" for the boundary and why.
 export { runAgent } from '#core/run-agent.js';
 export { storageSigners } from '#core/storage-signers/index.js';
+export { createAgentEnv, agentDirFor, envScopeOf } from '#core/agent-env.js';
 // The framework-agnostic browser client for adapters/http.ts's own wire
 // protocol (see client.ts's own header comment) — this, not a deep
 // subpath import, is how a consumer's React/Vue/etc. chat UI is meant to
@@ -50,7 +51,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, agentScopedEnvVarName, EnvVarNameError } from './web/env-admin.js';
+export { listDeclaredEnvVars, setEnvVar, unsetEnvVar, setAgentEnvVar, unsetAgentEnvVar, agentScopedEnvVarName, EnvVarNameError } from './web/env-admin.js';
 export { readActauthConfig, addActauthRule, updateActauthRule, removeActauthRule, setDefaultDecision, ActauthRuleExistsError, ActauthRuleNotFoundError, } from './web/actauth-admin.js';
 export { installAbility, upgradeAbility, removeAbility, listInstalledAbilities, backfillDependencies, AbilityManifestError, AbilityVersionError, AbilityCollisionError, AbilityAlreadyInstalledError, AbilityNotInstalledError, } from './bin/ability-manager.js';
 export { searchPublicAbilities, fetchLatestAbilityVersion } from './web/abilities-admin.js';

package/dist/web/agents-config-page.js

@@ -1177,11 +1177,23 @@ export const agentsConfigPageHtml = `<!doctype html>
     // of a bare "set", since the whole point of looking here is usually
     // to check *what* something is currently configured to, not just
     // whether it has a value.
+    // An agent row (v.slot === 'agent' — this agent's own value, see
+    // env-admin.ts's DeclaredEnvVar.slot) for an overridable var isn't a
+    // problem when unset: it just falls back to the shared row. One for
+    // an agent-scoped var has no fallback, so unset really is missing.
     var statusHtml = !v.set
-      ? '<span class="error">not set</span>'
+      ? (v.slot === 'agent' && v.scope === 'overridable'
+          ? '<span class="hint">not set &mdash; uses shared value</span>'
+          : '<span class="error">not set</span>')
       : v.secret
         ? '<span class="hint">set</span>'
         : '<code>' + escapeHtml(v.value || '') + '</code>';
+    if (v.set && v.source === 'legacy') {
+      statusHtml += ' <span class="hint" title="Read from the older prefixed project variable. Saving a value here moves it into this agent&#39;s own .env.">(from ' + escapeHtml(v.legacyName || '') + ')</span>';
+    }
+    var slotNote = v.slot === 'agent'
+      ? ' <span class="hint">' + (v.scope === 'agent' ? 'this agent only' : 'this agent&#39;s override') + '</span>'
+      : (v.scope === 'overridable' ? ' <span class="hint">shared</span>' : '');
     // A var with a closed set of valid values (AbilityEnvDecl.options,
     // e.g. a provider switch) gets a <select> instead of a free-text
     // field, so there's nothing to mistype — the same "value" form field
@@ -1208,13 +1220,13 @@ export const agentsConfigPageHtml = `<!doctype html>
     // them, on a freshly installed ability — see renderEnvConfigHtml's
     // own comment on why "not set" isn't itself treated as a problem).
     var removeHtml = v.set
-      ? ' <button type="button" class="env-var-remove" data-name="' + escapeHtml(v.name) + '">Remove</button>'
+      ? ' <button type="button" class="env-var-remove" data-name="' + escapeHtml(v.name) + '" data-slot="' + escapeHtml(v.slot) + '">Remove</button>'
       : '';
     return '<tr>' +
-      '<td><code>' + escapeHtml(v.name) + '</code>' + sharedNote + '</td>' +
+      '<td><code>' + escapeHtml(v.name) + '</code>' + slotNote + sharedNote + '</td>' +
       '<td style="max-width:320px">' + escapeHtml(v.description || '') + '</td>' +
       '<td>' + statusHtml + '</td>' +
-      '<td><form class="add-source env-var-form" data-name="' + escapeHtml(v.name) + '">' +
+      '<td><form class="add-source env-var-form" data-name="' + escapeHtml(v.name) + '" data-slot="' + escapeHtml(v.slot) + '">' +
         fieldHtml +
         '<button type="submit">Save</button>' +
       '</form>' + removeHtml + '</td>' +
@@ -1280,10 +1292,11 @@ export const agentsConfigPageHtml = `<!doctype html>
         ev.preventDefault();
         var form = ev.currentTarget;
         var varName = form.getAttribute('data-name');
+        var slot = form.getAttribute('data-slot');
         var value = new FormData(form).get('value');
         var submitBtn = form.querySelector('button[type="submit"]');
         submitBtn.disabled = true;
-        fetch('/agents/' + encodeURIComponent(name) + '/env/' + encodeURIComponent(varName), {
+        fetch('/agents/' + encodeURIComponent(name) + '/env/' + encodeURIComponent(varName) + '?slot=' + encodeURIComponent(slot), {
           method: 'PUT',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ value: value }),
@@ -1304,13 +1317,15 @@ export const agentsConfigPageHtml = `<!doctype html>
       removeButtons[j].addEventListener('click', function (ev) {
         var btn = ev.currentTarget;
         var varName = btn.getAttribute('data-name');
+        var slot = btn.getAttribute('data-slot');
         // A destructive action (clearing a configured value, possibly a
         // secret nothing else has a copy of) gets the one confirm() this
         // whole tab uses — every other action here is a plain upsert,
         // nothing else to lose by clicking it again.
-        if (!confirm('Remove ' + varName + '? Any tool/ability relying on it falls back to its own default (if it has one) or starts failing until it is set again.')) return;
+        var what = slot === 'agent' ? 'the agent-specific value of ' + varName : varName;
+        if (!confirm('Remove ' + what + '? Any tool/ability relying on it falls back to its own default (if it has one) or starts failing until it is set again.')) return;
         btn.disabled = true;
-        fetch('/agents/' + encodeURIComponent(name) + '/env/' + encodeURIComponent(varName), { method: 'DELETE' })
+        fetch('/agents/' + encodeURIComponent(name) + '/env/' + encodeURIComponent(varName) + '?slot=' + encodeURIComponent(slot), { method: 'DELETE' })
           .then(function (r) { return r.json().then(function (j) { return { ok: r.ok, body: j }; }); })
           .then(function (result) {
             if (!result.ok) throw new Error(result.body.error || 'request failed');

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

@@ -1,8 +1,23 @@
+import { agentScopedEnvVarName, type EnvScope } from '../core/agent-env.js';
+export { agentScopedEnvVarName };
 export declare class EnvVarNameError extends Error {
 }
 export interface DeclaredEnvVar {
     name: string;
     description?: string;
+    /** Which value this row reads and writes: `shared` = the project
+     * .env, `agent` = this agent's own agents/<name>/.env. A var declared
+     * `overridable` gets one row of each; `agent` only the agent row. */
+    slot: 'shared' | 'agent';
+    /** The scope the declaring ability gave this var (see
+     * core/agent-env.ts's EnvScope) — the strictest one when more than
+     * one ability declares it. */
+    scope: EnvScope;
+    /** Agent rows only, when set: `agent` = from agents/<name>/.env,
+     * `legacy` = from the older prefixed project var named `legacyName`
+     * (see agentScopedEnvVarName), still honored until replaced. */
+    source?: 'agent' | 'legacy';
+    legacyName?: string;
     secret: boolean;
     /** Every ability that declares this name, in install order — usually
      * one, but see listDeclaredEnvVars's own doc comment for why this is
@@ -25,8 +40,10 @@ export interface DeclaredEnvVar {
     multiline?: boolean;
 }
 /** Every env var any ability installed for `agentName` declared it
- * needs, merged by name. There's one .env per *project*, not per agent
- * or per ability, so this can't actually resolve a genuine cross-ability
+ * needs, merged by name — one row per slot it can be set in (see
+ * DeclaredEnvVar.slot): a `shared` row for the project .env, an `agent`
+ * row for this agent's own .env when the var's scope allows one. There's
+ * one shared .env per *project*, not per ability, so this can't actually resolve a genuine cross-ability
  * name collision (two abilities declaring, say, "API_KEY" for two
  * unrelated services still both read whichever single value ends up
  * set — there is no per-ability slot to give them) — unlike a tool or
@@ -45,27 +62,15 @@ export interface DeclaredEnvVar {
  * safer default, since treating a real secret as non-secret because a
  * different ability's own declaration happened to be checked first
  * would be the one direction genuinely worth avoiding. `set` is read
- * 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;
+ * live (process.env for a shared row, the agent's own .env file for an
+ * agent row), not cached. */
 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
- * applies it to *this* running process immediately via `process.env`,
- * so a newly-installed ability's tools work without a restart. Callers
- * (the PUT route in adapters/http.ts) are responsible for refusing to
- * call this at all when `LOOPENGINE_ADMIN_AUTH` isn't set — this
- * function itself has no notion of HTTP auth, it just writes. */
+/** Upserts `NAME=VALUE` into the project's `.env` file and applies it to
+ * *this* running process immediately via `process.env`, so a
+ * newly-installed ability's tools work without a restart. Callers (the
+ * PUT route in adapters/http.ts) are responsible for refusing to call
+ * this at all when `LOOPENGINE_ADMIN_AUTH` isn't set — this function
+ * itself has no notion of HTTP auth, it just writes. */
 export declare function setEnvVar(name: string, value: string): void;
 /** Removes NAME= entirely from the project's .env file (not just
  * blanking its value — an empty string is itself a real, distinct
@@ -74,8 +79,17 @@ export declare function setEnvVar(name: string, value: string): void;
  * *this* running process's own process.env immediately, the same
  * "no restart needed" promise setEnvVar already makes. A no-op,
  * not an error, when the var was never set in .env to begin with —
- * same reasoning the DELETE route calling this treats a missing name
- * as success rather than a 404: the end state ("not set") is identical
- * either way, and the caller has no way to distinguish "I removed it"
- * from "it was already gone" that would actually matter to them. */
+ * the end state ("not set") is identical either way. */
 export declare function unsetEnvVar(name: string): void;
+/** Upserts `NAME=VALUE` into `agentName`'s own agents/<name>/.env — read
+ * by that agent's tools through ToolContext.env (core/agent-env.ts),
+ * which reads the file fresh on every lookup, so no restart is needed.
+ * Deliberately never copied into process.env: that's shared by every
+ * agent in the process, which is exactly what a per-agent value must
+ * not be. Same auth responsibility for callers as setEnvVar. */
+export declare function setAgentEnvVar(agentName: string, name: string, value: string): void;
+/** Removes NAME= from `agentName`'s own .env — and the legacy prefixed
+ * project var for it too (see agentScopedEnvVarName), since createAgentEnv
+ * still falls back to that one, and "Remove" on this agent's row should
+ * leave the agent with no value of its own either way. */
+export declare function unsetAgentEnvVar(agentName: string, name: string): void;

package/dist/web/env-admin.js

@@ -9,6 +9,8 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { agentDir } from '../core/gateway-tools.js';
+import { agentEnvFilePath, agentScopedEnvVarName, envScopeOf, readAgentEnvFile } from '../core/agent-env.js';
+export { agentScopedEnvVarName };
 export class EnvVarNameError extends Error {
 }
 // Same shape web/http-tool-admin.ts's own ENV_VAR_PATTERN already
@@ -17,9 +19,12 @@ const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 function provenancePath(agentName) {
     return join(agentDir(agentName), '.loopengine-abilities.json');
 }
+const SCOPE_STRICTNESS = { shared: 0, overridable: 1, agent: 2 };
 /** Every env var any ability installed for `agentName` declared it
- * needs, merged by name. There's one .env per *project*, not per agent
- * or per ability, so this can't actually resolve a genuine cross-ability
+ * needs, merged by name — one row per slot it can be set in (see
+ * DeclaredEnvVar.slot): a `shared` row for the project .env, an `agent`
+ * row for this agent's own .env when the var's scope allows one. There's
+ * one shared .env per *project*, not per ability, so this can't actually resolve a genuine cross-ability
  * name collision (two abilities declaring, say, "API_KEY" for two
  * unrelated services still both read whichever single value ends up
  * set — there is no per-ability slot to give them) — unlike a tool or
@@ -38,41 +43,53 @@ function provenancePath(agentName) {
  * safer default, since treating a real secret as non-secret because a
  * different ability's own declaration happened to be checked first
  * would be the one direction genuinely worth avoiding. `set` is read
- * 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}`;
-}
+ * live (process.env for a shared row, the agent's own .env file for an
+ * agent row), not cached. */
 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);
+    const agentValues = readAgentEnvFile(agentDir(agentName));
+    const rows = new Map();
+    function upsert(slot, abilityName, decl, description) {
+        const scope = envScopeOf(decl);
+        const key = `${slot}:${decl.name}`;
+        const existing = rows.get(key);
         if (existing) {
             existing.abilityNames.push(abilityName);
             existing.secret = existing.secret || decl.secret === true;
             if (existing.secret)
                 existing.value = undefined;
+            if (SCOPE_STRICTNESS[scope] > SCOPE_STRICTNESS[existing.scope])
+                existing.scope = scope;
             return;
         }
-        const rawValue = process.env[name];
-        byName.set(name, {
-            name,
+        let rawValue;
+        let source;
+        let legacyName;
+        if (slot === 'shared') {
+            rawValue = process.env[decl.name];
+        }
+        else if (agentValues[decl.name] !== undefined) {
+            rawValue = agentValues[decl.name];
+            source = 'agent';
+        }
+        else {
+            const legacy = agentScopedEnvVarName(agentName, decl.name);
+            rawValue = process.env[legacy];
+            if (rawValue !== undefined) {
+                source = 'legacy';
+                legacyName = legacy;
+            }
+        }
+        rows.set(key, {
+            name: decl.name,
             description,
+            slot,
+            scope,
+            source,
+            legacyName,
             secret: decl.secret === true,
             abilityNames: [abilityName],
             set: rawValue !== undefined,
@@ -83,22 +100,25 @@ export function listDeclaredEnvVars(agentName) {
     }
     for (const [abilityName, record] of Object.entries(provenance)) {
         for (const decl of record.env) {
-            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 scope = envScopeOf(decl);
+            if (scope !== 'agent')
+                upsert('shared', abilityName, decl, decl.description);
+            if (scope === 'overridable') {
+                upsert('agent', abilityName, decl, `This agent's own value — if unset, falls back to the shared value.${decl.description ? ` ${decl.description}` : ''}`);
+            }
+            else if (scope === 'agent') {
+                upsert('agent', abilityName, decl, `Set per agent — never shared with or borrowed from other agents.${decl.description ? ` ${decl.description}` : ''}`);
             }
         }
     }
-    return [...byName.values()];
+    // A name that's `agent`-scoped by any declaring ability is never read
+    // from the shared slot (core/agent-env.ts's createAgentEnv), so a
+    // shared row for it would only mislead.
+    for (const [key, row] of rows) {
+        if (row.slot === 'shared' && rows.get(`agent:${row.name}`)?.scope === 'agent')
+            rows.delete(key);
+    }
+    return [...rows.values()];
 }
 // process.cwd(), matching exactly where bin/cli.ts's own runTsx passes
 // --env-file-if-exists=.env (Node's own --env-file resolves relative to
@@ -132,18 +152,14 @@ function serializeEnvValue(value) {
         return `'${value}'`;
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
-/** Upserts `NAME=VALUE` into the project's `.env` file — preserving
- * every other line (comments, blank lines, unrelated keys) — and
- * applies it to *this* running process immediately via `process.env`,
- * so a newly-installed ability's tools work without a restart. Callers
- * (the PUT route in adapters/http.ts) are responsible for refusing to
- * call this at all when `LOOPENGINE_ADMIN_AUTH` isn't set — this
- * function itself has no notion of HTTP auth, it just writes. */
-export function setEnvVar(name, value) {
+function assertEnvVarName(name) {
     if (!ENV_VAR_NAME_PATTERN.test(name)) {
         throw new EnvVarNameError(`"${name}" isn't a valid env var name (uppercase letters, digits, underscore, not starting with a digit).`);
     }
-    const path = envFilePath();
+}
+/** Upserts `NAME=VALUE` into the .env file at `path`, preserving every
+ * other line (comments, blank lines, unrelated keys). */
+function upsertEnvFileLine(path, name, value) {
     const lines = existsSync(path) ? readFileSync(path, 'utf8').split('\n') : [];
     const newLine = `${name}=${serializeEnvValue(value)}`;
     const existingIndex = lines.findIndex((line) => line.startsWith(`${name}=`));
@@ -160,6 +176,28 @@ export function setEnvVar(name, value) {
         lines[existingIndex] = newLine;
     }
     writeFileSync(path, lines.join('\n') + '\n');
+}
+/** Removes NAME= from the .env file at `path`, if present. Only
+ * rewrites the file when something actually changed — a no-op removal
+ * shouldn't still touch the file's own mtime/trailing-newline shape for
+ * no reason. */
+function removeEnvFileLine(path, name) {
+    if (!existsSync(path))
+        return;
+    const lines = readFileSync(path, 'utf8').split('\n');
+    const filtered = lines.filter((line) => !line.startsWith(`${name}=`));
+    if (filtered.length !== lines.length)
+        writeFileSync(path, filtered.join('\n').replace(/\n*$/, '\n'));
+}
+/** Upserts `NAME=VALUE` into the project's `.env` file and applies it to
+ * *this* running process immediately via `process.env`, so a
+ * newly-installed ability's tools work without a restart. Callers (the
+ * PUT route in adapters/http.ts) are responsible for refusing to call
+ * this at all when `LOOPENGINE_ADMIN_AUTH` isn't set — this function
+ * itself has no notion of HTTP auth, it just writes. */
+export function setEnvVar(name, value) {
+    assertEnvVarName(name);
+    upsertEnvFileLine(envFilePath(), name, value);
     process.env[name] = value;
 }
 /** Removes NAME= entirely from the project's .env file (not just
@@ -169,24 +207,28 @@ export function setEnvVar(name, value) {
  * *this* running process's own process.env immediately, the same
  * "no restart needed" promise setEnvVar already makes. A no-op,
  * not an error, when the var was never set in .env to begin with —
- * same reasoning the DELETE route calling this treats a missing name
- * as success rather than a 404: the end state ("not set") is identical
- * either way, and the caller has no way to distinguish "I removed it"
- * from "it was already gone" that would actually matter to them. */
+ * the end state ("not set") is identical either way. */
 export function unsetEnvVar(name) {
-    if (!ENV_VAR_NAME_PATTERN.test(name)) {
-        throw new EnvVarNameError(`"${name}" isn't a valid env var name (uppercase letters, digits, underscore, not starting with a digit).`);
-    }
-    const path = envFilePath();
-    if (existsSync(path)) {
-        const lines = readFileSync(path, 'utf8').split('\n');
-        const filtered = lines.filter((line) => !line.startsWith(`${name}=`));
-        // Only rewrites the file when something actually changed — a
-        // no-op removal shouldn't still touch the file's own mtime/trailing-
-        // newline shape for no reason. Matches setEnvVar's own exactly-one-
-        // trailing-newline convention when it does.
-        if (filtered.length !== lines.length)
-            writeFileSync(path, filtered.join('\n').replace(/\n*$/, '\n'));
-    }
+    assertEnvVarName(name);
+    removeEnvFileLine(envFilePath(), name);
     delete process.env[name];
 }
+/** Upserts `NAME=VALUE` into `agentName`'s own agents/<name>/.env — read
+ * by that agent's tools through ToolContext.env (core/agent-env.ts),
+ * which reads the file fresh on every lookup, so no restart is needed.
+ * Deliberately never copied into process.env: that's shared by every
+ * agent in the process, which is exactly what a per-agent value must
+ * not be. Same auth responsibility for callers as setEnvVar. */
+export function setAgentEnvVar(agentName, name, value) {
+    assertEnvVarName(name);
+    upsertEnvFileLine(agentEnvFilePath(agentDir(agentName)), name, value);
+}
+/** Removes NAME= from `agentName`'s own .env — and the legacy prefixed
+ * project var for it too (see agentScopedEnvVarName), since createAgentEnv
+ * still falls back to that one, and "Remove" on this agent's row should
+ * leave the agent with no value of its own either way. */
+export function unsetAgentEnvVar(agentName, name) {
+    assertEnvVarName(name);
+    removeEnvFileLine(agentEnvFilePath(agentDir(agentName)), name);
+    unsetEnvVar(agentScopedEnvVarName(agentName, name));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.61",
+  "version": "0.1.62",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -36,6 +36,8 @@
     "dist/core/client.d.ts",
     "dist/core/agent-config.js",
     "dist/core/agent-config.d.ts",
+    "dist/core/agent-env.js",
+    "dist/core/agent-env.d.ts",
     "dist/core/session-store.js",
     "dist/core/session-store.d.ts",
     "dist/core/vector-index.js",