@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

package/src/index.ts

@@ -9,14 +9,13 @@
  * - `Session` 是本项目的聊天会话边界，由一个 `UniversalAgent` facet 承载。
  * - `Turn` 是 Session 中从一次提示被接纳到输出终态的一次执行。
  * - `Host` 是承载 Runtime 的 Cloudflare Agent，并负责提供生命周期、存储和网络边界。
- * - `Kernel` 是 Runtime 内部连接 Cloudflare Agent 生命周期与 Pi 执行的核心实现。
- * - `Pi` 是负责模型、Tool 循环和 canonical transcript 的执行层。
+ * - `Harness` 是 Pi 提供的唯一模型、Tool 与 canonical transcript 执行引擎。
+ * - `Cloudflare adapter` 只连接 Durable Object 生命周期、RPC 和 Harness。
  * - `Workspace` 是 Tool 可以读取或修改的受控文件系统视图。
  * - `Memory` 是可跨 Turn 读取或写入的长期上下文能力。
  * - `Tool` 是模型在 Turn 中可以调用的一项受控能力。
  * - `Tool Candidate` 是尚未完成治理和编译的内部 Tool 定义。
- * - `Tool Settlement` 是 Tool 调用完成后写回模型循环的统一结果。
- * - `Governance` 是对 Tool 可见性、审批和执行条件的集中约束。
+ * - `Tool decision` 是宿主持久化的审批或交互事实；Pi 仍保存执行位置与 Tool 结果。
  * - `Artifact` 是 Runtime 保存并对外引用的结构化执行产物。
  * - `Extension` 是 Pi 在装配期加载、并在 Turn 中参与执行的扩展模块。
  * - `SubAgent` 是由父 Agent 发起、但拥有独立执行上下文的子任务执行者。
@@ -38,21 +37,21 @@
  * Snapshot 不允许替换已选集合，但不承诺把每个 Port 的内部对象深冻结。
  *
  * 正常调用顺序是 `assemble → validate → freeze → guard → commit`。
- * Runtime 独占跨能力校验和原子提交。
+ * Config 装配独占跨能力校验，Harness 独占执行状态提交。
  *
  * @packageDocumentation
  */
-export * from "./kernel/bindings";
-export * from "./kernel/extensions";
-export * from "./kernel/profile";
-export * from "./kernel/receipts";
-export * from "./kernel/runtime-config";
+export * from "./config/ports";
+export * from "./context/extension/contracts";
+export * from "./config/profile";
+export * from "./submission/contracts";
+export * from "./config/runtime-config";
 export * from "./telemetry";
-export type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
-export * from "./runtime-agent";
-export type { ToolInteractionResponsePreparation } from "./runtime";
-export * from "./kernel/state";
-export * from "./workspace-versioning";
+export type { RuntimeAssemblyView } from "./config/assembly-view";
+export * from "./adapter/cloudflare/define-agent";
+export type { ToolInteractionResponsePreparation } from "./adapter/cloudflare/agent";
+export * from "./conversation/state";
+export * from "./tools/workspace/versioning";
 export * from "./lib/execution-level";
 export type {
   RuntimeAssemblyInput,
@@ -61,8 +60,8 @@ export type {
   RuntimeProfileContribution,
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
-} from "./runtime-assembler";
-export { assembleRuntimeSnapshot } from "./runtime-assembler";
+} from "./config/assembler";
+export { assembleRuntimeSnapshot } from "./config/assembler";
 export type {
   ResolvedConnectors,
   ResolvedResources,
@@ -71,7 +70,7 @@ export type {
   RuntimeSkillBodyTransform,
   RuntimeToolBindings,
   ToolAssemblyResult,
-} from "./runtime-definition";
+} from "./config/definition";
 export type { ModelOption } from "./lib/model-catalog";
 export {
   assembleSubagentPrompt,
@@ -85,66 +84,62 @@ export type {
 } from "./lib/host-actions";
 export {
   AGENT_TYPES,
-} from "./layers/orchestration/subagents/agent-types/registry";
+} from "./tools/subagent/types/registry";
 export type {
   AgentType,
-} from "./layers/orchestration/subagents/agent-types/contract";
-export { withProviderRetry } from "./pi/runtime-adapter";
-export { compilePiTools } from "./pi/tool";
+} from "./tools/subagent/types/contract";
 export type {
-  CompilePiToolsOptions,
   PiToolCandidate,
-  SettledPiToolCall,
   ToolExposureMode,
-} from "./pi/tool";
-export { basePiToolCandidates } from "./pi/tool";
-export { createPiDeclaredToolCandidate } from "./pi/tool";
+} from "./tools";
+export { basePiToolCandidates } from "./tools";
+export { createPiDeclaredToolCandidate } from "./tools";
 export type {
   PiDeclaredTool,
   PiDeclaredToolCallContext,
   PiDeclaredToolPolicy,
-} from "./pi/tool";
-export { memoryPiToolCandidate } from "./pi/tool";
-export { GET_TIME_TOOL_NAME, getTimePiToolCandidate } from "./pi/tool";
-export { schedulePiToolCandidates } from "./pi/tool";
+} from "./tools";
+export { memoryPiToolCandidate } from "./tools";
+export { GET_TIME_TOOL_NAME, getTimePiToolCandidate } from "./tools";
+export { schedulePiToolCandidates } from "./tools";
 export {
   sandboxPiToolCandidates,
   workspaceRevisionPiToolCandidate,
   workspacePiToolCandidates,
-} from "./pi/tool";
-export { subagentPiToolCandidates } from "./pi/tool";
-export { skillPiToolCandidates } from "./pi/tool";
-export type { PiSkillBinding } from "./pi/tool";
+} from "./tools";
+export { subagentPiToolCandidates } from "./tools";
+export { skillPiToolCandidates } from "./tools";
+export type { PiSkillBinding } from "./tools";
 export {
   BROWSER_EXECUTE_TOOL_NAME,
   browserExecutionPiToolCandidate,
   codeExecutionPiToolCandidate,
-} from "./pi/tool";
+} from "./tools";
 export {
   createBrowserExecutionFactory,
   createWorkspaceCodeExecutionFactory,
-} from "./pi/tool";
+} from "./tools";
 export {
   assemblePiExtensions,
   loadPiExtension,
-} from "./pi/assembly";
+} from "./context";
 export type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
   TemporaryAgentLaunch,
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
-} from "./layers/orchestration/temporary-agent/core";
-export { TEMPORARY_AGENT_LAUNCH_KEY } from "./layers/orchestration/temporary-agent/core";
+} from "./tools/subagent/temporary/core";
+export { TEMPORARY_AGENT_LAUNCH_KEY } from "./tools/subagent/temporary/core";
 export {
   temporaryAgentExtensionIsSafe,
   temporaryAgentToolAllowed,
-} from "./layers/orchestration/temporary-agent/runner";
+} from "./tools/subagent/temporary/runner";
 export {
   createTemporaryAgentWorkspace,
-} from "./layers/orchestration/temporary-agent/workspace";
+} from "./tools/subagent/temporary/workspace";
 export {
   createPiModels,
   modelRequestUrl,
   resolvePiModel,
-} from "./pi/runtime-adapter/models";
+} from "./models";

package/src/lib/artifacts.ts

@@ -4,9 +4,12 @@
 /** Stable narrow reference shared by messages, RPC responses and the UI. */
 export interface ArtifactRef {
   kind: "artifact_ref";
+  artifactId: string;
   path: string;
   bytes: number;
   hash: string;
+  workspaceRevision: string;
+  availability: "available" | "unavailable";
   preview: string;
   note: string;
 }
@@ -14,6 +17,15 @@ export interface ArtifactRef {
 export interface SpillWorkspace {
   /** 把溢出的 Artifact 内容写入指定 Workspace 路径。 */
   writeFile(path: string, content: string, mimeType?: string): Promise<void>;
+  /** 写入后验证物理文件，防止只持久化了一个不存在或被截断的引用。 */
+  stat?(path: string): Promise<{
+    type: "file" | "directory" | "symlink";
+    size: number;
+    updatedAt: number;
+    contentVersion?: string;
+  } | null>;
+  /** 写入后验证内容摘要；Artifact 全部是 UTF-8 文本。 */
+  readFileBytes?(path: string): Promise<Uint8Array | null>;
 }
 
 /**
@@ -33,6 +45,10 @@ export async function sha256Hex(text: string): Promise<string> {
   return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+function artifactId(hash: string): string {
+  return `artifact_${hash.slice(0, 24)}`;
+}
+
 /**
  * 把 Tool 结果转成可存储的文本，并选择 `.txt` 或 `.json` 扩展名。
  *
@@ -52,3 +68,5 @@ export function serializeOutput(output: unknown): { text: string; ext: "txt" | "
     return { text: String(output), ext: "txt" };
   }
 }
+
+export { artifactId };

package/src/lib/execution-level.ts

@@ -25,3 +25,16 @@ export function maxExecutionLevel(
     )
   ]!;
 }
+
+/** The most permissive level shared by an Agent and a Scheduled Task ceiling. */
+export function minExecutionLevel(
+  left: ExecutionLevel,
+  right: ExecutionLevel,
+): ExecutionLevel {
+  return EXECUTION_LEVELS[
+    Math.min(
+      EXECUTION_LEVELS.indexOf(left),
+      EXECUTION_LEVELS.indexOf(right),
+    )
+  ]!;
+}

package/src/lib/mcp.ts

@@ -1,5 +1,5 @@
 import type { RetryOptions } from "agents";
-import { withRuntimeLoadTimeout } from "../kernel/runtime-load";
+import { withRuntimeLoadTimeout } from "../config/runtime-load";
 
 const MCP_RETRY: RetryOptions = {
   maxAttempts: 3,

package/src/lib/prompt.ts

@@ -17,9 +17,8 @@ export const PERSONA =
 // Names the stable runtime environment.
 export const RUNTIME =
   "Runtime: this agent runs on Cloudflare Workers. When execute is present, its Code Mode Dynamic Worker is your " +
-  "instrument — code there runs with outbound network access (fetch), your " +
-  "workspace filesystem (state.*), and the tools.* methods listed in its own description. Use it for raw or customized HTTP " +
-  "requests, parsing a payload, hitting several known endpoints, or computing over a file. Write plain " +
+  "instrument — code there runs with your workspace filesystem (state.*) and the tools.* methods listed in its own description. " +
+  "Use it for tool composition, parsing a payload, or computing over a file. Write plain " +
   "JavaScript — the sandbox evaluates " +
   "it directly, so TypeScript type annotations (`: number`, `as Type`) are a syntax error, and there " +
   "is no Python interpreter or package manager to invoke. Use the JS/Workers equivalent of what you " +
@@ -58,8 +57,7 @@ export const TOOLS =
   "use state.* for workspace file operations, tools.* for other host capabilities, and sequential calls for repeated or durable operations. " +
   "Top-level-only Tools remain Direct even when called repeatedly. " +
   "For web tasks, use web_search for web discovery, current facts, cited research, " +
-  "and public URL analysis. For web access specifically, use execute Code Mode only for raw or customized network requests, structured " +
-  "API calls, or when web_search cannot retrieve the required content; do not use execute for ordinary web " +
+  "and public URL analysis; do not use execute for ordinary web " +
   "searches. When execute is absent, use the actually exposed Direct Tools. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
   "package managers, system commands, builds, tests and background processes; its filesystem is temporary, " +
   "persistent inputs are copied in automatically on first use, /userspace is read-only, and only explicitly " +
@@ -70,7 +68,10 @@ export const TOOLS =
   "prioritize verification, saving durable results, and the final response. " +
   "When related Tool calls can run independently, all are available inside execute, and execute is present, run them inside that execute rather than as parallel top-level calls; " +
   "only independent top-level-only Direct Tools should be issued together in one turn. When you reference " +
-  "code, cite it as file_path:line_number.";
+  "code, cite it as file_path:line_number. " +
+  "When schedule tools are available, prepare a standalone Requirement (at most 1000 Unicode characters), a name (at most 50), a time rule and an explicit timezone. Ask for missing information. " +
+  "Use local once/daily/weekly rules for new scheduled tasks. The Host prepares the authorization scope and the user must confirm before saving; never claim a task was created before the Tool succeeds. " +
+  "One source Chat may create multiple tasks. Before editing, list tasks and use the exact Task ID; ask when the target is ambiguous. Never attach source history or hidden context to the Requirement.";
 
 // A real browser is the only way to observe what a page actually does, and the
 // shared failure mode is a browser tool that returns nothing and looks clean.

package/src/lib/token-estimate.ts

@@ -0,0 +1,8 @@
+/** Conservative token estimate for prompt budgeting, not provider billing. */
+export function estimateStringTokens(text: string): number {
+  if (!text) return 0;
+  return Math.ceil(Math.max(
+    text.length / 4,
+    text.split(/\s+/u).filter(Boolean).length * 1.3,
+  ));
+}

package/src/{pi/runtime-adapter/models.ts → models/index.ts}

@@ -48,9 +48,9 @@ import type {
   RuntimeModelInputModality,
   RuntimeModelProtocol,
   RuntimeProviderPort,
-} from "../../kernel/bindings";
-import { modelInputMessages } from "../message/model-input";
-import { openRouterMessagesApi } from "./openrouter-messages";
+} from "../config/ports";
+import { modelInputMessages } from "../conversation/message/model-input";
+import { openRouterMessagesApi } from "./openrouter/messages";
 
 const CATALOGS = {
   "openai-chat": openaiProvider().getModels(),
@@ -60,8 +60,6 @@ const CATALOGS = {
   "openai-codex-responses": openaiCodexProvider().getModels(),
 } satisfies Record<RuntimeModelProtocol, readonly Model<Api>[]>;
 
-const PROVIDER_MAX_RETRIES = 2;
-
 const MESSAGES_HOSTED_INPUT_MODALITIES = ["image", "file"] as const;
 const NO_HOSTED_INPUT_MODALITIES: readonly RuntimeModelInputModality[] = [];
 
@@ -83,7 +81,7 @@ function adapterHostedInputModalities(
 // 结构上不可能收敛**,表现为前端 think 转到恢复预算耗尽为止。
 //
 // 调到 240s:比实测静默期留约 7 倍余量。代价是连接真死时单次要等更久,
-// 所以 runtime.ts 同时把 stall 的恢复次数单独收窄(见 CHAT_STALL_MAX_ATTEMPTS)。
+// Harness owns bounded provider retries; this timeout only detects a stream that stopped making progress.
 export const MODEL_STREAM_STALL_TIMEOUT_MS = 240_000;
 export const MODEL_STREAM_STALL_MESSAGE =
   `Chat stream stalled: no activity for ${MODEL_STREAM_STALL_TIMEOUT_MS}ms; the turn was aborted by the stall watchdog.`;
@@ -113,6 +111,12 @@ export type PiGenerationLifecycleEvent =
       readonly generationId: string;
       readonly timestamp: number;
       readonly durationMs: number;
+      readonly responseHeadersMs?: number;
+      readonly firstRawEventMs?: number;
+      readonly firstMeaningfulEventMs?: number;
+      readonly firstTextEventMs?: number;
+      readonly sourceWaitMs?: number;
+      readonly forwardingOverheadMs?: number;
       readonly outcome: "success" | "error" | "cancelled";
       readonly stopReason?: string;
       readonly errorName?: string;
@@ -302,8 +306,12 @@ async function* stopStalledModelStream(
   let stalled = false;
   let stallError: ChatStreamStalledError | undefined;
   let idleWaitMs = 0;
+  let sourceWaitMs = 0;
+  let forwardingOverheadMs = 0;
+  let yieldedAt: number | undefined;
   let rawEventCount = 0;
   let meaningfulEventCount = 0;
+  let firstTextSeen = false;
   let lastRawEventAt: number | undefined;
   let lastRawEventType: AssistantMessageEvent["type"] | undefined;
   const streamedContent = new Set<string>();
@@ -344,6 +352,10 @@ async function* stopStalledModelStream(
   });
   try {
     while (true) {
+      if (yieldedAt !== undefined) {
+        forwardingOverheadMs += Math.max(0, Date.now() - yieldedAt);
+        yieldedAt = undefined;
+      }
       const waitStartedAt = Date.now();
       const nextPromise = iterator
         ? iterator.next()
@@ -375,6 +387,7 @@ async function* stopStalledModelStream(
         timer = undefined;
       }
       if (stalled) throw stallError;
+      sourceWaitMs += Math.max(0, Date.now() - waitStartedAt);
       if (next.done) break;
       const event = next.value;
       rawEventCount += 1;
@@ -395,6 +408,8 @@ async function* stopStalledModelStream(
           output: event.type === "done" ? event.message : event.error,
           rawEventCount,
           meaningfulEventCount,
+          sourceWaitMs,
+          forwardingOverheadMs,
         });
         yield event;
         return;
@@ -410,6 +425,15 @@ async function* stopStalledModelStream(
         lastMeaningfulActivityType = progress;
         idleWaitMs = 0;
       }
+      if (
+        !firstTextSeen &&
+        (event.type === "text_delta" || event.type === "text_end") &&
+        (event.type === "text_delta" ? event.delta : event.content).trim()
+      ) {
+        firstTextSeen = true;
+        probe("first_text_event", { eventType: event.type });
+      }
+      yieldedAt = Date.now();
       yield event;
     }
   } finally {
@@ -431,7 +455,7 @@ function trimTrailingSlash(value: string): string {
 /**
  * 算出一个已解析模型真正会被请求的 URL。
  *
- * {@link withProviderRetry} 在每次派发模型请求前调用它写观测日志；诊断"这个 Agent 到底调了哪个 LLM"时也可以直接复用。
+ * {@link withProviderBoundary} 在每次派发模型请求前调用它写观测日志；诊断"这个 Agent 到底调了哪个 LLM"时也可以直接复用。
  *
  * 各协议的路径由底层 SDK 决定，这里必须与之逐条对齐：OpenAI 兼容 SDK 用 `baseURL + /chat/completions`，
  * Anthropic SDK 用 `baseURL + /v1/messages`（纯字符串拼接，不会去重 `/v1`），Google 的 baseUrl 已含版本段，
@@ -458,18 +482,15 @@ export function modelRequestUrl(model: Model<Api>): string {
 /**
  * 给模型请求补上可中断的空闲终止边界。
  *
- * Runtime Turn 和 SubAgent 在把 `Models.streamSimple` 交给 Pi 前调用；显式传入的重试次数优先。
- *
- * 调用方可以覆盖默认的 2 次 Provider 重试；主 Turn 传 0，由 Submission
- * 统一持有恢复预算。连续 {@link MODEL_STREAM_STALL_TIMEOUT_MS} 毫秒没有可展示进展时中止 provider。
+ * Runtime Turn 和 SubAgent 在把 `Models.streamSimple` 交给 Harness 前调用。
+ * 本边界只负责载荷转换、观测和空闲超时；重试次数由 Harness 传入，这里不提供第二个默认值。
  *
  * 可选 observer 接收配对的 generation started/finished 事实及实际模型输入输出；响应头仅保留
  * 白名单 request id，永不携带 key 或任意响应 header。正文由 telemetry 隐私模式统一脱敏。
  * observer 的异常被隔离，不能改变模型执行结果。
  */
-export function withProviderRetry(
+export function withProviderBoundary(
   streamFn: StreamFn,
-  defaultMaxRetries = PROVIDER_MAX_RETRIES,
   defaultSessionId?: string,
   onGeneration?: PiGenerationLifecycleObserver,
 ): StreamFn {
@@ -503,6 +524,12 @@ export function withProviderRetry(
       let responseCount = 0;
       let upstreamRequestId: string | undefined;
       let responseStatus: number | undefined;
+      let responseHeadersMs: number | undefined;
+      let firstRawEventMs: number | undefined;
+      let firstMeaningfulEventMs: number | undefined;
+      let firstTextEventMs: number | undefined;
+      let sourceWaitMs: number | undefined;
+      let forwardingOverheadMs: number | undefined;
       let finished = false;
       const finish = (
         outcome: "success" | "error" | "cancelled",
@@ -515,11 +542,18 @@ export function withProviderRetry(
       ) => {
         if (finished) return;
         finished = true;
+        const finishedAt = Date.now();
         notify({
           type: "finished",
           generationId: requestId,
-          timestamp: Date.now(),
-          durationMs: Math.max(0, Date.now() - startedAt),
+          timestamp: finishedAt,
+          durationMs: Math.max(0, finishedAt - startedAt),
+          responseHeadersMs,
+          firstRawEventMs,
+          firstMeaningfulEventMs,
+          firstTextEventMs,
+          sourceWaitMs,
+          forwardingOverheadMs,
           outcome,
           ...details,
           ...(upstreamRequestId ? { upstreamRequestId } : {}),
@@ -527,7 +561,9 @@ export function withProviderRetry(
         });
       };
       const probe = (phase: string, details: Record<string, unknown> = {}) => {
+        const elapsedMs = Math.max(0, Date.now() - startedAt);
         if (phase === "response_headers") {
+          responseHeadersMs ??= elapsedMs;
           if (typeof details.upstreamRequestId === "string") {
             upstreamRequestId = details.upstreamRequestId;
           }
@@ -536,6 +572,17 @@ export function withProviderRetry(
           }
           return;
         }
+        if (phase === "first_raw_event") firstRawEventMs ??= elapsedMs;
+        if (phase === "first_meaningful_event") {
+          firstMeaningfulEventMs ??= elapsedMs;
+        }
+        if (phase === "first_text_event") firstTextEventMs ??= elapsedMs;
+        if (typeof details.sourceWaitMs === "number") {
+          sourceWaitMs = details.sourceWaitMs;
+        }
+        if (typeof details.forwardingOverheadMs === "number") {
+          forwardingOverheadMs = details.forwardingOverheadMs;
+        }
         if (phase === "done") {
           finish("success", {
             ...(typeof details.stopReason === "string"
@@ -579,7 +626,7 @@ export function withProviderRetry(
           signal: options?.signal
             ? AbortSignal.any([options.signal, watchdog.signal])
             : watchdog.signal,
-          maxRetries: options?.maxRetries ?? defaultMaxRetries,
+          maxRetries: options?.maxRetries,
           sessionId,
           onPayload: async (payload, activeModel) =>
             pdfPayload(
@@ -789,7 +836,7 @@ export function resolvePiModel(
 /**
  * 用当前部署端点完整重建一个已有的 Pi 模型集合。
  *
- * PiRuntimeAdapter 激活新运行快照时调用它；需要复用 MutableModels 的调用方也可以调用，并继续使用返回的同一实例。
+ * HarnessRuntimeConfig 激活新运行快照时调用它；需要复用 MutableModels 的调用方也可以调用，并继续使用返回的同一实例。
  * 该函数在全部新 provider 校验通过后才清空并替换集合，所以失败时旧集合保持可用。
  *
  * Pi 当前用 provider.id 在 Map 中注册和路由请求，因此每个部署端点都必须同时注册唯一 provider、对应模型、认证解析器和协议实现。