@botbotgo/agent-harness 0.0.298 → 0.0.300

package/dist/resources/prompts/runtime/execution-with-tool-evidence-retry.md

@@ -0,0 +1 @@
+Your previous response was rejected because it claimed execution without any tool calls. Respond with real tool calls only. Start with write_todos, then call the required file or command tools. Do not describe completed work until the tool calls have actually run.

package/dist/resources/prompts/runtime/execution-with-tool-evidence.md

@@ -0,0 +1 @@
+Do not claim that files were created, files were edited, commands were run, waits completed, or todos were updated unless you actually call the relevant tool(s). For multi-step execution tasks, call write_todos first, then use real tool calls, and only summarize results that came from those tool calls.

package/dist/resources/prompts/runtime/invalid-tool-selection-recovery.md

@@ -0,0 +1 @@
+Do not call skill names or other non-tool labels as tools. Only emit tool calls whose names appear in the actual available tool list. If a skill is loaded, follow its instructions using the real available tools instead of calling the skill name as a tool.

package/dist/resources/prompts/runtime/memory-manager.md

@@ -0,0 +1,31 @@
+You are the runtime memory manager.
+Decide whether a candidate should be stored as durable memory and refine it if appropriate.
+Return JSON only.
+
+Rules:
+- Store only durable reusable knowledge. Reject transient chatter, scratchpad, or duplication without added value.
+- Reject raw request/session summaries, source-specific page/news recaps, and generic "we learned how to use the tools/workflow" reflections unless they clearly contain reusable preferences, facts, decisions, or procedures.
+- If transcript evidence shows the user explicitly asked the system to remember or follow a future instruction and the assistant confirmed that intent, store the durable instruction instead of rejecting it as a generic summary.
+- Treat durable knowledge as generic mutable records with database-like operations over the same underlying knowledge item.
+- One candidate may yield zero, one, or multiple durable knowledge items. Split it only when the input clearly contains multiple independently mutable knowledge points.
+- When storing a knowledge item, always return a `knowledgeMutation` object with a stable `identity` and an `operation` of `create`, `update`, or `delete`.
+- Keep `knowledgeMutation.identity` stable across revisions of the same knowledge point, even when the wording changes.
+- Use `create` for a newly introduced knowledge item, `update` for a revised active state of an existing knowledge item, and `delete` when the candidate says an existing knowledge item should no longer remain active.
+- If an existing relevant record already represents the same underlying knowledge item, reuse that record's `knowledge_identity` instead of inventing a new one.
+- Do not invent a second identity just because the new statement negates, revokes, deletes, or replaces the old wording. That is usually the same knowledge item with a different mutation operation.
+- The stored `content` must be canonical knowledge text, not an assistant acknowledgement such as "已记住" or "I will remember".
+- You may optionally include `operationalRule` when the knowledge is naturally a rule, instruction, or recurring procedure. Treat it as structured metadata, not as the primary identity mechanism.
+- Prefer semantic/episodic/procedural kinds only.
+- Prefer scopes session/agent/workspace/user/project only.
+- If the candidate should not be stored, return {"store": false, "reason": "..."}
+- If the candidate maps to one durable item, you may return {"store": true, "content": "...", "summary": "...", "kind": "...", "scope": "...", "tags": ["..."], "confidence": 0.0, "knowledgeMutation": {"identity": "...", "operation": "create|update|delete"}, "operationalRule": {"trigger": "...", "action": "...", "target": "...", "effect": "apply|invalidate"}}
+- If the candidate maps to multiple durable items, return {"store": true, "mutations": [{"content": "...", "summary": "...", "kind": "...", "scope": "...", "tags": ["..."], "confidence": 0.0, "knowledgeMutation": {"identity": "...", "operation": "create|update|delete"}, "operationalRule": {"trigger": "...", "action": "...", "target": "...", "effect": "apply|invalidate"}}]}
+
+sessionId={{sessionId}}
+requestId={{requestId}}
+
+Candidate:
+{{candidateJson}}
+
+Existing relevant records:
+{{existingRecords}}

package/dist/resources/prompts/runtime/memory-mutation-reconciliation.md

@@ -0,0 +1,22 @@
+You are reconciling one newly extracted durable knowledge candidate against existing durable knowledge records.
+Return JSON only.
+
+Rules:
+- Reuse an existing `knowledge_identity` when the candidate revises, deletes, revokes, narrows, broadens, or replaces that same underlying knowledge item.
+- Keep a new identity only when the candidate is genuinely about a different knowledge item.
+- If an existing record contains a structured rule, instruction, or target entity that the candidate now says is deleted, unavailable, forbidden, removed, revoked, or should no longer be executed, treat that as the same underlying knowledge item and reuse the existing identity.
+- If you reuse an existing identity, prefer the existing record's scope unless the candidate clearly belongs to a different long-lived scope.
+- Choose `delete` when the candidate says the prior knowledge item should no longer remain active.
+- Choose `update` when the candidate keeps the same underlying item but changes its active content.
+- Choose `create` only when none of the existing identities represent the same underlying knowledge item.
+- Never invent an identity that is not already listed when `reuseExistingIdentity` is true.
+
+Return one of:
+- {"reuseExistingIdentity": false}
+- {"reuseExistingIdentity": true, "identity": "...", "operation": "update|delete", "scope": "session|agent|workspace|user|project"}
+
+Candidate:
+{{candidateJson}}
+
+Existing candidate identities:
+{{existingRecords}}

package/dist/resources/prompts/runtime/slash-command-skill.md

@@ -0,0 +1,6 @@
+This user message is an explicit command-style invocation of the {{skillQualifier}} `{{skillName}}`.
+Read the skill file for `{{skillName}}` before taking action, then follow its documented phases and constraints exactly.
+You must use the `{{skillName}}` skill for this request and follow its documented workflow.
+Treat everything after `/{{skillName}}` as the skill argument string: {{argumentText}}.
+Do not answer with a generic explanation of what the skill would do. Execute the skill workflow using the available tools unless the skill instructions explicitly require confirmation before acting.
+{{dryRunHint}}

package/dist/resources/prompts/runtime/strict-tool-json.md

@@ -0,0 +1 @@
+When calling tools, return only the tool call itself. The arguments must be a pure JSON object with no explanatory text before or after it.

package/dist/resources/prompts/runtime/workspace-boundary-guidance.md

@@ -0,0 +1,3 @@
+Keep repository and file exploration bounded to the current workspace root unless the user explicitly asks for broader host or filesystem access.
+Do not inspect absolute paths outside the workspace, system directories, or unrelated repos by default.
+Prefer workspace-local tools, relative paths, and the current repository checkout when analyzing code.

package/dist/resources/prompts/runtime/workspace-relative-path.md

@@ -0,0 +1 @@
+The previous tool call used an absolute filesystem path outside the workspace root. Retry with a workspace-relative path only, such as 'tmp-counter.txt', and do not use absolute paths like '/tmp/...'.

package/dist/resources/prompts/runtime/write-todos-descriptive-content.md

@@ -0,0 +1 @@
+When first calling write_todos, use descriptive task content for each todo item. Do not use placeholders like '1', '2', '3', 'step 1', or 'todo 1'. Describe the real step, for example 'Create tmp-counter.txt' or 'Append digit 2 and read the file'.

package/dist/resources/prompts/runtime/write-todos-full-entry.md

@@ -0,0 +1 @@
+When calling write_todos, every todo item must include both content and status. Do not send status-only updates. Retry by resending the full todo entry with the original content preserved.

package/dist/resources/prompts/runtime/write-todos-non-empty-initial-list.md

@@ -0,0 +1 @@
+When first calling write_todos for a non-trivial task, do not send an empty todo list. Send the concrete task steps immediately, and every todo item must include both content and status.

package/dist/resources/tools/_runtime_tool_helpers.mjs

@@ -0,0 +1,152 @@
+import path from "node:path";
+
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+
+export function optionalString(value, fallback = undefined) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+export function requiredString(value, key) {
+  const normalized = optionalString(value);
+  if (!normalized) {
+    throw new Error(`${key} is required`);
+  }
+  return normalized;
+}
+
+export function optionalNumber(value, fallback = undefined) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+export function optionalBoolean(value, fallback = undefined) {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+export function optionalStringRecord(value) {
+  const record = asRecord(value);
+  const entries = Object.entries(record).filter(([, candidate]) => typeof candidate === "string");
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+export function optionalObject(value) {
+  const record = asRecord(value);
+  return Object.keys(record).length > 0 ? record : undefined;
+}
+
+export function defineSchema(shape) {
+  return {
+    parse(input = {}) {
+      const record = asRecord(input);
+      return Object.fromEntries(
+        Object.entries(shape).map(([key, parser]) => [key, parser(record[key])]),
+      );
+    },
+  };
+}
+
+export function getBackend(context) {
+  return asRecord(context?.backend);
+}
+
+export function getRuntimeApi(context) {
+  return asRecord(context?.runtime);
+}
+
+export function getCurrentRequestIdentity(context, toolName) {
+  const runtime = getRuntimeApi(context);
+  const current = asRecord(runtime.current);
+  const sessionId = optionalString(current.sessionId);
+  const requestId = optionalString(current.requestId);
+  if (!sessionId || !requestId) {
+    throw new Error(`${toolName} requires a current sessionId/requestId or explicit input.`);
+  }
+  return { sessionId, requestId };
+}
+
+export function normalizeWorkspacePath(context, inputPath, fallback = ".") {
+  const rawPath = optionalString(inputPath, fallback) ?? fallback;
+  const workspaceRoot = optionalString(context?.runtime?.workspaceRoot);
+  if (!workspaceRoot || !path.isAbsolute(rawPath)) {
+    return rawPath;
+  }
+  const resolvedWorkspaceRoot = path.resolve(workspaceRoot);
+  const resolvedInputPath = path.resolve(rawPath);
+  if (resolvedInputPath === resolvedWorkspaceRoot || resolvedInputPath.startsWith(`${resolvedWorkspaceRoot}${path.sep}`)) {
+    return path.relative(resolvedWorkspaceRoot, resolvedInputPath) || ".";
+  }
+  throw new Error(`Path '${rawPath}' is outside the workspace root '${resolvedWorkspaceRoot}'. Use a workspace-relative path instead.`);
+}
+
+export function toDisplayContent(content) {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (content instanceof Uint8Array) {
+    return new TextDecoder().decode(content);
+  }
+  return "";
+}
+
+export function truncateText(text, maxChars = 12000) {
+  if (typeof text !== "string" || text.length <= maxChars) {
+    return text;
+  }
+  return `${text.slice(0, maxChars - 18)}\n...[truncated]`;
+}
+
+export function truncateLines(lines, maxChars = 12000) {
+  return truncateText(lines.join("\n"), maxChars);
+}
+
+export function formatHttpResponse(result) {
+  if (result?.error) {
+    return result.error;
+  }
+  const content = toDisplayContent(result?.body ?? result?.content);
+  const status = typeof result?.status === "number" ? `${result.status}${result.statusText ? ` ${result.statusText}` : ""}` : null;
+  const headers = result?.headers && typeof result.headers === "object"
+    ? Object.entries(result.headers).map(([key, value]) => `${key}: ${value}`)
+    : [];
+  return [
+    ...(status ? [`Status: ${status}`] : []),
+    ...(headers.length > 0 ? ["Headers:", ...headers] : []),
+    ...(content ? ["Body:", content] : []),
+  ].join("\n") || "Request completed.";
+}
+
+export function normalizeGrepMatches(matches = []) {
+  return matches.map((match) => ({
+    path: optionalString(match.path, ""),
+    line: optionalNumber(match.lineNumber, optionalNumber(match.line_number, optionalNumber(match.line, 0))),
+    text: optionalString(match.content, optionalString(match.text, "")),
+  }));
+}
+
+export function formatGrepResult(pattern, matches) {
+  if (!matches || matches.length === 0) {
+    return `No matches found for pattern '${pattern}'`;
+  }
+  const lines = [];
+  let currentFile = "";
+  for (const match of matches) {
+    if (match.path !== currentFile) {
+      currentFile = match.path;
+      lines.push(`\n${currentFile}:`);
+    }
+    lines.push(`  ${match.line}: ${match.text}`);
+  }
+  return truncateLines(lines);
+}
+
+export function formatListEntries(entries, emptyMessage) {
+  if (!entries || entries.length === 0) {
+    return emptyMessage;
+  }
+  return truncateLines(entries);
+}
+
+export function notAvailable(toolName, capability) {
+  return `Error: ${toolName} is not available. This runtime does not expose ${capability}.`;
+}

package/dist/resources/tools/cancel_request.mjs

@@ -0,0 +1,21 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, getRuntimeApi, notAvailable, optionalString } from "./_runtime_tool_helpers.mjs";
+
+export const cancel_request = tool({
+  description: "Cancel a running or queued request.",
+  schema: defineSchema({
+    requestId: (value) => optionalString(value, undefined),
+    reason: (value) => optionalString(value, undefined),
+  }),
+  async invoke(input, context = {}) {
+    const runtime = getRuntimeApi(context);
+    if (!runtime?.requests?.cancel) {
+      return notAvailable("cancel_request", "request cancellation");
+    }
+    const requestId = input.requestId ?? runtime?.current?.requestId;
+    if (!requestId) {
+      throw new Error("cancel_request requires requestId or a current request.");
+    }
+    return runtime.requests.cancel({ requestId, reason: input.reason });
+  },
+});

package/dist/resources/tools/fetch_url.mjs

@@ -0,0 +1,23 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, formatHttpResponse, getBackend, optionalString } from "./_runtime_tool_helpers.mjs";
+
+export const fetch_url = tool({
+  description: "Fetch a URL and return the response body.",
+  schema: defineSchema({
+    url: (value) => optionalString(value, ""),
+  }),
+  async invoke(input, context = {}) {
+    const backend = getBackend(context);
+    if (typeof backend.fetchUrl === "function") {
+      const result = await backend.fetchUrl(input.url);
+      return typeof result === "string" ? result : formatHttpResponse(result);
+    }
+    const response = await fetch(input.url);
+    return formatHttpResponse({
+      status: response.status,
+      statusText: response.statusText,
+      headers: Object.fromEntries(response.headers.entries()),
+      body: await response.text(),
+    });
+  },
+});

package/dist/resources/tools/http_request.mjs

@@ -0,0 +1,30 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, formatHttpResponse, getBackend, optionalString, optionalStringRecord } from "./_runtime_tool_helpers.mjs";
+
+export const http_request = tool({
+  description: "Send a structured HTTP request.",
+  schema: defineSchema({
+    url: (value) => optionalString(value, ""),
+    method: (value) => optionalString(value, undefined),
+    headers: (value) => optionalStringRecord(value),
+    body: (value) => optionalString(value, undefined),
+  }),
+  async invoke(input, context = {}) {
+    const backend = getBackend(context);
+    if (typeof backend.httpRequest === "function") {
+      const result = await backend.httpRequest(input);
+      return typeof result === "string" ? result : formatHttpResponse(result);
+    }
+    const response = await fetch(input.url, {
+      method: input.method,
+      headers: input.headers,
+      body: input.body,
+    });
+    return formatHttpResponse({
+      status: response.status,
+      statusText: response.statusText,
+      headers: Object.fromEntries(response.headers.entries()),
+      body: await response.text(),
+    });
+  },
+});

package/dist/resources/tools/inspect_approvals.mjs

@@ -0,0 +1,27 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, getRuntimeApi, notAvailable, optionalString } from "./_runtime_tool_helpers.mjs";
+
+export const inspect_approvals = tool({
+  description: "Inspect runtime approvals by listing them or fetching one approval record.",
+  schema: defineSchema({
+    operation: (value) => optionalString(value, "list"),
+    approvalId: (value) => optionalString(value, undefined),
+    sessionId: (value) => optionalString(value, undefined),
+    requestId: (value) => optionalString(value, undefined),
+    status: (value) => optionalString(value, undefined),
+  }),
+  async invoke(input, context = {}) {
+    const runtime = getRuntimeApi(context);
+    if (!runtime?.approvals?.list || !runtime?.approvals?.get) {
+      return notAvailable("inspect_approvals", "runtime approval inspection");
+    }
+    if (input.operation === "get") {
+      return runtime.approvals.get(input.approvalId ?? "");
+    }
+    return runtime.approvals.list({
+      ...(input.sessionId ? { sessionId: input.sessionId } : runtime?.current?.sessionId ? { sessionId: runtime.current.sessionId } : {}),
+      ...(input.requestId ? { requestId: input.requestId } : runtime?.current?.requestId ? { requestId: runtime.current.requestId } : {}),
+      ...(input.status ? { status: input.status } : {}),
+    });
+  },
+});

package/dist/resources/tools/inspect_artifacts.mjs

@@ -0,0 +1,21 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, getCurrentRequestIdentity, getRuntimeApi, notAvailable, optionalString } from "./_runtime_tool_helpers.mjs";
+
+export const inspect_artifacts = tool({
+  description: "List persisted artifacts for one request.",
+  schema: defineSchema({
+    sessionId: (value) => optionalString(value, undefined),
+    requestId: (value) => optionalString(value, undefined),
+  }),
+  async invoke(input, context = {}) {
+    const runtime = getRuntimeApi(context);
+    if (!runtime?.artifacts?.list) {
+      return notAvailable("inspect_artifacts", "runtime artifact inspection");
+    }
+    const identity =
+      input.sessionId && input.requestId
+        ? { sessionId: input.sessionId, requestId: input.requestId }
+        : getCurrentRequestIdentity(context, "inspect_artifacts");
+    return runtime.artifacts.list(identity.sessionId, identity.requestId);
+  },
+});

package/dist/resources/tools/inspect_events.mjs

@@ -0,0 +1,21 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, getCurrentRequestIdentity, getRuntimeApi, notAvailable, optionalString } from "./_runtime_tool_helpers.mjs";
+
+export const inspect_events = tool({
+  description: "List persisted runtime events for one request.",
+  schema: defineSchema({
+    sessionId: (value) => optionalString(value, undefined),
+    requestId: (value) => optionalString(value, undefined),
+  }),
+  async invoke(input, context = {}) {
+    const runtime = getRuntimeApi(context);
+    if (!runtime?.events?.list) {
+      return notAvailable("inspect_events", "runtime event inspection");
+    }
+    const identity =
+      input.sessionId && input.requestId
+        ? { sessionId: input.sessionId, requestId: input.requestId }
+        : getCurrentRequestIdentity(context, "inspect_events");
+    return runtime.events.list(identity.sessionId, identity.requestId);
+  },
+});

package/dist/resources/tools/inspect_requests.mjs

@@ -0,0 +1,27 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, getRuntimeApi, notAvailable, optionalString } from "./_runtime_tool_helpers.mjs";
+
+export const inspect_requests = tool({
+  description: "Inspect runtime requests by listing them or fetching one request record.",
+  schema: defineSchema({
+    operation: (value) => optionalString(value, "list"),
+    requestId: (value) => optionalString(value, undefined),
+    sessionId: (value) => optionalString(value, undefined),
+    agentId: (value) => optionalString(value, undefined),
+    state: (value) => optionalString(value, undefined),
+  }),
+  async invoke(input, context = {}) {
+    const runtime = getRuntimeApi(context);
+    if (!runtime?.requests?.list || !runtime?.requests?.get) {
+      return notAvailable("inspect_requests", "runtime request inspection");
+    }
+    if (input.operation === "get") {
+      return runtime.requests.get(input.requestId ?? runtime?.current?.requestId ?? "");
+    }
+    return runtime.requests.list({
+      ...(input.sessionId ? { sessionId: input.sessionId } : runtime?.current?.sessionId ? { sessionId: runtime.current.sessionId } : {}),
+      ...(input.agentId ? { agentId: input.agentId } : {}),
+      ...(input.state ? { state: input.state } : {}),
+    });
+  },
+});

package/dist/resources/tools/inspect_sessions.mjs

@@ -0,0 +1,21 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, getRuntimeApi, notAvailable, optionalString } from "./_runtime_tool_helpers.mjs";
+
+export const inspect_sessions = tool({
+  description: "Inspect runtime sessions by listing them or fetching one session record.",
+  schema: defineSchema({
+    operation: (value) => optionalString(value, "list"),
+    sessionId: (value) => optionalString(value, undefined),
+    agentId: (value) => optionalString(value, undefined),
+  }),
+  async invoke(input, context = {}) {
+    const runtime = getRuntimeApi(context);
+    if (!runtime?.sessions?.list || !runtime?.sessions?.get) {
+      return notAvailable("inspect_sessions", "runtime session inspection");
+    }
+    if (input.operation === "get") {
+      return runtime.sessions.get(input.sessionId ?? runtime?.current?.sessionId ?? "");
+    }
+    return runtime.sessions.list(input.agentId ? { agentId: input.agentId } : undefined);
+  },
+});

package/dist/resources/tools/list_files.mjs

@@ -0,0 +1,27 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, formatListEntries, getBackend, normalizeWorkspacePath, optionalString, truncateLines } from "./_runtime_tool_helpers.mjs";
+
+export const list_files = tool({
+  description: "List files in a workspace directory.",
+  schema: defineSchema({
+    path: (value) => optionalString(value, "."),
+  }),
+  async invoke(input, context = {}) {
+    const backend = getBackend(context);
+    const targetPath = normalizeWorkspacePath(context, input.path, ".");
+    const legacyInfos = typeof backend.lsInfo === "function" ? await backend.lsInfo(targetPath) : [];
+    const infos = legacyInfos.length > 0
+      ? legacyInfos
+      : typeof backend.ls === "function"
+        ? ((await backend.ls(targetPath))?.files ?? []).map((item) => ({
+            path: item.path,
+            is_dir: item.isDir,
+            size: item.size,
+          }))
+        : [];
+    return formatListEntries(
+      infos.map((item) => item.is_dir ? `${item.path} (directory)` : `${item.path}${item.size ? ` (${item.size} bytes)` : ""}`),
+      `No files found in ${targetPath}`,
+    );
+  },
+});

package/dist/resources/tools/read_artifact.mjs

@@ -0,0 +1,22 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, getCurrentRequestIdentity, getRuntimeApi, notAvailable, optionalString, requiredString } from "./_runtime_tool_helpers.mjs";
+
+export const read_artifact = tool({
+  description: "Read one persisted request artifact.",
+  schema: defineSchema({
+    artifactPath: (value) => requiredString(value, "artifactPath"),
+    sessionId: (value) => optionalString(value, undefined),
+    requestId: (value) => optionalString(value, undefined),
+  }),
+  async invoke(input, context = {}) {
+    const runtime = getRuntimeApi(context);
+    if (!runtime?.artifacts?.read) {
+      return notAvailable("read_artifact", "runtime artifact reads");
+    }
+    const identity =
+      input.sessionId && input.requestId
+        ? { sessionId: input.sessionId, requestId: input.requestId }
+        : getCurrentRequestIdentity(context, "read_artifact");
+    return runtime.artifacts.read(identity.sessionId, identity.requestId, input.artifactPath);
+  },
+});

package/dist/resources/tools/request_approval.mjs

@@ -0,0 +1,27 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, getBackend, notAvailable, optionalObject, optionalString } from "./_runtime_tool_helpers.mjs";
+
+export const request_approval = tool({
+  description: "Request a runtime approval decision.",
+  schema: defineSchema({
+    action: (value) => optionalString(value, ""),
+    reason: (value) => optionalString(value, undefined),
+    details: (value) => optionalObject(value),
+  }),
+  async invoke(input, context = {}) {
+    const backend = getBackend(context);
+    if (typeof backend.requestApproval !== "function") {
+      return notAvailable("request_approval", "approval requests");
+    }
+    const result = await backend.requestApproval(input);
+    if (typeof result === "string") {
+      return result;
+    }
+    if (result?.error) {
+      return result.error;
+    }
+    return result?.approved === true
+      ? `Approval granted for '${input.action}'${result?.id ? ` (id: ${result.id})` : ""}.`
+      : `Approval requested for '${input.action}'${result?.id ? ` (id: ${result.id})` : ""}.`;
+  },
+});

package/dist/resources/tools/run_command.mjs

@@ -0,0 +1,21 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, getBackend, notAvailable, optionalString } from "./_runtime_tool_helpers.mjs";
+
+export const run_command = tool({
+  description: "Run a shell command in the workspace sandbox.",
+  schema: defineSchema({
+    command: (value) => optionalString(value, ""),
+  }),
+  async invoke(input, context = {}) {
+    const backend = getBackend(context);
+    if (typeof backend.execute !== "function") {
+      return notAvailable("run_command", "sandbox command execution");
+    }
+    const result = await backend.execute(input.command);
+    return [
+      result.output,
+      result.exitCode !== null ? `\n[Command ${result.exitCode === 0 ? "succeeded" : "failed"} with exit code ${result.exitCode}]` : "",
+      result.truncated ? "\n[Output was truncated due to size limits]" : "",
+    ].join("");
+  },
+});

package/dist/resources/tools/schedule_task.mjs

@@ -0,0 +1,76 @@
+import { tool } from "@botbotgo/agent-harness/tools";
+import { defineSchema, getBackend, getRuntimeApi, notAvailable, optionalObject, optionalString } from "./_runtime_tool_helpers.mjs";
+
+function parseScheduleWhen(value) {
+  const normalized = optionalString(value, "")?.toLowerCase() ?? "";
+  const intervalMatch = /^every\s+(\d+)\s*(minute|minutes|min|mins|hour|hours|hr|hrs)$/u.exec(normalized);
+  if (intervalMatch) {
+    const quantity = Number.parseInt(intervalMatch[1], 10);
+    const unit = intervalMatch[2];
+    return { type: "interval", everyMinutes: unit.startsWith("h") ? quantity * 60 : quantity };
+  }
+  if (normalized === "hourly" || normalized === "every hour") {
+    return { type: "interval", everyMinutes: 60 };
+  }
+  return normalized ? { type: "cron", expression: value } : undefined;
+}
+
+export const schedule_task = tool({
+  description: "Create, inspect, update, list, and delete runtime-managed scheduled tasks.",
+  schema: defineSchema({
+    operation: (value) => optionalString(value, "create"),
+    scheduleId: (value) => optionalString(value, undefined),
+    name: (value) => optionalString(value, undefined),
+    instruction: (value) => optionalString(value, undefined),
+    agentId: (value) => optionalString(value, undefined),
+    when: (value) => optionalString(value, undefined),
+    schedule: (value) => optionalObject(value),
+    filters: (value) => optionalObject(value),
+    metadata: (value) => optionalObject(value),
+  }),
+  async invoke(input, context = {}) {
+    const runtime = getRuntimeApi(context);
+    const backend = getBackend(context);
+    const schedulePayload = input.schedule ?? parseScheduleWhen(input.when);
+    if (runtime?.schedules?.manage) {
+      return runtime.schedules.manage({
+        operation: input.operation,
+        scheduleId: input.scheduleId,
+        name: input.name,
+        instruction: input.instruction,
+        agentId: input.agentId,
+        schedule: schedulePayload,
+        filters: input.filters,
+        metadata: input.metadata,
+      });
+    }
+    if (typeof backend.manageSchedule === "function") {
+      return backend.manageSchedule({
+        operation: input.operation,
+        scheduleId: input.scheduleId,
+        name: input.name,
+        instruction: input.instruction,
+        agentId: input.agentId,
+        schedule: schedulePayload,
+        filters: input.filters,
+        metadata: input.metadata,
+      });
+    }
+    if (typeof backend.scheduleTask !== "function") {
+      return notAvailable("schedule_task", "task scheduling");
+    }
+    if (input.operation !== "create") {
+      return "Error: schedule_task only supports create on this backend.";
+    }
+    const result = await backend.scheduleTask({
+      instruction: input.instruction ?? "",
+      when: input.when ?? "",
+      name: input.name,
+      metadata: input.metadata,
+    });
+    if (typeof result === "string") {
+      return result;
+    }
+    return result?.error ?? `Scheduled task '${input.name ?? input.instruction ?? ""}' for ${input.when ?? ""}${result?.id ? ` (id: ${result.id})` : ""}.`;
+  },
+});