@springbrand/agent-runtime 0.1.3-alpha.1 → 0.1.3-alpha.10

package/src/kernel/recoverable-chat-agent.ts

@@ -73,15 +73,15 @@ export type RuntimeRecoveryDecision<Data> =
   | { readonly kind: "ignore"; readonly reason: string };
 
 /**
- * 记录一次已执行恢复的最终结果。
+ * 记录一次已执行恢复的结果，或表明该恢复已接力给下一次持久调度。
  *
  * @remarks
- * `_chatRecoveryRetry` 在调用端口的 `retry` 后读取该结果，并用它关闭对应的恢复事故。
+ * `_chatRecoveryRetry` 在调用端口的 `retry` 后读取该结果；终态关闭事故，`scheduled` 保持事故活跃。
  *
  * 只有失败时才需要 `error`；结果不承载流内容，避免在调度数据与流缓冲区之间复制状态。
  */
 export interface RuntimeRecoveryResult {
-  readonly status: "completed" | "failed";
+  readonly status: "completed" | "scheduled" | "failed";
   readonly error?: string;
 }
 
@@ -103,7 +103,7 @@ export interface RuntimeRecoveryPort<Data> {
   /**
    * 使用已分类的业务数据重放一次对话。
    *
-   * @remarks 持久调度回调会调用它；实现应返回权威终态，而不是仅表示重试已启动。
+   * @remarks 持久调度回调会调用它；实现应返回权威终态，或明确说明下一次恢复已经持久调度。
    */
   retry(data: Data): Promise<RuntimeRecoveryResult>;
   /**
@@ -353,7 +353,13 @@ export abstract class RecoverableChatAgent<
    * 清理延后执行，为断线重连的客户端保留终态流片段。
    */
   protected completeRecoverableStream(streamId: string): void {
+    const completedRequestId = this.resumableStream.activeRequestId;
     this.resumableStream.complete(streamId);
+    this.pendingResumeConnections.clear();
+    if (completedRequestId === this.continuation.activeRequestId) {
+      this.continuation.activeRequestId = null;
+      this.continuation.activeConnectionId = null;
+    }
     void this.ensureStreamCleanupScheduled();
   }
 
@@ -366,7 +372,13 @@ export abstract class RecoverableChatAgent<
    * 流错误标志与业务失败分开，因为续传协议和提交生命周期的责任不同。
    */
   protected failRecoverableStream(streamId: string): void {
+    const erroredRequestId = this.resumableStream.activeRequestId;
     this.resumableStream.markError(streamId);
+    this.pendingResumeConnections.clear();
+    if (erroredRequestId === this.continuation.activeRequestId) {
+      this.continuation.activeRequestId = null;
+      this.continuation.activeConnectionId = null;
+    }
     void this.ensureStreamCleanupScheduled();
   }
 
@@ -465,13 +477,20 @@ export abstract class RecoverableChatAgent<
    * @remarks
    * 子类在发送增量记录、成功终态或失败终态时调用；`done` 表示轮次终态，`error` 只在终态失败时设置。
    *
+   * `continuation` 必须与本轮 `runRecoverableChatFiber` 的取值一致。重放帧由
+   * `ResumableStream` 从 `is_continuation` 列自动补上这个标记，实时帧只能由调用方给出：
+   * 少了它，客户端会为续跑另建一个空的累加器，把已经渲染出来的那半条回答整条换掉。
+   *
    * 广播显式排除正在续传握手的连接，避免它们在历史流重放完成前同时收到实时帧。
    */
   protected sendChatResponse(
     requestId: string,
     body: string,
     done: boolean,
-    error = false,
+    options: {
+      readonly error?: boolean;
+      readonly continuation?: boolean;
+    } = {},
   ): void {
     this.broadcast(
       json({
@@ -479,7 +498,8 @@ export abstract class RecoverableChatAgent<
         id: requestId,
         body,
         done,
-        ...(error ? { error: true } : {}),
+        ...(options.error ? { error: true } : {}),
+        ...(options.continuation ? { continuation: true } : {}),
       }),
       [...this.pendingResumeConnections],
     );
@@ -544,6 +564,7 @@ export abstract class RecoverableChatAgent<
     this.activeRecoveryRootRequestId = data.requestId;
     try {
       const result = await this.recoveryPort().retry(data);
+      if (result.status === "scheduled") return;
       await this.engine().updateIncident(
         data.incidentId,
         result.status === "completed" ? "completed" : "failed",
@@ -563,6 +584,83 @@ export abstract class RecoverableChatAgent<
     }
   }
 
+  /**
+   * 把活跃进程内检测到的模型流停滞交给同一套持久恢复预算。
+   *
+   * @remarks
+   * 子类在确认当前 Turn 可以从 durable checkpoint 重放后调用；`beforeSchedule`
+   * 必须先结束旧流并恢复权威消息快照，随后引擎才广播 recovering 状态。
+   */
+  protected async scheduleChatRecoveryRetry(
+    data: RecoveryData,
+    beforeSchedule: () => void | Promise<void>,
+  ): Promise<"disabled" | "scheduled" | "exhausted"> {
+    if (!resolveChatRecoveryConfig(this.chatRecovery).enabled) {
+      return "disabled";
+    }
+    const recoveryRootRequestId =
+      this.activeRecoveryRootRequestId ?? data.requestId;
+    const { incident, exhausted } = await this.engine().beginIncident({
+      requestId: data.requestId,
+      recoveryRootRequestId,
+      recoveryKind: "retry",
+    });
+    await beforeSchedule();
+    if (exhausted) {
+      await this.engine().exhaustRecoveryGiveUp({
+        callback: "_chatRecoveryRetry",
+        data: {
+          incidentId: incident.incidentId,
+          originalRequestId: recoveryRootRequestId,
+        },
+        reason: incident.reason ?? "max_attempts_exceeded",
+      });
+      return "exhausted";
+    }
+    await this.engine().scheduleRecovery({
+      incident,
+      recoveryKind: "retry",
+      callback: "_chatRecoveryRetry",
+      data: {
+        ...data,
+        incidentId: incident.incidentId,
+      },
+      reason: this.activeRecoveryRootRequestId
+        ? "stable_timeout_retry"
+        : "initial",
+    });
+    return "scheduled";
+  }
+
+  /** 终态化一个 Turn 时取消同请求的恢复调度，并关闭恢复事故与客户端状态。 */
+  protected async settleChatRecovery(
+    requestId: string,
+    status: "completed" | "skipped" | "failed",
+    reason?: string,
+  ): Promise<void> {
+    const incidentIds = new Set<string>();
+    try {
+      for (const schedule of await this.listSchedules()) {
+        if (schedule.callback !== "_chatRecoveryRetry") continue;
+        const payload = schedule.payload;
+        if (!payload || typeof payload !== "object") continue;
+        const recovery = payload as Partial<
+          RecoveryScheduleData<RecoveryData>
+        >;
+        if (recovery.requestId !== requestId) continue;
+        if (typeof recovery.incidentId === "string") {
+          incidentIds.add(recovery.incidentId);
+        }
+        await this.cancelSchedule(schedule.id);
+      }
+      for (const incidentId of incidentIds) {
+        await this.engine().updateIncident(incidentId, status, reason);
+      }
+    } finally {
+      await this.setRecovering(false, requestId);
+    }
+  }
+
   /**
    * 把 Agents SDK 发现的孤立 Fiber 交给聊天恢复引擎。
    *

package/src/kernel/runtime-assembly-view.ts

@@ -0,0 +1,37 @@
+import type { RuntimeDegradation } from "./degradation";
+import type {
+  RuntimeMemoryProfile,
+  RuntimeMcpServer,
+  ThinkingEffort,
+} from "./profile";
+import type { ExecutionLevel } from "../lib/execution-level";
+
+export interface RuntimeAssemblySkillBinding {
+  readonly name: string;
+  readonly description: string;
+  readonly script: {
+    readonly network: "none" | "full";
+    readonly workspace: "none" | "read" | "read-write";
+    readonly tools: readonly string[];
+  };
+}
+
+export interface RuntimeAssemblyExtension {
+  readonly name: string;
+  readonly version: string;
+}
+
+export interface RuntimeAssemblyView {
+  readonly revision: string | null;
+  readonly model: string;
+  readonly thinking: ThinkingEffort;
+  readonly executionLevel: ExecutionLevel;
+  readonly systemPrompt?: string;
+  readonly memory: RuntimeMemoryProfile;
+  readonly toolDeny: readonly string[];
+  readonly skills: readonly RuntimeAssemblySkillBinding[];
+  readonly extensions: readonly RuntimeAssemblyExtension[];
+  readonly subagents: readonly string[];
+  readonly mcpServers: readonly RuntimeMcpServer[];
+  readonly degradations: readonly RuntimeDegradation[];
+}

package/src/kernel/runtime-assembly.ts

@@ -0,0 +1,41 @@
+import type { RuntimeSnapshot } from "../runtime-assembler";
+import type { PreparedPiRuntime } from "../pi/runtime-adapter";
+import type { RuntimeAssemblyView } from "./runtime-assembly-view";
+export type * from "./runtime-assembly-view";
+
+/**
+ * Serializable view of the Runtime Snapshot currently installed on a Session facet.
+ *
+ * @remarks
+ * UI debug panels and Host tooling call `getRuntimeAssembly` to read what the
+ * Agent actually assembled, not what upstream configuration merely declared.
+ */
+export function projectRuntimeAssembly(
+  snapshot: RuntimeSnapshot,
+  revision: string | null,
+  prepared: Pick<PreparedPiRuntime, "degradations" | "extensions">,
+): RuntimeAssemblyView {
+  const { profile, bindings } = snapshot;
+  return {
+    revision,
+    model: profile.model,
+    thinking: profile.thinking,
+    executionLevel: profile.executionLevel,
+    ...(profile.systemPrompt ? { systemPrompt: profile.systemPrompt } : {}),
+    memory: { ...profile.memory },
+    toolDeny: [...(profile.denyPolicy?.deny ?? [])],
+    skills: bindings.skills.sources.map((binding) => ({
+      name: binding.name,
+      description: binding.description,
+      script: {
+        network: binding.script.network,
+        workspace: binding.script.workspace,
+        tools: [...binding.script.tools],
+      },
+    })),
+    extensions: prepared.extensions.map((extension) => ({ ...extension })),
+    subagents: [...profile.enabledSubagents],
+    mcpServers: profile.mcpServers.map((server) => ({ ...server })),
+    degradations: prepared.degradations.map((degradation) => ({ ...degradation })),
+  };
+}

package/src/kernel/runtime-config.ts

@@ -0,0 +1,4 @@
+export interface RuntimeConfigUpdateResult<Change> {
+  readonly change: Change;
+  readonly runtime: "unchanged" | "reloaded" | "reload-failed";
+}

package/src/kernel/runtime-load.ts

@@ -0,0 +1,191 @@
+import type { RuntimeLoadPhase, RuntimeLoadState } from "./state";
+
+/** Hard ceiling for one Host-owned Runtime definition phase. */
+export const RUNTIME_LOAD_TIMEOUT_MS = 180_000;
+
+/** Hard ceiling for one optional external capability load. */
+export const RUNTIME_CAPABILITY_LOAD_TIMEOUT_MS = 60_000;
+
+const reportedFailures = new WeakSet<object>();
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Emit one stable structured record for a Runtime load failure. */
+export function logRuntimeLoadFailure(
+  step: string,
+  error: unknown,
+  details: {
+    reason?: "error" | "timeout";
+    timeoutMs?: number;
+    durationMs?: number;
+  } = {},
+): void {
+  if (typeof error === "object" && error !== null) {
+    if (reportedFailures.has(error)) return;
+    reportedFailures.add(error);
+  }
+  console.error(
+    "[runtime-load:failed]",
+    JSON.stringify({
+      step,
+      reason: details.reason ?? "error",
+      ...(details.timeoutMs !== undefined
+        ? { timeoutMs: details.timeoutMs }
+        : {}),
+      ...(details.durationMs !== undefined
+        ? { durationMs: details.durationMs }
+        : {}),
+      error: errorText(error),
+    }),
+  );
+}
+
+/** Stop waiting for one Runtime load boundary and report any failure once. */
+export async function withRuntimeLoadTimeout<T>(
+  step: string,
+  load: () => T | PromiseLike<T>,
+  options: {
+    timeoutMs?: number;
+    onLateResult?: (value: T) => void | Promise<void>;
+  } = {},
+): Promise<T> {
+  const timeoutMs = options.timeoutMs ?? RUNTIME_CAPABILITY_LOAD_TIMEOUT_MS;
+  const startedAt = Date.now();
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  const operation = Promise.resolve().then(load);
+
+  if (options.onLateResult) {
+    void operation.then(async (value) => {
+      if (timedOut) await options.onLateResult!(value);
+    }, () => undefined).catch((error) => {
+      logRuntimeLoadFailure(`${step}:late-cleanup`, error);
+    });
+  }
+
+  try {
+    return await Promise.race([
+      operation,
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => {
+          timedOut = true;
+          reject(new Error(
+            `Runtime load step "${step}" timed out after ${timeoutMs}ms`,
+          ));
+        }, timeoutMs);
+      }),
+    ]);
+  } catch (error) {
+    logRuntimeLoadFailure(step, error, {
+      reason: timedOut ? "timeout" : "error",
+      timeoutMs,
+      durationMs: Date.now() - startedAt,
+    });
+    throw error;
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout);
+  }
+}
+
+/**
+ * 装载状态机与宿主之间的全部接触面。
+ *
+ * @remarks
+ * 只有这三项：读上一次发布的状态、发布新状态、回答旧 Runtime 是否仍可服务。
+ * 追踪器碰不到 Kernel 的 Snapshot、数据库或 Submission，因此它的行为可以脱离
+ * Durable Object 单独验证。
+ */
+export interface RuntimeLoadPort {
+  read(): RuntimeLoadState | undefined;
+  publish(next: RuntimeLoadState): void;
+  /** 旧 Runtime 是否仍在服务；强制重载失败时它可能仍为 true。 */
+  isAvailable(): boolean;
+}
+
+/**
+ * 维护一次 Runtime 装载尝试的公开状态机。
+ *
+ * @remarks
+ * 宿主在装载的各个边界调用 `begin` / `advance` / `complete` / `fail`，
+ * 由本类统一发布 `RuntimeLoadState` 的形状与时间戳。
+ *
+ * `startedAt` 表示一次尝试的开始时刻：`begin` 重置它，其余转移沿用它，
+ * 使前端可以按同一基准显示耗时。
+ */
+export class RuntimeLoadTracker {
+  constructor(
+    private readonly port: RuntimeLoadPort,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  // 作用：把状态清回未装载。
+  // 调用：Durable Object 启动时调用。
+  // 原因：实例刚被唤醒时没有任何在途尝试，旧记录里的 ready 不能继续对外承诺。
+  reset(): void {
+    this.port.publish({ status: "idle", available: false });
+  }
+
+  // 作用：开始一轮新的装载尝试。
+  // 调用：宿主在调用 Definition config.read 前调用。
+  // 原因：config 阶段可能包含身份、D1 和 Resource 解析，必须在首个慢请求前可见。
+  begin(): void {
+    const now = this.now();
+    this.port.publish({
+      status: "loading",
+      phase: "config",
+      available: this.port.isAvailable(),
+      startedAt: now,
+      updatedAt: now,
+    });
+  }
+
+  // 作用：推进当前装载尝试的阶段。
+  // 调用：宿主在进入 Assembly、MCP 和 Pi 边界时调用。
+  // 原因：保持一个稳定的粗粒度协议，不向前端泄漏具体能力准备和并发细节。
+  advance(phase: RuntimeLoadPhase): void {
+    const now = this.now();
+    this.port.publish({
+      status: "loading",
+      phase,
+      available: this.port.isAvailable(),
+      startedAt: this.startedAt(now),
+      updatedAt: now,
+    });
+  }
+
+  // 作用：把成功提交的装载尝试标记为可用。
+  // 调用：宿主在配置初始化和 Runtime key 提交完成后调用。
+  // 原因：只有完整原子提交后才能向客户端承诺 ready。
+  complete(): void {
+    const now = this.now();
+    this.port.publish({
+      status: "ready",
+      available: true,
+      startedAt: this.startedAt(now),
+      completedAt: now,
+    });
+  }
+
+  // 作用：记录装载失败，同时保留旧 Runtime 是否仍可用的信息。
+  // 调用：宿主收口 Config 读取或 Runtime 装配异常时调用。
+  // 原因：前端需要状态但不应接收可能包含存储细节的底层错误文本。
+  fail(): void {
+    const now = this.now();
+    const current = this.port.read();
+    this.port.publish({
+      status: "error",
+      phase: current?.status === "loading" ? current.phase : "config",
+      available: this.port.isAvailable(),
+      startedAt: this.startedAt(now),
+      failedAt: now,
+    });
+  }
+
+  // 同一轮尝试内沿用原开始时刻；不在装载中说明这是一次孤立转移，只能以当下为准。
+  private startedAt(now: number): number {
+    const current = this.port.read();
+    return current?.status === "loading" ? current.startedAt : now;
+  }
+}

package/src/kernel/state.ts

@@ -1,11 +1,18 @@
 import type { ApprovalReceipt } from "./receipts";
 
-export type RuntimeLoadPhase = "config" | "plugins" | "mcp" | "pi";
+export type RuntimeLoadPhase = "config" | "assembly" | "mcp" | "pi";
 
 export type RuntimeActivity = "idle" | "working" | "needs-input";
 
 export interface RuntimeActivityProjection {
   activity: RuntimeActivity;
+  /**
+   * 是否仍有 Agent Tool 子运行在执行。
+   *
+   * `activity` 三态互斥，表达不了「等人回应的同时后台还在跑」。Host 的列表需要
+   * 这两件事各自成立，所以它是一个独立维度，而不是第四种活动值。
+   */
+  backgroundWork: boolean;
   revision: number;
 }
 
@@ -51,6 +58,10 @@ export interface RuntimeQueuedSubmission {
 
 export interface RuntimeTurnState {
   activeSubmissionId?: string;
+  activeRequestId?: string;
+  recoveryAttempt?: number;
+  recoveryMax?: number;
+  recoveryReason?: "no_meaningful_model_progress" | "transient_model_error";
   steerable: boolean;
   hasPendingSteer: boolean;
   queued: RuntimeQueuedSubmission[];

package/src/kernel/submission-lifecycle.ts

@@ -202,6 +202,13 @@ interface SubmissionLifecycleOptions<
   // 调用：`cancel` 命中活动执行器，或 `activate` 发现早到取消时调用。
   // 原因：生命周期不依赖具体执行器类型，只通过这个回调中断。
   abortActive(active: TActive): void;
+  /**
+   * 中断活动执行器，但让这条提交留给持久续跑接手。
+   *
+   * `interrupt` 调用。与 `abortActive` 的差别在结局而不在动作：中断不写终态，
+   * 也不接受这条执行器退场路上产生的任何工具结算。
+   */
+  interruptActive(active: TActive): void;
 }
 
 // #endregion
@@ -528,6 +535,29 @@ export class SubmissionLifecycle<
     };
   }
 
+  /**
+   * 中断一条提交的活动执行器，但不写取消原因，也不写终态。
+   *
+   * @remarks
+   * 宿主在 park 期间换掉装配后调用：内存里那条执行器的系统提示和工具表锁在它
+   * 自己被创建的那一刻，续跑不可能带上新能力，必须让位给持久续跑路径重建一条。
+   *
+   * 返回的 Promise 在旧执行器真正退场后才完成，调用方必须等它 —— 否则决策会
+   * 看到还没散场的内存等待器，又把这一轮唤回旧装配上。没有活动执行器时是空操作。
+   */
+  async interrupt(
+    submissionId: string,
+    afterAbort?: () => void,
+  ): Promise<void> {
+    const active = this.activeBySubmission.get(submissionId);
+    if (!active) return;
+    // 先中断再拆等待器：反过来的话，park 住的工具会先醒来、发现自己没有结算，
+    // 然后真的把工具跑一遍 —— 而这一轮本来就该让位。
+    this.options.interruptActive(active);
+    afterAbort?.();
+    await this.executions.get(submissionId)?.catch(() => undefined);
+  }
+
   /**
    * 返回当前唯一活动的执行器。
    *
@@ -587,13 +617,14 @@ export class SubmissionLifecycle<
           return submission ? [submission.submissionId] : [];
         })()
       : (() => {
-          const submission = this.options.store.findRunning();
+          const submission = this.options.store.findRunning() ??
+            this.options.store.findNextPending();
           return submission ? [submission.submissionId] : [];
         })();
     for (const submissionId of submissionIds) {
       await this.cancel(submissionId, reason);
     }
-    return { ok: true };
+    return { ok: submissionIds.length > 0 };
   }
 
   // #endregion

package/src/layers/orchestration/temporary-agent/core.ts

@@ -1,9 +1,21 @@
+import type { ExecutionLevel } from "../../../lib/execution-level";
+
+export const TEMPORARY_AGENT_LAUNCH_KEY =
+  "universal-agent:temporary-agent-launch";
+
 export interface TemporaryAgentRequest {
   subagentName: string;
   instructions: string;
   task: string;
 }
 
+export interface TemporaryAgentLaunch<Config = unknown>
+  extends TemporaryAgentRequest {
+  runtimeKey: string;
+  config: Config;
+  executionLevel: ExecutionLevel;
+}
+
 export interface TemporaryAgentRunContext {
   signal: AbortSignal;
   requestId: string;
@@ -149,4 +161,3 @@ export class TemporaryAgentCoordinator {
     });
   }
 }
-import type { ExecutionLevel } from "../../../lib/execution-level";

package/src/layers/orchestration/temporary-agent/runner.ts

@@ -10,7 +10,6 @@ const BLOCKED_TOOLS = new Set([
   "resume_schedule",
   "change_schedule_agent",
   "cancel_schedule",
-  "execute",
   "set_context",
   "load_context",
   "search_context",
@@ -25,7 +24,7 @@ const BLOCKED_TOOLS = new Set([
  * @remarks
  * 宿主在装配临时 Agent 的平台、Workspace、Sandbox 和其他 Tool 时调用；调用方可再加名字或前缀黑名单。
  *
- * 固定黑名单排除再次委派、调度、主 Session 上下文和绕过隔离边界的 execute，以保持单层临时 Agent 和已确认的继承范围。
+ * 固定黑名单排除再次委派、调度和主 Session 上下文，以保持单层临时 Agent 和已确认的继承范围。
  *
  * Agent、Session、Workspace 和 Tool 的术语见 `src/index.ts`。
  */

package/src/lib/mcp.ts

@@ -1,4 +1,5 @@
 import type { RetryOptions } from "agents";
+import { withRuntimeLoadTimeout } from "../kernel/runtime-load";
 
 const MCP_RETRY: RetryOptions = {
   maxAttempts: 3,
@@ -63,9 +64,12 @@ export async function connectConfiguredMcpServers(
   const servers = [...pending.values()];
   const settled = await Promise.allSettled(
     servers.map((server) =>
-      host.addMcpServer(server.name, server.url, {
-        retry: MCP_RETRY,
-      }),
+      withRuntimeLoadTimeout(
+        `mcp:${server.name}:connect`,
+        () => host.addMcpServer(server.name, server.url, {
+          retry: MCP_RETRY,
+        }),
+      ),
     ),
   );
   const failed = settled.flatMap((result, index) =>

package/src/lib/prompt.ts

@@ -46,7 +46,7 @@ export const BEHAVIOR =
 export const PLANNING =
   "Planning: For work with 3 or more distinct steps, or any non-trivial / multi-file change, call " +
   "update_plan with the complete plan (it fully replaces the previous one) so the user sees live " +
-  "progress. Mark a step in_progress before starting it and completed the moment it's done; keep only " +
+  "progress. Mark a step in_progress before starting it and done the moment it's done; keep only " +
   "one step in_progress at a time and don't batch completions. Do not make a plan for a single trivial " +
   "step or a purely conversational reply — just do it.";
 

package/src/lib/telemetry-dev.ts

@@ -1,9 +1,12 @@
 /**
- * dev-only 观测降级:把 observability 事件打到 console,让 `wrangler dev` /
- * `wrangler tail` 里能实时看到埋点(否则 publish 到零订阅 channel = 静默 no-op)。
+ * 观测降级:把 observability 事件打到 console,让 `wrangler dev` / `wrangler tail` 里能实时看到埋点,
+ * 并且(生产上开了 `observability.logs` 时)进 Workers Logs 供事后查询。
+ * 不装它,事件就 publish 到零订阅 channel = 静默 no-op。
  *
- * 仅在 env `TELEMETRY_CONSOLE==="1"` 时由 onStart 装载(`.dev.vars` 里开,prod 不设 → 自动关)。
- * 生产不靠它:prod 所有 channel 事件自动转发 Tail Worker。
+ * 由 onStart 在 env `TELEMETRY_CONSOLE==="1"` 时装载 —— `.dev.vars` 和 `wrangler.jsonc` 的 vars 里都开着。
+ * 注意:上游注释宣称"生产上所有 channel 事件自动转发 Tail Worker",那条路径需要 `tail_consumers`,
+ * 本仓没有配,所以生产**不能**指望它;这个 console sink 就是生产的唯一消费面(2026-08-06 实测:
+ * 未开启前 Observability API 查 universal-agent 24h 事件 count=0)。
  *
  * 用 `agents/observability` 的类型化 `subscribe`(按 channel key 订阅),避免引 `node:diagnostics_channel`
  * 与 `@types/node`(tsconfig 只带 workers-types)。

package/src/pi/assembly/context.ts

@@ -367,7 +367,7 @@ async function readMemory(
   return { blocks, degradations };
 }
 
-// 作用：把已授权 Skill 的持久化 catalog 整理成提示词。
+// 作用：把已配置 Skill 的持久化 catalog 整理成提示词。
 // 调用：系统上下文装配在需要告诉模型当前可用 Skill 时调用。
 // 原因：catalog 已在发布和绑定时固定，装配期不得为此访问远端内容来源。
 function renderSkillCatalog(
@@ -379,8 +379,8 @@ function renderSkillCatalog(
   if (bindings.length === 0) return null;
 
   return [
-    "AUTHORIZED SKILLS",
-    "Use an authorized Skill when its description matches. Read its instructions or files only through the authorized Skill tool.",
+    "AVAILABLE SKILLS",
+    "Use an available Skill when its description matches. Read its instructions or files only through the Skill tools.",
     "",
     ...bindings.map(
       ({ name, description }) => `- ${name}: ${description}`,