@dynamicagents/plugins 0.16.0 → 0.17.0

package/dist/repo-github/skills.js

@@ -0,0 +1,414 @@
+/**
+ * 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 const SKILLS_DIR = ".claude/skills";
+/**
+ * The backstop on each `SKILL.md` read: a byte ceiling, and a line count on what
+ * is left after it.
+ *
+ * Neither is where frontmatter *ends*. {@link READ_SKILLS} stops at the closing
+ * delimiter, which is the one place that decides it, and these stop a file
+ * carrying no such delimiter from sending a whole skill body through the read:
+ * frontmatter is at the top of a file and a body runs to tens of kilobytes, so
+ * without them a directory of dozens of skills is not a read worth making.
+ *
+ * They are a backstop rather than a limit because a bound that cuts real
+ * frontmatter costs more than a long read does: a field nobody saw is a field
+ * {@link invocationOf} cannot report, and a restriction sits wherever in the
+ * block its author put it, which in the prompt-only skill this was written
+ * against is below a description of several lines. The longest frontmatter in
+ * this workspace is 15 lines and 938 bytes, its description 831 characters of
+ * that, and these bounds are several times both.
+ *
+ * Stopping at the delimiter is most of what the read costs, too: this
+ * workspace's own set of skills arrives in 9,936 bytes, where a bounded head of
+ * every file carries a page of each body along with it and costs five times
+ * that.
+ *
+ * **Bytes are cut by `head` and lines by `awk`**, each by the tool that can do it
+ * without holding the file: `head -c` is what keeps a file whose top is one
+ * enormous line out of `awk`'s `$0`, and `awk` prints whole lines, so what `head`
+ * cut mid-line is still a line of its own in the stream.
+ */
+const SKILL_HEAD_BYTES = 4_000;
+const SKILL_HEAD_LINES = 120;
+/**
+ * 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 const MAX_SKILLS_LISTED = 40;
+export const MAX_DESCRIPTION_CHARS = 200;
+/**
+ * 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 const READ_SKILLS = `for d in ${SKILLS_DIR}/*/; do
+  [ -f "$d/SKILL.md" ] || continue
+  printf '%s\\n' "\${d%/}"
+  head -c ${SKILL_HEAD_BYTES} "$d/SKILL.md" | awk -v lines=${SKILL_HEAD_LINES} '
+    { print "\\t" $0 }
+    NR == 1 { if ($0 !~ /^---[[:space:]]*$/) exit; next }
+    /^---[[:space:]]*$/ { exit }
+    NR >= lines { exit }
+  '
+  printf '\\n'
+done`;
+/**
+ * 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 async function skillInventory(shell, dir) {
+    const read = await shell(READ_SKILLS, dir);
+    if (!read.success) {
+        // Clipped the way a description is, and for the same reason: this is one
+        // line of an answer about a clone that worked. What `context.ts` hands a
+        // tool for a command that never ran is a paragraph on whether retrying a
+        // lost `git push` is safe, which is the right thing to tell a model whose
+        // push vanished and the wrong thing to attach to a checkout that is on disk.
+        const why = read.stderr.trim() || read.stdout.trim();
+        return (`The skills under \`${SKILLS_DIR}\` in this checkout could not be read: ` +
+            `${why ? clip(why) : "the read failed"}`);
+    }
+    return skillInventoryText(readSkillInventory(read.stdout));
+}
+/**
+ * {@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 function readSkillInventory(stdout) {
+    const skills = [];
+    let dir;
+    let head = [];
+    const flush = () => {
+        if (dir !== undefined)
+            skills.push(skillOf(dir, head));
+        head = [];
+    };
+    for (const raw of stdout.split("\n")) {
+        // A checkout written on Windows is still a checkout, and a stray `\r` would
+        // otherwise end up inside a name.
+        const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+        if (line.startsWith("\t")) {
+            head.push(line.slice(1));
+            continue;
+        }
+        if (!line.startsWith(`${SKILLS_DIR}/`))
+            continue;
+        flush();
+        dir = line.trim();
+    }
+    flush();
+    return skills;
+}
+/** One skill, from its directory and the head of its `SKILL.md`. */
+function skillOf(dir, head) {
+    const front = readFrontmatter(head);
+    const described = front.fields.description?.trim();
+    return {
+        // The directory is the fallback because it is the only name left: a block
+        // that did not parse, or did not arrive at all, still leaves a directory
+        // with a `SKILL.md` in it, and a reader given its name can go and look.
+        name: front.fields.name?.trim() || directoryName(dir),
+        ...(described ? { description: described } : {}),
+        invocation: invocationOf(front)
+    };
+}
+function directoryName(dir) {
+    const at = dir.lastIndexOf("/");
+    return at < 0 ? dir : dir.slice(at + 1);
+}
+/** What the two invocation fields leave open. See {@link SkillInvocation}. */
+function invocationOf(front) {
+    // A block that did not arrive whole is a block whose remaining fields nobody
+    // has seen, and an absent field is a default only among fields that were
+    // read. A restriction sits wherever in the block its author put it, below the
+    // description as often as above it, so reading the defaults here would let
+    // the length of a skill's prose decide whether its restriction is reported.
+    if (!front.whole)
+        return "unknown";
+    const model = !isTrue(front.fields["disable-model-invocation"]);
+    const person = !isFalse(front.fields["user-invocable"]);
+    if (model && person)
+        return "either";
+    if (person)
+        return "command";
+    if (model)
+        return "prose";
+    return "neither";
+}
+/**
+ * The YAML 1.1 spellings of a boolean, because that is what a frontmatter author
+ * writes. Anything else reads as absent, which leaves the field's default: a
+ * skill is model-invocable and user-invocable unless it says otherwise, so an
+ * unreadable value never takes a way in away.
+ */
+const TRUE = /^(?:true|yes|on)$/i;
+const FALSE = /^(?:false|no|off)$/i;
+const isTrue = (value) => value !== undefined && TRUE.test(value.trim());
+const isFalse = (value) => value !== undefined && FALSE.test(value.trim());
+/** The frontmatter delimiter, opening and closing. */
+const DELIMITER = /^---\s*$/;
+/**
+ * A value that says the scalar is the lines below it: a block indicator, or
+ * nothing at all. An empty value is the plain multi-line form,
+ * `description:` with its text indented under it, and it folds the same way.
+ */
+const BLOCK = /^(?:[>|][-+]?\s*)?$/;
+/**
+ * The frontmatter block's **top-level** keys.
+ *
+ * Top-level is the load-bearing word. A skill's frontmatter carries nested
+ * mappings (`metadata:` with children under it), and a child spelled `name:`
+ * would otherwise overwrite the skill's own. Reading column zero only is what
+ * keeps a nested key out, and it costs nothing: every field this module wants is
+ * at the top level.
+ *
+ * Not a YAML implementation, and deliberately narrow: nothing inside quotes is
+ * unescaped, and every block form folds to one line. What it does carry is the
+ * YAML that changes an answer here, which is {@link commentOff}'s.
+ */
+function readFrontmatter(head) {
+    const fields = {};
+    // Nothing arrived at all, which is what a `SKILL.md` the read could not open
+    // looks like from here: the directory was named and no line followed it.
+    if (head.length === 0)
+        return { fields, whole: false };
+    let at = head.findIndex((line) => line.trim() !== "");
+    // No block to read. Nothing was cut short either, so what the fields below
+    // default to is a reading of this file rather than a guess about it.
+    if (at < 0 || !DELIMITER.test(head[at]))
+        return { fields, whole: true };
+    for (at += 1; at < head.length; at += 1) {
+        const line = head[at];
+        if (DELIMITER.test(line))
+            return { fields, whole: true };
+        // Indented or blank: a nested key, a block scalar's own lines when one was
+        // not consumed below, or spacing. A whole-line comment is not a field
+        // either, and reading one as a key is how a commented-out field comes back.
+        if (line.trim() === "" || /^[\s#]/.test(line))
+            continue;
+        const colon = line.indexOf(":");
+        if (colon < 0)
+            continue;
+        const key = line.slice(0, colon).trim();
+        const value = commentOff(line.slice(colon + 1).trim());
+        if (BLOCK.test(value)) {
+            const block = readBlock(head, at + 1);
+            fields[key] = block.text;
+            at = block.next - 1;
+            continue;
+        }
+        fields[key] = unquote(value);
+    }
+    return { fields, whole: false };
+}
+/**
+ * A block scalar's lines, folded to one.
+ *
+ * Every block form is folded the same way, `|` included, and that is a
+ * simplification rather than an oversight: the answer carries one clipped line
+ * per skill, so a literal block's newlines are removed by the clip a moment
+ * later. Reading this as YAML's folding rules would be reading it as more than
+ * it is.
+ */
+function readBlock(head, from) {
+    const lines = [];
+    let at = from;
+    for (; at < head.length; at += 1) {
+        const line = head[at];
+        if (DELIMITER.test(line))
+            break;
+        if (line.trim() !== "" && !/^\s/.test(line))
+            break;
+        if (line.trim() !== "")
+            lines.push(line.trim());
+    }
+    return { text: lines.join(" "), next: at };
+}
+/**
+ * Where a YAML comment starts in a plain scalar: a `#` at the value's start, or
+ * one with whitespace in front of it. Nowhere else, which is what keeps `C#` and
+ * `#tag` inside a value.
+ */
+const COMMENT = /(?:^|\s)#/;
+/** What may follow a quoted scalar's closing quote, and all that may. */
+const AFTER_QUOTE = /^\s+#/;
+/**
+ * One scalar's text with a YAML comment taken off, quotes left as they are.
+ *
+ * Both halves of YAML's rule change an answer here.
+ * `disable-model-invocation: true # named from the prompt` is a restriction
+ * whose value is not the string `true`, so left whole it reads as a spelling
+ * nothing recognises and hands the skill back the way in it just gave up; and
+ * `name: audit # the command` would otherwise be offered as `/audit # the
+ * command`. Inside quotes nothing starts a comment, and a description carries a
+ * hash legitimately, so a quoted value is read to its closing quote and only a
+ * comment may follow it.
+ *
+ * A plain value that loses text to a ` #` has lost it in Claude Code's reading
+ * of the same file, which is the test for whether cutting it is right: this
+ * module reads a field the way the parser that acts on it does, or it reports
+ * something nobody wrote.
+ */
+function commentOff(value) {
+    const quote = value[0];
+    if (quote === '"' || quote === "'") {
+        const close = value.lastIndexOf(quote);
+        // A scalar whose quote closes, with nothing after it or a comment. Anything
+        // else never was a quoted scalar, and is left to `unquote` to read as it
+        // stands.
+        if (close > 0 && AFTER_QUOTE.test(value.slice(close + 1)))
+            return value.slice(0, close + 1);
+        return value;
+    }
+    const at = value.search(COMMENT);
+    return at < 0 ? value : value.slice(0, at).trimEnd();
+}
+/** A scalar with one matching pair of quotes taken off. */
+function unquote(value) {
+    const quoted = value.length >= 2 &&
+        (value.startsWith('"') || value.startsWith("'")) &&
+        value.endsWith(value[0]);
+    return quoted ? value.slice(1, -1) : value;
+}
+/**
+ * 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 function skillInventoryText(skills) {
+    // Ordinal, and not a ranking: nothing here knows which skill matters to the
+    // task, so the order is the one a reader can predict.
+    const sorted = [...skills].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    const listed = sorted.slice(0, MAX_SKILLS_LISTED);
+    const counts = `${skills.length} ${skills.length === 1 ? "skill" : "skills"}, ` +
+        `${listed.length} listed, ${skills.length - listed.length} omitted.`;
+    if (listed.length === 0) {
+        return `No skills under \`${SKILLS_DIR}\` in this checkout: ${counts}`;
+    }
+    return [
+        `Skills under \`${SKILLS_DIR}\` in this checkout:`,
+        ...listed.map(skillLine),
+        counts
+    ].join("\n");
+}
+function skillLine(skill) {
+    const note = {
+        either: "",
+        command: ` (name it as \`/${skill.name}\`)`,
+        prose: " (name it in prose; it has no `/` form)",
+        neither: " (no prompt can invoke it)",
+        unknown: " (how to reach it is unknown: its frontmatter did not read whole)"
+    }[skill.invocation];
+    const described = skill.description ? `: ${clip(skill.description)}` : "";
+    return `- \`${skill.name}\`${note}${described}`;
+}
+/**
+ * One line, cut at a word rather than mid-word.
+ *
+ * The bound is a description's, and a failed read's reason takes the same one:
+ * both are one line of an answer whose subject is the clone.
+ */
+function clip(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    if (flat.length <= MAX_DESCRIPTION_CHARS)
+        return flat;
+    const cut = flat.slice(0, MAX_DESCRIPTION_CHARS);
+    const space = cut.lastIndexOf(" ");
+    return `${space > 0 ? cut.slice(0, space) : cut}…`;
+}

package/dist/repo-github/tools-clone.js

@@ -2,12 +2,31 @@ import { tool } from "ai";
 import { z } from "zod";
 import { parseRepo, repoLocation, UNSAFE_BRANCH } from "./url.js";
 import { refreshCheckout, writeGitIdentity } from "./checkout.js";
+import { skillInventory } from "./skills.js";
 /** Putting a checkout on disk, fresh or refreshed. */
 export function cloneTools(ctx) {
-    const { config, workdir, author, allowedHosts, bounded, notifyCheckout, logFailure, plain, runGit, fetchOrigin } = ctx;
+    const { config, workdir, author, allowedHosts, bounded, notifyCheckout, logFailure, plain, shell, runGit, fetchOrigin } = ctx;
+    /**
+     * One answer about a checkout that is on disk: what happened to it, and the
+     * skills the repository carries.
+     *
+     * **Only for an answer that establishes such a checkout.** A URL that names no
+     * repository, a directory holding a different one, and a tree git could not
+     * read are all answers about where the checkout is *not*, and an inventory
+     * read on that path would be describing something nobody asked about. What
+     * tells the two apart on the refresh path is `checkout` in
+     * {@link file://./checkout.ts refreshCheckout}'s outcome.
+     *
+     * Bounded here rather than in the inventory: the inventory caps itself at a
+     * list a reader can use, and this is the host's own ceiling on an answer,
+     * which the rest of the plugin applies in the same place. The refusals that
+     * carry no inventory are bounded in the same expression, since each of them
+     * quotes something it was given: another remote's URL, or git's own output.
+     */
+    const withSkills = async (message, dir) => bounded(`${message}\n\n${await skillInventory(shell, dir)}`);
     return {
         repo_clone: tool({
-            description: "Clone a git repository into the workspace. Returns the checkout path and the branch you landed on. If the repository is already checked out from an earlier task, it is fetched and reset to the remote instead — unless it has uncommitted changes, which are left alone for you to inspect.",
+            description: "Clone a git repository into the workspace. Returns the checkout path, the branch you landed on, and the skills the repository carries with how each one may be named in a prompt. If the repository is already checked out from an earlier task, it is fetched and reset to the remote instead. A checkout with uncommitted changes is left alone for you to inspect.",
             inputSchema: z.object({
                 url: z.string().describe("HTTPS repository URL"),
                 branch: z
@@ -125,7 +144,9 @@ export function cloneTools(ctx) {
                             fresh: false
                         });
                     }
-                    return refreshed.message;
+                    return refreshed.checkout
+                        ? await withSkills(refreshed.message, dir)
+                        : bounded(refreshed.message);
                 }
                 // `depth` is bounded here rather than trusted from the schema. It no
                 // longer reaches a shell, so this is arithmetic rather than quoting: a
@@ -166,7 +187,7 @@ export function cloneTools(ctx) {
                     branch: landed,
                     fresh: true
                 });
-                return `cloned to ${dir} on branch ${landed}`;
+                return await withSkills(`cloned to ${dir} on branch ${landed}`, dir);
             }
         })
     };

package/dist/sandbox/header.d.ts

@@ -48,3 +48,16 @@ export declare function readRunHeader(text: string): {
 };
 /** Whether `path` is `root` or inside it, with no `..` escaping it. */
 export declare function isUnder(path: string, root: string): boolean;
+/**
+ * `path` with its dot segments and repeated separators resolved, or `undefined`
+ * for one that is not absolute or that climbs above `/`.
+ *
+ * Shared with the tools rather than kept here, because anything comparing a
+ * path against this root has to compare what the path *means*: `/workspace/.`
+ * and `/workspace/repo/..` are both this root, and a comparison that read them
+ * literally would answer no to a path the sandbox itself answers yes to.
+ *
+ * A `..` with nothing left to pop is refused rather than clamped at `/`: a
+ * clamp would turn an attempt to climb out into a valid root path.
+ */
+export declare function normalizeAbsolute(path: string): string | undefined;

package/dist/sandbox/header.js

@@ -75,20 +75,35 @@ function assertRunHeader(value) {
 }
 /** Whether `path` is `root` or inside it, with no `..` escaping it. */
 export function isUnder(path, root) {
+    const normal = normalizeAbsolute(path);
+    return (normal !== undefined && (normal === root || normal.startsWith(`${root}/`)));
+}
+/**
+ * `path` with its dot segments and repeated separators resolved, or `undefined`
+ * for one that is not absolute or that climbs above `/`.
+ *
+ * Shared with the tools rather than kept here, because anything comparing a
+ * path against this root has to compare what the path *means*: `/workspace/.`
+ * and `/workspace/repo/..` are both this root, and a comparison that read them
+ * literally would answer no to a path the sandbox itself answers yes to.
+ *
+ * A `..` with nothing left to pop is refused rather than clamped at `/`: a
+ * clamp would turn an attempt to climb out into a valid root path.
+ */
+export function normalizeAbsolute(path) {
     if (!path.startsWith("/"))
-        return false;
+        return undefined;
     const parts = [];
     for (const part of path.split("/")) {
         if (part === "" || part === ".")
             continue;
         if (part === "..") {
             if (parts.length === 0)
-                return false;
+                return undefined;
             parts.pop();
             continue;
         }
         parts.push(part);
     }
-    const normal = `/${parts.join("/")}`;
-    return normal === root || normal.startsWith(`${root}/`);
+    return `/${parts.join("/")}`;
 }

package/dist/sandbox/install-plan.d.ts

@@ -36,7 +36,7 @@ export interface InstallProbe {
  * Where the install has got to, as the host reports it and the tools read it.
  *
  * Declared here rather than in the host because both sides depend on it and
- * neither owns the other: the Durable Object runs the job, and `bash` refuses
+ * neither owns the other: the Durable Object runs the job, and the shell tool refuses
  * to run against a tree that is still being built. A shape they agreed on
  * informally would drift, and the drift would show up as a shell command running
  * halfway through an `npm ci`.

package/dist/sandbox/install-plan.js

@@ -26,6 +26,7 @@
  * absent. So: an explicit override wins, then the repository's own
  * `packageManager` pin, then lockfiles in the order the plan lists them.
  */
+import { sha256Hex } from "@dynamicagents/core";
 /**
  * A sensible starting table, meant to be copied into a host and edited.
  *
@@ -304,8 +305,5 @@ async function digestFiles(fs, dir, names, prefix) {
     }
     if (!found)
         return null;
-    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
-    return [...new Uint8Array(digest)]
-        .map((b) => b.toString(16).padStart(2, "0"))
-        .join("");
+    return await sha256Hex(input);
 }

package/dist/sandbox/object.d.ts

@@ -96,6 +96,7 @@ export declare abstract class SandboxObjectBase<Env extends object = Cloudflare.
         type: string;
         size: number;
         modifiedAt: number;
+        mode: number;
     } | null>;
     readDir(path: string): Promise<{
         name: string;

package/dist/sandbox/object.js

@@ -1,5 +1,6 @@
 import { DurableObject } from "cloudflare:workers";
 import { ContainerHarness, containerAgent } from "agents/harness/container";
+import { sha256Hex } from "@dynamicagents/core";
 import { installScheduler, namedDeadline } from "@dynamicagents/core/alarm";
 import { DirectoryBackup, Files } from "@cloudflare/sandbox";
 import { asAgent, AGENT_GID, AGENT_UID, shellQuote } from "./agent-exec.js";
@@ -380,7 +381,11 @@ export class SandboxObjectBase extends DurableObject {
                 return {
                     type: stat.type,
                     size: Number(stat.size),
-                    modifiedAt: stat.modifiedAt.getTime()
+                    modifiedAt: stat.modifiedAt.getTime(),
+                    // Reported because the file tools' own contract asks for one, and
+                    // the container knows it. Nothing can set it back: the sandbox's
+                    // write takes no mode.
+                    mode: stat.mode
                 };
             }
             catch (err) {
@@ -1105,14 +1110,16 @@ function markOf(dir) {
 function installMarkOf(dir) {
     return `${INSTALL_MARKS}/${encodeURIComponent(dir)}`;
 }
-/** `env`, in key order, as a digest a fingerprint can carry. */
+/**
+ * `env`, in key order, as a digest a fingerprint can carry.
+ *
+ * The width is load-bearing: this goes into an install mark stored on the
+ * container's disk, so changing it makes every tree already marked look
+ * uninstalled and costs each one an install it does not need.
+ */
 async function digestEnv(env) {
     const sorted = Object.entries(env ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
-    const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(sorted)));
-    return [...new Uint8Array(bytes)]
-        .map((b) => b.toString(16).padStart(2, "0"))
-        .join("")
-        .slice(0, 16);
+    return (await sha256Hex(JSON.stringify(sorted))).slice(0, 16);
 }
 function isNotFound(err) {
     return (typeof err === "object" &&
@@ -1129,11 +1136,12 @@ function isAbort(err) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * `value`, as the digest a poll returns beside a message.
+ *
+ * Nothing stores it: a poll composes it again for every message it answers
+ * with, so the width has only to tell two messages apart.
+ */
 async function digest(value) {
-    const bytes = new TextEncoder().encode(JSON.stringify(value));
-    const hash = await crypto.subtle.digest("SHA-256", bytes);
-    return [...new Uint8Array(hash)]
-        .slice(0, 12)
-        .map((byte) => byte.toString(16).padStart(2, "0"))
-        .join("");
+    return (await sha256Hex(JSON.stringify(value))).slice(0, 24);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamicagents/plugins",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Optional, composable capabilities for a Dynamic Agent: browser rendering, a Linux container, git and pull requests on GitHub, a scratchpad, and Claude Code sessions. One subpath per plugin, so a bundle grows only with what it imports.",
   "keywords": [
     "ai-agents",
@@ -84,10 +84,11 @@
     "prepare": "husky || true && npm run build"
   },
   "peerDependencies": {
+    "@cloudflare/computer": "^0.5.1",
     "@cloudflare/sandbox": "^1.0.1",
-    "@cloudflare/think": ">=0.20.2 <0.21.0",
-    "@dynamicagents/core": ">=0.16.0 <0.17.0",
-    "agents": ">=0.28.0 <0.29.0",
+    "@cloudflare/think": ">=0.21.0 <0.22.0",
+    "@dynamicagents/core": ">=0.17.0 <0.18.0",
+    "agents": ">=0.30.0 <0.31.0",
     "ai": "^7.0.88",
     "zod": "^4.4.3"
   },
@@ -97,12 +98,13 @@
     }
   },
   "devDependencies": {
+    "@cloudflare/computer": "^0.5.1",
     "@cloudflare/sandbox": "^1.0.1",
-    "@cloudflare/think": "^0.20.2",
+    "@cloudflare/think": "^0.21.0",
     "@cloudflare/vitest-plugin": "^1.4.4",
-    "@dynamicagents/core": "^0.16.0",
+    "@dynamicagents/core": "^0.17.1",
     "@types/node": "^26.5.1",
-    "agents": "^0.28.0",
+    "agents": "^0.30.1",
     "ai": "^7.0.101",
     "eslint": "^10.10.0",
     "husky": "^9.1.7",