@prismer/runtime 2.2.55 → 2.2.64

package/dist/index.d.ts

@@ -3,7 +3,8 @@ import Database from 'better-sqlite3';
 import { Options } from '@anthropic-ai/claude-agent-sdk';
 import { EventEmitter } from 'node:events';
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { Models, Model, Api } from '@earendil-works/pi-ai';
+import { AgentTool } from '@earendil-works/pi-agent-core/node';
+import { TextContent, ImageContent, Models, Model, Api } from '@earendil-works/pi-ai';
 import { Command } from 'commander';
 
 interface AssetRef {
@@ -402,6 +403,14 @@ interface ResolvedAssetRef extends AssetRef {
     base64?: string;
     reachable?: 'cdn' | 'base64' | 'unknown';
 }
+/**
+ * spec 11 T4-2 — hand-maintained mirror of the cloud canon
+ * (`src/im/types/im-events.ts`). The field-NAME set (incl. `?`; field TYPES
+ * are NOT in the nail's scope) MUST match canon; the one named exception is
+ * the runtime-only `projectId?` below (cloud retired the project dimension —
+ * see its field comment). Drift is nailed by
+ * `scripts/__tests__/dispatch-wire-mirror-parity.test.ts` (T0 CI tier).
+ */
 interface TaskDispatchRequestPayload {
     taskId: string;
     /**
@@ -558,6 +567,13 @@ interface TaskDispatchRequestPayload {
          */
         sections?: IdentitySection[];
     };
+    /**
+     * S6/M1 — capability bit. Only a cloud that understands multi-frame replies
+     * sets this (chat agent-run dispatches). Legacy clouds never carry it, so the
+     * daemon must never send interim frames on their behalf — "legacy cloud only
+     * ever sees the final frame" is carried by THIS field, not by the frames.
+     */
+    interimReply?: boolean;
 }
 /**
  * product204/07 Phase C — one named identityContext section. `content` is a
@@ -565,9 +581,13 @@ interface TaskDispatchRequestPayload {
  * does no templating, only order-sort + trim + join.
  */
 interface IdentitySection {
-    /** kebab-case, globally unique ('platform-directives' | 'config-directives' | 'per-turn-voice' | …). */
+    /** kebab-case, globally unique ('platform-directives' | 'config-directives' | 'per-turn-voice' | 'org-collaboration' | …). */
     id: string;
-    /** Owning product204 doc number ('07' | '09' | '03') — kept loose for forward compat. */
+    /**
+     * Owning doc number ('07' | '09' | '03' | 'product205/12' | 'bugfix211/B' |
+     * 'organization/04') — kept loose (cloud side is a closed union; this mirror
+     * stays `string` so an old daemon never rejects a section added later).
+     */
     owner: string;
     /** Render position; daemon stable-sorts ascending before joining. */
     order: number;
@@ -721,6 +741,10 @@ interface TaskDispatchReplyPayload {
     outboxRejections?: OutboxRejectionRecord[];
     /** product209 Phase 1: bounded pre-reply authoritative Memory outcome. */
     durability?: TaskDurabilityResult;
+    /** S6/M1 — 1-based position in this turn's reply stream; present on every frame of a multi-frame turn. */
+    seq?: number;
+    /** S6/M1 — false = interim commentary frame (I1 shape); true/absent = terminal frame. */
+    final?: boolean;
 }
 interface TaskCancelPayload {
     taskId: string;
@@ -1851,11 +1875,25 @@ interface AgentRunOptions {
 interface AgentUsage {
     inputTokens?: number;
     cachedInputTokens?: number;
+    /** PI cache creation tokens, separate from uncached input and cache reads. */
+    cacheWriteTokens?: number;
     outputTokens?: number;
     totalCostUsd?: number;
     contextWindowMaxTokens?: number;
     contextWindowUsedTokens?: number;
 }
+/** Measurements at the PI engine boundary, not a provider billing receipt. */
+interface ModelCallObservation {
+    sequence: number;
+    source: 'pi-engine';
+    provider: string;
+    model: string;
+    startedAt: number;
+    durationMs: number;
+    firstTextMs: number | null;
+    status: 'completed' | 'failed' | 'canceled';
+    usage: AgentUsage | null;
+}
 declare const TOOL_CALL_ICON_NAMES: readonly ["wrench", "square_terminal", "eye", "pencil", "search", "bot", "sparkles", "brain", "mic_vocal"];
 type ToolCallIconName = (typeof TOOL_CALL_ICON_NAMES)[number];
 type ToolCallDetail = {
@@ -2008,6 +2046,16 @@ type AgentTimelineItem = {
     message: string;
 } | CompactionTimelineItem;
 type AgentStreamEvent = {
+    type: 'model_request_started';
+    provider: AgentProvider;
+    startedAt: number;
+    turnId?: string;
+} | {
+    type: 'model_call_observed';
+    provider: AgentProvider;
+    call: ModelCallObservation;
+    turnId?: string;
+} | {
     type: "thread_started";
     sessionId: string;
     provider: AgentProvider;
@@ -2200,6 +2248,20 @@ interface AgentSessionConfig {
     sandboxMode?: string;
     networkAccess?: boolean;
     webSearch?: boolean;
+    /**
+     * Runtime turn tool declarations supplied by the cloud-side envelope.
+     *
+     * Omitted means provider default behavior. When present, runtime engines must
+     * fail closed to the declared, enabled tool set.
+     */
+    runtimeTools?: Array<{
+        name: string;
+        kind: "builtin" | "component" | string;
+        enabled?: boolean;
+        version?: string;
+        source?: string;
+        config?: Record<string, unknown>;
+    }>;
     extra?: {
         codex?: AgentMetadata;
         claude?: Partial<Options>;
@@ -2459,6 +2521,20 @@ interface TaskInput {
         message?: string;
         detail?: Record<string, unknown>;
     }) => void;
+    /**
+     * S6/M1 — mid-turn milestone narration relay (hermes v2026.9.14
+     * `assistant.commentary` SSE events). Invoked once per non-empty commentary
+     * segment, in stream order, with a per-turn 1-based `seq`. The final
+     * `TaskResult.output` stays the last `assistant.completed` — narration is
+     * never merged into it, and the callback is fire-and-forget: a throwing
+     * consumer must never break the SSE loop. Optional — adapters that don't
+     * relay commentary leave it undefined. Kill-switch:
+     * `HERMES_COMMENTARY_RELAY` (default on, explicit `false|0|off` disables).
+     */
+    onInterimReply?: (segment: {
+        text: string;
+        seq: number;
+    }) => void;
     signal?: AbortSignal;
     /**
      * Wave-3 D2 observability handles. Optional — pre-Wave-3 adapters that
@@ -2656,10 +2732,35 @@ interface TaskResult {
  * For Hermes this wraps an HTTP client to `hermes gateway`; for OpenClaw
  * (1.9.5+) it wraps an in-process TS worker.
  */
+/**
+ * S7 (spec 07 Task 1 / 裁决 B) — options for ONE dispatch CALL.
+ *
+ * The daemon's P2 retry loop is a single dispatch call: a transient failure
+ * retries the same intent. Anything the upstream uses to recognise a replay
+ * must therefore be identical across those attempts — a re-minted value turns
+ * the retry into a second, separately-billed execution.
+ *
+ * It is deliberately NOT the same axis as `TaskInput.metadata.attemptNo`,
+ * which exists to make LLM-proxy cache keys differ per attempt.
+ */
+interface DispatchCallOptions {
+    /**
+     * Minted ONCE by the daemon at the entry of a dispatch call and reused by
+     * every P2 attempt. A genuinely NEW dispatch call (cloud requeue, a fresh
+     * user action) mints a new one: replaying an already-closed run's terminal
+     * result is worse than running it again.
+     */
+    idempotencyNonce?: string;
+}
 interface AdapterService {
     /** Service-specific identifier (e.g. 'http://127.0.0.1:8642' for hermes). */
     id: string;
-    dispatch(task: TaskInput): Promise<TaskResult>;
+    /**
+     * `opts` is per-CALL, not per-task: adapters that talk to a replay-aware
+     * upstream read `idempotencyNonce` from it so every P2 retry of this call
+     * presents the same identity (see DispatchCallOptions).
+     */
+    dispatch(task: TaskInput, opts?: DispatchCallOptions): Promise<TaskResult>;
     healthy(): Promise<boolean>;
     /** Optional: stop the service. May be no-op if user owns lifecycle. */
     shutdown?(): Promise<void>;
@@ -2816,6 +2917,171 @@ declare const HermesProfileConfigSchema: z.ZodObject<{
 type HermesProfileConfig = z.infer<typeof HermesProfileConfigSchema>;
 declare const hermesAdapter: AdapterDef;
 
+/** Loopback only — the plugin binds 127.0.0.1, never a routable interface. */
+declare const BRIDGE_DEFAULT_HOST = "127.0.0.1";
+/** Plugin default when `PRISMER_PLATFORM_PORT` is unset (adapter.py `_port()`). */
+declare const BRIDGE_DEFAULT_PORT = 8788;
+declare const BRIDGE_DEFAULT_CONNECT_TIMEOUT_MS = 5000;
+declare const BRIDGE_DEFAULT_RECONNECT_DELAY_MS = 1000;
+/**
+ * Ceiling on the pending-line buffer. The plugin truncates content at 32 000
+ * chars (≈32× headroom here), so a longer line means the peer is not speaking
+ * this protocol — drop the buffer instead of growing it without bound.
+ */
+declare const BRIDGE_MAX_LINE_CHARS = 1048576;
+interface BridgeInboundFrame {
+    t: 'in';
+    conversation_id: string;
+    sender_id: string;
+    sender_name: string;
+    text: string;
+    message_id: string;
+    metadata: Record<string, unknown>;
+}
+interface BridgeOutboundFrame {
+    t: 'out';
+    chat_id: string;
+    content: string;
+    reply_to: string | null;
+    metadata: Record<string, unknown>;
+    message_id: string;
+    /** Non-null when the gateway reports a delivery failure for this reply. */
+    error: string | null;
+}
+interface BridgeInboundInput {
+    conversationId: string;
+    senderId: string;
+    senderName: string;
+    text: string;
+    /** Defaults to a fresh uuid; the caller keeps it to anchor `reply_to`. */
+    messageId?: string;
+    metadata?: Record<string, unknown>;
+}
+type BridgeFrameParse = {
+    ok: true;
+    frame: BridgeOutboundFrame;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Build the frame the plugin expects on the wire. Shape mirrors
+ * `adapter.py::_on_inbound` field-for-field — snake_case keys, `t` first.
+ */
+declare function buildInboundFrame(input: BridgeInboundInput): BridgeInboundFrame;
+/**
+ * Parse one outbound line into a usable frame.
+ *
+ * Strict on the two fields a reply cannot be routed without (`chat_id`,
+ * `content`); everything else normalises to its documented default. Gateway
+ * field drift must degrade to a still-usable frame rather than a dropped reply
+ * — `reply_to`/`metadata`/`message_id`/`error` are omitted defaults, not
+ * errors.
+ */
+declare function parseOutboundFrame(raw: string): BridgeFrameParse;
+interface BridgeProbeResult {
+    reachable: boolean;
+    host: string;
+    port: number;
+    latencyMs: number | null;
+    /** Node errno (`ECONNREFUSED`, …) when the dial failed at the OS level. */
+    code: string | null;
+    error: string | null;
+}
+interface BridgeProbeOptions {
+    port: number;
+    host?: string;
+    timeoutMs?: number;
+}
+/**
+ * Liveness probe: open a TCP connection and close it. The bridge protocol has
+ * no ping/pong frame, so reachability IS the health signal.
+ *
+ * NEVER rejects and never hangs — a missing bridge resolves
+ * `{ reachable: false, code: 'ECONNREFUSED' | 'ETIMEDOUT', error }` so callers
+ * get an explicit answer instead of an unhandled rejection.
+ */
+declare function probeBridge(options: BridgeProbeOptions): Promise<BridgeProbeResult>;
+type BridgeConnectionState = 'idle' | 'connecting' | 'connected' | 'closed';
+type BridgeSendResult = {
+    ok: true;
+    messageId: string;
+} | {
+    ok: false;
+    error: string;
+};
+interface BridgeClientOptions {
+    port: number;
+    host?: string;
+    connectTimeoutMs?: number;
+    /** Delay between reconnect attempts after an unexpected drop. */
+    reconnectDelayMs?: number;
+    /** Reconnect after a drop. Default true; `close()` always stops the loop. */
+    autoReconnect?: boolean;
+    /** Called for every parsed outbound frame. */
+    onOutbound: (frame: BridgeOutboundFrame) => void;
+    /** Called for every unparseable / wrong-shaped line. Never throws. */
+    onMalformed?: (raw: string, reason: string) => void;
+    onStateChange?: (state: BridgeConnectionState) => void;
+}
+/**
+ * Long-lived client for the bridge socket: dials, frames lines, reconnects on
+ * drop and surfaces the outbound stream to `onOutbound`.
+ *
+ * Nothing here throws asynchronously — a dead bridge shows up as a state
+ * change, a `log.warn`, a failed `sendInbound` result, or a rejected
+ * `waitForConnected`. There is no path that silently swallows a failure.
+ */
+declare class BridgeClient {
+    readonly host: string;
+    readonly port: number;
+    private readonly connectTimeoutMs;
+    private readonly reconnectDelayMs;
+    private readonly autoReconnect;
+    private readonly options;
+    private socket;
+    private started;
+    private state;
+    private reconnectTimer;
+    private connectTimer;
+    private lineBuffer;
+    private lastError;
+    private attempts;
+    private readonly waiters;
+    constructor(options: BridgeClientOptions);
+    get connectionState(): BridgeConnectionState;
+    get isConnected(): boolean;
+    /** Dial attempts so far (initial + reconnects). Diagnostics/tests only. */
+    get connectAttempts(): number;
+    /** Last dial/socket error, human-readable. Null before any failure. */
+    get lastConnectError(): string | null;
+    /** Begin dialing. Idempotent while started. */
+    start(): void;
+    /**
+     * Resolve once the socket is up, reject with an explicit error on timeout.
+     * Rejects immediately if the client was closed while waiting.
+     */
+    waitForConnected(timeoutMs?: number): Promise<void>;
+    /**
+     * Write one inbound frame. Never throws: a detached socket, a blank `text`
+     * (the gateway drops those silently) and a build failure all come back as
+     * `{ ok: false, error }`.
+     */
+    sendInbound(input: BridgeInboundInput): BridgeSendResult;
+    /**
+     * Stop for good: drop the socket, cancel the reconnect loop, reject anything
+     * still waiting on `waitForConnected`. Safe to call repeatedly.
+     */
+    close(): Promise<void>;
+    private setState;
+    private dial;
+    private onData;
+    private onLine;
+    private reportMalformed;
+    private clearReconnectTimer;
+    private clearConnectTimer;
+}
+
 /** Direct-connect provider families the daemon can route to (doc §2a). */
 declare const PROVIDER_PROFILE_TYPES: readonly ["anthropic", "openai", "deepseek", "ollama", "openai-compatible"];
 type ProviderProfileType = (typeof PROVIDER_PROFILE_TYPES)[number];
@@ -4541,6 +4807,17 @@ interface DispatchDeps {
      * in-flight run (the background path can't kill safely, so it only flags).
      */
     consumeSkillDirty?: (profileId: string) => boolean;
+    /**
+     * S5 §3.4-4b — re-arm a profile's skill-dirty flag. Counterpart of
+     * `consumeSkillDirty`: when the skill-sync respawn is DEFERRED because a turn
+     * is in flight, the pending change must survive to the next dispatch.
+     */
+    markSkillDirty?: (profileId: string) => void;
+    /**
+     * S5 §3.4-4b — does the profile's cached service have a turn in flight?
+     * Wired to `ServicePool.peek(id) instanceof HermesService && svc.busy`.
+     */
+    peekServiceBusy?: (profileId: string) => boolean;
     /** Aborts the in-flight adapter dispatch when cloud sends task.cancel. */
     signal?: AbortSignal;
     /** Hook for tests / observability. */
@@ -6766,10 +7043,179 @@ type CodexConfig = z.infer<typeof CodexConfigSchema>;
 declare function parseCodexOutput(stdout: string): string;
 declare const codexAdapter: AdapterDef;
 
+interface ComponentStageRequest {
+    schemaVersion: 1;
+    environmentId: string;
+    sandboxId: string;
+    bindingHash: string;
+    environmentEpoch: number;
+    operationId: string;
+    componentId: string;
+    generation: string;
+    attemptId: string;
+    source: string;
+    integrity: string;
+    policyRevision: string;
+    installerIdentity: string;
+    packageName: string;
+    version: string;
+    archiveSha256: string;
+    treeSha256: string;
+    tools: string[];
+    files: {
+        path: string;
+        bytes: number;
+        sha256: string;
+        contentBase64: string;
+    }[];
+}
+interface ComponentStageReceipt {
+    schemaVersion: 1;
+    status: 'staged';
+    environmentId: string;
+    sandboxId: string;
+    bindingHash: string;
+    environmentEpoch: number;
+    operationId: string;
+    componentId: string;
+    generation: string;
+    attemptId: string;
+    relativePath: string;
+    archiveSha256: string;
+    treeSha256: string;
+    diskBytes: number;
+    fileCount: number;
+    loader: {
+        kind: 'pi-extension';
+        entrypoint: string;
+        tools: string[];
+    };
+}
+type ComponentStageManifest = Omit<ComponentStageRequest, 'files'> & {
+    files: Array<Omit<ComponentStageRequest['files'][number], 'contentBase64'>>;
+};
+
+type ActiveTenantComponent = ComponentStageManifest & {
+    enabled: boolean;
+    relativePath: string;
+    loader: ComponentStageReceipt['loader'];
+};
+type TenantComponentContext = Pick<ComponentStageManifest, 'environmentId' | 'sandboxId' | 'bindingHash' | 'environmentEpoch'>;
+
+/** Untrusted turn selection, never an executable path or load authority. */
+interface TenantComponentReference {
+    componentId: string;
+    generation: string;
+    treeSha256: string;
+}
+/** Trusted host contract. Resolve from authenticated server state, never disk receipts/envelope config.
+ * authorize must check current owner grant, enabled generation, expiry/deletion, epoch,
+ * sandbox and binding on EVERY call. Offline/error/unknown must deny; no cached allow.
+ * Cloud sender/authorization transport is a separate integration, not implemented here.
+ */
+interface TenantComponentHost {
+    root: string;
+    context: TenantComponentContext;
+    components: ActiveTenantComponent[];
+    authorize(query: {
+        turnId: string;
+        context: TenantComponentContext;
+        component: ActiveTenantComponent;
+        phase: 'load' | 'invoke';
+        tool?: string;
+    }): Promise<boolean>;
+}
+interface TenantComponentSelection {
+    turnId: string;
+    components: TenantComponentReference[];
+}
+interface TenantComponentBinding extends TenantComponentSelection {
+    host: TenantComponentHost;
+}
+
+/**
+ * TurnEnvelopeV1 / TurnEgressV1 / TurnResultV2 — 「一次 turn」的 in-pod 文件协议
+ * （Gate B+ Task 7 design §2.4；MUST-1 起出口凭据走 `egress.json`；**v2** 起工具
+ * 活动走同目录的 `events.jsonl`、结果带 `tools[]` 终态汇总）。
+ *
+ * 形态：cloud 侧把 envelope 写进 `<turnDir>/input.json`（0600，**不含密钥**）；
+ * LLM 出口凭据写进同目录的 `egress.json`（0600，**turn 作用域短 TTL token**，不是
+ * owner 凭据——pod 内没有 provider key，模型调用经 cloud 的出口端点代理），本 CLI
+ * 跑完一轮后把 TurnResultV2 写进 `<output.json>`，turn 进行中逐行追加
+ * `events.jsonl`（0600）。投递文件**读完即删**。**stdout 不是数据通道**——引擎日志
+ * 会污染它；结果只走文件。
+ *
+ * exit code 契约（cloud 侧 exec 包装器按此判定）：
+ *   0  = output.json 已写（turn 跑完；里面可能是 status:"error"）
+ *   70 = 基建失败（bundle 缺 / node 崩 / 无 output）→ 端口映射 runtime_unavailable
+ *
+ * 命名：`TurnEnvelopeV1` / `TurnEgressV1` 是**形态族名**（v2 未改这两个文件的字节
+ * 形态，改动的是版本常量与结果面）；`TurnResultV2` 与 `ToolEventV1` 是各自形态的
+ * 版本——events 文件是 v2 新引入的产物，其行 schema 即该文件的首版（V1）。
+ *
+ * 校验纪律与 `src/tenant/contract.ts` 同族：手写 guard，违例抛
+ * `TurnProtocolError`（不静默补默认值——坏输入必须可见）。
+ */
+/**
+ * 协议版本（唯一合法值；不匹配 = 明确拒绝，不做兼容推断）。
+ *
+ * v2 = 工具事件（`events.jsonl` + `result.tools[]`）。旧 bundle（常量 = 1）收到 v2
+ * envelope 会在 `parseTurnEnvelope` 明确拒绝（exit 70 + 可见错误），不静默降级。
+ */
+
+/** 工具事件种类（§3.2：每工具调用两条）。 */
+type ToolEventKind = 'tool_started' | 'tool_finished';
+/**
+ * `events.jsonl` 的一行（§3.2 逐字段）。`seq` / `at` **由写侧赋值**：hook 只上报
+ * 原始测量值（`ToolEventInput`），seq 是「文件里的第几行」——由唯一写者按追加顺序
+ * 赋 1-based 单调值并打 ISO 时间戳，故 seq 顺序 ≡ 行序，轮询器据此去重。
+ */
+interface ToolEventV1 {
+    /**
+     * 1-based 单调序号（写侧赋值）。写侧达上限即**整条停写**（不跳号），故文件里恒为
+     * 连续 1..N；消费方仍按「≤ 已见 seq 即重复」去重（对重放/截断天然安全）。
+     */
+    seq: number;
+    /** 事件落盘时刻（写侧打戳，ISO）。 */
+    at: string;
+    kind: ToolEventKind;
+    /** 工具名（read / write / edit / bash）。 */
+    name: string;
+    /** 入参摘要（≤500 字符，已剥凭据）。 */
+    argsSummary?: string;
+    /** 结果摘要（≤500 字符，已剥凭据）。 */
+    resultSummary?: string;
+    isError?: boolean;
+    durationMs?: number;
+}
+/** 引擎 hook 上报的原始测量值——`seq` / `at` 归写侧（见 {@link ToolEventV1}）。 */
+type ToolEventInput = Omit<ToolEventV1, 'seq' | 'at'>;
+/** 工具事件 sink（引擎 → 写侧）；**只记录不拦截**，实现必须自吞异常。 */
+type ToolEventSink = (event: ToolEventInput) => void;
+
 declare const PI_CORE_PROVIDER: "pi-core";
 declare const DEFAULT_PI_GATEWAY_PROVIDER: "prismer";
 declare const DEFAULT_PI_GATEWAY_MODEL: "gemini-3.1-flash-lite-preview";
+interface PiCoreToolPolicy {
+    /** Exact bound tool names; absent allows all, an empty list allows none. */
+    allow?: readonly string[];
+    /** Exact bound tool names. Deny always wins over allow/authorize. */
+    deny?: readonly string[];
+    /** Trusted host authorization, checked per call. Only true permits execution. */
+    authorize?: (call: {
+        name: string;
+        args: unknown;
+        cwd: string;
+    }, signal?: AbortSignal) => boolean | Promise<boolean>;
+}
+interface PiCoreHistoryEntry {
+    role: "principal" | "agent";
+    content: string | Array<TextContent | ImageContent>;
+}
 interface PiAgentCoreClientOptions {
+    tenantComponents?: TenantComponentBinding;
+    /** Trusted host replay data; never executable tool calls or system messages. */
+    initialHistory?: readonly PiCoreHistoryEntry[];
     /** Test seam: callers can inject a scripted Models collection. */
     models?: Models;
     /** Test seam: pin a concrete model object instead of resolving by id. */
@@ -6778,12 +7224,35 @@ interface PiAgentCoreClientOptions {
     defaultProvider?: string;
     /** Preferred model when neither config.model nor gateway env chooses one. */
     defaultModelId?: string;
+    /**
+     * 会话级 shell 开关（design §3.1 修1，缺省 **false**）：true 时该 client 建出的
+     * 会话额外绑 bash 工具、解除 `exec()` 恒拒、放开 jail 内的 temp 文件。
+     *
+     * 缺省 false 是**刻意的爆炸半径控制**：pi-core 同时被 daemon（dispatch / runner /
+     * skill-sync）与 engine registry（`createPiCoreAdapter`）使用，全局绑 bash 会外溢到
+     * 桌面 / 本地 hosted agent。EaaS turn 显式传 true；daemon 侧是否解禁是独立决策。
+     */
+    allowShell?: boolean;
+    /** Execution gate, not a shell sandbox. Allowed bash retains container-level access. */
+    toolPolicy?: PiCoreToolPolicy;
+    /**
+     * 工具事件 sink（design §3.2；EaaS turn 注入）。只记录不授权；授权由独立的
+     * toolPolicy 执行，sink 失败不得改变授权结果。未配置策略时保留原执行行为。
+     */
+    onToolEvent?: ToolEventSink;
 }
 interface PiAgentCoreSessionOptions {
+    tenantTools?: AgentTool[];
+    initialHistory?: readonly PiCoreHistoryEntry[];
     config: AgentSessionConfig;
     model: Model<Api>;
     models: Models;
     launchEnv?: Record<string, string>;
+    /** 见 {@link PiAgentCoreClientOptions.allowShell}（缺省 false）。 */
+    allowShell?: boolean;
+    toolPolicy?: PiCoreToolPolicy;
+    /** 见 {@link PiAgentCoreClientOptions.onToolEvent}。 */
+    onToolEvent?: ToolEventSink;
 }
 declare class PiAgentCoreSession implements AgentSession {
     private readonly options;
@@ -6794,6 +7263,8 @@ declare class PiAgentCoreSession implements AgentSession {
     private readonly tools;
     private readonly subscribers;
     private readonly toolArgs;
+    /** 工具事件面的起表（toolCallId → 开始时刻）；与 `toolArgs`（timeline 用）互不依赖。 */
+    private readonly toolStartedAt;
     private activeRun;
     constructor(options: PiAgentCoreSessionOptions);
     run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult>;
@@ -6813,6 +7284,7 @@ declare class PiAgentCoreSession implements AgentSession {
     close(): Promise<void>;
     listCommands(): Promise<AgentSlashCommand[]>;
     private emit;
+    private emitObservation;
     private recordTimeline;
     private handlePiEvent;
     private handleMessageEvent;
@@ -6882,6 +7354,13 @@ interface HermesBundleConfig {
     model: string;
     /** Optional per-profile/per-role model overrides (desktop multi-workspace). */
     models?: Record<string, string>;
+    /**
+     * Model id → authoritative context window (tokens). Written to
+     * `~/.hermes/config.yaml` as `custom_providers[].models.<id>.context_length`
+     * — Hermes' step-0 config override, which short-circuits the per-turn
+     * endpoint-probe pipeline for context-length resolution.
+     */
+    modelContextLengths?: Record<string, number>;
 }
 type MemoryRuntimeCapabilityV1 = 'memory-authority-snapshot-v1' | 'memory-replica-manifest-v1' | 'memory-replica-content-v1';
 /** Server-derived actor authority row. Cloud generates; daemon NEVER submits. */
@@ -7090,4 +7569,4 @@ interface DrainBeforeKillResult {
  */
 declare function drainBeforeGatewayKill(opts?: DrainBeforeKillOptions): Promise<DrainBeforeKillResult>;
 
-export { ADMIN_OBSERVABILITY_REQUEST_MAX_BYTES, ADMIN_OBSERVABILITY_RESPONSE_MAX_BYTES, type AcquireResult, type AdapterDef, type AdapterKind, AdapterRegistry, type AdapterService, type AgentChangedPayload, type AgentDispatchReplyAttachment, type AgentDispatchReplyContentBlockInput, type AgentDispatchReplyContentBlockToolResultInput, type AgentDispatchReplyPayload, type AgentDispatchReplyPkfContentBlock, type AgentDispatchReplyPkfContentBlockInput, type AgentDispatchReplyStatus, type AgentDispatchRequest, type AgentDispatchResponse, type AgentHostDeclarePayload, type AgentProfile, type AgentProfileChangedPayload, type AgentStatusChangedPayload, AssetCache, type AssetCacheOptions, type AssetChangedPayload, type AssetDispatchObservation, type AssetDispatchStrategy, type AssetRef, type AttachAdminObservabilityRpcOptions, type AttachMirrorRpcOptions, BOOTSTRAP_BACKOFF_MS, BUILTIN_ROLE_TEMPLATES, type BootstrapFetchOptions, type BootstrapFetchResult, type BootstrapRequest, type BootstrapResponse, type BootstrapState, type BootstrapStopReason, type BundleApplyResult, type CachedAsset, type ClaudeCodeConfig, CloudClient, type CloudClientOptions, CloudError, type CloudResponse, type CodexConfig, type Config, type ConfigApplyState, type ConfigPaths, ConfigSchema, DEFAULT_PI_GATEWAY_MODEL, DEFAULT_PI_GATEWAY_PROVIDER, DEFAULT_REMOTE_ALLOWLIST, type DispatchDeps, type DrainBeforeKillOptions, type DrainBeforeKillResult, type EditCheckResult, type Envelope, type FlushFn, type FlushResult, GIT_RPC_OPS, type GatewayConfig, type GatewayDeps, type GitExecPayload, type GitExecReply, GitRpcError, type GitRpcErrorCode, type GitRpcOp, type GitRpcRequest, type GitRpcResult, type HealthStatus, type HermesBundleConfig, type HermesProfileConfig, type HermesProviderConfig, type HostAckedPayload, type HostedAgentDeclaration, type IMAgentStatus, type IMWSMessage, type KeyRefResolver, LOCAL_PROVIDER_PREFIX, type LocalDb, LocalGateway, LocalRelay, LocalServer, type LocalServerOptions, type LocalServerState, type LocalSyncEvent, type MaterializeResult$1 as MaterializeResult, Materializer, type MaterializerDeps, type MessageDispatchAgent, type MessageDispatchDeps, type MessageDispatchHandle, type MessageDispatchTaskInput, type MirrorAssetDescriptor, type MirrorEntry, MirrorManager, type MirrorManagerOptions, type NormalizedContent, type OllamaProbeResult, PI_CORE_PROVIDER, PROVIDER_PROFILE_TYPES, type PairOptions, type PairResult, type ParseClaim, ParseClaimController, type ParseClaimControllerOptions, type ParsedPrismerUri, PiAgentCoreClient, type PiAgentCoreClientOptions, PiAgentCoreSession, type PiCoreConfig, type PrismerUriType, type ProviderProfile, ProviderProfileSchema, type ProviderProfileType, RM_SCHEMA_VERSION, type RawWsEvent, type RejectedHostedAgent, type ResolvedLocalProvider, type RmDomain, type RmSyncStatus, type RoleTemplate, Runner, type RunnerOptions, type RuntimeConfigBundle, type AgentDispatchReplyPkfContentBlockInput as RuntimePkfContentBlockInput, SWR_TTL_MS, ServicePool, type SyncOperation, SyncQueue, type SyncQueueRow, type SyncResourceType, type SyncStatus, SyncWorker, type SyncWorkerOptions, TARGET_SCHEMA_VERSION, type TakeAdminObservabilityCloudInput, type TaskCancelPayload, type TaskDispatchContextEntry, type TaskDispatchProgressPayload, type TaskDispatchReplyPayload, type TaskDispatchRequestPayload, type TaskInput, type TaskResult, UriResolver, type UriResolverOptions, type UrlResolution, type ValidationResult, WS_CLOSE, type WorkspaceChangedPayload, type WorkspaceFileBinding, type WorkspaceFileChangedPayload, WorkspaceMirror, type WorkspaceMirrorOptions, type WorkspaceNameResolver, WsClient, type WsClientOptions, applyBundle, attachAdminObservabilityRpc, attachMirrorRpc, buildProgram, claudeCodeAdapter, codexAdapter, composePrompt, computeBootstrapErrorAction, configExists, createBootstrapState, createPiCoreAdapter, currentSchemaVersion, deriveWsUrl, drainBeforeGatewayKill, effectiveBaseUrl, envelope, extractHttpUrls, fetchBootstrapBundle, getLocalProviders, getRoleTemplate, gitRpc, handleAgentMessageDispatch, handleDispatch, hermesAdapter, isDaemonId, isLocalProviderSelector, isValidBundle, keyRefEnvVar, listRoleTemplates, loadConfig, localProviderProfileId, newDaemonId, nextBackoffMs, nextBootstrapBackoffMs, openLocalDb, openReadModel, pair, parseCodexOutput, parseUris, piCoreAdapter, probeOllama, providerTypeRequiresKey, remoteAllowlistFromEnv, resetBootstrapStopped, resolveGatewayConfig, resolveGitCwd, resolveKeyRef, resolveLocalProvider, resolvePaths, runCli, runGitExecRequest, runMigrations, sanitizeSegment, saveConfig, setKeyRefResolver, setLocalProviders, takeAdminObservabilityCloud, toApplyState };
+export { ADMIN_OBSERVABILITY_REQUEST_MAX_BYTES, ADMIN_OBSERVABILITY_RESPONSE_MAX_BYTES, type AcquireResult, type AdapterDef, type AdapterKind, AdapterRegistry, type AdapterService, type AgentChangedPayload, type AgentDispatchReplyAttachment, type AgentDispatchReplyContentBlockInput, type AgentDispatchReplyContentBlockToolResultInput, type AgentDispatchReplyPayload, type AgentDispatchReplyPkfContentBlock, type AgentDispatchReplyPkfContentBlockInput, type AgentDispatchReplyStatus, type AgentDispatchRequest, type AgentDispatchResponse, type AgentHostDeclarePayload, type AgentProfile, type AgentProfileChangedPayload, type AgentStatusChangedPayload, AssetCache, type AssetCacheOptions, type AssetChangedPayload, type AssetDispatchObservation, type AssetDispatchStrategy, type AssetRef, type AttachAdminObservabilityRpcOptions, type AttachMirrorRpcOptions, BOOTSTRAP_BACKOFF_MS, BRIDGE_DEFAULT_CONNECT_TIMEOUT_MS, BRIDGE_DEFAULT_HOST, BRIDGE_DEFAULT_PORT, BRIDGE_DEFAULT_RECONNECT_DELAY_MS, BRIDGE_MAX_LINE_CHARS, BUILTIN_ROLE_TEMPLATES, type BootstrapFetchOptions, type BootstrapFetchResult, type BootstrapRequest, type BootstrapResponse, type BootstrapState, type BootstrapStopReason, BridgeClient, type BridgeClientOptions, type BridgeConnectionState, type BridgeFrameParse, type BridgeInboundFrame, type BridgeInboundInput, type BridgeOutboundFrame, type BridgeProbeOptions, type BridgeProbeResult, type BridgeSendResult, type BundleApplyResult, type CachedAsset, type ClaudeCodeConfig, CloudClient, type CloudClientOptions, CloudError, type CloudResponse, type CodexConfig, type Config, type ConfigApplyState, type ConfigPaths, ConfigSchema, DEFAULT_PI_GATEWAY_MODEL, DEFAULT_PI_GATEWAY_PROVIDER, DEFAULT_REMOTE_ALLOWLIST, type DispatchDeps, type DrainBeforeKillOptions, type DrainBeforeKillResult, type EditCheckResult, type Envelope, type FlushFn, type FlushResult, GIT_RPC_OPS, type GatewayConfig, type GatewayDeps, type GitExecPayload, type GitExecReply, GitRpcError, type GitRpcErrorCode, type GitRpcOp, type GitRpcRequest, type GitRpcResult, type HealthStatus, type HermesBundleConfig, type HermesProfileConfig, type HermesProviderConfig, type HostAckedPayload, type HostedAgentDeclaration, type IMAgentStatus, type IMWSMessage, type KeyRefResolver, LOCAL_PROVIDER_PREFIX, type LocalDb, LocalGateway, LocalRelay, LocalServer, type LocalServerOptions, type LocalServerState, type LocalSyncEvent, type MaterializeResult$1 as MaterializeResult, Materializer, type MaterializerDeps, type MessageDispatchAgent, type MessageDispatchDeps, type MessageDispatchHandle, type MessageDispatchTaskInput, type MirrorAssetDescriptor, type MirrorEntry, MirrorManager, type MirrorManagerOptions, type NormalizedContent, type OllamaProbeResult, PI_CORE_PROVIDER, PROVIDER_PROFILE_TYPES, type PairOptions, type PairResult, type ParseClaim, ParseClaimController, type ParseClaimControllerOptions, type ParsedPrismerUri, PiAgentCoreClient, type PiAgentCoreClientOptions, PiAgentCoreSession, type PiCoreConfig, type PrismerUriType, type ProviderProfile, ProviderProfileSchema, type ProviderProfileType, RM_SCHEMA_VERSION, type RawWsEvent, type RejectedHostedAgent, type ResolvedLocalProvider, type RmDomain, type RmSyncStatus, type RoleTemplate, Runner, type RunnerOptions, type RuntimeConfigBundle, type AgentDispatchReplyPkfContentBlockInput as RuntimePkfContentBlockInput, SWR_TTL_MS, ServicePool, type SyncOperation, SyncQueue, type SyncQueueRow, type SyncResourceType, type SyncStatus, SyncWorker, type SyncWorkerOptions, TARGET_SCHEMA_VERSION, type TakeAdminObservabilityCloudInput, type TaskCancelPayload, type TaskDispatchContextEntry, type TaskDispatchProgressPayload, type TaskDispatchReplyPayload, type TaskDispatchRequestPayload, type TaskInput, type TaskResult, UriResolver, type UriResolverOptions, type UrlResolution, type ValidationResult, WS_CLOSE, type WorkspaceChangedPayload, type WorkspaceFileBinding, type WorkspaceFileChangedPayload, WorkspaceMirror, type WorkspaceMirrorOptions, type WorkspaceNameResolver, WsClient, type WsClientOptions, applyBundle, attachAdminObservabilityRpc, attachMirrorRpc, buildInboundFrame, buildProgram, claudeCodeAdapter, codexAdapter, composePrompt, computeBootstrapErrorAction, configExists, createBootstrapState, createPiCoreAdapter, currentSchemaVersion, deriveWsUrl, drainBeforeGatewayKill, effectiveBaseUrl, envelope, extractHttpUrls, fetchBootstrapBundle, getLocalProviders, getRoleTemplate, gitRpc, handleAgentMessageDispatch, handleDispatch, hermesAdapter, isDaemonId, isLocalProviderSelector, isValidBundle, keyRefEnvVar, listRoleTemplates, loadConfig, localProviderProfileId, newDaemonId, nextBackoffMs, nextBootstrapBackoffMs, openLocalDb, openReadModel, pair, parseCodexOutput, parseOutboundFrame, parseUris, piCoreAdapter, probeBridge, probeOllama, providerTypeRequiresKey, remoteAllowlistFromEnv, resetBootstrapStopped, resolveGatewayConfig, resolveGitCwd, resolveKeyRef, resolveLocalProvider, resolvePaths, runCli, runGitExecRequest, runMigrations, sanitizeSegment, saveConfig, setKeyRefResolver, setLocalProviders, takeAdminObservabilityCloud, toApplyState };