@springbrand/agent-runtime 0.3.0-alpha.1 → 0.3.0-alpha.11

package/src/config/harness-runtime.ts

@@ -1,5 +1,6 @@
 import {
   createModels,
+  lazyStream,
   type MutableModels,
 } from "@earendil-works/pi-ai";
 import {
@@ -23,6 +24,7 @@ import {
   type PreparePiRuntimeOptions,
   type PreparedPiRuntime,
 } from "./pinning";
+import { refreshModelGuidance } from "./model-guidance";
 
 /**
  * Runtime 通过这个配置入口准备、固定并读取 Harness 的模型、提示和工具输入。
@@ -109,11 +111,17 @@ export class HarnessRuntimeConfig {
               : target.getModel(provider, modelId);
         }
         if (property === "streamSimple") {
-          return withProviderBoundary(
+          const stream = withProviderBoundary(
             target.streamSimple.bind(target),
             request.modelSessionId,
             request.onGeneration,
           );
+          return ((model, context, options) => lazyStream(model, async () => {
+            options?.signal?.throwIfAborted();
+            const refreshed = await refreshModelGuidance(state.candidates, context);
+            options?.signal?.throwIfAborted();
+            return stream(model, refreshed, options);
+          })) satisfies typeof stream;
         }
         if (property === "completeSimple") {
           return target.completeSimple.bind(models);

package/src/config/model-guidance.ts

@@ -0,0 +1,21 @@
+import type { Context } from "@earendil-works/pi-ai";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
+
+/** Only descriptions and guidance may vary inside a pinned Submission. */
+export async function refreshModelGuidance(
+  candidates: readonly PiToolCandidate[],
+  context: Context,
+): Promise<Context> {
+  const guidance = new Map(await Promise.all(candidates
+    .filter(candidate => candidate.modelGuidance && context.tools?.some(tool => tool.name === candidate.tool.name))
+    .map(async candidate => [candidate.tool.name, await candidate.modelGuidance!()] as const)));
+  if (!guidance.size) return context;
+  return {
+    ...context,
+    systemPrompt: [context.systemPrompt, ...new Set([...guidance.values()].map(item => item.systemPrompt).filter(Boolean))].filter(Boolean).join("\n\n"),
+    tools: context.tools?.map(tool => {
+      const prompt = guidance.get(tool.name);
+      return prompt ? { ...tool, description: prompt.description } : tool;
+    }),
+  };
+}

package/src/config/pinning.ts

@@ -157,6 +157,11 @@ export interface PreparedPiRuntime {
 export interface PinPiRuntimeOptions {
   readonly prepared: PreparedPiRuntime;
   readonly baseRevision: string;
+  /**
+   * Whether this Submission may inherit automatic hot and cold Memory context.
+   * Scheduled task input is intentionally isolated from those sources.
+   */
+  readonly includeMemory?: boolean;
   /**
    * 读取一个扩展要写入固定系统提示词的上下文。
    *
@@ -249,9 +254,20 @@ function describeTools(candidates: readonly PiToolCandidate[]) {
       description: candidate.tool.description ?? candidate.tool.label,
       parameters: candidate.tool.parameters,
       requiredExecutionLevel: candidate.requiredExecutionLevel,
+      ...(candidate.confirmation ? { confirmation: true } : {}),
       ...(candidate.alwaysRequiresApproval
         ? { alwaysRequiresApproval: true }
         : {}),
+      ...(candidate.unattendedExecution
+        ? {
+            unattendedExecution: {
+              capability: candidate.unattendedExecution.capability,
+              operation: candidate.unattendedExecution.operation,
+              objectConstrained:
+                candidate.unattendedExecution.objectForInput !== undefined,
+            },
+          }
+        : {}),
       ...(candidate.deferLoading ? { deferLoading: true } : {}),
       ...(candidate.source ? { source: candidate.source } : {}),
       retry: piToolRetryPolicy(candidate),
@@ -481,11 +497,14 @@ export async function pinPiRuntime(
 ): Promise<PinnedPiRuntime> {
   const state = readPreparedPiRuntime(options.prepared, owner);
   const { snapshot, assembly } = state;
+  const includeMemory = options.includeMemory !== false;
   const context = await assemblePiSystemContext({
     baseSystemPrompt: snapshot.pi.systemPrompt,
-    memory: snapshot.profile.memory,
-    memoryPort: snapshot.bindings.memory,
-    workspace: snapshot.bindings.workspace,
+    memory: includeMemory
+      ? snapshot.profile.memory
+      : { ...snapshot.profile.memory, enabled: false },
+    memoryPort: includeMemory ? snapshot.bindings.memory : undefined,
+    workspace: includeMemory ? snapshot.bindings.workspace : undefined,
     skills: snapshot.bindings.skills.sources,
     extensionContexts: assembly.context,
     readExtensionContext: options.readExtensionContext,

package/src/config/ports.ts

@@ -1,16 +1,17 @@
+export type { RuntimeSchedulePreparation } from "../submission/contracts";
 import type { RuntimeModelInputModality } from "./profile";
 import type { SkillSource } from "agents/skills";
-import type { ScheduleSpec } from "../submission/contracts";
+import type { ScheduleSpec, RuntimeSchedulePreparation } from "../submission/contracts";
 import type { RuntimeActivityProjection } from "../conversation/state";
 import type { ExecutionLevel } from "../lib/execution-level";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { PiToolCandidate } from "../tools/compiler";
+import type { PiToolCandidate } from "../tools/runtime/contracts";
 import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
   RuntimeSubagentUsageEvent,
   RuntimeSubagentUsageMetrics,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";
 export type { RuntimeModelInputModality } from "./profile";
 export type {
   RuntimeEventConfirmation,
@@ -21,7 +22,7 @@ export type {
   RuntimeSubmissionAdmissionHook,
   RuntimeSubmissionAdmissionInput,
   RuntimeSubmissionAdmissionResult,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";
 
 // #region Workspace 端口
 
@@ -669,16 +670,25 @@ export interface RuntimeScheduleAgentSummary {
  * 让 Runtime 通过 Host 管理当前用户的定时任务。
  *
  * @remarks
- * Schedule Plugin 在装配时把它交给基础工具，模型在用户要求创建、查询或取消时调用。
+ * Host 提供准备与提交操作；Runtime 在现有持久化审批中固定候选并等待用户确认。
  *
- * 任务归属和持久化留在 Host，Runtime 只传递 `ScheduleSpec` 和窄结果。
+ * 任务事实、候选版本、授权检查和保存幂等由 Host 持有，不存放凭据。
  */
+export interface RuntimeScheduleConfirmationPort {
+  /** Read-only preparation; bind the full candidate and authorization to this stable intent. */
+  prepare(request: RuntimeScheduleUpdate & { intentId: string; id?: string }): Promise<RuntimeSchedulePreparation>;
+  /** Atomically check candidate/version, live authorization and quotas. Replay must return the same task. */
+  commit(prepared: RuntimeSchedulePreparation, context: { intentId: string; signal: AbortSignal }): Promise<{ id: string }>;
+}
+
 export interface RuntimeSchedulePort {
+  /** Required for chat creation/editing. Legacy management callers retain their CRUD contract. */
+  confirmation?: RuntimeScheduleConfirmationPort;
   /**
    * 创建一条定时任务并返回它的 ID。
    *
    * @remarks
-   * `schedule` 工具在把用户的时间与提示词组成 `ScheduleSpec` 后调用。
+   * 保留给既有宿主管理调用者；聊天 `schedule` 只经 confirmation.commit 保存。
    *
    * Host 在该边界内绑定用户与会话，Runtime 不携带业务归属 ID。
    */
@@ -1020,6 +1030,16 @@ export interface RuntimePlatformPort {
     requiredExecutionLevel: ExecutionLevel;
     signal: AbortSignal;
   }): Promise<void>;
+  /**
+   * Match a pinned scheduled-task grant against the concrete Tool operation
+   * and recheck the Host-owned live account authorization.
+   *
+   * This callback must fail closed by throwing a user-safe, specific reason.
+   * It is called before dispatch and again at the effect boundary so a grant
+   * revocation cannot be hidden by an earlier decision.
+   */
+  /** @deprecated Scheduled execution is authorized locally by execution level. */
+  authorizeUnattendedExecution?(request: unknown): Promise<void>;
 }
 
 /**

package/src/config/public-contracts.ts

@@ -17,7 +17,7 @@ export * from "../conversation/message";
 export * from "../submission/contracts";
 export * from "../conversation/state";
 export * from "../lib/execution-level";
-export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../tools/workspace-versioning";
+export type { WorkspaceRevision, WorkspaceRevisionManifest } from "../tools/workspace/versioning";
 export type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
@@ -27,4 +27,4 @@ export type {
   RuntimeSubmissionAdmissionHook,
   RuntimeSubmissionAdmissionInput,
   RuntimeSubmissionAdmissionResult,
-} from "../tools/subagent-authority";
+} from "../tools/subagent/authority";

package/src/context/assembly.ts

@@ -1,4 +1,4 @@
-import { estimateStringTokens } from "agents/experimental/memory/utils";
+import { estimateStringTokens } from "../lib/token-estimate";
 import type { RuntimeMemoryPort } from "../config/ports";
 import type { RuntimeDegradation } from "../config/degradation";
 import type { RuntimeMemoryProfile } from "../config/profile";

package/src/context/extension/assembly.ts

@@ -12,8 +12,8 @@ import type {
 import type { RuntimeDegradation } from "../../config/degradation";
 import { withRuntimeLoadTimeout } from "../../config/runtime-load";
 import { sanitizeExtensionName } from "../../lib/extension-name";
-import type { PiToolCandidate } from "../../tools/compiler";
-import { createPiDeclaredToolCandidate } from "../../tools/declared";
+import type { PiToolCandidate } from "../../tools/runtime/contracts";
+import { createPiDeclaredToolCandidate } from "../../tools/adapters/declared";
 
 export interface PiExtensionContextContribution {
   readonly extensionName: string;

package/src/context/memory/budget/gate.ts

@@ -1,4 +1,5 @@
 import {
+  artifactId,
   type ArtifactRef,
   serializeOutput,
   sha256Hex,
@@ -29,7 +30,7 @@ import {
 /**
  * 持久化单个字符串叶子的上限。
  *
- * MUST ≥ 单页 read 的上限（见 `workspace-sandbox.ts` 的 `READ_PAGE_MAX_CHARS`），
+ * MUST ≥ 单页 read 的上限（见 `tools/workspace/index.ts` 的 `READ_PAGE_MAX_CHARS`），
  * 否则持久记录会比模型当轮看到的内容还少，会话恢复后出现凭空缺页。
  */
 export const STORAGE_LEAF_MAX_CHARS = 64 * 1024;
@@ -161,11 +162,26 @@ export async function spillDurableToolOutput(
       text,
       ext === "json" ? "application/json" : "text/plain",
     );
+    if (!options.workspace.stat || !options.workspace.readFileBytes) {
+      throw new Error("Workspace artifact verification is unavailable");
+    }
+    const stat = await options.workspace.stat(path);
+    const expectedBytes = new TextEncoder().encode(text).byteLength;
+    if (!stat || stat.type !== "file" || stat.size !== expectedBytes) {
+      throw new Error("Workspace artifact failed size verification");
+    }
+    const stored = await options.workspace.readFileBytes(path);
+    if (!stored || new TextDecoder().decode(stored) !== text) {
+      throw new Error("Workspace artifact failed content verification");
+    }
     return {
       kind: "artifact_ref",
+      artifactId: artifactId(hash),
       path,
-      bytes: new TextEncoder().encode(text).byteLength,
-      hash: hash.slice(0, 16),
+      bytes: expectedBytes,
+      hash,
+      workspaceRevision: stat.contentVersion ?? `${stat.updatedAt}:${stat.size}`,
+      availability: "available",
       preview: text.slice(0, PREVIEW_CHARS),
       // 出口指令必须是可执行的：只说“去 read 这个路径”会诱导模型整读，而整读一个
       // 刚刚因为过大被外置的文件毫无意义。这里明确要求分页，并告知 read 会返回

package/src/conversation/harness-stream.ts

@@ -2,13 +2,14 @@ import type { AgentEvent, Events, HarnessEvent } from "@earendil-works/pi-agent-
 import type { OperationResultRecord } from "@earendil-works/pi-agent-core/harness/session";
 import type { AssistantMessage } from "@earendil-works/pi-ai";
 import type { UIMessage, UIMessageChunk } from "ai";
-import { PiChunkEncoder } from "./message";
+import { PiChunkEncoder, type ToolInputPreparer } from "./message";
 
 export interface HarnessStreamOptions {
   readonly messageId: string;
   readonly startedAt: number;
   readonly turnId: string;
   readonly userMessageId?: string | null;
+  readonly prepareToolInput?: ToolInputPreparer;
 }
 
 /** Project the final Host decision without rewriting Pi's canonical operation result. */

package/src/conversation/history.ts

@@ -5,6 +5,7 @@ import type {
 } from "@earendil-works/pi-agent-core";
 import type {
   AssistantMessage,
+  JsonValue,
   ToolResultMessage,
   UserMessage,
 } from "@earendil-works/pi-ai";
@@ -490,6 +491,7 @@ export class ConversationHistory {
           toolName: tool.toolName,
           ...toolResult,
           content: toolResult.content ?? [],
+          details: toolResult.details as JsonValue | undefined,
           isError: tool.status === "settled" && tool.isError,
           timestamp: snapshot.operation!.startedAt,
         }, { preliminary: tool.status === "running" });

package/src/conversation/message/projection.ts

@@ -75,6 +75,35 @@ function safeInput(value: unknown): Record<string, unknown> {
   return isRecord(safe) ? safe : {};
 }
 
+export type ToolInputPreparer = (
+  toolName: string,
+  input: unknown,
+) => unknown;
+
+function safeToolInput(
+  toolName: string,
+  value: unknown,
+  prepare?: ToolInputPreparer,
+): Record<string, unknown> {
+  if (prepare) {
+    try {
+      value = prepare(toolName, value);
+    } catch {
+      // Preserve invalid provider output for the normal Tool validation path.
+    }
+  }
+  const input = safeInput(value);
+  if (toolName === "ask_user" && typeof input.questions === "string") {
+    try {
+      const questions: unknown = JSON.parse(input.questions);
+      if (Array.isArray(questions)) input.questions = questions;
+    } catch {
+      // Preserve malformed provider output for the normal unavailable state.
+    }
+  }
+  return input;
+}
+
 function contentText(result: unknown): string | undefined {
   if (!isRecord(result) || !Array.isArray(result.content)) return undefined;
   const text = result.content.flatMap((part) =>
@@ -175,6 +204,7 @@ export class PiChunkEncoder {
   private readonly startedAt?: number;
   private readonly turnId?: string;
   private readonly userMessageId?: string;
+  private readonly prepareToolInput?: ToolInputPreparer;
   private started = false;
   private finished = false;
   private firstTurnStarted = false;
@@ -194,11 +224,13 @@ export class PiChunkEncoder {
     startedAt?: number;
     turnId?: string;
     userMessageId?: string | null;
+    prepareToolInput?: ToolInputPreparer;
   }) {
     this.messageId = options.messageId;
     this.startedAt = options.startedAt;
     this.turnId = options.turnId;
     this.userMessageId = options.userMessageId ?? undefined;
+    this.prepareToolInput = options.prepareToolInput;
   }
 
   start(): UIMessageChunk[] {
@@ -277,7 +309,7 @@ export class PiChunkEncoder {
     toolName: string,
     input: unknown,
   ): UIMessageChunk[] {
-    const safe = safeInput(input);
+    const safe = safeToolInput(toolName, input, this.prepareToolInput);
     this.toolInputs.set(toolCallId, { toolName, input: safe });
     return [{
       type: "tool-input-available",
@@ -505,18 +537,11 @@ export class PiChunkEncoder {
       streaming.deltas.length = 0;
     }
     if (update.type === "toolcall_end") {
-      const input = safeInput(update.toolCall.arguments);
-      this.toolInputs.set(toolCallId, {
-        toolName: update.toolCall.name,
-        input,
-      });
-      chunks.push({
-        type: "tool-input-available",
+      chunks.push(...this.toolInput(
         toolCallId,
-        toolName: update.toolCall.name,
-        input,
-        dynamic: true,
-      });
+        update.toolCall.name,
+        update.toolCall.arguments,
+      ));
       this.pendingToolByIndex.delete(index);
       this.toolCallIdByIndex.delete(index);
     }
@@ -613,15 +638,7 @@ function projectedTool(
   call: ToolCall,
   approval?: PiToolApprovalView,
 ): DynamicToolUIPart {
-  const input = safeInput(call.arguments);
-  if (call.name === "ask_user" && typeof input.questions === "string") {
-    try {
-      const questions: unknown = JSON.parse(input.questions);
-      if (Array.isArray(questions)) input.questions = questions;
-    } catch {
-      // Preserve malformed provider output for the normal unavailable state.
-    }
-  }
+  const input = safeToolInput(call.name, call.arguments);
   const base = {
     type: "dynamic-tool" as const,
     toolCallId: call.id,

package/src/conversation/state.ts

@@ -1,6 +1,6 @@
 import type { ApprovalReceipt } from "../submission/contracts";
 import type { StoredSubmission } from "../submission/repository";
-import type { PendingApprovalSummary } from "../tools/approval/repository";
+import type { PendingApprovalSummary } from "../tools/runtime/approval/repository";
 import type { PiCanonicalUserInput } from "./message/contract";
 
 export type RuntimeLoadPhase = "config" | "assembly" | "mcp" | "pi";
@@ -68,6 +68,17 @@ export interface RuntimeTurnState {
   queued: RuntimeQueuedSubmission[];
 }
 
+/**
+ * 本 Session 当前是否拒绝普通用户输入。
+ *
+ * 定时 Run 未结束时它独占输入:宿主据此禁用输入框并显示原因。
+ * 服务端准入用同一事实拒绝消息,所以客户端状态与后端判定不会漂移。
+ */
+export interface RuntimeInputLock {
+  /** 稳定原因码,由宿主/UI 决定文案。 */
+  reason: string;
+}
+
 /**
  * 保存 Kernel 在当前会话里自己维护的审批状态。
  *
@@ -85,6 +96,8 @@ export interface RuntimeState {
   activity?: RuntimeActivityProjection;
   approvals?: ApprovalReceipt[];
   turn?: RuntimeTurnState;
+  /** 有值时普通输入被锁定,直到锁定的 Submission 进入终态。 */
+  inputLock?: RuntimeInputLock;
 }
 
 type SubmissionProjection = Pick<
@@ -103,6 +116,8 @@ export function projectRuntimeState(input: {
   readonly hasPendingInteraction: (submissionId: string) => boolean;
   readonly hasPendingSteer: (submissionId: string) => boolean;
   readonly hasRunningAgentTools: boolean;
+  /** A non-terminal scheduled Submission owns ordinary input until it ends. */
+  readonly hasUnfinishedScheduled?: boolean;
   readonly previousState: RuntimeState;
 }): { state: RuntimeState; changed: boolean } {
   const approvals: ApprovalReceipt[] = [
@@ -164,12 +179,18 @@ export function projectRuntimeState(input: {
       backgroundWork: input.hasRunningAgentTools,
       revision: (previousActivity?.revision ?? 0) + 1,
     };
+  const inputLock: RuntimeInputLock | undefined = input.hasUnfinishedScheduled
+    ? { reason: "scheduled-run" }
+    : undefined;
   const changed = input.previousState.approvals === undefined ||
     JSON.stringify(input.previousState.approvals) !== JSON.stringify(approvals) ||
     JSON.stringify(input.previousState.turn) !== JSON.stringify(turn) ||
+    JSON.stringify(input.previousState.inputLock) !== JSON.stringify(inputLock) ||
     nextActivity !== previousActivity;
   return {
-    state: changed ? { ...input.previousState, activity: nextActivity, approvals, turn } : input.previousState,
+    state: changed
+      ? { ...input.previousState, activity: nextActivity, approvals, turn, inputLock }
+      : input.previousState,
     changed,
   };
 }