loopengine 0.1.2 → 0.1.4

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

@@ -295,11 +295,15 @@ export interface AgentConfig {
      * Omit entirely and it defaults to importing
      * `agents/<name>/tools/index.{ts,js}` and using its exported `tools` —
      * this repo's own aggregation-file convention (see
-     * `agents/customer-service/tools/index.ts`), resolved next to
-     * `run-agent.ts` itself (not `process.cwd()`, unlike `skillsDirs`/
-     * `rules` — that file is real compiled code, not data, so it has to be
-     * found next to whichever build of `run-agent.ts` is actually running).
-     * A missing file there is just `[]`, not an error — same
+     * `agents/customer-service/tools/index.ts`). Tried first next to
+     * `run-agent.ts` itself, since that file is real compiled code, not
+     * data — right when `agents/` is built alongside `core/` into the same
+     * `dist/` tree (this repo's own reference agents); falls back to
+     * `process.cwd()`, same as `skillsDirs`/`rules`, when nothing's built
+     * there — right for a project that only depends on the published
+     * package, whose own `agents/<name>/tools/` was never compiled into
+     * `node_modules/loopengine` at all.
+     * A missing file either place is just `[]`, not an error — same
      * missing-is-fine treatment `skillsDirs` gets. An agent that needs to
      * merge in tools from somewhere else too (e.g.
      * `agents/file-agent/index.ts`'s Composio-sourced ones) can't rely on

package/dist/core/durable-approvals.d.ts

@@ -0,0 +1,106 @@
+import { Redis } from 'ioredis';
+import type { ModelContentBlock } from './run-agent.js';
+export interface OutstandingItem {
+    /** Which kind of durable decision this is — 'approval' (a gated tool
+     * call) or 'question' (a system_ask_user call), see
+     * HUMAN_IN_THE_LOOP.md's "Durable questions" section. Optional, not
+     * required: this store is deliberately agnostic to what it's storing
+     * (see this module's own header comment) — undefined means 'approval',
+     * preserving every checkpoint written before 'question' existed.
+     * adapters/http.ts's two resolve routes are the only things that ever
+     * read this. */
+    kind?: 'approval' | 'question';
+    toolUseId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    reason: string;
+}
+export interface TurnCheckpoint {
+    id: string;
+    sessionId: string;
+    agent: string;
+    tenant: string;
+    /** tool_result blocks already computed — either safely auto-allowed
+     * calls from the same batch that ran immediately (see run-agent.ts's
+     * bucket-then-execute), or outstanding items resolved since this
+     * checkpoint was created. Complete and ready to push as the turn's
+     * completing message the instant `outstanding` is empty. */
+    resultsSoFar: ModelContentBlock[];
+    /** Keyed by pendingId, not toolUseId — a pendingId is what an incoming
+     * resolution actually names (a webhook callback, a magic-link visit),
+     * and is what DurableApprover.requestDurableApproval handed out. */
+    outstanding: Record<string, OutstandingItem>;
+    closed: boolean;
+}
+export interface CreateCheckpointInput {
+    sessionId: string;
+    agent: string;
+    tenant: string;
+    resultsSoFar: ModelContentBlock[];
+    outstanding: Record<string, OutstandingItem>;
+}
+export interface CheckpointStore {
+    create(input: CreateCheckpointInput): Promise<TurnCheckpoint>;
+    /** Loads the checkpoint `pendingId` belongs to, runs `fn` exclusively
+     * for that checkpoint (serializes concurrent resolutions of different
+     * outstanding items in the same checkpoint — see HUMAN_IN_THE_LOOP.md's
+     * own "denial closes the checkpoint immediately" race), and persists
+     * whatever checkpoint `fn` returns (or deletes it, once closed —
+     * nothing revisits a closed checkpoint again).
+     *
+     * `fn` receives `undefined` for an unknown pendingId, or one whose
+     * checkpoint is already closed — the graceful no-op case (a sibling
+     * denial, or an earlier resolve of the very same pendingId, got there
+     * first). `fn` itself decides what "closed" means (every outstanding
+     * item resolved, or a denial that closes early and skips the rest) —
+     * this store only persists the result, it never decides it. */
+    withCheckpoint<T>(pendingId: string, fn: (checkpoint: TurnCheckpoint | undefined) => Promise<{
+        checkpoint: TurnCheckpoint | undefined;
+        result: T;
+    }>): Promise<T>;
+    close(): Promise<void>;
+}
+/** One JSON file per checkpoint under `<dir>/checkpoints/`, plus one
+ * small pendingId -> checkpointId pointer file per outstanding item under
+ * `<dir>/pending-index/`. Fine for a single local process; not safe
+ * across multiple processes/instances — those need RedisCheckpointStore. */
+export declare class FileCheckpointStore implements CheckpointStore {
+    private readonly checkpointsDir;
+    private readonly indexDir;
+    constructor(dir: string);
+    private checkpointPath;
+    private indexPath;
+    create(input: CreateCheckpointInput): Promise<TurnCheckpoint>;
+    withCheckpoint<T>(pendingId: string, fn: (checkpoint: TurnCheckpoint | undefined) => Promise<{
+        checkpoint: TurnCheckpoint | undefined;
+        result: T;
+    }>): Promise<T>;
+    close(): Promise<void>;
+}
+/** Redis-backed store for multi-instance deployments. Unlike
+ * RedisSessionStore's lock (held for an entire turn, including however
+ * long a live human takes), this one only ever needs to be held for a
+ * quick read-modify-write — durable resolution never blocks on a human
+ * while holding it — so a short SET NX PX lock with retry, no renewal
+ * loop, is enough. */
+export declare class RedisCheckpointStore implements CheckpointStore {
+    private readonly redis;
+    private readonly lockTtlMs;
+    private readonly lockRetryDelayMs;
+    private readonly lockMaxWaitMs;
+    constructor(redisUrl: string, client?: Redis);
+    private checkpointKey;
+    private indexKey;
+    private lockKey;
+    private withLock;
+    create(input: CreateCheckpointInput): Promise<TurnCheckpoint>;
+    withCheckpoint<T>(pendingId: string, fn: (checkpoint: TurnCheckpoint | undefined) => Promise<{
+        checkpoint: TurnCheckpoint | undefined;
+        result: T;
+    }>): Promise<T>;
+    close(): Promise<void>;
+}
+/** Same REDIS_URL-gated pattern as session-store.ts's own
+ * createSessionStore(): set -> RedisCheckpointStore, otherwise
+ * FileCheckpointStore under .checkpoints. */
+export declare function createCheckpointStore(): CheckpointStore;

package/dist/core/durable-approvals.js

@@ -0,0 +1,158 @@
+// Durable storage for a turn paused on one or more DurableApprover
+// decisions — see HUMAN_IN_THE_LOOP.md for the full design. Mirrors
+// session-store.ts's own shape deliberately: a small "load, run
+// exclusively, persist" contract (withCheckpoint, here, plays the same
+// role withSession does there), a file-backed store for local dev and a
+// Redis-backed one for multi-instance deployments, and a
+// REDIS_URL-gated factory. This module does no tool execution and knows
+// nothing about ActAuth or the model loop — it only stores and locks;
+// run-agent.ts/adapters/http.ts own deciding what a resolution actually
+// does (see HUMAN_IN_THE_LOOP.md's own "request + raw resolve only"
+// division of labor).
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { Redis } from 'ioredis';
+import { KeyedMutex } from './session-store.js';
+const fileMutex = new KeyedMutex();
+/** One JSON file per checkpoint under `<dir>/checkpoints/`, plus one
+ * small pendingId -> checkpointId pointer file per outstanding item under
+ * `<dir>/pending-index/`. Fine for a single local process; not safe
+ * across multiple processes/instances — those need RedisCheckpointStore. */
+export class FileCheckpointStore {
+    checkpointsDir;
+    indexDir;
+    constructor(dir) {
+        this.checkpointsDir = path.join(dir, 'checkpoints');
+        this.indexDir = path.join(dir, 'pending-index');
+        mkdirSync(this.checkpointsDir, { recursive: true });
+        mkdirSync(this.indexDir, { recursive: true });
+    }
+    checkpointPath(id) {
+        return path.join(this.checkpointsDir, `${id}.json`);
+    }
+    indexPath(pendingId) {
+        return path.join(this.indexDir, pendingId);
+    }
+    async create(input) {
+        const checkpoint = { id: randomUUID(), closed: false, ...input };
+        writeFileSync(this.checkpointPath(checkpoint.id), JSON.stringify(checkpoint));
+        for (const pendingId of Object.keys(checkpoint.outstanding)) {
+            writeFileSync(this.indexPath(pendingId), checkpoint.id);
+        }
+        return checkpoint;
+    }
+    async withCheckpoint(pendingId, fn) {
+        const indexPath = this.indexPath(pendingId);
+        if (!existsSync(indexPath))
+            return (await fn(undefined)).result;
+        const checkpointId = readFileSync(indexPath, 'utf8');
+        return fileMutex.run(checkpointId, async () => {
+            const checkpointPath = this.checkpointPath(checkpointId);
+            // A concurrent resolution of a sibling pendingId in the same
+            // checkpoint may have already closed (and removed) it while this
+            // call was queued behind the mutex above.
+            const current = existsSync(checkpointPath)
+                ? JSON.parse(readFileSync(checkpointPath, 'utf8'))
+                : undefined;
+            const { checkpoint, result } = await fn(current && !current.closed ? current : undefined);
+            if (checkpoint) {
+                if (checkpoint.closed) {
+                    rmSync(checkpointPath, { force: true });
+                    for (const id of [...Object.keys(current?.outstanding ?? {})])
+                        rmSync(this.indexPath(id), { force: true });
+                }
+                else {
+                    writeFileSync(checkpointPath, JSON.stringify(checkpoint));
+                }
+            }
+            return result;
+        });
+    }
+    async close() { }
+}
+/** Redis-backed store for multi-instance deployments. Unlike
+ * RedisSessionStore's lock (held for an entire turn, including however
+ * long a live human takes), this one only ever needs to be held for a
+ * quick read-modify-write — durable resolution never blocks on a human
+ * while holding it — so a short SET NX PX lock with retry, no renewal
+ * loop, is enough. */
+export class RedisCheckpointStore {
+    redis;
+    lockTtlMs = 5_000;
+    lockRetryDelayMs = 50;
+    lockMaxWaitMs = 10_000;
+    constructor(redisUrl, client) {
+        this.redis = client ?? new Redis(redisUrl);
+    }
+    checkpointKey(id) {
+        return `checkpoint:${id}`;
+    }
+    indexKey(pendingId) {
+        return `checkpoint-pending-index:${pendingId}`;
+    }
+    lockKey(checkpointId) {
+        return `checkpoint-lock:${checkpointId}`;
+    }
+    async withLock(checkpointId, fn) {
+        const token = randomUUID();
+        const key = this.lockKey(checkpointId);
+        const deadline = Date.now() + this.lockMaxWaitMs;
+        for (;;) {
+            const ok = await this.redis.set(key, token, 'PX', this.lockTtlMs, 'NX');
+            if (ok)
+                break;
+            if (Date.now() > deadline)
+                throw new Error(`timed out waiting for lock on checkpoint '${checkpointId}'`);
+            await new Promise((resolve) => setTimeout(resolve, this.lockRetryDelayMs));
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            // Compare-and-delete, same script shape session-store.ts's own
+            // UNLOCK_IF_OWNER_SCRIPT uses — don't release a lock a slower
+            // caller's TTL expiry already handed to someone else.
+            await this.redis.eval(`if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end`, 1, key, token);
+        }
+    }
+    async create(input) {
+        const checkpoint = { id: randomUUID(), closed: false, ...input };
+        await this.redis.set(this.checkpointKey(checkpoint.id), JSON.stringify(checkpoint));
+        for (const pendingId of Object.keys(checkpoint.outstanding)) {
+            await this.redis.set(this.indexKey(pendingId), checkpoint.id);
+        }
+        return checkpoint;
+    }
+    async withCheckpoint(pendingId, fn) {
+        const checkpointId = await this.redis.get(this.indexKey(pendingId));
+        if (!checkpointId)
+            return (await fn(undefined)).result;
+        return this.withLock(checkpointId, async () => {
+            const raw = await this.redis.get(this.checkpointKey(checkpointId));
+            const current = raw ? JSON.parse(raw) : undefined;
+            const { checkpoint, result } = await fn(current && !current.closed ? current : undefined);
+            if (checkpoint) {
+                if (checkpoint.closed) {
+                    await this.redis.del(this.checkpointKey(checkpointId));
+                    for (const id of Object.keys(current?.outstanding ?? {}))
+                        await this.redis.del(this.indexKey(id));
+                }
+                else {
+                    await this.redis.set(this.checkpointKey(checkpointId), JSON.stringify(checkpoint));
+                }
+            }
+            return result;
+        });
+    }
+    async close() {
+        await this.redis.quit();
+    }
+}
+/** Same REDIS_URL-gated pattern as session-store.ts's own
+ * createSessionStore(): set -> RedisCheckpointStore, otherwise
+ * FileCheckpointStore under .checkpoints. */
+export function createCheckpointStore() {
+    const redisUrl = process.env.REDIS_URL;
+    return redisUrl ? new RedisCheckpointStore(redisUrl) : new FileCheckpointStore('.checkpoints');
+}

package/dist/core/gateway-tools.js

@@ -8,20 +8,21 @@
 // the only intended writer of that file; loadGatewayToolsFromDir is what
 // run-agent.ts calls to actually resolve it into ToolDefinitions.
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { parse as parseYaml, parseDocument, stringify as stringifyYaml } from 'yaml';
 import { connectComposioSource } from 'mcpplug';
 const execFileAsync = promisify(execFile);
-// Same "one level up from this file, not process.cwd()" reasoning
-// run-agent.ts's own agentsRootDir uses (this file lives in core/
-// alongside it, with agents/ one level up at repo root either way) — real
-// code (an actauth.yml write, a gateway-tools.yml write) needs to land in
-// the same place a built dist/ would look for it, not wherever the
-// process happened to be launched from.
-const agentsRootDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'agents');
+// gateway-tools.yml is plain data (see this file's own header comment),
+// not compiled code — same "resolved against process.cwd(), like
+// actauth.yml/skillsDirs, not import.meta.url" reasoning run-agent.ts's
+// own loadRules/skillsDirs defaults use, and unlike that file's tools/
+// subagents defaults (real compiled code, needing the built-alongside-
+// core/ fallback) this one doesn't need a dual-path check: the physical
+// file is at the same cwd-relative path whether it's this repo's own
+// agents/ or an external project's.
+const agentsRootDir = join(process.cwd(), 'agents');
 function gatewayToolsPath(dir) {
     return join(dir, 'gateway-tools.yml');
 }

package/dist/core/run-agent.js

@@ -33,6 +33,23 @@ export { systemTools } from './system-tools/index.js';
 // tools/index.ts is real code that only exists compiled, at a different
 // relative location, once dist/ is what's actually running.
 const agentsRootDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'agents');
+// agentsRootDir above is right when agents/ is compiled alongside core/
+// into the same dist/ tree (this repo's own reference agents; also this
+// repo's own Dockerfile, which copies dist/agents/**/*.js this way) — but
+// a project that only *depends on* the published loopengine package has
+// no dist/agents/<name> inside node_modules/loopengine at all, just its
+// own agents/<name>/ at the project root, found only via process.cwd(),
+// the same way loadRules/skillsDirs already resolve their own (data, not
+// code) defaults. Tried first since it's this repo's own existing,
+// tested behavior; process.cwd() only kicks in when nothing's built
+// there to find — so this repo's own agents are unaffected either way.
+function resolveAgentCodeDir(name, subpath, indexRequired) {
+    const built = join(agentsRootDir, name, subpath);
+    const builtExists = indexRequired
+        ? existsSync(join(built, 'index.ts')) || existsSync(join(built, 'index.js'))
+        : existsSync(built);
+    return builtExists ? built : join(process.cwd(), 'agents', name, subpath);
+}
 // Same "resolved relative to this file's own location" reasoning as
 // agentsRootDir above, but system-skills/ is a same-level sibling of
 // run-agent.ts itself (both live directly under core/ — see package.json's
@@ -157,7 +174,7 @@ async function loadToolsFromDir(toolsDir) {
     return [];
 }
 export async function loadDefaultTools(config) {
-    return loadToolsFromDir(join(agentsRootDir, config.name, 'tools'));
+    return loadToolsFromDir(resolveAgentCodeDir(config.name, 'tools', true));
 }
 /** Every other folder-form default in this file (loadDefaultTools,
  * loadRules, the skillsDirs default below) resolves against
@@ -229,7 +246,7 @@ async function resolveSubagentConfig(config, dir) {
  * this can't cycle the way a hand-wired agentAsTool(getEntry(...)) call
  * elsewhere could. */
 export async function loadSubagentAsTools(config) {
-    const subagentsDir = join(agentsRootDir, config.name, 'subagents');
+    const subagentsDir = resolveAgentCodeDir(config.name, 'subagents', false);
     if (!existsSync(subagentsDir))
         return [];
     const tools = [];
@@ -280,7 +297,7 @@ async function buildTurnContext(config, modelCall, options) {
         askUserTool,
         ...(config.tools ?? (await loadDefaultTools(config))),
         ...(await loadSubagentAsTools(config)),
-        ...(await loadGatewayToolsFromDir(join(agentsRootDir, config.name))),
+        ...(await loadGatewayToolsFromDir(join(process.cwd(), 'agents', config.name))),
     ]);
     // Omitted entirely (undefined): default to this agent's own
     // agents/<name>/skills — the folder-form convention every agent in

package/dist/index.d.ts

@@ -14,6 +14,29 @@ export { createOpenAIModelCall } from './core/model-calls/openai-model-call.js';
 export type { OpenAIModelCallOptions } from './core/model-calls/openai-model-call.js';
 export { createDeepSeekModelCall } from './core/model-calls/deepseek-model-call.js';
 export type { DeepSeekModelCallOptions } from './core/model-calls/deepseek-model-call.js';
-export { discoverAgents, loadAgentModule } from './core/discover-agents.js';
+export { discoverAgents, loadAgentModule, synthesizeCreateModelCall } from './core/discover-agents.js';
 export type { AgentModule } from './core/discover-agents.js';
 export { agentAsTool } from './core/agent-as-tool.js';
+export { resumeAgent, loadRules, loadDefaultTools, loadSubagentAsTools, systemTools, systemSkillsDir } from './core/run-agent.js';
+export { createCheckpointStore } from './core/durable-approvals.js';
+export type { TurnCheckpoint, CheckpointStore, OutstandingItem } from './core/durable-approvals.js';
+export { addGatewayTool, agentDir, disconnectComposioAccount, describeGatewayTools, listComposioConnections, listComposioTools, loadGatewayToolsFromDir, removeGatewayTool, removeGatewayToolSlug, GatewayToolExistsError, GatewayToolNotFoundError, } from './core/gateway-tools.js';
+export type { GatewayToolEntry, GatewayToolDecision } from './core/gateway-tools.js';
+export { WebhookNotifier } from './core/http-notify-triggers/webhook.js';
+export { listQuestions, answerQuestion as resolvePendingQuestion, findQuestion, createAskUserTool } from './core/system-tools/index.js';
+export type { PendingQuestion } from './core/system-tools/index.js';
+export { editAgentFile, AgentEditNotSupportedError, AgentFileNotFoundError } from './web/agent-file-admin.js';
+export type { AgentEditableFields, AgentEditResult } from './web/agent-file-admin.js';
+export { agentsConfigPageHtml } from './web/agents-config-page.js';
+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 type { SkillContent } from './web/skills-admin.js';
+export { readActauthConfig, addActauthRule, updateActauthRule, removeActauthRule, setDefaultDecision, ActauthRuleExistsError, ActauthRuleNotFoundError, } from './web/actauth-admin.js';
+export type { ActauthRuleInput, ActauthConfigView } from './web/actauth-admin.js';
+export { describeModelProviders, describeGateways } from './web/global-config.js';
+export type { ModelProviderInfo, AgentModelUsage, ModelsView, GatewayProviderInfo, GatewaysView } from './web/global-config.js';
+export { createTrackedApprover, listApprovals, decideApproval, findApproval } from './web/web-approver.js';
+export { scaffoldAgent, scaffoldSubagent, AgentNameError, AgentExistsError, AgentNotFoundError, AgentModelError } from './bin/cli.js';
+export type { AgentTemplateOptions } from './bin/cli.js';

package/dist/index.js

@@ -16,5 +16,30 @@ export { VectorIndex, embed, cosineSimilarity } from './core/vector-index.js';
 export { createAnthropicModelCall } from './core/model-calls/anthropic-model-call.js';
 export { createOpenAIModelCall } from './core/model-calls/openai-model-call.js';
 export { createDeepSeekModelCall } from './core/model-calls/deepseek-model-call.js';
-export { discoverAgents, loadAgentModule } from './core/discover-agents.js';
+export { discoverAgents, loadAgentModule, synthesizeCreateModelCall } from './core/discover-agents.js';
 export { agentAsTool } from './core/agent-as-tool.js';
+// Everything below backs the Admin UI (agents-config/list/global-config
+// pages, playground) that this repo's own adapters/http.ts wires up —
+// re-exported here, same "one entry point, no deep subpath imports"
+// convention as everything above, so a project scaffolded by
+// create-loopengine can build the same admin surface on top of its own
+// copy of adapters/http.ts (which, like agent-registry.ts, is meant to be
+// owned/edited, not imported — see this file's own header comment).
+export { resumeAgent, loadRules, loadDefaultTools, loadSubagentAsTools, systemTools, systemSkillsDir } from './core/run-agent.js';
+export { createCheckpointStore } from './core/durable-approvals.js';
+export { addGatewayTool, agentDir, disconnectComposioAccount, describeGatewayTools, listComposioConnections, listComposioTools, loadGatewayToolsFromDir, removeGatewayTool, removeGatewayToolSlug, GatewayToolExistsError, GatewayToolNotFoundError, } from './core/gateway-tools.js';
+export { WebhookNotifier } from './core/http-notify-triggers/webhook.js';
+// answerQuestion above (core/client.ts) is the HTTP client-side helper —
+// this is the server-side function that actually resolves a pending
+// question in-process, aliased to avoid colliding with that name.
+export { listQuestions, answerQuestion as resolvePendingQuestion, findQuestion, createAskUserTool } from './core/system-tools/index.js';
+export { editAgentFile, AgentEditNotSupportedError, AgentFileNotFoundError } from './web/agent-file-admin.js';
+export { agentsConfigPageHtml } from './web/agents-config-page.js';
+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 { readActauthConfig, addActauthRule, updateActauthRule, removeActauthRule, setDefaultDecision, ActauthRuleExistsError, ActauthRuleNotFoundError, } from './web/actauth-admin.js';
+export { describeModelProviders, describeGateways } from './web/global-config.js';
+export { createTrackedApprover, listApprovals, decideApproval, findApproval } from './web/web-approver.js';
+export { scaffoldAgent, scaffoldSubagent, AgentNameError, AgentExistsError, AgentNotFoundError, AgentModelError } from './bin/cli.js';

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

@@ -0,0 +1,36 @@
+import type { Decision } from 'actauth';
+export declare class ActauthRuleExistsError extends Error {
+}
+export declare class ActauthRuleNotFoundError extends Error {
+}
+export interface ActauthRuleInput {
+    name: string;
+    scope: string;
+    tool: string;
+    decision: Decision;
+}
+export interface ActauthConfigView {
+    defaultDecision: Decision;
+    rules: ActauthRuleInput[];
+}
+/** The admin page's read model for the Actauth tab — every rule as plain
+ * data, in file order. Unlike run-agent.ts's loadRules, this reads the
+ * raw per-agent scope (e.g. "default/production", a wildcard pair)
+ * rather than the 3-segment form actauth.RuleSet works with internally —
+ * the admin UI edits the same file an operator would hand-edit, so it
+ * should show exactly what's on disk, not a resolved/expanded form. */
+export declare function readActauthConfig(agentName: string): ActauthConfigView;
+/** Appends a new rule. `rule.name` must be unique among this agent's
+ * existing rules — it's the only handle update/removeActauthRule below
+ * have to find it again, so a duplicate would make those ambiguous. */
+export declare function addActauthRule(agentName: string, rule: ActauthRuleInput): void;
+/** Mutates an existing rule's scope/tool/decision in place (via the
+ * node's own `.set()`, not remove-then-re-add), so any comment attached
+ * to that specific rule in the source YAML survives the edit. */
+export declare function updateActauthRule(agentName: string, ruleName: string, updates: {
+    scope: string;
+    tool: string;
+    decision: Decision;
+}): void;
+export declare function removeActauthRule(agentName: string, ruleName: string): void;
+export declare function setDefaultDecision(agentName: string, decision: Decision): void;

package/dist/web/actauth-admin.js

@@ -0,0 +1,108 @@
+// Lets an operator add, edit, or remove an actauth.yml rule (and set
+// default_decision) from the Actauth tab in /agents/config, instead of
+// hand-editing agents/<name>/actauth.yml directly. Same yaml Document
+// API discipline gateway-tools.ts's appendActauthRules/
+// removeAutoAddedActauthRules already established — parse → mutate the
+// CST → toString, never parse-into-plain-object → re-stringify, since
+// the latter silently drops every comment in a file real agents (see
+// agents/customer-service/actauth.yml) use to document individual
+// rules' reasoning.
+//
+// Deliberately does not let a rule be renamed — `name` is this admin
+// UI's identifier for a rule (the :ruleName URL segment), so an "update"
+// only ever touches scope/tool/decision/when; renaming is a delete +
+// re-add, same as any other keyed-by-name resource here.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseDocument } from 'yaml';
+import { agentDir } from '../core/gateway-tools.js';
+export class ActauthRuleExistsError extends Error {
+}
+export class ActauthRuleNotFoundError extends Error {
+}
+function actauthPath(dir) {
+    return join(dir, 'actauth.yml');
+}
+function loadDoc(dir) {
+    const path = actauthPath(dir);
+    const doc = existsSync(path) ? parseDocument(readFileSync(path, 'utf8')) : parseDocument('default_decision: deny\nrules: []\n');
+    if (doc.get('rules') == null)
+        doc.set('rules', []);
+    return { path, doc };
+}
+function saveDoc(dir, path, doc) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, doc.toString());
+}
+/** The admin page's read model for the Actauth tab — every rule as plain
+ * data, in file order. Unlike run-agent.ts's loadRules, this reads the
+ * raw per-agent scope (e.g. "default/production", a wildcard pair)
+ * rather than the 3-segment form actauth.RuleSet works with internally —
+ * the admin UI edits the same file an operator would hand-edit, so it
+ * should show exactly what's on disk, not a resolved/expanded form. */
+export function readActauthConfig(agentName) {
+    const dir = agentDir(agentName);
+    const path = actauthPath(dir);
+    if (!existsSync(path))
+        return { defaultDecision: 'deny', rules: [] };
+    const doc = parseDocument(readFileSync(path, 'utf8'));
+    const defaultDecision = doc.get('default_decision') ?? 'ask';
+    const rules = doc.get('rules');
+    const rulesList = (rules?.items ?? []).map((rule) => ({
+        name: String(rule.get('name') ?? ''),
+        scope: String(rule.get('scope') ?? ''),
+        tool: String(rule.get('tool') ?? ''),
+        decision: rule.get('decision'),
+    }));
+    return { defaultDecision, rules: rulesList };
+}
+function findRuleIndex(rules, ruleName) {
+    return rules.items.findIndex((rule) => rule.get('name') === ruleName);
+}
+/** Appends a new rule. `rule.name` must be unique among this agent's
+ * existing rules — it's the only handle update/removeActauthRule below
+ * have to find it again, so a duplicate would make those ambiguous. */
+export function addActauthRule(agentName, rule) {
+    const dir = agentDir(agentName);
+    const { path, doc } = loadDoc(dir);
+    const rules = doc.get('rules');
+    if (findRuleIndex(rules, rule.name) !== -1) {
+        throw new ActauthRuleExistsError(`A rule named '${rule.name}' already exists for '${agentName}' — pick a different name or remove it first.`);
+    }
+    rules.add(doc.createNode({ name: rule.name, scope: rule.scope, tool: rule.tool, decision: rule.decision }));
+    saveDoc(dir, path, doc);
+}
+/** Mutates an existing rule's scope/tool/decision in place (via the
+ * node's own `.set()`, not remove-then-re-add), so any comment attached
+ * to that specific rule in the source YAML survives the edit. */
+export function updateActauthRule(agentName, ruleName, updates) {
+    const dir = agentDir(agentName);
+    const { path, doc } = loadDoc(dir);
+    const rules = doc.get('rules');
+    const index = findRuleIndex(rules, ruleName);
+    if (index === -1) {
+        throw new ActauthRuleNotFoundError(`No rule named '${ruleName}' for '${agentName}'.`);
+    }
+    const rule = rules.items[index];
+    rule.set('scope', updates.scope);
+    rule.set('tool', updates.tool);
+    rule.set('decision', updates.decision);
+    saveDoc(dir, path, doc);
+}
+export function removeActauthRule(agentName, ruleName) {
+    const dir = agentDir(agentName);
+    const { path, doc } = loadDoc(dir);
+    const rules = doc.get('rules');
+    const index = findRuleIndex(rules, ruleName);
+    if (index === -1) {
+        throw new ActauthRuleNotFoundError(`No rule named '${ruleName}' for '${agentName}'.`);
+    }
+    rules.items = rules.items.filter((_, i) => i !== index);
+    saveDoc(dir, path, doc);
+}
+export function setDefaultDecision(agentName, decision) {
+    const dir = agentDir(agentName);
+    const { path, doc } = loadDoc(dir);
+    doc.set('default_decision', decision);
+    saveDoc(dir, path, doc);
+}

package/dist/web/agent-file-admin.d.ts

@@ -0,0 +1,30 @@
+export declare class AgentEditNotSupportedError extends Error {
+}
+export declare class AgentFileNotFoundError extends Error {
+}
+type Provider = 'anthropic' | 'openai' | 'deepseek';
+export interface AgentEditableFields {
+    systemPrompt?: string;
+    model?: {
+        provider: Provider;
+        model?: string;
+    };
+}
+export interface AgentEditResult {
+    systemPrompt?: string;
+    model?: {
+        provider: Provider;
+        model: string;
+    };
+}
+/** Surgically rewrites just the fields given in `fields` — see this
+ * file's own header comment for why, and for the "refuse rather than
+ * guess" rule this follows for anything that isn't a plain, recognizable
+ * shape. Returns the values actually written (model's own default
+ * resolution included), so the caller (adapters/http.ts's
+ * handleEditAgent) can apply the exact same values to the *live*
+ * registry entry — see core/agent-registry.ts's own updateAgent — without
+ * needing to re-derive them. A field omitted from `fields` entirely is
+ * left completely untouched, both on disk and in the return value. */
+export declare function editAgentFile(agentName: string, fields: AgentEditableFields): AgentEditResult;
+export {};