@armadra/agent 0.6.6 → 0.6.7

package/CHANGELOG.md

@@ -5,6 +5,13 @@ English · [简体中文](CHANGELOG.zh-CN.md)
 > This file is in English starting with 0.6.0. Release notes for 0.1 through 0.5.1 are in Chinese in
 > [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md). New entries go into both files.
 
+## 0.6.7 (2026-10-03)
+
+- **A host runner with id `ama` is used**: when the host registers a runner for `ama` via `HostApi.runners.provide`
+  (for example another ama node on an Armadra canvas), `task(agent="ama")` now goes to it instead of being unknown; without
+  one nothing changes, and the built-in types (`general` / `explore` / `plan`) are always ama sub-sessions. Docs:
+  docs/agents.md.
+
 ## 0.6.6 (2026-10-03)
 
 - **Local search hints**: when both `grep` and `glob` are directly available, the system prompt's rules gain one line

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,12 @@
 
 > 从 0.6.0 起 [CHANGELOG.md](CHANGELOG.md) 为英文，本文件保留中文记录（0.1–0.5.1 的完整历史在此）。新条目两份都要加。
 
+## 0.6.7（2026-10-03）
+
+- **宿主注入的 `ama` runner 生效**：宿主经 `HostApi.runners.provide` 注入 id 为 `ama` 的 runner（如 Armadra 画布上另一个
+  ama 节点）时，`task(agent="ama")` 交给它；没注入时行为不变，内置类型（`general` / `explore` / `plan`）始终是 ama 子会话。
+  文档：docs/agents.md。
+
 ## 0.6.6（2026-10-03）
 
 - **本地检索提示**：`grep` 与 `glob` 都直接可用时，系统提示的规则节多一句「先 grep / glob 定位再 read，不要猜路径」；`grep` /

package/dist/agents/external.d.ts

@@ -2,7 +2,8 @@
  * 外部 Agent 接入 `task(agent=…)`（docs/wave5-plan.md §5.3–§5.5、§7.3、§7.6，D13、D15、D17）。[W5-EG]
  *
  * - 名字：`claude` / `codex` / `acp:<program>` / 驱动表里的其它 id（`gemini` …，`ama` 除外——那是子会话
- *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id。启动时 PATH 上找得到的
+ *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id（宿主注入的 `ama` 在类型里的 runner
+ *   名是 `host:ama`，交给宿主；没注入时 `ama` 照旧不是外部 Agent）。启动时 PATH 上找得到的
  *   claude / codex 与已注入的宿主 runner 登记进类型目录（进 task 工具描述）；其余按需解析（不进描述，
  *   描述在会话内字节不变）。
  * - 每个主会话一个 {@link ExternalAgents}：审批接 `requestApproval`（只走 broker 链，不经 gateToolCall
@@ -34,6 +35,11 @@ export declare const externalTesting: {
 export declare function isExternalSpec(name: string): boolean;
 /** 外部 CLI 的类型（`task(agent="claude")`）。 */
 export declare function externalDefinition(spec: string): AgentDefinition;
+/**
+ * 宿主注入的 id 恰为 `ama` 的 runner（画布上另一个 ama 节点）在类型里的 runner 名。裸 `ama` 是子会话
+ * 类型的 runner 名（注册表按它起子会话），不能共用；名字仍是 `ama`，`task(agent="ama")` 照常解析。
+ */
+export declare const HOST_AMA_RUNNER = "host:ama";
 export declare function hostDefinition(runner: HostRunner): AgentDefinition;
 /** 只查 PATH（不起进程）：候选链里任一程序在 PATH 上。 */
 export declare function externalOnPath(spec: string, env: NodeJS.ProcessEnv): boolean;

package/dist/agents/external.js

@@ -2,7 +2,8 @@
  * 外部 Agent 接入 `task(agent=…)`（docs/wave5-plan.md §5.3–§5.5、§7.3、§7.6，D13、D15、D17）。[W5-EG]
  *
  * - 名字：`claude` / `codex` / `acp:<program>` / 驱动表里的其它 id（`gemini` …，`ama` 除外——那是子会话
- *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id。启动时 PATH 上找得到的
+ *   类型的 runner 名；ama 自己经 ACP 用 `acp:ama`）/ 宿主注入的 runner id（宿主注入的 `ama` 在类型里的 runner
+ *   名是 `host:ama`，交给宿主；没注入时 `ama` 照旧不是外部 Agent）。启动时 PATH 上找得到的
  *   claude / codex 与已注入的宿主 runner 登记进类型目录（进 task 工具描述）；其余按需解析（不进描述，
  *   描述在会话内字节不变）。
  * - 每个主会话一个 {@link ExternalAgents}：审批接 `requestApproval`（只走 broker 链，不经 gateToolCall
@@ -58,8 +59,17 @@ function definition(name, runner, description, source) {
 export function externalDefinition(spec) {
     return definition(spec, spec, `External ${labelOf(spec)} CLI (its own login, model and permission policy; full instructions in prompt).`, "builtin");
 }
+/**
+ * 宿主注入的 id 恰为 `ama` 的 runner（画布上另一个 ama 节点）在类型里的 runner 名。裸 `ama` 是子会话
+ * 类型的 runner 名（注册表按它起子会话），不能共用；名字仍是 `ama`，`task(agent="ama")` 照常解析。
+ */
+export const HOST_AMA_RUNNER = "host:ama";
+/** 宿主 runner id → 类型里的 runner 名。 */
+function hostRunnerName(id) {
+    return id === "ama" ? HOST_AMA_RUNNER : id;
+}
 export function hostDefinition(runner) {
-    return definition(runner.id, runner.id, runner.description, "host");
+    return definition(runner.id, hostRunnerName(runner.id), runner.description, "host");
 }
 /** 只查 PATH（不起进程）：候选链里任一程序在 PATH 上。 */
 export function externalOnPath(spec, env) {
@@ -207,8 +217,16 @@ export class SessionExternalAgents {
     runner(agent) {
         if (agent.runner === "ama")
             return undefined;
-        const spec = agent.runner;
+        // 宿主注入的 `ama` 走宿主；宿主已注销时报不可用，不退回自起（驱动表里也有一个 ama）。
+        // 宿主 id 不在 AgentRunnerSpec 的字面量里（见 definition），按字符串比
+        const runnerName = agent.runner;
+        const hostAma = runnerName === HOST_AMA_RUNNER;
+        const spec = hostAma ? "ama" : agent.runner;
         const host = this.wiring.hostRunners?.get(spec);
+        if (hostAma && host === undefined) {
+            const error = new AmaError("agent_host_only", `"ama" was provided by the host and is no longer available`);
+            return { id: spec, start: () => Promise.reject(error) };
+        }
         let inner;
         try {
             inner = this.agents.resolve(spec);

package/dist/bundle/ama.cjs

@@ -41,7 +41,7 @@ var AMA_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    AMA_VERSION = true ? "0.6.6" : readPackageVersion();
+    AMA_VERSION = true ? "0.6.7" : readPackageVersion();
   }
 });
 
@@ -33541,8 +33541,11 @@ function externalDefinition(spec2) {
     "builtin"
   );
 }
+function hostRunnerName(id) {
+  return id === "ama" ? HOST_AMA_RUNNER : id;
+}
 function hostDefinition(runner) {
-  return definition(runner.id, runner.id, runner.description, "host");
+  return definition(runner.id, hostRunnerName(runner.id), runner.description, "host");
 }
 function externalOnPath(spec2, env) {
   const found = candidatesFor(spec2);
@@ -33594,7 +33597,7 @@ function mergeAgentInfos(base4, external) {
   }
   return out;
 }
-var import_node_crypto14, LISTED_EXTERNAL_AGENTS, NO_AGENT_PROBE_ENV, externalTesting, ExternalTaskHandle, infoCache, SessionExternalAgents;
+var import_node_crypto14, LISTED_EXTERNAL_AGENTS, NO_AGENT_PROBE_ENV, externalTesting, HOST_AMA_RUNNER, ExternalTaskHandle, infoCache, SessionExternalAgents;
 var init_external = __esm({
   "src/agents/external.ts"() {
     "use strict";
@@ -33611,6 +33614,7 @@ var init_external = __esm({
     LISTED_EXTERNAL_AGENTS = ["claude", "codex"];
     NO_AGENT_PROBE_ENV = "AMA_NO_AGENT_PROBE";
     externalTesting = {};
+    HOST_AMA_RUNNER = "host:ama";
     ExternalTaskHandle = class {
       constructor(inner, reopen) {
         this.inner = inner;
@@ -33689,8 +33693,17 @@ var init_external = __esm({
       /** 注册表的 `runners(agent)`：ama 子会话类型返回 undefined。 */
       runner(agent) {
         if (agent.runner === "ama") return void 0;
-        const spec2 = agent.runner;
+        const runnerName = agent.runner;
+        const hostAma = runnerName === HOST_AMA_RUNNER;
+        const spec2 = hostAma ? "ama" : agent.runner;
         const host = this.wiring.hostRunners?.get(spec2);
+        if (hostAma && host === void 0) {
+          const error2 = new AmaError(
+            "agent_host_only",
+            `"ama" was provided by the host and is no longer available`
+          );
+          return { id: spec2, start: () => Promise.reject(error2) };
+        }
         let inner;
         try {
           inner = this.agents.resolve(spec2);

package/docs/agents.md

@@ -259,7 +259,7 @@ ama 能以各 CLI 自己的账户、模型与权限策略驱动外部编码 Agen
 
 ### 嵌入宿主
 
-有宿主（`--host` 或 profile 的 `host`，如嵌入 Armadra）时 ama **不自己启动外部 CLI**：内置外部 Agent 一律不可用，不写进 task 描述，`task(agent="claude")` 以「由宿主提供」失败；只有宿主经 `HostApi.runners.provide(runner)` 注入的 runner 可用，它以同一个 `task(agent=<id>)` 入口出现，同名时替换内置的。`create()` 时已注入的 runner 写进 task 描述（`- <id>: <description>`），之后注入的也能用但不进描述。runner 的 `start` 收到 `prompt`、`cwd`、`mode`（父会话当前模式）、`taskId`、`signal`、`onEvent`；不经首次确认。
+有宿主（`--host` 或 profile 的 `host`，如嵌入 Armadra）时 ama **不自己启动外部 CLI**：内置外部 Agent 一律不可用，不写进 task 描述，`task(agent="claude")` 以「由宿主提供」失败；只有宿主经 `HostApi.runners.provide(runner)` 注入的 runner 可用，它以同一个 `task(agent=<id>)` 入口出现，同名时替换内置的。`create()` 时已注入的 runner 写进 task 描述（`- <id>: <description>`），之后注入的也能用但不进描述。runner 的 `start` 收到 `prompt`、`cwd`、`mode`（父会话当前模式）、`taskId`、`signal`、`onEvent`；不经首次确认。宿主注入的 runner id 也可以是 `ama`（例如画布上另一个 ama 节点）：`task(agent="ama")` 交给宿主，不起子会话；没注入时 `ama` 照旧不是可用类型，内置类型（`general` / `explore` / `plan`）始终是 ama 子会话。
 
 **在 Armadra 画布终端里直接运行 ama（没有 `--host`）**：此时 ama 按独立模式工作，自己启动的外部 Agent 是这个终端节点里的子进程，不会出现在画布上，也不经连线授权；需要让多个 Agent 在画布上协同，就在画布上连线 Agent 节点，或以宿主模式嵌入 ama。终端带着该节点的身份变量（`ARMADRA_NODE_ID`、`ARMADRA_SESSION_ID`、Hook 端点、`ARMADRA_CANVAS_CONTROL` 等），ama 起子进程时一律剥离（askpass 除外），否则 Armadra 装在 Claude / Codex 上的 Hook 会把子 Agent 的事件记到这个节点名下。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armadra/agent",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "A coding and coordination agent that runs standalone or embedded in Armadra",
   "type": "module",
   "keywords": [