@geohar/unbien-durable 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 George Harker
+
+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

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @geohar/unbien-durable
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [pi-durable](https://github.com/earendil-works/pi) agent host on the
+[un-bien](https://github.com/georgeharker/un-bien) mesh and relay. The
+Un Bien app talks to a durable conversation exactly as it talks to a pi
+session: the same transcript, live streaming, tool cards, model and thinking
+controls, and pairing.
+
+Durable conversations have stable ids and survive restarts, so the app
+reconnects to the same room and its history after the host restarts.
+
+```bash
+npm install -g @geohar/unbien-durable
+```
+
+## Running the host
+
+```bash
+unbien-durable [--cwd <dir>] [--name <agent-name>] [--relay <url>]
+               [--db <path>] [--model <provider/model>]
+               [--thinking <level>] [--no-pairing-qr]
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--cwd` | Working directory of the conversation (default: the current directory) |
+| `--name` | Name shown in the app and on the mesh (default: `durable`) |
+| `--relay` | Relay URL (default: the configured un-bien relay) |
+| `--db` | JSONL storage directory (default: `~/.local/state/un-bien/durable/session`) |
+| `--model` | `provider/modelId` for a new conversation |
+| `--thinking` | Thinking level a conversation still at `off` starts at (default: `medium`, clamped to the model); `off` keeps pi-durable's default |
+| `--no-pairing-qr` | Don't mint the rotating pairing QR; pair with `unbien pair-token` instead |
+
+Provider API keys come from the environment, as for pi (`ANTHROPIC_API_KEY`,
+`OPENAI_API_KEY`, `OLLAMA_API_KEY`, …). `UNBIEN_NO_PAIRING_QR` and
+`UNBIEN_DURABLE_THINKING` match the flags.
+
+## As a library
+
+The package also exports the binding itself, for hosts that compose their own
+harness (models, tools, extensions):
+
+- `DurableBridge`: serves one conversation over the relay. Pass the harness's
+  `models` to enable the app's model, thinking, rename and queue controls.
+- `DurableSessionPort` / `DurableSessionControl` / `DurableAgentConfig`: the
+  un-bien core ports over a durable `Conversation`.
+- `ConversationViewSource` / `ViewTranslator`: the conversation view as pi's
+  event plane.
+- `createUnBienDurableExtension`: the mesh tools and `launch_pi_task`.
+
+## Requirements
+
+Node 22.19 or later. Built on `@earendil-works/pi-durable` 1.5.

package/dist/agent_config.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Durable binding's AgentConfigPort: the app's model / thinking-level /
+ * session-name / queue verbs over a durable Conversation.
+ *
+ *   getModelState / listModels / setModel / setThinkingLevel
+ *     → `conversation.agent()` / `configure()` against the harness's model
+ *       registry. setModel accepts only models with credentials
+ *       (`models.getAvailable()`), the same answer pi's registry gives, and
+ *       like pi clamps the thinking level to what the new model supports;
+ *       setThinkingLevel clamps to the current model. The agent state is
+ *       durable, so both survive restarts.
+ *   setSessionName → the bridge's rename (room name, live confirmation,
+ *     persisted record).
+ *   clearQueue → aborts each queued steer / follow-up submission in
+ *     `pi.inbox`; resolves to the text of those withdrawn.
+ *
+ * There is no command registry, so `isKnownSlash` is absent: slash tokens
+ * pass to the agent as text.
+ */
+import type { Context } from "@earendil-works/chord";
+import { type Models } from "@earendil-works/pi-ai/models";
+import type { Conversation, Harness, InboxState } from "@earendil-works/pi-durable";
+import type { AgentConfigPort, ThinkingLevel, WireModel } from "@geohar/un-bien/core";
+export interface DurableAgentConfigOptions {
+    /** The conversation served now (the bridge retargets it). */
+    conversation(): Conversation;
+    harness: Harness;
+    models: Models;
+    context: Context;
+    /** The conversation's queue, as of the latest view value. */
+    inbox(): InboxState | undefined;
+    /** Rename the served session (the bridge's room + record). */
+    rename(name: string): Promise<void>;
+}
+export declare class DurableAgentConfig implements AgentConfigPort {
+    private readonly opts;
+    constructor(opts: DurableAgentConfigOptions);
+    getModelState(): Promise<{
+        model?: {
+            id: string;
+            provider: string;
+        };
+        thinkingLevel?: string;
+    }>;
+    listModels(): Promise<{
+        models: WireModel[];
+        current?: WireModel;
+    }>;
+    setModel(provider: string, modelId: string): Promise<WireModel>;
+    setThinkingLevel(level: ThinkingLevel): Promise<void>;
+    setSessionName(name: string): Promise<void>;
+    clearQueue(): Promise<{
+        steering: string[];
+        followUp: string[];
+    }>;
+}

package/dist/agent_config.js

@@ -0,0 +1,92 @@
+import { clampThinkingLevel } from "@earendil-works/pi-ai/models";
+import { wireFromModel } from "@geohar/un-bien/durable";
+export class DurableAgentConfig {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async getModelState() {
+        const agent = await this.opts.conversation().agent(this.opts.context);
+        return {
+            ...(agent.model
+                ? { model: { id: agent.model.modelId, provider: agent.model.provider } }
+                : {}),
+            thinkingLevel: agent.thinkingLevel,
+        };
+    }
+    async listModels() {
+        const [available, agent] = await Promise.all([
+            this.opts.models.getAvailable(),
+            this.opts.conversation().agent(this.opts.context),
+        ]);
+        const current = agent.model
+            ? this.opts.models.getModel(agent.model.provider, agent.model.modelId)
+            : undefined;
+        return {
+            models: available.map(wireFromModel),
+            current: current ? wireFromModel(current) : undefined,
+        };
+    }
+    async setModel(provider, modelId) {
+        const model = this.opts.models.getModel(provider, modelId);
+        if (!model)
+            throw new Error(`model "${provider}/${modelId}" not in registry`);
+        const available = await this.opts.models.getAvailable(provider);
+        if (!available.some((m) => m.id === modelId))
+            throw new Error("no auth configured for this model");
+        const conversation = this.opts.conversation();
+        const agent = await conversation.agent(this.opts.context);
+        const thinkingLevel = clampThinkingLevel(model, agent.thinkingLevel);
+        await conversation.configure({
+            model: { provider, modelId },
+            ...(thinkingLevel !== agent.thinkingLevel ? { thinkingLevel } : {}),
+        }, this.opts.context);
+        return wireFromModel(model);
+    }
+    async setThinkingLevel(level) {
+        const conversation = this.opts.conversation();
+        const agent = await conversation.agent(this.opts.context);
+        const model = agent.model
+            ? this.opts.models.getModel(agent.model.provider, agent.model.modelId)
+            : undefined;
+        const target = model
+            ? clampThinkingLevel(model, level)
+            : level;
+        await conversation.configure({ thinkingLevel: target }, this.opts.context);
+    }
+    async setSessionName(name) {
+        await this.opts.rename(name);
+    }
+    async clearQueue() {
+        const cleared = { steering: [], followUp: [] };
+        for (const item of this.opts.inbox()?.items ?? []) {
+            if (item.mode === "write")
+                continue;
+            const submission = await this.opts.harness.submission(item.id, this.opts.context);
+            if (!submission)
+                continue;
+            // "already_placed": the run took it first; "settled": already done.
+            if ((await submission.abort(this.opts.context)) !== "aborted")
+                continue;
+            const text = inputText(item.content);
+            if (item.mode === "steer")
+                cleared.steering.push(text);
+            else
+                cleared.followUp.push(text);
+        }
+        return cleared;
+    }
+}
+/** The text of a queued input: a string, or its text blocks joined. */
+function inputText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((block) => block?.type === "text" &&
+        typeof block.text === "string")
+        .map((block) => block.text)
+        .join("\n");
+}
+//# sourceMappingURL=agent_config.js.map

package/dist/agent_config.js.map

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

package/dist/bridge.d.ts

@@ -0,0 +1,175 @@
+import type { Context } from "@earendil-works/chord";
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
+import type { Models } from "@earendil-works/pi-ai/models";
+import type { Conversation, Harness } from "@earendil-works/pi-durable";
+import { RelayClient, type Ed25519Keypair } from "@geohar/un-bien/durable";
+import type { NotifyLevel } from "@geohar/un-bien/core";
+export interface DurableBridgeOptions {
+    harness: Harness;
+    context: Context;
+    /** http(s):// relay URL (converted to ws(s):// at the boundary). */
+    relayUrl: string;
+    /** Display name for room_meta + pair_ok. */
+    displayName: string;
+    /** Machine name the app records (defaults to os.hostname()). Distinct for
+     *  the durable host so the app lists it as its own machine, not the Mac. */
+    machineName?: string;
+    /** The conversations' working directory. */
+    cwd: string;
+    /** Pairing QR rotation cadence in ms (default: the 60s token TTL, so the
+     *  invite renews exactly as the previous token expires). Tests shrink it
+     *  to observe rotation in real time. */
+    pairingRotationMs?: number;
+    /** Suppress the auto-minted rotating pairing QR (no user gesture minted
+     *  it — headless hosts pair via the CLI instead). Default: false, the
+     *  rotation mints as before. */
+    pairingQr?: boolean;
+    /** Relay client factory — tests inject a fake; production gets the real
+     *  RelayClient. */
+    createRelay?: (wsUrl: string, keypair: Ed25519Keypair) => RelayClient;
+    /** The harness's model registry. With it, each attached conversation
+     *  still at thinking level "off" (pi-durable's default) is raised to
+     *  `thinkingLevel`, clamped to its model — see thinking.ts. */
+    models?: Models;
+    /** Default thinking level (default "medium", pi's). "off" disables. */
+    thinkingLevel?: ModelThinkingLevel;
+    /** Host log surface (notify + async failures). */
+    log(message: string, level?: NotifyLevel): void;
+    /** Graceful host shutdown (terminate frame) — close bridge + harness. */
+    shutdownHost(): Promise<void>;
+}
+export declare class DurableBridge {
+    private readonly opts;
+    private relay;
+    private readonly activePeers;
+    private keypair;
+    private conversation;
+    private mirror;
+    private busy;
+    private port;
+    private control;
+    private events;
+    private rpcEnvelope;
+    private myRoomId;
+    private sessionStartedAt;
+    private reconnectTimer;
+    private reconnectAttempt;
+    private stopped;
+    private pairingRotationActive;
+    private pairingRotationTimer;
+    /** The last minted rotating invite (null when paired/not rotating) —
+     *  surfaced via currentPairingInvite() for host-side web pages. */
+    private lastPairingInvite;
+    /** The served session's display name: the newest rename recorded in the
+     *  conversation, else the host's displayName. */
+    private sessionName;
+    private agentConfig;
+    constructor(opts: DurableBridgeOptions);
+    /** The currently served conversation (stable id across restarts). */
+    get currentConversation(): Conversation;
+    /** Live busy flag (run in flight) — the port's `streaming`. */
+    get isBusy(): boolean;
+    /** Attach to a conversation: port + control + watch + event fanout. */
+    attach(conversation: Conversation): Promise<void>;
+    /** Connect the relay + announce this conversation's room. */
+    start(): Promise<void>;
+    /** Full teardown (host shutdown / retarget). */
+    stop(): Promise<void>;
+    /**
+     * Session replacement WITHOUT replacement machinery: flush a
+     * session_shutdown to the old room, stop everything, attach to the new
+     * conversation, reconnect under its room. The app drops the old
+     * conversation on the new hello (changed sessionId), exactly as it does
+     * for pi.
+     */
+    retarget(conversation: Conversation): Promise<void>;
+    private buildPort;
+    private buildControl;
+    private connectRelay;
+    private scheduleReconnect;
+    /** Fail-closed signed allow-list push (the relay refuses rooms whose
+     *  owners are not listed). Same single-signer path as the pi extension. */
+    private pushPairingAllowList;
+    /**
+     * The auto-listener: pair_request from new devices, reconnect attach for
+     * known peers, unknown-peer refusal. The durable port of the pi
+     * extension's listener — no listener-authority generations (a stopped
+     * bridge is `this.relay !== relay`, checked directly).
+     */
+    private installAutoListener;
+    private handlePairRequest;
+    /**
+     * The startup pairing invite: while the machine has no paired peers, the
+     * bridge ITSELF mints the rotating QR on the same qrSession the
+     * pair_request handler consumes from — one process issues AND validates
+     * the token, so a scan can never hit "token was not issued by this host"
+     * (the failure mode of minting in a separate CLI process). Armed on every
+     * successful relay connect (startup + reconnects); the first tick reads
+     * peers.json and retires silently when a peer already exists, so a
+     * revoked-then-restarted host re-arms on its next start().
+     */
+    private armPairingRotation;
+    /** Fire-and-forget one rotation step: a rejection (listPeers on a wedged
+     *  broker socket, …) logs + retires the rotation instead of escaping as
+     *  an unhandled rejection — the rotation re-arms on the next successful
+     *  relay connect. */
+    private tickPairingRotation;
+    /** One rotation step: retire when peers exist, otherwise mint + log a
+     *  fresh invite and schedule the next tick. */
+    private rotatePairingQR;
+    /** Cancel the rotation (a peer paired / teardown). No qrSession.clear()
+     *  here: the outstanding token either was just consumed by the pairing
+     *  handshake or dies with the process — consumption is same-process by
+     *  design. */
+    private stopPairingRotation;
+    /** The CURRENT pairing invite as a deep-link URI — what a /pair web page
+     *  renders as a tappable link. null when not rotating (paired already, or
+     *  rotation stopped). Updated on every rotation tick. */
+    currentPairingInvite(): string | null;
+    /** Ask attached app peers to authorize: ONE live toast
+     *  (extension_ui_request notify) is the visible channel. An authorize
+     *  pending expires in minutes, so nothing replays it; a late peer gets a
+     *  fresh mint when the model calls the tool again. The request is also
+     *  recorded as a hidden app entry (customType "un-bien:auth-required",
+     *  display:false), kept for the record and out of model context.
+     *
+     *  `message` is the elicit text and names the real upstream server;
+     *  `server` is the caller's label (the combiner bridge, say), kept in
+     *  details. `url` is appended unless the message already carries it, and
+     *  may be empty for a prompt with nothing to open. */
+    sendAuthorizeCard(server: string, url: string, message: string): Promise<void>;
+    /** Rename the served session: record it in the conversation (a hidden app
+     *  entry, read back at attach), then confirm it live as pi does — the
+     *  session_info evt to attached apps and room_meta_update so the relay
+     *  pushes the name to room subscribers. */
+    private renameSession;
+    /** Record a run that ended without an answer as a display app entry, so
+     *  the app shows why (live, and on replay). `nothing_to_answer` (a
+     *  continue with nothing pending) is not a failure anyone needs to see. */
+    private recordRunFailure;
+    /** Mint a FRESH pairing invite on demand — for host-side pairing pages
+     *  (/pair) so a SECOND device can be added after the rotation retired, or
+     *  an operator can open pairing mode without a restart. One process mints
+     *  + consumes (this bridge), so the token race is structurally excluded.
+     *  Multi-device safe: adding a peer appends to peers.json; the page's
+     *  caller gates availability (enable/disable toggle). */
+    forcePairingInvite(): string | null;
+    private emitPairOk;
+    /** un-plane error reply, correlated to the request id when present.
+     *  Same best-effort wire as sendEnvelope — a relay hiccup mid-reply must
+     *  not throw into the fire-and-forget ub dispatch. */
+    private sendUbError;
+    private sendInner;
+    /** Attach (or re-attach) an owner channel and say hello. */
+    private attachOwner;
+    private buildRpcDeps;
+    /** Envelope-carried pi rpc command dispatch (the shared handlers). */
+    private routeRpc;
+    /** un-bien plane: session_sync (minimal ack) + session_fork/
+   *  session_navigate + terminate. */
+    private routeUnBienPlane;
+    /** Stock ClientMessage switch: ping/pong + cancel. */
+    private routeStock;
+    private broadcast;
+    private broadcastFlushed;
+}