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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Knock Knock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,396 @@
+# Agent Knock Knock for Pi — POC
+
+This Pi Extension makes Pi an Agent Knock Knock (AKK) orchestration Host. Pi
+can use `/akk` and AKK's 16 semantic tools to control Codex and Claude Code
+terminals that are already running in tmux or Herdr.
+
+The connector does not modify Pi, launch or authenticate a coding agent, or
+depend on an OpenClaw Gateway. It uses AKK's public HostAdapter and returns
+callbacks to the exact initiating Pi session through a private local Unix
+socket.
+
+## Status and compatibility
+
+This is a POC prerelease distributed on npm as
+`@scotthuang/agent-knock-knock-pi`. Prereleases use the `next` dist-tag:
+
+```sh
+pi install npm:@scotthuang/agent-knock-knock-pi@next
+```
+
+The current compatibility contract is intentionally exact:
+
+- Pi `0.84.4`, installed from the official
+  `@earendil-works/pi-coding-agent` package.
+- Node.js `22.19.0` or newer.
+- AKK `0.12.23`, pinned by this connector's package and lockfile. Running
+  `npm ci` in `connectors/pi` installs that exact AKK runtime; a different
+  version at the repository root is not substituted automatically.
+- macOS or Linux. The POC requires a POSIX Unix socket and does not support
+  Windows named pipes.
+- At least one authenticated Codex or Claude Code process already running in a
+  supported tmux or Herdr terminal under the same OS user.
+- A configured Pi model/provider. Pi model authentication is separate from
+  AKK and is not performed by this connector.
+
+The connector rejects a Pi runtime other than `0.84.4` before it creates a
+socket or starts AKK lifecycle work. Pi's own packages remain `*` peer
+dependencies as required by Pi's package contract; the runtime check is the
+compatibility authority.
+
+## Five-minute quick start
+
+### 1. Install the accepted Pi version
+
+```sh
+npm install -g @earendil-works/pi-coding-agent@0.84.4
+node --version
+pi --version
+```
+
+Configure a model using Pi's normal `/login`, provider environment variable,
+or settings flow before continuing.
+
+### 2. Start a coding agent in a shared terminal
+
+AKK discovers an existing process; it never starts one for you. For example:
+
+```sh
+tmux new-session -s akk-pi-work -c "$(pwd -P)" codex
+```
+
+Wait for Codex to reach its interactive prompt, then detach with `Ctrl-b`
+followed by `d`. Use `claude` instead of `codex` to test Claude Code. An
+existing supported Herdr terminal works too.
+
+### 3. Install the connector
+
+```sh
+pi install npm:@scotthuang/agent-knock-knock-pi@next
+pi list
+```
+
+Using `next` follows compatible Pi connector prereleases. To pin this exact
+build instead, install
+`npm:@scotthuang/agent-knock-knock-pi@0.1.0-poc.1`; exact versions are pinned
+and are not advanced by Pi's bulk update command.
+
+### 4. Start Pi
+
+```sh
+pi
+```
+
+Pi should show `AKK ready`. The package manifest registers the Extension, so
+no `-e` path or repository checkout is required.
+
+### 5. Complete the first round trip
+
+In Pi, list the live targets:
+
+```text
+/akk list
+```
+
+If exactly one terminal is send-ready, submit a small task:
+
+```text
+/akk reply with exactly AKK_PI_OK after inspecting the current workspace
+```
+
+If multiple targets are present, use the fresh selector printed by
+`/akk list`:
+
+```text
+/akk @a1b2c3d4: reply with exactly AKK_PI_OK after inspecting the current workspace
+```
+
+A managed Send returns a `turn_id`; when the coding agent settles, its callback
+is injected into the same Pi session. Inspect it at any time with the exact
+turn selector printed by AKK:
+
+```text
+/akk status <turn-selector>
+```
+
+To observe work that you started manually in the terminal, copy the complete
+`terminal_id` from a fresh list and start a read-only Watch:
+
+```text
+/akk watch <exact-terminal-id>
+/akk status <watch-id>
+/akk unwatch <watch-id>
+```
+
+Watch does not send, adopt, approve, interrupt, or reserve the task. Do not add
+a second Watch merely to make a normal managed Send callback: managed Send
+already has a callback. When a user-priority Send must fall back to unmanaged
+physical delivery, AKK instead tries to attach the request-bound Watch itself
+and returns its `watch_id`.
+
+## Tool workflow
+
+The usual product loop is:
+
+1. **List** to discover live terminals and their current `available_actions`.
+2. **Send** using the fresh action's prefilled `session_id` or `terminal_id`.
+   Do not invent semantic IDs or retry an uncertain terminal mutation.
+3. Wait for the managed **Callback**. An unmanaged user-priority fallback may
+   return a Terminal Watch callback instead of a managed Turn callback.
+4. Use **Status** with the exact `turn_id` or `watch_id` when the callback is
+   delayed or the Pi route changed.
+5. Use **Respond** for a question in that same Turn. Use **Approve** only after
+   reviewing the live approval prompt and making an explicit decision.
+6. Use **Cancel**, **Close**, **Renew**, or **Retry Callback** only when the
+   current list/status output advertises that exact action.
+
+The `/akk` command is the direct human surface. The following 16 tools are also
+registered for model-driven orchestration:
+
+| Tool | Purpose |
+| --- | --- |
+| `agent_knock_knock_list` | List verified Codex/Claude terminals, managed work, Watches, and currently available semantic actions. |
+| `agent_knock_knock_watch` | Start a durable, read-only Watch for one exact `terminal_id`. |
+| `agent_knock_knock_unwatch` | Stop observation by exact `watch_id`; it does not interrupt the coding agent. |
+| `agent_knock_knock_list_resumable_threads` | List structurally verified native threads that can be resumed in one terminal. |
+| `agent_knock_knock_native_inspect` | Run the closed native `status` inspection for one exact terminal. Arbitrary slash commands are not accepted. |
+| `agent_knock_knock_new_thread` | Start and verify a clean native coding-agent thread after explicit user intent. |
+| `agent_knock_knock_reconcile_binding` | Detach one exact conflicting AKK Session binding after explicit confirmation, without adopting another thread. |
+| `agent_knock_knock_resume_thread` | Resume one exact complete `native_thread_id` returned by the current discovery result. |
+| `agent_knock_knock_status` | Inspect one exact managed Turn or Terminal Watch. |
+| `agent_knock_knock_send` | Send a new task through the exact currently advertised Session or terminal action. |
+| `agent_knock_knock_respond` | Answer a question or blocked callback in one existing Turn; it does not start a new Turn. |
+| `agent_knock_knock_approve` | Approve one current permission request after Pi presents a native user-decision gate. |
+| `agent_knock_knock_renew` | Renew monitoring for one stalled but still-live Turn without terminal input. |
+| `agent_knock_knock_retry_callback` | Retry one persisted managed callback with its original message identity. |
+| `agent_knock_knock_cancel` | Interrupt one exact task after Pi obtains native confirmation; the shared pane stays open. |
+| `agent_knock_knock_close` | Release AKK management for one Turn without sending terminal input or stopping the coding agent. |
+
+Except for the deliberately user-intent-first, read-only Watch path, treat the
+fresh `available_actions` output as authority. The connector preserves AKK's
+semantic-ID, idempotency, terminal identity, Store, Session, Turn, and
+completion rules rather than recreating them in Pi.
+
+## Active approval, response, and cancellation
+
+When a managed task needs permission, its callback is queued into the
+originating Pi session. A model-facing `agent_knock_knock_approve` call does not
+immediately type into the terminal. The connector first refreshes AKK Status,
+shows the current prompt in Pi's native UI, and requires a selection:
+
+- **Approve once** sends the current prompt-scoped AKK approval.
+- **Keep pending** sends no terminal input.
+- For a managed `turn_id`, **Reject and cancel task** asks for a second
+  confirmation, then invokes AKK Cancel.
+
+A terminal-scoped approval has no terminal-scoped Cancel authority, so its
+dialog offers only Approve or Keep pending. A separately advertised Cancel
+action gets its own Pi confirmation dialog.
+
+`agent_knock_knock_respond` answers an ordinary question in the exact
+in-flight Turn; it is not an approval denial. AKK currently has no generic
+"select the target's No option and continue this Turn" tool. Reject-and-cancel
+interrupts the task instead.
+
+The native confirmation flow requires an interactive Pi UI. In a context where
+`ctx.hasUI` is false, the connector refuses model-facing Approve and Cancel
+instead of mutating the terminal without a person. Headless/non-interactive Pi
+is not a product-acceptance target for this POC.
+
+AKK keeps the coding agent's existing permission mode. This connector does not
+enable `--yolo`, change a target's permission settings, or expose AKK's
+OpenClaw-specific `autoApprove` configuration.
+
+## Callback delivery and recovery
+
+The callback path is:
+
+```text
+AKK callback outbox
+  -> command_json_v1 callback helper
+  -> authenticated private Unix socket
+  -> fsync-backed Pi callback inbox
+  -> originating Pi session
+```
+
+When Pi is idle, the callback is injected with `triggerTurn: true` and starts a
+new Pi turn. When Pi is already producing a response, the connector uses Pi's
+follow-up queue so the callback is not mixed into the current model turn.
+
+An `accepted` callback acknowledgement means that the connector durably
+admitted the exact delivery to its local inbox and returned an acceptance ID.
+It does **not** mean the Pi model consumed the message: Pi `0.84.4` exposes a
+synchronous `sendMessage()` call without a model-consumption receipt. The last
+hop is therefore at-least-once or uncertain if Pi crashes between
+`sendMessage()` and recording the inbox entry as delivered. Delivery and
+idempotency IDs let the connector reject collisions and suppress known exact
+duplicates.
+
+For a missing callback:
+
+1. If Pi is busy, wait for the current response to end; the callback may be a
+   queued follow-up.
+2. Refresh `/akk list`, then run `/akk status <turn-selector-or-watch-id>`.
+   Status is the authoritative manual recovery path and does not need the
+   callback to have reached the model.
+3. If a still-live task has no managed callback route, start a new read-only
+   Watch on its exact current `terminal_id` and retain the returned `watch_id`.
+4. Use `agent_knock_knock_retry_callback` only when the current managed Turn
+   advertises it and the original Pi callback route is still live. Never retry
+   an uncertain terminal Send to recover a callback.
+
+The POC owns one live Pi runtime and one branch epoch. Explicit session-tree
+navigation rotates the controller route; Pi shutdown removes the socket and
+invalidates that runtime's route. The durable inbox does not migrate callbacks
+from an old random controller identity into a new Pi runtime or branch. After a
+restart or branch change, use fresh List/Status and, for still-running terminal
+work, a fresh Watch. Do not expect the old route's callback to jump to the new
+conversation automatically.
+
+## Configuration, security, and storage
+
+The connector needs no project-specific configuration. These optional
+environment variables must be set **before** Pi starts and must contain
+absolute paths:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `AKK_PI_STORE_DIR` | `~/.agent-knock-knock/store` | Override AKK's shared Session, Turn, Watch, receipt, and callback-outbox Store. |
+| `AKK_PI_STATE_DIR` | `~/.pi/agent/akk` | Override the Pi connector's durable callback-inbox directory. |
+
+Example with isolated development state:
+
+```sh
+AKK_PI_STORE_DIR=/absolute/private/path/akk-store \
+AKK_PI_STATE_DIR=/absolute/private/path/pi-akk-state \
+pi
+```
+
+Security and retention boundaries:
+
+- Pi Extensions execute with the same OS privileges as Pi. Review local
+  connector source before loading it.
+- Each Pi runtime creates a random directory under the OS temporary directory
+  with mode `0700`. Its Host Profile and authenticated Unix socket use mode
+  `0600`, and the directory is removed on clean Pi shutdown.
+- The socket token is random and runtime-private. It is not written to the
+  durable inbox or accepted as a model/tool argument. The callback helper is
+  allowed only the socket and token environment variables it needs.
+- The persistent state directory is forced to `0700`; its
+  `callback-inbox.json` is written atomically with mode `0600`. It can retain
+  callback bodies, which may contain task results. The inbox is bounded to 256
+  entries and 64 MiB, pruning older delivered entries as new callbacks arrive.
+- The AKK Store is separate from the Pi inbox and may contain terminal/session
+  metadata and callback results. Use a dedicated private directory for either
+  override; do not point it at a shared or broad filesystem root.
+- The connector strips the supported GLM credential environment variables
+  from AKK relay/callback subprocess environments. Model credentials remain
+  Pi-owned and are never connector configuration.
+
+## Troubleshooting
+
+| Symptom | Check and recovery |
+| --- | --- |
+| `requires Pi 0.84.4` | Run `pi --version`, then reinstall the exact accepted release with `npm install -g @earendil-works/pi-coding-agent@0.84.4`. Newer Pi releases are not silently accepted by this POC. |
+| Pi never shows `AKK ready` | Confirm Node is at least 22.19, run `pi list`, update or reinstall `npm:@scotthuang/agent-knock-knock-pi@next`, and fully restart Pi. For a source checkout, follow the local-development build commands below. |
+| Module or `lib/index.js` not found | Remove and reinstall the npm package. For a source checkout, confirm Pi was given `connectors/pi`, not the repository root, and rebuild with the documented cwd-specific command. |
+| `/akk list` finds no terminal | Start authenticated `codex` or `claude` inside supported tmux/Herdr under the same OS user and leave the process running. The connector never launches it. |
+| Send says the target is ambiguous | Run a fresh `/akk list` and use the exact displayed selector for `/akk`, or the prefilled semantic ID from that row's current tool action. |
+| Callback does not appear immediately | Pi may be busy, so the callback is queued as a follow-up. Wait for the current turn, then use fresh List and Status. After a Pi restart or branch change, the old callback route is intentionally not migrated. |
+| Approval or cancellation says an interactive UI is required | Use Pi's interactive TUI. The POC deliberately blocks model-facing Approve/Cancel when `ctx.hasUI` is false. |
+| Approval changed before confirmation | Refresh Status and review the newly observed prompt. Do not reuse an old approval offer or blindly retry an interrupted approval. |
+| Callback socket/profile is unavailable | The owning Pi runtime may have stopped or its temporary private directory may have disappeared. Restart Pi to create a fresh route; recover existing work with List/Status rather than copying socket paths or tokens. |
+| State-directory or Store permission error | Both override variables must be absolute and point to dedicated real directories. Stop Pi, inspect ownership and contents, then choose a new private directory if the existing path is unsafe or incompatible. |
+| Updated connector still behaves like the old POC | Run `pi update npm:@scotthuang/agent-knock-knock-pi` and fully restart Pi. For a source checkout, re-run `npm ci` and the connector-specific build first. A running Extension is not hot-replaced. |
+| Send result is uncertain | Do not automatically send the task again. Inspect Status, the exact pane, or the attached Watch; retrying terminal input could duplicate work. |
+
+## Upgrade and uninstall
+
+Inspect and update the npm installation with Pi's package manager:
+
+```sh
+pi list
+pi update npm:@scotthuang/agent-knock-knock-pi
+```
+
+Keep Pi at exactly `0.84.4` until this README declares another accepted
+version. Do not use an unverified Pi upgrade as a connector update.
+
+Remove the npm package by its package identity:
+
+```sh
+pi remove npm:@scotthuang/agent-knock-knock-pi
+```
+
+`pi uninstall` is an alias for `pi remove`. Removing the package does not stop
+or delete Codex/Claude terminals, model credentials, `~/.pi/agent/akk`, or the
+AKK Store. Those durable directories are retained for inspection/recovery and
+should be reviewed separately before any manual deletion.
+
+## Development and verification
+
+To load a source checkout for one Pi run, build the connector explicitly:
+
+```sh
+AKK_REPO=/absolute/path/to/agent-knock-knock
+cd "$AKK_REPO"
+npm --prefix connectors/pi ci
+npm run pi:build
+pi -e "$AKK_REPO/connectors/pi"
+```
+
+The equivalent child-package build is:
+
+```sh
+cd "$AKK_REPO/connectors/pi"
+npm ci
+npm run build
+```
+
+Do not run a bare root `npm run build` and assume it built this connector. The
+unambiguous root command is `npm run pi:build`; inside `connectors/pi`, use
+`npm run build`. `pi -e` is temporary and changes no package settings. To
+persist a local source path, use `pi install "$AKK_REPO/connectors/pi"`; remove
+that same absolute source with `pi remove` when finished.
+
+From the repository root:
+
+```sh
+npm run pi:typecheck
+npm run pi:test:fast
+npm run pi:pack:check
+```
+
+Or from `connectors/pi`:
+
+```sh
+npm run typecheck
+npm run test:fast
+npm run pack:check
+```
+
+The [PR #266](https://github.com/scotthuang/agent-knock-knock/pull/266)
+acceptance record on 2026-08-30 included:
+
+- root fast tests: 1,462/1,462 passed;
+- connector fast tests: 23/23 passed;
+- root and connector TypeScript typechecks, architecture/evidence validators,
+  and connector package dry-run passed;
+- a real Claude Code 2.1.251 flow covering Send, approval callback, Pi native
+  approval, exact marker execution, completion callback, and delivered Status;
+- a real Codex flow in a clean isolated environment covering native
+  `agent_accepted`, exact marker execution, Unix Socket callback into Pi, and
+  durable high-confidence delivered Status.
+
+These are POC acceptance results, not a promise of compatibility with every
+future Pi, Codex, Claude Code, tmux, or Herdr release. Version
+`0.1.0-poc.1` is the first npm prerelease and is distributed through the
+`next` dist-tag; it does not change the AKK main package or ClawHub artifact.
+
+## Deliberate POC limits
+
+The POC intentionally does not provide a standalone Supervisor, multi-Host
+leader election, cross-session or cross-branch callback migration, remote
+terminal access, Windows named pipes, configuration-driven auto-approval, or
+coding-agent `--yolo` adaptation. It controls only the Codex and Claude Code
+terminal surfaces already supported by AKK.

package/lib/callback-helper.d.ts

@@ -0,0 +1,14 @@
+import type { CallbackAcknowledgement } from "./routes.js";
+export interface CallbackHelperArguments {
+    readonly controllerId: string;
+    readonly deliveryId: string;
+    readonly messageId: string;
+    readonly idempotencyKey: string;
+}
+/** Execute the Host Profile callback helper without putting authority in argv. */
+export declare function runCallbackHelper(options: {
+    readonly arguments: CallbackHelperArguments;
+    readonly body: string;
+    readonly environment: Readonly<NodeJS.ProcessEnv>;
+}): Promise<CallbackAcknowledgement>;
+export declare function parseCallbackHelperArguments(argv: readonly string[]): CallbackHelperArguments;

package/lib/callback-helper.js

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { CALLBACK_MAX_BODY_BYTES, CALLBACK_SOCKET_ENV, CALLBACK_TOKEN_ENV, sendCallbackOverIpc, } from "./ipc.js";
+/** Execute the Host Profile callback helper without putting authority in argv. */
+export async function runCallbackHelper(options) {
+    if (Buffer.byteLength(options.body, "utf8") > CALLBACK_MAX_BODY_BYTES) {
+        throw new Error("Pi callback body exceeded its limit");
+    }
+    const socketPath = requiredEnvironment(options.environment[CALLBACK_SOCKET_ENV], CALLBACK_SOCKET_ENV);
+    const token = requiredEnvironment(options.environment[CALLBACK_TOKEN_ENV], CALLBACK_TOKEN_ENV);
+    const response = await sendCallbackOverIpc({
+        socketPath,
+        request: {
+            ...options.arguments,
+            body: options.body,
+            token,
+        },
+    });
+    if (response.deliveryId !== options.arguments.deliveryId ||
+        response.messageId !== options.arguments.messageId) {
+        throw new Error("Pi callback IPC acknowledgement identity did not match");
+    }
+    return {
+        request: {
+            delivery_id: response.deliveryId,
+            message_id: response.messageId,
+        },
+        result: {
+            status: response.status,
+            ...(response.acceptanceId ? { acceptance_id: response.acceptanceId } : {}),
+            ...(response.errorCode ? { error_code: response.errorCode } : {}),
+        },
+    };
+}
+export function parseCallbackHelperArguments(argv) {
+    const values = new Map();
+    const supported = new Set([
+        "--controller-id",
+        "--delivery-id",
+        "--message-id",
+        "--idempotency-key",
+    ]);
+    if (argv.length % 2 !== 0) {
+        throw new Error("invalid Pi AKK callback helper arguments");
+    }
+    for (let index = 0; index < argv.length; index += 2) {
+        const flag = argv[index];
+        const value = argv[index + 1];
+        if (!flag || !supported.has(flag) || !value || values.has(flag)) {
+            throw new Error("invalid Pi AKK callback helper arguments");
+        }
+        values.set(flag, value);
+    }
+    return {
+        controllerId: requiredArgument(values, "--controller-id"),
+        deliveryId: requiredArgument(values, "--delivery-id"),
+        messageId: requiredArgument(values, "--message-id"),
+        idempotencyKey: requiredArgument(values, "--idempotency-key"),
+    };
+}
+async function main() {
+    let parsed;
+    try {
+        parsed = parseCallbackHelperArguments(process.argv.slice(2));
+        const body = await readStandardInput();
+        const acknowledgement = await runCallbackHelper({
+            arguments: parsed,
+            body,
+            environment: process.env,
+        });
+        process.stdout.write(`${JSON.stringify(acknowledgement)}\n`);
+    }
+    catch {
+        if (parsed) {
+            const fallback = {
+                request: {
+                    delivery_id: parsed.deliveryId,
+                    message_id: parsed.messageId,
+                },
+                result: {
+                    status: "retry",
+                    error_code: "callback_ipc_unavailable",
+                },
+            };
+            process.stdout.write(`${JSON.stringify(fallback)}\n`);
+            return;
+        }
+        process.stderr.write("agent-knock-knock Pi callback helper configuration is invalid\n");
+        process.exitCode = 2;
+    }
+}
+async function readStandardInput() {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > CALLBACK_MAX_BODY_BYTES) {
+            throw new Error("Pi callback body exceeded its limit");
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks, bytes).toString("utf8");
+}
+function requiredArgument(values, flag) {
+    const value = values.get(flag);
+    if (!value || value.trim() !== value || /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new Error(`missing ${flag}`);
+    }
+    return value;
+}
+function requiredEnvironment(value, name) {
+    if (!value || value.trim() !== value || /[\u0000\r\n]/u.test(value)) {
+        throw new Error(`missing ${name}`);
+    }
+    return value;
+}
+if (isDirectExecution()) {
+    void main();
+}
+function isDirectExecution() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=callback-helper.js.map

package/lib/callback-helper.js.map

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

package/lib/callback-inbox.d.ts

@@ -0,0 +1,40 @@
+import type { CallbackRequest } from "./routes.js";
+export type CallbackInboxState = "pending" | "delivered";
+export interface CallbackInboxEntry extends CallbackRequest {
+    readonly fingerprint: string;
+    readonly acceptanceId: string;
+    readonly state: CallbackInboxState;
+    readonly acceptedAt: string;
+    readonly deliveredAt?: string;
+}
+export type CallbackInboxAdmission = {
+    readonly disposition: "admitted" | "duplicate";
+    readonly entry: CallbackInboxEntry;
+} | {
+    readonly disposition: "collision";
+};
+/**
+ * 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 declare class CallbackInbox {
+    private entries;
+    private transactionTail;
+    private active;
+    private readonly filePath;
+    private readonly maxEntries;
+    private readonly maxFileBytes;
+    constructor(options: {
+        readonly filePath: string;
+        readonly maxEntries?: number;
+        readonly maxFileBytes?: number;
+    });
+    admit(request: CallbackRequest): Promise<CallbackInboxAdmission>;
+    markDelivered(entry: CallbackInboxEntry): Promise<CallbackInboxEntry>;
+    listPending(controllerId?: string): Promise<readonly CallbackInboxEntry[]>;
+    close(): Promise<void>;
+    private withTransaction;
+}