@scotthuang/agent-knock-knock-pi 0.1.0-poc.1

package/lib/ipc.js

@@ -0,0 +1,255 @@
+import { timingSafeEqual } from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import { CALLBACK_MAX_REQUEST_BYTES as CALLBACK_BODY_LIMIT_BYTES, CALLBACK_MAX_RESPONSE_BYTES, CALLBACK_SOCKET_ENV, CALLBACK_TIMEOUT_MS, CALLBACK_TOKEN_ENV, } from "./constants.js";
+export { CALLBACK_MAX_RESPONSE_BYTES, CALLBACK_SOCKET_ENV, CALLBACK_TIMEOUT_MS, CALLBACK_TOKEN_ENV, };
+export const CALLBACK_MAX_BODY_BYTES = CALLBACK_BODY_LIMIT_BYTES;
+export const CALLBACK_MAX_REQUEST_BYTES = CALLBACK_MAX_BODY_BYTES + 64 * 1024;
+/** Host an authenticated, one-frame-per-connection Pi callback transport. */
+export function createCallbackIpcServer(options) {
+    let state = "idle";
+    const sockets = new Set();
+    const server = net.createServer((socket) => {
+        sockets.add(socket);
+        socket.setTimeout(CALLBACK_TIMEOUT_MS, () => socket.destroy());
+        socket.once("close", () => sockets.delete(socket));
+        socket.once("error", () => undefined);
+        void handleConnection(socket, options);
+    });
+    return {
+        start() {
+            if (state === "running")
+                return Promise.resolve();
+            if (state !== "idle") {
+                return Promise.reject(new Error("Pi callback IPC server cannot be restarted"));
+            }
+            if (!options.socketPath || !options.token) {
+                state = "stopped";
+                return Promise.reject(new Error("Pi callback IPC configuration is invalid"));
+            }
+            state = "starting";
+            return new Promise((resolve, reject) => {
+                const failed = (error) => {
+                    state = "stopped";
+                    reject(error);
+                };
+                server.once("error", failed);
+                server.listen(options.socketPath, () => {
+                    server.off("error", failed);
+                    server.on("error", () => undefined);
+                    try {
+                        fs.chmodSync(options.socketPath, 0o600);
+                    }
+                    catch (error) {
+                        state = "stopped";
+                        server.close(() => reject(error));
+                        return;
+                    }
+                    state = "running";
+                    resolve();
+                });
+            });
+        },
+        async stop() {
+            if (state === "stopped")
+                return;
+            state = "stopped";
+            for (const socket of sockets)
+                socket.destroy();
+            if (server.listening) {
+                await new Promise((resolve) => server.close(() => resolve()));
+            }
+            await fs.promises.rm(options.socketPath, { force: true }).catch(() => undefined);
+        },
+    };
+}
+/** Send one authenticated request from the short-lived Profile helper. */
+export function sendCallbackOverIpc(options) {
+    const frame = `${JSON.stringify(options.request)}\n`;
+    if (Buffer.byteLength(frame, "utf8") > CALLBACK_MAX_REQUEST_BYTES) {
+        return Promise.reject(new Error("Pi callback IPC request exceeded its limit"));
+    }
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(options.socketPath);
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            callback();
+        };
+        socket.setTimeout(CALLBACK_TIMEOUT_MS, () => {
+            finish(() => reject(new Error("Pi callback IPC timed out")));
+        });
+        socket.once("error", () => {
+            finish(() => reject(new Error("Pi callback IPC unavailable")));
+        });
+        socket.once("connect", () => socket.write(frame));
+        readFrame(socket, CALLBACK_MAX_RESPONSE_BYTES).then((value) => {
+            const response = parseWireResponse(value);
+            if (!response) {
+                finish(() => reject(new Error("Pi callback IPC response was invalid")));
+                return;
+            }
+            finish(() => resolve(response));
+        }, () => {
+            finish(() => reject(new Error("Pi callback IPC response was incomplete")));
+        });
+    });
+}
+async function handleConnection(socket, options) {
+    try {
+        const frame = await readFrame(socket, CALLBACK_MAX_REQUEST_BYTES);
+        const request = parseWireRequest(frame);
+        if (!request) {
+            socket.destroy();
+            return;
+        }
+        if (!sameSecret(request.token, options.token)) {
+            writeFrame(socket, {
+                deliveryId: request.deliveryId,
+                messageId: request.messageId,
+                status: "rejected",
+                errorCode: "callback_authentication_failed",
+            });
+            return;
+        }
+        const acknowledgement = await options.routes.deliver(request);
+        writeFrame(socket, {
+            deliveryId: acknowledgement.request.delivery_id,
+            messageId: acknowledgement.request.message_id,
+            status: acknowledgement.result.status,
+            ...(acknowledgement.result.acceptance_id
+                ? { acceptanceId: acknowledgement.result.acceptance_id }
+                : {}),
+            ...(acknowledgement.result.error_code
+                ? { errorCode: acknowledgement.result.error_code }
+                : {}),
+        });
+    }
+    catch {
+        socket.destroy();
+    }
+}
+function readFrame(socket, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let bytes = 0;
+        let settled = false;
+        const cleanup = () => {
+            socket.off("data", onData);
+            socket.off("end", onEnd);
+            socket.off("close", onClose);
+            socket.off("error", onError);
+        };
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error)
+                reject(error);
+            else
+                resolve(value ?? "");
+        };
+        const onData = (chunk) => {
+            const newline = chunk.indexOf(0x0a);
+            const frameChunk = newline >= 0 ? chunk.subarray(0, newline) : chunk;
+            bytes += frameChunk.length;
+            if (bytes > maxBytes) {
+                finish(new Error("Pi callback IPC frame exceeded its limit"));
+                return;
+            }
+            chunks.push(frameChunk);
+            if (newline >= 0) {
+                finish(undefined, Buffer.concat(chunks, bytes).toString("utf8"));
+            }
+        };
+        const onEnd = () => finish(new Error("Pi callback IPC frame ended early"));
+        const onClose = () => finish(new Error("Pi callback IPC connection closed"));
+        const onError = () => finish(new Error("Pi callback IPC failed"));
+        socket.on("data", onData);
+        socket.once("end", onEnd);
+        socket.once("close", onClose);
+        socket.once("error", onError);
+    });
+}
+function writeFrame(socket, value) {
+    if (socket.destroyed)
+        return;
+    const frame = `${JSON.stringify(value)}\n`;
+    if (Buffer.byteLength(frame, "utf8") > CALLBACK_MAX_RESPONSE_BYTES) {
+        socket.destroy();
+        return;
+    }
+    socket.end(frame);
+}
+function parseWireRequest(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(parsed))
+        return undefined;
+    const keys = [
+        "token",
+        "controllerId",
+        "deliveryId",
+        "messageId",
+        "idempotencyKey",
+        "body",
+    ];
+    if (Object.keys(parsed).length !== keys.length)
+        return undefined;
+    if (keys.some((key) => typeof parsed[key] !== "string"))
+        return undefined;
+    return parsed;
+}
+function parseWireResponse(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(parsed))
+        return undefined;
+    const allowed = new Set([
+        "deliveryId",
+        "messageId",
+        "status",
+        "acceptanceId",
+        "errorCode",
+    ]);
+    if (Object.keys(parsed).some((key) => !allowed.has(key)))
+        return undefined;
+    if (typeof parsed.deliveryId !== "string" || typeof parsed.messageId !== "string") {
+        return undefined;
+    }
+    if (!["accepted", "retry", "rejected", "unknown"].includes(String(parsed.status))) {
+        return undefined;
+    }
+    if (parsed.acceptanceId !== undefined && typeof parsed.acceptanceId !== "string") {
+        return undefined;
+    }
+    if (parsed.errorCode !== undefined && typeof parsed.errorCode !== "string") {
+        return undefined;
+    }
+    if (parsed.status === "accepted" && !parsed.acceptanceId)
+        return undefined;
+    return parsed;
+}
+function sameSecret(left, right) {
+    const leftBytes = Buffer.from(left, "utf8");
+    const rightBytes = Buffer.from(right, "utf8");
+    return leftBytes.length === rightBytes.length && timingSafeEqual(leftBytes, rightBytes);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=ipc.js.map

package/lib/ipc.js.map

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

package/lib/profile.d.ts

@@ -0,0 +1,14 @@
+export interface ConnectorProfileResources {
+    readonly instanceNonce: string;
+    readonly directory: string;
+    readonly socketPath: string;
+    readonly stateDirectory: string;
+    readonly token: string;
+    readonly profilePath: string;
+    readonly profile: Readonly<Record<string, unknown>>;
+    readonly fingerprint: string;
+    environment(controllerId: string): NodeJS.ProcessEnv;
+    remove(): void;
+}
+/** Create one Pi-runtime-private route-bound Host Profile and IPC authority. */
+export declare function createConnectorProfileResources(baseEnvironment?: Readonly<NodeJS.ProcessEnv>): ConnectorProfileResources;

package/lib/profile.js

@@ -0,0 +1,160 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createTrustedHostProfileRuntime, hostProfileRelayEnvironment, } from "@scotthuang/agent-knock-knock/host-adapter";
+import { CALLBACK_MAX_RESPONSE_BYTES, CALLBACK_SOCKET_ENV, CALLBACK_TIMEOUT_MS, CALLBACK_TOKEN_ENV, CONNECTOR_STATE_DIR_ENV, CONNECTOR_VERSION, CONTROLLER_ID_ENV, PI_HOST_ID, SUPPORTED_PI_VERSION, } from "./constants.js";
+const HOST_PROFILE_SCHEMA_URL = "https://raw.githubusercontent.com/scotthuang/agent-knock-knock/main/" +
+    "schemas/host-profile-v1.schema.json";
+/** Create one Pi-runtime-private route-bound Host Profile and IPC authority. */
+export function createConnectorProfileResources(baseEnvironment = process.env) {
+    if (process.platform === "win32") {
+        throw new Error("agent-knock-knock-pi POC requires a POSIX Unix socket");
+    }
+    const instanceNonce = randomBytes(12).toString("hex");
+    const token = randomBytes(32).toString("base64url");
+    const stateDirectory = resolveStateDirectory(baseEnvironment);
+    ensurePrivateDirectory(stateDirectory);
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), "akk-pi-"));
+    fs.chmodSync(directory, 0o700);
+    const socketPath = path.join(directory, "callback.sock");
+    const profilePath = path.join(directory, "host-profile.json");
+    const helperPath = fileURLToPath(new URL("./callback-helper.js", import.meta.url));
+    const revision = `${CONNECTOR_VERSION}-${instanceNonce}`;
+    const profile = Object.freeze({
+        $schema: HOST_PROFILE_SCHEMA_URL,
+        schema: "agent-knock-knock/host-profile",
+        version: 1,
+        id: "pi-native",
+        revision,
+        compatibility: {
+            host: PI_HOST_ID,
+            range: `=${SUPPORTED_PI_VERSION}`,
+        },
+        controllerContext: {
+            driver: "environment_v1",
+            sessionIdVariable: CONTROLLER_ID_ENV,
+            scope: "route_bound_v1",
+        },
+        callback: {
+            driver: "command_json_v1",
+            executable: process.execPath,
+            arguments: [
+                helperPath,
+                "--controller-id",
+                "${controller.session_id}",
+                "--delivery-id",
+                "${envelope.delivery_id}",
+                "--message-id",
+                "${envelope.message_id}",
+                "--idempotency-key",
+                "${envelope.idempotency_key}",
+            ],
+            stdin: "${envelope.body}",
+            environment: {
+                allow: [CALLBACK_SOCKET_ENV, CALLBACK_TOKEN_ENV],
+            },
+            timeoutMs: CALLBACK_TIMEOUT_MS,
+            maxOutputBytes: CALLBACK_MAX_RESPONSE_BYTES,
+            acknowledgement: {
+                disposition: {
+                    jsonPointer: "/result/status",
+                    mapping: {
+                        accepted: "accepted",
+                        retry: "retryable_failure",
+                        rejected: "permanent_failure",
+                        unknown: "uncertain",
+                    },
+                },
+                acceptanceId: { jsonPointer: "/result/acceptance_id" },
+                acknowledgedDeliveryId: { jsonPointer: "/request/delivery_id" },
+                acknowledgedMessageId: { jsonPointer: "/request/message_id" },
+            },
+        },
+    });
+    try {
+        fs.writeFileSync(profilePath, `${JSON.stringify(profile, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+    }
+    catch (error) {
+        fs.rmSync(directory, { recursive: true, force: true });
+        throw error;
+    }
+    const environment = (controllerId) => {
+        if (!validIdentity(controllerId)) {
+            throw new Error("Pi AKK controller id is missing or invalid");
+        }
+        const base = {
+            ...baseEnvironment,
+            [CONTROLLER_ID_ENV]: controllerId,
+            [CALLBACK_SOCKET_ENV]: socketPath,
+            [CALLBACK_TOKEN_ENV]: token,
+        };
+        const runtime = createTrustedHostProfileRuntime({
+            selection: profilePath,
+            host: PI_HOST_ID,
+            hostVersion: SUPPORTED_PI_VERSION,
+            environment: base,
+        });
+        return hostProfileRelayEnvironment(runtime, base);
+    };
+    let fingerprint;
+    try {
+        const validationEnvironment = environment(`akk-pi:${instanceNonce}:profile-validation`);
+        const candidate = validationEnvironment.AKK_HOST_PROFILE_FINGERPRINT;
+        if (!candidate) {
+            throw new Error("AKK Host Adapter did not produce a Profile fingerprint");
+        }
+        fingerprint = candidate;
+    }
+    catch (error) {
+        fs.rmSync(directory, { recursive: true, force: true });
+        throw error;
+    }
+    let removed = false;
+    return Object.freeze({
+        instanceNonce,
+        directory,
+        socketPath,
+        stateDirectory,
+        token,
+        profilePath,
+        profile,
+        fingerprint,
+        environment,
+        remove() {
+            if (removed)
+                return;
+            removed = true;
+            fs.rmSync(directory, { recursive: true, force: true });
+        },
+    });
+}
+function resolveStateDirectory(environment) {
+    const configured = environment[CONNECTOR_STATE_DIR_ENV];
+    if (configured) {
+        if (!path.isAbsolute(configured)) {
+            throw new Error(`${CONNECTOR_STATE_DIR_ENV} must be an absolute path`);
+        }
+        return path.resolve(configured);
+    }
+    return path.join(os.homedir(), ".pi", "agent", "akk");
+}
+function ensurePrivateDirectory(directory) {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stats = fs.lstatSync(directory);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error("Pi AKK state directory must be a real directory");
+    }
+    fs.chmodSync(directory, 0o700);
+}
+function validIdentity(value) {
+    return value.length > 0 &&
+        value.trim() === value &&
+        !/[\u0000-\u001f\u007f]/u.test(value);
+}
+//# sourceMappingURL=profile.js.map

package/lib/profile.js.map

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

package/lib/routes.d.ts

@@ -0,0 +1,71 @@
+import { CallbackInbox } from "./callback-inbox.js";
+export interface CallbackRequest {
+    readonly controllerId: string;
+    readonly deliveryId: string;
+    readonly messageId: string;
+    readonly idempotencyKey: string;
+    readonly body: string;
+}
+export type CallbackStatus = "accepted" | "retry" | "rejected" | "unknown";
+export interface CallbackAcknowledgement {
+    readonly request: {
+        readonly delivery_id: string;
+        readonly message_id: string;
+    };
+    readonly result: {
+        readonly status: CallbackStatus;
+        readonly acceptance_id?: string;
+        readonly error_code?: string;
+    };
+}
+/** One exact Pi session/branch runtime that may receive AKK callbacks. */
+export interface PiCallbackTarget {
+    /** Exact object identity shared with the HostAdapter controller context. */
+    readonly authority: object;
+    readonly sessionId: string;
+    /** Changes when the extension runtime or explicit branch epoch changes. */
+    readonly runtimeGeneration: string;
+    /** Diagnostic-only snapshot; normal conversation messages advance the leaf. */
+    readonly anchorLeafId: string | null;
+    isLive(): boolean;
+    deliver(body: string, request: CallbackRequest): void | Promise<void>;
+}
+export interface PiCallbackRoute {
+    readonly controllerId: string;
+    readonly target: PiCallbackTarget;
+    readonly sessionId: string;
+    readonly runtimeGeneration: string;
+    readonly anchorLeafId: string | null;
+}
+/**
+ * Exact-object callback routing for a Pi controller incarnation.
+ *
+ * Admission is durable before an accepted ACK is returned. Delivery into Pi
+ * is then at-least-once across the narrow `sendMessage()`/inbox-state window,
+ * because Pi 0.84.4 does not expose an admission receipt for that API.
+ */
+export declare class PiRouteTable {
+    private readonly inbox;
+    private readonly routeByAuthority;
+    private readonly disposedAuthorities;
+    private readonly routeByControllerId;
+    private readonly deliveryByKey;
+    private readonly retryTimerByKey;
+    private readonly retryAttemptByKey;
+    private readonly instanceNonce;
+    private nextRouteNonce;
+    private active;
+    constructor(inbox: CallbackInbox, instanceNonce?: string);
+    bind(target: PiCallbackTarget): PiCallbackRoute;
+    dispose(target: PiCallbackTarget): void;
+    deliver(request: CallbackRequest): Promise<CallbackAcknowledgement>;
+    close(): Promise<void>;
+    private replayPending;
+    private ensureDelivery;
+    private attemptDelivery;
+    private scheduleRetry;
+    private cancelRouteRetries;
+    private clearRetry;
+    private assertActive;
+    private routeIsLive;
+}