loopengine 0.1.62 → 0.1.64

package/README.md

@@ -108,17 +108,25 @@ working examples.
 
 ## Admin UI
 
-Run the HTTP adapter and open `http://localhost:8787/agents/config` — a
-live, editable view of every registered agent, no code changes or
-redeploy needed for most of it:
+Run the HTTP adapter and open `http://localhost:8787/agents` — one
+console for every registered agent: a sidebar of agents (with a badge
+when one still needs a setting), and for each agent a set of tabs. No
+code changes or redeploy needed for most of it:
 
 | Tab | What you can do |
 | --- | --- |
-| **Overview** | System prompt, model, every tool (with its JSON schema and parallel-safety), and a read-only view of the rules that would actually apply. |
+| **Chat** | Talk to the agent, approve or deny tool calls as they come up, and follow each step (model calls, tool calls, permission checks) in the Run trace. Past conversations are under History. |
+| **Overview** | A card per tab (tools, permissions, skills, settings), plus the system prompt, model, hooks and limits, each editable in place. |
+| **Tools** | Your hand-written tools, tools from integrations (e.g. [Composio](https://composio.dev)) and subagents, with whether each call runs on its own, asks first, or is denied. Build an HTTP tool or connect an integration without touching a file. |
 | **Skills** | Create, edit, and delete `SKILL.md` files for this agent directly in the browser — write the body, preview the rendered markdown, save. |
-| **Tools** | Local hand-written tools, gateway-sourced tools (e.g. [Composio](https://composio.dev)), and subagents-as-tools, in one place. Connect a new external gateway source or add/remove a tool without touching a file. |
-| **ActAuth** | Add, edit, and delete permission rules — scope, tool, condition, decision — and change `default_decision`, live. |
-| **Environment** | Every env var an ability (see [Ability system](#ability-system)) declared it needs, across everything installed for this agent — which ones are set, which are missing, and a form to set one. A value is never echoed back once set. |
+| **Abilities** | Install, upgrade, and uninstall abilities (see [Ability system](#ability-system)). |
+| **Permissions** | Add, edit, and delete permission rules (actauth) — who, tool, decision — and choose what happens when no rule matches. |
+| **Environment** | Every setting an installed ability reads, with its project-wide value and this agent's own value side by side, and which one the agent actually uses. A secret is never shown again once set. |
+
+Models and Integrations in the sidebar show which model providers have a
+key set and which outside tool sources are connected. Tabs deep-link:
+`/agents/config?agent=<name>&tab=tools`, `/playground?agent=<name>` for
+Chat.
 
 Every tab is backed by a real API (`GET /agents/:name/config`, `.../actauth`,
 `.../env`, ...) that reuses the exact same resolution `runAgent()` itself
@@ -264,10 +272,11 @@ content-negotiated on the `Accept` header, so nothing that already calls
 it as an API needs to change) to see every registered agent with links
 into the playground and config page below.
 
-**Dev playground:** open `http://localhost:8787/playground` (optionally
-`?agent=<name>` to preselect one) — pick an agent, chat with it, and watch
-that same loop-step event stream render live instead of reading raw SSE
-frames. Same `/messages/stream` route underneath.
+**Chat:** open `http://localhost:8787/playground` (optionally
+`?agent=<name>` to preselect one) — the console's Chat tab: talk to an
+agent and watch the loop-step event stream render live in the Run trace
+instead of reading raw SSE frames. Same `/messages/stream` route
+underneath.
 
 **Building your own client:** the playground is one UI on top of a typed
 event protocol, not the only way to consume a turn — see
@@ -332,3 +341,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