wave-agent-sdk 1.2.0 → 1.3.0

package/dist/utils/nestedMemory.d.ts

@@ -0,0 +1,22 @@
+export interface NestedMemoryFile {
+    path: string;
+    content: string;
+}
+/**
+ * Collect the memory files that sit in the directories above a file the agent
+ * just read, outermost first.
+ *
+ * The root memory file is loaded eagerly into every request, so putting
+ * subdirectory-specific conventions there costs context on every turn; this
+ * pulls them in only once work actually reaches that subtree.
+ *
+ * Aligned with Claude Code's `nested_memory` attachment (attachments.ts
+ * `getDirectoriesToProcess` + `memoryFilesToAttachments`): the walk stops at
+ * the project root (the root's own memory file is already loaded), only
+ * directories inside the project are considered, and the order is root-ward
+ * first so the most specific file lands closest to the read.
+ *
+ * `loadedPaths` is the session-level dedup set, owned by the caller — it must
+ * outlive any read-state cache, or an eviction re-injects the same file.
+ */
+export declare function findNestedMemoryFiles(filePath: string, workdir: string, loadedPaths: Set<string>): Promise<NestedMemoryFile[]>;

package/dist/utils/nestedMemory.js

@@ -0,0 +1,61 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isPathInside } from "./pathSafety.js";
+/**
+ * Memory file names to look for in a directory, in priority order:
+ * `AGENTS.md` is the convention, `CLAUDE.md` the compatibility fallback —
+ * the same order `MemoryService.readMemoryFile` uses for project memory.
+ */
+const NESTED_MEMORY_FILENAMES = ["AGENTS.md", "CLAUDE.md"];
+/**
+ * Collect the memory files that sit in the directories above a file the agent
+ * just read, outermost first.
+ *
+ * The root memory file is loaded eagerly into every request, so putting
+ * subdirectory-specific conventions there costs context on every turn; this
+ * pulls them in only once work actually reaches that subtree.
+ *
+ * Aligned with Claude Code's `nested_memory` attachment (attachments.ts
+ * `getDirectoriesToProcess` + `memoryFilesToAttachments`): the walk stops at
+ * the project root (the root's own memory file is already loaded), only
+ * directories inside the project are considered, and the order is root-ward
+ * first so the most specific file lands closest to the read.
+ *
+ * `loadedPaths` is the session-level dedup set, owned by the caller — it must
+ * outlive any read-state cache, or an eviction re-injects the same file.
+ */
+export async function findNestedMemoryFiles(filePath, workdir, loadedPaths) {
+    const root = path.resolve(workdir);
+    const directories = [];
+    let current = path.dirname(path.resolve(filePath));
+    while (current !== root && isPathInside(current, root)) {
+        directories.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    // Outermost (closest to the project root) first — Claude Code's order.
+    directories.reverse();
+    const memories = [];
+    for (const directory of directories) {
+        for (const filename of NESTED_MEMORY_FILENAMES) {
+            const candidate = path.join(directory, filename);
+            // One memory file per directory: a directory whose AGENTS.md was already
+            // injected must not fall through to its CLAUDE.md.
+            if (loadedPaths.has(candidate))
+                break;
+            try {
+                const content = await fs.readFile(candidate, "utf-8");
+                loadedPaths.add(candidate);
+                memories.push({ path: candidate, content });
+                break;
+            }
+            catch {
+                // Try the next candidate name; a missing AGENTS.md falls back to
+                // CLAUDE.md, and an unreadable file must not abort the whole chain.
+            }
+        }
+    }
+    return memories;
+}

package/dist/utils/npmTarball.d.ts

@@ -0,0 +1,19 @@
+export interface TarballEntry {
+    /** Path relative to the package root (the leading `package/` is removed). */
+    path: string;
+    kind: "file" | "directory";
+    /** File contents; empty for directories. */
+    data: Uint8Array;
+    /**
+     * Unix permission bits from the header (e.g. `0o755`). Callers that only write
+     * files may ignore it, but an executable payload (the ripgrep binary) is
+     * unusable without the exec bit.
+     */
+    mode: number;
+}
+/**
+ * Decompress and list an npm tarball. Directory entries are returned (empty
+ * `data`) so callers can recreate empty directories, but a caller that just
+ * writes files may ignore them.
+ */
+export declare function extractNpmTarball(tarball: Uint8Array): TarballEntry[];

package/dist/utils/npmTarball.js

@@ -0,0 +1,92 @@
+/**
+ * Minimal npm-tarball reader: gunzip + ustar extraction, no dependencies.
+ *
+ * The runtime-dependency installer (`runtimeDeps.ts`) downloads packages
+ * straight from the registry instead of shelling out to npm, so it needs to
+ * turn a `.tgz` into files. Node ships gzip (`zlib`) but not tar, and pulling in
+ * a tar package would drag a dependency into the CLI bundle for one code path.
+ *
+ * Scope is deliberately narrow — this reads *npm* tarballs, not tar in general:
+ *
+ * - npm wraps every entry in a top-level `package/` directory; that wrapper is
+ *   stripped, so returned paths are relative to the package root. Anything not
+ *   under it is an unexpected layout and throws rather than guessing.
+ * - Regular files (`0`) and directories (`5`) are supported. Everything else —
+ *   GNU long names (`L`), pax headers (`x`), symlinks (`2`) — throws: npm
+ *   publishes none of them, and silently skipping an entry would leave a
+ *   half-installed package that only fails later.
+ * - The 512-byte ustar `prefix` field is honoured, so paths beyond 100 bytes
+ *   resolve correctly.
+ * - Permission bits are reported (`mode`), not applied — some packages ship an
+ *   executable payload (`@vscode/ripgrep-*` holds `bin/rg` at `0o755`), and
+ *   whoever writes the files has to set the exec bit itself.
+ *
+ * Tarball integrity (sha512 from the registry) is verified by the caller before
+ * extraction, so this module does not re-checksum headers.
+ */
+import { gunzipSync } from "node:zlib";
+const BLOCK_SIZE = 512;
+/** Read a NUL-terminated (or full-length) utf8 field out of a tar header. */
+function readField(block, offset, length) {
+    let end = offset;
+    const limit = offset + length;
+    while (end < limit && block[end] !== 0)
+        end++;
+    return Buffer.from(block.subarray(offset, end)).toString("utf8");
+}
+/** Reject anything that could escape the target directory. */
+function assertSafeRelativePath(path) {
+    if (path.startsWith("/") || path.split("/").some((seg) => seg === "..")) {
+        throw new Error(`Refusing unsafe path in npm tarball: ${path}`);
+    }
+}
+/**
+ * Decompress and list an npm tarball. Directory entries are returned (empty
+ * `data`) so callers can recreate empty directories, but a caller that just
+ * writes files may ignore them.
+ */
+export function extractNpmTarball(tarball) {
+    const tar = gunzipSync(tarball);
+    const entries = [];
+    let offset = 0;
+    while (offset + BLOCK_SIZE <= tar.length) {
+        const header = tar.subarray(offset, offset + BLOCK_SIZE);
+        offset += BLOCK_SIZE;
+        // A zeroed block marks the end of the archive (conventionally two of them).
+        if (header.every((byte) => byte === 0))
+            break;
+        const name = readField(header, 0, 100);
+        const size = Number.parseInt(readField(header, 124, 12).trim(), 8);
+        const mode = Number.parseInt(readField(header, 100, 8).trim(), 8);
+        const typeFlag = String.fromCharCode(header[156]);
+        const prefix = readField(header, 345, 155);
+        const fullPath = prefix ? `${prefix}/${name}` : name;
+        if (!Number.isInteger(size) || size < 0) {
+            throw new Error(`Corrupt npm tarball: bad size field for ${fullPath}`);
+        }
+        const data = tar.subarray(offset, offset + size);
+        if (data.length < size) {
+            throw new Error(`Corrupt npm tarball: truncated entry ${fullPath}`);
+        }
+        offset += Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+        if (fullPath === "package")
+            continue; // the wrapper directory itself
+        if (!fullPath.startsWith("package/")) {
+            throw new Error(`Unexpected npm tarball layout: ${fullPath}`);
+        }
+        const path = fullPath.slice("package/".length);
+        if (path === "")
+            continue;
+        assertSafeRelativePath(path);
+        if (typeFlag === "5") {
+            entries.push({ path, kind: "directory", data: new Uint8Array(0), mode });
+            continue;
+        }
+        if (typeFlag === "0" || typeFlag === "\0") {
+            entries.push({ path, kind: "file", data: Buffer.from(data), mode });
+            continue;
+        }
+        throw new Error(`Unsupported tar entry type "${typeFlag}" in npm tarball: ${fullPath}`);
+    }
+    return entries;
+}

package/dist/utils/pluginSource.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Marketplace plugin entry `source` parsing (spec plugin A-021).
+ *
+ * Two shapes are accepted:
+ * - **string** — a Git URL (`http://` / `https://` / `git@` / `ssh://`, optionally
+ *   `url#ref`) or a path relative to the marketplace checkout.
+ * - **object** — `{"source":"url","url":…}` (whole repo) or
+ *   `{"source":"git-subdir","url":…,"path":…}` (subdirectory of that repo), both
+ *   optionally carrying `ref` (branch/tag) and `sha` (pinned commit, wins over `ref`).
+ *
+ * Tolerance is per-entry (spec plugin「兼容 Claude Code 生态的市场清单与插件」场景 4):
+ * an unrecognized shape yields `undefined` so only that entry fails, never the
+ * whole marketplace listing.
+ */
+export interface LocalPluginSource {
+    kind: "local";
+    /** Path relative to the marketplace checkout. */
+    path: string;
+}
+export interface GitPluginSource {
+    kind: "git";
+    url: string;
+    /** Branch or tag. */
+    ref?: string;
+    /** Pinned commit; when present it is checked out after cloning. */
+    sha?: string;
+    /** Subdirectory inside the cloned repository that holds the plugin. */
+    subdir?: string;
+}
+export type ParsedPluginSource = LocalPluginSource | GitPluginSource;
+export declare function isGitUrl(value: string): boolean;
+export declare function parsePluginSource(source: unknown): ParsedPluginSource | undefined;
+/**
+ * Renders an unrecognized `source` for error messages so install failures name
+ * the offending shape instead of hiding it (spec plugin A-021).
+ */
+export declare function describePluginSource(source: unknown): string;

package/dist/utils/pluginSource.js

@@ -0,0 +1,73 @@
+/**
+ * Marketplace plugin entry `source` parsing (spec plugin A-021).
+ *
+ * Two shapes are accepted:
+ * - **string** — a Git URL (`http://` / `https://` / `git@` / `ssh://`, optionally
+ *   `url#ref`) or a path relative to the marketplace checkout.
+ * - **object** — `{"source":"url","url":…}` (whole repo) or
+ *   `{"source":"git-subdir","url":…,"path":…}` (subdirectory of that repo), both
+ *   optionally carrying `ref` (branch/tag) and `sha` (pinned commit, wins over `ref`).
+ *
+ * Tolerance is per-entry (spec plugin「兼容 Claude Code 生态的市场清单与插件」场景 4):
+ * an unrecognized shape yields `undefined` so only that entry fails, never the
+ * whole marketplace listing.
+ */
+const GIT_URL_PREFIXES = ["http://", "https://", "git@", "ssh://"];
+export function isGitUrl(value) {
+    return GIT_URL_PREFIXES.some((prefix) => value.startsWith(prefix));
+}
+export function parsePluginSource(source) {
+    if (typeof source === "string") {
+        return parseStringSource(source);
+    }
+    if (source && typeof source === "object") {
+        return parseObjectSource(source);
+    }
+    return undefined;
+}
+function parseStringSource(source) {
+    const trimmed = source.trim();
+    if (!trimmed)
+        return undefined;
+    if (!isGitUrl(trimmed)) {
+        return { kind: "local", path: trimmed };
+    }
+    const hashIndex = trimmed.indexOf("#");
+    if (hashIndex === -1) {
+        return { kind: "git", url: trimmed };
+    }
+    const url = trimmed.slice(0, hashIndex);
+    const ref = trimmed.slice(hashIndex + 1);
+    return { kind: "git", url, ref: ref || undefined };
+}
+function parseObjectSource(source) {
+    const declaration = source.source;
+    if (declaration !== "url" && declaration !== "git-subdir") {
+        return undefined;
+    }
+    const url = typeof source.url === "string" ? source.url.trim() : "";
+    if (!url)
+        return undefined;
+    const ref = typeof source.ref === "string" && source.ref ? source.ref : undefined;
+    const sha = typeof source.sha === "string" && source.sha ? source.sha : undefined;
+    if (declaration === "url") {
+        return { kind: "git", url, ref, sha };
+    }
+    const subdir = typeof source.path === "string" ? source.path.trim() : "";
+    if (!subdir)
+        return undefined;
+    return { kind: "git", url, ref, sha, subdir };
+}
+/**
+ * Renders an unrecognized `source` for error messages so install failures name
+ * the offending shape instead of hiding it (spec plugin A-021).
+ */
+export function describePluginSource(source) {
+    if (typeof source === "string")
+        return JSON.stringify(source);
+    if (source && typeof source === "object") {
+        const json = JSON.stringify(source);
+        return json.length > 200 ? `${json.slice(0, 200)}…` : json;
+    }
+    return String(source);
+}

package/dist/utils/ripgrep.d.ts

@@ -1,6 +1,20 @@
 /**
- * Path to the ripgrep binary, provided by the @vscode/ripgrep dependency.
- * The wrapper resolves the platform-specific binary package at import time
- * via optionalDependencies + os/cpu filtering.
+ * Resolve the rg binary path through [requireFn], or `undefined` when it is not
+ * installed. `requireFn` is injectable so the installer can verify an install
+ * from the directory the CLI will actually load it from, and so tests can
+ * exercise both outcomes without the real package.
  */
-export { rgPath } from "@vscode/ripgrep";
+export declare function resolveRipgrep(requireFn: NodeRequire): string | undefined;
+/**
+ * Path to the ripgrep binary, or `undefined` when grep is unavailable (the Grep
+ * tool reports it, file search throws its own error). Memoised once resolved —
+ * callers on a hot path pay a string check after that.
+ */
+export declare function getRgPath(): string | undefined;
+/**
+ * Forget the memoised path so the next {@link getRgPath} resolves again. Called
+ * by the runtime-dependency installer once rg is on disk — without it a process
+ * that asked for rg *before* the download finished would report grep as missing
+ * for its whole lifetime. Also used by tests.
+ */
+export declare function resetRipgrep(): void;

package/dist/utils/ripgrep.js

@@ -1,6 +1,58 @@
+import { createRequire } from "node:module";
 /**
- * Path to the ripgrep binary, provided by the @vscode/ripgrep dependency.
- * The wrapper resolves the platform-specific binary package at import time
- * via optionalDependencies + os/cpu filtering.
+ * Lazy access to the optional `@vscode/ripgrep` search dependency.
+ *
+ * ## Why a runtime require, and why not at module-evaluation time
+ *
+ * The wrapper resolves the platform-specific binary package
+ * (`@vscode/ripgrep-<platform>-<arch>`) while its module body evaluates and
+ * throws when that package is absent. A top-level import would therefore take
+ * down any host that loads the SDK barrel without the platform package — the
+ * desktop main process and the IDE extension hosts ship no such package and run
+ * grep in the CLI child process instead.
+ *
+ * Resolution is also *re-attempted* rather than frozen at module-evaluation
+ * time: the CLI installs this dependency itself, after its own module graph has
+ * been evaluated (see `utils/runtimeDeps.ts`), so an eager value would pin "grep
+ * is missing" for the whole first process. The installer calls
+ * {@link resetRipgrep} once the binary is on disk.
  */
-export { rgPath } from "@vscode/ripgrep";
+let cached;
+let resolutionAttempted = false;
+/**
+ * Resolve the rg binary path through [requireFn], or `undefined` when it is not
+ * installed. `requireFn` is injectable so the installer can verify an install
+ * from the directory the CLI will actually load it from, and so tests can
+ * exercise both outcomes without the real package.
+ */
+export function resolveRipgrep(requireFn) {
+    try {
+        const loaded = requireFn("@vscode/ripgrep");
+        return typeof loaded?.rgPath === "string" ? loaded.rgPath : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Path to the ripgrep binary, or `undefined` when grep is unavailable (the Grep
+ * tool reports it, file search throws its own error). Memoised once resolved —
+ * callers on a hot path pay a string check after that.
+ */
+export function getRgPath() {
+    if (!resolutionAttempted) {
+        resolutionAttempted = true;
+        cached = resolveRipgrep(createRequire(import.meta.url));
+    }
+    return cached;
+}
+/**
+ * Forget the memoised path so the next {@link getRgPath} resolves again. Called
+ * by the runtime-dependency installer once rg is on disk — without it a process
+ * that asked for rg *before* the download finished would report grep as missing
+ * for its whole lifetime. Also used by tests.
+ */
+export function resetRipgrep() {
+    cached = undefined;
+    resolutionAttempted = false;
+}

package/dist/utils/runtimeDeps.d.ts

@@ -0,0 +1,35 @@
+/** npm registry mirror for China users (same choice as the ripgrep download). */
+export declare const RUNTIME_DEPS_REGISTRY = "https://registry.npmmirror.com";
+export interface RuntimeDepsResult {
+    available: boolean;
+    reason?: string;
+}
+/**
+ * Whether this code runs from a CLI copy under the shared cli home.
+ *
+ * An npm-installed CLI (bundle under `<prefix>/lib/node_modules/wave-code/...`)
+ * must not self-install: Node would never look in `~/.wave/cli/node_modules`
+ * from there, and writing into a global npm prefix may lack permissions and
+ * gets pruned by the next `npm install`. Such a setup either already has the
+ * dependencies (the normal case) or degrades with an actionable warning.
+ */
+export declare function isManagedCliInstall(moduleUrl: string, cliHome?: string): boolean;
+/** sha512/base64 check against the registry's `dist.integrity`. */
+export declare function verifyIntegrity(buffer: Buffer, integrity: string): void;
+/**
+ * Make sure the runtime dependencies are installed. Never throws: the long-lived
+ * CLI entry points await it before serving, so a first pasted image (or a first
+ * search) cannot race a download — the same reason the hosts used to block on
+ * ripgrep before spawning the CLI. A failed install is reported once and only
+ * degrades images and grep.
+ *
+ * The outcome is memoised for the process lifetime, failures included — one
+ * attempt per launch, so a broken network does not retry on every image.
+ */
+export declare function ensureRuntimeDeps(options?: {
+    moduleUrl?: string;
+    fetchImpl?: typeof fetch;
+    cliHome?: string;
+}): Promise<RuntimeDepsResult>;
+/** Forget the memoised outcome, and the settled result (tests). */
+export declare function __resetRuntimeDepsForTesting(): void;