@selesai/code 0.13.38 → 0.13.40

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
+## [0.13.39] - 2026-10-02
+
+### Changed
+- **`/tokenin usage` shows the account balance.** It queries `/tokenin/account/me/balance` and shows available credit (plan, PAYG, debt), active plan credit used, and plan expiry; a 404 falls back to the LiteLLM `/key/info` quota view.
+- **The `researcher` subagent uses `web_explore`** from the bundled `pi-web-agent` extension instead of `pi-web-access` tools; `pi-web-agent` registers a builtin-agent augmentation so foreground `researcher` children load it.
+- **Graft CLI floor raised to 0.21** (`MIN_GRAFT_VERSION` 0.21.0, install spec `@nanonets/graft@^0.21`).
+
 ## [0.13.38] - 2026-10-01
 
 ### Changed

package/dist/core/intercom-rpc.d.ts

@@ -0,0 +1,135 @@
+import type { RpcObservationScope } from "./subagent-rpc.ts";
+import type { Attachment, BrokerMessage, DeliveryDetails, Message, SessionInfo } from "../extensions/pi-intercom/types.ts";
+/** Dedicated same-process bridge. These channels are not externally callable RPC bus operations. */
+export declare const INTERCOM_RPC_REQUEST_EVENT = "intercom:rpc-request";
+export declare const INTERCOM_RPC_RESULT_EVENT = "intercom:rpc-result";
+export declare const INTERCOM_RPC_EVENT = "intercom:rpc-event";
+export declare const INTERCOM_RPC_ASK_TIMEOUT_MS = 600000;
+export interface IntercomRpcMessageOptions {
+    message: string;
+    attachments?: Attachment[];
+    replyTo?: string;
+}
+export type IntercomRpcCommand = {
+    id?: string;
+    type: "intercom_status";
+} | {
+    id?: string;
+    type: "intercom_list";
+} | {
+    id?: string;
+    type: "intercom_pending";
+} | ({
+    id?: string;
+    type: "intercom_send";
+    to: string;
+} & IntercomRpcMessageOptions) | ({
+    id?: string;
+    type: "intercom_ask";
+    to: string;
+    timeoutMs?: number;
+} & IntercomRpcMessageOptions) | ({
+    id?: string;
+    type: "intercom_reply";
+    to?: string;
+} & IntercomRpcMessageOptions);
+export interface IntercomRpcStatus {
+    scope: RpcObservationScope;
+    enabled: boolean;
+    connected: boolean;
+    sessionId: string | null;
+    name?: string;
+}
+export interface IntercomRpcDelivery extends DeliveryDetails {
+    messageId: string;
+    delivered: boolean;
+    reason?: string;
+    to: string;
+    replyTo?: string;
+}
+export interface IntercomRpcDataMap {
+    intercom_status: IntercomRpcStatus;
+    intercom_list: {
+        sessionId: string;
+        sessions: SessionInfo[];
+    };
+    intercom_pending: {
+        asks: Array<{
+            from: SessionInfo;
+            message: Message;
+            receivedAt: number;
+        }>;
+    };
+    intercom_send: IntercomRpcDelivery;
+    intercom_reply: IntercomRpcDelivery;
+    intercom_ask: IntercomRpcDelivery & {
+        reply: Message;
+    };
+}
+export type IntercomRpcResponse = {
+    [K in keyof IntercomRpcDataMap]: {
+        id?: string;
+        type: "response";
+        command: K;
+        success: true;
+        data: IntercomRpcDataMap[K];
+    };
+}[keyof IntercomRpcDataMap];
+export type IntercomRpcEvent = IntercomRpcEventData & {
+    scope: RpcObservationScope;
+};
+/** Internal event data; the stdio host adds its own binding scope. */
+export type IntercomRpcEventData = {
+    type: "intercom_connection";
+    enabled: boolean;
+    connected: boolean;
+    sessionId: string | null;
+    reason?: string;
+} | {
+    type: "intercom_message";
+    from: SessionInfo;
+    message: Message;
+} | {
+    type: "intercom_presence";
+    session: SessionInfo;
+} | {
+    type: "intercom_session_joined";
+    session: SessionInfo;
+} | {
+    type: "intercom_session_left";
+    sessionId: string;
+} | {
+    type: "intercom_receipt";
+    from: SessionInfo;
+    receipt: Extract<BrokerMessage, {
+        type: "message_receipt";
+    }>["receipt"];
+} | {
+    type: "intercom_delivery";
+    result: Extract<BrokerMessage, {
+        type: "delivered" | "delivery_failed";
+    }>;
+};
+export interface IntercomRpcRequest {
+    requestId: string;
+    command: IntercomRpcCommand;
+    signal: AbortSignal;
+    /** Synchronous acknowledgement allows the host to fail promptly if the extension is missing. */
+    accept(): void;
+}
+export type IntercomRpcResult = {
+    requestId: string;
+} & ({
+    success: true;
+    data: IntercomRpcDataMap[keyof IntercomRpcDataMap] | Omit<IntercomRpcStatus, "scope">;
+} | {
+    success: false;
+    error: string;
+});
+export declare function intercomRpcTimeout(command: IntercomRpcCommand): number;
+export interface IntercomRpcEventEnvelope {
+    sessionId: string | null;
+    event: IntercomRpcEventData;
+}
+/** Fail closed before forwarding extension-bus payloads to a host client. */
+export declare function isIntercomRpcEvent(value: unknown): value is IntercomRpcEventData;

package/dist/core/intercom-rpc.js

@@ -0,0 +1,64 @@
+/** Dedicated same-process bridge. These channels are not externally callable RPC bus operations. */
+export const INTERCOM_RPC_REQUEST_EVENT = "intercom:rpc-request";
+export const INTERCOM_RPC_RESULT_EVENT = "intercom:rpc-result";
+export const INTERCOM_RPC_EVENT = "intercom:rpc-event";
+export const INTERCOM_RPC_ASK_TIMEOUT_MS = 600_000;
+export function intercomRpcTimeout(command) {
+    if (command.type !== "intercom_ask")
+        return 30_000;
+    const timeout = command.timeoutMs ?? INTERCOM_RPC_ASK_TIMEOUT_MS;
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > INTERCOM_RPC_ASK_TIMEOUT_MS) {
+        throw new Error("timeoutMs must be an integer between 1 and 600000");
+    }
+    return timeout;
+}
+/** Fail closed before forwarding extension-bus payloads to a host client. */
+export function isIntercomRpcEvent(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const event = value;
+    switch (event.type) {
+        case "intercom_connection":
+            return typeof event.enabled === "boolean" && typeof event.connected === "boolean"
+                && (event.sessionId === null || typeof event.sessionId === "string")
+                && (event.reason === undefined || typeof event.reason === "string");
+        case "intercom_message": return isSessionInfo(event.from) && isMessage(event.message);
+        case "intercom_presence":
+        case "intercom_session_joined": return isSessionInfo(event.session);
+        case "intercom_session_left": return typeof event.sessionId === "string";
+        case "intercom_receipt": return isSessionInfo(event.from) && isMessageReceipt(event.receipt);
+        case "intercom_delivery": {
+            if (!event.result || typeof event.result !== "object")
+                return false;
+            const result = event.result;
+            return typeof result.messageId === "string" && typeof result.retryable === "boolean" && typeof result.outcomeKnown === "boolean"
+                && (result.code === undefined || typeof result.code === "string")
+                && (result.type === "delivered" && (result.delivery === "queued" || result.delivery === "socket_delivered")
+                    || result.type === "delivery_failed" && typeof result.reason === "string" && (result.delivery === "failed" || result.delivery === "unknown"));
+        }
+        default: return false;
+    }
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function isSessionInfo(value) {
+    return isRecord(value) && ["id", "cwd", "model"].every(key => typeof value[key] === "string")
+        && ["pid", "startedAt", "lastActivity"].every(key => typeof value[key] === "number" && Number.isFinite(value[key]));
+}
+function isMessage(value) {
+    if (!isRecord(value) || typeof value.id !== "string" || typeof value.timestamp !== "number" || !Number.isFinite(value.timestamp)
+        || !isRecord(value.content) || typeof value.content.text !== "string")
+        return false;
+    if (value.replyTo !== undefined && typeof value.replyTo !== "string" || value.expectsReply !== undefined && typeof value.expectsReply !== "boolean")
+        return false;
+    const attachments = value.content.attachments;
+    return attachments === undefined || Array.isArray(attachments) && attachments.every(item => isRecord(item)
+        && ["file", "snippet", "context"].includes(String(item.type)) && typeof item.name === "string" && typeof item.content === "string"
+        && (item.language === undefined || typeof item.language === "string"));
+}
+function isMessageReceipt(value) {
+    return isRecord(value) && typeof value.messageId === "string" && typeof value.timestamp === "number" && Number.isFinite(value.timestamp)
+        && ["receiver_received", "queued", "injected", "acknowledged", "expired", "cancelled", "superseded", "cancellation_requested"].includes(String(value.status))
+        && (value.detail === undefined || typeof value.detail === "string");
+}

package/dist/core/release-rpc.d.ts

@@ -0,0 +1,137 @@
+/** Release-readiness DTOs. No extension runtime or filesystem dependencies. */
+import type { RpcObservationScope } from "./subagent-rpc.ts";
+export type { RpcObservationScope } from "./subagent-rpc.ts";
+export declare const RELEASE_READINESS_EVENT = "release:readiness:v1";
+export type ReleaseReadinessCommand = {
+    type: "release_readiness";
+    id?: string;
+    version: 1;
+};
+export type ReleaseBlockerSource = "core" | "subagents" | "intercom" | "scheduler" | (string & {});
+export interface ReleaseBlocker {
+    source: ReleaseBlockerSource;
+    /** Short stable machine token, e.g. streaming, compacting, retrying, queued_messages, pending_tool_calls, pending_bash,
+     * extension_dialog, compaction_prompt_queue, async_run, foreground_run, undelivered_result, inbound_ask, outbound_ask,
+     * armed_schedule, releasing, contributor_error. */
+    kind: string;
+    id?: string;
+    detail: string;
+    /** Epoch milliseconds when the blocking condition began (or, for armed schedules, is next due). */
+    since?: number;
+}
+export interface ReleaseReadiness extends RpcObservationScope {
+    /** True only when `blockers` is empty. A false negative here means lost work, so uncertainty is reported as a blocker. */
+    safe: boolean;
+    blockers: ReleaseBlocker[];
+    /** Extension contributors that answered. `safe` with an empty list means nobody reported. */
+    contributors: string[];
+}
+export type ReleaseReadinessResponse = {
+    id?: string;
+    type: "response";
+    command: "release_readiness";
+    success: true;
+    data: ReleaseReadiness;
+};
+/** Atomic "release if safe": see `decideRelease`. Validated exactly like `release_readiness`. */
+export type ReleaseCommand = {
+    type: "release";
+    id?: string;
+    version: 1;
+};
+export interface ReleaseResult {
+    /** True only when the process committed to a gentle exit (exit code 0, no abort). False: it keeps running normally. */
+    released: boolean;
+    /** The readiness the decision was based on; when `released` is false it lists what blocked the release. */
+    readiness: ReleaseReadiness;
+}
+export type ReleaseResponse = {
+    id?: string;
+    type: "response";
+    command: "release";
+    success: true;
+    data: ReleaseResult;
+};
+/**
+ * Core blocker kind reported by `release_readiness` once a `release` has been committed (the process is about to exit).
+ * `kind` is `releasing`.
+ */
+export declare const RELEASING_BLOCKER_KIND = "releasing";
+/**
+ * Whether a readiness answer permits an immediate release. "Nobody answered" (`contributors` empty, e.g. extensions not
+ * loaded) is NOT safe: the process cannot prove that no background work exists.
+ */
+export declare function decideRelease(readiness: Pick<ReleaseReadiness, "safe" | "blockers" | "contributors">): boolean;
+/**
+ * Synchronous broadcast on the session EventBus. Every listener calls `contribute` before `emit` returns.
+ * Listeners MUST ignore requests whose `sessionId` is not the session they are bound to.
+ */
+export interface ReleaseReadinessRequest {
+    version: 1;
+    sessionId: string;
+    contribute(name: string, blockers: ReleaseBlocker[]): void;
+}
+/**
+ * Listener-side helper: gate on session identity, compute blockers, and fail closed.
+ * The EventBus swallows listener exceptions, so a contributor that throws would otherwise look like "not loaded"
+ * and the host would report safe. Always answer through this helper (or reproduce its try/catch).
+ */
+export declare function answerReleaseReadiness(raw: unknown, name: string, boundSessionId: string | null | undefined, compute: () => ReleaseBlocker[]): void;
+/** Bounded shape check for blockers received from trusted-but-fallible extension contributors. */
+export declare function isReleaseBlocker(v: unknown): v is ReleaseBlocker;
+export declare const STOP_ALL_BACKGROUND_EVENT = "release:stop-all:v1";
+/** Total budget for one `stop_all_background`: core abort plus every extension's (possibly asynchronous) stop. */
+export declare const STOP_ALL_BACKGROUND_TIMEOUT_MS = 5000;
+/**
+ * Destructive: aborts the turn and stops every background run, session-only schedule and outbound ask of this session.
+ * Validated exactly like `release_readiness` and `release`; refused while a `release` is committed.
+ */
+export type StopAllBackgroundCommand = {
+    type: "stop_all_background";
+    id?: string;
+    version: 1;
+};
+export interface StopAllBackgroundItem {
+    source: ReleaseBlockerSource;
+    /** Short stable machine token, e.g. turn, retry, compaction, bash, queued_messages, async_run, foreground_run, schedule, outbound_ask, inbound_ask, contributor. */
+    kind: string;
+    id?: string;
+    detail: string;
+    /** True when the thing is no longer running/armed/pending. False: it could not be stopped (see `error`). */
+    ok: boolean;
+    error?: string;
+}
+export interface StopAllBackgroundResult extends RpcObservationScope {
+    /** Everything that was running, armed or pending when the command arrived, with the outcome of each stop. Empty on an idle session. */
+    stopped: StopAllBackgroundItem[];
+    /** Readiness computed AFTER the stop: what is still running or pending (also lists things that cannot be stopped). */
+    remaining: ReleaseReadiness;
+}
+export type StopAllBackgroundResponse = {
+    id?: string;
+    type: "response";
+    command: "stop_all_background";
+    success: true;
+    data: StopAllBackgroundResult;
+};
+/**
+ * Synchronous broadcast on the session EventBus, like `ReleaseReadinessRequest`. Every listener calls `contribute` before
+ * `emit` returns; the stop itself should start synchronously. A contributor that needs to wait (e.g. for a runner to
+ * acknowledge) passes a promise and must settle by `deadline` (epoch ms) with its still-pending items as `ok:false, error:"timeout"`.
+ * Listeners MUST ignore requests whose `sessionId` is not the session they are bound to.
+ */
+export interface StopAllBackgroundRequest {
+    version: 1;
+    sessionId: string;
+    deadline: number;
+    contribute(name: string, items: StopAllBackgroundItem[] | PromiseLike<StopAllBackgroundItem[]>): void;
+}
+/**
+ * Listener-side helper: gate on session identity and fail closed. A synchronous throw becomes an `ok:false` item, so one
+ * extension failing never prevents the others from stopping (the bridge also converts a rejected promise).
+ */
+export declare function answerStopAllBackground(raw: unknown, name: string, boundSessionId: string | null | undefined, compute: (request: Pick<StopAllBackgroundRequest, "deadline">) => StopAllBackgroundItem[] | PromiseLike<StopAllBackgroundItem[]>): void;
+/** The item every failure path uses, so a broken contributor is visible instead of silent. */
+export declare function stopAllContributorError(source: string, error: unknown): StopAllBackgroundItem;
+/** Bounded shape check for items received from trusted-but-fallible extension contributors. */
+export declare function isStopAllBackgroundItem(v: unknown): v is StopAllBackgroundItem;

package/dist/core/release-rpc.js

@@ -0,0 +1,77 @@
+export const RELEASE_READINESS_EVENT = "release:readiness:v1";
+/**
+ * Core blocker kind reported by `release_readiness` once a `release` has been committed (the process is about to exit).
+ * `kind` is `releasing`.
+ */
+export const RELEASING_BLOCKER_KIND = "releasing";
+/**
+ * Whether a readiness answer permits an immediate release. "Nobody answered" (`contributors` empty, e.g. extensions not
+ * loaded) is NOT safe: the process cannot prove that no background work exists.
+ */
+export function decideRelease(readiness) {
+    return readiness.safe === true && readiness.blockers.length === 0 && readiness.contributors.length > 0;
+}
+/**
+ * Listener-side helper: gate on session identity, compute blockers, and fail closed.
+ * The EventBus swallows listener exceptions, so a contributor that throws would otherwise look like "not loaded"
+ * and the host would report safe. Always answer through this helper (or reproduce its try/catch).
+ */
+export function answerReleaseReadiness(raw, name, boundSessionId, compute) {
+    const request = raw;
+    if (!request || request.version !== 1 || typeof request.contribute !== "function" || !boundSessionId || request.sessionId !== boundSessionId)
+        return;
+    let blockers;
+    try {
+        blockers = compute();
+    }
+    catch (error) {
+        blockers = [{ source: name, kind: "contributor_error", detail: (error instanceof Error ? error.message : String(error)).slice(0, 512) || "contributor failed" }];
+    }
+    request.contribute(name, blockers);
+}
+const text = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max;
+const record = (v) => Boolean(v && typeof v === "object" && !Array.isArray(v));
+/** Bounded shape check for blockers received from trusted-but-fallible extension contributors. */
+export function isReleaseBlocker(v) {
+    return record(v) && Object.keys(v).every(key => ["source", "kind", "id", "detail", "since"].includes(key))
+        && text(v.source, 64) && text(v.kind, 64) && text(v.detail, 512)
+        && (v.id === undefined || text(v.id, 256))
+        && (v.since === undefined || typeof v.since === "number" && Number.isSafeInteger(v.since) && v.since >= 0);
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// stop_all_background: the kill switch behind the desktop's "Quit anyway".
+// ---------------------------------------------------------------------------------------------------------------------
+export const STOP_ALL_BACKGROUND_EVENT = "release:stop-all:v1";
+/** Total budget for one `stop_all_background`: core abort plus every extension's (possibly asynchronous) stop. */
+export const STOP_ALL_BACKGROUND_TIMEOUT_MS = 5_000;
+/**
+ * Listener-side helper: gate on session identity and fail closed. A synchronous throw becomes an `ok:false` item, so one
+ * extension failing never prevents the others from stopping (the bridge also converts a rejected promise).
+ */
+export function answerStopAllBackground(raw, name, boundSessionId, compute) {
+    const request = raw;
+    if (!request || request.version !== 1 || typeof request.contribute !== "function" || !boundSessionId || request.sessionId !== boundSessionId)
+        return;
+    const deadline = typeof request.deadline === "number" && Number.isFinite(request.deadline) ? request.deadline : Date.now() + STOP_ALL_BACKGROUND_TIMEOUT_MS;
+    let items;
+    try {
+        items = compute({ deadline });
+    }
+    catch (error) {
+        items = [stopAllContributorError(name, error)];
+    }
+    request.contribute(name, items);
+}
+/** The item every failure path uses, so a broken contributor is visible instead of silent. */
+export function stopAllContributorError(source, error) {
+    const detail = (error instanceof Error ? error.message : String(error)).slice(0, 400) || "contributor failed";
+    return { source, kind: "contributor", detail: `Stop failed: ${detail}`, ok: false, error: detail.slice(0, 256) };
+}
+/** Bounded shape check for items received from trusted-but-fallible extension contributors. */
+export function isStopAllBackgroundItem(v) {
+    return record(v) && Object.keys(v).every(key => ["source", "kind", "id", "detail", "ok", "error"].includes(key))
+        && text(v.source, 64) && text(v.kind, 64) && text(v.detail, 512)
+        && (v.id === undefined || text(v.id, 256))
+        && typeof v.ok === "boolean"
+        && (v.error === undefined || text(v.error, 256));
+}

package/dist/core/resource-loader.d.ts

@@ -28,6 +28,8 @@ export interface ResourceLoaderReloadOptions {
     }) => Promise<boolean>;
 }
 export interface ResourceLoader {
+    /** Same-process extension bridge for host integrations; never exposed as an arbitrary RPC command. */
+    getEventBus?(): EventBus;
     getExtensions(): LoadExtensionsResult;
     getExtensionDiagnostics(): ResourceDiagnostic[];
     getSkills(): {
@@ -201,6 +203,7 @@ export declare class DefaultResourceLoader implements ResourceLoader {
     private lastThemePaths;
     private loaded;
     constructor(options: DefaultResourceLoaderOptions);
+    getEventBus(): EventBus;
     getExtensions(): LoadExtensionsResult;
     getExtensionDiagnostics(): ResourceDiagnostic[];
     getSkills(): {

package/dist/core/resource-loader.js

@@ -215,6 +215,9 @@ export class DefaultResourceLoader {
         this.lastThemePaths = [];
         this.loaded = false;
     }
+    getEventBus() {
+        return this.eventBus;
+    }
     getExtensions() {
         return this.extensionsResult;
     }

package/dist/core/subagent-rpc.d.ts

@@ -0,0 +1,110 @@
+/** Read-only stdio observability DTOs. No extension runtime or filesystem dependencies. */
+export declare const SUBAGENT_OBSERVE_EVENT = "subagent:observe:v1";
+export declare const SUBAGENT_RPC_MAX_BYTES = 65536;
+export interface RpcObservationScope {
+    version: 1;
+    sessionId: string | null;
+    epoch: string;
+}
+export type SubagentRpcCommand = {
+    type: "subagent_status";
+    id?: string;
+    version: 1;
+};
+export interface SubagentRpcTokens {
+    input: number;
+    output: number;
+    total: number;
+    window?: number;
+    windowPeak?: number;
+}
+export interface SubagentRpcFleet {
+    version: 1;
+    entries: Array<{
+        key: string;
+        agent: string;
+        role?: string;
+        model?: string;
+        effort?: string;
+        startedAt: number;
+        tokens: SubagentRpcTokens;
+        goal?: string;
+    }>;
+    totalActive: number;
+    topLevelAsyncCapacity: {
+        used: number;
+        limit: number;
+    };
+    omitted: number;
+}
+export type SubagentRpcLifecycle = "queued" | "pending" | "running" | "complete" | "completed" | "failed" | "partial" | "paused" | "stopped" | "rejected" | "detached";
+export interface SubagentRpcNode {
+    key: string;
+    runId?: string;
+    workflowId?: string;
+    agent?: string;
+    status: SubagentRpcLifecycle;
+    activity?: "waiting_supervisor" | "needs_attention";
+    startedAt?: number;
+    updatedAt?: number;
+    endedAt?: number;
+    progress?: string;
+    currentTool?: string;
+    tokens?: SubagentRpcTokens;
+    error?: string;
+    reason?: string;
+    /** Only explicit runtime execution projections; lifecycle is not a task verdict. */
+    outcome?: {
+        status: SubagentRpcLifecycle;
+        success?: boolean;
+        exitCode?: number;
+    };
+    /** Independent point-in-time runner proof, never inferred from outcome. */
+    processTerminal?: {
+        state: "pending" | "observed" | "unknown" | "not-started";
+        observedAt?: number;
+        reason?: string;
+    };
+    children: SubagentRpcNode[];
+    omittedChildren: number;
+}
+export interface SubagentRpcProjection {
+    fleet: SubagentRpcFleet;
+    runs: SubagentRpcNode[];
+    omitted: {
+        runs: number;
+        children: number;
+    };
+}
+export interface SubagentRpcSnapshot extends RpcObservationScope, SubagentRpcProjection {
+    available: boolean;
+    capabilities: {
+        snapshot: true;
+        events: boolean;
+    };
+    revision: number;
+}
+export interface SubagentRpcEvent extends RpcObservationScope {
+    type: "subagent_event";
+    revision: number;
+    snapshot: SubagentRpcSnapshot;
+}
+export type SubagentRpcResponse = {
+    id?: string;
+    type: "response";
+    command: "subagent_status";
+    success: true;
+    data: SubagentRpcSnapshot;
+};
+/** Synchronous, dedicated internal registration. Only native projections, never generic bus invocation. */
+export interface SubagentObserveRequest {
+    version: 1;
+    sessionId: string;
+    accept(source: SubagentObservationSource): void;
+}
+export interface SubagentObservationSource {
+    snapshot(): SubagentRpcProjection;
+    subscribe(listener: (projection: SubagentRpcProjection | null) => void): () => void;
+}
+/** Reject malformed or oversized trusted-extension payloads before JSONL publication. */
+export declare function isSubagentRpcProjection(v: unknown): v is SubagentRpcProjection;

package/dist/core/subagent-rpc.js

@@ -0,0 +1,60 @@
+/** Read-only stdio observability DTOs. No extension runtime or filesystem dependencies. */
+export const SUBAGENT_OBSERVE_EVENT = "subagent:observe:v1";
+export const SUBAGENT_RPC_MAX_BYTES = 65_536;
+const statuses = new Set(["queued", "pending", "running", "complete", "completed", "failed", "partial", "paused", "stopped", "rejected", "detached"]);
+const record = (v) => Boolean(v && typeof v === "object" && !Array.isArray(v));
+const count = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+const text = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max;
+const optionalText = (v, max) => v === undefined || text(v, max);
+const identity = (v) => text(v, 128) && !/[\\/\r\n]/.test(v);
+const onlyKeys = (v, keys) => Object.keys(v).every(key => keys.includes(key));
+function tokens(v) {
+    return record(v) && onlyKeys(v, ["input", "output", "total", "window", "windowPeak"]) && [v.input, v.output, v.total].every(count) && [v.window, v.windowPeak].every(n => n === undefined || count(n));
+}
+/** Reject malformed or oversized trusted-extension payloads before JSONL publication. */
+export function isSubagentRpcProjection(v) {
+    if (!record(v) || !onlyKeys(v, ["fleet", "runs", "omitted"]) || !record(v.fleet) || !record(v.omitted) || !Array.isArray(v.runs) || v.runs.length > 32)
+        return false;
+    const fleet = v.fleet;
+    if (!onlyKeys(fleet, ["version", "entries", "totalActive", "topLevelAsyncCapacity", "omitted"]) || !onlyKeys(v.omitted, ["runs", "children"])
+        || fleet.version !== 1 || !Array.isArray(fleet.entries) || fleet.entries.length > 16 || !count(fleet.totalActive) || !count(fleet.omitted)
+        || fleet.totalActive !== fleet.entries.length + fleet.omitted || !record(fleet.topLevelAsyncCapacity)
+        || !onlyKeys(fleet.topLevelAsyncCapacity, ["used", "limit"]) || !count(fleet.topLevelAsyncCapacity.used) || !count(fleet.topLevelAsyncCapacity.limit) || !count(v.omitted.runs) || !count(v.omitted.children))
+        return false;
+    if (!fleet.entries.every(e => record(e) && onlyKeys(e, ["key", "agent", "role", "model", "effort", "startedAt", "tokens", "goal"]) && identity(e.key) && text(e.agent, 96) && count(e.startedAt) && tokens(e.tokens)
+        && optionalText(e.role, 96) && optionalText(e.model, 128) && optionalText(e.effort, 128) && optionalText(e.goal, 512)))
+        return false;
+    let nodes = 0;
+    let omittedChildren = 0;
+    const keys = new Set();
+    function node(n, depth) {
+        if (!record(n) || !onlyKeys(n, ["key", "runId", "workflowId", "agent", "status", "activity", "startedAt", "updatedAt", "endedAt", "progress", "currentTool", "tokens", "error", "reason", "outcome", "processTerminal", "children", "omittedChildren"]) || depth > 4 || ++nodes > 64 || !identity(n.key) || keys.has(n.key) || !statuses.has(n.status)
+            || !Array.isArray(n.children) || n.children.length > 16 || !count(n.omittedChildren))
+            return false;
+        keys.add(n.key);
+        omittedChildren += n.omittedChildren;
+        if ([n.runId, n.workflowId].some(id => id !== undefined && !identity(id))
+            || !optionalText(n.agent, 96) || !optionalText(n.progress, 256) || !optionalText(n.currentTool, 96)
+            || !optionalText(n.error, 256) || !optionalText(n.reason, 128)
+            || [n.startedAt, n.updatedAt, n.endedAt].some(t => t !== undefined && !count(t))
+            || n.activity !== undefined && n.activity !== "waiting_supervisor" && n.activity !== "needs_attention"
+            || n.tokens !== undefined && !tokens(n.tokens))
+            return false;
+        if (n.outcome !== undefined && (!record(n.outcome) || !onlyKeys(n.outcome, ["status", "success", "exitCode"]) || !statuses.has(n.outcome.status)
+            || n.outcome.success !== undefined && typeof n.outcome.success !== "boolean"
+            || n.outcome.exitCode !== undefined && (typeof n.outcome.exitCode !== "number" || !Number.isSafeInteger(n.outcome.exitCode))))
+            return false;
+        if (n.processTerminal !== undefined && (!record(n.processTerminal) || !onlyKeys(n.processTerminal, ["state", "observedAt", "reason"]) || !["pending", "observed", "unknown", "not-started"].includes(n.processTerminal.state)
+            || !optionalText(n.processTerminal.reason, 128) || n.processTerminal.observedAt !== undefined && !count(n.processTerminal.observedAt)))
+            return false;
+        return n.children.every(child => node(child, depth + 1));
+    }
+    if (!v.runs.every(n => node(n, 0)) || omittedChildren !== v.omitted.children)
+        return false;
+    try {
+        return Buffer.byteLength(JSON.stringify(v), "utf8") <= SUBAGENT_RPC_MAX_BYTES - 1024;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/extensions/agent-browser.ts

@@ -146,6 +146,15 @@ export default function agentBrowserSetupExtension(pi: ExtensionAPI): void {
 		if (event.reason !== "startup") return;
 		if (process.env[SKIP_ENV] === "1") return;
 		if (isDeclined()) return;
+		// Startup activation is awaited before the RPC command loop serves stdin, so a
+		// startup confirm can deadlock headless RPC hosts that never render it. Warn once
+		// instead; /setup-agent-browser re-runs the interactive flow in any mode.
+		if (ctx.mode === "rpc") {
+			if (!(await isAgentBrowserInstalled(pi))) {
+				notify(ctx, `agent-browser CLI not found; install with: ${INSTALL_COMMAND}`, "warning");
+			}
+			return;
+		}
 		await ensureAgentBrowser(pi, ctx);
 	});