@scotthuang/agent-knock-knock 0.13.2 → 0.13.4

package/dist/src/semantic-tool-relay.d.ts

@@ -0,0 +1,16 @@
+export interface SemanticToolRelayOptions {
+    readonly cwd?: string;
+    readonly allowNonzeroJson?: boolean;
+    readonly timeoutMs?: number;
+}
+export declare const defaultSemanticToolRelayPath: string;
+export declare function bindSemanticToolRelayPath(owner: object, relayPath: string): void;
+/** Bind a private child-process environment for one exact Host owner. */
+export declare function bindSemanticToolRelayEnvironment(owner: object, environment: NodeJS.ProcessEnv): void;
+/** Keep an embedding Host's event loop responsive while AKK CLI work runs. */
+export declare function bindSemanticToolAsyncRelay(owner: object): void;
+/** Scope one Host invocation's cancellation without sharing mutable state. */
+export declare function withHostBridgeInvocationSignal<T>(signal: AbortSignal | undefined, operation: () => Promise<T>): Promise<T>;
+export declare function runCli(owner: object, cliArgs: readonly string[], { cwd, allowNonzeroJson }?: SemanticToolRelayOptions): Record<string, unknown>;
+export declare function runCliAsync(owner: object, cliArgs: readonly string[], { cwd, allowNonzeroJson, timeoutMs }?: SemanticToolRelayOptions): Promise<Record<string, unknown>>;
+export declare function runHostAwareCli(owner: object, cliArgs: readonly string[], options?: SemanticToolRelayOptions): Promise<Record<string, unknown>>;

package/dist/src/semantic-tool-relay.js

@@ -0,0 +1,175 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+export const defaultSemanticToolRelayPath = fileURLToPath(new URL("./cli.js", import.meta.url));
+const relayPathByOwner = new WeakMap();
+const relayEnvironmentByOwner = new WeakMap();
+const asyncRelayOwners = new WeakSet();
+const invocationStorage = new AsyncLocalStorage();
+export function bindSemanticToolRelayPath(owner, relayPath) {
+    relayPathByOwner.set(owner, relayPath);
+}
+/** Bind a private child-process environment for one exact Host owner. */
+export function bindSemanticToolRelayEnvironment(owner, environment) {
+    relayEnvironmentByOwner.set(owner, Object.freeze({ ...environment }));
+}
+/** Keep an embedding Host's event loop responsive while AKK CLI work runs. */
+export function bindSemanticToolAsyncRelay(owner) {
+    asyncRelayOwners.add(owner);
+}
+/** Scope one Host invocation's cancellation without sharing mutable state. */
+export function withHostBridgeInvocationSignal(signal, operation) {
+    const effectiveSignal = signal ?? invocationStorage.getStore()?.signal;
+    if (effectiveSignal?.aborted) {
+        return Promise.reject(hostBridgeAbortError());
+    }
+    return invocationStorage.run({ signal: effectiveSignal }, async () => operation());
+}
+export function runCli(owner, cliArgs, { cwd = process.cwd(), allowNonzeroJson = false } = {}) {
+    const binPath = relayPathForOwner(owner);
+    const spawned = spawnSync(process.execPath, [binPath, ...cliArgs], {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 10,
+        cwd,
+        env: relayEnvironmentForOwner(owner)
+    });
+    if (spawned.error) {
+        throw new Error(`agent-knock-knock ${cliArgs[0]} failed to start: ${spawned.error.message}`);
+    }
+    if (spawned.status !== 0) {
+        if (allowNonzeroJson && spawned.stdout.trim()) {
+            return parseJson(spawned.stdout);
+        }
+        throw new Error(cleanError(spawned.stderr ||
+            spawned.stdout ||
+            `agent-knock-knock ${cliArgs[0]} exited with status ${spawned.status}`));
+    }
+    return parseJson(spawned.stdout);
+}
+export function runCliAsync(owner, cliArgs, { cwd = process.cwd(), allowNonzeroJson = false, timeoutMs = 90_000 } = {}) {
+    const binPath = relayPathForOwner(owner);
+    const maxBuffer = 10 * 1024 * 1024;
+    const signal = invocationStorage.getStore()?.signal;
+    if (signal?.aborted) {
+        return Promise.reject(hostBridgeAbortError());
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [binPath, ...cliArgs], {
+            cwd,
+            env: relayEnvironmentForOwner(owner),
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true
+        });
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        let stdout = "";
+        let stderr = "";
+        let overflow = false;
+        let timedOut = false;
+        let aborted = false;
+        const onAbort = () => {
+            aborted = true;
+            child.kill("SIGKILL");
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const append = (current, chunk) => {
+            const next = current + chunk;
+            if (Buffer.byteLength(next, "utf8") > maxBuffer) {
+                overflow = true;
+                child.kill("SIGKILL");
+            }
+            return next;
+        };
+        child.stdout.on("data", (chunk) => {
+            stdout = append(stdout, chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr = append(stderr, chunk);
+        });
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, timeoutMs);
+        timeout.unref();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted) {
+            onAbort();
+        }
+        child.once("error", (error) => {
+            cleanup();
+            if (aborted) {
+                reject(hostBridgeAbortError());
+                return;
+            }
+            reject(new Error(`agent-knock-knock ${cliArgs[0]} failed to start: ${error.message}`));
+        });
+        child.once("close", (status) => {
+            cleanup();
+            if (aborted) {
+                reject(hostBridgeAbortError());
+                return;
+            }
+            if (timedOut) {
+                reject(new Error(`agent-knock-knock ${cliArgs[0]} timed out`));
+                return;
+            }
+            if (overflow) {
+                reject(new Error(`agent-knock-knock ${cliArgs[0]} output exceeded 10 MiB`));
+                return;
+            }
+            if (status !== 0) {
+                if (allowNonzeroJson && stdout.trim()) {
+                    try {
+                        resolve(parseJson(stdout));
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                    return;
+                }
+                reject(new Error(cleanError(stderr ||
+                    stdout ||
+                    `agent-knock-knock ${cliArgs[0]} exited with status ${status}`)));
+                return;
+            }
+            try {
+                resolve(parseJson(stdout));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+}
+export async function runHostAwareCli(owner, cliArgs, options = {}) {
+    if (asyncRelayOwners.has(owner)) {
+        return runCliAsync(owner, cliArgs, options);
+    }
+    return runCli(owner, cliArgs, options);
+}
+function hostBridgeAbortError() {
+    const error = new Error("agent-knock-knock Host invocation was aborted");
+    error.name = "AbortError";
+    return error;
+}
+function relayPathForOwner(owner) {
+    return relayPathByOwner.get(owner) ?? defaultSemanticToolRelayPath;
+}
+function relayEnvironmentForOwner(owner) {
+    return relayEnvironmentByOwner.get(owner) ?? process.env;
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`agent-knock-knock CLI returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function cleanError(text) {
+    return String(text).trim().slice(0, 2000);
+}
+//# sourceMappingURL=semantic-tool-relay.js.map

package/dist/src/semantic-tool-relay.js.map

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

package/dist/src/semantic-tool-runtime.d.ts

@@ -0,0 +1,10 @@
+import { type SemanticToolCatalog } from "./semantic-tool-catalog.js";
+export { bindSemanticToolAsyncRelay, bindSemanticToolRelayEnvironment, bindSemanticToolRelayPath, defaultSemanticToolRelayPath, runCli, runCliAsync, withHostBridgeInvocationSignal } from "./semantic-tool-relay.js";
+export { bindHostBridgeToolPresentation } from "./semantic-tool-presentation.js";
+export { pushOptional } from "./semantic-tool-arguments.js";
+export type DisplayedResumeSnapshotMap = Map<string, {
+    snapshotId: string;
+    expiresAtMs: number;
+}>;
+/** Build the one host-neutral AKK command/tool catalog for a runtime owner. */
+export declare function createAkkSemanticToolCatalog(api: object & Record<string, any>, displayedResumeSnapshots: DisplayedResumeSnapshotMap): SemanticToolCatalog;