@sema-agent/core 7.7.0 → 7.8.0

package/dist/tools/fs/safety.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { sliceHeadSafe } from "../../core/surrogate-safe-slice.js";
+import { pathTargetValue, protectivePathTargetOf } from "../../core/tool-registry.js";
 export function fileArgPath(args) {
     const a = args;
     const fp = a?.file_path;
@@ -8,12 +9,12 @@ export function fileArgPath(args) {
     const p = a?.path;
     return typeof p === "string" && p.length > 0 ? p : undefined;
 }
-export function writeTargetPath(canonicalName, args) {
-    const np = args?.notebook_path;
+export function writeTargetPath(call, pt = protectivePathTargetOf(call)) {
+    if (pt !== undefined)
+        return pathTargetValue(call.args, pt);
+    const np = call.args?.notebook_path;
     const notebook = typeof np === "string" && np.length > 0 ? np : undefined;
-    if (canonicalName === "NotebookEdit")
-        return notebook ?? fileArgPath(args);
-    return fileArgPath(args) ?? notebook;
+    return fileArgPath(call.args) ?? notebook;
 }
 export function sha256(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");

package/dist/tools/monitor.js

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../core/tools.js";
 import { hasBackgroundShell } from "../core/background-shell.js";
 import { MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, } from "../core/task-registry.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 const MONITOR_DESCRIPTION = "Run a shell command in the background and watch its stdout as a stream of events.\n" +
     "\n" +
     "- Each line the command writes to stdout becomes a notification event delivered to you between turns; " +
@@ -42,7 +43,7 @@ function envBackgroundWallSec(caps, requestedSec) {
 export function createMonitorTool(env, opts) {
     return defineTool({
         name: "Monitor",
-        contract: { contractId: "core.monitor@1", implementationRevision: "1" },
+        ...toolFace("monitor"),
         description: MONITOR_DESCRIPTION,
         parameters: Type.Object({
             command: Type.String({
@@ -58,7 +59,6 @@ export function createMonitorTool(env, opts) {
                 description: "Set to true for a session-resident monitor with no watch timeout of its own (default false). It keeps watching until the execution environment's background time budget expires, until you stop it with TaskStop, or until the session ends.",
             })),
         }),
-        effect: "write",
         execute: async (args, ctx) => {
             const { command, description, timeout_ms, persistent } = args;
             if (!hasBackgroundShell(env)) {

package/dist/tools/scheduler-tools.js

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../core/tools.js";
 import { hasScheduler, isValidCronExpr, } from "../core/scheduler.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 export const SCHEDULE_WAKEUP_TOOL_NAME = "ScheduleWakeup";
 export const AUTONOMOUS_LOOP_SENTINEL = "<<autonomous-loop>>";
 export const AUTONOMOUS_LOOP_DYNAMIC_SENTINEL = "<<autonomous-loop-dynamic>>";
@@ -199,7 +200,7 @@ Every user who asks for "9am" gets \`0 9\`, and every user who asks for "hourly"
 Only use minute 0 or 30 when the user names that exact time and clearly means it ("at 9:00 sharp", "at half past", coordinating with a meeting). When in doubt, nudge a few minutes early or late — the user will not notice, and the fleet will.`;
     const cronCreate = defineTool({
         name: "CronCreate",
-        contract: { contractId: "core.cron_create@1", implementationRevision: "1" },
+        ...toolFace("cron-create"),
         description: cronCreateDescription,
         parameters: Type.Object({
             prompt: Type.String({ description: "Self-contained instructions for the future task (it runs unattended)." }),
@@ -222,7 +223,6 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
             })),
             label: Type.Optional(Type.String({ description: "Short label (also a dedup key with the schedule)." })),
         }),
-        effect: "write",
         execute: async (args) => serializedCronCreateOp(async () => {
             const a = args;
             if (a.schedule !== undefined && a.cron !== undefined) {
@@ -305,10 +305,9 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
     };
     const cronCancel = defineTool({
         name: "CronDelete",
-        contract: { contractId: "core.cron_delete@1", implementationRevision: "1" },
+        ...toolFace("cron-delete"),
         description: "Cancel a cron job previously scheduled with CronCreate. Idempotent; ids also appear in CronList.",
         parameters: Type.Object({ id: Type.String({ description: "Job ID returned by CronCreate." }) }),
-        effect: "idempotent",
         execute: async (args) => {
             const { id } = args;
             const taskId = id;
@@ -329,10 +328,9 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
     });
     const cronList = defineTool({
         name: "CronList",
-        contract: { contractId: "core.cron_list@1", implementationRevision: "1" },
+        ...toolFace("cron-list"),
         description: "List all cron jobs scheduled via CronCreate (id, when, label).",
         parameters: Type.Object({}),
-        effect: "read",
         execute: async () => {
             const rows = [];
             const seen = new Set();
@@ -409,7 +407,7 @@ MOUNT NOTE: this host has no resident wakeup leg, so ${SCHEDULE_WAKEUP_TOOL_NAME
 MOUNT NOTE: this host does not vouch for session-scoped scheduling, so a wakeup scheduled here is PERSISTENT — contrary to the paragraph above, it can outlive this session instead of ending with it. End the loop explicitly with \`stop: true\` when the work is done; do not rely on the session ending to cancel it.`;
     const scheduleWakeup = defineTool({
         name: SCHEDULE_WAKEUP_TOOL_NAME,
-        contract: { contractId: "core.schedule_wakeup@1", implementationRevision: "1" },
+        ...toolFace("schedule-wakeup"),
         description: `${SCHEDULE_WAKEUP_PROMPT}${wakeupMountNote}`,
         parameters: Type.Object({
             delaySeconds: Type.Optional(Type.Number({
@@ -428,7 +426,6 @@ MOUNT NOTE: this host does not vouch for session-scoped scheduling, so a wakeup
                 description: "true = nothing changed (you checked and there is nothing to report). false = something happened worth keeping (edited a file, posted a message, advanced state, surfaced a finding). Consecutive noop:true ticks are collapsed in the user's terminal view and tracked as a streak. Required unless `stop` is true.",
             })),
         }),
-        effect: "write",
         execute: async (args) => serializedWakeupOp(async () => {
             const a = args;
             if (a.stop === true) {

package/dist/tools/task-list.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { toolFace } from "../core/tool-catalog-entries.js";
 const STATUS = Type.Union([
     Type.Literal("pending"),
     Type.Literal("in_progress"),
@@ -96,7 +97,7 @@ export function createTaskListTools(store) {
     const tasks = store ?? createMemoryTaskListStore();
     const taskCreate = {
         name: "TaskCreate",
-        contract: { contractId: "core.task_create@1", implementationRevision: "1" },
+        ...toolFace("task-create"),
         description: "Use this tool to create a structured task list for your current session. This helps you track progress, organize complex tasks, and demonstrate thoroughness.\n" +
             "It also helps the user understand the progress of the task and overall progress of their requests.\n" +
             "\n" +
@@ -144,7 +145,6 @@ export function createTaskListTools(store) {
             activeForm: Type.Optional(Type.String({ description: 'Present continuous form shown when in_progress (e.g., "Running tests")' })),
             metadata: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Arbitrary metadata to attach to the task" })),
         }),
-        effect: "write",
         execute: (args) => serialized(tasks, async (tx) => {
             const a = args;
             if (a.metadata)
@@ -169,7 +169,7 @@ export function createTaskListTools(store) {
     };
     const taskGet = {
         name: "TaskGet",
-        contract: { contractId: "core.task_get@1", implementationRevision: "1" },
+        ...toolFace("task-get"),
         description: "Use this tool to retrieve a task by its ID from the task list.\n" +
             "\n" +
             "## When to Use This Tool\n" +
@@ -189,7 +189,6 @@ export function createTaskListTools(store) {
         parameters: Type.Object({
             taskId: Type.String({ description: "The ID of the task to retrieve" }),
         }),
-        effect: "read",
         execute: (args) => serialized(tasks, async (tx) => {
             const id = String(args.taskId);
             const t = await tx.get(id);
@@ -201,7 +200,7 @@ export function createTaskListTools(store) {
     };
     const taskUpdate = {
         name: "TaskUpdate",
-        contract: { contractId: "core.task_update@1", implementationRevision: "1" },
+        ...toolFace("task-update"),
         description: "Use this tool to update a task in the task list.\n" +
             "\n" +
             "## When to Use This Tool\n" +
@@ -285,7 +284,6 @@ export function createTaskListTools(store) {
             addBlocks: Type.Optional(Type.Array(Type.String(), { description: "Task IDs that this task blocks" })),
             addBlockedBy: Type.Optional(Type.Array(Type.String(), { description: "Task IDs that block this task" })),
         }),
-        effect: "idempotent",
         execute: (args) => serialized(tasks, async (tx) => {
             const a = args;
             const id = String(a.taskId);
@@ -395,7 +393,7 @@ export function createTaskListTools(store) {
     };
     const taskList = {
         name: "TaskList",
-        contract: { contractId: "core.task_list@1", implementationRevision: "1" },
+        ...toolFace("task-list"),
         description: "Use this tool to list all tasks in the task list.\n" +
             "\n" +
             "## When to Use This Tool\n" +
@@ -420,7 +418,6 @@ export function createTaskListTools(store) {
             "\n" +
             "Use TaskGet with a specific task ID to view full details including description and metadata.",
         parameters: Type.Object({}),
-        effect: "read",
         execute: () => serialized(tasks, async (tx) => {
             const all = await tx.list();
             if (all.length === 0) {

package/dist/tools/todo.js

@@ -1,10 +1,11 @@
 import { Type } from "typebox";
 import { errorResult } from "../core/tools.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 export function createTodoWriteTool() {
     let todos = [];
     return {
         name: "TodoWrite",
-        contract: { contractId: "core.todo_write@1", implementationRevision: "1" },
+        ...toolFace("todo-write"),
         description: "Create and update a task list for the current session. The list is rendered to the user as your working plan.\n" +
             "\n" +
             '- Each todo has `content`, `status` ("pending" | "in_progress" | "completed"), and `activeForm` (present-tense label shown while in progress).\n' +
@@ -80,7 +81,6 @@ export function createTodoWriteTool() {
                 activeForm: Type.String({ minLength: 1, description: "Present-continuous form shown while in progress (e.g. \"Running the tests\")." }),
             })),
         }),
-        effect: "idempotent",
         execute: (args) => {
             const shape = (t) => ({ content: t.content, status: t.status, activeForm: t.activeForm });
             const oldTodos = todos.map(shape);

package/dist/tools/web.js

@@ -7,6 +7,7 @@ import { isPrivateHost } from "../core/runner/image.js";
 import { DEFAULT_CHARS_PER_TOKEN } from "../internal/harness.js";
 import { binaryMagicFormat } from "./fs/safety.js";
 import { pdfMagicMatches } from "./fs/pdf.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 const MAX_REDIRECTS = 10;
 const MAX_URL_LENGTH = 2048;
 const WEBFETCH_ACCEPT = "text/markdown, text/html, */*";
@@ -262,7 +263,7 @@ export function webFetchToolSpec(config = {}) {
     const canSummarize = config.summarize !== undefined;
     return {
         name: "WebFetch",
-        contract: { contractId: "core.web_fetch@1", implementationRevision: "1" },
+        ...toolFace("web-fetch"),
         description: (canSummarize
             ? "Fetches a URL, converts the page to markdown, and answers `prompt` against it with a sub-model.\n"
             : "Fetches a URL, converts the page to markdown, and returns the markdown. This deployment has no " +
@@ -278,8 +279,6 @@ export function webFetchToolSpec(config = {}) {
                 ? { prompt: Type.Optional(Type.String({ description: "The prompt to run on the fetched content (answered by the configured sub-model)." })) }
                 : {}),
         }),
-        effect: "read",
-        contentOrigin: "external",
         execute: async (args, ctx) => {
             const { url, prompt } = args;
             const startedAt = Date.now();
@@ -844,7 +843,7 @@ export function createWebSearchTool(config) {
     const currentMonthYear = new Date().toLocaleString("en-US", { month: "long", year: "numeric" });
     return {
         name: "WebSearch",
-        contract: { contractId: "core.web_search@1", implementationRevision: "1" },
+        ...toolFace("web-search"),
         description: "Search the web. Returns result blocks with titles and URLs.\n" +
             "\n" +
             `- The current month is ${currentMonthYear} — use this when searching for recent information.\n` +
@@ -857,8 +856,6 @@ export function createWebSearchTool(config) {
             allowed_domains: Type.Optional(Type.Array(Type.String(), { description: "Only include search results from these domains" })),
             blocked_domains: Type.Optional(Type.Array(Type.String(), { description: "Never include search results from these domains" })),
         }),
-        effect: "read",
-        contentOrigin: "external",
         execute: async (args, ctx) => {
             const { query, allowed_domains, blocked_domains } = args;
             const startedAt = Date.now();

package/dist/tools/worktree.js

@@ -2,6 +2,7 @@ import { resolve } from "node:path";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../core/tools.js";
 import { addWorktree, pruneWorktrees, WORKTREE_PARENT } from "../core/git-worktree-env.js";
+import { toolFace } from "../core/tool-catalog-entries.js";
 const ENTER_DESCRIPTION = "Use this tool ONLY when explicitly instructed to work in a worktree — either by the user directly, or by " +
     "project instructions. This tool creates an isolated git worktree and switches the current session into it.\n" +
     "\n" +
@@ -108,7 +109,7 @@ export function createWorktreeTools(env, opts) {
     const session = opts.session ?? {};
     const enter = defineTool({
         name: "EnterWorktree",
-        contract: { contractId: "core.enter_worktree@1", implementationRevision: "1" },
+        ...toolFace("enter-worktree"),
         description: ENTER_DESCRIPTION,
         parameters: Type.Object({
             name: Type.Optional(Type.String({
@@ -121,7 +122,6 @@ export function createWorktreeTools(env, opts) {
                 description: '"fresh" (default) bases the worktree on the default branch tip (origin default branch, else local main/master, else the current HEAD with a note); "head" bases it on the current local HEAD (unpushed commits present).',
             })),
         }),
-        effect: "write",
         execute: async (args) => {
             const { name, path, baseRef } = args;
             if (path !== undefined && name !== undefined) {
@@ -238,7 +238,7 @@ export function createWorktreeTools(env, opts) {
     });
     const exit = defineTool({
         name: "ExitWorktree",
-        contract: { contractId: "core.exit_worktree@1", implementationRevision: "1" },
+        ...toolFace("exit-worktree"),
         description: EXIT_DESCRIPTION,
         parameters: Type.Object({
             keep: Type.Optional(Type.Boolean({
@@ -254,7 +254,6 @@ export function createWorktreeTools(env, opts) {
                 description: 'Set true to remove the worktree even when it has uncommitted files or unmerged commits — they are permanently discarded. Without it a changed worktree is KEPT (the exit still completes and the reply lists the changes plus this escape), never refused.',
             })),
         }),
-        effect: "write",
         execute: async (args) => {
             const raw = args;
             const keep = raw.keep ?? (raw.action === "keep" ? true : undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.7.0",
+  "version": "7.8.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",
@@ -79,6 +79,9 @@
     "gate:closed-sets": "node scripts/verify-closed-sets.mjs",
     "gate:agent-returns": "node scripts/verify-agent-returns.mjs",
     "gate:contract-sentences": "node scripts/verify-contract-sentences.mjs",
+    "gate:tool-catalog": "node scripts/verify-tool-catalog.mjs",
+    "gate:tool-names": "node scripts/verify-tool-name-tables.mjs",
+    "gate:tool-docs": "node scripts/gen-tool-spec-fields.mjs --check",
     "gate:all": "node scripts/gate-all.mjs"
   },
   "dependencies": {