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

package/lib/callback-inbox.js

@@ -0,0 +1,281 @@
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const INBOX_SCHEMA = "agent-knock-knock/pi-callback-inbox";
+const INBOX_VERSION = 1;
+const DEFAULT_MAX_ENTRIES = 256;
+const DEFAULT_MAX_FILE_BYTES = 64 * 1024 * 1024;
+/**
+ * A small, process-owned durable inbox for the last callback hop into Pi.
+ *
+ * `admit()` returns only after an atomic, fsync-backed file replacement. This
+ * lets the callback helper acknowledge connector admission even though Pi's
+ * `sendMessage()` API itself does not return an admission receipt.
+ */
+export class CallbackInbox {
+    entries;
+    transactionTail = Promise.resolve();
+    active = true;
+    filePath;
+    maxEntries;
+    maxFileBytes;
+    constructor(options) {
+        if (!path.isAbsolute(options.filePath)) {
+            throw new Error("Pi callback inbox path must be absolute");
+        }
+        this.filePath = options.filePath;
+        this.maxEntries = positiveInteger(options.maxEntries ?? DEFAULT_MAX_ENTRIES, "maxEntries");
+        this.maxFileBytes = positiveInteger(options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES, "maxFileBytes");
+        this.entries = loadInbox(this.filePath, this.maxEntries, this.maxFileBytes);
+    }
+    admit(request) {
+        return this.withTransaction(async () => {
+            const key = callbackKey(request.controllerId, request.idempotencyKey);
+            const fingerprint = requestFingerprint(request);
+            const previous = this.entries.get(key);
+            if (previous) {
+                if (previous.fingerprint !== fingerprint) {
+                    return { disposition: "collision" };
+                }
+                return { disposition: "duplicate", entry: previous };
+            }
+            const entry = Object.freeze({
+                ...request,
+                fingerprint,
+                acceptanceId: `akk-pi-callback:${randomBytes(18).toString("base64url")}`,
+                state: "pending",
+                acceptedAt: new Date().toISOString(),
+            });
+            const next = new Map(this.entries);
+            pruneDeliveredEntries(next, this.maxEntries - 1);
+            if (next.size >= this.maxEntries) {
+                throw new Error("Pi callback inbox is full");
+            }
+            next.set(key, entry);
+            await persistInbox(this.filePath, next.values(), this.maxFileBytes);
+            this.entries = next;
+            return { disposition: "admitted", entry };
+        });
+    }
+    markDelivered(entry) {
+        return this.withTransaction(async () => {
+            const key = callbackKey(entry.controllerId, entry.idempotencyKey);
+            const current = this.entries.get(key);
+            if (!current || current.fingerprint !== entry.fingerprint) {
+                throw new Error("Pi callback inbox entry is no longer current");
+            }
+            if (current.state === "delivered")
+                return current;
+            const delivered = Object.freeze({
+                ...current,
+                state: "delivered",
+                deliveredAt: new Date().toISOString(),
+            });
+            const next = new Map(this.entries);
+            next.set(key, delivered);
+            await persistInbox(this.filePath, next.values(), this.maxFileBytes);
+            this.entries = next;
+            return delivered;
+        });
+    }
+    listPending(controllerId) {
+        return this.withTransaction(() => Promise.resolve([...this.entries.values()].filter((entry) => entry.state === "pending" &&
+            (controllerId === undefined || entry.controllerId === controllerId))));
+    }
+    async close() {
+        await this.transactionTail;
+        this.active = false;
+    }
+    withTransaction(operation) {
+        const run = this.transactionTail.then(() => {
+            if (!this.active)
+                throw new Error("Pi callback inbox is closed");
+            return operation();
+        });
+        this.transactionTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+}
+function loadInbox(filePath, maxEntries, maxFileBytes) {
+    const directory = path.dirname(filePath);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    let stat;
+    try {
+        stat = fs.lstatSync(filePath);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return new Map();
+        throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new Error("Pi callback inbox must be a regular file");
+    }
+    if (stat.size > maxFileBytes) {
+        throw new Error("Pi callback inbox exceeded its size limit");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        throw new Error("Pi callback inbox is invalid");
+    }
+    if (!isInboxDocument(parsed)) {
+        throw new Error("Pi callback inbox is invalid");
+    }
+    if (parsed.entries.length > maxEntries) {
+        throw new Error("Pi callback inbox contains too many entries");
+    }
+    const entries = new Map();
+    for (const candidate of parsed.entries) {
+        const entry = validateInboxEntry(candidate);
+        const key = callbackKey(entry.controllerId, entry.idempotencyKey);
+        if (entries.has(key))
+            throw new Error("Pi callback inbox contains duplicate entries");
+        entries.set(key, Object.freeze(entry));
+    }
+    return entries;
+}
+async function persistInbox(filePath, entries, maxFileBytes) {
+    const document = {
+        schema: INBOX_SCHEMA,
+        version: INBOX_VERSION,
+        entries: [...entries],
+    };
+    const body = `${JSON.stringify(document)}\n`;
+    if (Buffer.byteLength(body, "utf8") > maxFileBytes) {
+        throw new Error("Pi callback inbox exceeded its size limit");
+    }
+    const directory = path.dirname(filePath);
+    const temporaryPath = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+    let handle;
+    try {
+        handle = await fs.promises.open(temporaryPath, "wx", 0o600);
+        await handle.writeFile(body, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fs.promises.rename(temporaryPath, filePath);
+        await fs.promises.chmod(filePath, 0o600);
+        await syncDirectory(directory);
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await fs.promises.rm(temporaryPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+async function syncDirectory(directory) {
+    let handle;
+    try {
+        handle = await fs.promises.open(directory, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        if (!isNodeError(error) ||
+            !["EINVAL", "ENOTSUP", "EISDIR"].includes(error.code ?? "")) {
+            throw error;
+        }
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function pruneDeliveredEntries(entries, targetSize) {
+    if (entries.size <= targetSize)
+        return;
+    const delivered = [...entries.entries()]
+        .filter(([, entry]) => entry.state === "delivered")
+        .sort((left, right) => left[1].acceptedAt.localeCompare(right[1].acceptedAt));
+    for (const [key] of delivered) {
+        if (entries.size <= targetSize)
+            return;
+        entries.delete(key);
+    }
+}
+function requestFingerprint(request) {
+    return createHash("sha256")
+        .update(JSON.stringify([
+        request.controllerId,
+        request.deliveryId,
+        request.messageId,
+        request.idempotencyKey,
+        request.body,
+    ]))
+        .digest("hex");
+}
+function callbackKey(controllerId, idempotencyKey) {
+    return `${controllerId}\u0000${idempotencyKey}`;
+}
+function isInboxDocument(value) {
+    if (!isRecord(value))
+        return false;
+    return value.schema === INBOX_SCHEMA &&
+        value.version === INBOX_VERSION &&
+        Array.isArray(value.entries) &&
+        Object.keys(value).every((key) => ["schema", "version", "entries"].includes(key));
+}
+function validateInboxEntry(value) {
+    if (!isRecord(value))
+        throw new Error("Pi callback inbox entry is invalid");
+    const requiredStrings = [
+        "controllerId",
+        "deliveryId",
+        "messageId",
+        "idempotencyKey",
+        "body",
+        "fingerprint",
+        "acceptanceId",
+        "acceptedAt",
+    ];
+    if (requiredStrings.some((key) => typeof value[key] !== "string")) {
+        throw new Error("Pi callback inbox entry is invalid");
+    }
+    if (value.state !== "pending" && value.state !== "delivered") {
+        throw new Error("Pi callback inbox entry is invalid");
+    }
+    if (value.deliveredAt !== undefined && typeof value.deliveredAt !== "string") {
+        throw new Error("Pi callback inbox entry is invalid");
+    }
+    const allowedKeys = new Set([...requiredStrings, "state", "deliveredAt"]);
+    if (Object.keys(value).some((key) => !allowedKeys.has(key))) {
+        throw new Error("Pi callback inbox entry is invalid");
+    }
+    const entry = value;
+    if (!validIdentity(entry.controllerId) ||
+        !validIdentity(entry.deliveryId) ||
+        !validIdentity(entry.messageId) ||
+        !validIdentity(entry.idempotencyKey) ||
+        !/^[a-f0-9]{64}$/u.test(entry.fingerprint) ||
+        !validIdentity(entry.acceptanceId) ||
+        !validDate(entry.acceptedAt) ||
+        (entry.state === "delivered" && !entry.deliveredAt) ||
+        (entry.deliveredAt !== undefined && !validDate(entry.deliveredAt)) ||
+        requestFingerprint(entry) !== entry.fingerprint) {
+        throw new Error("Pi callback inbox entry is invalid");
+    }
+    return entry;
+}
+function validIdentity(value) {
+    return value.length > 0 &&
+        value.length <= 4096 &&
+        value.trim() === value &&
+        !/[\u0000-\u001f\u007f]/u.test(value);
+}
+function validDate(value) {
+    return Number.isFinite(Date.parse(value));
+}
+function positiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`Pi callback inbox ${name} must be a positive integer`);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+//# sourceMappingURL=callback-inbox.js.map

package/lib/callback-inbox.js.map

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

package/lib/constants.d.ts

@@ -0,0 +1,14 @@
+export declare const CONNECTOR_NAME = "agent-knock-knock-pi";
+export declare const CONNECTOR_PACKAGE = "@scotthuang/agent-knock-knock-pi";
+export declare const CONNECTOR_VERSION = "0.1.0-poc.1";
+export declare const PI_HOST_ID = "pi-coding-agent";
+export declare const SUPPORTED_PI_VERSION = "0.84.4";
+export declare const CONTROLLER_ID_ENV = "AKK_PI_CONTROLLER_ID";
+export declare const CALLBACK_SOCKET_ENV = "AKK_PI_CALLBACK_SOCKET";
+export declare const CALLBACK_TOKEN_ENV = "AKK_PI_CALLBACK_TOKEN";
+export declare const CONNECTOR_STATE_DIR_ENV = "AKK_PI_STATE_DIR";
+export declare const CONNECTOR_STORE_DIR_ENV = "AKK_PI_STORE_DIR";
+export declare const CALLBACK_MAX_REQUEST_BYTES: number;
+export declare const CALLBACK_MAX_RESPONSE_BYTES: number;
+export declare const CALLBACK_TIMEOUT_MS = 8000;
+export declare const LIFECYCLE_INTERVAL_MS = 5000;

package/lib/constants.js

@@ -0,0 +1,15 @@
+export const CONNECTOR_NAME = "agent-knock-knock-pi";
+export const CONNECTOR_PACKAGE = "@scotthuang/agent-knock-knock-pi";
+export const CONNECTOR_VERSION = "0.1.0-poc.1";
+export const PI_HOST_ID = "pi-coding-agent";
+export const SUPPORTED_PI_VERSION = "0.84.4";
+export const CONTROLLER_ID_ENV = "AKK_PI_CONTROLLER_ID";
+export const CALLBACK_SOCKET_ENV = "AKK_PI_CALLBACK_SOCKET";
+export const CALLBACK_TOKEN_ENV = "AKK_PI_CALLBACK_TOKEN";
+export const CONNECTOR_STATE_DIR_ENV = "AKK_PI_STATE_DIR";
+export const CONNECTOR_STORE_DIR_ENV = "AKK_PI_STORE_DIR";
+export const CALLBACK_MAX_REQUEST_BYTES = 2 * 1024 * 1024;
+export const CALLBACK_MAX_RESPONSE_BYTES = 64 * 1024;
+export const CALLBACK_TIMEOUT_MS = 8_000;
+export const LIFECYCLE_INTERVAL_MS = 5_000;
+//# sourceMappingURL=constants.js.map

package/lib/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,cAAc,GAAG,sBAAsB,CAAC;AACrD,MAAM,CAAC,MAAM,iBAAiB,GAAG,kCAAkC,CAAC;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAE/C,MAAM,CAAC,MAAM,UAAU,GAAG,iBAAiB,CAAC;AAC5C,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAE7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;AACxD,MAAM,CAAC,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAG,kBAAkB,CAAC;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAG,kBAAkB,CAAC;AAE1D,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,GAAG,IAAI,CAAC;AACrD,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AACzC,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,20 @@
+/** Pi-as-orchestrator POC: Pi controls Codex and Claude Code through AKK. */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type CreateHostAdapterOptions, type HostAdapter } from "@scotthuang/agent-knock-knock/host-adapter";
+import { CallbackInbox } from "./callback-inbox.js";
+import { createCallbackIpcServer } from "./ipc.js";
+import { createConnectorProfileResources } from "./profile.js";
+import { PiRouteTable } from "./routes.js";
+/** @internal Replaceable seams for native wiring and lifecycle tests. */
+export interface ConnectorDependencies {
+    readonly piVersion: string;
+    readonly createConnectorProfileResources: typeof createConnectorProfileResources;
+    readonly createCallbackInbox: (options: ConstructorParameters<typeof CallbackInbox>[0]) => CallbackInbox;
+    readonly createRouteTable: (inbox: CallbackInbox, instanceNonce: string) => PiRouteTable;
+    readonly createCallbackIpcServer: typeof createCallbackIpcServer;
+    readonly createHostAdapter: (options: CreateHostAdapterOptions) => HostAdapter;
+}
+/** Mount one Host-owned AKK runtime for the current Pi session incarnation. */
+export default function agentKnockKnockPi(pi: ExtensionAPI): void;
+/** @internal Mount with deterministic process, IPC, and HostAdapter seams. */
+export declare function applyWithDependencies(pi: ExtensionAPI, dependencies?: Partial<ConnectorDependencies>): void;