loopengine 0.1.14 → 0.1.22

package/README.md

@@ -7,25 +7,36 @@ and permission rules, run through a transparent ReAct loop. No chain DSL,
 no hidden control flow — `core/run-agent.ts` is a single function you can read
 top to bottom. Run agents over a CLI, an HTTP API, or both.
 
-Once you define an agent, the loop turns it into something you can put in
-front of real users or real systems:
-
-- **Callable over CLI or HTTP** — a script you run locally, or a real
-  service other apps can hit.
-- **Does real work, safely** — tools can hit a database, send emails, call
+## Why LoopEngine
+
+- **Up and running in one command.** `npx create-loopengine@latest` scaffolds
+  a real, standalone project — its own repo, a starter agent, CLI and HTTP
+  adapters already wired up. `npm install && npm run dev` and you have a
+  running agent server, not a half-finished template to wire up yourself.
+- **A real Admin UI, not just logs.** Open `/agents/config` in a browser to
+  see and edit a live agent: its resolved config, permission rules, skills,
+  tool connections, and secrets — no redeploy to change a rule or add a
+  skill. See [Admin UI](#admin-ui) below.
+- **Human-in-the-loop, wired for real notification channels.** A risky tool
+  call or a genuinely ambiguous question routes to a human — live in a chat
+  session, or durably via Slack, Lark, email, a generic webhook, or a
+  polling queue, resumable minutes or days later. See
+  [Human in the loop](#human-in-the-loop) below.
+- **Sessions persist automatically.** Send a message, get a reply, come
+  back later with the same session id and continue — no database to wire
+  up yourself, and it survives a crash mid-turn cleanly.
+- **A package system for reusable capabilities.** Install a bundle of
+  tools, a skill, and the permission rules that gate them with one command
+  — real, reviewable files in your own repo, not an opaque dependency. See
+  [Package system](#package-system) below.
+- **Does real work, safely.** Tools can hit a database, send emails, call
   GitHub/Slack, anything with an `execute` function. Permission rules gate
-  what happens without a human: safe reads auto-run, risky actions (a
-  refund, a send) get approval or are denied outright, so you can wire up
-  powerful tools without trusting the model blindly.
-- **Remembers** — conversations persist across requests, so a caller can
-  send one message, get a reply, and continue later.
-- **Multi-tenant out of the box** — the same deployed agent can serve
-  different customers/orgs with different permission levels, with no
-  forking required.
-- **Composable into bigger agents** — drop one agent's folder under
-  another's `subagents/` and it becomes a tool the parent can delegate
-  to, own tools/rules/loop intact. No chain DSL for orchestration either:
-  the parent's model just decides when to call it, like any other tool.
+  what happens without a human: safe reads auto-run, risky actions get
+  approval or are denied outright.
+- **Multi-tenant and composable out of the box.** The same deployed agent
+  serves different customers with different permission levels, no forking
+  required — and one agent's folder drops under another's `subagents/` to
+  become a tool the parent can delegate to, own tools/rules/loop intact.
 
 So the payoff: you write one `AgentConfig`, and get a deployable,
 persistent, permission-safe service — not just a prompt-and-response demo.
@@ -69,11 +80,14 @@ conventional path under the agent's own folder:
 | `skillsDirs` | `agents/<name>/skills` (missing → no skills) |
 
 There's no `subagents` field to omit — `agents/<name>/subagents/*` is its
-own folder convention, always merged into `tools` on top of whatever the
-table above resolves to. See "Subagents" below.
+own folder convention (drop another agent's folder there and it becomes
+one of this agent's tools automatically), always merged into `tools` on
+top of whatever the table above resolves to.
 
-`rules` is how you gate what a tool can do without approval — see
-"Tool permission and multi-tenancy" below.
+`rules` is how you gate what a tool can do without approval — each rule
+maps a `scope` (tenant/environment) + tool name to `allow`/`ask`/`deny`,
+with an `ask` decision routing to a human — see
+[Human in the loop](#human-in-the-loop) below.
 
 The simplest possible agent, `agents/weather-agent/index.ts` — `tools`,
 `rules`, and `skillsDirs` all omitted, so they default to
@@ -92,281 +106,101 @@ export const config: AgentConfig = {
 See `agents/customer-service/` and `agents/file-agent/` for complete,
 working examples.
 
-## Core concepts
-
-### 1. The Loop
-
-`core/run-agent.ts` is the whole engine — a single, readable ReAct loop with no
-hidden control flow: call the model, act on what it asks for, repeat.
-
-1. Call the model with the conversation so far.
-2. If it responds with tool calls, each one is checked against
-   `AgentConfig.rules` — allowed calls run, denied calls are refused,
-   "ask" calls go to whatever approver applies for the call's own channel
-   (see "Tool permission and multi-tenancy" below) — a live approver is
-   awaited right there; a durable one returns instantly and the call is
-   resolved later instead.
-3. Approved calls execute and their results feed back into the
-   conversation.
-4. Repeat from step 1 — until the model stops requesting tools
-   (`end_turn`) or `AgentConfig.maxTurns` (default 25) is hit, which ends
-   the turn with `RunAgentResult.stopReason: 'max_turns'`, a real result
-   rather than a thrown error.
-
-`runAgent` itself does no I/O — callers own conversation history and the
-model call — which is what lets the same loop serve a one-shot CLI call,
-a long-lived HTTP chat session, and a fully simulated test, unchanged.
-
-### 2. Agents — convention over configuration
-
-Beyond the `AgentConfig` shape and folder convention shown in "Define
-your first agent" above, the discovery mechanism is what makes this
-convention-over-configuration: `discoverAgents` scans `agents/` at
-startup, keyed by each module's own `AgentConfig.name` — not the
-filename or folder name — and builds the name → config lookup every
-adapter uses. Nothing to register by hand; a module that exports neither
-`config` nor a way to build a model call fails loudly at startup instead
-of silently not showing up.
-
-### 3. Skills and tools: agent-specific vs. global
-
-Both skills and tools follow the same rule: **default to agent-specific,
-promote to global only once something is genuinely shared.**
-
-- **Agent-specific** (the default) — lives under that agent's own folder,
-  seen only by that agent:
-  ```
-  agents/<name>/skills/<skill>/SKILL.md
-  agents/<name>/tools/<tool>.ts
-  ```
-- **Global** — lives at the repo root, seen by every agent that opts in:
-  ```
-  skills/<skill>/SKILL.md      # pointed at by any agent whose skillsDirs includes it
-  tools/<tool>.ts              # imported explicitly into any agent's tools array
-  ```
-
-Skills are discovered via `AgentConfig.skillsDirs` (an array of
-directories, `SKILL.md`-based: a short description stays in context, the
-full body loads only when the model invokes it). Tools have no
-auto-discovery — an agent's `tools` array just imports whichever tool
-files it wants, agent-specific or global.
-
-Both root directories (`tools/`, `skills/`) are empty today — every skill
-and tool in this repo is agent-specific. Move something there only when a
-second agent actually needs the exact same one, not because it feels
-reusable in theory.
-
-**Opting an agent into a global skill or tool** is explicit either way —
-nothing scans the root for you:
-
-```ts
-// Global skill: add the root path alongside the agent's own
-skillsDirs: ['agents/my-agent/skills', 'skills']
-
-// Global tool: tools has no auto-discovery, so import it and merge it
-// into the agent's own array by hand
-import { sharedTool } from '../../tools/shared-tool.js'
-import { tools as ownTools } from './tools/index.js'
-
-tools: [...ownTools, sharedTool]
-```
-
-Tools don't have to be hand-written either. For SaaS actions (GitHub,
-Slack, etc.) where you'd rather not own the vendor's OAuth flow yourself,
-[`mcpplug`](https://www.npmjs.com/package/mcpplug) connects through
-[Composio](https://composio.dev), which already holds the OAuth
-relationship with 1000+ apps, and returns tools in the same
-`ToolDefinition` shape — so they drop into `tools` right alongside your
-own:
-
-```ts
-import { connectComposioSource } from 'mcpplug'
-
-const composioTools = await connectComposioSource('composio', {
-  slugs: ['GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER'],
-}).then((source) => source.loadTools())
-
-const config: AgentConfig = {
-  name: 'my-agent',
-  tools: [...handWrittenTools, ...composioTools],
-  rules: [{ scopePattern: 'default/production/my-agent', tool: 'composio_GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER', decision: 'allow' }],
-  defaultDecision: 'ask',
-}
-```
-
-Either kind of tool goes through the same permission gating, parallel
-scheduling, and context-budget tracking. See `agents/file-agent/index.ts`
-for a working example.
-
-### 4. Subagents — an agent as another agent's tool
+## Admin UI
 
-Drop a folder under `agents/<name>/subagents/<child>/` and `child` becomes
-one of `name`'s tools automatically — no import, no `AgentConfig.tools`
-edit, nothing to register by hand:
+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:
 
-```
-agents/support-orchestrator/
-  index.ts                        # the orchestrator's own AgentConfig
-  subagents/
-    billing-agent/index.ts        # a full AgentConfig, same shape as a top-level agent
-    refunds-agent/index.ts
-```
-
-Scaffold one directly:
-
-```bash
-npx loopengine add-subagent support-orchestrator billing-agent
-# -> Created agents/support-orchestrator/subagents/billing-agent/index.ts
-```
-
-A subagent is a normal `AgentConfig` plus one required field —
-`toolDescription`, the text the *parent's* model reads to decide when to
-delegate to it (its own `systemPrompt` is instructions for itself, not a
-pitch to a caller deciding whether to invoke 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. |
+| **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 a package (see [Package system](#package-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. |
+
+Every tab is backed by a real API (`GET /agents/:name/config`, `.../actauth`,
+`.../env`, ...) that reuses the exact same resolution `runAgent()` itself
+uses — so what you see here can't drift out of sync with what a real
+request actually gets, and never returns a model API key.
+
+## Human in the loop
+
+A risky tool call (`actauth`'s `ask` decision) or a genuinely ambiguous
+question the model itself raises both need a human — and LoopEngine
+handles both the same way, live or durable:
+
+- **Live** — someone's actively watching right now (a terminal, an open
+  chat session). The turn just waits; `cli`/`http_stream` get this
+  automatically, with nothing to configure.
+- **Durable** — nobody's watching (a webhook-triggered run, a ticket that
+  came in overnight). The turn ends immediately with a resumable pending
+  state, and a real notification goes out on whichever channel you've
+  configured — resolvable minutes or days later without holding any
+  process open in between.
+
+Six channels ship as real, working notifiers — configure one and the
+"send a notification" side is done for you:
+
+| Channel | What it does |
+| --- | --- |
+| `webhook` | Signed HMAC-SHA256 POST to any URL you own |
+| `slack` | An interactive message via `chat.postMessage`, with Approve/Deny buttons |
+| `lark` | A Lark/Feishu interactive card |
+| `email` | A signed, expiring magic-link per decision |
+| `database` | Writes a row for your own worker/dashboard to poll |
+| `redis` | Pushes a queue entry for your own worker to consume |
 
 ```ts
 export const config: AgentConfig = {
-  name: 'billing-agent',
-  systemPrompt: 'You answer billing questions.',
-  toolDescription: 'Call this for any billing-related question.',
-  model: { provider: 'anthropic', model: 'claude-sonnet-5' },
+  // ...
+  httpNotifier: {
+    channel: 'slack',
+    config: { botToken: process.env.SLACK_BOT_TOKEN!, channelId: process.env.SLACK_CHANNEL_ID! },
+    events: ['approval', 'question'],
+  },
 }
 ```
 
-Calling that tool runs the subagent's whole ReAct loop — its own tools,
-rules, permissions — to completion, and only its final text comes back;
-the parent never sees the subagent's turns or tool calls. Orchestration
-needs no separate concept on top of this: an "orchestrator" is just an
-agent whose tools happen to be other agents, and the model decides which
-to call, in what order, the same as any other tool — no chain DSL.
+Reference implementations for the receiving side (verifying a Slack
+click, a webhook HMAC signature, a magic-link token) ship under
+`examples/notifier-handler/` for the four channels that need one. See
+[`HUMAN_IN_THE_LOOP.md`](HUMAN_IN_THE_LOOP.md) for the full setup guide —
+live and durable, worked examples, and how resumption actually works
+under the hood.
 
-Subagents nest — a subagent's own `subagents/` folder works the same way,
-one level down, addressed by joining names with `/`:
+## Package system
+
+Giving an agent a new capability is usually three separate, hand-authored
+things: a tool file, a `SKILL.md` teaching the model when to use it, and
+an `actauth` rule allowing it to actually run. A **loopengine package**
+bundles all three into one installable unit:
 
 ```bash
-npx loopengine add-subagent support-orchestrator/billing-agent disputes-agent
+npx loopengine add-package <spec> --agent customer-service
 ```
 
-A few things worth knowing before reaching for this:
-
-- **The call blocks.** Every tool call in the loop is awaited before the
-  next model turn, so a slow subagent blocks its parent's turn — and if
-  the parent is itself a subagent of another agent, that blocks too.
-  There's no background/async or streaming pattern here.
-- **Permissions don't inherit.** Each agent's own `actauth.yml` governs
-  only its own tools; delegating to a subagent neither grants nor
-  inherits permissions in either direction.
-- **`maxTurns` compounds.** A request that reaches a grandchild subagent
-  spends turns at every level (default 25 each) — a "simple" answer can
-  cost far more than any one agent's own turn budget suggests.
-
-### 5. Gateway tool sources — connecting external tools from a web page
-
-Beyond hand-written tools and subagents, an agent can pull tools from an
-external gateway — [Composio](https://composio.dev) today, with
-[`mcpplug`](https://www.npmjs.com/package/mcpplug)'s `ToolSource`
-interface designed so more providers (Nango, Arcade, Scalekit, ...) slot
-in later as thin adapters, same shape. Unlike hand-written tools, these
-are meant to be managed by an operator at runtime, not committed to code:
-run the HTTP adapter, open `/agents/config`, pick an agent, and switch to
-its "Gateway tools" tab — alongside "Overview" and "Actauth" — to see its
-connected sources and add or remove one.
+`<spec>` is anything `npm pack` understands — a public or private npm
+package, a scoped package on a private registry, or a plain git repo. The
+tool files, skill directory, and actauth rules all land as real files in
+the agent's own tree, copied in rather than imported as a `node_modules`
+dependency — reviewable, diffable, and editable the same as anything you
+would have hand-written, not an opaque black box.
 
 ```bash
-npx tsx --env-file-if-exists=.env adapters/http.ts
-# open http://localhost:8787/agents/config
+npx loopengine upgrade-package <packageName> --agent customer-service
+npx loopengine remove-package <packageName> --agent customer-service
 ```
 
-Adding a source (via the page, or `POST /agents/:name/gateway-tools` with
-`{ provider: 'composio', name: 'gh', slugs: [...] }`) writes
-`agents/<name>/gateway-tools.yml` — read fresh off disk on every request,
-same "no restart to see an edit" behavior `actauth.yml` already has.
-Composio's own OAuth is out of band: run `composio link <toolkit>` once
-on the machine running the server, then use the page purely to pick which
-already-authorized slugs to expose to which agent.
-
-A newly-added tool is **denied by default**, same "opt-in, not silently
-allowed" rule every tool in this repo follows — pass a `decision` when
-adding a source (or use the page's permission dropdown) to seed an
-`actauth.yml` rule for it instead, or add the rule by hand afterward.
-
-### 6. Tool permission and multi-tenancy
-
-Every tool call is gated by [`actauth`](https://www.npmjs.com/package/actauth):
-each rule in `AgentConfig.rules` maps a `scope` (tenant/environment) + tool
-name to `allow` / `ask` / `deny`. Anything not covered falls through to
-`defaultDecision`. An `ask` decision routes to whichever approver applies
-for the call's own channel: `cli`/`http_stream` always get the library's
-own live default (`ConsoleApprover`, blocking on stdin, for `cli`; a live
-approval popup for `http_stream`) — nothing to configure there — and
-`http` gets a durable one whenever `AgentConfig.httpNotifier` is
-configured for it (see below), falling back to the same kind of live
-default otherwise.
-
-`ask` approvers come in two shapes. A **live** one (`WebchatApprover`,
-`SlackChatApprover`, `ConsoleApprover`) is awaited directly — the turn stays
-suspended until a human decides, which only makes sense when someone's
-actually there right now (a terminal, an open chat connection). A
-**durable** one (`WebhookApprover`) fires a signed webhook and returns
-instantly instead — the turn ends with `stopReason: 'pending_approval'`,
-durably resumable minutes or days later via
-`POST /pending-approvals/:pendingId/resolve`, without holding any
-process open in between. See `HUMAN_IN_THE_LOOP.md` for the full design.
-
-The system `ask_user` tool (a model asking a human a genuinely ambiguous
-clarifying question mid-turn) gets the same live/durable split, via
-`RunAgentOptions.questionHandler` (or `AgentConfig.httpNotifier`'s own
-`'question'` event, for the `http` channel specifically): live by default
-(blocks on the channel it's raised on), or durable — a
-`DurableQuestionHandler` (e.g. `core/http-notify-triggers/webhook.ts`'s
-`WebhookNotifier`) instead ends the turn with `stopReason:
-'pending_question'`, resumable via
-`POST /pending-questions/:pendingId/answer`. See `HUMAN_IN_THE_LOOP.md`'s
-own "Durable questions" section.
-
-For the practical "what do I actually need to build" version of all of
-this — live chat setup, durable setup, and reference implementations for
-Slack/Lark/email/generic-webhook notification channels — see
-[`HUMAN_IN_THE_LOOP.md`](HUMAN_IN_THE_LOOP.md).
-
-A real agent's rules live in `agents/<name>/actauth.yml`:
-
-```yaml
-default_decision: deny
-
-rules:
-  - name: weather-lookup-always-allowed
-    scope: "*/*"
-    tool: get_weather
-    decision: allow
-```
-
-`scope` is `tenant/environment` — `"*/*"` here means "every tenant, every
-environment." Rules are matched most-specific-scope-first, so an agent
-that needs different behavior per tenant just adds a more specific rule
-(e.g. `acme-corp/production`) alongside the wildcard fallback.
-
-That `scope` is what makes rules multi-tenant: the same agent can behave
-differently for different customers. `environment` is a deployment-wide
-setting (`LOOPENGINE_ENV`, default `production`). `tenant` is resolved per
-request via `AgentConfig.tenantFor?: (headers, body) => string |
-undefined` — from headers only, never the request body, since it feeds
-permission decisions directly. No `tenantFor` means every request is the
-`'default'` tenant.
-
-### 7. Sessions
-
-A session is one ongoing conversation. Message history persists between
-requests automatically — send a message, get a reply, come back later with
-the same `sessionId` and continue where you left off. Two storage backends,
-picked automatically: a local file store, or Redis if `REDIS_URL` is set
-(needed for multiple server instances).
-
-An agent can define `AgentConfig.sessionIdFor(body)` to control what
-counts as "one conversation" for its own domain (e.g. `customer-service`
-hashes `customerEmail`, so a request with no email is rejected rather than
-starting an anonymous session). Without it, the caller just supplies a
-`sessionId`, or gets one generated for them.
+Upgrading does a real three-way merge per file — a hand-edit since install
+survives, a genuine conflict leaves `<<<<<<<` markers to resolve by hand
+instead of silently overwriting either side. Removing refuses a file
+that's been modified since install unless you pass `--force`. A package
+can also declare the env vars its tools need, which then show up in the
+Admin UI's [Environment tab](#admin-ui) automatically once installed. See
+[`PACKAGES.md`](PACKAGES.md) for the full design — format, publishing,
+and how the merge/upgrade mechanics work in detail.
 
 ## Running an agent
 
@@ -443,18 +277,8 @@ plain-HTTP/CLI transport bindings, and a JSON Schema
 `core/client.ts` and the `examples/chatbox/react`/`examples/chatbox/vue`
 hooks are reference implementations of it.
 
-**Agent config page:** open `http://localhost:8787/agents/config`
-(optionally `?agent=<name>`) to browse every registered agent's resolved
-config — system prompt, model, tools (with their JSON schemas and
-parallel-safety), the actual ActAuth rules that would be enforced (source,
-default decision, per-rule scope/tool/decision/`when`), and whether
-`sessionIdFor`/`tenantFor`/`isSafeTool` are custom or defaulted, and
-whether the `http` channel's approver is custom (`httpNotifier` covers
-`'approval'`) or the library's own default. Backed
-by `GET /agents/:name/config`, which reuses the same
-rule/tool resolution `runAgent()` itself uses, so it can't drift out of
-sync with what a real request actually gets. Never returns
-`AgentModelConfig.apiKey`.
+**Agent config page:** this is the [Admin UI](#admin-ui) described above
+— open `http://localhost:8787/agents/config` (optionally `?agent=<name>`).
 
 ## Wiring a real model
 
@@ -490,13 +314,14 @@ testing), export your own `createModelCall(): ModelCall` instead.
 | `core/budget.ts` / `core/compaction.ts` | Context-window budget tracking and tail-preserving compaction (vendored in-repo, not an external dependency) |
 | `core/recovery.ts` | Retries prompt-too-long / truncated-output failures (vendored in-repo, not an external dependency) |
 | `core/durable-approvals.ts` | `TurnCheckpoint`/`CheckpointStore` (file/Redis) backing durable, resumable `ask` decisions — see `HUMAN_IN_THE_LOOP.md` |
-| [`sessionknit`](https://www.npmjs.com/package/sessionknit) | Durable session log with crash-interruption detection |
-| [`skillgarden`](https://www.npmjs.com/package/skillgarden) | `SKILL.md` discovery and lazy loading |
-| [`toollane`](https://www.npmjs.com/package/toollane) | Parallel/solo tool-call scheduling |
-| [`mcpplug`](https://www.npmjs.com/package/mcpplug) | Gateway tool sourcing (e.g. Composio) |
-
-Installing `loopengine` pulls all of these in as regular dependencies —
-install one directly only if you want to use it standalone.
+| `core/sessionknit.ts` | Durable session log with crash-interruption detection (vendored in-repo, not an external dependency) |
+| `core/skillgarden/` | `SKILL.md` discovery and lazy loading (vendored in-repo, not an external dependency) |
+| `core/toollane.ts` | Parallel/solo tool-call scheduling (vendored in-repo, not an external dependency) |
+| `core/mcpplug.ts` | Gateway tool sourcing (e.g. Composio) (vendored in-repo, not an external dependency) |
+
+Installing `loopengine` pulls in `actauth` as a regular dependency —
+install it directly only if you want to use it standalone. Everything
+else in this table ships inside `loopengine` itself.
 
 ## Deployment
 

package/dist/bin/package-manager.js

@@ -24,7 +24,7 @@ import { tmpdir } from 'node:os';
 import { parse as parseYaml } from 'yaml';
 import semver from 'semver';
 import { agentDir } from '../core/gateway-tools.js';
-import { addToolToIndex, toCamelCase } from '../web/http-tool-admin.js';
+import { addToolToIndex, removeToolFromIndex, toCamelCase } from '../web/http-tool-admin.js';
 import { addActauthRule, updateActauthRule, removeActauthRule, readActauthConfig } from '../web/actauth-admin.js';
 export class PackageManifestError extends Error {
 }
@@ -484,6 +484,7 @@ export function removePackage(agentName, packageName, force = false) {
     const refused = [];
     const remainingTools = [];
     const remainingSkills = [];
+    const toolsIndexPath = join(agentDir(agentName), 'tools', 'index.ts');
     for (const toolName of record.tools) {
         const relPath = `tools/${toolName}.ts`;
         const fullPath = join(agentDir(agentName), relPath);
@@ -493,6 +494,14 @@ export function removePackage(agentName, packageName, force = false) {
             continue;
         }
         rmSync(fullPath, { force: true });
+        // Undoes installPackage's own addToolToIndex call — without this, a
+        // deleted tool's import survives in tools/index.ts, and either fails
+        // the next build (a dangling import to a file that no longer exists)
+        // or, worse, silently duplicates on a later add-package of the same
+        // tool (addToolToIndex used to have no idempotence check at all —
+        // now it does, but this is the actual fix: the stale entry shouldn't
+        // be there to begin with).
+        removeToolFromIndex(toolsIndexPath, toolName, toCamelCase(toolName));
         removed.push(relPath);
     }
     for (const skillId of record.skills) {

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

@@ -1,6 +1,6 @@
 import type { Rule, Decision, Scope } from 'actauth';
 import type { Redis } from 'ioredis';
-import type { SafetyClassifier } from 'toollane';
+import type { SafetyClassifier } from './toollane.js';
 import type { Summarizer } from './compaction.js';
 /** Which channel a runAgent() call is on — the value RunAgentOptions.channel
  * carries, checked against directly by AgentConfig.httpNotifier's own

package/dist/core/gateway-tools.js

@@ -1,7 +1,7 @@
 // Lets an operator register external tool gateways (Composio today —
-// Nango, Arcade, Scalekit are meant to slot in later as thin mcpplug
-// ToolSource adapters, same shape, once this mechanism is proven) against
-// an agent, without hand-writing a tools/index.ts. The registry is
+// Nango, Arcade, Scalekit are meant to slot in later as thin
+// mcpplug.ts ToolSource adapters, same shape, once this mechanism is
+// proven) against an agent, without hand-writing a tools/index.ts. The registry is
 // agents/<name>/gateway-tools.yml — plain data, read fresh off disk every
 // call, same "no restart to see an edit" behavior actauth.yml already
 // has (see run-agent.ts's loadRules). adapters/http.ts's admin routes are
@@ -12,7 +12,7 @@ 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';
+import { connectComposioSource } from './mcpplug.js';
 const execFileAsync = promisify(execFile);
 // gateway-tools.yml is plain data (see this file's own header comment),
 // not compiled code — same "resolved against process.cwd(), like

package/dist/core/mcpplug.d.ts

@@ -0,0 +1,23 @@
+import type { ToolDefinition } from './agent-config.js';
+/** One connection to one external tool gateway (Composio today; a raw MCP
+ * client is a later, separate source). `name` is used to namespace every
+ * tool it produces, so two sources never collide. */
+export interface ToolSource {
+    name: string;
+    loadTools(): Promise<ToolDefinition[]>;
+    close(): Promise<void>;
+}
+export interface ComposioSourceOptions {
+    /** Composio tool slugs to expose, e.g.
+     * "GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER". Explicit, not
+     * auto-discovered — same reasoning actauth rules are opt-in per tool
+     * rather than a blanket allow; an agent should only see the Composio
+     * actions its config actually lists. */
+    slugs: string[];
+    /** Defaults to 'composio' — override to point at a stand-in binary in tests. */
+    cliCommand?: string;
+}
+/** Sources ToolDefinitions from the Composio CLI — already-authenticated
+ * (`composio link <toolkit>`) tool execution across 1000+ apps, so this
+ * source needs no OAuth code of its own; Composio owns that entirely. */
+export declare function connectComposioSource(name: string, options: ComposioSourceOptions): Promise<ToolSource>;

package/dist/core/mcpplug.js

@@ -0,0 +1,64 @@
+// Formerly the standalone `mcpplug` package — folded in here since it
+// had exactly one real consumer (gateway-tools.ts, below) and the
+// "usable by any agent runtime" framing it shipped with was aspirational,
+// never actually exercised by a second host. Reuses this repo's own
+// ToolDefinition (agent-config.ts) directly instead of mcpplug's own
+// parallel-but-identical copy — that duplication only existed to keep
+// mcpplug import-free of loopengine, which stopped mattering once it
+// moved in.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+function humanize(slug) {
+    return slug.toLowerCase().split('_').join(' ');
+}
+async function runCli(cliCommand, args) {
+    let stdout;
+    try {
+        ;
+        ({ stdout } = await run(cliCommand, args));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`composio CLI call failed (${args.join(' ')}): ${message}`);
+    }
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`composio CLI returned non-JSON output for ${args.join(' ')}: ${stdout}`);
+    }
+}
+/** Sources ToolDefinitions from the Composio CLI — already-authenticated
+ * (`composio link <toolkit>`) tool execution across 1000+ apps, so this
+ * source needs no OAuth code of its own; Composio owns that entirely. */
+export async function connectComposioSource(name, options) {
+    const cliCommand = options.cliCommand ?? 'composio';
+    return {
+        name,
+        async loadTools() {
+            const tools = [];
+            for (const slug of options.slugs) {
+                const schema = await runCli(cliCommand, ['execute', slug, '--get-schema']);
+                const inputSchema = schema.inputSchema ?? {};
+                tools.push({
+                    name: `${name}_${slug}`,
+                    description: humanize(slug),
+                    input_schema: inputSchema,
+                    execute: async (input) => {
+                        const result = await runCli(cliCommand, ['execute', slug, '-d', JSON.stringify(input)]);
+                        if (result.successful === false || result.error) {
+                            throw new Error(`composio tool ${slug} failed: ${JSON.stringify(result.error ?? result)}`);
+                        }
+                        return result.data ?? result;
+                    },
+                });
+            }
+            return tools;
+        },
+        // Each call is its own subprocess — nothing held open between calls,
+        // so there's nothing to tear down. Kept for symmetry with sources
+        // that do hold a live connection (e.g. a future raw MCP client).
+        close: async () => { },
+    };
+}