@springbrand/agent-runtime 0.3.0-alpha.2 → 0.3.0-alpha.21

package/src/harness/submission-operation.ts

@@ -1,49 +1,24 @@
-import type { OperationRequest, OperationResultRecord } from "@earendil-works/pi-agent-core";
-import type { Context } from "@earendil-works/pi-agent-core/harness/context";
+import type { Context } from "@earendil-works/chord";
+import type { EntryId } from "@earendil-works/pi-durable";
 import type { PiCanonicalUserInput } from "../conversation/message/contract";
 import type { StoredSubmission } from "../submission/repository";
-import type { SessionHarness } from "./session-harness";
+import type { SessionHarness, SessionRunRequest } from "./session-harness";
 
-/** Recover the stable operation before accepting new input or navigating its branch. */
+/** Reacquire Pi's stable Submission before admitting another model run. */
 export async function prepareSubmissionOperation(
-  runtime: SessionHarness<object | undefined>,
+  runtime: SessionHarness,
   submission: Pick<StoredSubmission, "submissionId" | "queuedInputJson" | "regenerateMessageId">,
-  regenerationTarget: (messageId: string) => string | null,
+  regenerationTarget: (messageId: string) => Promise<EntryId | null>,
   context: Context,
-): Promise<{ kind: "run"; request?: OperationRequest } | { kind: "settled"; outcome: OperationResultRecord }> {
-  const id = submission.submissionId;
-  const navigationId = `${id}:regenerate`;
-  if (runtime.openOperation?.operationId === navigationId) {
-    const navigation = await runtime.run(undefined, context);
-    if (navigation.kind !== "settled" || navigation.outcome.status !== "completed") {
-      throw new Error("Could not recover the regeneration branch navigation");
-    }
-  }
-  if (runtime.openOperation) {
-    if (runtime.openOperation.operationId !== id) {
-      throw new Error(`Submission ${id} does not own the open Harness operation`);
-    }
-    return { kind: "run" };
-  }
-  const watch = await runtime.lane.watch(context);
-  const previous = watch.snapshot.lastResult;
-  watch.unsubscribe();
-  if (previous?.operationId === id) return { kind: "settled", outcome: previous };
-  if (!submission.queuedInputJson) {
-    throw new Error(`Submission ${id} has no open Harness operation or queued input`);
-  }
+): Promise<SessionRunRequest> {
+  const existing = await runtime.submissionFor(submission.submissionId, context);
+  if (existing) return { operationId: submission.submissionId };
+  if (!submission.queuedInputJson) throw new Error("The admitted Submission has no canonical input");
   const prompt = JSON.parse(submission.queuedInputJson) as PiCanonicalUserInput;
-  if (prompt.role !== "user") throw new Error("Queued SpringBrand user message is invalid");
-  if (submission.regenerateMessageId && previous?.operationId !== navigationId) {
-    const navigation = await runtime.run({
-      kind: "navigation",
-      operationId: navigationId,
-      targetId: regenerationTarget(submission.regenerateMessageId),
-      options: { summarize: false },
-    }, context);
-    if (navigation.kind !== "settled" || navigation.outcome.status !== "completed") {
-      throw new Error("Could not navigate to the regeneration branch");
-    }
+  if (prompt.role !== "user") throw new Error("Invalid canonical user input");
+  if (submission.regenerateMessageId) {
+    const target = await regenerationTarget(submission.regenerateMessageId);
+    await runtime.fork(target, context);
   }
-  return { kind: "run", request: { kind: "prompt", operationId: id, prompt } };
+  return { operationId: submission.submissionId, prompt };
 }

package/src/index.ts

@@ -51,7 +51,7 @@ 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 "./tools/workspace/versioning";
 export * from "./lib/execution-level";
 export type {
   RuntimeAssemblyInput,
@@ -84,16 +84,17 @@ export type {
 } from "./lib/host-actions";
 export {
   AGENT_TYPES,
-} from "./tools/subagent-types/registry";
+} from "./tools/subagent/types/registry";
 export type {
   AgentType,
-} from "./tools/subagent-types/contract";
+} from "./tools/subagent/types/contract";
 export type {
   PiToolCandidate,
   ToolExposureMode,
 } from "./tools";
 export { basePiToolCandidates } from "./tools";
 export { createPiDeclaredToolCandidate } from "./tools";
+export { harnessToolActivation } from "./tools";
 export type {
   PiDeclaredTool,
   PiDeclaredToolCallContext,
@@ -126,20 +127,29 @@ export {
 export type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
-  TemporaryAgentLaunch,
+  TemporaryAgentLaunchSelection,
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
-} from "./tools/temporary-agent/core";
-export { TEMPORARY_AGENT_LAUNCH_KEY } from "./tools/temporary-agent/core";
+} from "./tools/subagent/temporary/core";
+export { TEMPORARY_AGENT_LAUNCH_KEY } from "./tools/subagent/temporary/core";
 export {
   temporaryAgentExtensionIsSafe,
   temporaryAgentToolAllowed,
-} from "./tools/temporary-agent/runner";
+} from "./tools/subagent/temporary/runner";
 export {
   createTemporaryAgentWorkspace,
-} from "./tools/temporary-agent/workspace";
+} from "./tools/subagent/temporary/workspace";
 export {
   createPiModels,
   modelRequestUrl,
   resolvePiModel,
 } from "./models";
+export {
+  openRouterRequestUrl,
+  requestOpenRouter,
+} from "./model-protocol/openrouter";
+export type { OpenRouterRequestOptions } from "./model-protocol/openrouter";
+export type {
+  ModelProtocolResponse,
+  OpenRouterProtocol,
+} from "./models/openrouter/protocol-response";

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/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.
@@ -117,10 +118,8 @@ export const INTERACTION =
   "without that answer; required defaults to false. At most one question may request attachments. Do not add an accept field or tell the user to upload through the normal chat composer; " +
   "continue the same turn when its result arrives. " +
   "Don't use it when a sensible default lets you proceed. " +
-  "After completing a substantive task (report, analysis, multi-step job), finish all work and other Tool calls, " +
-  "then call suggest_followups (2-4 directions) as the last Tool call before your final answer. " +
-  "After it returns, write your complete final answer and make no further Tool calls. Never for small talk or while a " +
-  "task is still in progress; it is non-blocking, unlike ask_user.";
+  "When a substantive task (report, analysis, or multi-step job) is complete, call suggest_followups once before the final answer. " +
+  "Never use it for small talk, quick answers, or while a task is still in progress; it is non-blocking, unlike ask_user.";
 
 // Separates short always-on memory from indexed long-tail workspace files.
 export const MEMORY =

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/model-protocol/openrouter.ts

@@ -0,0 +1,41 @@
+import type { RuntimeModelEndpoint } from "../config/ports";
+
+export interface OpenRouterRequestOptions {
+  readonly headers?: HeadersInit;
+  readonly signal?: AbortSignal;
+  readonly fetch?: typeof fetch;
+}
+
+export function openRouterRequestUrl(
+  endpoint: Pick<RuntimeModelEndpoint, "protocol" | "baseURL">,
+): string {
+  const baseURL = endpoint.baseURL.replace(/\/+$/, "");
+  switch (endpoint.protocol) {
+    case "openrouter-messages":
+      return `${baseURL}/v1/messages`;
+    case "openrouter-chat":
+      return `${baseURL}/chat/completions`;
+    case "openrouter-responses":
+      return `${baseURL}/responses`;
+    default:
+      throw new Error(`Not an OpenRouter protocol: ${endpoint.protocol}`);
+  }
+}
+
+export function requestOpenRouter(
+  endpoint: RuntimeModelEndpoint,
+  body: Readonly<Record<string, unknown>>,
+  options: OpenRouterRequestOptions = {},
+): Promise<Response> {
+  const url = openRouterRequestUrl(endpoint);
+  const headers = new Headers(endpoint.headers);
+  new Headers(options.headers).forEach((value, name) => headers.set(name, value));
+  headers.set("content-type", "application/json");
+  headers.set("authorization", `Bearer ${endpoint.apiKey}`);
+  return (options.fetch ?? globalThis.fetch)(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    ...(options.signal ? { signal: options.signal } : {}),
+  });
+}