@springbrand/agent-runtime 0.2.0-alpha.40 → 0.2.0-alpha.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.40",
+  "version": "0.2.0-alpha.42",
   "type": "module",
   "files": [
     "src",

package/src/adapter/cloudflare/resources/r2-skill-source.ts

@@ -0,0 +1,215 @@
+import {
+  parseSkillMarkdown,
+  type SkillContent,
+  type SkillDescriptor,
+  type SkillResource,
+  type SkillResourceDescriptor,
+  type SkillSource,
+} from "agents/skills";
+
+type ListedObject = Pick<R2Object, "key" | "size">;
+
+interface IndexedSkill {
+  readonly descriptor: SkillDescriptor;
+  readonly content: SkillContent;
+  readonly directory: string;
+  readonly resources: ReadonlyMap<string, SkillResourceDescriptor>;
+}
+
+const TEXT_EXTENSIONS = new Set([
+  ".bash",
+  ".css",
+  ".csv",
+  ".html",
+  ".js",
+  ".json",
+  ".jsx",
+  ".md",
+  ".mjs",
+  ".py",
+  ".sh",
+  ".svg",
+  ".ts",
+  ".tsx",
+  ".txt",
+  ".xml",
+  ".yaml",
+  ".yml",
+]);
+
+function trimSlashes(value: string): string {
+  return value.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+function resourceKind(path: string): SkillResourceDescriptor["kind"] {
+  if (path.startsWith("references/")) return "reference";
+  if (path.startsWith("scripts/")) return "script";
+  if (path.startsWith("assets/")) return "asset";
+  return "file";
+}
+
+function resourceEncoding(path: string): "text" | "base64" {
+  const file = path.split("/").at(-1) ?? path;
+  const dot = file.lastIndexOf(".");
+  return TEXT_EXTENSIONS.has(dot < 0 ? "" : file.slice(dot).toLowerCase())
+    ? "text"
+    : "base64";
+}
+
+function normalizedResourcePath(path: string): boolean {
+  return !path.startsWith("/") &&
+    !path.includes("\0") &&
+    path.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+
+function base64Encode(buffer: ArrayBuffer): string {
+  let binary = "";
+  for (const byte of new Uint8Array(buffer)) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+async function readR2<T>(operation: () => Promise<T>): Promise<T> {
+  try {
+    return await operation();
+  } catch {
+    return operation();
+  }
+}
+
+async function listAllObjects(
+  bucket: R2Bucket,
+  prefix: string,
+): Promise<ListedObject[]> {
+  const objects: ListedObject[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await readR2(() => bucket.list({
+      prefix,
+      ...(cursor ? { cursor } : {}),
+    }));
+    objects.push(...page.objects);
+    cursor = page.truncated ? page.cursor : undefined;
+  } while (cursor);
+  return objects;
+}
+
+async function readText(bucket: R2Bucket, key: string): Promise<string> {
+  return readR2(async () => {
+    const object = await bucket.get(key);
+    if (!object) throw new Error(`Skill content not found: ${key}`);
+    return object.text();
+  });
+}
+
+async function readResource(
+  bucket: R2Bucket,
+  key: string,
+  descriptor: SkillResourceDescriptor,
+): Promise<SkillResource> {
+  return readR2(async () => {
+    const object = await bucket.get(key);
+    if (!object) throw new Error(`Skill resource not found: ${key}`);
+    const encoding = descriptor.encoding ?? resourceEncoding(descriptor.path);
+    return {
+      ...descriptor,
+      encoding,
+      ...(object.httpMetadata?.contentType
+        ? { mimeType: object.httpMetadata.contentType }
+        : {}),
+      content: encoding === "text"
+        ? await object.text()
+        : base64Encode(await object.arrayBuffer()),
+    };
+  });
+}
+
+/** Create the immutable, single-Skill R2 Source used by SpringBrand runtimes. */
+export function createR2SkillSource(
+  bucket: R2Bucket,
+  resourceId: string,
+  contentHash: string,
+  contentRef: string,
+): SkillSource {
+  const prefix = `${trimSlashes(contentRef)}/`;
+  const id = `resource-${resourceId}-${contentHash}`;
+  let indexPromise: Promise<IndexedSkill> | undefined;
+
+  const loadIndex = async (): Promise<IndexedSkill> => {
+    const objects = await listAllObjects(bucket, prefix);
+    const skillObjects = objects.filter(({ key }) => key.endsWith("/SKILL.md"));
+    if (skillObjects.length !== 1) {
+      throw new Error(`Skill content requires exactly one SKILL.md: ${contentRef}`);
+    }
+    const skillKey = skillObjects[0]!.key;
+    const directory = skillKey.slice(prefix.length, -"/SKILL.md".length);
+    if (!directory || directory.includes("/")) {
+      throw new Error(`Skill content has an invalid directory: ${contentRef}`);
+    }
+    const parsed = parseSkillMarkdown(await readText(bucket, skillKey));
+    if (!parsed) throw new Error(`Skill content has invalid frontmatter: ${contentRef}`);
+
+    const resourcePrefix = `${prefix}${directory}/`;
+    const resources = objects.flatMap(({ key, size }) => {
+      if (key === skillKey || !key.startsWith(resourcePrefix)) return [];
+      const path = key.slice(resourcePrefix.length);
+      return normalizedResourcePath(path)
+        ? [{ path, kind: resourceKind(path), encoding: resourceEncoding(path), size }]
+        : [];
+    });
+    const descriptor: SkillDescriptor = {
+      name: parsed.name,
+      description: parsed.description,
+      compatibility: parsed.compatibility,
+      license: parsed.license,
+      allowedTools: parsed.allowedTools,
+      metadata: parsed.metadata,
+      sourceId: id,
+    };
+    return {
+      descriptor,
+      directory,
+      resources: new Map(resources.map((resource) => [resource.path, resource])),
+      content: {
+        ...descriptor,
+        body: parsed.body,
+        resources,
+      },
+    };
+  };
+
+  const index = (): Promise<IndexedSkill> => {
+    if (!indexPromise) {
+      indexPromise = loadIndex().catch((error) => {
+        indexPromise = undefined;
+        throw error;
+      });
+    }
+    return indexPromise;
+  };
+
+  return {
+    id,
+    fingerprint: id,
+    async list() {
+      return [{ ...(await index()).descriptor }];
+    },
+    async load(name) {
+      const indexed = await index();
+      return indexed.descriptor.name === name ? { ...indexed.content } : null;
+    },
+    async readResource(name, path) {
+      if (!normalizedResourcePath(path)) return null;
+      const indexed = await index();
+      if (indexed.descriptor.name !== name) return null;
+      const descriptor = indexed.resources.get(path);
+      if (!descriptor) return null;
+      return readResource(
+        bucket,
+        `${prefix}${indexed.directory}/${path}`,
+        descriptor,
+      );
+    },
+  };
+}

package/src/adapter/cloudflare/resources/runtime-resources.ts

@@ -1,8 +1,8 @@
-import { r2, type SkillSource } from "agents/skills";
 import type { RuntimeDegradation } from "../../../kernel/degradation";
 import type { RuntimeExtensionConfig } from "../../../kernel/extensions";
 import { withRuntimeLoadTimeout } from "../../../kernel/runtime-load";
 import type { RuntimeExtensionContribution } from "../../../runtime-definition";
+export { createR2SkillSource } from "./r2-skill-source";
 
 export interface CloudflareRuntimeExtensionSource {
   readonly name: string;
@@ -11,29 +11,12 @@ export interface CloudflareRuntimeExtensionSource {
   readonly sourceHash: string;
 }
 
-function trimSlashes(value: string): string {
-  return value.replace(/^\/+/, "").replace(/\/+$/, "");
-}
-
 function hex(bytes: ArrayBuffer): string {
   return [...new Uint8Array(bytes)]
     .map((byte) => byte.toString(16).padStart(2, "0"))
     .join("");
 }
 
-export function createR2SkillSource(
-  bucket: R2Bucket,
-  resourceId: string,
-  contentHash: string,
-  contentRef: string,
-): SkillSource {
-  return r2(bucket, {
-    prefix: `${trimSlashes(contentRef)}/`,
-    id: `resource-${resourceId}-${contentHash}`,
-    fingerprint: "metadata",
-  });
-}
-
 export async function readVerifiedR2Text(
   bucket: R2Bucket,
   sourceRef: string,

package/src/lib/prompt.ts

@@ -14,7 +14,7 @@ export const PERSONA =
   "You can recall user-managed cold memory across sessions and keep working memory within the current Session, " +
   "manage files in your workspace, and use execute Code Mode for network requests and tool composition.";
 
-// Explains how to reach capabilities instead of listing unsupported substitutes.
+// 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 " +
@@ -47,7 +47,8 @@ export const PLANNING =
 const TOOL_ROUTING =
   "Tools: execute can call only the tools.* methods explicitly listed in its description; that list is exhaustive. Never guess a tools.* method. " +
   "If a required top-level Tool is not visible, do not use execute. Call top-level Tool Search with that exact name, then call the discovered Tool directly. " +
-  "codemode.search searches only methods already installed inside execute; it cannot discover deferred top-level Tools.";
+  "codemode.search searches only methods already installed inside execute; it cannot discover deferred top-level Tools. " +
+  "Never invent a Tool name or input field.";
 
 // Tool-selection guidance mirrors the actual approval and network boundaries.
 export const TOOLS =
@@ -66,7 +67,9 @@ export const TOOLS =
   "raw or customized network cases described above; every response and failure it sees is visible to you. " +
   "bash is a shell over the workspace filesystem only " +
   "(no network, no system utilities) and is approval-gated — don't reach for it to read files or fetch. " +
-  "When execute is present, make related file changes in one execute with state.*; when execute is absent, use one write or bash operation instead of serial edits. " +
+  "When execute is present, make related file changes in one execute with state.*. " +
+  "Use read for one existing Workspace file, write to create or replace one file, and edit for one localized change. " +
+  "Use bash only when a single shell workflow must coordinate multiple Workspace files; do not use it for a single-file read, write, or edit. " +
   "Do not re-plan or explain between consecutive tool calls. When a run is within the last five model turns, stop expanding scope and " +
   "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; " +

package/src/pi/assembly/context.ts

@@ -380,7 +380,10 @@ function renderSkillCatalog(
 
   return [
     "AVAILABLE SKILLS",
-    "Use an available Skill when its description matches. Read its instructions or files only through the Skill tools.",
+    "Skill descriptions are only for deciding which Skills apply; they are not instructions.",
+    "Before the first Tool call for work covered by an available Skill in the current Turn, you MUST call the top-level activate_skill Tool with that Skill's exact name and follow the returned instructions.",
+    "Do not perform Skill-governed work before activation. When multiple Skills apply, activate every matching Skill before acting.",
+    "Read Skill instructions or files only through the Skill tools.",
     "",
     ...bindings.map(
       ({ name, description }) => `- ${name}: ${description}`,

package/src/pi/message/projection.ts

@@ -16,7 +16,7 @@ import { USER_STOP_REASON } from "../../kernel/receipts";
 const MAX_OUTPUT_BYTES = 256 * 1024;
 const MAX_OUTPUT_PREVIEW = 16 * 1024;
 const PROVIDER_CREDIT_ERROR =
-  "The AI service is temporarily unavailable. Please try again later.";
+  "We’re unable to complete your request right now. Please try again in a few moments.";
 
 export interface PiToolApprovalView {
   readonly id: string;
@@ -108,7 +108,9 @@ export function publicAssistantError(message?: string): string | undefined {
   if (!message) return undefined;
   return /"limit_source"\s*:\s*"openrouter_credits"/.test(message) ||
       (message.includes("Insufficient credits") &&
-        message.includes("openrouter.ai/settings/credits"))
+        message.includes("openrouter.ai/settings/credits")) ||
+      (message.includes("can only afford") &&
+        /openrouter\.ai\/workspaces\/[^/\s]+\/keys\//.test(message))
     ? PROVIDER_CREDIT_ERROR
     : message;
 }

package/src/pi/tool/base.ts

@@ -183,13 +183,31 @@ export function normalizeUpdatePlanArguments(
     return input as UpdatePlanArguments;
   }
   const value = input as Record<string, unknown>;
-  if (!Array.isArray(value.steps)) return input as UpdatePlanArguments;
+  let steps = value.steps;
+  if (typeof steps === "string") {
+    try {
+      steps = JSON.parse(steps);
+    } catch {
+      return input as UpdatePlanArguments;
+    }
+  }
+  if (!Array.isArray(steps)) return input as UpdatePlanArguments;
   return {
     ...value,
-    steps: value.steps.map((step) => {
+    steps: steps.map((step) => {
       if (step === null || typeof step !== "object") return step;
       const s = step as Record<string, unknown>;
-      return { ...s, status: normalizeStepStatus(s.status) };
+      const { step: alias, ...rest } = s;
+      const text = typeof rest.text === "string"
+        ? rest.text
+        : typeof alias === "string"
+        ? alias
+        : undefined;
+      return {
+        ...rest,
+        ...(text === undefined ? {} : { text }),
+        status: normalizeStepStatus(s.status),
+      };
     }),
   } as UpdatePlanArguments;
 }
@@ -198,12 +216,17 @@ const setContextParameters = Type.Object({
   label: Type.Union([
     Type.Literal("memory"),
     Type.Literal("preferences"),
-  ]),
-  content: Type.String(),
+  ], {
+    description:
+      "Context block to update: memory for durable facts and active context, preferences for tone and workflow choices.",
+  }),
+  content: Type.String({ description: "Text to store in the selected context block." }),
   action: Type.Optional(Type.Union([
     Type.Literal("replace"),
     Type.Literal("append"),
-  ])),
+  ], {
+    description: 'Whether to replace the block or append to it. Defaults to "replace".',
+  })),
 });
 
 function result<T>(details: T): AgentToolResult<T> {

package/src/pi/tool/skill.ts

@@ -46,6 +46,12 @@ const SKILL_RESOURCE_BUDGET_BYTES = 8 * 1024 * 1024;
 
 type LoadedSkill = NonNullable<Awaited<ReturnType<SkillSource["load"]>>>;
 
+const SKILL_RESOURCE_READ_GUIDANCE =
+  "Bundled Skill resources are not Workspace files. " +
+  "Use read_skill_resource for text instead of read, bash, or find on /skills.";
+const SKILL_RESOURCE_MATERIALIZE_GUIDANCE =
+  "Use materialize_skill_resource for Workspace assets when that Tool is available.";
+
 /**
  * 按体积裁掉超预算的 Skill 资源，并把裁掉的事实写回 Skill 正文。
  *
@@ -121,7 +127,21 @@ function catalogSkillSource(binding: PiSkillBinding): SkillSource {
     }],
     load: async (name) => {
       const skill = await source.load(name);
-      return skill && budgetSkillResources(skill);
+      if (!skill) return null;
+      const loaded = budgetSkillResources(skill);
+      const hasOversizedResource = skill.resources?.some((resource) =>
+        typeof resource.size === "number" &&
+        resource.size > SKILL_RESOURCE_BUDGET_BYTES
+      );
+      const guidance = hasOversizedResource
+        ? SKILL_RESOURCE_READ_GUIDANCE
+        : `${SKILL_RESOURCE_READ_GUIDANCE} ${SKILL_RESOURCE_MATERIALIZE_GUIDANCE}`;
+      return loaded.resources?.length
+        ? {
+            ...loaded,
+            body: `${loaded.body}\n\n${guidance}`,
+          }
+        : loaded;
     },
     ...(source.readResource
       ? { readResource: (name: string, path: string) =>
@@ -175,9 +195,38 @@ const SKILL_TOOL_LABELS: Readonly<Record<string, string>> = {
   materialize_skill_resource: "Materialize Skill resource",
 };
 
+const SKILL_TOOL_PARAMETER_DESCRIPTIONS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  activate_skill: {
+    name: "Exact name of the available Skill to activate.",
+  },
+  read_skill_resource: {
+    name: "Name of the activated Skill. Omit only when path starts with the Skill name.",
+    path: "Bundled resource path listed by activate_skill.",
+  },
+  run_skill_script: {
+    name: "Name of the activated Skill that supplies the script.",
+    path: "Bundled script path listed by activate_skill.",
+    input: "JSON input expected by the Skill script. Defaults to an empty object.",
+  },
+};
+
 const SKILL_ENTRY_READ_GUIDANCE =
   "SKILL.md contains the Skill instructions; use activate_skill instead.";
 
+function normalizeRunSkillScriptArguments(input: unknown): unknown {
+  if (input === null || typeof input !== "object") return input;
+  const value = input as Record<string, unknown>;
+  if (typeof value.input !== "string") return input;
+  try {
+    const decoded = JSON.parse(value.input);
+    return decoded !== null && typeof decoded === "object"
+      ? { ...value, input: decoded }
+      : input;
+  } catch {
+    return input;
+  }
+}
+
 function resourceBytes(resource: SkillResource): Uint8Array {
   if ((resource.encoding ?? "text") === "text") {
     return new TextEncoder().encode(resource.content);
@@ -270,6 +319,17 @@ export async function skillPiToolCandidates(
           }
         : {}),
     });
+    const properties = (adapted.parameters as { properties?: unknown }).properties;
+    if (properties && typeof properties === "object" && !Array.isArray(properties)) {
+      for (const [parameter, description] of Object.entries(
+        SKILL_TOOL_PARAMETER_DESCRIPTIONS[name] ?? {},
+      )) {
+        const schema = (properties as Record<string, unknown>)[parameter];
+        if (schema && typeof schema === "object" && !Array.isArray(schema)) {
+          (schema as Record<string, unknown>).description ??= description;
+        }
+      }
+    }
     if (name === "read_skill_resource") {
       const execute = adapted.execute;
       adapted.execute = (toolCallId, input, signal) => {
@@ -291,6 +351,9 @@ export async function skillPiToolCandidates(
         return execute(toolCallId, input, signal);
       };
     }
+    if (name === "run_skill_script") {
+      adapted.prepareArguments = normalizeRunSkillScriptArguments;
+    }
     return {
       owner: "runtime-skill",
       requiredExecutionLevel:

package/src/pi/tool/workspace-sandbox.ts

@@ -70,9 +70,16 @@ const workspaceReadParameters = Type.Object({
   })),
 });
 const workspaceEditParameters = Type.Object({
-  path: Type.String({ minLength: 1, maxLength: 4_096 }),
-  old_string: Type.String(),
-  new_string: Type.String(),
+  path: Type.String({
+    minLength: 1,
+    maxLength: 4_096,
+    description: "Absolute Workspace path of the file to edit.",
+  }),
+  old_string: Type.String({
+    description:
+      "Exact existing text to replace. Include enough surrounding context to match one location.",
+  }),
+  new_string: Type.String({ description: "Replacement text." }),
 });
 
 /**
@@ -430,24 +437,47 @@ export function workspacePiToolCandidates(
 // #region Sandbox tools
 
 const sandboxCommandParameters = {
-  command: Type.String({ minLength: 1, maxLength: 32_768 }),
-  cwd: Type.Optional(Type.String({ maxLength: 4_096 })),
-  stdin: Type.Optional(Type.String({ maxLength: 65_536 })),
+  command: Type.String({
+    minLength: 1,
+    maxLength: 32_768,
+    description: "Shell command to run in the isolated Linux Sandbox.",
+  }),
+  cwd: Type.Optional(Type.String({
+    maxLength: 4_096,
+    description: "Sandbox working directory. Omit to use the Sandbox default.",
+  })),
+  stdin: Type.Optional(Type.String({
+    maxLength: 65_536,
+    description: "Optional text to pass to the command on standard input.",
+  })),
 };
 const sandboxExecParameters = Type.Object({
   ...sandboxCommandParameters,
   timeoutMs: Type.Optional(
-    Type.Integer({ minimum: 1, maximum: 60_000 }),
+    Type.Integer({
+      minimum: 1,
+      maximum: 60_000,
+      description: "Maximum command runtime in milliseconds, from 1 to 60000.",
+    }),
   ),
 });
 const sandboxStartParameters = Type.Object(sandboxCommandParameters);
 const sandboxProcessParameters = Type.Object({
-  id: Type.String({ minLength: 1, maxLength: 128 }),
+  id: Type.String({
+    minLength: 1,
+    maxLength: 128,
+    description: "Process ID returned by sandbox_start_process.",
+  }),
 });
 const sandboxPublishParameters = Type.Object({
-  paths: Type.Array(Type.String({ minLength: 1, maxLength: 4_096 }), {
+  paths: Type.Array(Type.String({
+    minLength: 1,
+    maxLength: 4_096,
+    description: "Sandbox file path to publish.",
+  }), {
     minItems: 1,
     maxItems: 100,
+    description: "Files to copy from the temporary Sandbox into the persistent Workspace.",
   }),
 });