@noopolis/daimon 0.1.2 → 0.2.1

package/dist/runtime/productionAgentTools.js

@@ -0,0 +1,336 @@
+import { spawn, readyTaskClockEnvironment } from "./taskClockProcess.js";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { moltnetOperationResult, readMoltnetPages } from "./moltnetMachineRead.js";
+import { McpToolCallError, MCP_TOOL_RESULT_MAX_BYTES, renderMcpToolResult, replayMcpReceipt } from "./mcpToolResult.js";
+import { ensureRuntimeHomeDirectory } from "./runtimeHomeLayout.js";
+import { capToolResult, resolveExemptToolNames, resolveToolResultMaxBytes, TOOL_OUTPUT_DIRECTORY_NAME } from "./toolResultSpill.js";
+import { cliChildEnvironment } from "../pi/cliEnvironment.js";
+import { taskClockChildEnvironment, taskClockProcessEnvironment, taskClockTimestamp } from "./taskClock.js";
+const MAX_RESULT = 65_536;
+const TIMEOUT = 10_000;
+/**
+ * Action and delivery identifiers are prefixed with a hyphen, never a colon.
+ *
+ * Moltnet's machine protocol rejects any identifier that parses as a scoped
+ * agent id, and `ParseScopedAgentID` treats *every* `left:right` string as one
+ * (`moltnet/pkg/protocol/identity.go`). A `daimon:<digest>` delivery id
+ * therefore failed `delivery_id must be a local id`, and the CLI answered
+ * `error: invalid request` for every send an agent ever attempted.
+ */
+const DAIMON_ACTION_ID_PREFIX = "daimon-";
+export async function createProductionAgentTools(agent, wakeContext = {}) {
+    taskClockChildEnvironment();
+    for (const server of agent.mcp ?? [])
+        taskClockChildEnvironment(server.env);
+    readyTaskClockEnvironment(cliChildEnvironment([], agent.runtimeHomePath));
+    await ensureRuntimeHomeDirectory(agent.runtimeHomePath, "tool-state");
+    // Resolved once, at agent start: a malformed bound is a configuration error
+    // that should refuse the agent, not a surprise thrown from the middle of a
+    // tool call the model is waiting on.
+    const cap = { maxBytes: resolveToolResultMaxBytes(), exempt: resolveExemptToolNames() };
+    const tools = [...await Promise.all((agent.mcp ?? []).map((server) => mcpTools(agent, server, wakeContext, cap)))].flat();
+    if (agent.moltnet !== undefined)
+        tools.push(moltnetTool(agent, wakeContext), moltnetReadTool(agent));
+    if (new Set(tools.map((tool) => tool.name)).size !== tools.length)
+        throw new Error("compiled cognition tool names collide");
+    return tools;
+}
+async function mcpTools(agent, server, wakeContext, cap) {
+    const { client, close } = await connect(agent, server);
+    const listed = await client.listTools(undefined, { timeout: TIMEOUT });
+    if (Buffer.byteLength(JSON.stringify(listed)) > MAX_RESULT) {
+        await close();
+        throw new Error(`MCP server ${server.name} tool list exceeds bound`);
+    }
+    const available = new Map(listed.tools.map((tool) => [tool.name, tool]));
+    const undeclared = [...available.keys()].filter((name) => !server.tools.includes(name));
+    if (undeclared.length > 0) {
+        await close();
+        throw new Error(`MCP server ${server.name} exposed undeclared tools`);
+    }
+    const missing = server.tools.filter((name) => !available.has(name));
+    if (missing.length > 0) {
+        await close();
+        throw new Error(`MCP server ${server.name} omitted declared tools`);
+    }
+    await close();
+    return server.tools.map((name) => {
+        const declared = available.get(name);
+        return {
+            name: mcpToolName(server.name, name),
+            label: `${server.name}: ${name}`,
+            description: declared.description ?? `Call declared MCP tool ${server.name}/${name}`,
+            parameters: declared.inputSchema,
+            async execute(_id, params) {
+                if (!wakeContext.current)
+                    throw new Error("MCP call requires an active wake");
+                const actionId = `${DAIMON_ACTION_ID_PREFIX}${createHash("sha256").update(JSON.stringify([wakeContext.current, agent.id, server.name, name, params])).digest("hex")}`;
+                const prior = await priorReceipt(agent, actionId);
+                if (prior !== undefined) {
+                    const replayed = replayMcpReceipt(server.name, name, prior);
+                    return { content: replayed.content, details: replayed.details };
+                }
+                const active = await connect(agent, server);
+                try {
+                    const result = await active.client.callTool({ name, arguments: params }, undefined, { timeout: TIMEOUT });
+                    const bytes = JSON.stringify(result);
+                    const envelope = { kind: "mcp", agent_id: agent.id, engine: agent.engine.kind, delivery_id: actionId, server: server.name, tool: name, digest: digest(bytes) };
+                    let rendered;
+                    try {
+                        // The SDK types this as a union with the pre-schema compatibility shape;
+                        // only the three fields `McpUpstreamResult` names are ever read.
+                        rendered = renderMcpToolResult({ server: server.name, tool: name, result: result, maxBytes: MCP_TOOL_RESULT_MAX_BYTES });
+                        // Every tool result stays in the transcript for every *subsequent*
+                        // model request of the wake, so one oversized answer is re-billed
+                        // once per remaining request. Above the bound the full payload goes
+                        // to disk and the model gets head+tail plus the path
+                        // (`toolResultSpill.ts`); at or below it, this returns `rendered`
+                        // itself and the passthrough contract is untouched.
+                        rendered = await capToolResult({
+                            toolName: mcpToolName(server.name, name),
+                            rendered,
+                            result: result,
+                            maxBytes: cap.maxBytes,
+                            exempt: cap.exempt,
+                            spillDirectory: path.join(agent.runtimeHomePath, TOOL_OUTPUT_DIRECTORY_NAME),
+                            spillId: actionId
+                        });
+                    }
+                    catch (error) {
+                        // The server's own reason is the receipt's payload as much as the
+                        // model's: a replayed failure has to fail for the same stated cause.
+                        if (error instanceof McpToolCallError)
+                            await receipt(agent, { ...envelope, is_error: true, error: error.reason });
+                        throw error;
+                    }
+                    await receipt(agent, { ...envelope, is_error: false, result: { content: rendered.content, details: rendered.details }, ...(rendered.truncated ? { truncated: true } : {}) });
+                    return { content: rendered.content, details: rendered.details };
+                }
+                finally {
+                    await active.close();
+                }
+            }
+        };
+    });
+}
+/**
+ * Reading a declared room is a native Moltnet machine operation. Without it an agent can
+ * only learn what a wake pushed at it, so any role that weighs several peers' messages
+ * has to be woken once per message instead of reading the room once.
+ *
+ * The whole payload goes in `details` as well as `content`, matching every other
+ * Daimon tool (`memoryTools.ts`, `worldTools.ts`). This tool was written by
+ * copying `moltnet_send`, whose useful payload genuinely *is* its details
+ * (`{"accepted":true}`) — but the MCP mount lowers `details` to
+ * `structuredContent` (`src/mcp/toolServer.ts`) and the engines render that in
+ * preference to `content`, so a read that put its messages only in `content`
+ * handed the model a bare `{"messages":5}` and dropped every message and the
+ * page cursor. It looked like a confused agent for a night; it was an empty tool.
+ */
+function moltnetReadTool(agent) {
+    return {
+        name: "moltnet_read", label: "Read a scoped Moltnet room or DM", description: "Read recent messages from one room or DM declared for this agent.",
+        parameters: { type: "object", additionalProperties: false, required: ["network", "target"], properties: { network: { type: "string" }, target: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 100 }, before: { type: "string" }, after: { type: "string" } } },
+        async execute(_id, params) {
+            const input = params;
+            const network = agent.moltnet.networks.find((entry) => entry.id === input.network);
+            if (network === undefined)
+                throw new Error("Moltnet action exceeds declared scope");
+            const [kind, target] = input.target.split(":", 2);
+            if ((kind === "room" && !network.rooms.includes(target ?? "")) || (kind === "dm" && !network.dms) || !target || !["room", "dm"].includes(kind ?? ""))
+                throw new Error("Moltnet target is not declared");
+            const read = await readMoltnetPages({
+                requested: input.limit ?? 20, maxBytes: MAX_RESULT,
+                ...(input.before === undefined ? {} : { before: input.before }),
+                ...(input.after === undefined ? {} : { after: input.after }),
+                fetch: (request) => moltnetReadPage(agent, input.network, kind, target, request)
+            });
+            const payload = {
+                target: read.target ?? { kind, id: target },
+                messages: read.messages,
+                message_count: read.messages.length,
+                page: {
+                    has_more: read.hasMore,
+                    ...(read.nextBefore === undefined ? {} : { next_before: read.nextBefore }),
+                    ...(read.nextAfter === undefined ? {} : { next_after: read.nextAfter })
+                },
+                ...(read.truncated === undefined ? {} : { truncated: read.truncated })
+            };
+            const bytes = JSON.stringify(payload);
+            if (Buffer.byteLength(bytes) > MAX_RESULT)
+                throw new Error("Moltnet read result exceeds bound");
+            return { content: [{ type: "text", text: bytes }], details: payload };
+        }
+    };
+}
+/** One `machine` read request, unwrapped onto the shape the pager consumes. */
+async function moltnetReadPage(agent, networkId, kind, target, request) {
+    const correlationId = `${DAIMON_ACTION_ID_PREFIX}${createHash("sha256").update(JSON.stringify([agent.id, networkId, kind, target, request.limit, request.before ?? "", request.after ?? ""])).digest("hex")}`;
+    const response = await machine(agent.moltnet.cliPath, agent.moltnet.configPath, networkId, {
+        version: "moltnet.machine.v1", correlation_id: correlationId, operation: "read",
+        read: { target: { kind, id: target }, limit: request.limit, ...(request.before === undefined ? {} : { before: request.before }), ...(request.after === undefined ? {} : { after: request.after }) }
+    });
+    const result = moltnetOperationResult(response, "read", "read");
+    if (result?.page?.messages === undefined)
+        throw new Error("Moltnet read was not accepted");
+    const info = result.page.page ?? {};
+    return {
+        ...(result.target === undefined ? {} : { target: result.target }),
+        messages: result.page.messages,
+        hasMore: info.has_more === true,
+        ...(typeof info.next_before === "string" ? { nextBefore: info.next_before } : {}),
+        ...(typeof info.next_after === "string" ? { nextAfter: info.next_after } : {})
+    };
+}
+function moltnetTool(agent, wakeContext) {
+    return {
+        name: "moltnet_send", label: "Send a scoped Moltnet message", description: "Send to one room or DM declared for this agent.",
+        parameters: { type: "object", additionalProperties: false, required: ["network", "target", "text"], properties: { network: { type: "string" }, target: { type: "string" }, text: { type: "string", minLength: 1, maxLength: 2048 } } },
+        async execute(_id, params) {
+            const input = params;
+            const network = agent.moltnet.networks.find((entry) => entry.id === input.network);
+            if (network === undefined || Buffer.byteLength(input.text) > 2_048)
+                throw new Error("Moltnet action exceeds declared scope");
+            const [kind, target] = input.target.split(":", 2);
+            if ((kind === "room" && !network.rooms.includes(target ?? "")) || (kind === "dm" && !network.dms) || !target || !["room", "dm"].includes(kind ?? ""))
+                throw new Error("Moltnet target is not declared");
+            if (!wakeContext.current)
+                throw new Error("Moltnet send requires an active wake");
+            const deliveryId = `${DAIMON_ACTION_ID_PREFIX}${createHash("sha256").update(JSON.stringify([wakeContext.current, agent.id, input.network, input.target, input.text])).digest("hex")}`;
+            const prior = await priorReceipt(agent, deliveryId);
+            if (prior !== undefined) {
+                wakeContext.spokeFor = wakeContext.current;
+                const visible = typeof prior.at === "string" ? { ...prior, at: taskClockTimestamp(prior.at) } : prior;
+                return { content: [{ type: "text", text: JSON.stringify(visible) }], details: visible };
+            }
+            const response = await machine(agent.moltnet.cliPath, agent.moltnet.configPath, input.network, { version: "moltnet.machine.v1", correlation_id: deliveryId, operation: "send_nudge", send_nudge: { delivery_id: deliveryId, target: { kind, id: target }, body: input.text } });
+            const result = moltnetOperationResult(response, "send_nudge", "send");
+            if (result?.accepted !== true || typeof result.message_id !== "string")
+                throw new Error("Moltnet send was not accepted");
+            await receipt(agent, { kind: "moltnet", agent_id: agent.id, engine: agent.engine.kind, delivery_id: deliveryId, network: input.network, target: input.target, message_id: result.message_id });
+            // An explicit send and the bridge's terminal-text fallback share one
+            // publication slot (moltnet AGENTS.md); recording that this wake spoke
+            // lets the wake-completion path blank the terminal text so it is not
+            // echoed as a second message.
+            wakeContext.spokeFor = wakeContext.current;
+            return { content: [{ type: "text", text: JSON.stringify({ accepted: true, message_id: result.message_id }) }], details: { accepted: true } };
+        }
+    };
+}
+async function connect(agent, server) {
+    taskClockChildEnvironment(server.env);
+    const client = new Client({ name: "daimon-production", version: "0.2.1" });
+    const headers = server.authSecretEnv === undefined ? {} : { authorization: `Bearer ${requiredSecret(server.authSecretEnv)}` };
+    const transport = server.transport === "stdio"
+        ? new StdioClientTransport({ command: server.command, args: [...server.args], env: stringEnvironment(readyTaskClockEnvironment({ ...server.env, ...cliChildEnvironment([], agent.runtimeHomePath, { executablePath: server.command }) })) })
+        : server.transport === "sse" ? new SSEClientTransport(new URL(server.url), { requestInit: { headers } })
+            : new StreamableHTTPClientTransport(new URL(server.url), { requestInit: { headers } });
+    await client.connect(transport);
+    return { client, close: () => client.close() };
+}
+function requiredSecret(name) { const value = process.env[name]; if (!value)
+    throw new Error(`required MCP secret ${name} is missing`); return value; }
+function receiptPath(agent, deliveryId) { return path.join(agent.runtimeHomePath, "tool-state", `${digest(deliveryId).slice(7)}.json`); }
+async function receipt(agent, value) { const deliveryId = String(value.delivery_id); const file = receiptPath(agent, deliveryId); const temporary = `${file}.${process.pid}.${Date.now()}.tmp`; const bytes = `${JSON.stringify({ ...value, at: new Date().toISOString() })}\n`; if (Buffer.byteLength(bytes) > MAX_RESULT)
+    throw new Error("tool receipt exceeds bound"); const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+}
+finally {
+    await handle.close();
+} try {
+    await rename(temporary, file);
+    await pruneReceipts(path.dirname(file));
+    const directory = await open(path.dirname(file), constants.O_RDONLY);
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+catch (error) {
+    await unlink(temporary).catch(() => undefined);
+    throw error;
+} }
+async function pruneReceipts(directory) { const candidates = await Promise.all((await readdir(directory)).filter((name) => /^[a-f0-9]{64}\.json$/u.test(name)).map(async (name) => ({ name, info: await lstat(path.join(directory, name)) }))); if (candidates.some(({ info }) => !info.isFile() || info.nlink !== 1))
+    throw new Error("tool receipt directory contains an unsafe entry"); for (const candidate of candidates.sort((left, right) => right.info.mtimeMs - left.info.mtimeMs || right.name.localeCompare(left.name)).slice(2048))
+    await unlink(path.join(directory, candidate.name)); }
+async function priorReceipt(agent, deliveryId) { const file = receiptPath(agent, deliveryId); let handle; try {
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+}
+catch (error) {
+    if (error.code === "ENOENT")
+        return undefined;
+    throw error;
+} try {
+    const entry = await handle.stat();
+    if (!entry.isFile() || entry.size > MAX_RESULT)
+        throw new Error("tool receipt is unsafe or exceeds bound");
+    const value = JSON.parse(await handle.readFile("utf8"));
+    if (value.delivery_id !== deliveryId || value.agent_id !== agent.id || value.engine !== agent.engine.kind)
+        throw new Error("tool receipt identity mismatch");
+    return value;
+}
+finally {
+    await handle.close();
+} }
+/**
+ * One request/response exchange with `moltnet machine`.
+ *
+ * Stdin is held open until the response line arrives. `moltnet machine` treats
+ * end-of-input as cancellation of everything still in flight, so ending stdin
+ * with the request — as this did — raced the send and lost: the CLI answered
+ * `{"error":{"code":"canceled"}}` and no message was ever delivered. The
+ * operation is complete once its line is on stdout, so closing stdin there can
+ * no longer cancel it.
+ */
+async function machine(cli, config, network, request) {
+    const clockEnvironment = taskClockChildEnvironment();
+    return await new Promise((resolve, reject) => {
+        const child = spawn(cli, ["machine", "--config", config, "--network", network], { stdio: ["pipe", "pipe", "pipe"], env: taskClockProcessEnvironment(process.env, clockEnvironment) });
+        let output = "", error = "", settled = false;
+        const settle = (action) => { if (settled)
+            return; settled = true; clearTimeout(timer); action(); };
+        const timer = setTimeout(() => { child.kill("SIGKILL"); settle(() => reject(new Error("Moltnet machine timed out"))); }, TIMEOUT);
+        child.stdin.on("error", () => undefined);
+        child.stdout.on("data", (chunk) => {
+            output += chunk;
+            if (Buffer.byteLength(output) > MAX_RESULT) {
+                child.kill("SIGKILL");
+                settle(() => reject(new Error("Moltnet machine response exceeds bound")));
+                return;
+            }
+            const newline = output.indexOf("\n");
+            if (newline < 0)
+                return;
+            const line = output.slice(0, newline).trim();
+            if (line.length === 0)
+                return;
+            child.stdin.end();
+            settle(() => { try {
+                resolve(JSON.parse(line));
+            }
+            catch (cause) {
+                reject(cause);
+            } });
+            child.kill("SIGTERM");
+        });
+        child.stderr.on("data", (chunk) => { error += chunk; });
+        child.once("error", (cause) => settle(() => reject(cause)));
+        child.once("exit", () => settle(() => reject(new Error(`Moltnet machine failed: ${(error.slice(0, 1024) || "no response").trim()}`))));
+        child.stdin.write(`${JSON.stringify(request)}\n`);
+    });
+}
+function digest(value) { return `sha256:${createHash("sha256").update(value).digest("hex")}`; }
+/** The mounted name of one declared MCP tool: the one place it is spelled. */
+function mcpToolName(server, tool) { return `mcp_${safe(server)}_${safe(tool)}`; }
+function safe(value) { return value.replace(/[^A-Za-z0-9_]/gu, "_").slice(0, 48); }
+function stringEnvironment(value) { return Object.fromEntries(Object.entries(value).filter((entry) => entry[1] !== undefined)); }

package/dist/runtime/relocateRuntimeConfig.d.ts

@@ -0,0 +1,14 @@
+import { type OrganizationRuntimeConfig } from "./organizationRuntime.js";
+export type RuntimeConfigLocation = Readonly<{
+    workspace: string;
+    home: string;
+    memory: string;
+    /** Both paths are explicit: runtime config declares no control-token file. */
+    controlToken: Readonly<{
+        from: string;
+        to: string;
+    }>;
+}>;
+/** Rebase one memory-backed agent's path prefixes, preserving instructions verbatim. */
+export declare function relocateRuntimeConfig(config: OrganizationRuntimeConfig, location: RuntimeConfigLocation): OrganizationRuntimeConfig;
+//# sourceMappingURL=relocateRuntimeConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relocateRuntimeConfig.d.ts","sourceRoot":"","sources":["../../src/runtime/relocateRuntimeConfig.ts"],"names":[],"mappings":"AACA,OAAO,EAAkC,KAAK,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAE1G,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,YAAY,EAAE,QAAQ,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD,CAAC,CAAC;AAEH,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,yBAAyB,EAAE,QAAQ,EAAE,qBAAqB,GAAG,yBAAyB,CA8BnI"}

package/dist/runtime/relocateRuntimeConfig.js

@@ -0,0 +1,38 @@
+import { posix } from "node:path";
+import { parseOrganizationRuntimeConfig } from "./organizationRuntime.js";
+/** Rebase one memory-backed agent's path prefixes, preserving instructions verbatim. */
+export function relocateRuntimeConfig(config, location) {
+    const parsed = parseOrganizationRuntimeConfig(config);
+    const agent = parsed.agents[0];
+    if (parsed.agents.length !== 1 || !agent?.memory)
+        throw new TypeError("Relocation requires one memory-backed agent");
+    const mappings = [
+        [agent.workspacePath, location.workspace],
+        [agent.runtimeHomePath, location.home],
+        [agent.memory.runtimeHomePath, location.memory],
+        [location.controlToken.from, location.controlToken.to]
+    ];
+    for (const pair of mappings)
+        for (const value of pair) {
+            if (typeof value !== "string" || !posix.isAbsolute(value) || posix.normalize(value) !== value || value === "/" || value.endsWith("/") || value.includes("\\") || value.includes("\0")) {
+                throw new TypeError("Relocation paths must be canonical absolute POSIX paths other than root");
+            }
+        }
+    // Memory may live below home; the most specific source must own that subtree.
+    const ordered = [...mappings].sort(([a], [b]) => b.length - a.length);
+    if (new Set(ordered.map(([source]) => source)).size !== ordered.length)
+        throw new TypeError("Relocation source paths must be distinct");
+    const relocate = (value) => {
+        if (typeof value === "string") {
+            const mapping = ordered.find(([source]) => value === source || value.startsWith(`${source}/`));
+            return mapping ? mapping[1] + value.slice(mapping[0].length) : value;
+        }
+        if (Array.isArray(value))
+            return value.map(relocate);
+        if (value !== null && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, key === "instructions" ? item : relocate(item)]));
+        }
+        return value;
+    };
+    return parseOrganizationRuntimeConfig(relocate(parsed));
+}

package/dist/runtime/runtimeHomeLayout.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Mode for every directory Daimon creates inside an agent's runtime home.
+ *
+ * A brokered Grok agent's runtime home is `0710`
+ * (`GROK_ENGINE_BROKER.worker.home.organizationRuntimeHome`) so its sandboxed
+ * worker can traverse into the setgid `tool-output/` spill directory. Traverse
+ * is all it may have: anything Daimon creates in that home — telemetry traces
+ * (prompts, replies, world trajectories), tool state, receipts, the engine's
+ * XDG directories and the private `.tmp` — stays `0700`, so a default
+ * `mkdir` (0755 under the usual umask) never turns a traversable home into a
+ * readable one.
+ */
+export declare const RUNTIME_HOME_SUBDIRECTORY_MODE = 448;
+/**
+ * The home itself, created if it is absent and otherwise left exactly as it is.
+ *
+ * Create-only is the whole contract here. A brokered Grok agent's home is
+ * deliberately `0710` and an organization's may be `0700`; which of the two is
+ * correct is `physicalReadiness.ts`'s judgement, made against the agent's
+ * declared engine, and a layout helper that "corrected" a traversable home to
+ * `0700` would break the worker's only route to its own spills.
+ */
+export declare const ensureRuntimeHome: (runtimeHomePath: string) => Promise<string>;
+/**
+ * One directory Daimon owns *below* a runtime home, private on every install.
+ *
+ * `mkdir(..., { mode })` decides nothing for a directory that already exists,
+ * and that is the common case rather than the exotic one: a `telemetry/` left
+ * at `0755` by a pre-branch Daimon, or pre-created by a deployment, stayed
+ * `0755` forever. Under a Grok agent's traversable `0710` home that is the
+ * worker reading its own agent's prompts, replies and causal history — the
+ * home is traverse-only precisely so that nothing but `tool-output/` is
+ * readable. `assertRuntimeDirectory` checks the home, and nothing checked what
+ * Daimon created inside it.
+ *
+ * So every level below the home is asserted and corrected on the way down,
+ * through a handle rather than a path: `O_DIRECTORY|O_NOFOLLOW` refuses a
+ * symlink planted where a directory belongs, and the `fchmod` that follows
+ * lands on the directory that was stat'd. A directory owned by anyone but the
+ * runtime user is **refused**, never widened and never silently accepted — the
+ * runtime cannot make someone else's directory private, and proceeding would
+ * write an agent's telemetry into it anyway.
+ *
+ * `owner` is a seam so both refusals are testable unprivileged, exactly as
+ * `physicalReadiness.ts`'s `RuntimeIdentity` is.
+ */
+export declare function ensureRuntimeHomeDirectory(runtimeHomePath: string, relative: string, owner?: number): Promise<string>;
+//# sourceMappingURL=runtimeHomeLayout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeHomeLayout.d.ts","sourceRoot":"","sources":["../../src/runtime/runtimeHomeLayout.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,MAAQ,CAAC;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAU,iBAAiB,MAAM,KAAG,OAAO,CAAC,MAAM,CAG/E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,0BAA0B,CAAC,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,GAAE,MAAiC,GAAG,OAAO,CAAC,MAAM,CAAC,CAcrJ"}

package/dist/runtime/runtimeHomeLayout.js

@@ -0,0 +1,84 @@
+import { constants } from "node:fs";
+import { mkdir, open } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Mode for every directory Daimon creates inside an agent's runtime home.
+ *
+ * A brokered Grok agent's runtime home is `0710`
+ * (`GROK_ENGINE_BROKER.worker.home.organizationRuntimeHome`) so its sandboxed
+ * worker can traverse into the setgid `tool-output/` spill directory. Traverse
+ * is all it may have: anything Daimon creates in that home — telemetry traces
+ * (prompts, replies, world trajectories), tool state, receipts, the engine's
+ * XDG directories and the private `.tmp` — stays `0700`, so a default
+ * `mkdir` (0755 under the usual umask) never turns a traversable home into a
+ * readable one.
+ */
+export const RUNTIME_HOME_SUBDIRECTORY_MODE = 0o700;
+/**
+ * The home itself, created if it is absent and otherwise left exactly as it is.
+ *
+ * Create-only is the whole contract here. A brokered Grok agent's home is
+ * deliberately `0710` and an organization's may be `0700`; which of the two is
+ * correct is `physicalReadiness.ts`'s judgement, made against the agent's
+ * declared engine, and a layout helper that "corrected" a traversable home to
+ * `0700` would break the worker's only route to its own spills.
+ */
+export const ensureRuntimeHome = async (runtimeHomePath) => {
+    await mkdir(runtimeHomePath, { recursive: true, mode: RUNTIME_HOME_SUBDIRECTORY_MODE });
+    return runtimeHomePath;
+};
+/**
+ * One directory Daimon owns *below* a runtime home, private on every install.
+ *
+ * `mkdir(..., { mode })` decides nothing for a directory that already exists,
+ * and that is the common case rather than the exotic one: a `telemetry/` left
+ * at `0755` by a pre-branch Daimon, or pre-created by a deployment, stayed
+ * `0755` forever. Under a Grok agent's traversable `0710` home that is the
+ * worker reading its own agent's prompts, replies and causal history — the
+ * home is traverse-only precisely so that nothing but `tool-output/` is
+ * readable. `assertRuntimeDirectory` checks the home, and nothing checked what
+ * Daimon created inside it.
+ *
+ * So every level below the home is asserted and corrected on the way down,
+ * through a handle rather than a path: `O_DIRECTORY|O_NOFOLLOW` refuses a
+ * symlink planted where a directory belongs, and the `fchmod` that follows
+ * lands on the directory that was stat'd. A directory owned by anyone but the
+ * runtime user is **refused**, never widened and never silently accepted — the
+ * runtime cannot make someone else's directory private, and proceeding would
+ * write an agent's telemetry into it anyway.
+ *
+ * `owner` is a seam so both refusals are testable unprivileged, exactly as
+ * `physicalReadiness.ts`'s `RuntimeIdentity` is.
+ */
+export async function ensureRuntimeHomeDirectory(runtimeHomePath, relative, owner = process.getuid?.() ?? -1) {
+    const segments = relative.split("/").filter((segment) => segment.length > 0);
+    if (segments.length === 0 || segments.some((segment) => segment === "." || segment === "..")) {
+        throw new Error(`runtime home subdirectory must name a path below the home: ${relative}`);
+    }
+    let current = await ensureRuntimeHome(runtimeHomePath);
+    for (const segment of segments) {
+        current = path.join(current, segment);
+        await mkdir(current, { mode: RUNTIME_HOME_SUBDIRECTORY_MODE }).catch((error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+        await assertPrivateDirectory(current, owner);
+    }
+    return current;
+}
+const flag = (name) => constants[name] ?? 0;
+async function assertPrivateDirectory(directory, owner) {
+    const handle = await open(directory, constants.O_RDONLY | flag("O_DIRECTORY") | flag("O_NOFOLLOW"));
+    try {
+        const entry = await handle.stat();
+        if (!entry.isDirectory())
+            throw new Error(`runtime home path is not a directory: ${directory}`);
+        if (entry.uid !== owner)
+            throw new Error(`runtime home subdirectory must be owned by the runtime user: ${directory}`);
+        if ((entry.mode & 0o7777) !== RUNTIME_HOME_SUBDIRECTORY_MODE)
+            await handle.chmod(RUNTIME_HOME_SUBDIRECTORY_MODE);
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/runtime/schedule.d.ts

@@ -0,0 +1,40 @@
+import type { OrganizationRuntimeAgentConfig, OrganizationRuntimeSchedule } from "./organizationRuntime.js";
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+export type ScheduledOccurrence = Readonly<{
+    agentId: string;
+    deliveryId: string;
+    occurredAt: string;
+    prompt: string;
+}>;
+type ActiveSchedule = Exclude<OrganizationRuntimeSchedule, {
+    kind: "disabled";
+}>;
+type Timer = ReturnType<typeof setTimeout>;
+export type ScheduleController = Readonly<{
+    start(): Promise<void>;
+    drain(agentId?: string): Promise<void>;
+    stop(): Promise<void>;
+}>;
+export type ScheduleControllerOptions = Readonly<{
+    acceptanceStorePath: string;
+    agents: readonly OrganizationRuntimeAgentConfig[];
+    /** False means the agent is busy; the durable latest-pending slot remains. */
+    accept(occurrence: ScheduledOccurrence): Promise<boolean | void>;
+    now?: () => number;
+    /** Draws the fractional jitter offset; defaults to `Math.random`. Injectable so tests can assert bounds/independence without real randomness. */
+    random?: () => number;
+    setTimer?: (callback: () => void, delayMs: number) => Timer;
+    clearTimer?: (timer: Timer) => void;
+    /** @internal Observable durability stages for focused crash-order tests. */
+    onPersistStageForTest?: (stage: "write" | "file-sync" | "rename" | "directory-sync") => void;
+}>;
+/** Schedules create durable pending occurrences; engine execution remains elsewhere. */
+export declare function createScheduleController(options: ScheduleControllerOptions): ScheduleController;
+export declare function occurrenceFor(agentId: string, schedule: ActiveSchedule, at: number): ScheduledOccurrence;
+export declare function isCanonicalScheduleDeliveryId(value: string): boolean;
+export declare function nextOccurrence(agentId: string, schedule: ActiveSchedule, anchor: number | undefined, from: number): number;
+export declare function cronIsPossible(cron: string): boolean;
+/** Independent per-arming offset in `[0, jitter_seconds * 1000]`; absent/zero jitter always yields exactly 0. */
+export declare function jitterOffsetMs(schedule: ActiveSchedule | undefined, random: () => number): number;
+export {};
+//# sourceMappingURL=schedule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/runtime/schedule.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,8BAA8B,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAK5G,eAAO,MAAM,kBAAkB,aAAgB,CAAC;AAKhD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AACxH,KAAK,cAAc,GAAG,OAAO,CAAC,2BAA2B,EAAE;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC;AAGjF,KAAK,KAAK,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAE3C,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAAC;AACrI,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,SAAS,8BAA8B,EAAE,CAAC;IAClD,8EAA8E;IAC9E,MAAM,CAAC,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACjE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,iJAAiJ;IACjJ,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;IAC5D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACpC,4EAA4E;IAC5E,qBAAqB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,gBAAgB,KAAK,IAAI,CAAC;CAC9F,CAAC,CAAC;AAEH,wFAAwF;AACxF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CA8F/F;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,mBAAmB,CAIxG;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKpE;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAY1H;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAA8E;AAEnI,iHAAiH;AACjH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,MAAM,GAAG,MAAM,CAKjG"}