@springbrand/agent-runtime 0.3.0-alpha.5 → 0.3.0-alpha.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.5",
+  "version": "0.3.0-alpha.7",
   "type": "module",
   "files": [
     "src",

package/src/adapter/cloudflare/agent.ts

@@ -519,11 +519,15 @@ export abstract class AgentRuntimeKernel<
   }> {
     if (fresh) await this.prepareRuntimeForSubmission(submissionId);
     else await this.ensureRuntimeReady();
-    return this.currentAssemblyPin();
+    const submission = this.db.submissions.find(submissionId);
+    if (!submission) {
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
+    }
+    return this.currentAssemblyPin(submission.origin !== "scheduled");
   }
 
   // initConfig can call this inside its serialized load; re-entering ensureRuntimeReady would deadlock.
-  private async currentAssemblyPin(): Promise<{
+  private async currentAssemblyPin(includeMemory = true): Promise<{
     revision: string;
     descriptor: string;
   }> {
@@ -532,16 +536,18 @@ export abstract class AgentRuntimeKernel<
     if (!runtime) {
       throw new Error("Runtime revision is not initialized");
     }
-    return this.pinAssembly(runtime.pi, runtime.revision);
+    return this.pinAssembly(runtime.pi, runtime.revision, includeMemory);
   }
 
   private async pinAssembly(
     prepared: PreparedPiRuntime,
     baseRevision: string,
+    includeMemory: boolean,
   ): Promise<{ revision: string; descriptor: string }> {
     const pinned = await this.pi.pin({
       prepared,
       baseRevision,
+      includeMemory,
       readExtensionContext: ({ label }) =>
         this._hostGetContext(label),
     });

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/compiler";
+
+/** 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;
   /**
    * 读取一个扩展要写入固定系统提示词的上下文。
    *
@@ -492,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/harness/session-harness.ts

@@ -175,12 +175,13 @@ export class SessionHarness<TContext extends object | undefined> {
   }
 
   private async operationEntries(context: Context): Promise<Entry[]> {
+    // Stop boundaries follow traversal order; walk back from the current tip.
     const entries = await this.lane.findEntries({
       ...(this.operationStartTip === null ? {} : { stopAtId: this.operationStartTip }),
       type: "message",
-      order: "oldestFirst",
+      order: "newestFirst",
     }, context);
-    return entries.filter(({ id }) => id !== this.operationStartTip);
+    return entries.filter(({ id }) => id !== this.operationStartTip).reverse();
   }
 
   private async restoreToolGovernance(context: Context): Promise<void> {

package/src/tools/compiler.ts

@@ -62,6 +62,8 @@ export interface PiToolConfirmationSpec {
 }
 
 export interface PiToolCandidate {
+  /** Presentation only, resolved at the model boundary; never changes approved execution inputs. */
+  readonly modelGuidance?: () => Promise<{ description: string; systemPrompt?: string }>;
   readonly confirmation?: PiToolConfirmationSpec;
   readonly owner: string;
   readonly tool: AgentTool<any, any>;

package/src/tools/schedule.ts

@@ -25,34 +25,41 @@ const scheduleTriggerParameters = Type.Union([
     endDate: Type.Optional(Type.String({ description: "Inclusive last local date YYYY-MM-DD." })),
   }, { additionalProperties: false }),
   Type.Object({
-    kind: Type.Literal("once-in"),
+    kind: Type.Literal("once-in", { description: "Run once after a delay." }),
     seconds: Type.Integer({
       minimum: 1,
       description: "Fire once, this many seconds from now.",
     }),
   }, { additionalProperties: false }),
   Type.Object({
-    kind: Type.Literal("once-at"),
+    kind: Type.Literal("once-at", { description: "Run once at an absolute UTC time." }),
     at: Type.String({
       description:
         "Fire once at this absolute UTC ISO time, e.g. 2026-07-20T09:00:00Z.",
     }),
   }, { additionalProperties: false }),
   Type.Object({
-    kind: Type.Literal("cron"),
+    kind: Type.Literal("cron", { description: "Repeat on a UTC cron schedule." }),
     cron: Type.String({
       description:
         "Repeat on a standard UTC cron, e.g. '0 9 * * *' = daily 09:00 UTC.",
     }),
   }, { additionalProperties: false }),
   Type.Object({
-    kind: Type.Literal("interval"),
+    kind: Type.Literal("interval", { description: "Repeat at fixed intervals." }),
     seconds: Type.Integer({
       minimum: 1,
       description: "Repeat every this many seconds.",
     }),
   }, { additionalProperties: false }),
-], { description: "When to fire." });
+], {
+  description:
+    "When to fire. Discriminate on the `kind` field (never \"type\"). " +
+    'Shapes: {"kind":"local","rule":{"kind":"once","date":"2026-09-17","time":"14:06"}} runs once at 14:06 in `timezone`; ' +
+    '{"kind":"local","rule":{"kind":"daily","time":"09:00"}} runs daily; ' +
+    '{"kind":"local","rule":{"kind":"weekly","weekdays":[1,3],"time":"09:30"}} runs on Mondays and Wednesdays; ' +
+    '{"kind":"once-at","at":"2026-09-17T06:06:00Z"} fires once at an absolute UTC time.',
+});
 
 const scheduleParameters = Type.Object({
   prompt: Type.String({ minLength: 1, maxLength: 1000, pattern: "\\S",
@@ -125,7 +132,7 @@ export function schedulePiToolCandidates(
         name: "schedule",
         label: "Schedule prompt",
         description:
-          "Schedule a prompt to run LATER, autonomously. Required inputs: prompt (Requirement, at most 1000 Unicode characters), trigger and timezone. Prefer local once/daily/weekly rules. label is optional (at most 50 characters); the Host generates an omitted name. Ask for missing information.  Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The user always reviews the proposed schedule before it is created. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
+          "Schedule a prompt to run LATER, autonomously. Required inputs: prompt (Requirement, at most 1000 Unicode characters), trigger and timezone. Prefer local once/daily/weekly rules. trigger discriminates on `kind` (never \"type\"); see the trigger parameter schema for detailed shapes. label is optional (at most 50 characters); the Host generates an omitted name. Ask for missing information.  Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The user always reviews the proposed schedule before it is created. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
         parameters: scheduleParameters,
         async execute(_toolCallId, input, signal) {
           signal?.throwIfAborted();
@@ -156,7 +163,7 @@ export function schedulePiToolCandidates(
       name: "update_schedule",
       label: "Update schedule",
       description:
-        "Update one scheduled task without changing its id or history. Required input: id. Optional prompt, trigger, label and timezone preserve the saved values when omitted. Every edit requires user confirmation; changing Requirement requires a fresh Host authorization check.  Call `list_schedules` first and use an exact id. If multiple tasks plausibly match the user's wording, ask which one instead of guessing.",
+        "Update one scheduled task without changing its id or history. Required input: id. Optional prompt, trigger, label and timezone preserve the saved values when omitted; trigger uses the same `kind`-based shapes as `schedule`. Every edit requires user confirmation; changing Requirement requires a fresh Host authorization check.  Call `list_schedules` first and use an exact id. If multiple tasks plausibly match the user's wording, ask which one instead of guessing.",
       parameters: updateScheduleParameters,
       async execute(_toolCallId, input, signal) {
         signal?.throwIfAborted();
@@ -255,8 +262,8 @@ export function schedulePiToolCandidates(
     if (!confirmation) return [];
     return [{ ...toolCandidate, alwaysRequiresApproval: true, confirmation: {
       async prepare(args, { intentId }) {
-        validateToolArguments(toolCandidate.tool, fauxToolCall(name, args as Record<string, unknown>));
-        const input = args as { id?: string; prompt?: string; trigger?: ScheduleSpec["trigger"]; label?: string; timezone?: string };
+        const validated = validateToolArguments(toolCandidate.tool, fauxToolCall(name, args as Record<string, unknown>));
+        const input = validated as { id?: string; prompt?: string; trigger?: ScheduleSpec["trigger"]; label?: string; timezone?: string };
         if (input.timezone !== undefined && !isValidTimeZone(input.timezone)) throw new Error("A valid IANA timezone is required");
         if (input.trigger?.kind === "local" && input.timezone) {
           const error = validateScheduleRuleSpec(toScheduleRuleSpec(input.trigger, input.timezone));
@@ -270,7 +277,7 @@ export function schedulePiToolCandidates(
         });
         if (prepared.id !== input.id) throw new Error("Host preparation changed the target Task ID");
         const fullInput = { prompt: prepared.prompt, label: prepared.label, trigger: prepared.trigger, timezone: prepared.timezone };
-        validateToolArguments({ ...toolCandidate.tool, parameters: scheduleParameters }, fauxToolCall(name, fullInput));
+        void validateToolArguments({ ...toolCandidate.tool, parameters: scheduleParameters }, fauxToolCall(name, fullInput));
         if (!prepared.label?.trim() || !isValidTimeZone(prepared.timezone) || !prepared.candidateId?.trim() || !prepared.candidateVersion?.trim() || !prepared.authorization?.version?.trim() || !prepared.authorization.scope?.trim() || !Array.isArray(prepared.authorization.missing)) {
           throw new Error("Host preparation is incomplete");
         }