@noopolis/daimon 0.1.1 → 0.2.0

package/dist/runtime/mcpToolResult.js

@@ -0,0 +1,214 @@
+/**
+ * Lowering an upstream MCP server's `CallToolResult` onto a Pi tool result.
+ *
+ * Every `mcp_*` tool is a *passthrough*: Daimon calls a declared MCP server and
+ * has to hand the model back what that server actually said. It used to hand
+ * back routing metadata instead — `details: { server, tool, is_error }` — and
+ * because the MCP mount lowers `details` to `structuredContent`
+ * (`src/mcp/toolServer.ts`) and the engines render `structuredContent` in
+ * preference to `content`, an agent calling any declared MCP tool saw
+ * `{"server":"newsroom","tool":"file_article","is_error":true}` and nothing
+ * else. The tool's own answer, and the reason for its own failure, never
+ * reached the model. `moltnet_read` was the same defect in a Daimon-authored
+ * tool; this is the wider one, in the tools Daimon does not author.
+ *
+ * Three rules follow, and they are the whole design:
+ *
+ *   1. **Both channels always carry the payload.** `content` and
+ *      `structuredContent` are each filled with the result, mirroring whichever
+ *      one the server did not send. Daimon has already been wrong once about
+ *      which channel an engine renders; carrying the answer in both is the only
+ *      shape where being wrong again costs nothing. A server that sent
+ *      `structuredContent` gets it forwarded *verbatim*, so a declared
+ *      `outputSchema` still describes what the model sees.
+ *
+ *   2. **`isError` is raised, not reported.** Pi's `AgentToolResult` has no
+ *      error channel — a Pi tool signals failure by throwing, and
+ *      `toolServer.ts` lowers a throw to `isError: true` plus the message. So an
+ *      upstream `isError: true` becomes a thrown {@link McpToolCallError}
+ *      carrying the server's own reason text. The model then gets a result
+ *      flagged as a failure *and* the sentence explaining it, which is the
+ *      difference between correcting a call and guessing at it.
+ *
+ *   3. **The bound truncates; it never throws the payload away.** An oversized
+ *      result used to be refused outright, so the agent got
+ *      `Error: MCP tool result exceeds bound` and none of the data. It is now
+ *      degraded to a head of the serialized result plus an explicit marker
+ *      naming both sizes.
+ *
+ * Daimon deliberately does *not* re-declare the upstream `outputSchema` on its
+ * own mount. A declared output schema obliges every result to carry conforming
+ * `structuredContent`, which neither a content-only server response nor rule 3's
+ * truncation marker can satisfy — declaring it would turn a degraded result into
+ * a client-side protocol error and lose the payload all over again.
+ */
+/** Bound on the whole receipt record, mirrored from `productionAgentTools.ts`. */
+const MAX_RECEIPT_BYTES = 65_536;
+/**
+ * Headroom left inside the receipt bound for the receipt's own envelope.
+ *
+ * A successful MCP result is stored in its receipt so a replayed identical call
+ * in the same wake answers with the result rather than with a digest of it. The
+ * envelope (`kind`, ids, engine, server, tool, digest, `is_error`, `at`) is a
+ * few hundred bytes for any sane name; 4096 is generous enough that a stored
+ * result can never push the receipt past its own bound.
+ */
+export const MCP_RECEIPT_ENVELOPE_RESERVE_BYTES = 4_096;
+/** Bound on one lowered MCP tool result, model-facing and receipt-facing alike. */
+export const MCP_TOOL_RESULT_MAX_BYTES = MAX_RECEIPT_BYTES - MCP_RECEIPT_ENVELOPE_RESERVE_BYTES;
+/** Rendered for a server that answered with neither content nor structured content. */
+export const MCP_EMPTY_RESULT_TEXT = "[daimon: the MCP server returned a result with no content]";
+/** Reason used when a server flags an error but supplies no text for it. */
+export const MCP_ERROR_WITHOUT_DETAIL = "the MCP server reported an error and gave no reason";
+/**
+ * An upstream MCP tool that answered with `isError: true`.
+ *
+ * The reason is the server's own words. `toolServer.ts` renders a thrown error
+ * as `"<name>: <message>"` inside an `isError: true` result, so the model
+ * receives both the failure flag and the explanation.
+ */
+export class McpToolCallError extends Error {
+    server;
+    tool;
+    reason;
+    constructor(server, tool, reason) {
+        super(`${server}/${tool} failed: ${reason}`);
+        this.name = "McpToolCallError";
+        this.server = server;
+        this.tool = tool;
+        this.reason = reason;
+    }
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Flatten an MCP content array to text, naming the parts that are not text. */
+export function mcpContentText(content) {
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => {
+        if (!isRecord(part))
+            return "";
+        if (part.type === "text" && typeof part.text === "string")
+            return part.text;
+        return `[${typeof part.type === "string" ? part.type : "unknown"} content part]`;
+    })
+        .filter((text) => text.length > 0)
+        .join("\n");
+}
+/** Truncate to a byte budget without splitting a UTF-8 code point. */
+export function truncateUtf8(value, maxBytes) {
+    const bytes = Buffer.from(value, "utf8");
+    if (bytes.byteLength <= maxBytes)
+        return { text: value, truncated: false, originalBytes: bytes.byteLength };
+    let end = Math.max(0, maxBytes);
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return { text: bytes.subarray(0, end).toString("utf8"), truncated: true, originalBytes: bytes.byteLength };
+}
+const truncationMarker = (resultBytes, boundBytes) => `\n[daimon: truncated — the MCP tool result was ${resultBytes} bytes, above the ${boundBytes}-byte tool result bound]`;
+/**
+ * The server's own explanation for an `isError: true` result.
+ *
+ * Both channels are consulted, because a server may put a human sentence in
+ * `content` and a machine-readable code in `structuredContent`, and an agent
+ * that has to fix its own call needs whichever one it was given.
+ */
+export function mcpErrorReason(result, maxBytes) {
+    const text = mcpContentText(result.content);
+    const structured = result.structuredContent === undefined ? "" : safeStringify(result.structuredContent);
+    const reason = [text, structured].filter((piece) => piece.length > 0).join(" ");
+    if (reason.length === 0)
+        return MCP_ERROR_WITHOUT_DETAIL;
+    const bounded = truncateUtf8(reason, maxBytes);
+    return bounded.truncated ? `${bounded.text}${truncationMarker(bounded.originalBytes, maxBytes)}` : bounded.text;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        return "[daimon: the MCP server returned a value that is not JSON-serialisable]";
+    }
+}
+/** Everything a result carries beyond the three fields this module names. */
+function otherFields(result) {
+    if (!isRecord(result))
+        return undefined;
+    const rest = Object.fromEntries(Object.entries(result).filter(([key]) => key !== "content" && key !== "structuredContent" && key !== "isError"));
+    return Object.keys(rest).length === 0 ? undefined : rest;
+}
+const measure = (content, details) => Buffer.byteLength(safeStringify({ content, structuredContent: details }), "utf8");
+/**
+ * Lower one upstream result, or throw {@link McpToolCallError} when it is an
+ * error result.
+ */
+export function renderMcpToolResult(input) {
+    const maxBytes = input.maxBytes ?? MCP_TOOL_RESULT_MAX_BYTES;
+    if (input.result.isError === true) {
+        throw new McpToolCallError(input.server, input.tool, mcpErrorReason(input.result, Math.floor(maxBytes / 2)));
+    }
+    const upstreamContent = Array.isArray(input.result.content) ? input.result.content : undefined;
+    // A server predating the `content` field answers in some other shape entirely
+    // (the SDK still types `toolResult` for those). Forward whatever it did send
+    // rather than reporting an empty result over the top of a real one.
+    const legacy = upstreamContent === undefined && !isRecord(input.result.structuredContent) ? otherFields(input.result) : undefined;
+    const structured = isRecord(input.result.structuredContent) ? input.result.structuredContent : legacy;
+    const content = upstreamContent !== undefined && upstreamContent.length > 0
+        ? upstreamContent
+        : structured !== undefined
+            ? [{ type: "text", text: safeStringify(structured) }]
+            : [{ type: "text", text: MCP_EMPTY_RESULT_TEXT }];
+    // Rule 1: the channel the server left empty mirrors the one it filled, so the
+    // payload is present whichever one the engine chooses to render.
+    const details = structured ?? { content: upstreamContent ?? [] };
+    if (measure(content, details) <= maxBytes)
+        return { content, details, truncated: false };
+    return degrade(input.result, measure(content, details), maxBytes);
+}
+/**
+ * Rule 3: an oversized result becomes a bounded head of itself plus a marker.
+ *
+ * Both channels still mirror each other, so the head is written twice; the
+ * budget is halved to pay for that and then shrunk until the whole record
+ * genuinely fits, rather than trusting an estimate of the JSON overhead.
+ */
+function degrade(result, resultBytes, maxBytes) {
+    const serialized = safeStringify({
+        ...(result.content === undefined ? {} : { content: result.content }),
+        ...(result.structuredContent === undefined ? {} : { structured_content: result.structuredContent })
+    });
+    const marker = truncationMarker(resultBytes, maxBytes);
+    const build = (head) => ({
+        content: [{ type: "text", text: `${head}${marker}` }],
+        details: { daimon_truncated: true, bound_bytes: maxBytes, result_bytes: resultBytes, result_json_head: head },
+        truncated: true
+    });
+    let budget = Math.max(0, Math.floor(maxBytes / 2));
+    let candidate = build(truncateUtf8(serialized, budget).text);
+    for (let attempt = 0; attempt < 8 && budget > 0; attempt += 1) {
+        const size = measure(candidate.content, candidate.details);
+        if (size <= maxBytes)
+            return candidate;
+        budget = Math.max(0, budget - Math.ceil((size - maxBytes) / 2) - 16);
+        candidate = build(truncateUtf8(serialized, budget).text);
+    }
+    return candidate;
+}
+/**
+ * Rebuild a tool answer from a receipt written by an earlier identical call.
+ *
+ * The wake-scoped receipt exists so a repeated identical call is not sent
+ * upstream twice. It used to be *returned* to the model in place of the result,
+ * so a retried call answered with `{"kind":"mcp",…,"digest":"sha256:…"}` — the
+ * least useful thing an agent stuck in a retry loop could possibly receive.
+ * A recorded failure is replayed as the same failure, with the same reason.
+ */
+export function replayMcpReceipt(server, tool, receipt) {
+    if (typeof receipt.error === "string")
+        throw new McpToolCallError(server, tool, receipt.error);
+    const stored = receipt.result;
+    if (isRecord(stored) && Array.isArray(stored.content) && isRecord(stored.details)) {
+        return { content: stored.content, details: stored.details, truncated: receipt.truncated === true };
+    }
+    throw new McpToolCallError(server, tool, "an identical earlier call in this wake was recorded without its result, so it cannot be replayed; change the arguments to make a new call");
+}

package/dist/runtime/moltnetMachineRead.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Paging and error semantics for Moltnet's frozen `machine` read wire.
+ *
+ * The wire is a strict v1 with two caps that a naive read ignores, and both are
+ * enforced *server side* by `projectRead` in the Moltnet CLI
+ * (`moltnet/internal/machine/service.go`), which answers
+ * `{"error":{"code":"transport"}}` rather than truncating:
+ *
+ *   - `MachineMaxOutputLineBytes` (16384) bounds the whole encoded response
+ *     line. `MachineReadPage.Validate` measures it against a *worst case*
+ *     envelope — a maximum-length correlation id and target id — so the
+ *     effective payload budget is roughly 250 bytes tighter than the line an
+ *     agent actually receives.
+ *   - `MachineMaxReadPartTextBytes` (4096) bounds any single message part.
+ *
+ * An agent asking for `limit: 100` on a room of six ~2000-byte messages
+ * therefore never got a page at all: seven such messages already overflow the
+ * line. Reading in small pages and following the returned cursor is the only
+ * way to get a busy room across this wire, so that behaviour lives here rather
+ * than in the tool that happens to call it.
+ */
+/** `protocol.MachineMaxOutputLineBytes`, quoted for diagnostics only. */
+export declare const MOLTNET_MACHINE_MAX_OUTPUT_LINE_BYTES = 16384;
+/** `protocol.MachineMaxReadPartTextBytes`, quoted for diagnostics only. */
+export declare const MOLTNET_MACHINE_MAX_READ_PART_TEXT_BYTES = 4096;
+/**
+ * Messages requested per wire page.
+ *
+ * Six ~2000-byte messages were the largest page observed to encode inside the
+ * line cap against the real 0.1.17 binary, so five leaves headroom for a page
+ * of unusually large messages before the adaptive halving below is needed.
+ */
+export declare const MOLTNET_READ_PAGE_LIMIT = 5;
+/** Hard stop on wire round trips, so a misbehaving cursor cannot spin forever. */
+export declare const MOLTNET_READ_MAX_PAGES = 64;
+/**
+ * A `machine` response that carried `error.code`.
+ *
+ * The code is the whole diagnosis — a `transport` is a cap overflow, a
+ * `not_found` is an undeclared target, a `canceled` is a stdin race — and
+ * collapsing all of them into one generic string is what hid a never-working
+ * tool for as long as it did.
+ */
+export declare class MoltnetMachineError extends Error {
+    readonly code: string;
+    constructor(operation: string, code: string);
+}
+/**
+ * Unwrap one `machine` response, surfacing `error.code` as a thrown
+ * {@link MoltnetMachineError} rather than an anonymous refusal.
+ */
+export declare function moltnetOperationResult(response: Record<string, unknown>, key: string, operation: string): Record<string, unknown> | undefined;
+export interface MoltnetReadWirePage {
+    readonly messages: readonly unknown[];
+    readonly hasMore: boolean;
+    readonly nextBefore?: string;
+    readonly nextAfter?: string;
+    readonly target?: unknown;
+}
+export type MoltnetReadFetch = (request: {
+    readonly limit: number;
+    readonly before?: string;
+    readonly after?: string;
+}) => Promise<MoltnetReadWirePage>;
+export interface MoltnetReadTruncation {
+    readonly reason: "message_exceeds_machine_wire_caps" | "result_bound" | "page_bound";
+    readonly detail: string;
+    readonly cursor?: string;
+}
+export interface MoltnetPagedRead {
+    readonly target?: unknown;
+    readonly messages: readonly unknown[];
+    readonly hasMore: boolean;
+    readonly nextBefore?: string;
+    readonly nextAfter?: string;
+    readonly pages: number;
+    readonly truncated?: MoltnetReadTruncation;
+}
+export interface MoltnetPagedReadOptions {
+    readonly requested: number;
+    readonly before?: string;
+    readonly after?: string;
+    readonly maxBytes: number;
+    readonly pageLimit?: number;
+    readonly fetch: MoltnetReadFetch;
+}
+/**
+ * Read `requested` messages by walking the wire in pages small enough to encode.
+ *
+ * Direction follows the caller's cursor: an `after` read walks forward through
+ * `next_after`, everything else walks backward from the newest message through
+ * `next_before`. Either way the returned messages are in one stable
+ * chronological order, oldest first, matching the order a single page arrives
+ * in.
+ */
+export declare function readMoltnetPages(options: MoltnetPagedReadOptions): Promise<MoltnetPagedRead>;
+//# sourceMappingURL=moltnetMachineRead.d.ts.map

package/dist/runtime/moltnetMachineRead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moltnetMachineRead.d.ts","sourceRoot":"","sources":["../../src/runtime/moltnetMachineRead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,yEAAyE;AACzE,eAAO,MAAM,qCAAqC,QAAS,CAAC;AAC5D,2EAA2E;AAC3E,eAAO,MAAM,wCAAwC,OAAQ,CAAC;AAC9D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEV,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAKnD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAUrC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KACnF,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,mCAAmC,GAAG,cAAc,GAAG,YAAY,CAAC;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,CAAC;CAC5C;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuElG"}

package/dist/runtime/moltnetMachineRead.js

@@ -0,0 +1,183 @@
+/**
+ * Paging and error semantics for Moltnet's frozen `machine` read wire.
+ *
+ * The wire is a strict v1 with two caps that a naive read ignores, and both are
+ * enforced *server side* by `projectRead` in the Moltnet CLI
+ * (`moltnet/internal/machine/service.go`), which answers
+ * `{"error":{"code":"transport"}}` rather than truncating:
+ *
+ *   - `MachineMaxOutputLineBytes` (16384) bounds the whole encoded response
+ *     line. `MachineReadPage.Validate` measures it against a *worst case*
+ *     envelope — a maximum-length correlation id and target id — so the
+ *     effective payload budget is roughly 250 bytes tighter than the line an
+ *     agent actually receives.
+ *   - `MachineMaxReadPartTextBytes` (4096) bounds any single message part.
+ *
+ * An agent asking for `limit: 100` on a room of six ~2000-byte messages
+ * therefore never got a page at all: seven such messages already overflow the
+ * line. Reading in small pages and following the returned cursor is the only
+ * way to get a busy room across this wire, so that behaviour lives here rather
+ * than in the tool that happens to call it.
+ */
+/** `protocol.MachineMaxOutputLineBytes`, quoted for diagnostics only. */
+export const MOLTNET_MACHINE_MAX_OUTPUT_LINE_BYTES = 16_384;
+/** `protocol.MachineMaxReadPartTextBytes`, quoted for diagnostics only. */
+export const MOLTNET_MACHINE_MAX_READ_PART_TEXT_BYTES = 4_096;
+/**
+ * Messages requested per wire page.
+ *
+ * Six ~2000-byte messages were the largest page observed to encode inside the
+ * line cap against the real 0.1.17 binary, so five leaves headroom for a page
+ * of unusually large messages before the adaptive halving below is needed.
+ */
+export const MOLTNET_READ_PAGE_LIMIT = 5;
+/** Hard stop on wire round trips, so a misbehaving cursor cannot spin forever. */
+export const MOLTNET_READ_MAX_PAGES = 64;
+/**
+ * A `machine` response that carried `error.code`.
+ *
+ * The code is the whole diagnosis — a `transport` is a cap overflow, a
+ * `not_found` is an undeclared target, a `canceled` is a stdin race — and
+ * collapsing all of them into one generic string is what hid a never-working
+ * tool for as long as it did.
+ */
+export class MoltnetMachineError extends Error {
+    code;
+    constructor(operation, code) {
+        super(`Moltnet ${operation} failed: ${code}`);
+        this.name = "MoltnetMachineError";
+        this.code = code;
+    }
+}
+/**
+ * Unwrap one `machine` response, surfacing `error.code` as a thrown
+ * {@link MoltnetMachineError} rather than an anonymous refusal.
+ */
+export function moltnetOperationResult(response, key, operation) {
+    const error = response.error;
+    if (error !== undefined && error !== null) {
+        const code = typeof error === "object" && typeof error.code === "string"
+            ? error.code
+            : "unknown";
+        throw new MoltnetMachineError(operation, code);
+    }
+    const result = response[key];
+    return typeof result === "object" && result !== null ? result : undefined;
+}
+/**
+ * Read `requested` messages by walking the wire in pages small enough to encode.
+ *
+ * Direction follows the caller's cursor: an `after` read walks forward through
+ * `next_after`, everything else walks backward from the newest message through
+ * `next_before`. Either way the returned messages are in one stable
+ * chronological order, oldest first, matching the order a single page arrives
+ * in.
+ */
+export async function readMoltnetPages(options) {
+    const forward = options.after !== undefined;
+    const pageLimit = Math.max(1, options.pageLimit ?? MOLTNET_READ_PAGE_LIMIT);
+    const collected = [];
+    const visited = new Set();
+    let cursor = forward ? options.after : options.before;
+    let target;
+    let total = 0;
+    let pages = 0;
+    let bytes = 0;
+    let hasMore = false;
+    let nextCursor;
+    let truncated;
+    while (total < options.requested && pages < MOLTNET_READ_MAX_PAGES) {
+        const wanted = Math.min(pageLimit, options.requested - total);
+        const page = await fetchWithinCaps(options.fetch, wanted, forward, cursor);
+        if (page instanceof MoltnetMachineError) {
+            // A cursor the caller supplied that yields nothing is a bad cursor, not a
+            // message too large to encode: the two are indistinguishable on this wire
+            // (both are `transport`), and an empty truncated read hides the mistake
+            // where the code names it.
+            if (pages === 0 && (options.before !== undefined || options.after !== undefined))
+                throw page;
+            truncated = oversizedMessage(cursor);
+            hasMore = true;
+            nextCursor = cursor;
+            break;
+        }
+        const pageBytes = Buffer.byteLength(JSON.stringify(page.messages));
+        if (pages > 0 && bytes + pageBytes > options.maxBytes) {
+            truncated = {
+                reason: "result_bound",
+                detail: `the concatenated read reached the ${options.maxBytes} byte tool result bound`,
+                ...(cursor === undefined ? {} : { cursor })
+            };
+            hasMore = true;
+            nextCursor = cursor;
+            break;
+        }
+        if (target === undefined)
+            target = page.target;
+        collected.push(page.messages);
+        bytes += pageBytes;
+        total += page.messages.length;
+        pages += 1;
+        const next = forward ? page.nextAfter : page.nextBefore;
+        const resumable = page.hasMore && typeof next === "string" && next.length > 0;
+        hasMore = resumable;
+        nextCursor = resumable ? next : undefined;
+        // A repeated cursor or an empty page means the wire stopped making
+        // progress; continuing would spin without ever satisfying `requested`.
+        if (!resumable || page.messages.length === 0 || visited.has(next))
+            break;
+        visited.add(next);
+        cursor = next;
+    }
+    if (hasMore && truncated === undefined && pages >= MOLTNET_READ_MAX_PAGES) {
+        truncated = {
+            reason: "page_bound",
+            detail: `the read stopped after ${MOLTNET_READ_MAX_PAGES} wire pages`,
+            ...(nextCursor === undefined ? {} : { cursor: nextCursor })
+        };
+    }
+    return {
+        ...(target === undefined ? {} : { target }),
+        messages: forward ? collected.flat() : collected.reverse().flat(),
+        hasMore,
+        ...(nextCursor === undefined ? {} : forward ? { nextAfter: nextCursor } : { nextBefore: nextCursor }),
+        pages,
+        ...(truncated === undefined ? {} : { truncated })
+    };
+}
+/**
+ * Fetch one page, halving the requested limit on every `transport` refusal.
+ *
+ * A returned {@link MoltnetMachineError} means even a single message could not
+ * be projected onto the wire. The wire offers no way to name or skip that
+ * message — a cursor only ever comes back inside a page that encoded — so the
+ * caller decides between reporting the blockage and failing outright.
+ */
+async function fetchWithinCaps(fetch, wanted, forward, cursor) {
+    let limit = wanted;
+    for (;;) {
+        try {
+            return await fetch({
+                limit,
+                ...(cursor === undefined ? {} : forward ? { after: cursor } : { before: cursor })
+            });
+        }
+        catch (error) {
+            if (!(error instanceof MoltnetMachineError) || error.code !== "transport")
+                throw error;
+            if (limit <= 1)
+                return error;
+            limit = Math.max(1, Math.floor(limit / 2));
+        }
+    }
+}
+function oversizedMessage(cursor) {
+    return {
+        reason: "message_exceeds_machine_wire_caps",
+        detail: "one Moltnet message could not be encoded onto the machine read wire"
+            + ` (part text limit ${MOLTNET_MACHINE_MAX_READ_PART_TEXT_BYTES} bytes,`
+            + ` response line limit ${MOLTNET_MACHINE_MAX_OUTPUT_LINE_BYTES} bytes);`
+            + " the read returned everything up to it rather than failing",
+        ...(cursor === undefined ? {} : { cursor })
+    };
+}

package/dist/runtime/organizationRuntime.d.ts

@@ -0,0 +1,165 @@
+import type { AttentionConfig } from "../contracts/attentionContract.js";
+import { ORGANIZATION_RUNTIME_CODEX_REASONING_EFFORTS, ORGANIZATION_RUNTIME_CODEX_WORKSPACE_NO_NETWORK_POLICY, ORGANIZATION_RUNTIME_CONFIG_SCHEMA, ORGANIZATION_RUNTIME_CONFIG_V2_SCHEMA, ORGANIZATION_RUNTIME_MAX_AGENTS, ORGANIZATION_RUNTIME_MAX_CONFIG_BYTES, ORGANIZATION_RUNTIME_MAX_INSTRUCTIONS_CODEPOINTS, ORGANIZATION_RUNTIME_MAX_STRING_BYTES, ORGANIZATION_RUNTIME_MAX_STRING_CODEPOINTS, ORGANIZATION_RUNTIME_MAX_WAKE_TEXT_BYTES, ORGANIZATION_RUNTIME_MAX_SCHEDULE_INTERVAL_MS, ORGANIZATION_RUNTIME_MAX_SCHEDULE_JITTER_SECONDS, ORGANIZATION_RUNTIME_V2_VERSION, ORGANIZATION_RUNTIME_VERSION } from "../contracts/organizationRuntimeContract.js";
+export { ORGANIZATION_RUNTIME_CODEX_REASONING_EFFORTS, ORGANIZATION_RUNTIME_CODEX_WORKSPACE_NO_NETWORK_POLICY, ORGANIZATION_RUNTIME_CONFIG_SCHEMA, ORGANIZATION_RUNTIME_CONFIG_V2_SCHEMA, ORGANIZATION_RUNTIME_MAX_AGENTS, ORGANIZATION_RUNTIME_MAX_CONFIG_BYTES, ORGANIZATION_RUNTIME_MAX_INSTRUCTIONS_CODEPOINTS, ORGANIZATION_RUNTIME_MAX_STRING_BYTES, ORGANIZATION_RUNTIME_MAX_STRING_CODEPOINTS, ORGANIZATION_RUNTIME_MAX_WAKE_TEXT_BYTES, ORGANIZATION_RUNTIME_MAX_SCHEDULE_INTERVAL_MS, ORGANIZATION_RUNTIME_MAX_SCHEDULE_JITTER_SECONDS, ORGANIZATION_RUNTIME_V2_VERSION, ORGANIZATION_RUNTIME_VERSION };
+export type OrganizationRuntimeEngineKind = "codex" | "grok" | "agy";
+/**
+ * `model`/`reasoningEffort` are accepted for codex (open model name) and for
+ * grok (closed broker lists, declared together); agy owns its own model
+ * selection and `organizationRuntimeParsing.ts` rejects either field there at
+ * parse time rather than silently ignoring it. The type stays flat
+ * — not a `kind`-discriminated union — because every parsed value already
+ * satisfies the invariant; callers that need it narrow on `kind === "codex"`.
+ */
+export type OrganizationRuntimeCodexSandboxPolicy = Readonly<{
+    mode: "workspace-write";
+    networkAccess: false;
+    webSearch: "disabled";
+}>;
+export type OrganizationRuntimeEngineIntent = Readonly<{
+    kind: OrganizationRuntimeEngineKind;
+    model?: string;
+    reasoningEffort?: string;
+    codexSandbox?: OrganizationRuntimeCodexSandboxPolicy;
+}>;
+export type OrganizationRuntimeMcpServer = Readonly<{
+    name: string;
+    transport: "stdio" | "sse" | "streamable_http";
+    command?: string;
+    args: readonly string[];
+    env: Readonly<Record<string, string>>;
+    authSecretEnv?: string;
+    url?: string;
+    tools: readonly string[];
+}>;
+export type OrganizationRuntimeMoltnet = Readonly<{
+    cliPath: string;
+    configPath: string;
+    networks: readonly Readonly<{
+        id: string;
+        rooms: readonly string[];
+        dms: boolean;
+    }>[];
+}>;
+export type OrganizationRuntimeMemory = Readonly<{
+    runtimeHomePath: string;
+    source?: string;
+    tokenBudget?: number;
+}>;
+export type OrganizationRuntimeSchedule = Readonly<{
+    kind: "disabled";
+}> | Readonly<{
+    kind: "every";
+    interval_ms: number;
+    prompt: string;
+    jitter_seconds?: number;
+}> | Readonly<{
+    kind: "cron";
+    cron: string;
+    timezone: string;
+    prompt: string;
+    jitter_seconds?: number;
+}>;
+export type OrganizationRuntimeAgentConfig = Readonly<{
+    id: string;
+    name: string;
+    instructions: string;
+    workspacePath: string;
+    runtimeHomePath: string;
+    engine: OrganizationRuntimeEngineIntent;
+    attention?: AttentionConfig;
+    schedule?: OrganizationRuntimeSchedule;
+    mcp?: readonly OrganizationRuntimeMcpServer[];
+    moltnet?: OrganizationRuntimeMoltnet;
+    memory?: OrganizationRuntimeMemory;
+}>;
+export type OrganizationRuntimeHostConfig = Readonly<{
+    bindHost: string;
+    port: number; /** Variable name only; never secret configuration data. */
+    controlTokenEnv: string;
+}>;
+export type OrganizationRuntimeConfig = Readonly<{
+    version: typeof ORGANIZATION_RUNTIME_VERSION | typeof ORGANIZATION_RUNTIME_V2_VERSION;
+    host: OrganizationRuntimeHostConfig;
+    agents: readonly OrganizationRuntimeAgentConfig[];
+}>;
+export type OrganizationRuntimeLifecycleState = "starting" | "running" | "stopping" | "stopped";
+export type OrganizationRuntimeWakeEvent = Readonly<{
+    version: "noopolis.daimon.wake.v1";
+    id: string;
+    kind: "manual" | "message" | "schedule" | "external";
+    text: string;
+    occurredAt: string;
+}>;
+export type OrganizationRuntimeWakeRequest = Readonly<{
+    token: string | undefined;
+    agentId: string;
+    event: OrganizationRuntimeWakeEvent;
+}>;
+export type OrganizationRuntimeWakeResult = Readonly<{
+    version: "noopolis.daimon.wake-result.v1";
+    status: "completed";
+    agentId: string;
+    wakeId: string;
+    text: string;
+    durationMs: number;
+}> | Readonly<{
+    version: "noopolis.daimon.wake-result.v1";
+    status: "rejected";
+    agentId: string;
+    wakeId: string;
+    code: "invalid_request" | "unauthorized" | "unknown_agent" | "queue_full" | "durable_inbox_required";
+}> | Readonly<{
+    version: "noopolis.daimon.wake-result.v1";
+    status: "stopped";
+    agentId: string;
+    wakeId: string;
+    code: "host_stopping" | "host_stopped" | "queued_wake_stopped" | "active_wake_aborted";
+}> | Readonly<{
+    version: "noopolis.daimon.wake-result.v1";
+    status: "failed";
+    agentId: string;
+    wakeId: string;
+    code: "engine_failed";
+    detail?: string;
+}>;
+export type OrganizationRuntimeAgentHealth = Readonly<{
+    agentId: string;
+    engine: OrganizationRuntimeEngineIntent["kind"];
+    state: OrganizationRuntimeLifecycleState | "idle" | "running" | "failed";
+}>;
+export type OrganizationRuntimeHealth = Readonly<{
+    version: "noopolis.daimon.organization-runtime-health.v1";
+    state: OrganizationRuntimeLifecycleState;
+    agents: readonly OrganizationRuntimeAgentHealth[];
+}>;
+export type OrganizationRuntimeActivityRequest = Readonly<{
+    agentId?: string;
+    cursor?: string;
+    limit: number;
+}>;
+export type OrganizationRuntimeActivity = Readonly<{
+    id: string;
+    agentId: string;
+    wakeId?: string;
+    kind: "wake_started" | "wake_completed" | "wake_rejected" | "wake_aborted" | "agent_stopped";
+    occurredAt: string;
+}>;
+export type OrganizationRuntimeActivityPage = Readonly<{
+    version: "noopolis.daimon.organization-runtime-activity.v1";
+    items: readonly OrganizationRuntimeActivity[];
+    nextCursor?: string;
+}>;
+export type OrganizationRuntimeShutdownCompletion = Readonly<{
+    version: "noopolis.daimon.organization-runtime-stop.v1";
+    state: "stopped";
+}>;
+/** One host runs isolated agents; it never coordinates their work. */
+export interface OrganizationRuntimeHost {
+    start(): Promise<void>;
+    wake(request: OrganizationRuntimeWakeRequest): Promise<OrganizationRuntimeWakeResult>;
+    health(agentId?: string): Promise<OrganizationRuntimeHealth>;
+    activity(request: OrganizationRuntimeActivityRequest): Promise<OrganizationRuntimeActivityPage>;
+    stop(): Promise<OrganizationRuntimeShutdownCompletion>;
+}
+export { isOrganizationRuntimeConfig, parseOrganizationRuntimeConfig, parseOrganizationRuntimeWakeRequest, validateOrganizationRuntimeConfig } from "./organizationRuntimeParsing.js";
+//# sourceMappingURL=organizationRuntime.d.ts.map