tinker-agent 1.0.65 → 1.2.0

package/src/skills/skill-tool.ts

@@ -0,0 +1,297 @@
+import { lstat, readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import {
+  SKILL_RESOURCE_MAX_DEPTH,
+  SKILL_RESOURCE_MAX_ENTRIES,
+  SkillError,
+  type LoadedSkill,
+  type SkillCatalogSnapshot,
+} from "./skill-loader";
+import { createSkillToolDefinition } from "./skill-catalog";
+import type { SkillActivationCoordinator } from "./skill-context";
+import { defineToolExecutor, type ToolExecutor } from "../tools/types";
+import { cancellationError, throwIfTurnCancelled } from "../agent/turn-cancellation";
+
+export function createSkillToolExecutor(input: {
+  catalog: SkillCatalogSnapshot;
+  coordinator: SkillActivationCoordinator;
+}): ToolExecutor {
+  return defineToolExecutor("skill", {
+    definition: createSkillToolDefinition(input.catalog),
+    async execute(args, _call, context) {
+      throwIfTurnCancelled(context.signal);
+      let name: string;
+      try {
+        name = parseSkillArgs(args);
+      } catch (error) {
+        return failed(
+          "",
+          error instanceof SkillError ? error.code : "SKILL_FIELD_INVALID",
+          errorMessage(error),
+        );
+      }
+      const skill = input.catalog.skills.get(name);
+      if (skill === undefined) {
+        return failed(name, "SKILL_NOT_FOUND", `Unknown Agent Skill: ${name}.`);
+      }
+      const status = input.coordinator.status(name);
+      if (status.status === "active") {
+        return {
+          ok: true,
+          status: "already_active",
+          name,
+          scope: status.skill.scope,
+          sha256: status.skill.sha256,
+        };
+      }
+      if (status.status === "loaded") {
+        return {
+          ok: true,
+          status: "already_loaded",
+          name,
+          scope: status.skill.scope,
+          lifecycle: status.lifecycle,
+          sha256: status.skill.sha256,
+        };
+      }
+
+      try {
+        input.coordinator.reserve(skill);
+        const resources = await listSkillResources(skill, context.signal);
+        throwIfTurnCancelled(context.signal);
+        return {
+          ok: true,
+          status: "loaded",
+          name,
+          scope: skill.scope,
+          directory: skill.directory,
+          skillFilePath: skill.skillFilePath,
+          content: skill.content,
+          byteLength: skill.byteLength,
+          sha256: skill.sha256,
+          resources: resources.paths,
+          resourcesTruncated: resources.truncated,
+        };
+      } catch (error) {
+        input.coordinator.release(name);
+        if (context.signal.aborted) {
+          throw cancellationError(context.signal, error);
+        }
+        const code =
+          error instanceof SkillError ? error.code : "SKILL_RESOURCE_INVALID";
+        return failed(name, code, errorMessage(error));
+      }
+    },
+  });
+}
+
+function parseSkillArgs(args: unknown): string {
+  if (
+    typeof args !== "object" ||
+    args === null ||
+    Array.isArray(args) ||
+    Object.keys(args).length !== 1 ||
+    typeof (args as Record<string, unknown>).name !== "string" ||
+    (args as Record<string, string>).name.trim() === ""
+  ) {
+    throw new SkillError(
+      "SKILL_FIELD_INVALID",
+      "Skill arguments must be exactly { name: <available-skill-name> }.",
+    );
+  }
+  return (args as { name: string }).name;
+}
+
+async function listSkillResources(
+  skill: LoadedSkill,
+  signal: AbortSignal,
+): Promise<{
+  paths: readonly string[];
+  truncated: boolean;
+}> {
+  const files: string[] = [];
+  let depthTruncated = false;
+  for (const rootName of ["assets", "references", "scripts"] as const) {
+    throwIfTurnCancelled(signal);
+    if (files.length > SKILL_RESOURCE_MAX_ENTRIES) {
+      break;
+    }
+    const logicalRoot = path.join(skill.directory, rootName);
+    let rootStats;
+    try {
+      rootStats = await lstat(logicalRoot);
+    } catch (error) {
+      if (isErrno(error, "ENOENT")) {
+        continue;
+      }
+      throw resourceError(skill, rootName, error);
+    }
+    const canonicalRoot = await resolveResourcePath(skill, logicalRoot, rootName);
+    const targetStats = await stat(canonicalRoot);
+    if (!targetStats.isDirectory()) {
+      if (rootStats.isSymbolicLink()) {
+        throw resourceError(
+          skill,
+          rootName,
+          "resource root symlink is not a directory",
+        );
+      }
+      continue;
+    }
+    await walkResources({
+      skill,
+      logicalDirectory: logicalRoot,
+      logicalRelative: rootName,
+      depth: 1,
+      canonicalAncestors: new Set([canonicalRoot]),
+      files,
+      signal,
+      onDepthTruncated: () => {
+        depthTruncated = true;
+      },
+    });
+  }
+  files.sort(compareText);
+  const truncated = depthTruncated || files.length > SKILL_RESOURCE_MAX_ENTRIES;
+  return {
+    paths: Object.freeze(files.slice(0, SKILL_RESOURCE_MAX_ENTRIES)),
+    truncated,
+  };
+}
+
+async function walkResources(input: {
+  skill: LoadedSkill;
+  logicalDirectory: string;
+  logicalRelative: string;
+  depth: number;
+  canonicalAncestors: ReadonlySet<string>;
+  files: string[];
+  signal: AbortSignal;
+  onDepthTruncated(): void;
+}): Promise<void> {
+  throwIfTurnCancelled(input.signal);
+  let entries;
+  try {
+    entries = await readdir(input.logicalDirectory, { withFileTypes: true });
+  } catch (error) {
+    throw resourceError(input.skill, input.logicalRelative, error);
+  }
+  entries.sort((left, right) => compareText(left.name, right.name));
+  for (const entry of entries) {
+    throwIfTurnCancelled(input.signal);
+    if (input.files.length > SKILL_RESOURCE_MAX_ENTRIES) {
+      return;
+    }
+    const logicalPath = path.join(input.logicalDirectory, entry.name);
+    const relativePath = `${input.logicalRelative}/${entry.name}`;
+    const canonicalPath = await resolveResourcePath(
+      input.skill,
+      logicalPath,
+      relativePath,
+    );
+    const targetStats = await stat(canonicalPath);
+    if (targetStats.isFile()) {
+      input.files.push(relativePath.split(path.sep).join("/"));
+      continue;
+    }
+    if (!targetStats.isDirectory()) {
+      throw resourceError(
+        input.skill,
+        relativePath,
+        "resource must resolve to a regular file or directory",
+      );
+    }
+    if (input.depth >= SKILL_RESOURCE_MAX_DEPTH) {
+      input.onDepthTruncated();
+      continue;
+    }
+    if (input.canonicalAncestors.has(canonicalPath)) {
+      throw resourceError(input.skill, relativePath, "resource symlink cycle detected");
+    }
+    await walkResources({
+      ...input,
+      logicalDirectory: logicalPath,
+      logicalRelative: relativePath,
+      depth: input.depth + 1,
+      canonicalAncestors: new Set([...input.canonicalAncestors, canonicalPath]),
+    });
+    if (input.files.length > SKILL_RESOURCE_MAX_ENTRIES) {
+      return;
+    }
+  }
+}
+
+async function resolveResourcePath(
+  skill: LoadedSkill,
+  logicalPath: string,
+  relativePath: string,
+): Promise<string> {
+  try {
+    const canonical = await realpath(logicalPath);
+    if (!isWithin(skill.directory, canonical)) {
+      throw resourceError(
+        skill,
+        relativePath,
+        "resource resolves outside the skill directory",
+      );
+    }
+    return canonical;
+  } catch (error) {
+    if (error instanceof SkillError) {
+      throw error;
+    }
+    throw resourceError(skill, relativePath, error);
+  }
+}
+
+function failed(
+  name: string,
+  errorCode: string,
+  error: string,
+): {
+  ok: false;
+  status: "failed";
+  name: string;
+  errorCode: string;
+  error: string;
+} {
+  return { ok: false, status: "failed", name, errorCode, error };
+}
+
+function resourceError(
+  skill: LoadedSkill,
+  relativePath: string,
+  cause: unknown,
+): SkillError {
+  return new SkillError(
+    "SKILL_RESOURCE_INVALID",
+    `Agent Skill ${skill.scope}/${skill.name} resource ${relativePath} is invalid: ${errorMessage(cause)}.`,
+    { cause },
+  );
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return (
+    relative !== ".." &&
+    !relative.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relative)
+  );
+}
+
+function isErrno(error: unknown, code: string): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === code
+  );
+}
+
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/tools/edit.ts

@@ -1,14 +1,14 @@
-import path from "node:path";
 import { Buffer } from "node:buffer";
 import { readFile, stat, writeFile } from "node:fs/promises";
 import { throwIfTurnCancelled } from "../agent/turn-cancellation";
 import { computeFilePatch } from "./file-diff";
-import { sha256Text } from "./hash";
+import { ensureParentDirectory } from "./ensure-parent-directory";
+import { sha256Bytes, sha256Text } from "./hash";
 import { resolveWorkspacePath } from "./path-safety";
 import { defineToolExecutor } from "./types";
 import type {
   EditFileRawResult,
-  ReadSnapshotStore,
+  FileSnapshotStore,
   ToolExecutionContext,
   ToolExecutor,
 } from "./types";
@@ -22,7 +22,7 @@ type EditArgs = {
 
 export type EditToolOptions = {
   workspaceRoot: string;
-  snapshots: ReadSnapshotStore;
+  snapshots: FileSnapshotStore;
 };
 
 export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
@@ -30,7 +30,7 @@ export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
     definition: {
       name: "Edit",
       description:
-        "Replace an exact string in a workspace file. The file must be read first; a successful paginated Read is sufficient.",
+        "Replace an exact string in an existing file. Exact replacement requires a current version established by a successful Read, Write, or Edit; when none exists, call Read first, and a successful paginated Read is sufficient. Set old_string='' to create a file or write to an empty file; missing parent directories are created when creating a file.",
       parameters: {
         type: "object",
         additionalProperties: false,
@@ -41,7 +41,8 @@ export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
           },
           old_string: {
             type: "string",
-            description: "Exact text to replace.",
+            description:
+              "Exact text to replace. Use an empty string only to create a file or write to an empty file.",
           },
           new_string: {
             type: "string",
@@ -84,17 +85,6 @@ export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
         };
       }
 
-      const parentPath = path.dirname(absolutePath);
-      const parentCheck = await directoryExists(parentPath);
-      if (!parentCheck.ok) {
-        return {
-          ok: false,
-          filePath: input.file_path,
-          absolutePath,
-          error: parentCheck.error,
-        };
-      }
-
       const target = await targetFileState(absolutePath);
       if (!target.ok) {
         return {
@@ -126,7 +116,7 @@ export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
       }
 
       const snapshot = options.snapshots.get(absolutePath);
-      if (snapshot === undefined || snapshot.source === "write") {
+      if (snapshot === undefined) {
         return {
           ok: false,
           filePath: input.file_path,
@@ -136,15 +126,14 @@ export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
         };
       }
 
-      if (target.mtimeMs > snapshot.mtimeMs) {
+      if (target.sha256 !== snapshot.sha256) {
         return {
           ok: false,
           filePath: input.file_path,
           absolutePath,
-          currentMtimeMs: target.mtimeMs,
-          lastObservedMtimeMs: snapshot.mtimeMs,
-          error:
-            "File changed after it was last read or edited. Read it again before Edit.",
+          currentSha256: target.sha256,
+          lastObservedSha256: snapshot.sha256,
+          error: "File changed after it was last observed. Read it again before Edit.",
         };
       }
 
@@ -181,7 +170,7 @@ export function createEditToolExecutor(options: EditToolOptions): ToolExecutor {
         replacementCount: input.replace_all ? replacementCount : 1,
         replaceAll: input.replace_all,
         created: false,
-        expectedMtimeMs: target.mtimeMs,
+        expectedSha256: target.sha256,
         readRequiredOnChange: true,
         snapshots: options.snapshots,
         signal: context.signal,
@@ -229,7 +218,7 @@ async function writeEmptyTarget(input: {
   absolutePath: string;
   target: TargetFileState;
   newContent: string;
-  snapshots: ReadSnapshotStore;
+  snapshots: FileSnapshotStore;
   signal: AbortSignal;
 }): Promise<EditFileRawResult> {
   if (input.target.exists && input.target.content.length > 0) {
@@ -250,7 +239,7 @@ async function writeEmptyTarget(input: {
     replacementCount: 0,
     replaceAll: false,
     created: !input.target.exists,
-    expectedMtimeMs: input.target.exists ? input.target.mtimeMs : undefined,
+    expectedSha256: input.target.exists ? input.target.sha256 : undefined,
     readRequiredOnChange: false,
     snapshots: input.snapshots,
     signal: input.signal,
@@ -266,15 +255,15 @@ async function writeEditedContent(input: {
   replacementCount: number;
   replaceAll: boolean;
   created: boolean;
-  expectedMtimeMs?: number;
+  expectedSha256?: string;
   readRequiredOnChange: boolean;
-  snapshots: ReadSnapshotStore;
+  snapshots: FileSnapshotStore;
   signal: AbortSignal;
 }): Promise<EditFileRawResult> {
   throwIfTurnCancelled(input.signal);
 
-  if (input.expectedMtimeMs !== undefined) {
-    const currentState = await fileMtime(input.absolutePath);
+  if (input.expectedSha256 !== undefined) {
+    const currentState = await targetFileState(input.absolutePath);
     throwIfTurnCancelled(input.signal);
 
     if (!currentState.ok) {
@@ -286,13 +275,22 @@ async function writeEditedContent(input: {
       };
     }
 
-    if (currentState.mtimeMs > input.expectedMtimeMs) {
+    if (!currentState.exists) {
+      return {
+        ok: false,
+        filePath: input.filePath,
+        absolutePath: input.absolutePath,
+        error: "File changed while Edit was being prepared: File does not exist.",
+      };
+    }
+
+    if (currentState.sha256 !== input.expectedSha256) {
       return {
         ok: false,
         filePath: input.filePath,
         absolutePath: input.absolutePath,
-        currentMtimeMs: currentState.mtimeMs,
-        lastObservedMtimeMs: input.expectedMtimeMs,
+        currentSha256: currentState.sha256,
+        lastObservedSha256: input.expectedSha256,
         error: input.readRequiredOnChange
           ? "File changed while Edit was being prepared. Read it again before Edit."
           : "File changed while Edit was being prepared. Retry Edit with the current file state.",
@@ -300,6 +298,20 @@ async function writeEditedContent(input: {
     }
   }
 
+  if (input.created) {
+    try {
+      await ensureParentDirectory(input.absolutePath);
+    } catch (error) {
+      return {
+        ok: false,
+        filePath: input.filePath,
+        absolutePath: input.absolutePath,
+        error: `Failed to create parent directory: ${errorMessage(error)}`,
+      };
+    }
+    throwIfTurnCancelled(input.signal);
+  }
+
   await writeFile(input.absolutePath, input.newContent, "utf8");
   const newSha256 = sha256Text(input.newContent);
   const writtenInfo = await stat(input.absolutePath);
@@ -330,33 +342,6 @@ async function writeEditedContent(input: {
   };
 }
 
-async function directoryExists(
-  directoryPath: string,
-): Promise<{ ok: true } | { ok: false; error: string }> {
-  try {
-    const info = await stat(directoryPath);
-    return info.isDirectory()
-      ? { ok: true }
-      : { ok: false, error: "Parent path is not a directory." };
-  } catch {
-    return { ok: false, error: "Parent directory does not exist." };
-  }
-}
-
-async function fileMtime(
-  filePath: string,
-): Promise<{ ok: true; mtimeMs: number } | { ok: false; error: string }> {
-  try {
-    const info = await stat(filePath);
-    if (!info.isFile()) {
-      return { ok: false, error: "Path is not a file." };
-    }
-    return { ok: true, mtimeMs: info.mtimeMs };
-  } catch (error) {
-    return { ok: false, error: errorMessage(error) };
-  }
-}
-
 type TargetFileState =
   | { ok: true; exists: false }
   | {
@@ -376,7 +361,7 @@ async function targetFileState(
       return { ok: false, error: "Path is not a file." };
     }
 
-    const content = await readFile(absolutePath, "utf8");
+    const bytes = await readFile(absolutePath);
     const currentInfo = await stat(absolutePath);
     if (currentInfo.mtimeMs > info.mtimeMs) {
       return { ok: false, error: "File changed while it was being read." };
@@ -385,8 +370,8 @@ async function targetFileState(
     return {
       ok: true,
       exists: true,
-      content,
-      sha256: sha256Text(content),
+      content: bytes.toString("utf8"),
+      sha256: sha256Bytes(bytes),
       mtimeMs: currentInfo.mtimeMs,
     };
   } catch (error) {
@@ -415,11 +400,13 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function isNotFound(error: unknown): boolean {
+  // ENOTDIR means a parent component is a file, so the target file cannot exist.
+  // Treat it as missing here so each Edit mode can apply its documented behavior.
   return (
     typeof error === "object" &&
     error !== null &&
     "code" in error &&
-    error.code === "ENOENT"
+    (error.code === "ENOENT" || error.code === "ENOTDIR")
   );
 }
 

package/src/tools/ensure-parent-directory.ts

@@ -0,0 +1,6 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+export async function ensureParentDirectory(filePath: string): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+}

package/src/tools/read.ts

@@ -5,8 +5,8 @@ import { sha256Bytes } from "./hash";
 import { resolveWorkspacePath } from "./path-safety";
 import { defineToolExecutor } from "./types";
 import type {
+  FileSnapshotStore,
   ReadFileRawResult,
-  ReadSnapshotStore,
   ToolExecutionContext,
   ToolExecutor,
 } from "./types";
@@ -19,7 +19,7 @@ type ReadArgs = {
 
 export type ReadToolOptions = {
   workspaceRoot: string;
-  snapshots: ReadSnapshotStore;
+  snapshots: FileSnapshotStore;
   maxContentBytes?: number;
 };
 

package/src/tools/recall.ts

@@ -18,9 +18,51 @@ import {
   type RecallRawResult,
   type RecallToolErrorCode,
   type ToolExecutionContext,
+  type ToolDefinition,
   type ToolExecutor,
 } from "./types";
 
+export const RECALL_TOOL_DEFINITION: ToolDefinition = Object.freeze({
+  name: "Recall",
+  description:
+    "Search or retrieve immutable model-visible history from the current session. Search matches literal substrings: use a short distinctive anchor such as a path, symbol, project, command fragment, or error text, not a whole natural-language question. Results are historical snapshots and may differ from the current workspace. Use search to find a source, get to retrieve exact content, and Read/Grep for current files.",
+  parameters: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      mode: { type: "string", enum: ["search", "get"] },
+      query: { type: "string", maxLength: 1024 },
+      roles: {
+        type: "array",
+        minItems: 1,
+        uniqueItems: true,
+        items: { type: "string", enum: ["user", "assistant", "tool"] },
+      },
+      tool_names: {
+        type: "array",
+        minItems: 1,
+        maxItems: 16,
+        uniqueItems: true,
+        items: { type: "string", minLength: 1 },
+      },
+      turn_from: { type: "integer", minimum: 1 },
+      turn_to: { type: "integer", minimum: 1 },
+      limit: { type: "integer", minimum: 1, maximum: 20, default: 10 },
+      offset: { type: "integer", minimum: 0, default: 0 },
+      snapshot_through_ordinal: { type: "integer", minimum: 1 },
+      source: { type: "string" },
+      byte_offset: { type: "integer", minimum: 0, default: 0 },
+      byte_limit: {
+        type: "integer",
+        minimum: 256,
+        maximum: 20_000,
+        default: 12_000,
+      },
+    },
+    required: ["mode"],
+  },
+});
+
 type RecallSearchArgs = {
   mode: "search";
   query: string;
@@ -55,46 +97,7 @@ export function createRecallToolExecutor(options: {
   historyReader: SessionHistoryReader;
 }): ToolExecutor {
   return defineToolExecutor("recall", {
-    definition: {
-      name: "Recall",
-      description:
-        "Search or retrieve immutable model-visible history from the current session. Results are historical snapshots and may differ from the current workspace. Use search to find a source, get to retrieve exact content, and Read/Grep for current files.",
-      parameters: {
-        type: "object",
-        additionalProperties: false,
-        properties: {
-          mode: { type: "string", enum: ["search", "get"] },
-          query: { type: "string", maxLength: 1024 },
-          roles: {
-            type: "array",
-            minItems: 1,
-            uniqueItems: true,
-            items: { type: "string", enum: ["user", "assistant", "tool"] },
-          },
-          tool_names: {
-            type: "array",
-            minItems: 1,
-            maxItems: 16,
-            uniqueItems: true,
-            items: { type: "string", minLength: 1 },
-          },
-          turn_from: { type: "integer", minimum: 1 },
-          turn_to: { type: "integer", minimum: 1 },
-          limit: { type: "integer", minimum: 1, maximum: 20, default: 10 },
-          offset: { type: "integer", minimum: 0, default: 0 },
-          snapshot_through_ordinal: { type: "integer", minimum: 1 },
-          source: { type: "string" },
-          byte_offset: { type: "integer", minimum: 0, default: 0 },
-          byte_limit: {
-            type: "integer",
-            minimum: 256,
-            maximum: 20_000,
-            default: 12_000,
-          },
-        },
-        required: ["mode"],
-      },
-    },
+    definition: RECALL_TOOL_DEFINITION,
     async execute(
       args,
       _call,