loopengine 0.0.18 → 0.0.21

package/PROTOCOL.md

@@ -0,0 +1,245 @@
+# The loopengine event protocol
+
+**Status:** v1 · **Schema:** [`protocol/loop-event.schema.json`](protocol/loop-event.schema.json)
+
+One `runAgent()` turn emits an ordered sequence of typed `LoopEvent`
+objects. That sequence — not any particular transport — is the actual
+contract. The SSE stream, the plain HTTP response, and the CLI's `--json`
+mode are three different ways of delivering the exact same objects; a
+client written against one of them can switch to another without
+changing how it interprets a single event.
+
+This document specifies that sequence: every event's shape, when it
+fires, what's guaranteed about ordering, and how each transport carries
+it. If you're building a UI or integration against loopengine in any
+language — not just TypeScript — this is what to implement against
+instead of reverse-engineering `core/loop-events.ts`.
+
+## Stability
+
+This is v1. Within v1:
+
+- **Additive is safe to rely on being additive.** A new event `type` may
+  be introduced; a new optional field may be added to an existing event.
+  A consumer that ignores unrecognized `type` values and unrecognized
+  fields will never break.
+- **These are breaking changes**, and won't happen inside v1: renaming or
+  removing an event `type`; renaming, removing, or changing the meaning
+  of an existing field; turning an optional field required; changing an
+  established transport's framing (SSE's `event: <type>\ndata: <json>`,
+  the plain response's `events` array, or `--json`'s one-object-per-line
+  NDJSON).
+- A breaking change ships as v2, documented as a new section here, not a
+  silent edit to this one.
+
+## Lifecycle
+
+Every event has a `type` field, which doubles as the discriminant and,
+on the SSE transport, the literal frame name. Two families:
+
+- **Engine events** — emitted by `runAgent()` itself, identically
+  regardless of which transport is carrying them.
+- **Adapter events** — synthesized by the HTTP/CLI adapter around a turn
+  (`session`, `approval:pending`, `question:pending`, `done`, `error`).
+  `runAgent()` itself has no notion of sessions or HTTP-level failures;
+  these exist because a real caller needs them.
+
+A turn always starts with `session` (streamed) and always ends with
+exactly one `done`. The only real branch is the ActAuth Gate's decision
+on each requested tool call:
+
+```
+session → budget:check → assistant:text? → actauth:decision
+                                                       │
+                              ┌────────────────────────┴───────────────────────┐
+                              │ allow                                          │ deny
+                              ▼                                                ▼
+                   [approval:pending first,             tool:result (statusText: "Denied.")
+                    if the rule said "ask"]              — no execution, no tool:started.
+                              │                           Any sibling call already approved
+                              ▼                           in the same batch gets loop:skipped
+                        tool:started                      + its own tool:result ("Skipped.")
+                              ▼                                                │
+                       toollane:result                                        │
+                              ▼                                                │
+                     tool:result (Approved./Error.)                           │
+                              │                                                │
+                              └─────────────────┬──────────────────────────────┘
+                                                 ▼
+                          loops back to budget:check for the
+                          next tool call, or the model's next turn,
+                          until exactly one of:
+                          loop:done / loop:max_turns / loop:denied
+                                                 ▼
+                                               done
+```
+
+`approval:pending`/`question:pending` are the only events without a
+fixed position in that diagram — they can arrive at any point a tool call
+is being evaluated. At most one is ever pending at a time (the Gate
+evaluates one call before starting the next), so a consumer never needs
+to track more than one open decision per turn.
+
+## Event catalog
+
+### Engine — emitted by `runAgent()`
+
+| `type` | Fires | Fields |
+|---|---|---|
+| `budget:check` | Once per model call, before it | `action: 'ok'\|'nudge'\|'over_hard_limit'`, `usedTokens`, `budgetTokens`, `ratio`, `nudge?` |
+| `prompt:compaction` | A prompt was rejected as too large | `from`, `to` (message-array lengths, not tokens) |
+| `assistant:text` | The model's "I'll do X" preamble alongside a tool call | `text` |
+| `actauth:decision` | Once per requested tool call | `tool`, `decision: 'allow'\|'ask'\|'deny'`, `reason` |
+| `tool:started` | The instant a call is decided, before it runs | `id`, `tool`, `args`, `detailText` |
+| `tool:result` | A call resolves — allowed, denied, or skipped | `id`, `tool`, `args?`, `detailText?`, `statusText` |
+| `toollane:result` | ToolLane's own raw outcome, alongside `tool:result` | `name`, `summary` |
+| `skill:loaded` | A `Skill` block resolved to a real skill body | `skill` |
+| `loop:skipped` | A sibling call never ran because another was denied | `name`, `deniedTools` |
+| `loop:max_turns` | Hit `config.maxTurns` with no final answer | `maxTurns` |
+| `loop:denied` | A human denied a call — the turn stops | `deniedTools` |
+| `loop:done` | A genuine finish — no more tool calls | `text` |
+
+### Adapter — synthesized around a turn
+
+| `type` | Fires | Fields |
+|---|---|---|
+| `session` | First event of every streamed turn | `sessionId` |
+| `approval:pending` | A tool call needs a live human decision | `id`, `tool`, `args`, `scope: {tenant,environment,agent}`, `reason`, `requestedAt` |
+| `question:pending` | The `ask_user` tool raised a real question | `id`, `question`, `options?`, `agent`, `sessionId?`, `requestedAt` |
+| `done` | The turn is over — wraps `loop:done`/`max_turns`/`denied` | `text`, `stopReason?: 'max_turns'\|'denied'` |
+| `error` | Something failed after the response was already committed | `error` |
+
+Full field types, `required` vs optional, and `additionalProperties: false`
+enforcement live in [`protocol/loop-event.schema.json`](protocol/loop-event.schema.json)
+— the table above is a summary, the schema is the source of truth.
+
+## Transports
+
+### SSE stream — live, frame by frame
+
+```
+POST /agents/:name/messages/stream
+content-type: application/json
+
+{"message": "order A-1001 arrived broken, can you refund it?"}
+```
+
+Each frame is `event: <type>\ndata: <json>\n\n`, `<json>` being the whole
+event object (`type` included, redundantly with the frame name — parse
+whichever is more convenient):
+
+```
+event: tool:started
+data: {"type":"tool:started","id":"call_1","tool":"issue_refund","args":{"orderId":"A-1001"},"detailText":"matched rule 'refunds-need-approval'"}
+
+event: approval:pending
+data: {"type":"approval:pending","id":"3f9c...","tool":"issue_refund","args":{"orderId":"A-1001"},"scope":{"tenant":"default","environment":"production","agent":"customer-service"},"reason":"matched rule 'refunds-need-approval'","requestedAt":"2026-08-28T01:34:32.193Z"}
+```
+
+### Plain HTTP — one request, the full array
+
+```
+POST /agents/:name/messages
+content-type: application/json
+
+{"message": "..."}
+```
+
+Two response shapes, both carrying the identical `events` array a
+streamed version of the same turn would have delivered live:
+
+**200 — the turn finished:**
+
+```json
+{
+  "text": "Refunded $42.00 to your original payment method.",
+  "sessionId": "5a83c6b4-...",
+  "events": [ /* every LoopEvent this turn produced, in order */ ],
+  "stopReason": "max_turns"
+}
+```
+
+`stopReason` is present only for a synthetic finish (`max_turns`/`denied`).
+
+**202 — the turn needs a decision right now:**
+
+```json
+{
+  "pending": true,
+  "type": "approval",
+  "id": "3f9c...",
+  "sessionId": "5a83c6b4-...",
+  "tool": "issue_refund",
+  "args": { "orderId": "A-1001" },
+  "scope": { "tenant": "default", "environment": "production", "agent": "customer-service" },
+  "reason": "matched rule 'refunds-need-approval'",
+  "approveUrl": "/approvals/3f9c.../approve",
+  "denyUrl": "/approvals/3f9c.../deny",
+  "events": [ /* everything so far */ ],
+  "statusUrl": "/agents/customer-service/sessions/5a83c6b4-..."
+}
+```
+
+(`type: "question"` carries `question`/`options`/`answerUrl` instead.)
+
+### CLI — one JSON object per line
+
+```
+loopengine run customer-service --json "order A-1001 arrived broken, can you refund it?"
+```
+
+```
+{"type":"session","sessionId":"5a83c6b4-..."}
+{"type":"budget:check","action":"ok","usedTokens":2,"budgetTokens":8000,"ratio":0.00025}
+{"type":"tool:started","id":"call_1","tool":"issue_refund", ...}
+{"type":"done","text":"Refunded $42.00..."}
+```
+
+Every line is a complete `LoopEvent`, pipeable straight into `jq` or
+anything else that reads NDJSON. Without `--json`, stdout stays
+human-readable (just the final answer) and events go to stderr instead.
+
+### Resolving a pending item
+
+```
+POST /approvals/:id/approve      POST /approvals/:id/deny
+POST /questions/:id/answer   {"answer": "..."}
+```
+
+All three return the exact same two-shape family as plain
+`POST /messages` above (200 done, or 202 the *next* pending item, if the
+turn needed another decision) — a caller can treat send → approve/deny/
+answer → approve/deny/answer → ... as one uniform loop regardless of
+which endpoint produced the response.
+
+## Validating against the schema
+
+```js
+import Ajv2020 from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats' // schema uses format: 'date-time'
+import schema from './protocol/loop-event.schema.json' with { type: 'json' }
+
+const ajv = new Ajv2020({ strict: true })
+addFormats(ajv)
+const validate = ajv.compile(schema)
+validate(event) // true/false; validate.errors on failure
+```
+
+The schema is hand-maintained alongside `core/loop-events.ts`, not
+generated from it — a PR that changes one without the other is
+incomplete. It's plain JSON Schema (draft 2020-12), so it works from any
+language with a validator, not just JavaScript.
+
+## Reference implementations
+
+- **`core/client.ts`** — the framework-agnostic TypeScript client this
+  spec was extracted from: SSE parsing, the plain-request helpers,
+  approve/deny/answer. Re-exported through the package's own entry point.
+- **`ui-examples/react/`**, **`ui-examples/vue/`** — a hook/composable
+  and a chat component each, built on `core/client.ts`, rendering
+  `approval:pending`/`question:pending` as real UI.
+
+Implementing this protocol in another language means reproducing what
+`core/client.ts` does: parse whichever transport you chose into
+`LoopEvent` objects per this schema, and drive your own UI or logic off
+`type`.

package/README.md

@@ -4,7 +4,7 @@
 
 LoopEngine is a runtime for building AI agents: a persona, a set of tools,
 and permission rules, run through a transparent ReAct loop. No chain DSL,
-no hidden control flow — `run-agent.ts` is a single function you can read
+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
@@ -37,7 +37,7 @@ npx create-loopengine@latest my-agents
 cd my-agents
 npm install
 cp .env.example .env   # fill in ANTHROPIC_API_KEY
-npm run dev             # HTTP server on :8787
+npm run dev             # HTTP server on :8787 — same as `npx loopengine dev`
 ```
 
 This scaffolds a standalone project — its own repo, with `loopengine` as
@@ -96,7 +96,7 @@ working examples.
 
 ### 1. The Loop
 
-`run-agent.ts` is the whole engine — a single, readable ReAct loop with no
+`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.
@@ -338,6 +338,37 @@ starting an anonymous session). Without it, the caller just supplies a
 
 ## Running an agent
 
+`adapters/cli.ts` and `adapters/http.ts` are files your own scaffolded
+project owns (see "Quick start" above), not something hidden inside the
+`loopengine` package — run them directly with `tsx`, or through shorter
+`loopengine` commands that just call the same files for you:
+
+```bash
+npx loopengine run customer-service --session s1 "order A-1001 arrived broken"
+npx loopengine run customer-service --session s1 --input "order A-1001 arrived broken"
+npx loopengine serve   # HTTP server on :8787
+npx loopengine dev     # same server, restarts on file changes (tsx watch)
+```
+
+`--session <id>` is just an arbitrary string you pick — `s1` above isn't
+special, it's only a label. Omit it entirely for a fresh, one-off
+conversation each call; reuse the same value on a later call to continue
+that exact conversation (the id is printed to stderr if you omit it, so
+you can capture it for next time). `--input "<message>"` is an
+alternative to the trailing positional message, for scripts that build
+the argument list programmatically and would rather not depend on the
+message always being the last argument.
+
+`run`/`serve`/`dev` are thin wrappers, not a separate implementation —
+each shells out to your project's own `adapters/cli.ts` or
+`adapters/http.ts` via `npx tsx` (so it's always *your* copy that runs,
+edits included, resolved from your project's own `node_modules`), and
+fails with a clear message pointing at `create-loopengine` if that file
+doesn't exist yet. `.env` is loaded automatically for all three,
+equivalent to passing `--env-file-if-exists=.env` to `tsx` yourself.
+
+The same thing, spelled out without the wrapper:
+
 **CLI:**
 
 ```bash
@@ -372,6 +403,14 @@ into the playground and config page below.
 that same loop-step event stream render live 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
+[`PROTOCOL.md`](PROTOCOL.md) for the full `LoopEvent` catalog, the SSE/
+plain-HTTP/CLI transport bindings, and a JSON Schema
+(`protocol/loop-event.schema.json`) any language can validate against.
+`core/client.ts` and the `ui-examples/react`/`ui-examples/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
@@ -402,8 +441,8 @@ testing), export your own `createModelCall(): ModelCall` instead.
 | Package | Responsibility |
 |---|---|
 | [`actauth`](https://www.npmjs.com/package/actauth) | Permission gating (allow/ask/deny) with human-approval hooks |
-| [`contextclip`](https://www.npmjs.com/package/contextclip) | Context-window budget tracking |
-| [`reflowkit`](https://www.npmjs.com/package/reflowkit) | Retries prompt-too-long / truncated-output failures |
+| `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) |
 | [`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 |

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

@@ -0,0 +1,25 @@
+---
+name: composio-large-outputs
+description: How to retrieve a gateway tool's real output when its result says storedInFile is true instead of returning the data inline.
+---
+
+# Gateway tools with a large result
+
+Some gateway tools (Composio-sourced ones in particular) return a small
+pointer object instead of their real output when the actual result is
+too large to return inline:
+
+```
+{
+  "successful": true,
+  "storedInFile": true,
+  "tokenCount": 10234,
+  "outputFilePath": "/tmp/.../SOME_TOOL_OUTPUT_xxxxx.json"
+}
+```
+
+When you see `storedInFile: true` in a tool result, the real data is
+**not** in that object — it's in the file at `outputFilePath`. Call
+`system_read_file` with that exact path to retrieve the actual content
+before answering. Don't guess at an answer, summarize from the pointer
+alone, or claim you don't have the data — read the file first.

package/dist/{cli.d.ts → bin/cli.d.ts}

@@ -5,19 +5,39 @@ export declare class AgentExistsError extends Error {
 }
 export declare class AgentNotFoundError extends Error {
 }
-export declare function agentIndexTemplate(name: string): string;
+export declare class AgentModelError extends Error {
+}
+type Provider = 'anthropic' | 'openai' | 'deepseek';
+export interface AgentTemplateOptions {
+    systemPrompt?: string;
+    model?: {
+        provider: Provider;
+        model?: string;
+    };
+}
+/** Generates agents/<name>/index.ts's real content. `options` is
+ * entirely optional and defaults to exactly what this template always
+ * wrote before it existed ('You are ...', anthropic/claude-sonnet-5) —
+ * `loopengine add-agent <name>` (which never passes it) produces
+ * byte-identical output to before this existed. openai/deepseek have no
+ * default model (only anthropic's is optional — see AgentModelConfig's
+ * own doc comment), so scaffoldAgent validates a model name was given
+ * for those rather than this function silently writing a wrong one. */
+export declare function agentIndexTemplate(name: string, options?: AgentTemplateOptions, importSpecifier?: string): string;
 /** Same shape as agentIndexTemplate, plus `toolDescription` — the one
  * field a subagent needs that a top-level agent doesn't. run-agent.ts's
  * loadSubagentAsTools wraps this config with agentAsTool, which throws
  * without a real toolDescription: it's what the parent agent's model
  * reads to decide when to delegate here, and systemPrompt (instructions
  * for this agent itself) isn't a substitute. See agent-as-tool.ts. */
-export declare function subagentIndexTemplate(name: string): string;
+export declare function subagentIndexTemplate(name: string, importSpecifier?: string): string;
 /** Writes agents/<name>/index.ts under baseDir and returns its path.
  * Only that one file — tools, rules, and skillsDirs are left to their
  * smart defaults (see AgentConfig's own doc comments), the same as the
- * README's own "simplest possible agent" example. */
-export declare function scaffoldAgent(baseDir: string, name: string): Promise<string>;
+ * README's own "simplest possible agent" example. `options` (systemPrompt,
+ * model) is entirely optional — see agentIndexTemplate's own doc comment
+ * for the defaults used when omitted. */
+export declare function scaffoldAgent(baseDir: string, name: string, options?: AgentTemplateOptions): Promise<string>;
 /** Writes <parentDir>/subagents/<name>/index.ts under baseDir and
  * returns its path, where <parentDir> is `parent` resolved by
  * resolveParentDir — the folder convention run-agent.ts's
@@ -29,3 +49,4 @@ export declare function scaffoldAgent(baseDir: string, name: string): Promise<st
  * scaffoldAgent already covers. Nesting more than one level is just
  * `parent` itself being a path — see resolveParentDir. */
 export declare function scaffoldSubagent(baseDir: string, parent: string, name: string): Promise<string>;
+export {};

package/dist/{cli.js → bin/cli.js}

@@ -9,7 +9,7 @@
 // these stay thin wrappers around those files rather than a built-in
 // runner/server this package hides inside itself.
 import { realpathSync } from 'node:fs';
-import { access, mkdir, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -20,13 +20,61 @@ export class AgentExistsError extends Error {
 }
 export class AgentNotFoundError extends Error {
 }
-export function agentIndexTemplate(name) {
-    return `import type { AgentConfig } from 'loopengine'
+export class AgentModelError extends Error {
+}
+const MODEL_ENV_VAR = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    deepseek: 'DEEPSEEK_API_KEY',
+};
+// Escapes a value for safe interpolation into a single-quoted TS string
+// literal in generated code — an operator-supplied systemPrompt (from
+// the admin UI's Create new agent form, say) containing a literal quote
+// or backslash would otherwise produce invalid, or silently different,
+// generated TypeScript.
+function tsStringLiteral(value) {
+    return "'" + value.replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'";
+}
+/** 'loopengine' for a real consumer project — the only thing that ever
+ * resolves once this package is genuinely installed as a dependency. A
+ * checkout of this repo itself has no such install (see this repo's own
+ * git history around the reverted self-link attempt: pointing
+ * node_modules/loopengine back at itself collides with tsc trying to
+ * write dist/ while also reading it as an input), so a file scaffolded
+ * *into this repo* — an agent created via `loopengine dev`'s admin UI
+ * while hacking on loopengine itself, say — needs the same internal
+ * alias every hand-maintained demo agent here already uses instead.
+ * Detected by baseDir's own package.json name rather than a flag the
+ * caller has to remember to pass, so this can never drift out of sync
+ * with which project is actually being scaffolded into. */
+async function configImportSpecifier(baseDir) {
+    try {
+        const raw = await readFile(path.join(baseDir, 'package.json'), 'utf8');
+        const pkg = JSON.parse(raw);
+        return pkg.name === 'loopengine' ? '#core/agent-config.js' : 'loopengine';
+    }
+    catch {
+        return 'loopengine';
+    }
+}
+/** Generates agents/<name>/index.ts's real content. `options` is
+ * entirely optional and defaults to exactly what this template always
+ * wrote before it existed ('You are ...', anthropic/claude-sonnet-5) —
+ * `loopengine add-agent <name>` (which never passes it) produces
+ * byte-identical output to before this existed. openai/deepseek have no
+ * default model (only anthropic's is optional — see AgentModelConfig's
+ * own doc comment), so scaffoldAgent validates a model name was given
+ * for those rather than this function silently writing a wrong one. */
+export function agentIndexTemplate(name, options = {}, importSpecifier = 'loopengine') {
+    const systemPrompt = options.systemPrompt?.trim() || 'You are ...';
+    const provider = options.model?.provider ?? 'anthropic';
+    const modelName = options.model?.model?.trim() || (provider === 'anthropic' ? 'claude-sonnet-5' : '');
+    return `import type { AgentConfig } from '${importSpecifier}'
 
 export const config: AgentConfig = {
   name: '${name}',
-  systemPrompt: 'You are ...',
-  model: { provider: 'anthropic', model: 'claude-sonnet-5' }, // reads ANTHROPIC_API_KEY
+  systemPrompt: ${tsStringLiteral(systemPrompt)},
+  model: { provider: '${provider}', model: ${tsStringLiteral(modelName)} }, // reads ${MODEL_ENV_VAR[provider]}
 }
 `;
 }
@@ -36,8 +84,8 @@ export const config: AgentConfig = {
  * without a real toolDescription: it's what the parent agent's model
  * reads to decide when to delegate here, and systemPrompt (instructions
  * for this agent itself) isn't a substitute. See agent-as-tool.ts. */
-export function subagentIndexTemplate(name) {
-    return `import type { AgentConfig } from 'loopengine'
+export function subagentIndexTemplate(name, importSpecifier = 'loopengine') {
+    return `import type { AgentConfig } from '${importSpecifier}'
 
 export const config: AgentConfig = {
   name: '${name}',
@@ -50,18 +98,24 @@ export const config: AgentConfig = {
 /** Writes agents/<name>/index.ts under baseDir and returns its path.
  * Only that one file — tools, rules, and skillsDirs are left to their
  * smart defaults (see AgentConfig's own doc comments), the same as the
- * README's own "simplest possible agent" example. */
-export async function scaffoldAgent(baseDir, name) {
+ * README's own "simplest possible agent" example. `options` (systemPrompt,
+ * model) is entirely optional — see agentIndexTemplate's own doc comment
+ * for the defaults used when omitted. */
+export async function scaffoldAgent(baseDir, name, options = {}) {
     if (!NAME_PATTERN.test(name)) {
         throw new AgentNameError(`Agent name must be lowercase, alphanumeric, hyphen-separated (e.g. "weather-agent") — got "${name}"`);
     }
+    const provider = options.model?.provider ?? 'anthropic';
+    if (provider !== 'anthropic' && !options.model?.model?.trim()) {
+        throw new AgentModelError(`A model name is required for provider '${provider}' — only anthropic has a default (claude-sonnet-5).`);
+    }
     const dir = path.join(baseDir, 'agents', name);
     const indexPath = path.join(dir, 'index.ts');
     if (await pathExists(indexPath)) {
         throw new AgentExistsError(`agents/${name}/index.ts already exists — pick a different name or edit it directly.`);
     }
     await mkdir(dir, { recursive: true });
-    await writeFile(indexPath, agentIndexTemplate(name));
+    await writeFile(indexPath, agentIndexTemplate(name, options, await configImportSpecifier(baseDir)));
     return indexPath;
 }
 /** Resolves `parent` — a single agent name, or a `/`-joined path of
@@ -105,7 +159,7 @@ export async function scaffoldSubagent(baseDir, parent, name) {
         throw new AgentExistsError(`A subagent named '${name}' already exists under '${parent}' (${indexPath}) — pick a different name or edit it directly.`);
     }
     await mkdir(dir, { recursive: true });
-    await writeFile(indexPath, subagentIndexTemplate(name));
+    await writeFile(indexPath, subagentIndexTemplate(name, await configImportSpecifier(baseDir)));
     return indexPath;
 }
 async function pathExists(p) {
@@ -130,8 +184,32 @@ async function pathExists(p) {
 function runTsx(args) {
     return new Promise((resolve) => {
         const child = spawn('npx', ['tsx', ...args], { cwd: process.cwd(), stdio: 'inherit' });
-        child.on('exit', (code) => resolve(code ?? 1));
-        child.on('error', () => resolve(1));
+        // `stdio: 'inherit'` with no `detached` puts this child in the same
+        // foreground process group as this process itself — so a terminal's
+        // Ctrl+C delivers SIGINT to *both* at once, not just to this process
+        // for it to relay. Node's default disposition for an unhandled
+        // SIGINT/SIGTERM is to terminate immediately — without a listener,
+        // this process would die right then, before ever observing the
+        // child's own 'exit' below. That's a real bug, not cosmetic: this
+        // process is the shell's *direct* child, so the shell returns control
+        // as soon as it exits — but the child (tsx watch, itself possibly
+        // still killing *its* own child, adapters/http.ts) can still be alive
+        // for a moment after, orphaned but still attached to the same TTY.
+        // A plain no-op listener is enough to opt out of that default
+        // immediate-termination behavior — the child already gets the same
+        // signal directly (same process group), nothing needs forwarding —
+        // so this just keeps this process alive long enough to actually see
+        // the child finish, and exit in step with it instead of ahead of it.
+        const noop = () => { };
+        process.on('SIGINT', noop);
+        process.on('SIGTERM', noop);
+        function settle(result) {
+            process.off('SIGINT', noop);
+            process.off('SIGTERM', noop);
+            resolve(result);
+        }
+        child.on('exit', (code) => settle(code ?? 1));
+        child.on('error', () => settle(1));
     });
 }
 /** run/serve/dev all delegate to a file the *project* owns (created by
@@ -203,17 +281,38 @@ async function main() {
     // adapters/cli.ts's own contract (see its own header comment), not a
     // REPL. `rest` after `<agent>` is forwarded through as-is (--session,
     // the message, and any future flag that file grows), so this wrapper
-    // never needs to change in step with adapters/cli.ts's own arg parsing.
+    // never needs to change in step with adapters/cli.ts's own arg parsing
+    // — except --input, which is this wrapper's own convenience flag, not
+    // adapters/cli.ts's: that file only understands --agent/--session plus
+    // one trailing positional message (see its own parseArgs, which joins
+    // every non-flag arg back into one string), so --input's value is
+    // translated into that positional form before forwarding, rather than
+    // taught to adapters/cli.ts itself. Exists for callers building the
+    // arg list programmatically, where getting a trailing positional's
+    // exact position right (after --session, after --agent, ...) is easy
+    // to get wrong; an explicit flag has no position to get wrong.
     if (command === 'run') {
         const [agent, ...forward] = rest;
         if (!agent) {
             console.error('Usage: loopengine run <agent> [--session <id>] "<message>"');
+            console.error('       loopengine run <agent> [--session <id>] --input "<message>"');
             process.exitCode = 1;
             return;
         }
         if (!(await requireAdapterFile('adapters/cli.ts')))
             return;
-        process.exitCode = await runTsx(['--env-file-if-exists=.env', 'adapters/cli.ts', '--agent', agent, ...forward]);
+        let finalArgs = forward;
+        const inputIndex = forward.indexOf('--input');
+        if (inputIndex !== -1) {
+            const message = forward[inputIndex + 1];
+            if (message === undefined) {
+                console.error('--input requires a value.');
+                process.exitCode = 1;
+                return;
+            }
+            finalArgs = [...forward.slice(0, inputIndex), ...forward.slice(inputIndex + 2), message];
+        }
+        process.exitCode = await runTsx(['--env-file-if-exists=.env', 'adapters/cli.ts', '--agent', agent, ...finalArgs]);
         return;
     }
     // Serves every registered agent at once (adapters/http.ts has no
@@ -234,10 +333,26 @@ async function main() {
     // read fresh off disk every call regardless (no restart needed for
     // those even under plain `serve`) — this is for the TS source itself:
     // a new tool file, an edited AgentConfig, ...
+    //
+    // --include 'agents/*/index.ts' is deliberately narrow, not a blanket
+    // 'agents/**' — tsx watch on its own only tracks the actual ES module
+    // graph, so a *new* agents/<name>/index.ts (e.g. from the admin UI's
+    // "Create new agent," or from `loopengine add-agent`) wouldn't
+    // otherwise trigger a restart at all: core/agent-registry.ts discovers
+    // agents once via a top-level `readdirSync` (see discover-agents.ts),
+    // not an import, so tsx's watcher has no static edge to that new file
+    // until this flag adds one. A wider 'agents/**' would also match
+    // gateway-tools.yml/actauth.yml/skills/*.md — restarting the whole
+    // server (dropping in-flight sessions) on every admin-UI edit to
+    // those, which is exactly the "no restart needed" behavior this repo
+    // went out of its way to build for them elsewhere. Confirmed live
+    // (both directions) before landing this: editing gateway-tools.yml
+    // under this exact glob triggers no restart; adding a new
+    // agents/<name>/index.ts does.
     if (command === 'dev') {
         if (!(await requireAdapterFile('adapters/http.ts')))
             return;
-        process.exitCode = await runTsx(['watch', '--env-file-if-exists=.env', 'adapters/http.ts', ...rest]);
+        process.exitCode = await runTsx(['watch', '--include', 'agents/*/index.ts', '--env-file-if-exists=.env', 'adapters/http.ts', ...rest]);
         return;
     }
     console.error('Usage: loopengine add-agent <name>');

package/dist/{agent-as-tool.d.ts → core/agent-as-tool.d.ts}

@@ -1,5 +1,5 @@
-import type { AgentConfig, ToolDefinition } from '#agent-config.js';
-import { type ModelCall } from '#run-agent.js';
+import type { AgentConfig, ToolDefinition } from '#core/agent-config.js';
+import { type ModelCall } from '#core/run-agent.js';
 /** `createModelCall` is a factory, not a shared instance — the same
  * `AgentModule.createModelCall` contract discover-agents.ts already
  * uses, so each call to the returned tool gets its own ModelCall rather

package/dist/{agent-as-tool.js → core/agent-as-tool.js}

@@ -1,4 +1,4 @@
-import { runAgent } from '#run-agent.js';
+import { runAgent } from '#core/run-agent.js';
 /** `createModelCall` is a factory, not a shared instance — the same
  * `AgentModule.createModelCall` contract discover-agents.ts already
  * uses, so each call to the returned tool gets its own ModelCall rather