@dynamicagents/plugins 0.16.0 → 0.17.0

package/dist/computer/tools-grep.js

@@ -1,6 +1,7 @@
 import { tool } from "ai";
 import { z } from "zod";
-import { guardPath, WALK_SKIPS } from "./paths.js";
+import { SANDBOX_ROOT } from "../sandbox/header.js";
+import { guardPath, walkSkips } from "./paths.js";
 import { renderGrepMatches } from "./render.js";
 /**
  * Searching file contents, under Think's name so it replaces Think's `grep` —
@@ -31,7 +32,7 @@ export function grepTools(ctx) {
         /**
          * Search, without the container.
          *
-         * The alternative is `bash("grep -rn …")`, and the case for a native one is
+         * The alternative is `exec("grep -rn …")`, and the case for a native one is
          * not that shelling out fails — it is where the search runs. `fs.grep` reads
          * the Durable Object's SQLite, so it answers while the container is being
          * replaced or an install is still running, which is exactly the window the
@@ -51,7 +52,7 @@ export function grepTools(ctx) {
                 "The query is matched literally — set `regex` to interpret it as a regular expression. " +
                 "Pass `include` to limit which files are searched, e.g. '**/*.ts' — without it every file under `path` is read, which is slower and rarely what you meant. " +
                 "A cut result reports the `offset` that continues it. Use `context` to see the lines around a match. " +
-                "Results from `.git` and `node_modules` are left out — search node_modules with bash.",
+                "Results from `.git` and `node_modules` are left out — search node_modules with exec.",
             inputSchema: z.object({
                 query: z.string().describe("Text to find, e.g. 'buildComputerTools'"),
                 path: z
@@ -102,7 +103,12 @@ export function grepTools(ctx) {
                         context: around,
                         limit: DEFAULT_MAX_MATCHES + 1,
                         offset: from,
-                        exclude: WALK_SKIPS.map((segment) => `**/${segment}`)
+                        // The same skips the workspace's own walks hand on, anchored to
+                        // the served root rather than to the target: this tool replaces
+                        // Think's `grep`, so a search of the root that kept the agent's
+                        // own directories would fill a bounded page with them before the
+                        // checkout's matches. See `src/computer/paths.ts`.
+                        exclude: walkSkips(target, SANDBOX_ROOT)
                     });
                     if (matches.length === 0)
                         return `no matches for ${JSON.stringify(query)} in ${target}${include ? ` (${include})` : ""}${from > 0 ? ` past offset ${from}` : ""}`;

package/dist/repo-github/checkout.d.ts

@@ -17,6 +17,22 @@
 interface RefreshOutcome {
     message: string;
     branch?: string;
+    /**
+     * Set once this directory is known to hold a checkout of the repository that
+     * was asked for, with a tree git could read.
+     *
+     * Weaker than `branch` on purpose, and the difference is the dirty tree: that
+     * checkout is there and is the right repository, so an answer may describe
+     * what is in it, while nothing may *act* on it.
+     *
+     * The returns above the status read leave it unset, and so does the status
+     * read's own failure: a tree git could not read is not one to read anything
+     * else out of, and the doubt that stops the reset below stops a description of
+     * what is on the disk under it. A caller cannot tell any of that from the
+     * message alone, which is why this is a flag and not a reading of the
+     * sentence.
+     */
+    checkout?: true;
 }
 /**
  * What this module needs back from a git command.

package/dist/repo-github/checkout.js

@@ -119,6 +119,7 @@ export async function refreshCheckout({ dir, url, branch, author, plain, fetchOr
         // call established — kicking off an install over it would be acting on a
         // state the model has not looked at yet.
         return {
+            checkout: true,
             message: `${dir} already has this repository checked out, with uncommitted changes:\n` +
                 `${dirty.stdout.trim()}\n\n` +
                 `Left untouched — these may be unfinished work from an earlier task. ` +
@@ -140,10 +141,11 @@ export async function refreshCheckout({ dir, url, branch, author, plain, fetchOr
         const current = await plain("symbolic-ref --quiet --short HEAD", dir);
         const on = current.success ? current.stdout.trim() : "";
         if (!on)
-            return { message: failure };
+            return { message: failure, checkout: true };
         return {
             message: `${failure}\nThe checkout was left on ${on}, clean but not updated from the remote.`,
-            branch: on
+            branch: on,
+            checkout: true
         };
     }
     // The branch to land on: the one asked for, else the remote's own default.
@@ -155,12 +157,16 @@ export async function refreshCheckout({ dir, url, branch, author, plain, fetchOr
         // way.
         if (head.unreachable)
             return {
-                message: `could not read the default branch for ${url}: ${head.unreachable}`
+                message: `could not read the default branch for ${url}: ${head.unreachable}`,
+                checkout: true
             };
         target = head.branch;
     }
     if (!target)
-        return { message: `could not determine a default branch for ${url}` };
+        return {
+            message: `could not determine a default branch for ${url}`,
+            checkout: true
+        };
     // The one place in this plugin where a model-authored value lands in git's
     // *operand* position — everywhere else it is prefixed (`origin/…`,
     // `refs/heads/…`) or is a flag's value. Quoting is not enough: it stops
@@ -172,17 +178,20 @@ export async function refreshCheckout({ dir, url, branch, author, plain, fetchOr
     });
     if (!checkout.success)
         return {
-            message: `could not check out ${target}: ${checkout.stderr || checkout.stdout}`
+            message: `could not check out ${target}: ${checkout.stderr || checkout.stdout}`,
+            checkout: true
         };
     const reset = await plain(`reset --hard "origin/$REPO_BRANCH"`, dir, {
         REPO_BRANCH: target
     });
     if (!reset.success)
         return {
-            message: `could not reset to origin/${target}: ${reset.stderr || reset.stdout}`
+            message: `could not reset to origin/${target}: ${reset.stderr || reset.stdout}`,
+            checkout: true
         };
     return {
         message: `reused the existing checkout at ${dir}, fetched and reset to origin/${target}`,
-        branch: target
+        branch: target,
+        checkout: true
     };
 }

package/dist/repo-github/context.d.ts

@@ -47,6 +47,17 @@ export interface RepoContext {
         stdout?: string;
     }) => void;
     plain: (args: string, cwd: string, vars?: Record<string, string>) => Promise<RunResult>;
+    /**
+     * The same runner without git in front of it, for the one thing these tools
+     * read that git cannot answer: what a checkout's own files say.
+     * {@link file://./skills.ts skillInventory} is what runs on it.
+     *
+     * Published alongside `plain` rather than instead of it. Every command this
+     * plugin runs is still one of two shapes, and a reader can tell which from the
+     * call: `plain` is a git subcommand, `shell` is a script whose text is this
+     * package's own constant.
+     */
+    shell: (script: string, cwd: string, vars?: Record<string, string>) => Promise<RunResult>;
     runGit: (op: () => Promise<RepoGitResult>) => Promise<RunResult>;
     fetchOrigin: (dir: string, url: string) => Promise<RunResult>;
     pushBranch: (dir: string, url: string, branch: string) => Promise<RunResult>;

package/dist/repo-github/context.js

@@ -532,6 +532,7 @@ runtime = () => undefined) {
         notifyCheckout,
         logFailure,
         plain,
+        shell,
         runGit,
         fetchOrigin,
         pushBranch,

package/dist/repo-github/skills.d.ts

@@ -0,0 +1,167 @@
+/**
+ * What skills a checkout carries, and how a prompt may reach each one.
+ *
+ * A Claude Code session reads the skills of the repository it is running in, and
+ * the agent that briefs that session has no other way to learn they are there:
+ * the session is a separate process with a context of its own, so a skill it
+ * should follow has to be named in the prompt it is given. This is what lets
+ * `repo_clone` answer with the list.
+ *
+ * **Why it is here rather than in the plugin that owns a session.** This package
+ * fails any subpath whose module graph reaches a sibling's, so the plugin that
+ * holds the checkout is the only one that can read it. What belongs to the
+ * session's own domain is the *policy*, which is to say when a skill should be
+ * named, and that stays with the host writing the prompt. This module reports
+ * what is in the checkout and what each skill's own frontmatter says about
+ * reaching it.
+ *
+ * The split inside the module is the one {@link file://./checkout.ts checkout.ts}
+ * uses: a runner arrives as a parameter and everything that reads is pure, so
+ * the parsing and the rendering are tested without a container.
+ */
+/**
+ * Where Claude Code reads a project's skills from, relative to the checkout.
+ *
+ * One level of it: `<dir>/<name>/SKILL.md` and no deeper, which is the layout a
+ * session loads. A skill a repository keeps somewhere else of its own is not
+ * collected and is not reported as missing either, because nothing here can tell
+ * such a directory from any other.
+ */
+export declare const SKILLS_DIR = ".claude/skills";
+/**
+ * How many skills the answer lists, and how long a description it carries.
+ *
+ * Both bound an answer the model pays for on every clone, and neither is a
+ * judgement about which skills matter. They are set against a real checkout
+ * rather than guessed: this workspace's own set of skills renders whole at these
+ * values, in 5,731 characters, inside the sixteen thousand `maxOutputChars`
+ * defaults to. A cap tight enough to bite would drop skills in ordinal order,
+ * and the one dropped could be the one somebody has to name, which is the
+ * failure these numbers are chosen to stay clear of.
+ *
+ * A description here is a line that helps decide whether to open the skill, not
+ * a substitute for reading it.
+ *
+ * Exported for the specs, which assert the bound rather than restate the
+ * number. Nothing outside this package reads them: `./index.ts` is what the
+ * subpath publishes, and it exports neither.
+ */
+export declare const MAX_SKILLS_LISTED = 40;
+export declare const MAX_DESCRIPTION_CHARS = 200;
+/**
+ * What one command this module runs answers with.
+ *
+ * A structural subset of `context.ts`'s `RunResult`, for the reason
+ * {@link file://./checkout.ts GitAnswer} is the home of: the dependency runs one
+ * way, so the tools know about this file and this file knows only the shape of
+ * an answer. Narrower than that one by `unreachable`, which nothing here reads:
+ * a read that never ran and a read that ran and failed cost the same line.
+ */
+export interface ShellAnswer {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+}
+/** The runner {@link skillInventory} borrows from `repoContext`. */
+export type ShellRunner = (script: string, cwd: string) => Promise<ShellAnswer>;
+/**
+ * Collect every skill's frontmatter block, each file's lines indented by one tab
+ * under the line naming its directory.
+ *
+ * **The tab is what makes the stream unambiguous.** A line at column zero names
+ * a skill's directory and every line of that skill's file is indented by one, so
+ * nothing in a file can be read as the start of another record. The obvious
+ * alternative, a separator line of its own, is a string a folded description
+ * could legally contain, and the failure would be a skill silently merged into
+ * its neighbour. It is written by `awk`'s own string escape, which is portable
+ * where `sed`'s `\t` is GNU's, and a published package does not get to assume a
+ * host's image.
+ *
+ * **`awk` stops at the closing delimiter**, so what arrives is the whole block
+ * and not a guess at how long one is. {@link readFrontmatter} reports a block
+ * that arrived without it, and {@link invocationOf} is why that matters: a
+ * restriction sits in whichever line of the block its author put it on, so a
+ * read that stops early is a read that cannot speak for the skill. The `NR == 1`
+ * test is the other half of the saving: a file with no block at all costs one
+ * line rather than the bound.
+ *
+ * **A file this cannot read costs its own record and no other.** The loop's exit
+ * status is the last `printf`'s, so a failed read leaves the directory line with
+ * nothing indented under it, which {@link readFrontmatter} reads as a block
+ * nobody has seen. Failing the whole read instead would spend every other
+ * skill's inventory on one unreadable file.
+ *
+ * It reads through whatever `<dir>/<name>` is. A checkout may commit each entry
+ * as a symlink to a directory it keeps elsewhere, which is how this workspace
+ * holds its own, and the glob and `head` both follow one.
+ *
+ * A glob that matches nothing stays literal in a POSIX shell, so the `-f` test
+ * is what makes an absent `.claude/skills` an empty answer rather than an error.
+ *
+ * The blank line after each record is the stream's own shape rather than a
+ * property of the tool above it: a name starts a line whatever the file below it
+ * ended with. No model input reaches any of this; every path is this module's
+ * own constant.
+ */
+export declare const READ_SKILLS = "for d in .claude/skills/*/; do\n  [ -f \"$d/SKILL.md\" ] || continue\n  printf '%s\\n' \"${d%/}\"\n  head -c 4000 \"$d/SKILL.md\" | awk -v lines=120 '\n    { print \"\\t\" $0 }\n    NR == 1 { if ($0 !~ /^---[[:space:]]*$/) exit; next }\n    /^---[[:space:]]*$/ { exit }\n    NR >= lines { exit }\n  '\n  printf '\\n'\ndone";
+/**
+ * How a prompt may reach a skill, as its frontmatter decides.
+ *
+ * The distinction is not cosmetic, and it is the reason this module reports more
+ * than a name and a description. `disable-model-invocation` takes the skill away
+ * from the model's own skill tool, which leaves naming it as `/<name>` the only
+ * way in; `user-invocable: false` removes that command, which leaves prose. A
+ * host that cannot tell the two apart writes a prompt that silently does
+ * nothing.
+ *
+ * `unknown` is the one that is not a reading of the frontmatter but a statement
+ * about the read: the block did not arrive whole, so the fields that decide this
+ * are fields nobody has seen. It is reported rather than guessed because both
+ * guesses are wrong in a case that happens. The permissive one advertises a
+ * prompt-only skill as one a model picks up by itself, which is the silent
+ * failure above; the strict one takes a way in away from a skill that has it.
+ */
+export type SkillInvocation = "either" | "command" | "prose" | "neither" | "unknown";
+/** One skill a checkout carries. */
+export interface RepoSkill {
+    /** What a prompt names it by: its frontmatter `name`, else its directory. */
+    name: string;
+    description?: string;
+    invocation: SkillInvocation;
+}
+/**
+ * The skills in a checkout, as a sentence the model reads, or why they could not
+ * be read.
+ *
+ * A failed read is reported and never raised: the clone it is appended to
+ * succeeded, and a missing inventory is worth a line rather than an error that
+ * sends the model to investigate git.
+ */
+export declare function skillInventory(shell: ShellRunner, dir: string): Promise<string>;
+/**
+ * {@link READ_SKILLS}'s output, read back.
+ *
+ * Unindented lines name directories and indented ones belong to the file above
+ * them, so the shape of the stream is what separates the records. A blank
+ * unindented line is the trailing newline of the stream, never the end of a
+ * record.
+ *
+ * **A record starts only on a path under {@link SKILLS_DIR}**, which is the one
+ * thing the indentation alone does not settle. Directory names come from a
+ * cloned repository, and one carrying a newline writes a second line at column
+ * zero: without the path, that line opens a record of its own and the skill
+ * above it loses the frontmatter that follows to a name nobody wrote. A
+ * directory name holds no `/`, so what the second line cannot be is a path,
+ * which is what closes it.
+ */
+export declare function readSkillInventory(stdout: string): RepoSkill[];
+/**
+ * The inventory as the model reads it: where this looked, a line per skill, and
+ * what the list left out.
+ *
+ * **The counts are unconditional**, the empty answer included. "No skills here"
+ * and "this tool does not report skills" are different facts, and a repository
+ * that keeps its skills somewhere Claude Code does not read them is the case
+ * that makes the difference worth a sentence.
+ */
+export declare function skillInventoryText(skills: readonly RepoSkill[]): string;