loopengine 0.1.62 → 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/core/agent-env.d.ts

@@ -22,17 +22,11 @@ export declare function envScopeOf(decl: {
  * 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`
+ * 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'`

package/dist/core/agent-env.js

@@ -3,12 +3,13 @@
 // 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.
+// 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 { parseEnv } from 'node:util';
 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. */
@@ -24,20 +25,6 @@ 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. */
@@ -69,7 +56,8 @@ 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`
+ * 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'`
@@ -77,7 +65,7 @@ export function agentDirFor(config) {
  * same order, so it can be overridden per agent too. */
 export function createAgentEnv(agentName, dir) {
     function get(name) {
-        const own = readAgentEnvFile(dir)[name];
+        const own = getSecretStore().readAgentValues(agentName, dir)[name];
         if (own !== undefined)
             return own;
         const legacy = process.env[agentScopedEnvVarName(agentName, name)];

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

@@ -15,6 +15,7 @@ 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';
@@ -445,6 +446,7 @@ 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,
@@ -462,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, toolContext } = 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);
@@ -533,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

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

@@ -4,6 +4,9 @@ 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, 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';

package/dist/index.js

@@ -6,6 +6,9 @@
 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

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

@@ -65,31 +65,32 @@ export interface DeclaredEnvVar {
  * 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 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 —
- * 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.
+/** 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): 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;
+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,10 +6,11 @@
 // `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 { agentEnvFilePath, agentScopedEnvVarName, envScopeOf, readAgentEnvFile } from '../core/agent-env.js';
+import { agentScopedEnvVarName, envScopeOf } from '../core/agent-env.js';
+import { getSecretStore } from '../core/secret-store.js';
 export { agentScopedEnvVarName };
 export class EnvVarNameError extends Error {
 }
@@ -50,7 +51,7 @@ export function listDeclaredEnvVars(agentName) {
     if (!existsSync(path))
         return [];
     const provenance = JSON.parse(readFileSync(path, 'utf8'));
-    const agentValues = readAgentEnvFile(agentDir(agentName));
+    const agentValues = getSecretStore().readAgentValues(agentName, agentDir(agentName));
     const rows = new Map();
     function upsert(slot, abilityName, decl, description) {
         const scope = envScopeOf(decl);
@@ -120,115 +121,52 @@ export function listDeclaredEnvVars(agentName) {
     }
     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
-// 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, '\\"')}"`;
-}
 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).`);
     }
 }
-/** 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'));
-}
-/** 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) {
+/** 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);
-    upsertEnvFileLine(envFilePath(), name, value);
+    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 —
- * the end state ("not set") is identical either way. */
-export function unsetEnvVar(name) {
+/** 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);
-    removeEnvFileLine(envFilePath(), name);
+    await getSecretStore().unsetShared(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.
+/** 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 function setAgentEnvVar(agentName, name, value) {
+export async function setAgentEnvVar(agentName, name, value) {
     assertEnvVarName(name);
-    upsertEnvFileLine(agentEnvFilePath(agentDir(agentName)), name, value);
+    await getSecretStore().setAgent(agentName, 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) {
+/** 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);
-    removeEnvFileLine(agentEnvFilePath(agentDir(agentName)), name);
-    unsetEnvVar(agentScopedEnvVarName(agentName, 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.62",
+  "version": "0.1.63",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -38,6 +38,12 @@
     "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.