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

package/lib/routes.js

@@ -0,0 +1,255 @@
+import { createHash, randomBytes } from "node:crypto";
+const RETRY_BASE_DELAY_MS = 1_000;
+const RETRY_MAX_DELAY_MS = 30_000;
+/**
+ * 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 class PiRouteTable {
+    inbox;
+    routeByAuthority = new WeakMap();
+    disposedAuthorities = new WeakSet();
+    routeByControllerId = new Map();
+    deliveryByKey = new Map();
+    retryTimerByKey = new Map();
+    retryAttemptByKey = new Map();
+    instanceNonce;
+    nextRouteNonce = 0;
+    active = true;
+    constructor(inbox, instanceNonce) {
+        this.inbox = inbox;
+        this.instanceNonce = instanceNonce ?? randomBytes(12).toString("hex");
+        if (!validIdentity(this.instanceNonce)) {
+            throw new Error("Pi AKK route instance nonce is invalid");
+        }
+    }
+    bind(target) {
+        this.assertActive();
+        validateTarget(target);
+        if (this.disposedAuthorities.has(target.authority)) {
+            throw new Error("AKK cannot reuse a disposed Pi controller authority");
+        }
+        const existing = this.routeByAuthority.get(target.authority);
+        if (existing) {
+            if (existing.target !== target ||
+                existing.sessionId !== target.sessionId ||
+                existing.runtimeGeneration !== target.runtimeGeneration ||
+                existing.anchorLeafId !== target.anchorLeafId) {
+                throw new Error("AKK Pi controller authority changed identity");
+            }
+            return existing;
+        }
+        this.nextRouteNonce += 1;
+        const controllerId = [
+            "akk-pi",
+            this.instanceNonce,
+            this.nextRouteNonce.toString(36),
+            identityDigest(target.sessionId, target.runtimeGeneration),
+        ].join(":");
+        const route = Object.freeze({
+            controllerId,
+            target,
+            sessionId: target.sessionId,
+            runtimeGeneration: target.runtimeGeneration,
+            anchorLeafId: target.anchorLeafId,
+        });
+        this.routeByAuthority.set(target.authority, route);
+        this.routeByControllerId.set(controllerId, route);
+        void this.replayPending(route);
+        return route;
+    }
+    dispose(target) {
+        this.disposedAuthorities.add(target.authority);
+        const route = this.routeByAuthority.get(target.authority);
+        if (!route)
+            return;
+        if (this.routeByControllerId.get(route.controllerId) === route) {
+            this.routeByControllerId.delete(route.controllerId);
+        }
+        this.cancelRouteRetries(route.controllerId);
+    }
+    async deliver(request) {
+        const base = acknowledgementBase(request);
+        if (!this.active || !validRequest(request)) {
+            return rejected(base, "invalid_or_stopped_callback_route");
+        }
+        const route = this.routeByControllerId.get(request.controllerId);
+        if (!route || !this.routeIsLive(route)) {
+            return rejected(base, "pi_route_not_live");
+        }
+        let admission;
+        try {
+            admission = await this.inbox.admit(request);
+        }
+        catch {
+            return retry(base, "callback_inbox_unavailable");
+        }
+        if (admission.disposition === "collision") {
+            return rejected(base, "idempotency_collision");
+        }
+        if (admission.entry.state === "pending") {
+            await this.ensureDelivery(route, admission.entry);
+        }
+        return accepted(base, admission.entry.acceptanceId);
+    }
+    async close() {
+        if (!this.active)
+            return;
+        this.active = false;
+        this.routeByControllerId.clear();
+        for (const timer of this.retryTimerByKey.values())
+            clearTimeout(timer);
+        this.retryTimerByKey.clear();
+        await Promise.allSettled(this.deliveryByKey.values());
+    }
+    async replayPending(route) {
+        let pending;
+        try {
+            pending = await this.inbox.listPending(route.controllerId);
+        }
+        catch {
+            return;
+        }
+        for (const entry of pending) {
+            if (!this.routeIsLive(route))
+                return;
+            await this.ensureDelivery(route, entry);
+        }
+    }
+    ensureDelivery(route, entry) {
+        const key = deliveryKey(entry);
+        const existing = this.deliveryByKey.get(key);
+        if (existing)
+            return existing;
+        const delivery = this.attemptDelivery(route, entry).finally(() => {
+            if (this.deliveryByKey.get(key) === delivery)
+                this.deliveryByKey.delete(key);
+        });
+        this.deliveryByKey.set(key, delivery);
+        return delivery;
+    }
+    async attemptDelivery(route, entry) {
+        if (!this.routeIsLive(route))
+            return;
+        try {
+            await route.target.deliver(entry.body, callbackRequest(entry));
+            await this.inbox.markDelivered(entry);
+            this.retryAttemptByKey.delete(deliveryKey(entry));
+            this.clearRetry(deliveryKey(entry));
+        }
+        catch {
+            this.scheduleRetry(route, entry);
+        }
+    }
+    scheduleRetry(route, entry) {
+        if (!this.routeIsLive(route))
+            return;
+        const key = deliveryKey(entry);
+        if (this.retryTimerByKey.has(key))
+            return;
+        const attempt = (this.retryAttemptByKey.get(key) ?? 0) + 1;
+        this.retryAttemptByKey.set(key, attempt);
+        const delay = Math.min(RETRY_BASE_DELAY_MS * 2 ** Math.min(attempt - 1, 5), RETRY_MAX_DELAY_MS);
+        const timer = setTimeout(() => {
+            this.retryTimerByKey.delete(key);
+            void this.ensureDelivery(route, entry);
+        }, delay);
+        timer.unref();
+        this.retryTimerByKey.set(key, timer);
+    }
+    cancelRouteRetries(controllerId) {
+        for (const [key, timer] of this.retryTimerByKey) {
+            if (!key.startsWith(`${controllerId}\u0000`))
+                continue;
+            clearTimeout(timer);
+            this.retryTimerByKey.delete(key);
+            this.retryAttemptByKey.delete(key);
+        }
+    }
+    clearRetry(key) {
+        const timer = this.retryTimerByKey.get(key);
+        if (timer)
+            clearTimeout(timer);
+        this.retryTimerByKey.delete(key);
+    }
+    assertActive() {
+        if (!this.active)
+            throw new Error("Pi AKK route table is stopped");
+    }
+    routeIsLive(route) {
+        if (!this.active || this.routeByControllerId.get(route.controllerId) !== route) {
+            return false;
+        }
+        try {
+            return route.target.sessionId === route.sessionId &&
+                route.target.runtimeGeneration === route.runtimeGeneration &&
+                route.target.anchorLeafId === route.anchorLeafId &&
+                route.target.isLive();
+        }
+        catch {
+            return false;
+        }
+    }
+}
+function validateTarget(target) {
+    if (typeof target.authority !== "object" ||
+        target.authority === null ||
+        !validIdentity(target.sessionId) ||
+        !validIdentity(target.runtimeGeneration) ||
+        (target.anchorLeafId !== null && !validIdentity(target.anchorLeafId)) ||
+        typeof target.isLive !== "function" ||
+        typeof target.deliver !== "function") {
+        throw new Error("Pi AKK callback target is invalid");
+    }
+}
+function callbackRequest(entry) {
+    return {
+        controllerId: entry.controllerId,
+        deliveryId: entry.deliveryId,
+        messageId: entry.messageId,
+        idempotencyKey: entry.idempotencyKey,
+        body: entry.body,
+    };
+}
+function acknowledgementBase(request) {
+    return {
+        delivery_id: request.deliveryId,
+        message_id: request.messageId,
+    };
+}
+function accepted(request, acceptanceId) {
+    return { request, result: { status: "accepted", acceptance_id: acceptanceId } };
+}
+function retry(request, errorCode) {
+    return { request, result: { status: "retry", error_code: errorCode } };
+}
+function rejected(request, errorCode) {
+    return { request, result: { status: "rejected", error_code: errorCode } };
+}
+function validRequest(request) {
+    return validIdentity(request.controllerId) &&
+        validIdentity(request.deliveryId) &&
+        validIdentity(request.messageId) &&
+        validIdentity(request.idempotencyKey) &&
+        typeof request.body === "string";
+}
+function validIdentity(value) {
+    return typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= 4096 &&
+        value.trim() === value &&
+        !/[\u0000-\u001f\u007f]/u.test(value);
+}
+function identityDigest(sessionId, generation) {
+    return createHash("sha256")
+        .update(JSON.stringify([sessionId, generation]))
+        .digest("base64url")
+        .slice(0, 22);
+}
+function deliveryKey(entry) {
+    return `${entry.controllerId}\u0000${entry.idempotencyKey}`;
+}
+//# sourceMappingURL=routes.js.map

package/lib/routes.js.map

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

package/lib/schema-adapter.d.ts

@@ -0,0 +1,7 @@
+import { type TSchema } from "typebox";
+/**
+ * Project AKK schemas into Pi's provider-facing TypeBox subset. The untouched
+ * schema remains authoritative at execution time through AJV and AKK itself.
+ */
+export declare function adaptHostToolInputSchema(schema: Readonly<Record<string, unknown>>): TSchema;
+export declare function compileAuthoritativeInputValidator(schema: Readonly<Record<string, unknown>>): (value: unknown) => void;

package/lib/schema-adapter.js

@@ -0,0 +1,85 @@
+import { Ajv } from "ajv";
+import { Type } from "typebox";
+const SCHEMA_TYPES = new Set([
+    "object",
+    "array",
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "null",
+]);
+const ajv = new Ajv({
+    allErrors: true,
+    strict: false,
+    validateFormats: false,
+});
+/**
+ * Project AKK schemas into Pi's provider-facing TypeBox subset. The untouched
+ * schema remains authoritative at execution time through AJV and AKK itself.
+ */
+export function adaptHostToolInputSchema(schema) {
+    const adapted = adaptNode(schema);
+    if (adapted.type !== "object") {
+        throw new Error("AKK Host tool input schema must have an object root");
+    }
+    return Type.Unsafe(adapted);
+}
+export function compileAuthoritativeInputValidator(schema) {
+    let validate;
+    try {
+        validate = ajv.compile(structuredClone(schema));
+    }
+    catch {
+        throw new Error("AKK Host tool exposed an invalid authoritative input schema");
+    }
+    return (value) => {
+        if (!validate(value)) {
+            throw new Error("arguments did not match the authoritative AKK tool schema");
+        }
+    };
+}
+function adaptNode(value) {
+    if (!isRecord(value))
+        return {};
+    const output = {};
+    if (typeof value.description === "string")
+        output.description = value.description;
+    if (typeof value.title === "string")
+        output.title = value.title;
+    const type = typeof value.type === "string" && SCHEMA_TYPES.has(value.type)
+        ? value.type
+        : undefined;
+    if (!type)
+        return output;
+    output.type = type;
+    if (type === "object") {
+        const inputProperties = isRecord(value.properties) ? value.properties : {};
+        const properties = {};
+        for (const [name, property] of Object.entries(inputProperties)) {
+            properties[name] = adaptNode(property);
+        }
+        output.properties = properties;
+        if (Array.isArray(value.required)) {
+            const required = value.required.filter((name) => typeof name === "string" && Object.hasOwn(properties, name));
+            if (required.length > 0)
+                output.required = required;
+        }
+        if (typeof value.additionalProperties === "boolean") {
+            output.additionalProperties = value.additionalProperties;
+        }
+        return output;
+    }
+    if (type === "array" && isRecord(value.items)) {
+        output.items = adaptNode(value.items);
+    }
+    if (Array.isArray(value.enum))
+        output.enum = structuredClone(value.enum);
+    if (Object.hasOwn(value, "const"))
+        output.const = structuredClone(value.const);
+    return output;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=schema-adapter.js.map

package/lib/schema-adapter.js.map

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

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@scotthuang/agent-knock-knock-pi",
+  "version": "0.1.0-poc.1",
+  "description": "Pi-as-orchestrator connector for Agent Knock Knock",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.js.map",
+    "lib/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "agent-knock-knock",
+    "codex",
+    "claude-code",
+    "orchestration"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scotthuang/agent-knock-knock.git",
+    "directory": "connectors/pi"
+  },
+  "bugs": {
+    "url": "https://github.com/scotthuang/agent-knock-knock/issues"
+  },
+  "homepage": "https://github.com/scotthuang/agent-knock-knock/tree/main/connectors/pi#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./lib/index.js"
+    ]
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "clean": "node -e \"fs.rmSync('lib', { recursive: true, force: true }); fs.rmSync('.test-dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test:fast": "npm run build && tsc -p tsconfig.test.json && node --test .test-dist/test/*.test.js",
+    "prepack": "npm run build",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "dependencies": {
+    "@scotthuang/agent-knock-knock": "0.12.23",
+    "ajv": "8.20.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@types/node": "22.20.0",
+    "typebox": "1.3.7",
+    "typescript": "6.0.3"
+  }
+}