@aragon-agent/core 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to `@aragon-agent/core` are documented here. Entries at
+`0.1.x` and earlier refer to the package by its former name, `@argon-agent/core`
+— those releases really were published under that name, so they are left as they
+were written.
+
+## 0.2.0
+
+### Breaking
+
+- **The package is renamed `@argon-agent/core` → `@aragon-agent/core`.** The
+  brand was always meant to be *Aragon*, matching AragonMesh; the missing `a`
+  was a typo that reached the registry. `@argon-agent/core` is deprecated and
+  receives no further releases.
+
+  Every subpath keeps its shape — only the scope changes:
+
+  ```diff
+  - import { Agent } from '@argon-agent/core';
+  + import { Agent } from '@aragon-agent/core';
+  - import type { LlmMessage } from '@argon-agent/core/llm/types';
+  + import type { LlmMessage } from '@aragon-agent/core/llm/types';
+  ```
+
+- **The exported alias `ArgonAgent` is now `AragonAgent`.** It remains an alias
+  of `Agent`, which is unchanged — code importing `Agent` needs no edit.
+
+### Added
+
+- **Skill system (pure-logic half).** New `src/skills/` module and a `./skills`
+  subpath export: `SkillRegistry`, `parseFrontmatter`,
+  `validateSkillFrontmatter`, `validateStagedSkill`, `renderSkillCatalog`,
+  `renderSkillBody`, `renderSkillInvocation`, `applySkillArguments`,
+  `suggestSkillNames`, `sanitizeForPromptBlock`, `createSkillTool`, and the
+  `SKILL_*` budget constants. The root runtime surface grows from 33 to 56
+  value exports; see `API.md`.
+- **`rankCatalogRecords(records, { usage, now })`** — orders the Level 1 catalog
+  by scope, then by usage recency and frequency, using integer buckets so the
+  result stays byte-reproducible. Invariant: called without a usage map it is
+  element-for-element identical to `catalogRecords()`, which is what keeps every
+  existing catalog snapshot valid.
+- **`createSkillFindTool(deps)` / `renderSkillFindResults(query, matched, opts)`**
+  — the `skill_find` tool and its rendering, for reaching skills that did not fit
+  in the catalog. Searches only the injected registry: no network, no
+  `activation: manual` skills, and an explicit refusal to invent an install
+  source when nothing matches. Same sanitisation and byte budget discipline as
+  the catalog (`SKILL_FIND_MAX_BYTES`).
+- Types `SkillIntegrity`, `SkillUsageStat`, `SkillUsageMap`, `SkillFindOptions`;
+  `SkillRecord.integrity`; optional `SkillManifestSource.resolvedRef` and
+  `SkillManifest.updatedAt` / `previousVersion` (additive — the manifest schema
+  version is deliberately unchanged so an older CLI still reads them).
+- All filesystem access goes through the injected `SkillHost` port, so the
+  package still imports no `node:*` builtin outside the one grandfathered
+  `node:crypto` in `llm/providers/google.ts`.
+- **Release tooling for the scope change.** `npm run verify:brand` derives the
+  list of files that would enter the tarball from `npm pack --dry-run --json`
+  and refuses the release if any of them still mentions the old brand — README
+  included, with only the four documented exceptions. It runs inside
+  `publish-latest.ps1` and cannot be skipped. `npm run preflight` answers "would
+  a real publish succeed?" before any version file is touched, and
+  `npm run verify:published` checks afterwards that the registry really serves
+  the renamed package, README and repository link included.
+
+### Changed
+
+- `no-host-coupling.test.ts` now also asserts that **no** file under `src/`
+  imports a `node:*` builtin, with a single documented allowlist entry and a
+  self-check so the assertion cannot pass vacuously. This guarantee was
+  previously assumed but never actually checked.
+- Added a repository-level PowerShell release workflow that versions, verifies,
+  and publishes Core before the dependent CLI, with dry-run rollback and
+  partial-release resume support.
+
+### Security
+
+- Every span of third-party text is passed through `sanitizeForPromptBlock()`
+  before it is concatenated into a tagged prompt block. Without it a skill
+  description containing `</available_skills>` could close the block and have
+  the text after it read as top-level system-prompt instructions.
+- All skill budgets are measured in UTF-8 **bytes**. A character-based budget
+  is ~3x under-counted for CJK text, which pushed results past `ToolExecutor`'s
+  100 000-byte ceiling and truncated the closing tag off the block.
+
+## 0.1.0
+
+Initial extraction of the ArgonAgent engine from the AragonMesh code base
+(`server/agent-core/`) into a standalone, publishable package.
+
+- Zero-coupling agent engine: LLM provider adapters (Anthropic, OpenAI,
+  Google), streaming, provider registry, model registry.
+- Tool system: typed tool definitions, registry, JSON-Schema validator (with
+  built-in fallback), executor.
+- Engine: multi-turn agent loop, message manager, steering queue, idle
+  watchdog.
+- Optional isolated-vm CodeAct sandbox (lazy-loaded).
+- Adds the `ArgonAgent` export as an alias of the `Agent` class.
+
+Publish-readiness (still part of the unreleased `0.1.0`):
+
+- Added `publishConfig.access:"public"` (required for scoped public publish),
+  a `prepublishOnly` build guard, and a package-directory `LICENSE`.
+- `files` now ships `CHANGELOG.md` alongside `dist`.
+- Added `typesVersions` so consumers on the legacy `moduleResolution:"node"`
+  can resolve the subpath type declarations.
+- Declared `sideEffects:false` (the barrel is pure re-exports) to aid
+  downstream tree-shaking.
+- Added discovery metadata: `keywords` / `author` / `repository` / `homepage`
+  / `bugs`.
+- Added a compile-checked `examples/minimal.ts` usage sample (not shipped in the
+  tarball).
+
+Reuse-verification harness (still part of the unreleased `0.1.0`):
+
+- Added `examples/consumer-smoke/run.mjs` + the `verify:dist` script: runs the
+  built `dist/` like an external consumer (Node package self-referencing →
+  `exports` map → `dist/`), driving `ArgonAgent` end-to-end with an offline stub
+  provider and asserting every `exports` subpath resolves at runtime.
+- Added a public-API contract snapshot (`src/__tests__/public-api.test.ts` +
+  `API.md`) that freezes the runtime export surface against silent drift.
+- Added a `no-host-coupling` guard test that forbids host-repo imports
+  (`@server/`, `@shared/`, `@/`, out-of-package `../../../`) and legacy-brand
+  leakage on the public surface.
+- Added a publish guard: `scripts/check-publishable.mjs` (wired into
+  `prepublishOnly`) hard-blocks publishing while the `<ORG>` placeholder remains
+  in `package.json`, and `scripts/stamp-org.mjs` replaces it in one command.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AragonAgent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# @aragon-agent/core
+
+The publishable **AragonAgent** engine: a zero-coupling, dependency-injected
+TypeScript agent runtime.
+
+## Requirements
+
+- **Node.js ≥ 18** — the engine relies on the global `fetch` / `AbortController`
+  built into Node 18+.
+- **ESM-only** — this package ships as native ES modules (`"type": "module"`).
+  Consume it with `import`; it cannot be `require()`-d from CommonJS.
+- **Optional native deps** — `ajv` and `isolated-vm` are `optionalDependencies`:
+  the package works without them (a built-in validator fallback is used, and the
+  sandbox modules are lazy-loaded). Install `isolated-vm` only if you use the
+  `@aragon-agent/core/sandbox/*` CodeAct sandbox.
+
+## Install
+
+```bash
+npm install @aragon-agent/core
+# optional — only if you use the isolated-vm CodeAct sandbox:
+npm install isolated-vm
+```
+
+`ajv` and `isolated-vm` are **optional dependencies**:
+
+- `ajv` — used by the tool param validator when present; a built-in fallback
+  validator is used otherwise.
+- `isolated-vm` — used only by the `@aragon-agent/core/sandbox/*` modules, which
+  are lazy-loaded and never imported from the package root (`isolated-vm` is
+  incompatible with some embedded V8 runtimes such as Electron's).
+
+## Usage
+
+```ts
+import { AragonAgent, getProviderRegistry, initProviders } from '@aragon-agent/core';
+
+initProviders();
+
+const agent = new AragonAgent({
+  systemPrompt: 'You are a coding agent.',
+  model: { providerId: 'anthropic', modelId: 'claude-...', baseUrl: '...' },
+  tools: [],
+  providerRegistry: getProviderRegistry(),
+  getApiKey: () => process.env.ANTHROPIC_API_KEY,
+});
+
+await agent.prompt('Hello');
+```
+
+`AragonAgent` is an alias of the engine's `Agent` class.
+
+A complete, type-checked version of this snippet (a dummy tool + provider setup
++ agent construction) lives in [`examples/minimal.ts`](./examples/minimal.ts).
+It is compile-only (never hits the network) and is not part of the published
+tarball.
+
+## Entry points
+
+| Import path                      | Contents                                  |
+| -------------------------------- | ----------------------------------------- |
+| `@aragon-agent/core`              | Full barrel (engine, LLM, tools, types).  |
+| `@aragon-agent/core/llm/types`    | LLM message / streaming / model types.    |
+| `@aragon-agent/core/llm/providers`| Provider registry + `streamLLM`/`completeLLM`. |
+| `@aragon-agent/core/tools/types`  | Tool system types.                        |
+| `@aragon-agent/core/tools/helpers`| `textResult` / `errorResult` / `defineTool`. |
+| `@aragon-agent/core/sandbox/*`    | Optional isolated-vm CodeAct sandbox.     |
+
+## Build
+
+```bash
+npm run build   # tsc → dist/*.js + *.d.ts
+npm test        # vitest (smoke + public-api contract + no-host-coupling guard)
+```
+
+## Verifying reuse
+
+`npm test` and `examples/minimal.ts` only prove the package **compiles**. To
+prove the built `dist/` can actually be **run** by an external consumer:
+
+```bash
+npm run verify:dist   # build dist/, then run examples/consumer-smoke/run.mjs
+```
+
+`run.mjs` imports this package **by its own name** (`@aragon-agent/core`) via
+Node's *package self-referencing*, so Node resolves it through
+`package.json#exports` → `./dist/index.js` — the same `(exports map + NodeNext +
+.js extension)` path that an external project's `npm install @aragon-agent/core`
+hits, **without** placing the package in `node_modules`. It injects an offline
+stub LLM provider, runs one `AragonAgent.prompt()` turn end-to-end (zero network),
+and asserts the `exports` subpaths all resolve at runtime. Success prints
+`[consumer-smoke] OK`.
+
+For the unambiguous "another project installs and reuses it" check (which also
+covers running **without** the optional `ajv` / `isolated-vm` deps), see the
+pack-into-a-fresh-project golden verification in
+[`examples/consumer-smoke/README.md`](./examples/consumer-smoke/README.md).
+
+The runtime public-API surface is frozen by `src/__tests__/public-api.test.ts`
+and documented for humans in [`API.md`](./API.md); a `no-host-coupling` test
+keeps the package free of host-repo imports and legacy brand leakage.
+
+## Publishing
+
+This package is published to the public npm registry. Run the release from the
+**package directory** so the package-level `prepublishOnly` hook fires and a
+fresh `dist/` is built:
+
+```bash
+cd packages/core
+npm run build                 # produce dist/
+npm pack --dry-run --json     # inspect the tarball file list (no upload)
+npm publish                   # publishConfig.access:"public" is baked in
+```
+
+(From the repo root you can equivalently run `npm publish -w packages/core`.)
+
+Notes:
+
+- **`publishConfig.access` is set to `"public"`**, so no `--access public` flag
+  is needed — scoped packages would otherwise default to restricted/private.
+- **The publishing account must own the `@aragon-agent` npm scope/org** before
+  the first publish. Even with `access:"public"`, publishing under a scope you
+  do not own fails with 403/404. Create the `@aragon-agent` org on npmjs (or
+  switch to a scope your account owns and rename the package accordingly).
+- **`files` is the load-bearing whitelist.** The repo's `.gitignore` ignores
+  `dist/`, but npm's `files: ["dist", "CHANGELOG.md"]` takes precedence and
+  ships the built output. Do not "simplify" the `files` field away, or the
+  published tarball will be empty. `npm pack --dry-run --json` should always
+  list `dist/index.js`.
+- Repository metadata points to
+  `https://github.com/xdrshjr/AragonAgent`.
+
+  If the repository moves, use the helper script or update
+  `repository` / `homepage` / `bugs` before publishing:
+
+  ```bash
+  node scripts/stamp-org.mjs <org>     # or: ARAGON_REPO_ORG=<org> node scripts/stamp-org.mjs
+  node scripts/check-publishable.mjs   # exits non-zero if the placeholder remains in package.json
+  ```
+
+  `prepublishOnly` runs `check-publishable.mjs` before the build, so any publish
+  attempt with an unstamped placeholder is hard-blocked automatically.
+
+## License
+
+MIT.

package/dist/engine/agent-loop.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Core Agent Loop — the heart of the engine.
+ *
+ * Implements the LLM call -> stream consumption -> tool execution -> loop
+ * cycle, with steering/follow-up checkpoints and optional CodeAct code
+ * block detection and execution.
+ */
+import type { ThinkingLevel } from '../llm/types.js';
+import type { ProviderRegistry } from '../llm/providers/index.js';
+import type { ToolExecutor } from '../tools/executor.js';
+import type { ToolRegistry } from '../tools/registry.js';
+import type { AgentEvent } from '../types.js';
+import type { MessageManager } from './message-manager.js';
+import type { MessageQueueManager } from './steering.js';
+import type { CodeActSandbox } from '../sandbox/types.js';
+export type { CodeActSandbox };
+export type { ExecuteResult as CodeActResult } from '../sandbox/types.js';
+export interface ModelRef {
+    providerId: string;
+    modelId: string;
+    baseUrl?: string;
+}
+export interface AgentLoopContext {
+    providerRegistry: ProviderRegistry;
+    toolRegistry: ToolRegistry;
+    toolExecutor: ToolExecutor;
+    messageManager: MessageManager;
+    messageQueueManager: MessageQueueManager;
+    getApiKey: (providerId: string) => string | undefined;
+    emit: (event: AgentEvent) => void;
+    sandbox?: CodeActSandbox;
+    model: ModelRef;
+    systemPrompt: string;
+    thinkingLevel?: ThinkingLevel;
+    /** Maximum output tokens per LLM call. `undefined` = use provider default. */
+    maxTokens?: number;
+    signal: AbortSignal;
+    timeouts: {
+        llmCallTimeout: number;
+        toolTimeout: number;
+        codeTimeout: number;
+    };
+}
+/**
+ * Run the Agent loop until completion, steering exhaustion, or abort.
+ *
+ * This function is invoked by `Agent.prompt()` and `Agent.continue()`.
+ * It mutates the messageManager and emits events through the provided
+ * context.  All errors are caught — the caller (Agent) is responsible
+ * for emitting `agent_end` in its own finally block.
+ */
+export declare function runAgentLoop(ctx: AgentLoopContext): Promise<void>;

package/dist/engine/agent-loop.js

@@ -0,0 +1,260 @@
+/**
+ * Core Agent Loop — the heart of the engine.
+ *
+ * Implements the LLM call -> stream consumption -> tool execution -> loop
+ * cycle, with steering/follow-up checkpoints and optional CodeAct code
+ * block detection and execution.
+ */
+// ---------------------------------------------------------------------------
+// CodeAct regex for extracting ```execute-js blocks
+// ---------------------------------------------------------------------------
+const CODEACT_REGEX = /```execute-js\n([\s\S]*?)```/g;
+/**
+ * Extract all execute-js code blocks from assistant text.
+ */
+function extractCodeBlocks(text) {
+    const blocks = [];
+    let match;
+    // Reset lastIndex for safety when reusing the regex.
+    CODEACT_REGEX.lastIndex = 0;
+    while ((match = CODEACT_REGEX.exec(text)) !== null) {
+        const code = match[1];
+        if (code && code.trim().length > 0) {
+            blocks.push(code);
+        }
+    }
+    return blocks;
+}
+/**
+ * Collect all text content from an AssistantMessage's content blocks.
+ */
+function getAssistantText(message) {
+    return message.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('\n');
+}
+/**
+ * Collect tool call blocks from an AssistantMessage.
+ */
+function getToolCalls(message) {
+    return message.content.filter((b) => b.type === 'tool_call');
+}
+// ---------------------------------------------------------------------------
+// runAgentLoop
+// ---------------------------------------------------------------------------
+/**
+ * Run the Agent loop until completion, steering exhaustion, or abort.
+ *
+ * This function is invoked by `Agent.prompt()` and `Agent.continue()`.
+ * It mutates the messageManager and emits events through the provided
+ * context.  All errors are caught — the caller (Agent) is responsible
+ * for emitting `agent_end` in its own finally block.
+ */
+export async function runAgentLoop(ctx) {
+    while (!ctx.signal.aborted) {
+        // ----- Steering checkpoint (before LLM call) -----
+        if (ctx.messageQueueManager.hasSteering()) {
+            const steeringMessages = ctx.messageQueueManager.drainSteering();
+            for (const text of steeringMessages) {
+                const userMsg = { role: 'user', content: text, timestamp: Date.now() };
+                ctx.messageManager.push(userMsg);
+            }
+            // Continue to LLM call with injected steering messages.
+        }
+        // ----- Turn start -----
+        ctx.emit({ type: 'turn_start' });
+        // ----- Build LLM request -----
+        const apiKey = ctx.getApiKey(ctx.model.providerId);
+        if (!apiKey) {
+            throw new Error(`No API key available for provider "${ctx.model.providerId}". ` +
+                'Please configure the API key in Settings.');
+        }
+        const toolDefs = ctx.toolRegistry.toToolDefinitions();
+        const messages = ctx.messageManager.getAll();
+        // ----- Stream LLM response -----
+        let assistantMessage;
+        let usage = { inputTokens: 0, outputTokens: 0 };
+        const stream = ctx.providerRegistry.stream(ctx.model.providerId, {
+            model: ctx.model.modelId,
+            messages,
+            systemPrompt: ctx.systemPrompt,
+            tools: toolDefs.length > 0 ? toolDefs : undefined,
+            apiKey,
+            baseUrl: ctx.model.baseUrl,
+            signal: ctx.signal,
+            thinkingLevel: ctx.thinkingLevel,
+            maxTokens: ctx.maxTokens,
+        });
+        for await (const event of stream) {
+            if (ctx.signal.aborted)
+                break;
+            // Forward every stream event to subscribers.
+            ctx.emit({ type: 'message_update', streamEvent: event });
+            if (event.type === 'done') {
+                assistantMessage = event.message;
+                usage = event.usage;
+            }
+            else if (event.type === 'error') {
+                throw event.error;
+            }
+        }
+        if (ctx.signal.aborted)
+            break;
+        if (!assistantMessage) {
+            // Stream ended without a 'done' event — treat as an error.
+            throw new Error('LLM stream ended without producing a done event');
+        }
+        // ----- Turn end -----
+        ctx.emit({ type: 'turn_end', message: assistantMessage, usage });
+        ctx.messageManager.push(assistantMessage);
+        // ----- Process tool calls -----
+        const toolCalls = getToolCalls(assistantMessage);
+        const hasToolCalls = toolCalls.length > 0;
+        let steeringInterrupted = false;
+        if (hasToolCalls) {
+            // Steering checkpoint: if steering arrived during the LLM call,
+            // skip tool execution and inject steering messages instead.
+            if (ctx.messageQueueManager.hasSteering()) {
+                const steeringMessages = ctx.messageQueueManager.drainSteering();
+                for (const text of steeringMessages) {
+                    const userMsg = { role: 'user', content: text, timestamp: Date.now() };
+                    ctx.messageManager.push(userMsg);
+                }
+                // Loop continues — LLM will see the steering messages.
+                continue;
+            }
+            // Execute each tool call sequentially.
+            for (const toolCall of toolCalls) {
+                if (ctx.signal.aborted)
+                    break;
+                // Check steering between individual tool executions.
+                if (ctx.messageQueueManager.hasSteering()) {
+                    // Inject remaining tool results as errors so LLM knows they were skipped.
+                    const remainingCalls = toolCalls.slice(toolCalls.indexOf(toolCall));
+                    for (const skipped of remainingCalls) {
+                        ctx.messageManager.push({
+                            role: 'tool_result',
+                            toolCallId: skipped.toolCallId,
+                            content: 'Tool execution skipped due to steering interrupt.',
+                            isError: true,
+                        });
+                    }
+                    // Inject steering messages.
+                    const steeringMessages = ctx.messageQueueManager.drainSteering();
+                    for (const text of steeringMessages) {
+                        const userMsg = { role: 'user', content: text, timestamp: Date.now() };
+                        ctx.messageManager.push(userMsg);
+                    }
+                    steeringInterrupted = true;
+                    break;
+                }
+                ctx.emit({
+                    type: 'tool_execution_start',
+                    toolCallId: toolCall.toolCallId,
+                    toolName: toolCall.toolName,
+                    args: toolCall.args,
+                });
+                const execResult = await ctx.toolExecutor.execute(toolCall.toolCallId, toolCall.toolName, toolCall.args, ctx.signal);
+                ctx.emit({
+                    type: 'tool_execution_end',
+                    toolCallId: toolCall.toolCallId,
+                    toolName: toolCall.toolName,
+                    result: execResult.result,
+                    isError: execResult.isError,
+                    duration: execResult.duration,
+                });
+                // Build and push tool result message.
+                const resultText = execResult.result.content
+                    .map((c) => (c.type === 'text' ? c.text : `[image: ${c.mediaType}]`))
+                    .join('\n');
+                ctx.messageManager.push({
+                    role: 'tool_result',
+                    toolCallId: toolCall.toolCallId,
+                    content: resultText,
+                    isError: execResult.isError,
+                });
+            }
+            if (ctx.signal.aborted)
+                break;
+            // If steering interrupted tool execution, skip CodeAct and continue
+            // to the next loop iteration where the LLM sees the steering messages.
+            if (steeringInterrupted)
+                continue;
+        }
+        // ----- CodeAct code block detection -----
+        const assistantText = getAssistantText(assistantMessage);
+        const codeBlocks = extractCodeBlocks(assistantText);
+        let hasCodeBlocks = codeBlocks.length > 0 && ctx.sandbox != null;
+        if (hasCodeBlocks && ctx.sandbox) {
+            for (const code of codeBlocks) {
+                if (ctx.signal.aborted)
+                    break;
+                ctx.emit({ type: 'code_execution_start', code, language: 'javascript' });
+                const startTime = Date.now();
+                let output = '';
+                let error;
+                try {
+                    const result = await ctx.sandbox.execute(code, {
+                        timeout: ctx.timeouts.codeTimeout,
+                        signal: ctx.signal,
+                    });
+                    // Build output from console entries and return value.
+                    const parts = [];
+                    for (const entry of result.consoleOutput) {
+                        const prefix = entry.level === 'log' ? '' : `[${entry.level}] `;
+                        parts.push(`${prefix}${entry.args.join(' ')}`);
+                    }
+                    if (result.returnValue !== undefined) {
+                        parts.push(`=> ${result.returnValue}`);
+                    }
+                    output = parts.join('\n');
+                    error = result.error?.message;
+                }
+                catch (err) {
+                    error = err instanceof Error ? err.message : String(err);
+                }
+                const duration = Date.now() - startTime;
+                ctx.emit({ type: 'code_execution_end', output, error, duration });
+                // Inject code execution result as a user message.
+                let resultContent = '[Code Execution Result]\n';
+                if (output) {
+                    resultContent += `Output: ${output}\n`;
+                }
+                if (error) {
+                    resultContent += `---\nError: ${error}\n`;
+                }
+                if (!output && !error) {
+                    resultContent += 'Output: (no output)\n';
+                }
+                const codeResultMsg = {
+                    role: 'user',
+                    content: resultContent,
+                    timestamp: Date.now(),
+                };
+                ctx.messageManager.push(codeResultMsg);
+            }
+            if (ctx.signal.aborted)
+                break;
+            // After code execution, continue the loop so LLM can react to results.
+            continue;
+        }
+        // ----- Exit or follow-up checkpoint -----
+        if (!hasToolCalls && !hasCodeBlocks) {
+            // No tools and no code blocks — check for follow-up messages.
+            if (ctx.messageQueueManager.hasFollowUp()) {
+                const followUpMessages = ctx.messageQueueManager.drainFollowUp();
+                for (const text of followUpMessages) {
+                    const userMsg = { role: 'user', content: text, timestamp: Date.now() };
+                    ctx.messageManager.push(userMsg);
+                }
+                // Continue loop with follow-up messages.
+                continue;
+            }
+            // No more work — exit the loop.
+            break;
+        }
+        // If we had tool calls (and they were executed), continue the loop
+        // so the LLM can process tool results.
+    }
+}