larkin 0.4.8 → 0.4.10

package/README.md

@@ -87,6 +87,8 @@ Feishu clients do not reliably render Markdown links such as `[label](URL)` as c
 
 ## Setup and configuration
 
+Feishu (https://open.feishu.cn) and Lark (https://open.larksuite.com) are different platforms; `larkin setup` must be told which brand with `--tenant feishu|lark` or the interactive prompt before the authorization QR, and must never emit a `feishu.cn` host for a Lark tenant.
+
 During setup, a new Agent is offered Pi first, followed by Codex and Claude Code. Provider keys are stored only in the selected Agent's private provider directory, not in the ordinary Agent config. Setup also discovers every API-key and OAuth/subscription login exposed by the pinned official Pi registry and delegates those flows to Pi.
 
 Use `larkin pi-auth status` or `larkin pi-auth logout <provider>` to manage Pi auth. The builtin Pi runtime loads Larkin's two supported extensions inline: background subagents and the 60-second foreground bash timeout guard are enabled without writing extension files or arguments. A compatible external Pi installation keeps the existing explicit `-e` extension path.

package/dist/agent/context-prompt.cjs

@@ -16,7 +16,7 @@ const agent_cli_capabilities_js_1 = require("./agent-cli-capabilities.cjs");
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v20";
+exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v21";
 /**
  * Agent 间协作唤醒引导（issue #75）：纯文本 @ 不会产生飞书 mention 事件，
  * 必须由模型直接构造真实的 mention 元素；`--mention` 扩展参数已移除。
@@ -126,6 +126,7 @@ class ContextPromptBuilder {
             "## Feishu IM command map",
             "",
             `Use only the Larkin-owned \`${executable}\` command for Feishu. Bot identity, private configuration, and freshness are Runtime-bound; the wrapper delegates to the unmodified global official CLI. Use \`${executable} <command> --help\`, never invoke bare \`lark-cli\`, and never pass \`--agent\`, \`--as user\`, \`--profile\`, or \`--config-dir\`. If a command reports a missing scope, relay that error unchanged and ask the user to authorize it; do not bypass the scope boundary.`,
+            "If a platform URL must be shown, use the current Agent tenant host; never emit feishu.cn for a Lark tenant.",
             `Use the exact Inbox target for history reads. For \`thread:<chat_id>:<thread_id>\`, run \`${executable} im +threads-messages-list --thread <thread_id> --order desc --page-size 10 --no-reactions --json\`. For \`chat:<chat_id>\`, run \`${executable} im +chat-messages-list --chat-id <chat_id> --order desc --page-size 10 --no-reactions --json\`.`,
             "Successful history response messages are always at `data.messages`. Never use a chat-wide fallback for a thread target, never merge stderr with `2>&1` before parsing JSON, and never truncate structured output before parsing it.",
             "If the scoped history read fails or its schema is invalid, fail visibly. Do not reuse remembered or hard-coded text to make the task appear successful.",

package/dist/agent/context-prompt.mjs

@@ -13,7 +13,7 @@ import { agentCliPromptCapabilities } from "./agent-cli-capabilities.mjs";
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v20";
+export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v21";
 /**
  * Agent 间协作唤醒引导（issue #75）：纯文本 @ 不会产生飞书 mention 事件，
  * 必须由模型直接构造真实的 mention 元素；`--mention` 扩展参数已移除。
@@ -123,6 +123,7 @@ export class ContextPromptBuilder {
             "## Feishu IM command map",
             "",
             `Use only the Larkin-owned \`${executable}\` command for Feishu. Bot identity, private configuration, and freshness are Runtime-bound; the wrapper delegates to the unmodified global official CLI. Use \`${executable} <command> --help\`, never invoke bare \`lark-cli\`, and never pass \`--agent\`, \`--as user\`, \`--profile\`, or \`--config-dir\`. If a command reports a missing scope, relay that error unchanged and ask the user to authorize it; do not bypass the scope boundary.`,
+            "If a platform URL must be shown, use the current Agent tenant host; never emit feishu.cn for a Lark tenant.",
             `Use the exact Inbox target for history reads. For \`thread:<chat_id>:<thread_id>\`, run \`${executable} im +threads-messages-list --thread <thread_id> --order desc --page-size 10 --no-reactions --json\`. For \`chat:<chat_id>\`, run \`${executable} im +chat-messages-list --chat-id <chat_id> --order desc --page-size 10 --no-reactions --json\`.`,
             "Successful history response messages are always at `data.messages`. Never use a chat-wide fallback for a thread target, never merge stderr with `2>&1` before parsing JSON, and never truncate structured output before parsing it.",
             "If the scoped history read fails or its schema is invalid, fail visibly. Do not reuse remembered or hard-coded text to make the task appear successful.",

package/dist/app/cli.mjs

@@ -49,8 +49,8 @@ if (runtimeAgentAuthority && command === "comment")
 const commandHelp = {
     start: `Usage: larkin start [--agent <App ID> | --agents <App ID,...>]
 Start one foreground supervisor for the daemon and local dashboard, or reuse it.`,
-    setup: `Usage: larkin setup [--runtime <builtin-pi|external-pi|codex|claude>] [--provider <id> --api-key <key>]
-Run setup to create or connect a bot, configure its Agent, and attach it. Interactive terminals keep the guided flow; Agent-driven (non-TTY) runs default to builtin-pi and need --provider/--api-key (or --runtime external-pi).`,
+    setup: `Usage: larkin setup [--tenant feishu|lark] [--runtime <builtin-pi|external-pi|codex|claude>] [--provider <id> --api-key <key>]
+Run setup to create or connect a bot, configure its Agent, and attach it. Choose Feishu or Lark before the authorization QR (--tenant; default feishu). Interactive terminals keep the guided flow; Agent-driven (non-TTY) runs default to builtin-pi and need --provider/--api-key (or --runtime external-pi).`,
     status: `Usage: larkin status [--json]
 Show Agent configuration, bot identity, credentials, and connection status. Use --json for readiness automation.`,
     agents: `Usage: larkin agents [--json]

package/dist/app/runtime-agent-config.mjs

@@ -9,6 +9,7 @@ import { assertSecureBotsDirectory, readSecureBotCredential, validCredentialReco
 import { resolveOfficialLarkCli } from "./official-lark-cli.mjs";
 import { internalCommandSpec } from "./internal-command.mjs";
 import { assertAgentWorkspaceBound, larkChannelSourceConfigPath, larkChannelWorkspaceConfigPath, managedLarkCliEnv, } from "./agent-lark-cli-workspace.mjs";
+import { accountTenantFromOpenHost, openPlatformHost, } from "../feishu/platform-hosts.mjs";
 function assertSecureProfileDirectory(directory) {
     const stat = fs.lstatSync(directory);
     if (!stat.isDirectory() || stat.isSymbolicLink()
@@ -140,7 +141,7 @@ export function hydrateRuntimeAgent(configDir, agent) {
     return {
         ...agent,
         feishuAppSecret: credential.appSecret,
-        feishuDomain: credential.tenant === "lark" ? "https://open.larksuite.com" : "https://open.feishu.cn",
+        feishuDomain: openPlatformHost(credential.tenant),
         credentialRevision,
     };
 }
@@ -248,7 +249,7 @@ export function installRuntimeCommandShims(agent) {
     }
     return commandDir;
 }
-function sourceProjection(agent, env) {
+export function sourceProjection(agent, env) {
     const configDir = path.resolve(env.LARKIN_CONFIG_DIR || "");
     if (!configDir)
         throw new Error("LARKIN_CONFIG_DIR required for lark-channel source projection");
@@ -261,7 +262,7 @@ function sourceProjection(agent, env) {
         accounts: { app: {
                 id: agent.feishuAppId,
                 secret: { source: "exec", provider: "larkin-bot-credential", id: agent.feishuAppId },
-                tenant: agent.feishuDomain === "https://open.larksuite.com" ? "lark" : "feishu",
+                tenant: accountTenantFromOpenHost(agent.feishuDomain),
             } },
         secrets: { providers: { "larkin-bot-credential": {
                     source: "exec", command: provider.command, args: provider.args,
@@ -294,6 +295,9 @@ function validateSourceProjection(file, agent) {
         throw new Error("lark-channel source projection 不得包含 plaintext secret 字段");
     if (root.credentialRevision !== agent.credentialRevision)
         throw new Error(`Agent ${agent.agentId} lark-channel credential revision mismatch`);
+    if (app?.tenant !== accountTenantFromOpenHost(agent.feishuDomain)) {
+        throw new Error(`Agent ${agent.agentId} lark-channel source projection tenant mismatch`);
+    }
 }
 export function syncAgentProfile(agent, env, dependencies = {}) {
     const expected = path.join(path.resolve(env.LARKIN_CONFIG_DIR || ""), "state", "agents", agent.agentId, "lark-cli-config");

package/dist/app/setup.mjs

@@ -82,6 +82,11 @@ Options:
   --base-url <url>                      custom 端点（provider=custom 时必填；也可覆盖 preset 默认端点）
   --model <id>                          模型 ID；默认取 provider 预设。不同 runtime 的模型可用
                                           \`larkin model\` 查看 / 切换
+  --tenant feishu|lark                  授权二维码之前选择品牌。默认 feishu（accounts.feishu.cn /
+                                          https://open.feishu.cn）。Lark 用 --tenant lark
+                                          （accounts.larksuite.com / https://open.larksuite.com）。
+                                          交互式未指定时会先询问。飞书与 Lark 是不同平台，
+                                          Lark 租户不得使用 feishu.cn 主机。
 
 setup handles browser authorization, permission grants, credential storage, Agent configuration,
 and target-only hot attach. Each Agent is identified by its bot App ID: selecting the same bot reuses
@@ -152,6 +157,12 @@ export async function main() {
             registerArgs.push("--pi-distribution", normalizedRuntime.distribution);
     }
     registerArgs.push("--comment-subscription", OPT.commentSubscription);
+    if (has("--tenant")) {
+        const tenant = flag("--tenant");
+        if (tenant !== "feishu" && tenant !== "lark")
+            die("--tenant 只支持 feishu 或 lark");
+        registerArgs.push("--tenant", tenant === "lark" ? "lark" : "feishu");
+    }
     for (const name of ["--provider", "--api-key", "--base-url", "--model"]) {
         const value = flag(name);
         if (value)

package/dist/feishu/host-shell.cjs

@@ -61,6 +61,7 @@ const internal_command_js_1 = require("../app/internal-command.cjs");
 const agent_lark_cli_workspace_js_1 = require("../app/agent-lark-cli-workspace.cjs");
 const agent_readiness_js_1 = require("../app/agent-readiness.cjs");
 const document_comment_js_1 = require("./document-comment.cjs");
+const platform_hosts_js_1 = require("./platform-hosts.cjs");
 const PENDING_DOCUMENT_COMMENT_LIMIT = 256;
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -152,7 +153,7 @@ function loadAgents(env, testEventSource, larkinHome, reconcileAgentWorkspaceImp
             }
         }
         if (!testEventSource && (typeof candidate.feishuAppSecret !== "string" || !candidate.feishuAppSecret.trim()
-            || !["https://open.feishu.cn", "https://open.larksuite.com"].includes(String(candidate.feishuDomain)))) {
+            || !(0, platform_hosts_js_1.isOpenPlatformHost)(candidate.feishuDomain))) {
             throw new Error(`LARKIN_AGENTS_CONFIG Agent ${id} 缺少有效 channel 凭证/domain`);
         }
         const expectedWorkspace = node_path_1.default.join(larkinHome, "agents", id);
@@ -742,7 +743,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
         const channel = createLarkChannel({
             appId: agent.feishuAppId,
             appSecret: agent.feishuAppSecret,
-            domain: agent.feishuDomain || "https://open.feishu.cn",
+            domain: (0, platform_hosts_js_1.requireOpenDomain)(agent.feishuDomain),
             source: "larkin",
             policy: { dmMode: "open", requireMention: false, respondToMentionAll: true },
             // issue #88：关闭 SDK 的防抖批量合并（默认 600ms），逐条投递，
@@ -857,7 +858,7 @@ function createHostShell({ env = process.env, runtimeHost, channelPackage, event
             const channel = createLarkChannel({
                 appId: agent.feishuAppId,
                 appSecret: agent.feishuAppSecret,
-                domain: agent.feishuDomain || "https://open.feishu.cn",
+                domain: (0, platform_hosts_js_1.requireOpenDomain)(agent.feishuDomain),
                 source: "larkin",
                 policy: { dmMode: "open", requireMention: false, respondToMentionAll: true },
                 // issue #88：关闭 SDK 的防抖批量合并（默认 600ms），逐条投递，

package/dist/feishu/host-shell.mjs

@@ -21,6 +21,7 @@ import { processCommandToken } from "../app/internal-command.mjs";
 import { managedOfficialLarkCli } from "../app/agent-lark-cli-workspace.mjs";
 import { isChannelReconnecting, isRuntimeReadinessCurrent } from "../app/agent-readiness.mjs";
 import { documentCommentMessageId, documentCommentNoticeType, projectDocumentCommentEnvelope, resolveDocumentCommentContext, } from "./document-comment.mjs";
+import { isOpenPlatformHost, requireOpenDomain } from "./platform-hosts.mjs";
 const PENDING_DOCUMENT_COMMENT_LIMIT = 256;
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -112,7 +113,7 @@ function loadAgents(env, testEventSource, larkinHome, reconcileAgentWorkspaceImp
             }
         }
         if (!testEventSource && (typeof candidate.feishuAppSecret !== "string" || !candidate.feishuAppSecret.trim()
-            || !["https://open.feishu.cn", "https://open.larksuite.com"].includes(String(candidate.feishuDomain)))) {
+            || !isOpenPlatformHost(candidate.feishuDomain))) {
             throw new Error(`LARKIN_AGENTS_CONFIG Agent ${id} 缺少有效 channel 凭证/domain`);
         }
         const expectedWorkspace = path.join(larkinHome, "agents", id);
@@ -702,7 +703,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
         const channel = createLarkChannel({
             appId: agent.feishuAppId,
             appSecret: agent.feishuAppSecret,
-            domain: agent.feishuDomain || "https://open.feishu.cn",
+            domain: requireOpenDomain(agent.feishuDomain),
             source: "larkin",
             policy: { dmMode: "open", requireMention: false, respondToMentionAll: true },
             // issue #88：关闭 SDK 的防抖批量合并（默认 600ms），逐条投递，
@@ -817,7 +818,7 @@ export function createHostShell({ env = process.env, runtimeHost, channelPackage
             const channel = createLarkChannel({
                 appId: agent.feishuAppId,
                 appSecret: agent.feishuAppSecret,
-                domain: agent.feishuDomain || "https://open.feishu.cn",
+                domain: requireOpenDomain(agent.feishuDomain),
                 source: "larkin",
                 policy: { dmMode: "open", requireMention: false, respondToMentionAll: true },
                 // issue #88：关闭 SDK 的防抖批量合并（默认 600ms），逐条投递，

package/dist/feishu/platform-hosts.cjs

@@ -0,0 +1,49 @@
+"use strict";
+// Official Feishu vs Lark hosts from @larksuite/cli ResolveEndpoints
+// (open / accounts / applink) plus Open-host docs and console paths.
+// Do not add larkoffice.com or any unofficial host.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLATFORM_HOSTS = void 0;
+exports.parseLarkinTenant = parseLarkinTenant;
+exports.openPlatformHost = openPlatformHost;
+exports.registerAppAccountsHost = registerAppAccountsHost;
+exports.isOpenPlatformHost = isOpenPlatformHost;
+exports.requireOpenDomain = requireOpenDomain;
+exports.accountTenantFromOpenHost = accountTenantFromOpenHost;
+exports.PLATFORM_HOSTS = {
+    feishu: {
+        open: "https://open.feishu.cn",
+        accounts: "https://accounts.feishu.cn",
+        applink: "https://applink.feishu.cn",
+        docs: "https://open.feishu.cn/document",
+        console: "https://open.feishu.cn/app",
+    },
+    lark: {
+        open: "https://open.larksuite.com",
+        accounts: "https://accounts.larksuite.com",
+        applink: "https://applink.larksuite.com",
+        docs: "https://open.larksuite.com/document",
+        console: "https://open.larksuite.com/app",
+    },
+};
+function parseLarkinTenant(value) {
+    return value === "feishu" || value === "lark" ? value : null;
+}
+function openPlatformHost(tenant) {
+    return exports.PLATFORM_HOSTS[tenant].open;
+}
+function registerAppAccountsHost(tenant) {
+    // node-sdk registerApp.domain / larkDomain interpolate https://${host}
+    return new URL(exports.PLATFORM_HOSTS[tenant].accounts).host;
+}
+function isOpenPlatformHost(value) {
+    return value === exports.PLATFORM_HOSTS.feishu.open || value === exports.PLATFORM_HOSTS.lark.open;
+}
+function requireOpenDomain(value) {
+    if (isOpenPlatformHost(value))
+        return value;
+    throw new Error("missing or invalid Open Platform domain");
+}
+function accountTenantFromOpenHost(domain) {
+    return domain === exports.PLATFORM_HOSTS.lark.open ? "lark" : "feishu";
+}

package/dist/feishu/platform-hosts.mjs

@@ -0,0 +1,40 @@
+// Official Feishu vs Lark hosts from @larksuite/cli ResolveEndpoints
+// (open / accounts / applink) plus Open-host docs and console paths.
+// Do not add larkoffice.com or any unofficial host.
+export const PLATFORM_HOSTS = {
+    feishu: {
+        open: "https://open.feishu.cn",
+        accounts: "https://accounts.feishu.cn",
+        applink: "https://applink.feishu.cn",
+        docs: "https://open.feishu.cn/document",
+        console: "https://open.feishu.cn/app",
+    },
+    lark: {
+        open: "https://open.larksuite.com",
+        accounts: "https://accounts.larksuite.com",
+        applink: "https://applink.larksuite.com",
+        docs: "https://open.larksuite.com/document",
+        console: "https://open.larksuite.com/app",
+    },
+};
+export function parseLarkinTenant(value) {
+    return value === "feishu" || value === "lark" ? value : null;
+}
+export function openPlatformHost(tenant) {
+    return PLATFORM_HOSTS[tenant].open;
+}
+export function registerAppAccountsHost(tenant) {
+    // node-sdk registerApp.domain / larkDomain interpolate https://${host}
+    return new URL(PLATFORM_HOSTS[tenant].accounts).host;
+}
+export function isOpenPlatformHost(value) {
+    return value === PLATFORM_HOSTS.feishu.open || value === PLATFORM_HOSTS.lark.open;
+}
+export function requireOpenDomain(value) {
+    if (isOpenPlatformHost(value))
+        return value;
+    throw new Error("missing or invalid Open Platform domain");
+}
+export function accountTenantFromOpenHost(domain) {
+    return domain === PLATFORM_HOSTS.lark.open ? "lark" : "feishu";
+}

package/dist/runtime/pi-subagents-notification.mjs

@@ -0,0 +1,161 @@
+function escapeXml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function extractTag(content, tagName) {
+    const match = new RegExp(`<${tagName}>([\\s\\S]*?)</${tagName}>`).exec(content);
+    return match ? match[1].trim() : null;
+}
+/**
+ * Pi subagents emit terminal <status> as Done or a display label
+ * (Error: ..., Aborted (...), Stopped, Wrapped up (turn limit)).
+ * Raw tokens completed/error/aborted/stopped/steered/turn-limit are also accepted.
+ */
+const TERMINAL_STATUS_TOKENS = new Set([
+    "done",
+    "completed",
+    "error",
+    "aborted",
+    "stopped",
+    "steered",
+    "turn-limit",
+    "turn_limit",
+]);
+export function isCanonicalTerminalPiSubagentStatus(status) {
+    const normalized = status.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    if (TERMINAL_STATUS_TOKENS.has(normalized))
+        return true;
+    if (normalized.startsWith("error:") || normalized.startsWith("error "))
+        return true;
+    if (normalized.startsWith("aborted"))
+        return true;
+    if (normalized.startsWith("stopped"))
+        return true;
+    if (normalized.includes("turn limit") || normalized.includes("turn-limit") || normalized.includes("turn_limit")) {
+        return true;
+    }
+    if (normalized.includes("steered"))
+        return true;
+    return false;
+}
+function parseTaskNotificationBlock(block) {
+    const taskId = extractTag(block, "task-id");
+    const status = extractTag(block, "status");
+    const summary = extractTag(block, "summary");
+    const result = extractTag(block, "result");
+    if (!taskId || !status || !summary || !result)
+        return null;
+    if (!isCanonicalTerminalPiSubagentStatus(status))
+        return null;
+    return {
+        taskId,
+        toolUseId: extractTag(block, "tool-use-id") ?? undefined,
+        outputFile: extractTag(block, "output-file") ?? undefined,
+        status,
+        summary,
+        result,
+    };
+}
+function parseCanonicalNotificationContent(content) {
+    const blocks = [...content.matchAll(/<task-notification>([\s\S]*?)<\/task-notification>/g)]
+        .map((match) => match[1]);
+    if (blocks.length === 0)
+        return null;
+    const seen = new Set();
+    const notifications = [];
+    for (const block of blocks) {
+        const parsed = parseTaskNotificationBlock(block);
+        if (!parsed || seen.has(parsed.taskId))
+            continue;
+        seen.add(parsed.taskId);
+        notifications.push(parsed);
+    }
+    if (notifications.length === 0)
+        return null;
+    const taskIds = notifications.map((notification) => notification.taskId);
+    return { taskIds, notifications, content, key: taskIds.join("|") };
+}
+function collectCandidateContents(node, found = new Set()) {
+    const candidates = [];
+    const visit = (value) => {
+        if (value === null || value === undefined)
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+            return;
+        }
+        if (typeof value !== "object")
+            return;
+        const record = value;
+        if (record.customType === "subagent-notification" && typeof record.content === "string") {
+            if (!found.has(record.content)) {
+                found.add(record.content);
+                candidates.push(record.content);
+            }
+        }
+        else if (Array.isArray(record.content)) {
+            visit(record.content);
+        }
+        if (Array.isArray(record.messages))
+            visit(record.messages);
+        if (Array.isArray(record.parts))
+            visit(record.parts);
+    };
+    visit(node);
+    return candidates;
+}
+export function buildCanonicalPiSubagentNotificationContent(options) {
+    const status = options.status ?? "Done";
+    const summary = options.summary ?? `Agent ${JSON.stringify("Fixture")} completed`;
+    const result = options.result ?? "Fixture result.";
+    const totalTokens = options.totalTokens ?? 12;
+    const toolUses = options.toolUses ?? 1;
+    const durationMs = options.durationMs ?? 34;
+    return [
+        "<task-notification>",
+        `<task-id>${escapeXml(options.taskId)}</task-id>`,
+        options.toolUseId ? `<tool-use-id>${escapeXml(options.toolUseId)}</tool-use-id>` : null,
+        options.outputFile ? `<output-file>${escapeXml(options.outputFile)}</output-file>` : null,
+        `<status>${escapeXml(status)}</status>`,
+        `<summary>${escapeXml(summary)}</summary>`,
+        `<result>${escapeXml(result)}</result>`,
+        `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${toolUses}</tool_uses><duration_ms>${durationMs}</duration_ms></usage>`,
+        "</task-notification>",
+    ].filter(Boolean).join("\n");
+}
+export function buildCanonicalPiSubagentAssistantMessage(options) {
+    return {
+        role: "assistant",
+        content: [{
+                type: "custom",
+                customType: "subagent-notification",
+                content: buildCanonicalPiSubagentNotificationContent(options),
+            }],
+    };
+}
+export function extractCanonicalPiSubagentNotification(messages) {
+    const seen = new Set();
+    const notifications = [];
+    const contents = [];
+    for (const content of collectCandidateContents(messages)) {
+        const parsed = parseCanonicalNotificationContent(content);
+        if (!parsed)
+            continue;
+        contents.push(parsed.content);
+        for (const notification of parsed.notifications) {
+            if (seen.has(notification.taskId))
+                continue;
+            seen.add(notification.taskId);
+            notifications.push(notification);
+        }
+    }
+    if (notifications.length === 0)
+        return null;
+    const taskIds = notifications.map((notification) => notification.taskId);
+    return { taskIds, notifications, content: contents.join("\n"), key: taskIds.join("|") };
+}
+export function extractCanonicalPiSubagentCompletionKeyFromMessages(messages) {
+    return extractCanonicalPiSubagentNotification(messages)?.key ?? null;
+}

package/dist/runtime/runtime-adapters.mjs

@@ -10,6 +10,7 @@ import { BUNDLED_PI_VERSION, piAgentDirectory } from "./pi-provider-config.mjs";
 import { recordPiRuntimeArtifactProvenance } from "./pi-artifact-provenance.mjs";
 import { traceProcessBoundary } from "../platform/process-boundary-trace.mjs";
 import { resolvePiSubagentExtensionArg } from "./pi-subagent-injection.mjs";
+import { extractCanonicalPiSubagentCompletionKeyFromMessages } from "./pi-subagents-notification.mjs";
 import { resolvePiBashTimeoutExtensionArg } from "./pi-bash-timeout-injection.mjs";
 import { classifyRuntimePrerequisite, probeNativeRuntimeReadiness, providerAuthenticationFailureReadiness, RuntimePrerequisiteError, } from "./runtime-readiness.mjs";
 import { buildStrictProviderErrorInput, classifyStrictProviderError, INTERNAL_CONTEXT_WINDOW_PROJECTION_REASON, } from "./provider-error-classifier.mjs";
@@ -451,6 +452,8 @@ class PiSession extends EventSession {
     observedSubmitEpochs = new Set();
     observedAcceptedEpochs = new Set();
     observedCompletedEpochs = new Set();
+    observedBackgroundCompletionKeys = new Set();
+    pendingUnownedCompletionKeys = new Set();
     observedAgentEndEpochs = new Set();
     firstOutputObserved = false;
     toolCallOpen = false;
@@ -551,6 +554,8 @@ class PiSession extends EventSession {
             this.observedSubmitEpochs.clear();
             this.observedAcceptedEpochs.clear();
             this.observedCompletedEpochs.clear();
+            this.observedBackgroundCompletionKeys.clear();
+            this.pendingUnownedCompletionKeys.clear();
             this.observedAgentEndEpochs.clear();
             this.activeEpoch = null;
             this.settleArmedEpoch = null;
@@ -600,11 +605,25 @@ class PiSession extends EventSession {
                 this.observedCompletedEpochs.add(this.activeEpoch);
                 this.emitObservation("completed");
             }
+            const completionNotificationKey = extractCanonicalPiSubagentCompletionKeyFromMessages(event.messages);
+            if (completionNotificationKey
+                && this.activeEpoch === null
+                && !this.observedBackgroundCompletionKeys.has(completionNotificationKey)) {
+                // agent_end can still have an active Pi session. Prompting before
+                // unowned agent_settled is rejected as "Agent is already processing".
+                this.pendingUnownedCompletionKeys.add(completionNotificationKey);
+            }
         }
         else if (event?.type === "agent_settled") {
             const epoch = this.activeEpoch;
-            if (epoch === null || this.settleArmedEpoch !== epoch)
+            if (epoch === null) {
+                this.flushPendingUnownedCompletions();
+                return;
+            }
+            if (this.settleArmedEpoch !== epoch) {
+                this.flushPendingUnownedCompletions();
                 return;
+            }
             this.activeEpoch = null;
             this.settleArmedEpoch = null;
             const error = this.finalAssistantError;
@@ -645,6 +664,7 @@ class PiSession extends EventSession {
             this.observedAcceptedEpochs.delete(epoch);
             this.observedCompletedEpochs.delete(epoch);
             this.observedAgentEndEpochs.delete(epoch);
+            this.flushPendingUnownedCompletions();
         }
         else if (event?.type === "tool_execution_start") {
             if (!this.firstOutputObserved) {
@@ -672,6 +692,15 @@ class PiSession extends EventSession {
             this.emit({ type: "activity", activity: kind, text: String(event.assistantMessageEvent.delta) });
         }
     }
+    flushPendingUnownedCompletions() {
+        for (const completionKey of this.pendingUnownedCompletionKeys) {
+            if (this.observedBackgroundCompletionKeys.has(completionKey))
+                continue;
+            this.observedBackgroundCompletionKeys.add(completionKey);
+            this.emitObservation("completed", { completionKey });
+        }
+        this.pendingUnownedCompletionKeys.clear();
+    }
     emitObservation(phase, fields = {}) {
         const inputId = this.oldestOwnedInput();
         const observation = { type: "runtime-observation", runtime: "pi",
@@ -681,6 +710,8 @@ class PiSession extends EventSession {
             Object.defineProperty(observation, "sessionId", { value: this.sessionId, enumerable: false });
         if (inputId)
             Object.defineProperty(observation, "inputId", { value: inputId, enumerable: false });
+        if (fields.completionKey)
+            Object.defineProperty(observation, "completionKey", { value: fields.completionKey, enumerable: false });
         this.emit(observation);
     }
     oldestOwnedInput() {