@botbotgo/kit-builtin 0.0.92

package/dist/src/git/gitStatus.js

@@ -0,0 +1,55 @@
+import { DEFAULT_GIT_MAX_OUTPUT_BYTES, DEFAULT_GIT_TIMEOUT_MS, } from "./defaults.js";
+import { failOnNonZero, resolveCwd, resolveRepoPath, runProcess } from "./common.js";
+import { getExtensionContext } from "../../index.js";
+import { overrideWithConfig } from "../util/overrideWithConfig.js";
+/**
+ * Get git working tree status.
+ * @tool
+ * @effect none
+ */
+export async function gitStatus(args) {
+    const defaults = {
+        sandboxRoot: "",
+        gitTimeoutMs: DEFAULT_GIT_TIMEOUT_MS,
+        gitMaxOutputBytes: DEFAULT_GIT_MAX_OUTPUT_BYTES,
+    };
+    const ctx = getExtensionContext();
+    const cfg = overrideWithConfig(defaults, ctx.config);
+    const repoPath = await resolveRepoPath((args.path ?? args.repoPath ?? "").trim(), cfg.sandboxRoot ?? "");
+    const cmdArgs = ["--no-pager", "status"];
+    if (args.porcelain ?? true)
+        cmdArgs.push("--porcelain=v1");
+    if (args.branch ?? true)
+        cmdArgs.push("--branch");
+    const out = await runProcess({
+        bin: "git",
+        cmdArgs,
+        cwd: resolveCwd(repoPath),
+        timeoutMs: args.timeoutMs ?? cfg.gitTimeoutMs ?? DEFAULT_GIT_TIMEOUT_MS,
+        maxOutputBytes: cfg.gitMaxOutputBytes ?? DEFAULT_GIT_MAX_OUTPUT_BYTES,
+    });
+    failOnNonZero("status", out);
+    const lines = out.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0);
+    return {
+        result: {
+            path: repoPath,
+            porcelain: args.porcelain ?? true,
+            branch: args.branch ?? true,
+            lines,
+            stdout: out.stdout,
+            stderr: out.stderr,
+            exitCode: out.exitCode,
+        },
+        evidence: [
+            {
+                type: "git",
+                summary: `gitStatus: ${lines.length} line(s) in ${repoPath}`,
+                createdAt: new Date().toISOString(),
+            },
+        ],
+    };
+}
+//# sourceMappingURL=gitStatus.js.map

package/dist/src/git/gitStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitStatus.js","sourceRoot":"","sources":["../../../src/git/gitStatus.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAM/B;IACC,MAAM,QAAQ,GAAG;QACf,WAAW,EAAE,EAAE;QACf,YAAY,EAAE,sBAAsB;QACpC,iBAAiB,EAAE,4BAA4B;KAChD,CAAC;IACF,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;IAClC,MAAM,GAAG,GAAG,kBAAkB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAErD,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IACzG,MAAM,OAAO,GAAG,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IACzC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAC3D,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAElD,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC;QAC3B,GAAG,EAAE,KAAK;QACV,OAAO;QACP,GAAG,EAAE,UAAU,CAAC,QAAQ,CAAC;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC,YAAY,IAAI,sBAAsB;QACvE,cAAc,EAAE,GAAG,CAAC,iBAAiB,IAAI,4BAA4B;KACtE,CAAC,CAAC;IACH,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAE7B,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM;SACrB,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;SAC7B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAErC,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;YACjC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;YAC3B,KAAK;YACL,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;SACvB;QACD,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,KAAK;gBACX,OAAO,EAAE,cAAc,KAAK,CAAC,MAAM,eAAe,QAAQ,EAAE;gBAC5D,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/src/git/gitSwitchBranch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Switch git branch in a repository.
+ * @tool
+ * @effect local_write
+ */
+export declare function gitSwitchBranch(args: {
+    path: string;
+    repoPath?: string;
+    branch: string;
+    create?: boolean;
+    trackRemote?: boolean;
+    timeoutMs?: number;
+}): Promise<{
+    result: {
+        path: string;
+        branch: string;
+        created: boolean;
+        trackedRemote: boolean;
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    };
+    evidence: {
+        type: string;
+        summary: string;
+        createdAt: string;
+    }[];
+}>;
+//# sourceMappingURL=gitSwitchBranch.d.ts.map

package/dist/src/git/gitSwitchBranch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitSwitchBranch.d.ts","sourceRoot":"","sources":["../../../src/git/gitSwitchBranch.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;;;;;;;;;;;;;;;GAgDA"}

package/dist/src/git/gitSwitchBranch.js

@@ -0,0 +1,57 @@
+import { createTaggedError } from "@botbotgo/kit/sdk";
+import { DEFAULT_GIT_MAX_OUTPUT_BYTES, DEFAULT_GIT_TIMEOUT_MS, } from "./defaults.js";
+import { failOnNonZero, resolveCwd, resolveRepoPath, runProcess } from "./common.js";
+import { getExtensionContext } from "../../index.js";
+import { overrideWithConfig } from "../util/overrideWithConfig.js";
+/**
+ * Switch git branch in a repository.
+ * @tool
+ * @effect local_write
+ */
+export async function gitSwitchBranch(args) {
+    const defaults = {
+        sandboxRoot: "",
+        gitTimeoutMs: DEFAULT_GIT_TIMEOUT_MS,
+        gitMaxOutputBytes: DEFAULT_GIT_MAX_OUTPUT_BYTES,
+    };
+    const ctx = getExtensionContext();
+    const cfg = overrideWithConfig(defaults, ctx.config);
+    const repoPath = await resolveRepoPath((args.path ?? args.repoPath ?? "").trim(), cfg.sandboxRoot ?? "");
+    const branch = args.branch?.trim();
+    if (!branch) {
+        throw createTaggedError("GIT_INVALID", "branch is required", {});
+    }
+    const cmdArgs = ["switch"];
+    if (args.create)
+        cmdArgs.push("-c");
+    if (args.trackRemote)
+        cmdArgs.push("--track");
+    cmdArgs.push(branch);
+    const out = await runProcess({
+        bin: "git",
+        cmdArgs,
+        cwd: resolveCwd(repoPath),
+        timeoutMs: args.timeoutMs ?? cfg.gitTimeoutMs ?? DEFAULT_GIT_TIMEOUT_MS,
+        maxOutputBytes: cfg.gitMaxOutputBytes ?? DEFAULT_GIT_MAX_OUTPUT_BYTES,
+    });
+    failOnNonZero("switch", out);
+    return {
+        result: {
+            path: repoPath,
+            branch,
+            created: args.create ?? false,
+            trackedRemote: args.trackRemote ?? false,
+            stdout: out.stdout,
+            stderr: out.stderr,
+            exitCode: out.exitCode,
+        },
+        evidence: [
+            {
+                type: "git",
+                summary: `gitSwitchBranch: switched to ${branch} in ${repoPath}`,
+                createdAt: new Date().toISOString(),
+            },
+        ],
+    };
+}
+//# sourceMappingURL=gitSwitchBranch.js.map

package/dist/src/git/gitSwitchBranch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitSwitchBranch.js","sourceRoot":"","sources":["../../../src/git/gitSwitchBranch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAOrC;IACC,MAAM,QAAQ,GAAG;QACf,WAAW,EAAE,EAAE;QACf,YAAY,EAAE,sBAAsB;QACpC,iBAAiB,EAAE,4BAA4B;KAChD,CAAC;IACF,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC;IAClC,MAAM,GAAG,GAAG,kBAAkB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAErD,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IACzG,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,iBAAiB,CAAC,aAAa,EAAE,oBAAoB,EAAE,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3B,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAErB,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC;QAC3B,GAAG,EAAE,KAAK;QACV,OAAO;QACP,GAAG,EAAE,UAAU,CAAC,QAAQ,CAAC;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC,YAAY,IAAI,sBAAsB;QACvE,cAAc,EAAE,GAAG,CAAC,iBAAiB,IAAI,4BAA4B;KACtE,CAAC,CAAC;IAEH,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAE7B,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,MAAM;YACN,OAAO,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK;YAC7B,aAAa,EAAE,IAAI,CAAC,WAAW,IAAI,KAAK;YACxC,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;SACvB;QACD,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,KAAK;gBACX,OAAO,EAAE,gCAAgC,MAAM,OAAO,QAAQ,EAAE;gBAChE,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC;SACF;KACF,CAAC;AACJ,CAAC"}

package/dist/src/git/gitTools.d.ts

@@ -0,0 +1,11 @@
+export * from "./gitRead.js";
+export * from "./gitLogHistory.js";
+export * from "./gitSwitchBranch.js";
+export * from "./gitPull.js";
+export * from "./gitPrView.js";
+export * from "./gitStatus.js";
+export * from "./gitDiff.js";
+export * from "./gitAdd.js";
+export * from "./gitCommit.js";
+export * from "./ghRead.js";
+//# sourceMappingURL=gitTools.d.ts.map

package/dist/src/git/gitTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitTools.d.ts","sourceRoot":"","sources":["../../../src/git/gitTools.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/src/git/gitTools.js

@@ -0,0 +1,11 @@
+export * from "./gitRead.js";
+export * from "./gitLogHistory.js";
+export * from "./gitSwitchBranch.js";
+export * from "./gitPull.js";
+export * from "./gitPrView.js";
+export * from "./gitStatus.js";
+export * from "./gitDiff.js";
+export * from "./gitAdd.js";
+export * from "./gitCommit.js";
+export * from "./ghRead.js";
+//# sourceMappingURL=gitTools.js.map

package/dist/src/git/gitTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitTools.js","sourceRoot":"","sources":["../../../src/git/gitTools.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/src/http/defaults.d.ts

@@ -0,0 +1,10 @@
+/**
+ * HTTP tool defaults (timeout, max bytes, User-Agent, blocked CIDRs for SSRF).
+ * Config: these constants or user's tool config at invoke time.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+export declare const DEFAULT_MAX_HTTP_BYTES: number;
+export declare const DEFAULT_MAX_DOWNLOAD_BYTES: number;
+export declare const DEFAULT_HTTP_USER_AGENT = "agent-tool-core/1.0";
+export declare const DEFAULT_BLOCKED_CIDRS: string[];
+//# sourceMappingURL=defaults.d.ts.map

package/dist/src/http/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../../src/http/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,sBAAsB,QAAkB,CAAC;AACtD,eAAO,MAAM,0BAA0B,QAAoB,CAAC;AAC5D,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D,eAAO,MAAM,qBAAqB,UASjC,CAAC"}

package/dist/src/http/defaults.js

@@ -0,0 +1,19 @@
+/**
+ * HTTP tool defaults (timeout, max bytes, User-Agent, blocked CIDRs for SSRF).
+ * Config: these constants or user's tool config at invoke time.
+ */
+export const DEFAULT_TIMEOUT_MS = 15_000;
+export const DEFAULT_MAX_HTTP_BYTES = 5 * 1024 * 1024;
+export const DEFAULT_MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024;
+export const DEFAULT_HTTP_USER_AGENT = "agent-tool-core/1.0";
+export const DEFAULT_BLOCKED_CIDRS = [
+    "127.0.0.0/8",
+    "10.0.0.0/8",
+    "172.16.0.0/12",
+    "192.168.0.0/16",
+    "169.254.0.0/16",
+    "::1/128",
+    "fc00::/7",
+    "fe80::/10",
+];
+//# sourceMappingURL=defaults.js.map

package/dist/src/http/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../../src/http/defaults.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AACzC,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AACtD,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAC5D,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE7D,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,aAAa;IACb,YAAY;IACZ,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,SAAS;IACT,UAAU;IACV,WAAW;CACZ,CAAC"}

package/dist/src/http/downloadFile.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Download URL to local sandbox path with size and SSRF limits.
+ * @tool
+ * @effect local_write
+ */
+export declare function downloadFile(args: {
+    url?: string;
+    uri?: string;
+    destPath?: string;
+    destination?: string;
+    filePath?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    maxBytes?: number;
+    overwrite?: boolean;
+}): Promise<{
+    result: {
+        destPath: string;
+        bytes: number;
+        sha256: string;
+        status: number;
+        url: string;
+    };
+    evidence: {
+        type: string;
+        ref: string;
+        summary: string;
+        createdAt: string;
+    }[];
+}>;
+//# sourceMappingURL=downloadFile.d.ts.map

package/dist/src/http/downloadFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloadFile.d.ts","sourceRoot":"","sources":["../../../src/http/downloadFile.ts"],"names":[],"mappings":"AA8KA;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;;;;;;;;;;;;;;GAgDA"}

package/dist/src/http/downloadFile.js

@@ -0,0 +1,188 @@
+import { writeFile, mkdir, access } from "node:fs/promises";
+import { createChecksumAccumulator } from "@botbotgo/common/utils";
+import { dirname } from "node:path";
+import { getExtensionContext } from "../../index.js";
+import { DEFAULT_TIMEOUT_MS, DEFAULT_MAX_DOWNLOAD_BYTES, DEFAULT_HTTP_USER_AGENT, DEFAULT_BLOCKED_CIDRS, } from "./defaults.js";
+import { createTaggedError } from "@botbotgo/kit/sdk";
+import { resolveSandboxedPath, validateUrl } from "../platform/securityCompat.js";
+import { overrideWithConfig } from "../util/overrideWithConfig.js";
+function getConfig() {
+    const defaults = {
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        maxBytes: DEFAULT_MAX_DOWNLOAD_BYTES,
+        userAgent: DEFAULT_HTTP_USER_AGENT,
+        blockedCidrs: DEFAULT_BLOCKED_CIDRS,
+        allowedHosts: [],
+        blockedHosts: [],
+        sandboxRoot: "",
+        enableSandboxValidation: false,
+    };
+    const cfg = overrideWithConfig(defaults, getExtensionContext().config);
+    return {
+        timeoutMs: cfg.timeoutMs ?? defaults.timeoutMs,
+        maxBytes: cfg.maxBytes ?? defaults.maxBytes,
+        userAgent: cfg.userAgent ?? defaults.userAgent,
+        blockedCidrs: Array.isArray(cfg.blockedCidrs) ? cfg.blockedCidrs : defaults.blockedCidrs,
+        allowedHosts: Array.isArray(cfg.allowedHosts) ? cfg.allowedHosts : defaults.allowedHosts,
+        blockedHosts: Array.isArray(cfg.blockedHosts) ? cfg.blockedHosts : defaults.blockedHosts,
+        sandboxRoot: cfg.sandboxRoot ?? defaults.sandboxRoot,
+    };
+}
+function parseInput(args) {
+    const url = (args.url ?? args.uri)?.trim();
+    const destPath = (args.destPath ?? args.destination ?? args.filePath)?.trim();
+    if (!url)
+        throw createTaggedError("HTTP_INVALID", "url is required (pass 'url' or 'uri')", {});
+    if (!destPath) {
+        throw createTaggedError("HTTP_INVALID", "destPath is required (pass 'destPath', 'destination', or 'filePath')", {});
+    }
+    return {
+        url,
+        destPath,
+        headers: args.headers ?? {},
+        overwrite: args.overwrite ?? false,
+        timeoutMs: args.timeoutMs,
+        maxBytes: args.maxBytes,
+    };
+}
+async function resolveDestinationAndValidate(args) {
+    await validateUrl(args.url, {
+        allowedHosts: args.allowedHosts,
+        blockedHosts: args.blockedHosts,
+        blockedCidrs: args.blockedCidrs,
+    });
+    const resolvedDest = await resolveSandboxedPath(args.destPath, args.sandboxRoot);
+    if (!args.overwrite) {
+        try {
+            await access(resolvedDest);
+            throw new Error(`File already exists: ${resolvedDest}. Set overwrite=true to allow overwriting.`);
+        }
+        catch (err) {
+            if (err instanceof Error && !err.message.includes("already exists")) {
+                // ENOENT: proceed
+            }
+            else if (err instanceof Error) {
+                throw err;
+            }
+        }
+    }
+    return resolvedDest;
+}
+async function fetchDownloadResponse(args) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), args.timeoutMs);
+    try {
+        return await fetch(args.url, {
+            method: "GET",
+            headers: args.headers,
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw createTaggedError("HTTP_TIMEOUT", `Download from ${args.url} timed out after ${args.timeoutMs}ms`, {
+                url: args.url,
+                timeoutMs: args.timeoutMs,
+            });
+        }
+        throw createTaggedError("UPSTREAM_ERROR", `Download failed for ${args.url}: ${err instanceof Error ? err.message : String(err)}`, { url: args.url });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function validateContentLength(response, maxBytes, url) {
+    const contentLength = response.headers.get("content-length");
+    if (!contentLength)
+        return;
+    const parsed = parseInt(contentLength, 10);
+    if (parsed <= maxBytes)
+        return;
+    throw createTaggedError("HTTP_TOO_LARGE", `Download Content-Length ${contentLength} exceeds limit of ${maxBytes} bytes`, {
+        url,
+        contentLength: parsed,
+        limit: maxBytes,
+    });
+}
+async function readBodyWithLimit(response, maxBytes, url) {
+    if (!response.body)
+        throw createTaggedError("UPSTREAM_ERROR", `No response body from ${url}`, { url });
+    const reader = response.body.getReader();
+    const chunks = [];
+    let totalBytes = 0;
+    const hasher = createChecksumAccumulator();
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            totalBytes += value.byteLength;
+            if (totalBytes > maxBytes) {
+                reader.cancel();
+                throw createTaggedError("HTTP_TOO_LARGE", `Download from ${url} exceeded limit of ${maxBytes} bytes (received ${totalBytes})`, {
+                    url,
+                    bytesRead: totalBytes,
+                    limit: maxBytes,
+                });
+            }
+            chunks.push(value);
+            hasher.update(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return { buffer: Buffer.concat(chunks), bytes: totalBytes, sha256: hasher.digest() };
+}
+/**
+ * Download URL to local sandbox path with size and SSRF limits.
+ * @tool
+ * @effect local_write
+ */
+export async function downloadFile(args) {
+    const cfg = getConfig();
+    const input = parseInput(args);
+    const timeoutMs = input.timeoutMs ?? cfg.timeoutMs;
+    const maxBytes = input.maxBytes ?? cfg.maxBytes;
+    const headers = { ...input.headers };
+    if (!headers["User-Agent"] && !headers["user-agent"])
+        headers["User-Agent"] = cfg.userAgent;
+    const resolvedDest = await resolveDestinationAndValidate({
+        url: input.url,
+        destPath: input.destPath,
+        overwrite: input.overwrite,
+        sandboxRoot: cfg.sandboxRoot,
+        allowedHosts: cfg.allowedHosts,
+        blockedHosts: cfg.blockedHosts,
+        blockedCidrs: cfg.blockedCidrs,
+    });
+    const response = await fetchDownloadResponse({ url: input.url, headers, timeoutMs });
+    validateContentLength(response, maxBytes, input.url);
+    const payload = await readBodyWithLimit(response, maxBytes, input.url);
+    await mkdir(dirname(resolvedDest), { recursive: true });
+    await writeFile(resolvedDest, payload.buffer);
+    return {
+        result: {
+            destPath: resolvedDest,
+            bytes: payload.bytes,
+            sha256: payload.sha256,
+            status: response.status,
+            url: input.url,
+        },
+        evidence: [
+            {
+                type: "url",
+                ref: input.url,
+                summary: `Downloaded ${payload.bytes} bytes from ${input.url}`,
+                createdAt: new Date().toISOString(),
+            },
+            {
+                type: "file",
+                ref: resolvedDest,
+                summary: `Saved to ${resolvedDest} (sha256: ${payload.sha256.slice(0, 12)}...)`,
+                createdAt: new Date().toISOString(),
+            },
+        ],
+    };
+}
+//# sourceMappingURL=downloadFile.js.map

package/dist/src/http/downloadFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloadFile.js","sourceRoot":"","sources":["../../../src/http/downloadFile.ts"],"names":[],"mappings":"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"}

package/dist/src/http/duckduckgoSearch.d.ts

@@ -0,0 +1,31 @@
+export declare function duckduckgoSearch(args: {
+    query: string;
+    q?: string;
+    maxResults?: number;
+    timeoutMs?: number;
+    maxBytes?: number;
+}): Promise<{
+    result: {
+        query: string;
+        abstract: string | undefined;
+        abstractUrl: string | undefined;
+        abstractSource: string | undefined;
+        heading: string | undefined;
+        results: {
+            url: string;
+            title: string;
+            snippet?: string;
+        }[];
+        relatedTopics: {
+            text: string;
+            url?: string;
+        }[];
+    };
+    evidence: {
+        type: string;
+        ref: string;
+        summary: string;
+        createdAt: string;
+    }[];
+}>;
+//# sourceMappingURL=duckduckgoSearch.d.ts.map

package/dist/src/http/duckduckgoSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckduckgoSearch.d.ts","sourceRoot":"","sources":["../../../src/http/duckduckgoSearch.ts"],"names":[],"mappings":"AA6MA,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;;;;;;;;iBAlF6B,MAAM;mBAAS,MAAM;sBAAY,MAAM;;;kBAYhC,MAAM;kBAAQ,MAAM;;;;;;;;;GAyHxD"}