@capybara-hq/kernel 0.1.0-rc.21 → 0.1.0-rc.23

package/dist/tools/elicitation.d.ts

@@ -75,6 +75,8 @@ export declare class ElicitationSession {
         } | undefined;
         onSuspend: () => void;
         declineAll?: boolean;
+        /** With `declineAll`: the note added to the result instead of the default one. */
+        declineNote?: string;
     });
     handle: (req: ElicitationRequest) => Promise<ElicitationResponse>;
 }

package/dist/tools/elicitation.js

@@ -239,7 +239,7 @@ export class ElicitationSession {
     }
     handle = async (req) => {
         if (this.opts.declineAll) {
-            this.notes.push(unsupportedNote("this tool cannot pause for user input"));
+            this.notes.push(this.opts.declineNote ?? unsupportedNote("this tool cannot pause for user input"));
             return { action: "decline" };
         }
         const fp = fingerprint(req);

package/dist/tools/fixed-ask.d.ts

@@ -0,0 +1,7 @@
+import type { ResolvedTool } from "./registry.js";
+/**
+ * Whether the tool is a fixed ask: its spec declares `requiresUserInteraction`, or it is on the R3
+ * list ({@link R3_FIXED_ASK_TOOL_KEYS}: the schedule writes). Its policy is at least `ask` and
+ * remembered grants never let it through.
+ */
+export declare function isFixedAsk(tool: ResolvedTool): boolean;

package/dist/tools/fixed-ask.js

@@ -0,0 +1,9 @@
+import { R3_FIXED_ASK_TOOL_KEYS } from "./builtin-names.js";
+/**
+ * Whether the tool is a fixed ask: its spec declares `requiresUserInteraction`, or it is on the R3
+ * list ({@link R3_FIXED_ASK_TOOL_KEYS}: the schedule writes). Its policy is at least `ask` and
+ * remembered grants never let it through.
+ */
+export function isFixedAsk(tool) {
+    return (tool.spec.annotations?.requiresUserInteraction === true || R3_FIXED_ASK_TOOL_KEYS.has(tool.key));
+}

package/dist/tools/network-asks.d.ts

@@ -0,0 +1,109 @@
+import { type DeviceFeature, type DeviceLocalPolicySummary, type NetworkBlockedHost } from "@capybara-hq/plugin-sdk";
+import type { NetworkRunState } from "../local-devices/network-grants.js";
+import { type UnattendedRun } from "../schedules/unattended.js";
+import { type ApprovalRecord } from "./approvals.service.js";
+/**
+ * Network asks in the tool pipeline (network ask-to-allow spec §6.2, §6.6–§6.9, §8.3): what a
+ * command's reported refusals turn into (an ask to the device owner, or notes written at once) and
+ * the model-visible notes. Pure: the pipeline reads the facts and writes the events.
+ */
+/** The most network asks one run makes (spec §6.8); later refusals get {@link tooManyNote}. */
+export declare const MAX_NETWORK_ASKS_PER_RUN = 5;
+/** The longest kept command result of a network ask, in UTF-8 bytes (spec §6.2). */
+export declare const NETWORK_ASK_KEPT_MAX_BYTES: number;
+/** The line a kept result ends with when it had to be clipped to {@link NETWORK_ASK_KEPT_MAX_BYTES}. */
+export declare const NETWORK_ASK_CLIPPED_NOTE = "[Output clipped to its first 16 KB while waiting for network access.]";
+/** The idempotency key of a call's `network_blocked` event. */
+export declare const networkBlockedIdemKey: (runId: string, callId: string) => string;
+/** Asked, allowed this time (a run grant; also the 「一直允许」 that fell back to one). */
+export declare const allowedOnceNote: (hosts: readonly string[]) => string;
+/** Asked, allowed on the device from now on. */
+export declare const allowedAlwaysNote: (hosts: readonly string[]) => string;
+/** Asked and declined (also the unchecked hosts of a partial decision, and a host refused earlier in the run). */
+export declare const deniedNote: (hosts: readonly string[], reason?: string | null) => string;
+/** Asked, no answer within the approval timeout. */
+export declare const expiredNote: (hosts: readonly string[], hours: number) => string;
+/** Asked, the person sent a message instead (spec §6.7). */
+export declare const skippedNote: (hosts: readonly string[]) => string;
+/** Asked, the run was stopped before the answer (the note abort writes too). */
+export declare const cancelledNote: () => string;
+/** Not asked: the run tree already waits for another network ask (at most one, spec §6.8). */
+export declare const otherAskPendingNote: (hosts: readonly string[]) => string;
+/** Not asked: the run made {@link MAX_NETWORK_ASKS_PER_RUN} asks already (spec §6.8). */
+export declare const tooManyNote: (hosts: readonly string[]) => string;
+/**
+ * Not asked: the device takes no network changes from the deployment (`remoteGrants: off`), so
+ * neither a run grant nor 「一直允许」 would reach it; only its owner can allow the host locally.
+ */
+export declare const localOnlyNote: (hosts: readonly string[]) => string;
+/**
+ * Asked and allowed 「一直允许」, but the device refused the policy op (outcome `refused`): nothing
+ * was granted.
+ */
+export declare const alwaysRefusedNote: (hosts: readonly string[]) => string;
+/** The org layer (spec §6.6): only an org admin can lift it. */
+export declare const orgLayerNote: (hosts: readonly string[]) => string;
+/** The address layer (spec §6.6): nobody can lift it. */
+export declare const addressLayerNote: (hosts: readonly string[]) => string;
+/**
+ * An unattended run (spec §8.1): the task approves the host, yet the device refused it: the device
+ * takes no network grants from the deployment (`remoteGrants` off, or a program too old for them).
+ * Not asked, not a missing grant: only the device's owner can allow it locally.
+ */
+export declare const taskGrantIgnoredNote: (hosts: readonly string[]) => string;
+/** An unattended run in `fail` mode (spec §8.3): no ask, the creator can add a task grant. */
+export declare const unattendedNetworkNote: (hosts: readonly string[]) => string;
+/** What the pipeline knows when a command reported refused hosts. */
+export interface NetworkPlanContext {
+    /** The device's active machine: its features and local policy summary (null: none connected). */
+    device: {
+        features: readonly DeviceFeature[];
+        policy: DeviceLocalPolicySummary | null;
+    } | null;
+    /** The scheduled task run the run serves (null / undefined: attended). */
+    unattended: UnattendedRun | null | undefined;
+}
+/** What to do with a command's refused hosts. */
+export interface NetworkPlan {
+    /** The device-layer hosts to ask the device owner about (empty: no ask). */
+    ask: {
+        host: string;
+        port: number;
+    }[];
+    /** The scopes the ask offers (a device without remote grants is never asked). */
+    scopes: ("once" | "always")[];
+    /** Notes written now, after the command output (one line per outcome). */
+    notes: string[];
+    /** `missing_grants` keys of an unattended run (`network:<host>`). */
+    missingGrants: string[];
+}
+/** The hosts of a `network_blocked` event: valid, deduplicated, at most {@link NETWORK_ASK_MAX_HOSTS}. */
+export declare function blockedEventHosts(blocked: readonly NetworkBlockedHost[]): NetworkBlockedHost[];
+/**
+ * Decides what a command's refused hosts become (spec §6.2, §6.8, §6.9, §8.3), given the run
+ * tree's network asks (`run`). The caller asks only for foreground `Bash` on a device; this decides
+ * the rest:
+ * - `address` and `org` layers: a note each (in an unattended run an `org` host is a missing grant);
+ *   `unknown`: nothing (the device's trailer explains);
+ * - `device` layer on a program without `policyOp`: nothing (no ask, the trailer explains);
+ * - approved by the scheduled task the run serves (`run.taskGranted`) yet refused: a note that
+ *   the device ignores the task's grants (never asked, never a missing grant);
+ * - refused earlier in the run tree: the denied note; an unattended run in `fail` mode: its note
+ *   and a missing grant;
+ * - the rest is asked, unless another ask of the run tree is pending or the run made
+ *   {@link MAX_NETWORK_ASKS_PER_RUN} asks (a note each).
+ */
+export declare function planNetworkAsk(blocked: readonly NetworkBlockedHost[], run: NetworkRunState | null, ctx: NetworkPlanContext): NetworkPlan;
+/**
+ * The note of a settled network ask (spec §6.6): one line per outcome. An approval allows
+ * `detail.grantedHosts` (once, always, or once after 「一直允许」 fell back) and declines the hosts
+ * left unchecked; `hours` is the ask's own wait (created to expiry). Null while it is pending.
+ */
+export declare function settledNetworkNotes(a: ApprovalRecord, hours: number): string[] | null;
+/** `text` followed by `notes` after a blank line (unchanged without notes). */
+export declare const withNetworkNotes: (text: string, notes: readonly string[]) => string;
+/**
+ * A kept result's content within {@link NETWORK_ASK_KEPT_MAX_BYTES} (UTF-8): the head, then
+ * {@link NETWORK_ASK_CLIPPED_NOTE}. The caller archives large output first, so this rarely cuts.
+ */
+export declare function clipKept(content: string): string;

package/dist/tools/network-asks.js

@@ -0,0 +1,221 @@
+import { validateAllowHost, } from "@capybara-hq/plugin-sdk";
+import { NETWORK_ASK_MAX_HOSTS, NETWORK_HOST_MAX_CHARS } from "../conversations/events.js";
+import { networkGrantKey, unattendedFails, unattendedRules, } from "../schedules/unattended.js";
+import { NETWORK_ASK_CANCELLED_NOTE } from "./approvals.service.js";
+/**
+ * Network asks in the tool pipeline (network ask-to-allow spec §6.2, §6.6–§6.9, §8.3): what a
+ * command's reported refusals turn into (an ask to the device owner, or notes written at once) and
+ * the model-visible notes. Pure: the pipeline reads the facts and writes the events.
+ */
+/** The most network asks one run makes (spec §6.8); later refusals get {@link tooManyNote}. */
+export const MAX_NETWORK_ASKS_PER_RUN = 5;
+/** The longest kept command result of a network ask, in UTF-8 bytes (spec §6.2). */
+export const NETWORK_ASK_KEPT_MAX_BYTES = 16 * 1024;
+/** The line a kept result ends with when it had to be clipped to {@link NETWORK_ASK_KEPT_MAX_BYTES}. */
+export const NETWORK_ASK_CLIPPED_NOTE = "[Output clipped to its first 16 KB while waiting for network access.]";
+/** The idempotency key of a call's `network_blocked` event. */
+export const networkBlockedIdemKey = (runId, callId) => `network_blocked:${runId}:${callId}`;
+const list = (hosts) => hosts.join(", ");
+const one = (hosts) => hosts.length === 1;
+const pron = (hosts) => (one(hosts) ? "it" : "them");
+/** "x was blocked by this device's network policy." (the lead of every device-layer note). */
+const blockedLead = (hosts) => `[network] ${list(hosts)} ${one(hosts) ? "was" : "were"} blocked by this device's network policy.`;
+/** Asked, allowed this time (a run grant; also the 「一直允许」 that fell back to one). */
+export const allowedOnceNote = (hosts) => `${blockedLead(hosts)} The user allowed ${pron(hosts)} for the rest of this task. Run the command again.`;
+/** Asked, allowed on the device from now on. */
+export const allowedAlwaysNote = (hosts) => `${blockedLead(hosts)} The user allowed ${pron(hosts)} on this device from now on. Run the command again.`;
+/** Asked and declined (also the unchecked hosts of a partial decision, and a host refused earlier in the run). */
+export const deniedNote = (hosts, reason) => `${blockedLead(hosts)} The user declined access to ${list(hosts)}. Do not try to reach ${pron(hosts)} another way; continue without ${pron(hosts)} or ask the user.` +
+    (reason != null && reason !== "" ? ` Reason: ${reason}` : "");
+/** Asked, no answer within the approval timeout. */
+export const expiredNote = (hosts, hours) => `${blockedLead(hosts)} The user did not answer within ${hours}h; access stays blocked.`;
+/** Asked, the person sent a message instead (spec §6.7). */
+export const skippedNote = (hosts) => `${blockedLead(hosts)} The user sent a message instead of answering; access stays blocked.`;
+/** Asked, the run was stopped before the answer (the note abort writes too). */
+export const cancelledNote = () => NETWORK_ASK_CANCELLED_NOTE;
+/** Not asked: the run tree already waits for another network ask (at most one, spec §6.8). */
+export const otherAskPendingNote = (hosts) => `${blockedLead(hosts).slice(0, -1)}; another network request is waiting for the user.`;
+/** Not asked: the run made {@link MAX_NETWORK_ASKS_PER_RUN} asks already (spec §6.8). */
+export const tooManyNote = (hosts) => `${blockedLead(hosts)} Too many network requests in this task; ask the user to allow the domains on the device page.`;
+/** The local command that allows each host (one `policy add` per host). */
+const localAdd = (hosts) => hosts.map((h) => `capybara-device policy add allowedDomains ${h}`).join(" and ");
+/**
+ * Not asked: the device takes no network changes from the deployment (`remoteGrants: off`), so
+ * neither a run grant nor 「一直允许」 would reach it; only its owner can allow the host locally.
+ */
+export const localOnlyNote = (hosts) => `${blockedLead(hosts).slice(0, -1)}, and this device does not accept network changes from the conversation. The device owner can allow ${pron(hosts)} locally: ${localAdd(hosts)}. Continue without ${pron(hosts)} or tell the user.`;
+/**
+ * Asked and allowed 「一直允许」, but the device refused the policy op (outcome `refused`): nothing
+ * was granted.
+ */
+export const alwaysRefusedNote = (hosts) => `${blockedLead(hosts)} The user allowed ${pron(hosts)} on this device, but the device does not accept network changes from the deployment; access stays blocked. The device owner can allow ${pron(hosts)} locally: ${localAdd(hosts)}.`;
+/** The org layer (spec §6.6): only an org admin can lift it. */
+export const orgLayerNote = (hosts) => one(hosts)
+    ? `[network] ${list(hosts)} is not in the organization's network allowlist. Only an organization admin can add it; the user can ask an admin from the conversation. Continue without it or tell the user.`
+    : `[network] ${list(hosts)} are not in the organization's network allowlist. Only an organization admin can add them; the user can ask an admin from the conversation. Continue without them or tell the user.`;
+/** The address layer (spec §6.6): nobody can lift it. */
+export const addressLayerNote = (hosts) => one(hosts)
+    ? `[network] ${list(hosts)} is a private or local address, which commands can never reach.`
+    : `[network] ${list(hosts)} are private or local addresses, which commands can never reach.`;
+/**
+ * An unattended run (spec §8.1): the task approves the host, yet the device refused it: the device
+ * takes no network grants from the deployment (`remoteGrants` off, or a program too old for them).
+ * Not asked, not a missing grant: only the device's owner can allow it locally.
+ */
+export const taskGrantIgnoredNote = (hosts) => `${blockedLead(hosts)} The scheduled task approves ${pron(hosts)}, but this device does not accept the task's network grants. The device owner can allow ${pron(hosts)} locally: ${localAdd(hosts)}. Continue without ${pron(hosts)}.`;
+/** An unattended run in `fail` mode (spec §8.3): no ask, the creator can add a task grant. */
+export const unattendedNetworkNote = (hosts) => `[network] ${list(hosts)} ${one(hosts) ? "is" : "are"} blocked on this device and this scheduled run cannot ask for network access. The task's owner can add ${pron(hosts)} to the task's approved domains. Continue without ${pron(hosts)}.`;
+/** Hosts in first-seen order, deduplicated, lower-cased, trailing dot dropped. */
+function hostsOf(blocked) {
+    const seen = new Set();
+    const out = [];
+    for (const b of blocked) {
+        const host = b.host.toLowerCase().replace(/\.$/, "");
+        if (host === "" || host.length > NETWORK_HOST_MAX_CHARS || seen.has(host))
+            continue;
+        seen.add(host);
+        out.push({ ...b, host });
+    }
+    return out;
+}
+/** The hosts of a `network_blocked` event: valid, deduplicated, at most {@link NETWORK_ASK_MAX_HOSTS}. */
+export function blockedEventHosts(blocked) {
+    return hostsOf(blocked)
+        .filter((b) => Number.isInteger(b.port) && b.port >= 1 && b.port <= 65535)
+        .slice(0, NETWORK_ASK_MAX_HOSTS);
+}
+/**
+ * Decides what a command's refused hosts become (spec §6.2, §6.8, §6.9, §8.3), given the run
+ * tree's network asks (`run`). The caller asks only for foreground `Bash` on a device; this decides
+ * the rest:
+ * - `address` and `org` layers: a note each (in an unattended run an `org` host is a missing grant);
+ *   `unknown`: nothing (the device's trailer explains);
+ * - `device` layer on a program without `policyOp`: nothing (no ask, the trailer explains);
+ * - approved by the scheduled task the run serves (`run.taskGranted`) yet refused: a note that
+ *   the device ignores the task's grants (never asked, never a missing grant);
+ * - refused earlier in the run tree: the denied note; an unattended run in `fail` mode: its note
+ *   and a missing grant;
+ * - the rest is asked, unless another ask of the run tree is pending or the run made
+ *   {@link MAX_NETWORK_ASKS_PER_RUN} asks (a note each).
+ */
+export function planNetworkAsk(blocked, run, ctx) {
+    const address = [];
+    const org = [];
+    const refused = [];
+    const localOnly = [];
+    const unattended = [];
+    const taskIgnored = [];
+    const candidates = [];
+    const missingGrants = [];
+    // a machine that reports blocked hosts and takes policy changes (Docker mode has no report)
+    const canAsk = ctx.device?.features.includes("networkReport") === true &&
+        ctx.device.features.includes("policyOp");
+    // no run grant or policy change reaches a device whose owner turned remote grants off
+    const remote = ctx.device?.policy?.remoteGrants !== "off";
+    for (const b of hostsOf(blocked)) {
+        if (b.layer === "address")
+            address.push(b.host);
+        else if (b.layer === "org") {
+            org.push(b.host);
+            if (unattendedRules(ctx.unattended))
+                missingGrants.push(networkGrantKey(b.host));
+        }
+        else if (b.layer === "device") {
+            if (!canAsk)
+                continue;
+            // relayer already made an invalid name an address; a wildcard is never asked
+            if (b.host.startsWith("*.") || validateAllowHost(b.host).length > 0) {
+                address.push(b.host);
+            }
+            else if (run?.taskGranted?.has(b.host))
+                taskIgnored.push(b.host);
+            else if (run?.refused.has(b.host))
+                refused.push(b.host);
+            else if (unattendedFails(ctx.unattended)) {
+                unattended.push(b.host);
+                missingGrants.push(networkGrantKey(b.host));
+            }
+            else if (!remote)
+                localOnly.push(b.host);
+            else
+                candidates.push({ host: b.host, port: b.port });
+        }
+    }
+    const notes = [];
+    if (refused.length > 0)
+        notes.push(deniedNote(refused));
+    if (localOnly.length > 0)
+        notes.push(localOnlyNote(localOnly));
+    if (taskIgnored.length > 0)
+        notes.push(taskGrantIgnoredNote(taskIgnored));
+    if (unattended.length > 0)
+        notes.push(unattendedNetworkNote(unattended));
+    let ask = [];
+    if (candidates.length > 0) {
+        const names = candidates.map((c) => c.host);
+        if (run?.pending === true)
+            notes.push(otherAskPendingNote(names));
+        else if ((run?.asks ?? 0) >= MAX_NETWORK_ASKS_PER_RUN)
+            notes.push(tooManyNote(names));
+        else
+            ask = candidates.slice(0, NETWORK_ASK_MAX_HOSTS);
+    }
+    if (org.length > 0)
+        notes.push(orgLayerNote(org));
+    if (address.length > 0)
+        notes.push(addressLayerNote(address));
+    return { ask, scopes: ["once", "always"], notes, missingGrants };
+}
+/**
+ * The note of a settled network ask (spec §6.6): one line per outcome. An approval allows
+ * `detail.grantedHosts` (once, always, or once after 「一直允许」 fell back) and declines the hosts
+ * left unchecked; `hours` is the ask's own wait (created to expiry). Null while it is pending.
+ */
+export function settledNetworkNotes(a, hours) {
+    const asked = (a.detail?.hosts ?? []).map((h) => h.host);
+    switch (a.status) {
+        case "approved": {
+            // 「一直允许」 the device refused: nothing took effect (compared as a string: the outcome
+            // may predate this build's type)
+            if (a.detail?.outcome === "refused") {
+                return [alwaysRefusedNote(asked)];
+            }
+            const granted = a.detail?.grantedHosts ?? asked;
+            const rest = asked.filter((h) => !granted.includes(h));
+            const notes = [];
+            if (granted.length > 0) {
+                notes.push(a.detail?.outcome === "always" ? allowedAlwaysNote(granted) : allowedOnceNote(granted));
+            }
+            if (rest.length > 0)
+                notes.push(deniedNote(rest));
+            return notes;
+        }
+        case "denied":
+            return [deniedNote(asked, a.denyReason)];
+        case "expired":
+            return [expiredNote(asked, hours)];
+        case "skipped":
+            return [skippedNote(asked)];
+        case "cancelled":
+            return [cancelledNote()];
+        default:
+            return null;
+    }
+}
+/** `text` followed by `notes` after a blank line (unchanged without notes). */
+export const withNetworkNotes = (text, notes) => notes.length === 0 ? text : `${text}\n\n${notes.join("\n")}`;
+/**
+ * A kept result's content within {@link NETWORK_ASK_KEPT_MAX_BYTES} (UTF-8): the head, then
+ * {@link NETWORK_ASK_CLIPPED_NOTE}. The caller archives large output first, so this rarely cuts.
+ */
+export function clipKept(content) {
+    const bytes = Buffer.from(content, "utf8");
+    if (bytes.length <= NETWORK_ASK_KEPT_MAX_BYTES)
+        return content;
+    const room = NETWORK_ASK_KEPT_MAX_BYTES - Buffer.byteLength(NETWORK_ASK_CLIPPED_NOTE) - 1;
+    // a cut inside a multi-byte character drops it rather than keeping half of it
+    const head = new TextDecoder("utf-8", { fatal: false })
+        .decode(bytes.subarray(0, room))
+        .replace(/�$/, "");
+    return `${head}\n${NETWORK_ASK_CLIPPED_NOTE}`;
+}

package/dist/tools/pipeline.d.ts

@@ -7,18 +7,22 @@ import { ExtensionHost } from "../extensions/host.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
+import { DevicePolicyService } from "../local-devices/device-policy.service.js";
+import { type NetworkRunState } from "../local-devices/network-grants.js";
 import type { OrgRole } from "../orgs/roles.js";
 import { type ConversationKindForHooks, type HookRunner } from "../runtime/hook-calls.js";
 import { type SubagentParent, type WaitingFor } from "../runtime/loop.js";
 import type { DispatchArgs, DispatchOutcome } from "../runtime/subagents/dispatch.js";
 import { SubagentMessages } from "../runtime/subagents/messages.js";
 import { SubagentsService } from "../runtime/subagents/subagents.service.js";
+import { type UnattendedRun } from "../schedules/unattended.js";
 import { ApprovalsService } from "./approvals.service.js";
 import { Breaker } from "./breaker.js";
 import { Credentials } from "./credentials.js";
 import { ToolDrift } from "./drift.js";
 import { OrgToolSwitches } from "./org-tool-switches.js";
 import { ToolOutputs } from "./outputs.js";
+import { type GrantKind } from "./policy.js";
 import { QuestionsService } from "./questions.service.js";
 import { type CallPolicy, type ResolvedTool, ToolRegistry } from "./registry.js";
 /** 审批被拒绝。 */
@@ -84,7 +88,15 @@ export type PolicyDecision = "allow" | "deny" | {
 }
 /** 记住的授权把 `ask` 放行（按 allow 执行，审计记授权种类）。 */
  | {
-    grant: "session" | "always";
+    grant: GrantKind;
+}
+/**
+ * Refused without an approval: an unattended run in `fail` mode (scheduled tasks spec §7). The
+ * text is the tool error; `missingGrant` is added to the task run's `missing_grants`.
+ */
+ | {
+    refused: string;
+    missingGrant?: string;
 };
 export interface PolicyContext {
     orgId: string;
@@ -114,6 +126,11 @@ export interface PolicyContext {
      * null / unset: policies, grants and approvals use the tool key.
      */
     callPolicy?: CallPolicy | null;
+    /**
+     * The scheduled task run the run serves, unattended or trial (scheduled tasks spec §7); unset or
+     * null: an attended run.
+     */
+    unattended?: UnattendedRun | null;
 }
 /** 管线第 3 阶段：策略判定。 */
 export type DecidePolicy = (tool: ResolvedTool, agentDef: AgentDefinition, ctx: PolicyContext) => Promise<PolicyDecision>;
@@ -138,8 +155,8 @@ interface PipelineDeps {
     readonly credentials: Pick<Credentials, "injection" | "onUnauthorized">;
     readonly breaker: Pick<Breaker, "check" | "failure" | "success">;
     readonly outputs: Pick<ToolOutputs, "save" | "load">;
-    /** 策略为 `ask` 时建审批；续跑时读该调用的审批结果。 */
-    readonly approvals: Pick<ApprovalsService, "request" | "forCall">;
+    /** 策略为 `ask` 时建审批；续跑时读该调用的审批结果。 A refused network host: a network ask. */
+    readonly approvals: Pick<ApprovalsService, "request" | "forCall" | "networkForCall" | "requestNetwork">;
     /** 处理函数返回 `input_required` 时建输入请求；续跑时读该调用的各轮输入请求。 */
     readonly questions: Pick<QuestionsService, "ask" | "forCall">;
     readonly log: Logger;
@@ -180,6 +197,18 @@ interface PipelineDeps {
      * it, their calls reach the builtins' guards, which refuse them.
      */
     readonly messages: Pick<SubagentMessages, "toChild" | "toParent"> | undefined;
+    /**
+     * What a command's refused network hosts need (network ask-to-allow spec §6.2): the run tree's
+     * network asks and the device's features and policy summary. Without them (hand-built test
+     * pipelines) a report only writes `network_blocked`.
+     */
+    readonly network: {
+        /** `deviceId` scopes the run tree's asks to the device (ignored by an older provider). */
+        grants: {
+            runState(runId: string, deviceId?: string): Promise<NetworkRunState>;
+        };
+        devices: Pick<DevicePolicyService, "summary">;
+    } | undefined;
 }
 /** The sub-agent dispatch the pipeline calls (`SubagentsService.dispatch`). */
 export type SubagentDispatch = NonNullable<PipelineDeps["subagents"]>["dispatch"];
@@ -206,6 +235,11 @@ export interface ToolStepContext {
      * (spec §10.1, agent map spec §6), and it dispatches sub-agents only below `subagents.maxDepth`.
      */
     parent?: SubagentParent;
+    /**
+     * The scheduled task run this run serves (scheduled tasks spec §7); filled by `runStep` once per
+     * step from PG (`unattendedRunOf`), null when attended. Callers leave it unset.
+     */
+    unattended?: UnattendedRun | null;
 }
 /** tools 节点一步的结果：全部调用都有了结果，或某个调用需要等人处理（之后的调用留到续跑）。 */
 export type ToolStepOutcome = {
@@ -242,6 +276,7 @@ export type ExecOutcome =
     kind: "connection_required";
     connectorId: string;
     connectorName: string;
+    connectorSlug: string;
     message: string;
 };
 /**
@@ -260,9 +295,11 @@ export declare class ToolPipeline {
     /** The `Agent` tool's sub-agent dispatch; absent (tests): `Agent` calls are refused. */
     subagents: Pick<SubagentsService, "dispatch"> | undefined, 
     /** The message tools between agents; absent (tests): their calls are refused. */
-    messages: Pick<SubagentMessages, "toChild" | "toParent"> | undefined, registry: Pick<ToolRegistry, "forAgent" | "findConnector" | "handler">, credentials: Pick<Credentials, "injection" | "onUnauthorized">, breaker: Pick<Breaker, "check" | "failure" | "success">, outputs: Pick<ToolOutputs, "save" | "load">, approvals: Pick<ApprovalsService, "request" | "forCall">, questions: Pick<QuestionsService, "ask" | "forCall">, config: Pick<KernelConfigService, "get">, log: Logger, 
+    messages: Pick<SubagentMessages, "toChild" | "toParent"> | undefined, registry: Pick<ToolRegistry, "forAgent" | "findConnector" | "handler">, credentials: Pick<Credentials, "injection" | "onUnauthorized">, breaker: Pick<Breaker, "check" | "failure" | "success">, outputs: Pick<ToolOutputs, "save" | "load">, approvals: Pick<ApprovalsService, "request" | "forCall" | "networkForCall" | "requestNetwork">, questions: Pick<QuestionsService, "ask" | "forCall">, config: Pick<KernelConfigService, "get">, log: Logger, 
     /** Plugin hooks and inline ui contributions; absent (tests): no hooks, cards dropped. */
-    host: Pick<ExtensionHost, "hooks" | "current"> | undefined, drift: Pick<ToolDrift, "onToolsChanged"> | undefined, effective: Pick<EffectiveConfigs, "get">, switches: Pick<OrgToolSwitches, "isToolOff">, txHost: TransactionHost, hooks?: ToolPipelineHooks);
+    host: Pick<ExtensionHost, "hooks" | "current"> | undefined, drift: Pick<ToolDrift, "onToolsChanged"> | undefined, effective: Pick<EffectiveConfigs, "get">, switches: Pick<OrgToolSwitches, "isToolOff">, txHost: TransactionHost, hooks?: ToolPipelineHooks, networkGrants?: {
+        runState(runId: string, deviceId?: string): Promise<NetworkRunState>;
+    }, devicePolicy?: Pick<DevicePolicyService, "summary">);
     /**
      * tools 节点：按顺序处理本步 assistant 消息里的全部 `tool_call`，每个调用都以一条 `tool_result` 结束
      * （之后才回到 prepare 构建下一次请求，保持「已记录调用、未记录结果之间不构建请求」的不变式）。
@@ -270,7 +307,7 @@ export declare class ToolPipeline {
      * 某个调用需要等人处理（审批 / 用户输入）→ 返回 `suspended`，之后的调用留到续跑时处理；
      * 续跑时重新进入本函数，按 PG 里的审批 / 输入请求结果继续。
      */
-    runStep(ctx: ToolStepContext): Promise<ToolStepOutcome>;
+    runStep(given: ToolStepContext): Promise<ToolStepOutcome>;
     /**
      * Writes, in the caller's transaction (`mandatory`), what a run that is being stopped (a person,
      * its deadline, a failure, the wait sweep) still owes its log: the report of its fork invocation
@@ -292,6 +329,16 @@ export declare class ToolPipeline {
      */
     private processCall;
     private runCall;
+    /**
+     * A foreground command's refused network hosts (network ask-to-allow spec §6.2, §6.8, §8.3):
+     * the `network_blocked` event, the missing grants of an unattended run, and either notes for the
+     * result written now, or (device-layer hosts worth asking) `network_blocked` and the call's
+     * `tool.called` audit written now, the result kept in a network ask to the device's owner and
+     * the run's wait. The kept result is the formatted one (≤ 16 KB: larger output is archived)
+     * followed by the notes written now; it is written with the decision's note when the ask
+     * settles (P-D2).
+     */
+    private networkBlocked;
     /** Appends a sub-agent's connect card to its root conversation ({@link rootSurfaceOf}). */
     private surfaceConnectInRoot;
     /**