@ericsanchezok/synergy-util 3.0.23 → 3.1.0

package/dist/json-value.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+const json = z.json();
+// hono-openapi 1.1.2 loses nested recursive $defs. JSON payloads need no recursive
+// OpenAPI restriction, but persistence still validates every nested value.
+export const JsonValue = z.unknown().refine((value) => {
+    try {
+        return json.safeParse(value).success;
+    }
+    catch {
+        return false;
+    }
+}, "Expected a JSON value");

package/dist/markdown-assets.d.ts

@@ -0,0 +1,6 @@
+export declare const MARKDOWN_ASSET_REFERENCE_CHARS = 262144;
+export declare function markdownAssetReferences(text: string): string[];
+export declare function attachmentSuppression(outputs: readonly {
+    id: string;
+    references?: readonly string[];
+}[], inline: readonly string[]): Record<string, string[]>;

package/dist/markdown-assets.js

@@ -0,0 +1,29 @@
+import { Marked } from "marked";
+import { ResourceReference } from "./resource-reference";
+const markdown = new Marked();
+export const MARKDOWN_ASSET_REFERENCE_CHARS = 262144;
+export function markdownAssetReferences(text) {
+    const source = text.slice(0, MARKDOWN_ASSET_REFERENCE_CHARS);
+    if (!source.includes("asset://"))
+        return [];
+    const references = new Set();
+    markdown.walkTokens(markdown.lexer(source), (token) => {
+        if (references.size >= 32 || (token.type !== "image" && token.type !== "link"))
+            return;
+        if (token.href.length > 256)
+            return;
+        const reference = ResourceReference.parse(token.href);
+        if (reference.kind === "asset")
+            references.add(reference.url);
+    });
+    return [...references];
+}
+export function attachmentSuppression(outputs, inline) {
+    const seen = new Set(inline);
+    return Object.fromEntries(outputs.map((output) => {
+        const hidden = [...new Set(output.references?.filter((reference) => seen.has(reference)))];
+        for (const reference of output.references ?? [])
+            seen.add(reference);
+        return [output.id, hidden];
+    }));
+}

package/dist/markdown-link.d.ts

@@ -0,0 +1,2 @@
+export declare function bareUrlEnd(value: string): number;
+export declare function isBareUrlBoundary(value: string): boolean;

package/dist/markdown-link.js

@@ -0,0 +1,8 @@
+const punctuation = /[\u3001\u3002\uff0c\uff1b\uff01\uff1f\uff1a\u201c\u201d\u2018\u2019\u300c\u300d\u300e\u300f\u300a\u300b\u3010\u3011\uff08\uff09]/;
+export function bareUrlEnd(value) {
+    const boundary = value.search(punctuation);
+    return boundary < 0 ? value.length : boundary;
+}
+export function isBareUrlBoundary(value) {
+    return punctuation.test(value);
+}

package/dist/native-assets.d.ts

@@ -0,0 +1,7 @@
+export declare function nativeLibc(): "glibc" | "musl";
+export declare function nativePackageName(options?: {
+    platform?: string;
+    arch?: string;
+    libc?: string;
+}): string;
+export declare function nativeAsset(filename: string, owner: string | URL): string | undefined;

package/dist/native-assets.js

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+export function nativeLibc() {
+    if (process.platform !== "linux")
+        return "glibc";
+    if (typeof SYNERGY_LIBC === "string")
+        return SYNERGY_LIBC === "musl" ? "musl" : "glibc";
+    return readFileSync("/proc/self/maps", "utf8").includes("ld-musl-") ? "musl" : "glibc";
+}
+export function nativePackageName(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const abi = platform === "linux" ? `-${options.libc ?? nativeLibc()}` : "";
+    return `@ericsanchezok/synergy-native-${platform}-${arch}${abi}`;
+}
+export function nativeAsset(filename, owner) {
+    if (!/^[a-zA-Z0-9_.-]+$/.test(filename) || filename === "." || filename === "..")
+        throw new Error("Native asset must be a package-local filename");
+    try {
+        const resolved = createRequire(owner).resolve(`${nativePackageName()}/${filename}`);
+        return existsSync(resolved) ? resolved : undefined;
+    }
+    catch (error) {
+        if (error.code === "MODULE_NOT_FOUND")
+            return undefined;
+        throw error;
+    }
+}

package/dist/network-error.d.ts

@@ -0,0 +1,7 @@
+export declare function classifyNetworkError(error: unknown): {
+    kind: "transient" | "permanent" | "aborted" | "indeterminate";
+    code?: string;
+    syscall?: string;
+    category?: string;
+} | undefined;
+export declare function isRetryableHttpStatus(status: number): boolean;

package/dist/network-error.js

@@ -0,0 +1,111 @@
+// Provenance: https://nodejs.org/docs/latest-v22.x/api/errors.html#common-system-errors
+// https://github.com/nodejs/undici/blob/v6.21.3/docs/docs/api/Errors.md
+// https://nodejs.org/docs/latest-v22.x/api/dns.html#dnslookuphostname-options-callback
+// Local adaptation: classify bounded error graphs across runtimes; callers own replay safety and retry budgets.
+const TRANSIENT_CODES = new Set([
+    "CONNECTIONREFUSED",
+    "CONNECTIONCLOSED",
+    "FAILEDTOOPENSOCKET",
+    "ETIMEOUT",
+    "ETIMEDOUT",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "ESERVFAIL",
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ECONNABORTED",
+    "EPIPE",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "ENETDOWN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+const PERMANENT_CODES = new Set([
+    "ENONAME",
+    "EAI_NONAME",
+    "ENODATA",
+    "EBADNAME",
+    "ERR_INVALID_URL",
+    "ERR_CAUSE_TRUNCATED",
+    "CERT_HAS_EXPIRED",
+    "CERT_NOT_YET_VALID",
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "UNABLE_TO_GET_ISSUER_CERT",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "UND_ERR_INVALID_ARG",
+    "UND_ERR_REQ_CONTENT_LENGTH_MISMATCH",
+    "UND_ERR_RES_EXCEEDED_MAX_SIZE",
+]);
+const ABORT_CODES = new Set(["ABORT_ERR", "UND_ERR_ABORT", "UND_ERR_ABORTED", "ECANCELLED"]);
+// Provenance: https://www.rfc-editor.org/rfc/rfc5280
+// Local adaptation: certificate wording without a reason code is reported as a distinct indeterminate
+// kind so callers can apply a narrower retry budget than a proven transient failure.
+const CERTIFICATE_MESSAGE = /\bcertificate\b/i;
+const VERIFICATION_MESSAGE = /\bverif/i;
+export function classifyNetworkError(error) {
+    const seen = new Set();
+    let remaining = 32;
+    function visit(value, depth) {
+        if (depth > 8 || --remaining < 0)
+            return { kind: "permanent" };
+        if (!value || (typeof value !== "object" && typeof value !== "string"))
+            return undefined;
+        if (typeof value === "object") {
+            if (seen.has(value))
+                return undefined;
+            seen.add(value);
+        }
+        const record = typeof value === "object" ? value : undefined;
+        const message = typeof value === "string" ? value : typeof record?.message === "string" ? record.message : "";
+        const code = typeof record?.code === "string" ? record.code : undefined;
+        const token = code?.toUpperCase() ?? message.match(/\b(?:E[A-Z_]+|UND_ERR_[A-Z_]+)\b/)?.[0] ?? message.trim().toUpperCase();
+        const syscall = typeof record?.syscall === "string" ? record.syscall : undefined;
+        const name = record?.name;
+        let result;
+        if (name === "AbortError" || (token && ABORT_CODES.has(token)))
+            result = { kind: "aborted", code, syscall };
+        else if ((token && (PERMANENT_CODES.has(token) || /^(ERR_TLS_|ERR_SSL_)/.test(token))) ||
+            /certificate (?:has expired|verify failed|verification failed)|self[- ]signed certificate|unable to verify (?:the )?first certificate/i.test(message)) {
+            result = { kind: "permanent", code, syscall };
+        }
+        else if (!code && CERTIFICATE_MESSAGE.test(message) && VERIFICATION_MESSAGE.test(message)) {
+            result = { kind: "indeterminate", code, syscall, category: "tls-verification" };
+        }
+        else if (token && TRANSIENT_CODES.has(token))
+            result = { kind: "transient", code: code ?? token, syscall };
+        else if (name === "TimeoutError" ||
+            /^(?:(?:TypeError|Error): )?(?:fetch failed(?:: failed to fetch)?|failed to fetch|load failed|network error|connection error|(?:the )?network request failed|(?:the )?network connection was lost|socket hang up|NetworkError when attempting to fetch resource|The Internet connection appears to be offline)\.?$/i.test(message) ||
+            /^The socket connection was closed unexpectedly\./i.test(message) ||
+            /unable to connect\. is the computer able to access the url\?/i.test(message)) {
+            result = { kind: "transient", code, syscall };
+        }
+        const children = [record?.cause, ...(Array.isArray(record?.errors) ? record.errors.slice(0, 33) : [])];
+        for (const child of children) {
+            if (child === undefined)
+                continue;
+            const nested = visit(child, depth + 1);
+            if (!nested)
+                continue;
+            if (nested.kind === "aborted")
+                return nested;
+            if (result?.kind === "aborted")
+                return result;
+            if (nested.kind === "permanent" ||
+                !result ||
+                (result.kind === "transient" && (nested.code || nested.kind === "indeterminate")))
+                result = nested;
+        }
+        return result;
+    }
+    return visit(error, 0);
+}
+// Provenance: https://www.rfc-editor.org/rfc/rfc9110.html#section-15
+// Local adaptation: transient HTTP reads exclude unsupported server capabilities; provider-specific conflicts stay with the SDK.
+export function isRetryableHttpStatus(status) {
+    return status === 408 || status === 429 || (status >= 500 && status <= 599 && status !== 501 && status !== 505);
+}

package/dist/plugin-policy.d.ts

@@ -37,7 +37,7 @@ export interface PolicyCheckResult {
 }
 export declare function resolveRuntimeMode(input: ResolveRuntimeModeInput): RuntimeMode;
 export declare function resolveRuntimeLimits(...overrides: Array<RuntimeLimitOverrides | undefined>): RuntimeLimits;
-export declare function isTrustedPluginSource(source: PluginSource): source is "local" | "official" | "builtin";
+export declare function isTrustedPluginSource(source: PluginSource): source is "builtin" | "local" | "official";
 export declare function decideTrust(input: {
     source: PluginSource;
     userTrusted: boolean;

package/dist/process-group.d.ts

@@ -0,0 +1,45 @@
+interface ProcessHandle {
+    readonly pid?: number;
+    stop?(): Promise<void>;
+    kill(signal?: NodeJS.Signals | number): boolean;
+}
+export declare namespace ProcessGroup {
+    interface TaskkillProcess {
+        once(event: "exit", listener: (code: number | null) => void): this;
+        once(event: "error", listener: () => void): this;
+        kill(): boolean;
+    }
+    export interface KillTreeRuntimeForTest {
+        platform: NodeJS.Platform;
+        taskkill(pid: number): TaskkillProcess;
+        isPidAlive(pid: number): boolean;
+        signalProcessGroup?(pid: number, signal: NodeJS.Signals | number): void;
+        taskkillTimeoutMs: number;
+    }
+    export type ProcessInvocation = {
+        command: string;
+        args: string[];
+    };
+    /**
+     * Wrap an invocation so it leads its own process group and keeps that group
+     * alive briefly after exit, without inserting a process between the caller
+     * and `invocation.command`.
+     *
+     * `exec` is load-bearing: callers correlate kernel-side facts with
+     * `child.pid` — the macOS sandbox audit record that names a denied path and
+     * access is attributed to the exec'd image — and an intermediate shell would
+     * be a different pid, silently detaching that evidence from the child. The
+     * ownership anchor therefore cannot be a fixed `sleep` started up front; it
+     * polls the pid it shares with the exec'd image and anchors the group only
+     * once that image has exited.
+     */
+    export function prepareOwnedProcessGroup(invocation: ProcessInvocation, platform?: NodeJS.Platform): ProcessInvocation;
+    export function releaseOwnedProcessGroup(proc: ProcessHandle): void;
+    export function killTree(proc: ProcessHandle, opts?: {
+        exited?: () => boolean;
+        allowExitedParent?: boolean;
+        runtime?: KillTreeRuntimeForTest;
+    }): Promise<void>;
+    export {};
+}
+export {};

package/dist/process-group.js

@@ -0,0 +1,156 @@
+import { spawn } from "node:child_process";
+import { setTimeout as sleep } from "node:timers/promises";
+const SIGKILL_TIMEOUT_MS = 200;
+const TASKKILL_TIMEOUT_MS = 2_000;
+export var ProcessGroup;
+(function (ProcessGroup) {
+    /**
+     * Wrap an invocation so it leads its own process group and keeps that group
+     * alive briefly after exit, without inserting a process between the caller
+     * and `invocation.command`.
+     *
+     * `exec` is load-bearing: callers correlate kernel-side facts with
+     * `child.pid` — the macOS sandbox audit record that names a denied path and
+     * access is attributed to the exec'd image — and an intermediate shell would
+     * be a different pid, silently detaching that evidence from the child. The
+     * ownership anchor therefore cannot be a fixed `sleep` started up front; it
+     * polls the pid it shares with the exec'd image and anchors the group only
+     * once that image has exited.
+     */
+    function prepareOwnedProcessGroup(invocation, platform = process.platform) {
+        if (platform === "win32")
+            return invocation;
+        return {
+            command: "/bin/sh",
+            args: [
+                "-c",
+                '(while kill -0 $$ 2>/dev/null; do sleep 0.2; done; sleep 5) </dev/null >/dev/null 2>&1 & exec "$0" "$@"',
+                invocation.command,
+                ...invocation.args,
+            ],
+        };
+    }
+    ProcessGroup.prepareOwnedProcessGroup = prepareOwnedProcessGroup;
+    function releaseOwnedProcessGroup(proc) {
+        if (process.platform === "win32" || !proc.pid)
+            return;
+        try {
+            process.kill(-proc.pid, "SIGTERM");
+        }
+        catch { }
+    }
+    ProcessGroup.releaseOwnedProcessGroup = releaseOwnedProcessGroup;
+    async function killTree(proc, opts) {
+        try {
+            if (proc.stop)
+                await proc.stop();
+            else
+                await killTreeOnce(proc, opts);
+        }
+        catch { }
+    }
+    ProcessGroup.killTree = killTree;
+    async function killTreeOnce(proc, opts) {
+        const pid = proc.pid;
+        if (!pid || (!opts?.allowExitedParent && didExit(opts?.exited)))
+            return;
+        const runtime = opts?.runtime ?? killTreeRuntime;
+        if (runtime.platform === "win32") {
+            if (didExit(opts?.exited))
+                return;
+            const succeeded = await runTaskkill(runtime, pid);
+            if (didExit(opts?.exited) || (succeeded && !isPidAlive(runtime, pid)))
+                return;
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch { }
+            return;
+        }
+        const signalProcessGroup = runtime.signalProcessGroup ?? ((target, signal) => process.kill(-target, signal));
+        try {
+            signalProcessGroup(pid, "SIGTERM");
+        }
+        catch (_e) {
+            if (didExit(opts?.exited))
+                return;
+            try {
+                proc.kill("SIGTERM");
+            }
+            catch { }
+            await sleep(SIGKILL_TIMEOUT_MS);
+            if (!didExit(opts?.exited)) {
+                try {
+                    proc.kill("SIGKILL");
+                }
+                catch { }
+            }
+            return;
+        }
+        await sleep(SIGKILL_TIMEOUT_MS);
+        try {
+            signalProcessGroup(pid, 0);
+            signalProcessGroup(pid, "SIGKILL");
+        }
+        catch { }
+    }
+    function didExit(exited) {
+        try {
+            return exited?.() ?? false;
+        }
+        catch {
+            return false;
+        }
+    }
+    function isPidAlive(runtime, pid) {
+        try {
+            return runtime.isPidAlive(pid);
+        }
+        catch {
+            return true;
+        }
+    }
+    const killTreeRuntime = {
+        platform: process.platform,
+        taskkill: (pid) => spawn("taskkill", ["/pid", String(pid), "/f", "/t"], { stdio: "ignore" }),
+        isPidAlive: (pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (error) {
+                return error.code === "EPERM";
+            }
+        },
+        taskkillTimeoutMs: TASKKILL_TIMEOUT_MS,
+    };
+    function runTaskkill(runtime, pid) {
+        return new Promise((resolve) => {
+            let killer;
+            try {
+                killer = runtime.taskkill(pid);
+            }
+            catch {
+                resolve(false);
+                return;
+            }
+            let settled = false;
+            const finish = (succeeded) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(succeeded);
+            };
+            const timer = setTimeout(() => {
+                try {
+                    killer.kill();
+                }
+                catch { }
+                finish(false);
+            }, runtime.taskkillTimeoutMs);
+            killer.once("exit", (code) => finish(code === 0));
+            killer.once("error", () => finish(false));
+        });
+    }
+})(ProcessGroup || (ProcessGroup = {}));

package/dist/process-identity.js

@@ -20,8 +20,11 @@ export async function processStartIdentity(pid) {
     if (pid === process.pid) {
         // Cache the promise, not the value: concurrent first acquisitions must
         // share a single query instead of spawning one subprocess each.
-        ownIdentityPromise ??= queryProcessStartIdentity(pid);
-        return ownIdentityPromise;
+        const pending = (ownIdentityPromise ??= queryProcessStartIdentity(pid));
+        const identity = await pending;
+        if (identity === undefined && ownIdentityPromise === pending)
+            ownIdentityPromise = undefined;
+        return identity;
     }
     return queryProcessStartIdentity(pid);
 }

package/dist/projection-patch.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export declare const ProjectionPatch: z.ZodObject<{
+    path: z.ZodArray<z.ZodString>;
+    value: z.ZodOptional<z.ZodType<z.JSONType, unknown, z.core.$ZodTypeInternals<z.JSONType, unknown>>>;
+    remove: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>;
+export type ProjectionPatch = z.infer<typeof ProjectionPatch>;
+export declare function projectionPatch(previous: unknown, next: unknown): ProjectionPatch[];
+export declare function applyProjectionPatch(previous: unknown, changes: ProjectionPatch[]): unknown;

package/dist/projection-patch.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { JsonValue } from "./json-value";
+export const ProjectionPatch = z.object({
+    path: z.array(z.string()).max(64),
+    value: JsonValue.optional(),
+    remove: z.literal(true).optional(),
+});
+const object = (value) => value !== null && typeof value === "object";
+const safe = (key) => !["__proto__", "prototype", "constructor"].includes(key);
+export function projectionPatch(previous, next) {
+    const changes = [];
+    const visit = (before, after, path) => {
+        if (before === after)
+            return;
+        if (!object(before) || !object(after) || Array.isArray(before) !== Array.isArray(after)) {
+            changes.push(after === undefined ? { path, remove: true } : { path, value: after });
+            return;
+        }
+        for (const key of Object.keys(after)) {
+            if (!safe(key))
+                throw new Error("Invalid projection key");
+            visit(before[key], after[key], [...path, key]);
+        }
+        if (Array.isArray(after)) {
+            if (before.length !== after.length)
+                changes.push({ path: [...path, "length"], value: after.length });
+            return;
+        }
+        for (const key of Object.keys(before))
+            if (!(key in after))
+                changes.push({ path: [...path, key], remove: true });
+    };
+    visit(previous, next, []);
+    return changes;
+}
+export function applyProjectionPatch(previous, changes) {
+    let value = previous;
+    const copies = new WeakMap();
+    const copy = (input) => {
+        if (!object(input))
+            throw new Error("Invalid projection parent");
+        let result = copies.get(input);
+        if (result)
+            return result;
+        result = (Array.isArray(input) ? [...input] : { ...input });
+        copies.set(input, result);
+        copies.set(result, result);
+        return result;
+    };
+    for (const change of changes) {
+        if (!change.path.every(safe))
+            throw new Error("Invalid projection path");
+        if (!change.path.length) {
+            value = change.remove ? undefined : structuredClone(change.value);
+            continue;
+        }
+        value = copy(value);
+        let parent = value;
+        for (const key of change.path.slice(0, -1)) {
+            if (!object(parent) || !Object.hasOwn(parent, key))
+                throw new Error("Missing projection parent");
+            parent[key] = copy(parent[key]);
+            parent = parent[key];
+        }
+        if (!object(parent))
+            throw new Error("Invalid projection parent");
+        const key = change.path.at(-1);
+        if (change.remove)
+            delete parent[key];
+        else
+            parent[key] = structuredClone(change.value);
+    }
+    return value;
+}

package/dist/reasoning-item.d.ts

@@ -0,0 +1 @@
+export declare function reasoningItemKey(metadata: unknown): string | undefined;

package/dist/reasoning-item.js

@@ -0,0 +1,16 @@
+export function reasoningItemKey(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+        return;
+    let identity;
+    for (const [provider, value] of Object.entries(metadata)) {
+        if (!value || typeof value !== "object" || Array.isArray(value) || !("itemId" in value))
+            continue;
+        const itemID = value.itemId;
+        if (typeof itemID !== "string" || !itemID.trim() || itemID.length > 1024 || provider.length > 128)
+            continue;
+        if (identity)
+            return;
+        identity = JSON.stringify([provider, itemID]);
+    }
+    return identity;
+}