loopengine 0.1.61 → 0.1.63

package/README.md

@@ -332,3 +332,20 @@ docker compose up --build
 Builds the HTTP adapter into a container and starts it alongside Redis.
 For production, push the image to any container platform with `REDIS_URL`
 and your model/tool API keys set as environment variables.
+
+### Hosting behind a platform
+
+These settings are for running LoopEngine inside a hosting platform
+(one workspace per user, behind a router that has already authenticated
+them). All are off by default; a self-hosted install that doesn't set
+them behaves exactly as described above.
+
+| Setting | What it does |
+| --- | --- |
+| `LOOPENGINE_TRUSTED_PROXY_SECRET` | Every request must carry an `X-LoopEngine-Identity` header signed with this secret (`signProxyIdentity` creates one; unsigned requests get 401). `LOOPENGINE_ADMIN_AUTH`, if also set, still works for direct access. Also enables `GET /internal/activity`: in-flight turns, open streams and idle time, so the host never stops a server mid-turn. |
+| `LOOPENGINE_EXIT_ON_CODE_CHANGE=1` | After an ability install, upgrade, uninstall or dependency install through the Admin UI, the server drains and exits so the platform restarts it with the new code loaded. Only set this when something restarts the process. |
+| `LOOPENGINE_USAGE_LOG` | `stdout` (one JSON line per model call) or a file path (JSON lines) — tokens per call with agent, tenant, session and model. Or call `setUsageSink()` in code. |
+| `setSecretStore()` | In code, at startup: keep env values set through the Admin UI somewhere other than `.env` files (a vault, a secret manager). The default `FileSecretStore` is today's behaviour. |
+
+`deploy/workspace/Dockerfile` is a runtime image for this: it serves a
+scaffolded project mounted at `/workspace` instead of baking agents in.

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,35 @@
+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 setAgentDir(config: AgentConfig, dir: string): void;
+export declare function agentDirFor(config: AgentConfig): string;
+/** Lookup order for `get(name)`:
+ * 1. `name` among this agent's own values (the secret store's
+ *    readAgentValues — `<dir>/.env` by default)
+ * 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,88 @@
+// 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 the
+// agent's own values (agents/<name>/.env by default — see
+// core/secret-store.ts) layered over the project's own.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentDir } from './gateway-tools.js';
+import { agentEnvFilePath, getSecretStore } from './secret-store.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}`;
+}
+/** 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` among this agent's own values (the secret store's
+ *    readAgentValues — `<dir>/.env` by default)
+ * 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 = getSecretStore().readAgentValues(agentName, 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/model-calls/anthropic-model-call.js

@@ -58,6 +58,7 @@ export function createAnthropicModelCall(options = {}) {
             }
             return { type: block.type };
         });
-        return { stop_reason: response.stop_reason ?? 'end_turn', content };
+        const usage = response.usage ? { input_tokens: response.usage.input_tokens, output_tokens: response.usage.output_tokens } : undefined;
+        return { stop_reason: response.stop_reason ?? 'end_turn', content, usage };
     };
 }

package/dist/core/model-calls/deepseek-model-call.js

@@ -48,6 +48,7 @@ export function createDeepSeekModelCall(options) {
                 }))
                 : undefined,
         });
-        return toModelResponse(response.choices[0]);
+        const usage = response.usage ? { input_tokens: response.usage.prompt_tokens, output_tokens: response.usage.completion_tokens } : undefined;
+        return { ...toModelResponse(response.choices[0]), usage };
     };
 }

package/dist/core/model-calls/gemini-model-call.js

@@ -48,6 +48,7 @@ export function createGeminiModelCall(options) {
                 }))
                 : undefined,
         });
-        return toModelResponse(response.choices[0]);
+        const usage = response.usage ? { input_tokens: response.usage.prompt_tokens, output_tokens: response.usage.completion_tokens } : undefined;
+        return { ...toModelResponse(response.choices[0]), usage };
     };
 }

package/dist/core/model-calls/glm-model-call.js

@@ -41,6 +41,7 @@ export function createGlmModelCall(options) {
                 }))
                 : undefined,
         });
-        return toModelResponse(response.choices[0]);
+        const usage = response.usage ? { input_tokens: response.usage.prompt_tokens, output_tokens: response.usage.completion_tokens } : undefined;
+        return { ...toModelResponse(response.choices[0]), usage };
     };
 }

package/dist/core/model-calls/kimi-model-call.js

@@ -54,6 +54,7 @@ export function createKimiModelCall(options) {
                 }))
                 : undefined,
         });
-        return toModelResponse(response.choices[0]);
+        const usage = response.usage ? { input_tokens: response.usage.prompt_tokens, output_tokens: response.usage.completion_tokens } : undefined;
+        return { ...toModelResponse(response.choices[0]), usage };
     };
 }

package/dist/core/model-calls/openai-model-call.js

@@ -122,6 +122,7 @@ export function createOpenAIModelCall(options) {
                 : undefined,
             reasoning_effort: options.reasoningEffort,
         });
-        return toModelResponse(response.choices[0]);
+        const usage = response.usage ? { input_tokens: response.usage.prompt_tokens, output_tokens: response.usage.completion_tokens } : undefined;
+        return { ...toModelResponse(response.choices[0]), usage };
     };
 }

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

@@ -44,6 +44,12 @@ export interface ModelContentBlock {
 export interface ModelResponse {
     stop_reason: string;
     content: ModelContentBlock[];
+    /** Tokens this call used, when the provider reports them — recorded
+     * per call by core/usage.ts if a usage sink is configured. */
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
 }
 /** loopengine's own conversation-message type — a superset of
  * budget.ts's own `{role, content: string}`: `content` can also be a

package/dist/core/run-agent.js

@@ -14,6 +14,8 @@ 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 { recordUsage } from './usage.js';
 import { loadAgentModule } from './discover-agents.js';
 import { agentAsTool } from './agent-as-tool.js';
 import { loadGatewayToolsFromDir } from './gateway-tools.js';
@@ -223,6 +225,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 +446,13 @@ async function buildTurnContext(config, modelCall, options) {
         askUserTool,
         questionHandler,
         httpNotifier,
+        modelLabel: { provider: config.model?.provider, model: config.model?.model },
+        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 +464,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, modelLabel } = ctx;
     function pushMessage(message) {
         messages.push(message);
         newMessages.push(message);
@@ -525,7 +535,23 @@ async function runLoop(ctx, messages, newMessages, starterMessage) {
         // and there's no second type yet to justify a second, more generic
         // event just to aggregate it (see PromptCompactionEvent's own doc
         // comment for the removed 'recovery:summary').
-        const { value: response } = await recovery.call((msgs) => modelCall(msgs, systemPrompt, toolSchemas), messages);
+        // Recorded inside the retried call, not after it, so a retry that
+        // spent tokens and then failed is still counted.
+        const { value: response } = await recovery.call(async (msgs) => {
+            const result = await modelCall(msgs, systemPrompt, toolSchemas);
+            if (result.usage) {
+                recordUsage({
+                    at: new Date().toISOString(),
+                    agent: toolContext.agentName,
+                    tenant: toolContext.tenant,
+                    sessionId: toolContext.sessionId,
+                    ...modelLabel,
+                    inputTokens: result.usage.input_tokens,
+                    outputTokens: result.usage.output_tokens,
+                });
+            }
+            return result;
+        }, messages);
         // The model's full response — text and tool_use blocks alike, with
         // real ids — becomes this turn's assistant message verbatim. Every
         // tool_use block emitted here gets a matching tool_result pushed
@@ -636,7 +662,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 +683,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/core/secret-store.d.ts

@@ -0,0 +1,32 @@
+export interface SecretStore {
+    /** Every value set for this one agent (its own, not the shared ones).
+     * Synchronous because ToolContext.env.get is — a store backed by a
+     * remote service should keep an in-memory copy and return that. */
+    readAgentValues(agentName: string, dir: string): Record<string, string>;
+    /** Persist a project-wide value. The caller (web/env-admin.ts) applies
+     * it to process.env afterwards, so a store doesn't need to. */
+    setShared(name: string, value: string): void | Promise<void>;
+    unsetShared(name: string): void | Promise<void>;
+    setAgent(agentName: string, dir: string, name: string, value: string): void | Promise<void>;
+    unsetAgent(agentName: string, dir: string, name: string): void | Promise<void>;
+}
+export declare function agentEnvFilePath(dir: string): string;
+/** Parsed with Node's own --env-file parser (util.parseEnv), so a value
+ * 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>;
+/** The project's .env for shared values, agents/<name>/.env for each
+ * agent's own — the default, and what every self-hosted install uses. */
+export declare class FileSecretStore implements SecretStore {
+    readAgentValues(_agentName: string, dir: string): Record<string, string>;
+    setShared(name: string, value: string): void;
+    unsetShared(name: string): void;
+    setAgent(_agentName: string, dir: string, name: string, value: string): void;
+    unsetAgent(_agentName: string, dir: string, name: string): void;
+}
+/** Replaces the store for this whole process — call once at startup,
+ * before the server handles requests. */
+export declare function setSecretStore(next: SecretStore): void;
+export declare function getSecretStore(): SecretStore;

package/dist/core/secret-store.js

@@ -0,0 +1,116 @@
+// Where env var values set through the Admin UI (web/env-admin.ts) are
+// persisted, and where an agent's own values (ToolContext.env — see
+// core/agent-env.ts) are read from. The default, FileSecretStore, is the
+// project's .env plus each agent's agents/<name>/.env — exactly what a
+// self-hosted install has always used. A host that keeps secrets
+// somewhere else (a hosted control plane's vault, Vault, a cloud secret
+// manager) swaps it in once at startup with setSecretStore().
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseEnv } from 'node:util';
+export function agentEnvFilePath(dir) {
+    return join(dir, '.env');
+}
+/** Parsed with Node's own --env-file parser (util.parseEnv), so a value
+ * 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'));
+}
+// 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
+// cwd too) — not core/agent-registry.ts's projectDir(), which resolves
+// relative to *that compiled file's own location* and would point at
+// node_modules/loopengine/dist/ in a real scaffolded project, not the
+// project's own root where .env actually lives.
+function projectEnvFilePath() {
+    return join(process.cwd(), '.env');
+}
+// Node's own --env-file parser (what bin/cli.ts's runTsx already passes
+// as --env-file-if-exists=.env) needs a value containing whitespace, '#',
+// or a quote character quoted, so it reads back as one value instead of
+// being reinterpreted as a comment or truncated at the first space.
+// Single-quoting wins over double — confirmed live against Node's actual
+// parser that a single-quoted value reads back fully literally, with no
+// backslash-escape processing inside it at all: a real embedded newline,
+// a literal double-quote, or a literal backslash (a JSON secret like
+// GOOGLE_APPLICATION_CREDENTIALS_JSON has all three at once) all survive
+// untouched. Double-quoting a value with an *escaped* embedded quote does
+// NOT round-trip — confirmed live that Node's parser has no support for
+// \" as an escaped literal quote inside a double-quoted value; it just
+// ends the value there instead (`X="a\"b"` reads back as only `a\`,
+// silently dropping `b"` entirely). The double-quote fallback below is
+// only reached when the value itself contains a literal single quote —
+// the one character single-quoting can't represent at all.
+function serializeEnvValue(value) {
+    if (!/[\s#"'\\]/.test(value) && value !== '')
+        return value;
+    if (!value.includes("'"))
+        return `'${value}'`;
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** 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}=`));
+    if (existingIndex === -1) {
+        // Drop a single trailing blank line (from the file's own final
+        // newline splitting into an empty last element) before appending,
+        // so this doesn't accumulate a growing gap of blank lines across
+        // repeated calls.
+        if (lines.length > 0 && lines[lines.length - 1] === '')
+            lines.pop();
+        lines.push(newLine);
+    }
+    else {
+        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'));
+}
+/** The project's .env for shared values, agents/<name>/.env for each
+ * agent's own — the default, and what every self-hosted install uses. */
+export class FileSecretStore {
+    readAgentValues(_agentName, dir) {
+        return readAgentEnvFile(dir);
+    }
+    setShared(name, value) {
+        upsertEnvFileLine(projectEnvFilePath(), name, value);
+    }
+    unsetShared(name) {
+        removeEnvFileLine(projectEnvFilePath(), name);
+    }
+    setAgent(_agentName, dir, name, value) {
+        upsertEnvFileLine(agentEnvFilePath(dir), name, value);
+    }
+    unsetAgent(_agentName, dir, name) {
+        removeEnvFileLine(agentEnvFilePath(dir), name);
+    }
+}
+let store = new FileSecretStore();
+/** Replaces the store for this whole process — call once at startup,
+ * before the server handles requests. */
+export function setSecretStore(next) {
+    store = next;
+}
+export function getSecretStore() {
+    return store;
+}

package/dist/core/trusted-proxy.d.ts

@@ -0,0 +1,15 @@
+export declare const TRUSTED_PROXY_IDENTITY_HEADER = "x-loopengine-identity";
+export interface ProxyIdentity {
+    /** The authenticated user (or `system` for the control plane itself). */
+    sub: string;
+    workspace?: string;
+    role: string;
+    /** Expiry, Unix seconds. */
+    exp: number;
+}
+/** What the proxy puts in X-LoopEngine-Identity — exported so a router
+ * (and tests) produce exactly the format verifyProxyIdentity accepts. */
+export declare function signProxyIdentity(identity: ProxyIdentity, secret: string): string;
+/** The identity, or undefined for a missing, malformed, wrongly-signed
+ * or expired header. */
+export declare function verifyProxyIdentity(header: string | string[] | undefined, secret: string, nowMs?: number): ProxyIdentity | undefined;

package/dist/core/trusted-proxy.js

@@ -0,0 +1,47 @@
+// Auth for a server that only ever receives requests through a trusted
+// proxy (a hosting router that has already authenticated the user) —
+// enabled by LOOPENGINE_TRUSTED_PROXY_SECRET, off otherwise. The proxy
+// sends who the caller is in an X-LoopEngine-Identity header, signed with
+// that shared secret, so this server can trust it without seeing the
+// user's own credentials.
+//
+// Header format: `<payload>.<signature>`, both base64url — payload is the
+// JSON identity, signature is HMAC-SHA256(secret, payload). `exp` (Unix
+// seconds) keeps a captured header from being replayed indefinitely.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+export const TRUSTED_PROXY_IDENTITY_HEADER = 'x-loopengine-identity';
+function sign(payload, secret) {
+    return createHmac('sha256', secret).update(payload).digest('base64url');
+}
+/** What the proxy puts in X-LoopEngine-Identity — exported so a router
+ * (and tests) produce exactly the format verifyProxyIdentity accepts. */
+export function signProxyIdentity(identity, secret) {
+    const payload = Buffer.from(JSON.stringify(identity)).toString('base64url');
+    return `${payload}.${sign(payload, secret)}`;
+}
+/** The identity, or undefined for a missing, malformed, wrongly-signed
+ * or expired header. */
+export function verifyProxyIdentity(header, secret, nowMs = Date.now()) {
+    if (typeof header !== 'string')
+        return undefined;
+    const dot = header.indexOf('.');
+    if (dot <= 0)
+        return undefined;
+    const payload = header.slice(0, dot);
+    const provided = Buffer.from(header.slice(dot + 1));
+    const expected = Buffer.from(sign(payload, secret));
+    if (provided.length !== expected.length || !timingSafeEqual(provided, expected))
+        return undefined;
+    let identity;
+    try {
+        identity = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof identity.sub !== 'string' || typeof identity.role !== 'string' || typeof identity.exp !== 'number')
+        return undefined;
+    if (identity.exp * 1000 <= nowMs)
+        return undefined;
+    return identity;
+}

package/dist/core/usage.d.ts

@@ -0,0 +1,18 @@
+export interface UsageEvent {
+    at: string;
+    agent: string;
+    tenant: string;
+    sessionId?: string;
+    /** From AgentConfig.model — absent for an agent with its own
+     * createModelCall. */
+    provider?: string;
+    model?: string;
+    inputTokens: number;
+    outputTokens: number;
+}
+export type UsageSink = (event: UsageEvent) => void;
+/** Replaces the sink for this whole process; undefined turns usage
+ * recording off. */
+export declare function setUsageSink(next: UsageSink | undefined): void;
+/** Never throws — a broken sink must not fail the agent's turn. */
+export declare function recordUsage(event: UsageEvent): void;

package/dist/core/usage.js

@@ -0,0 +1,32 @@
+// Token usage per model call — off unless a sink is configured, so a
+// self-hosted install that doesn't ask for it sees no change at all.
+// Configure with LOOPENGINE_USAGE_LOG (`stdout` for one JSON line per
+// call on stdout, or a file path to append JSON lines to), or in code
+// with setUsageSink() — a host billing for model usage, or anyone
+// wanting a per-agent token count.
+import { appendFileSync } from 'node:fs';
+function sinkFromEnv() {
+    const target = process.env.LOOPENGINE_USAGE_LOG;
+    if (!target)
+        return undefined;
+    if (target === 'stdout')
+        return (event) => console.log(JSON.stringify({ type: 'loopengine:usage', ...event }));
+    return (event) => appendFileSync(target, JSON.stringify(event) + '\n');
+}
+let sink = sinkFromEnv();
+/** Replaces the sink for this whole process; undefined turns usage
+ * recording off. */
+export function setUsageSink(next) {
+    sink = next;
+}
+/** Never throws — a broken sink must not fail the agent's turn. */
+export function recordUsage(event) {
+    if (!sink)
+        return;
+    try {
+        sink(event);
+    }
+    catch (err) {
+        console.error('[loopengine] usage sink failed:', err);
+    }
+}

package/dist/index.d.ts

@@ -2,7 +2,11 @@ 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 { FileSecretStore, setSecretStore, getSecretStore, type SecretStore } from '#core/secret-store.js';
+export { signProxyIdentity, verifyProxyIdentity, TRUSTED_PROXY_IDENTITY_HEADER, type ProxyIdentity } from '#core/trusted-proxy.js';
+export { setUsageSink, recordUsage, type UsageEvent, type UsageSink } from '#core/usage.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 +59,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,10 @@
 // "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';
+export { FileSecretStore, setSecretStore, getSecretStore } from '#core/secret-store.js';
+export { signProxyIdentity, verifyProxyIdentity, TRUSTED_PROXY_IDENTITY_HEADER } from '#core/trusted-proxy.js';
+export { setUsageSink, recordUsage } from '#core/usage.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 +54,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,37 +62,35 @@ 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. */
-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
- * value some vars would treat differently from "unset," e.g. falling
- * through to a default only when truly absent) and clears it from
- * *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. */
-export declare function unsetEnvVar(name: string): void;
+/** Persists a project-wide value through the secret store (the project's
+ * `.env` by default — see core/secret-store.ts) 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 the server has no auth configured — this function itself has no
+ * notion of HTTP auth, it just writes. */
+export declare function setEnvVar(name: string, value: string): Promise<void>;
+/** Removes a project-wide value entirely (not just blanking it — an
+ * empty string is itself a real, distinct value some vars would treat
+ * differently from "unset," e.g. falling through to a default only when
+ * truly absent) and clears it from *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 to begin with — the end state ("not set") is identical
+ * either way. */
+export declare function unsetEnvVar(name: string): Promise<void>;
+/** Persists `agentName`'s own value (agents/<name>/.env by default) —
+ * read by that agent's tools through ToolContext.env (core/agent-env.ts),
+ * which reads it 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): Promise<void>;
+/** Removes `agentName`'s own value — 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): Promise<void>;

package/dist/web/env-admin.js

@@ -6,9 +6,12 @@
 // `secret` is never echoed back once set — same never-echo-a-secret rule
 // web/http-tool-admin.ts's own `{{ENV_VAR}}` header handling already
 // establishes for a tool's own secrets.
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { agentDir } from '../core/gateway-tools.js';
+import { agentScopedEnvVarName, envScopeOf } from '../core/agent-env.js';
+import { getSecretStore } from '../core/secret-store.js';
+export { agentScopedEnvVarName };
 export class EnvVarNameError extends Error {
 }
 // Same shape web/http-tool-admin.ts's own ENV_VAR_PATTERN already
@@ -17,9 +20,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 +44,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 = getSecretStore().readAgentValues(agentName, 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,110 +101,72 @@ 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()];
-}
-// 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
-// cwd too) — not core/agent-registry.ts's projectDir(), which resolves
-// relative to *that compiled file's own location* and would point at
-// node_modules/loopengine/dist/ in a real scaffolded project, not the
-// project's own root where .env actually lives.
-function envFilePath() {
-    return join(process.cwd(), '.env');
-}
-// Node's own --env-file parser (what bin/cli.ts's runTsx already passes
-// as --env-file-if-exists=.env) needs a value containing whitespace, '#',
-// or a quote character quoted, so it reads back as one value instead of
-// being reinterpreted as a comment or truncated at the first space.
-// Single-quoting wins over double — confirmed live against Node's actual
-// parser that a single-quoted value reads back fully literally, with no
-// backslash-escape processing inside it at all: a real embedded newline,
-// a literal double-quote, or a literal backslash (a JSON secret like
-// GOOGLE_APPLICATION_CREDENTIALS_JSON has all three at once) all survive
-// untouched. Double-quoting a value with an *escaped* embedded quote does
-// NOT round-trip — confirmed live that Node's parser has no support for
-// \" as an escaped literal quote inside a double-quoted value; it just
-// ends the value there instead (`X="a\"b"` reads back as only `a\`,
-// silently dropping `b"` entirely). The double-quote fallback below is
-// only reached when the value itself contains a literal single quote —
-// the one character single-quoting can't represent at all.
-function serializeEnvValue(value) {
-    if (!/[\s#"'\\]/.test(value) && value !== '')
-        return value;
-    if (!value.includes("'"))
-        return `'${value}'`;
-    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+    // 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()];
 }
-/** 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();
-    const lines = existsSync(path) ? readFileSync(path, 'utf8').split('\n') : [];
-    const newLine = `${name}=${serializeEnvValue(value)}`;
-    const existingIndex = lines.findIndex((line) => line.startsWith(`${name}=`));
-    if (existingIndex === -1) {
-        // Drop a single trailing blank line (from the file's own final
-        // newline splitting into an empty last element) before appending,
-        // so this doesn't accumulate a growing gap of blank lines across
-        // repeated calls.
-        if (lines.length > 0 && lines[lines.length - 1] === '')
-            lines.pop();
-        lines.push(newLine);
-    }
-    else {
-        lines[existingIndex] = newLine;
-    }
-    writeFileSync(path, lines.join('\n') + '\n');
+}
+/** Persists a project-wide value through the secret store (the project's
+ * `.env` by default — see core/secret-store.ts) 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 the server has no auth configured — this function itself has no
+ * notion of HTTP auth, it just writes. */
+export async function setEnvVar(name, value) {
+    assertEnvVarName(name);
+    await getSecretStore().setShared(name, value);
     process.env[name] = value;
 }
-/** Removes NAME= entirely from the project's .env file (not just
- * blanking its value — an empty string is itself a real, distinct
- * value some vars would treat differently from "unset," e.g. falling
- * through to a default only when truly absent) and clears it from
- * *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. */
-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'));
-    }
+/** Removes a project-wide value entirely (not just blanking it — an
+ * empty string is itself a real, distinct value some vars would treat
+ * differently from "unset," e.g. falling through to a default only when
+ * truly absent) and clears it from *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 to begin with — the end state ("not set") is identical
+ * either way. */
+export async function unsetEnvVar(name) {
+    assertEnvVarName(name);
+    await getSecretStore().unsetShared(name);
     delete process.env[name];
 }
+/** Persists `agentName`'s own value (agents/<name>/.env by default) —
+ * read by that agent's tools through ToolContext.env (core/agent-env.ts),
+ * which reads it 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 async function setAgentEnvVar(agentName, name, value) {
+    assertEnvVarName(name);
+    await getSecretStore().setAgent(agentName, agentDir(agentName), name, value);
+}
+/** Removes `agentName`'s own value — 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 async function unsetAgentEnvVar(agentName, name) {
+    assertEnvVarName(name);
+    await getSecretStore().unsetAgent(agentName, agentDir(agentName), name);
+    await unsetEnvVar(agentScopedEnvVarName(agentName, name));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -36,6 +36,14 @@
     "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/secret-store.js",
+    "dist/core/secret-store.d.ts",
+    "dist/core/trusted-proxy.js",
+    "dist/core/trusted-proxy.d.ts",
+    "dist/core/usage.js",
+    "dist/core/usage.d.ts",
     "dist/core/session-store.js",
     "dist/core/session-store.d.ts",
     "dist/core/vector-index.js",

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

@@ -1,25 +0,0 @@
----
-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.