@geohar/unbien-durable 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @geohar/unbien-durable — public surface: the durable binding's ports,
+ * registrar, event source, extension bundle, launch port, and bridge.
+ * `host.ts` is the CLI entry (bin: unbien-durable) and stays out of the
+ * library surface.
+ */
+export { DurableSessionControl, DurableSessionPort, DurableTranscriptMirror, } from "./port.js";
+export { DurableToolRegistrar } from "./registrar.js";
+export { ConversationViewSource, } from "./event_source.js";
+export { ViewTranslator } from "./view_translator.js";
+export { entryIdOf, toWire } from "./mirror.js";
+export { createUnBienDurableExtension, } from "./extension.js";
+export { HeadlessPiLaunch, HeadlessPiSession, } from "./pi_launch.js";
+export { createLaunchWaitQuitTool, } from "./launch_wait_quit.js";
+export { DurableBridge } from "./bridge.js";
+export { ollamaCloudProvider } from "./ollama_cloud.js";
+export { DEFAULT_THINKING_LEVEL, ensureThinkingLevel, parseThinkingLevel, } from "./thinking.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,uBAAuB,GAGxB,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EACL,sBAAsB,GAEvB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,cAAc,EAA8B,MAAM,sBAAsB,CAAA;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EACL,4BAA4B,GAE7B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,wBAAwB,GAEzB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,aAAa,EAA6B,MAAM,aAAa,CAAA;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,eAAe,CAAA"}

package/dist/launch_wait_quit.d.ts

@@ -0,0 +1,12 @@
+import { type ToolRegistration } from "@earendil-works/pi-durable";
+import type { HeadlessLaunchPort } from "@geohar/un-bien/core";
+import type { MeshInbox, MeshNode } from "@geohar/un-bien/durable";
+export interface LaunchWaitQuitDeps {
+    /** The headless launch port (HeadlessPiLaunch). */
+    launch: HeadlessLaunchPort;
+    /** The HOST's mesh node — the tool sends from the host's own peer. */
+    getMeshNode(): MeshNode | null;
+    /** The host's inbound mesh inbox (correlated reply waits). */
+    getInbox(): MeshInbox;
+}
+export declare function createLaunchWaitQuitTool(deps: LaunchWaitQuitDeps): ToolRegistration;

package/dist/launch_wait_quit.js

@@ -0,0 +1,136 @@
+/**
+ * `launch_pi_task` — the durable binding's launch-wait-quit tool, and the
+ * ONE place the two bindings meet at runtime.
+ *
+ * Contract (documented for the model in the description):
+ *   1. fire up a headless pi-coding-agent session in the target cwd (a
+ *      full interactive-equivalent pi: coding tools, its own model);
+ *   2. it joins the un-bien UDS mesh under a scoped name minted per call;
+ *   3. the task body is agent_sent to it as a MESH message — the launched
+ *      session's own model handles it in its own turn and replies with
+ *      `re=<send id>`;
+ *   4. the reply lands in the host's mesh inbox and is returned as the
+ *      tool result;
+ *   5. the launched session is torn down in a finally — a failed task never
+ *      leaks a live pi peer.
+ *
+ * Why mesh messages and not a direct prompt: the launched session is an
+ * independent agent (its own harness, its own model config); the mesh
+ * request/reply correlation gives both sides durable delivery semantics and
+ * the same observability every other peer sees.
+ */
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-durable";
+/** How long to wait for the peer's correlated reply (default 5 min — the
+ *  launched agent runs a full multi-turn task with tools). */
+const DEFAULT_REPLY_TIMEOUT_MS = 300_000;
+/** Broker ACK deadline for the task delivery. */
+const SEND_ACK_TIMEOUT_MS = 5_000;
+export function createLaunchWaitQuitTool(deps) {
+    return defineTool({
+        name: "launch_pi_task",
+        description: "Launch a short-lived headless pi coding-agent session in a directory, " +
+            "send it a task over the agent mesh, wait for its reply, then shut it " +
+            "down. The launched session is a full pi agent (coding tools, its own " +
+            "model) joined to the local UDS mesh under a per-call scoped name — " +
+            "use it for ad-hoc coding firepower you don't want in your own " +
+            "conversation. The task must be self-contained: the peer has no " +
+            "access to this conversation's context. The target directory must " +
+            "have un-bien configured (auto-start) and the un-bien extension " +
+            "discoverable by pi there; a reply that never comes surfaces as a " +
+            "timeout, not a silent success.",
+        parameters: Type.Object({
+            task: Type.String({
+                description: "The task to send the launched agent, as a self-contained " +
+                    "instruction (its reply comes back as this tool's result).",
+            }),
+            cwd: Type.Optional(Type.String({
+                description: "Directory to launch in. Default: this host's working directory.",
+            })),
+            timeout_ms: Type.Optional(Type.Number({
+                description: "Max ms to wait for the reply (default 300000 = 5 minutes).",
+            })),
+        }),
+        execute: async (args, _api, _context) => {
+            const meshNode = deps.getMeshNode();
+            if (!meshNode) {
+                return {
+                    output: [
+                        {
+                            type: "text",
+                            text: "Not on the agent mesh — the host must join the mesh before launching pi tasks.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const cwd = args.cwd ?? process.cwd();
+            const replyTimeout = typeof args.timeout_ms === "number" && args.timeout_ms > 0
+                ? args.timeout_ms
+                : DEFAULT_REPLY_TIMEOUT_MS;
+            // Scoped name: per-call unique, broker-safe (hyphens, no slashes —
+            // the broker's name grammar rejects path separators).
+            const name = `pi-task-${crypto.randomUUID().slice(0, 8)}`;
+            const peer = meshNode.peer();
+            const session = await deps.launch.launchHeadless({ cwd, name });
+            try {
+                await session.joinMeshUnderName();
+                const { address } = await session.awaitReady();
+                const ack = await peer.sendWithAck(address, { type: "pi_task", task: args.task }, null, SEND_ACK_TIMEOUT_MS);
+                if (ack.status !== "received") {
+                    return {
+                        output: [
+                            {
+                                type: "text",
+                                text: `Task delivery to "${address}" failed (${ack.status}${ack.error ? `: ${ack.error}` : ""}). The session was shut down.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const reply = await deps
+                    .getInbox()
+                    .wait({ re: ack.id }, replyTimeout, { interruptOnUnmatched: true });
+                if (!reply) {
+                    return {
+                        output: [
+                            {
+                                type: "text",
+                                text: `No reply within ${replyTimeout}ms (send id ${ack.id}). ` +
+                                    `The session was shut down; if the reply arrives later it ` +
+                                    `lands in this host's mesh inbox.`,
+                            },
+                        ],
+                    };
+                }
+                if (reply.re !== ack.id) {
+                    // Early interrupt — an uncorrelated message arrived while waiting.
+                    return {
+                        output: [
+                            {
+                                type: "text",
+                                text: `Early interrupt while awaiting the task reply: ${reply.from} ` +
+                                    `sent ${reply.id} (re=${reply.re}). Handle it, then re-issue ` +
+                                    `launch_pi_task. The launched session was shut down.`,
+                            },
+                        ],
+                    };
+                }
+                const text = typeof reply.body === "string"
+                    ? reply.body
+                    : JSON.stringify(reply.body);
+                // SAFETY: a mesh reply body is a JSON tree by wire contract (the
+                // envelope codec only carries JSON); the inbox types it `unknown`
+                // only to stay harness-neutral.
+                return {
+                    output: [{ type: "text", text }],
+                    details: reply.body,
+                };
+            }
+            finally {
+                await session.tearDown();
+            }
+        },
+    });
+}
+//# sourceMappingURL=launch_wait_quit.js.map

package/dist/launch_wait_quit.js.map

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

package/dist/mesh_delivery.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The mesh → inbox feed: inbound mesh envelopes land in the MeshInbox (the
+ * model's pull/wait surface behind launch_pi_task / mesh_get_message /
+ * mesh_list_messages / mesh_wait_message).
+ *
+ * The durable analog of the pi extension's `peer.onMessage` →
+ * `_deliverMeshMessageToAgent` wiring (extension/src/commands/lifecycle.ts):
+ * broker system events (peer_joined / peer_left) and broker control frames
+ * are filtered, and every REAL agent-to-agent envelope is stored in the
+ * inbox. Replies arrive here already correlation-stamped by the sender
+ * (`env.re` = the outbound envelope id), so `launch_pi_task`'s
+ * `inbox.wait({ re: ack.id })` resolves the moment the launched peer's reply
+ * is delivered.
+ *
+ * Difference from the pi binding, by design: pi ALSO nudges the model (the
+ * drain pushes the message via pi.sendMessage as a custom message). The
+ * durable host has no push surface — the conversation is pull/wait only.
+ * A message that arrives while the model is between turns sits in the inbox
+ * until the model pulls it (mesh_list_messages) or a correlated wait
+ * (launch_pi_task, mesh_wait_message) returns it.
+ */
+import type { MeshInbox, MeshNode } from "@geohar/un-bien/durable";
+/**
+ * Subscribe `meshNode`'s message delivery into `inbox`. Idempotent per
+ * subscription (MeshNode.onMessage returns an unsubscribe the host never
+ * needs — the node's close() drops it).
+ */
+export declare function wireMeshInbox(meshNode: MeshNode, inbox: MeshInbox): void;

package/dist/mesh_delivery.js

@@ -0,0 +1,31 @@
+/**
+ * Subscribe `meshNode`'s message delivery into `inbox`. Idempotent per
+ * subscription (MeshNode.onMessage returns an unsubscribe the host never
+ * needs — the node's close() drops it).
+ */
+export function wireMeshInbox(meshNode, inbox) {
+    meshNode.onMessage((env) => {
+        const body = env.body;
+        // Broker system events: the roster self-heals — list_peers (the mesh
+        // tool + the host's peer inventory) queries the broker live, so there
+        // is no cached count to refresh on the durable host (the pi extension
+        // refreshes a session peer-count badge here; we have no badge).
+        if (body && (body.type === "peer_joined" || body.type === "peer_left"))
+            return;
+        if (env.from === "broker")
+            return; // other broker control messages — ignore
+        // Real agent-to-agent message: store for pull/wait. `deliveredAt`
+        // stays null — the durable binding has no pi.sendMessage push, so
+        // "delivered" means "in the inbox", which `sentAt` already records.
+        inbox.add({
+            id: env.id,
+            from: env.from,
+            to: meshNode.address(),
+            body: env.body,
+            re: env.re,
+            sentAt: Date.now(),
+            deliveredAt: null,
+        });
+    });
+}
+//# sourceMappingURL=mesh_delivery.js.map

package/dist/mesh_delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh_delivery.js","sourceRoot":"","sources":["../src/mesh_delivery.ts"],"names":[],"mappings":"AAuBA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,QAAkB,EAAE,KAAgB;IAChE,QAAQ,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE;QACzB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAgC,CAAA;QACjD,qEAAqE;QACrE,sEAAsE;QACtE,sEAAsE;QACtE,gEAAgE;QAChE,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,aAAa,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC;YACpE,OAAM;QACR,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAM,CAAC,yCAAyC;QAE3E,kEAAkE;QAClE,kEAAkE;QAClE,oEAAoE;QACpE,KAAK,CAAC,GAAG,CAAC;YACR,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,EAAE,EAAE,QAAQ,CAAC,OAAO,EAAE;YACtB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE;YAClB,WAAW,EAAE,IAAI;SAClB,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/mirror.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Synchronous view of the durable transcript, in pi's `SessionEntry` wire
+ * shapes, so the app's entry replay (get_entries) renders a durable
+ * conversation exactly as it renders a pi session.
+ *
+ * Fed by the ConversationViewSource with every entry the conversation's
+ * ConversationTranscript holds (the watch window plus the pages loaded
+ * before it), in entry-id order; `ingest` ignores ids it already has, so
+ * the whole held transcript can be offered on every view value.
+ *
+ * Mapping (durable EntryRecord → pi entry):
+ *   pi.user / pi.assistant / pi.tool-result (and any kind carrying model
+ *     messages) → one `message` entry per model message, unchanged: pi-ai
+ *     messages are pi's own, so thinking, toolCall, image, and toolResult
+ *     blocks (with `details`, `isError`) keep their types. The first message
+ *     keeps the entry id; later ones are `<id>.<n>`.
+ *   pi.compaction → `compaction` {summary, firstKeptEntryId, tokensBefore}:
+ *     the summary unwrapped from its `<summary>` user message.
+ *   pi.reset → `custom_message` customType `un-bien:durable-reset`
+ *     (display), carrying the handoff text when there is one.
+ *   un-bien.app → `custom_message` with the app entry's customType,
+ *     content, display, and details.
+ *   anything else (pi.system, extension bookkeeping) → a typed stub
+ *     `{type: kind}`, which the app skips like pi entry types it doesn't
+ *     render.
+ *
+ * Wire ids are stringified durable ids (the app keys entries by string and
+ * pages with `since: <id>`); `entryIdOf` parses one back, suffix and all.
+ * Timestamps come from the entry's first model message; entries without one
+ * take the time this process first saw them.
+ */
+import type { EntryId, EntryRecord } from "@earendil-works/pi-durable";
+import type { EntriesPage, EntryRange } from "@geohar/un-bien/core";
+/** The app-entry kind the bridge commits custom entries under. */
+export declare const UN_BIEN_APP_KIND = "un-bien.app";
+/** customType of a context reset in the app's transcript. */
+export declare const RESET_CUSTOM_TYPE = "un-bien:durable-reset";
+/** The durable entry id a wire id names (`"12"` and `"12.1"` → 12). */
+export declare function entryIdOf(wireId: string): EntryId | undefined;
+export declare class DurableTranscriptMirror {
+    private readonly wire;
+    private newest;
+    /** Add the records newer than every held one; returns those added. */
+    ingest(records: readonly EntryRecord[]): EntryRecord[];
+    /** The current leaf id (the newest wire entry). */
+    get leafId(): string | null;
+    page(range?: EntryRange): EntriesPage;
+}
+type WireEntry = {
+    id: string;
+    type: string;
+    timestamp: string;
+} & Record<string, unknown>;
+/** Map one durable entry to its pi wire entries (without parentId). */
+export declare function toWire(record: EntryRecord): WireEntry[];
+export {};

package/dist/mirror.js

@@ -0,0 +1,136 @@
+/** The app-entry kind the bridge commits custom entries under. */
+export const UN_BIEN_APP_KIND = "un-bien.app";
+/** customType of a context reset in the app's transcript. */
+export const RESET_CUSTOM_TYPE = "un-bien:durable-reset";
+const SUMMARY_PREFIX = "The conversation history before this point was compacted into the following summary:\n\n<summary>\n";
+const SUMMARY_SUFFIX = "\n</summary>";
+/** The durable entry id a wire id names (`"12"` and `"12.1"` → 12). */
+export function entryIdOf(wireId) {
+    const match = /^(\d+)(?:\.\d+)?$/.exec(wireId);
+    return match ? Number(match[1]) : undefined;
+}
+export class DurableTranscriptMirror {
+    wire = [];
+    newest;
+    /** Add the records newer than every held one; returns those added. */
+    ingest(records) {
+        const added = [];
+        for (const record of records) {
+            if (this.newest !== undefined && record.id <= this.newest)
+                continue;
+            this.newest = record.id;
+            added.push(record);
+            for (const entry of toWire(record)) {
+                const parentId = this.wire.at(-1)?.id ?? null;
+                this.wire.push({ ...entry, parentId });
+            }
+        }
+        return added;
+    }
+    /** The current leaf id (the newest wire entry). */
+    get leafId() {
+        return this.wire.at(-1)?.id ?? null;
+    }
+    page(range) {
+        if (range?.since !== undefined) {
+            const at = this.wire.findIndex((e) => e.id === range.since);
+            if (at === -1)
+                throw new Error(`Entry not found: ${range.since}`);
+            return { entries: this.wire.slice(at + 1), leafId: this.leafId };
+        }
+        return { entries: [...this.wire], leafId: this.leafId };
+    }
+}
+const firstSeen = new Map();
+function timestampOf(record) {
+    const ms = record.model?.[0]
+        ?.timestamp;
+    if (typeof ms === "number" && Number.isFinite(ms)) {
+        return new Date(ms).toISOString();
+    }
+    let seen = firstSeen.get(record.id);
+    if (seen === undefined) {
+        seen = new Date().toISOString();
+        firstSeen.set(record.id, seen);
+    }
+    return seen;
+}
+/** The text of a message's content: a string, or its text blocks joined. */
+function textOf(message) {
+    const content = message?.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");
+}
+/** Map one durable entry to its pi wire entries (without parentId). */
+export function toWire(record) {
+    const id = String(record.id);
+    const timestamp = timestampOf(record);
+    switch (record.kind) {
+        case "pi.compaction": {
+            let summary = textOf(record.model?.[0]);
+            if (summary.startsWith(SUMMARY_PREFIX) && summary.endsWith(SUMMARY_SUFFIX)) {
+                summary = summary.slice(SUMMARY_PREFIX.length, summary.length - SUMMARY_SUFFIX.length);
+            }
+            return [
+                {
+                    type: "compaction",
+                    id,
+                    timestamp,
+                    summary,
+                    firstKeptEntryId: record.head !== undefined ? String(record.head) : id,
+                    tokensBefore: 0,
+                },
+            ];
+        }
+        case "pi.reset": {
+            const handoff = textOf(record.model?.[0]);
+            return [
+                {
+                    type: "custom_message",
+                    id,
+                    timestamp,
+                    customType: RESET_CUSTOM_TYPE,
+                    content: handoff
+                        ? `Context reset. Handoff:\n\n${handoff}`
+                        : "Context reset",
+                    display: true,
+                },
+            ];
+        }
+        case UN_BIEN_APP_KIND: {
+            const data = (record.data ?? {});
+            return [
+                {
+                    type: "custom_message",
+                    id,
+                    timestamp,
+                    customType: typeof data.customType === "string" ? data.customType : "",
+                    content: typeof data.content === "string" ? data.content : "",
+                    display: data.display !== false,
+                    ...(data.details !== undefined ? { details: data.details } : {}),
+                },
+            ];
+        }
+        default:
+            break;
+    }
+    const messages = (record.model ?? []).filter((m) => typeof m.role === "string" &&
+        m.role !== "system");
+    if (messages.length === 0) {
+        return [{ type: record.kind, id, timestamp, kind: record.kind }];
+    }
+    return messages.map((message, n) => ({
+        type: "message",
+        id: n === 0 ? id : `${id}.${n}`,
+        timestamp,
+        message,
+    }));
+}
+//# sourceMappingURL=mirror.js.map

package/dist/mirror.js.map

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

package/dist/ollama_cloud.d.ts

@@ -0,0 +1,2 @@
+/** The Ollama Cloud provider (register via models.setProvider in host.ts). */
+export declare function ollamaCloudProvider(): import("@earendil-works/pi-ai").Provider<"openai-completions">;

package/dist/ollama_cloud.js

@@ -0,0 +1,98 @@
+/**
+ * Ollama Cloud provider for the durable host (skeleton).
+ *
+ * WHY THIS EXISTS: pi-durable has no pi-extension interface, so the
+ * `pi-ollama-cloud` extension (which registers the provider in pi sessions
+ * via pi.registerProvider) can't run here. pi-ai ships no ollama provider.
+ * The host owns its models registry (createModels + setProvider in host.ts),
+ * so the provider is composed host-side from the same data the extension
+ * uses: OpenAI-compatible completions transport against https://ollama.com/v1,
+ * OLLAMA_API_KEY auth, and the model catalog (compat flags copied from
+ * pi-ollama-cloud's models.generated.ts — they are pi-ai Model compat data,
+ * verified against the glm-5.3 entry).
+ *
+ * SKELETON SCOPE (TODOs):
+ *  - Static catalog: glm-5.3 + glm-5.3-flash only. Sync more entries from
+ *    pi-ollama-cloud's models.generated.ts as needed.
+ *  - No live catalog refresh (fetchModels / refreshOllamaCatalog overlay):
+ *    wire the GET https://ollama.com/v1/models + /api/show flow later if the
+ *    static list goes stale.
+ */
+import { createProvider, envApiKeyAuth } from "@earendil-works/pi-ai";
+import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+/** Compat flags shared by the glm-5.x family (pi-ollama-cloud models.generated.ts). */
+const GLM_COMPAT = {
+    maxTokensField: "max_tokens",
+    requiresAssistantAfterToolResult: false,
+    requiresReasoningContentOnAssistantMessages: false,
+    requiresThinkingAsText: false,
+    requiresToolResultName: false,
+    sendSessionAffinityHeaders: false,
+    supportsDeveloperRole: false,
+    supportsLongCacheRetention: false,
+    supportsReasoningEffort: true,
+    supportsStore: false,
+    supportsStrictMode: false,
+    supportsUsageInStreaming: true,
+    thinkingFormat: "openai",
+    zaiToolStream: false,
+};
+// TODO: sync further entries from pi-ollama-cloud models.generated.ts
+const OLLAMA_CLOUD_MODELS = [
+    {
+        id: "glm-5.3",
+        name: "glm-5.3",
+        api: "openai-completions",
+        provider: "ollama-cloud",
+        baseUrl: "https://ollama.com/v1",
+        compat: { ...GLM_COMPAT },
+        contextWindow: 1048576,
+        cost: { cacheRead: 0.26, cacheWrite: 0, input: 1.4, output: 4.4 },
+        input: ["text"],
+        maxTokens: 524288,
+        reasoning: true,
+        thinkingLevelMap: {
+            high: "high",
+            low: "low",
+            medium: null,
+            minimal: null,
+            off: "none",
+            xhigh: "max",
+        },
+    },
+    {
+        id: "glm-5.3-flash",
+        name: "glm-5.3-flash",
+        api: "openai-completions",
+        provider: "ollama-cloud",
+        baseUrl: "https://ollama.com/v1",
+        compat: { ...GLM_COMPAT },
+        // TODO: verify flash's window/cost/thinking map against models.generated.ts
+        contextWindow: 1048576,
+        cost: { cacheRead: 0.03, cacheWrite: 0, input: 0.15, output: 0.5 },
+        input: ["text"],
+        maxTokens: 524288,
+        reasoning: true,
+        thinkingLevelMap: {
+            high: "high",
+            low: "low",
+            medium: null,
+            minimal: null,
+            off: "none",
+            xhigh: "max",
+        },
+    },
+];
+/** The Ollama Cloud provider (register via models.setProvider in host.ts). */
+export function ollamaCloudProvider() {
+    return createProvider({
+        id: "ollama-cloud",
+        name: "Ollama Cloud",
+        baseUrl: "https://ollama.com/v1",
+        auth: { apiKey: envApiKeyAuth("Ollama Cloud API key", ["OLLAMA_API_KEY"]) },
+        models: OLLAMA_CLOUD_MODELS,
+        // TODO: fetchModels overlay (refreshOllamaCatalog) for the live catalog.
+        api: openAICompletionsApi(),
+    });
+}
+//# sourceMappingURL=ollama_cloud.js.map

package/dist/ollama_cloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama_cloud.js","sourceRoot":"","sources":["../src/ollama_cloud.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAc,MAAM,uBAAuB,CAAA;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,mDAAmD,CAAA;AAExF,uFAAuF;AACvF,MAAM,UAAU,GAAG;IACjB,cAAc,EAAE,YAAY;IAC5B,gCAAgC,EAAE,KAAK;IACvC,2CAA2C,EAAE,KAAK;IAClD,sBAAsB,EAAE,KAAK;IAC7B,sBAAsB,EAAE,KAAK;IAC7B,0BAA0B,EAAE,KAAK;IACjC,qBAAqB,EAAE,KAAK;IAC5B,0BAA0B,EAAE,KAAK;IACjC,uBAAuB,EAAE,IAAI;IAC7B,aAAa,EAAE,KAAK;IACpB,kBAAkB,EAAE,KAAK;IACzB,wBAAwB,EAAE,IAAI;IAC9B,cAAc,EAAE,QAAQ;IACxB,aAAa,EAAE,KAAK;CACZ,CAAA;AAEV,sEAAsE;AACtE,MAAM,mBAAmB,GAA2C;IAClE;QACE,EAAE,EAAE,SAAS;QACb,IAAI,EAAE,SAAS;QACf,GAAG,EAAE,oBAAoB;QACzB,QAAQ,EAAE,cAAc;QACxB,OAAO,EAAE,uBAAuB;QAChC,MAAM,EAAE,EAAE,GAAG,UAAU,EAAE;QACzB,aAAa,EAAE,OAAO;QACtB,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;QACjE,KAAK,EAAE,CAAC,MAAM,CAAC;QACf,SAAS,EAAE,MAAM;QACjB,SAAS,EAAE,IAAI;QACf,gBAAgB,EAAE;YAChB,IAAI,EAAE,MAAM;YACZ,GAAG,EAAE,KAAK;YACV,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,IAAI;YACb,GAAG,EAAE,MAAM;YACX,KAAK,EAAE,KAAK;SACb;KACF;IACD;QACE,EAAE,EAAE,eAAe;QACnB,IAAI,EAAE,eAAe;QACrB,GAAG,EAAE,oBAAoB;QACzB,QAAQ,EAAE,cAAc;QACxB,OAAO,EAAE,uBAAuB;QAChC,MAAM,EAAE,EAAE,GAAG,UAAU,EAAE;QACzB,4EAA4E;QAC5E,aAAa,EAAE,OAAO;QACtB,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;QAClE,KAAK,EAAE,CAAC,MAAM,CAAC;QACf,SAAS,EAAE,MAAM;QACjB,SAAS,EAAE,IAAI;QACf,gBAAgB,EAAE;YAChB,IAAI,EAAE,MAAM;YACZ,GAAG,EAAE,KAAK;YACV,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,IAAI;YACb,GAAG,EAAE,MAAM;YACX,KAAK,EAAE,KAAK;SACb;KACF;CACF,CAAA;AAED,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB;IACjC,OAAO,cAAc,CAAC;QACpB,EAAE,EAAE,cAAc;QAClB,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,uBAAuB;QAChC,IAAI,EAAE,EAAE,MAAM,EAAE,aAAa,CAAC,sBAAsB,EAAE,CAAC,gBAAgB,CAAC,CAAC,EAAE;QAC3E,MAAM,EAAE,mBAAmB;QAC3B,yEAAyE;QACzE,GAAG,EAAE,oBAAoB,EAAE;KAC5B,CAAC,CAAA;AACJ,CAAC"}

package/dist/pi_launch.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Durable binding's HeadlessLaunchPort implementation: the launch-wait-quit
+ * primitive behind the `launch_pi_task` tool — the ONE place the two
+ * bindings meet at runtime.
+ *
+ * Launch path: the pi SDK's headless `createAgentSession` (the programmatic
+ * equivalent of `pi` without a TUI — NOT `pi -p`, whose print-mode exit the
+ * un-bien extension deliberately never auto-starts the relay in). The session
+ * loads its extensions through pi's own resource discovery from the target
+ * cwd (installed pi-packages, `<cwd>/.pi/extensions`, `<agentDir>`), so the
+ * un-bien pi extension must be discoverable there — when it is, its
+ * session_start auto-init joins the UDS mesh under the session's display
+ * name, which is the SCOPED name minted per invocation.
+ *
+ * Readiness: the local UDS broker is probed (observer probe — never
+ * registers, never perturbs the roster) until the scoped name appears as a
+ * peer address; that address is the agent_send routing key for the task.
+ *
+ * Teardown: `session.dispose()` — the un-bien extension's session_shutdown
+ * handler leaves the mesh and closes the relay, exactly as it does for a
+ * quitting interactive pi.
+ */
+import { type AgentSession } from "@earendil-works/pi-coding-agent";
+import type { HeadlessLaunchPort, HeadlessLaunchedSession } from "@geohar/un-bien/core";
+export declare class HeadlessPiLaunch implements HeadlessLaunchPort {
+    launchHeadless(opts: {
+        cwd: string;
+        name: string;
+    }): Promise<HeadlessLaunchedSession>;
+}
+export declare class HeadlessPiSession implements HeadlessLaunchedSession {
+    private readonly session;
+    readonly name: string;
+    constructor(session: AgentSession, name: string);
+    /** join-mesh-under-name: bind the scoped name, then bring the un-bien
+     *  extension up. `bindExtensions` fires session_start; the extension's
+     *  auto-init resolves the mesh name from the session display name (set
+     *  FIRST so the join sees it) and connects the broker. */
+    joinMeshUnderName(): Promise<void>;
+    /** await-ready: poll the broker's observer probe until the scoped name is
+     *  a registered peer. Resolves with the broker-assigned address (the name
+     *  may carry a `#N` collision suffix the broker added). */
+    awaitReady(opts?: {
+        timeoutMs?: number;
+    }): Promise<{
+        address: string;
+    }>;
+    /** tear-down: quit gracefully (extension disposal leaves the mesh). */
+    tearDown(): Promise<void>;
+}