@noopolis/daimon 0.1.1 → 0.2.0

package/dist/mcp/toolServer.js

@@ -0,0 +1,145 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+export class McpToolTurnLimitError extends Error {
+    constructor(maxToolTurns) {
+        super(`McpToolTurnLimitError: maximum ${maxToolTurns} calls per wake`);
+        this.name = "McpToolTurnLimitError";
+    }
+}
+export class McpWakeDeadlineError extends Error {
+    constructor() {
+        super("McpWakeDeadlineError: wake deadline exceeded");
+        this.name = "McpWakeDeadlineError";
+    }
+}
+/**
+ * A non-standard request AGY issues during its MCP handshake.
+ *
+ * Captured live from `agy --print … --output-format stream-json`, the client
+ * sends `initialize`, `notifications/initialized`, **`server/discover`**,
+ * `tools/list`, `tools/call`. `server/discover` is not in the MCP
+ * specification, and the throwaway probe that proved AGY's headless tool
+ * calling answered it with `{}`. Codex and Grok never send it.
+ *
+ * This server answers it the same way that working probe did, rather than the
+ * SDK default of `MethodNotFound`, because a refusal here is the one observable
+ * difference between this server and the one AGY is known to work against, and
+ * the cost of being wrong is that every AGY agent silently loses every tool.
+ * The allowance is exactly this one method: any other unknown method still gets
+ * `MethodNotFound`, so a genuine protocol mistake is never hidden.
+ */
+export const AGY_SERVER_DISCOVER_METHOD = "server/discover";
+const jsonSchema = (parameters) => {
+    if (parameters === null || typeof parameters !== "object" || Array.isArray(parameters)) {
+        throw new TypeError("Pi tool parameters must be a JSON schema object");
+    }
+    return Object.fromEntries(Object.entries(parameters));
+};
+const toolResult = (result) => ({
+    content: result.content,
+    ...(result.details !== undefined && typeof result.details === "object" && result.details !== null
+        ? { structuredContent: Object.fromEntries(Object.entries(result.details)) }
+        : {})
+});
+/** Bound on the rendered Ajv violations, so a pathological schema cannot flood a turn. */
+const MAX_SCHEMA_VIOLATION_BYTES = 2_048;
+/**
+ * Why the arguments were rejected, in the schema's own words.
+ *
+ * A bare `Invalid arguments for tool X` tells an agent that its call was wrong
+ * and nothing about how, which leaves trial and error as the only way to learn
+ * a tool's argument shape. Ajv already knows which instance path failed and
+ * which keyword it failed on; saying so turns a guessing loop into one
+ * correction.
+ */
+const schemaViolations = (validator) => {
+    const rendered = (validator.errors ?? [])
+        .map((issue) => `${issue.instancePath === "" ? "(root)" : issue.instancePath} ${issue.message ?? "is invalid"}`.trim())
+        .join("; ");
+    if (rendered.length === 0)
+        return "the arguments do not match the tool's declared input schema";
+    return rendered.length > MAX_SCHEMA_VIOLATION_BYTES ? `${rendered.slice(0, MAX_SCHEMA_VIOLATION_BYTES)}…` : rendered;
+};
+const toolError = (error) => ({
+    content: [{ type: "text", text: error instanceof Error ? `${error.name}: ${error.message}` : String(error) }],
+    isError: true
+});
+// Pi's ExtensionContext has no meaning outside a Pi session. Mounted tools
+// must not read it; this named value documents the explicit absence.
+// The MCP mount deliberately has no Pi session context; `never` preserves typed positional checks.
+const NO_PI_EXTENSION_CONTEXT = undefined;
+const validateOptions = (options) => {
+    if (options.maxToolTurns !== undefined && (!Number.isSafeInteger(options.maxToolTurns) || options.maxToolTurns < 1)) {
+        throw new TypeError("maxToolTurns must be a positive safe integer");
+    }
+    if (options.wakeDeadline !== undefined && !Number.isFinite(options.wakeDeadline)) {
+        throw new TypeError("wakeDeadline must be a finite epoch-millisecond deadline");
+    }
+};
+export const createPiToolMcpServer = (tools, options) => {
+    validateOptions(options);
+    const server = new Server({ name: "daimon-pi-tools", version: "0.1.2" });
+    server.fallbackRequestHandler = async (request) => {
+        if (request.method !== AGY_SERVER_DISCOVER_METHOD) {
+            throw new McpError(ErrorCode.MethodNotFound, `Method not found: ${request.method}`);
+        }
+        return {};
+    };
+    const validators = new Map(tools.map((tool) => {
+        const schema = jsonSchema(tool.parameters);
+        return [tool.name, new Ajv2020({ strict: false }).compile(schema)];
+    }));
+    let toolTurns = 0;
+    server.registerCapabilities({ tools: { listChanged: true } });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            title: tool.label,
+            description: tool.description,
+            inputSchema: jsonSchema(tool.parameters)
+        }))
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        try {
+            if (options.wakeDeadline !== undefined && Date.now() >= options.wakeDeadline)
+                throw new McpWakeDeadlineError();
+            if (options.maxToolTurns !== undefined && toolTurns >= options.maxToolTurns)
+                throw new McpToolTurnLimitError(options.maxToolTurns);
+            const tool = tools.find((candidate) => candidate.name === request.params.name);
+            const validator = validators.get(request.params.name);
+            if (tool === undefined || validator === undefined) {
+                throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);
+            }
+            const args = request.params.arguments ?? {};
+            if (!validator(args)) {
+                throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for tool ${tool.name}: ${schemaViolations(validator)}`);
+            }
+            toolTurns += 1;
+            // Ajv validated this value against this tool's own schema immediately above.
+            const validatedArgs = args;
+            const deadlineController = options.wakeDeadline === undefined ? undefined : new AbortController();
+            const remainingMs = options.wakeDeadline === undefined ? undefined : Math.max(0, options.wakeDeadline - Date.now());
+            const deadlineTimer = deadlineController === undefined ? undefined : setTimeout(() => deadlineController.abort(), remainingMs);
+            const signal = deadlineController === undefined ? extra.signal
+                : extra.signal === undefined ? deadlineController.signal : AbortSignal.any([extra.signal, deadlineController.signal]);
+            const deadline = deadlineController === undefined ? undefined : new Promise((_resolve, reject) => {
+                deadlineController.signal.addEventListener("abort", () => reject(new McpWakeDeadlineError()), { once: true });
+            });
+            let result;
+            try {
+                const execution = tool.execute(`mcp-tool-turn-${toolTurns}`, validatedArgs, signal, undefined, NO_PI_EXTENSION_CONTEXT);
+                result = deadline === undefined ? await execution : await Promise.race([execution, deadline]);
+            }
+            finally {
+                if (deadlineTimer !== undefined)
+                    clearTimeout(deadlineTimer);
+            }
+            return toolResult(result);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    return server;
+};

package/dist/observability/causalEvents.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Daimon's own copy of the `noopolis.causal-event.v1` wire envelope. Field-
+ * for-field the canonical shape in `specs/causal-event.v1.schema.json` and
+ * `specs/CAUSAL.md` (root repo) — daimon is an independent repo and does not
+ * import that schema, it only conforms to it. The wire JSON emitted by
+ * `appendCausalEvent` is the actual contract; this type is local sugar over
+ * it.
+ */
+export declare const CAUSAL_EVENT_VERSION: "noopolis.causal-event.v1";
+export type CausalEventSystem = "simfile" | "moltnet" | "mneme" | "daimon";
+export interface CausalEventEmitter {
+    system: CausalEventSystem;
+    stream_id: string;
+    seq: number;
+}
+export interface CausalEvent<TPayload = Record<string, unknown>> {
+    cause_event_ids: string[];
+    emitter: CausalEventEmitter;
+    event_id: string;
+    payload: TPayload;
+    principal_id: string;
+    recorded_at: string;
+    run_id: string;
+    type: string;
+    version: typeof CAUSAL_EVENT_VERSION;
+}
+/** Payload for `turn.input.submitted`, stamped just before a Pi session prompt call. */
+export interface TurnInputSubmittedPayload extends Record<string, unknown> {
+    input_content_sha256: string;
+    input_message_ids: string[];
+    prompt_sha256: string;
+    turn_id: string;
+}
+/** Payload for `turn.output.completed`, stamped once a Pi turn finishes successfully. */
+export interface TurnOutputCompletedPayload extends Record<string, unknown> {
+    output_sha256: string;
+    turn_id: string;
+}
+export declare const TURN_INPUT_SUBMITTED_TYPE: "turn.input.submitted";
+export declare const TURN_OUTPUT_COMPLETED_TYPE: "turn.output.completed";
+/** Name of the environment variable every Noopolis authority reads `run_id` from. Never model output. */
+export declare const NOOPOLIS_RUN_ID_ENV = "NOOPOLIS_RUN_ID";
+/**
+ * Resolves `run_id` from the `NOOPOLIS_RUN_ID` environment variable, per
+ * `specs/CAUSAL.md`. Never derived from a WakeEvent, model output, or any
+ * other in-turn data. A causal event cannot be emitted without a real run id.
+ */
+export declare const resolveRunId: (env?: NodeJS.ProcessEnv) => string;
+export declare const sha256Hex: (value: string) => string;
+/** Deterministic, non-model-derived event id for a turn's `turn.input.submitted` record. */
+export declare const turnInputSubmittedEventId: (turnId: string) => string;
+/** Deterministic, non-model-derived event id for a turn's `turn.output.completed` record. */
+export declare const turnOutputCompletedEventId: (turnId: string) => string;
+/**
+ * The `cause_event_ids` an outbound Moltnet reply for `turnId` should carry.
+ * Pure and deterministic from `turn_id` alone — the harness owns this value,
+ * never the model. Daimon does not construct Moltnet `SendMessageRequest`
+ * values itself (see repo AGENTS.md: Moltnet wiring belongs to the caller,
+ * not this package), so this helper is what a caller sending the reply on
+ * Daimon's behalf attaches to that request's `cause_event_ids`.
+ */
+export declare const replyCauseEventIds: (turnId: string) => string[];
+/**
+ * Allocates the next contiguous seq number for `(run_id, stream_id)`,
+ * persisted under `runtimeHome/telemetry/causal.seq.json`. Allocation is
+ * serialized in-process and mutually excluded across processes by a lock
+ * file; the counter is written atomically and fsynced.
+ */
+export declare const nextCausalSeq: (input: {
+    runId: string;
+    runtimeHomePath: string;
+    streamId: string;
+}) => Promise<number>;
+/** Appends one CausalEvent record as a line of `runtimeHome/telemetry/causal.jsonl`. */
+export declare const appendCausalEvent: (runtimeHomePath: string, event: CausalEvent) => Promise<void>;
+export interface EmitCausalEventInput<TPayload extends Record<string, unknown>> {
+    agentId: string;
+    causeEventIds: string[];
+    eventId: string;
+    payload: TPayload;
+    principalId: string;
+    runId: string;
+    runtimeHomePath: string;
+    type: string;
+}
+/**
+ * Stamps and appends one causal event for this agent's stream
+ * (`agent:<agentId>`). `run_id` and `principal_id` are always caller-
+ * supplied values (never read from `payload` or model output) — see
+ * `piHarness.ts`, which is the only caller and always passes the resolved
+ * `NOOPOLIS_RUN_ID` and the authenticated agent identity.
+ */
+export declare const emitCausalEvent: <TPayload extends Record<string, unknown>>(input: EmitCausalEventInput<TPayload>) => Promise<CausalEvent<TPayload>>;
+export interface EmitTurnInputSubmittedInput {
+    agentId: string;
+    causeEventIds: string[];
+    inputContentSha256: string;
+    inputMessageIds: string[];
+    principalId: string;
+    promptSha256: string;
+    runId: string;
+    runtimeHomePath: string;
+    turnId: string;
+}
+/** Stamps `turn.input.submitted` for one Pi turn, right before the engine prompt call. */
+export declare const emitTurnInputSubmitted: (input: EmitTurnInputSubmittedInput) => Promise<CausalEvent<TurnInputSubmittedPayload>>;
+export interface EmitTurnOutputCompletedInput {
+    agentId: string;
+    causeEventIds: string[];
+    outputSha256: string;
+    principalId: string;
+    runId: string;
+    runtimeHomePath: string;
+    turnId: string;
+}
+/** Stamps `turn.output.completed` once a Pi turn finishes successfully. */
+export declare const emitTurnOutputCompleted: (input: EmitTurnOutputCompletedInput) => Promise<CausalEvent<TurnOutputCompletedPayload>>;
+//# sourceMappingURL=causalEvents.d.ts.map

package/dist/observability/causalEvents.d.ts.map

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

package/dist/observability/causalEvents.js

@@ -0,0 +1,223 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { appendFile, open, readFile, rename, stat, unlink } from "node:fs/promises";
+import path from "node:path";
+import { ensureRuntimeHomeDirectory } from "../runtime/runtimeHomeLayout.js";
+/**
+ * Daimon's own copy of the `noopolis.causal-event.v1` wire envelope. Field-
+ * for-field the canonical shape in `specs/causal-event.v1.schema.json` and
+ * `specs/CAUSAL.md` (root repo) — daimon is an independent repo and does not
+ * import that schema, it only conforms to it. The wire JSON emitted by
+ * `appendCausalEvent` is the actual contract; this type is local sugar over
+ * it.
+ */
+export const CAUSAL_EVENT_VERSION = "noopolis.causal-event.v1";
+export const TURN_INPUT_SUBMITTED_TYPE = "turn.input.submitted";
+export const TURN_OUTPUT_COMPLETED_TYPE = "turn.output.completed";
+/** Name of the environment variable every Noopolis authority reads `run_id` from. Never model output. */
+export const NOOPOLIS_RUN_ID_ENV = "NOOPOLIS_RUN_ID";
+/**
+ * Resolves `run_id` from the `NOOPOLIS_RUN_ID` environment variable, per
+ * `specs/CAUSAL.md`. Never derived from a WakeEvent, model output, or any
+ * other in-turn data. A causal event cannot be emitted without a real run id.
+ */
+export const resolveRunId = (env = process.env) => {
+    const value = env[NOOPOLIS_RUN_ID_ENV];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${NOOPOLIS_RUN_ID_ENV} must be set to a non-blank value`);
+    }
+    return value.trim();
+};
+export const sha256Hex = (value) => createHash("sha256").update(value, "utf8").digest("hex");
+/** Deterministic, non-model-derived event id for a turn's `turn.input.submitted` record. */
+export const turnInputSubmittedEventId = (turnId) => `daimon:${turnId}:turn.input.submitted`;
+/** Deterministic, non-model-derived event id for a turn's `turn.output.completed` record. */
+export const turnOutputCompletedEventId = (turnId) => `daimon:${turnId}:turn.output.completed`;
+/**
+ * The `cause_event_ids` an outbound Moltnet reply for `turnId` should carry.
+ * Pure and deterministic from `turn_id` alone — the harness owns this value,
+ * never the model. Daimon does not construct Moltnet `SendMessageRequest`
+ * values itself (see repo AGENTS.md: Moltnet wiring belongs to the caller,
+ * not this package), so this helper is what a caller sending the reply on
+ * Daimon's behalf attaches to that request's `cause_event_ids`.
+ */
+export const replyCauseEventIds = (turnId) => [turnOutputCompletedEventId(turnId)];
+const telemetryDir = (runtimeHomePath) => path.join(runtimeHomePath, "telemetry");
+const seqFilePath = (runtimeHomePath) => path.join(telemetryDir(runtimeHomePath), "causal.seq.json");
+const jsonlFilePath = (runtimeHomePath) => path.join(telemetryDir(runtimeHomePath), "causal.jsonl");
+const STALE_LOCK_MS = 30_000;
+const seqAllocationQueues = new Map();
+const readSeqStore = async (runtimeHomePath) => {
+    try {
+        const raw = await readFile(seqFilePath(runtimeHomePath), "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+};
+const writeSeqStore = async (runtimeHomePath, store) => {
+    const directory = await ensureRuntimeHomeDirectory(runtimeHomePath, "telemetry");
+    const file = seqFilePath(runtimeHomePath);
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(store, null, 2)}\n`, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, file);
+        await syncDirectory(directory);
+    }
+    finally {
+        await unlink(temporary).catch((error) => {
+            if (error.code !== "ENOENT")
+                throw error;
+        });
+    }
+};
+const syncDirectory = async (directory) => {
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const acquireSeqLock = async (lockPath) => {
+    const startedAt = Date.now();
+    let backoffMs = 2;
+    while (Date.now() - startedAt < 5_000) {
+        try {
+            const handle = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+            await handle.close();
+            return;
+        }
+        catch (error) {
+            if (!(error && typeof error === "object" && "code" in error && error.code === "EEXIST"))
+                throw error;
+        }
+        try {
+            const observed = await stat(lockPath);
+            if (Date.now() - observed.mtimeMs > STALE_LOCK_MS) {
+                const confirmed = await stat(lockPath);
+                if (confirmed.mtimeMs === observed.mtimeMs) {
+                    await unlink(lockPath).catch((error) => {
+                        if (error.code !== "ENOENT")
+                            throw error;
+                    });
+                    continue;
+                }
+            }
+        }
+        catch (error) {
+            if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT"))
+                throw error;
+            continue;
+        }
+        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+        backoffMs = Math.min(backoffMs * 2, 25);
+    }
+    throw new Error(`Timed out acquiring causal sequence lock: ${lockPath}`);
+};
+/**
+ * Allocates the next contiguous seq number for `(run_id, stream_id)`,
+ * persisted under `runtimeHome/telemetry/causal.seq.json`. Allocation is
+ * serialized in-process and mutually excluded across processes by a lock
+ * file; the counter is written atomically and fsynced.
+ */
+export const nextCausalSeq = async (input) => {
+    const lockPath = path.resolve(telemetryDir(input.runtimeHomePath), "causal.seq.lock");
+    const previous = seqAllocationQueues.get(lockPath) ?? Promise.resolve();
+    const allocation = previous.catch(() => undefined).then(async () => {
+        await ensureRuntimeHomeDirectory(input.runtimeHomePath, "telemetry");
+        await acquireSeqLock(lockPath);
+        try {
+            const store = await readSeqStore(input.runtimeHomePath);
+            const forRun = store[input.runId] ?? {};
+            const next = (forRun[input.streamId] ?? 0) + 1;
+            forRun[input.streamId] = next;
+            store[input.runId] = forRun;
+            await writeSeqStore(input.runtimeHomePath, store);
+            return next;
+        }
+        finally {
+            await unlink(lockPath).catch((error) => {
+                if (error.code !== "ENOENT")
+                    throw error;
+            });
+        }
+    });
+    seqAllocationQueues.set(lockPath, allocation);
+    void allocation.finally(() => {
+        if (seqAllocationQueues.get(lockPath) === allocation)
+            seqAllocationQueues.delete(lockPath);
+    }).catch(() => undefined);
+    return allocation;
+};
+/** Appends one CausalEvent record as a line of `runtimeHome/telemetry/causal.jsonl`. */
+export const appendCausalEvent = async (runtimeHomePath, event) => {
+    await ensureRuntimeHomeDirectory(runtimeHomePath, "telemetry");
+    await appendFile(jsonlFilePath(runtimeHomePath), `${JSON.stringify(event)}\n`, "utf8");
+};
+/**
+ * Stamps and appends one causal event for this agent's stream
+ * (`agent:<agentId>`). `run_id` and `principal_id` are always caller-
+ * supplied values (never read from `payload` or model output) — see
+ * `piHarness.ts`, which is the only caller and always passes the resolved
+ * `NOOPOLIS_RUN_ID` and the authenticated agent identity.
+ */
+export const emitCausalEvent = async (input) => {
+    const streamId = `agent:${input.agentId}`;
+    const seq = await nextCausalSeq({ runId: input.runId, runtimeHomePath: input.runtimeHomePath, streamId });
+    const event = {
+        cause_event_ids: [...input.causeEventIds],
+        emitter: { system: "daimon", stream_id: streamId, seq },
+        event_id: input.eventId,
+        payload: input.payload,
+        principal_id: input.principalId,
+        recorded_at: new Date().toISOString(),
+        run_id: input.runId,
+        type: input.type,
+        version: CAUSAL_EVENT_VERSION
+    };
+    await appendCausalEvent(input.runtimeHomePath, event);
+    return event;
+};
+/** Stamps `turn.input.submitted` for one Pi turn, right before the engine prompt call. */
+export const emitTurnInputSubmitted = (input) => emitCausalEvent({
+    agentId: input.agentId,
+    causeEventIds: input.causeEventIds,
+    eventId: turnInputSubmittedEventId(input.turnId),
+    payload: {
+        input_content_sha256: input.inputContentSha256,
+        input_message_ids: [...input.inputMessageIds],
+        prompt_sha256: input.promptSha256,
+        turn_id: input.turnId
+    },
+    principalId: input.principalId,
+    runId: input.runId,
+    runtimeHomePath: input.runtimeHomePath,
+    type: TURN_INPUT_SUBMITTED_TYPE
+});
+/** Stamps `turn.output.completed` once a Pi turn finishes successfully. */
+export const emitTurnOutputCompleted = (input) => emitCausalEvent({
+    agentId: input.agentId,
+    causeEventIds: input.causeEventIds,
+    eventId: turnOutputCompletedEventId(input.turnId),
+    payload: {
+        output_sha256: input.outputSha256,
+        turn_id: input.turnId
+    },
+    principalId: input.principalId,
+    runId: input.runId,
+    runtimeHomePath: input.runtimeHomePath,
+    type: TURN_OUTPUT_COMPLETED_TYPE
+});

package/dist/observability/controlCausal.d.ts

@@ -0,0 +1,117 @@
+import { type CausalEvent } from "./causalEvents.js";
+/**
+ * Control-wake causal emitters for root's two wake-acceptance surfaces
+ * (`src/runtime/pi/appControlSource.ts`, root repo, out of scope here):
+ * the operator-only control endpoint and the Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`). Both stamp `control.wake.accepted` —
+ * enforcement point #3 in `specs/CAUSAL.md` §"Enforcement points" — but with
+ * different `principal_id` authorities, per the B62 fix (Option B): the
+ * operator endpoint stamps `operator:<name>` (`emitControlWakeAccepted`),
+ * the delivery endpoint stamps the fixed `system:moltnet` authority
+ * (`emitDeliveryWakeAccepted`), never a caller-supplied `from`/agent field.
+ * `control.wake.denied` (`emitControlWakeDenied`) stays operator-only: the
+ * delivery endpoint has no bearer-token deny path to stamp. Root's generated
+ * app calls these directly; this file has no knowledge of HTTP, tokens, or
+ * the request shape, only the causal envelope contract.
+ */
+export declare const CONTROL_WAKE_ACCEPTED_TYPE: "control.wake.accepted";
+export declare const CONTROL_WAKE_DENIED_TYPE: "control.wake.denied";
+/** Payload for `control.wake.accepted`. */
+export interface ControlWakeAcceptedPayload extends Record<string, unknown> {
+    target_agent_id: string;
+    wake_kind: string;
+}
+/** Payload for `control.wake.denied`. */
+export interface ControlWakeDeniedPayload extends Record<string, unknown> {
+    reason: string;
+    target_agent_id: string;
+}
+/**
+ * Payload for a Moltnet-delivered `control.wake.accepted` (same event type
+ * as the operator path — it is still an accepted wake; `principal_id` is
+ * what distinguishes authority). Adds `delivered_by` so downstream readers
+ * can tell a delivery-stamped event from an operator-stamped one without
+ * inspecting `principal_id`.
+ */
+export interface DeliveryWakeAcceptedPayload extends ControlWakeAcceptedPayload {
+    delivered_by: "moltnet";
+}
+/**
+ * Principal grammar per `specs/CAUSAL.md` §3 (`^(agent|operator|system):.+`):
+ * an authenticated operator identity, e.g. `operator:control`. Callers must
+ * pass the identity behind the verified bearer token, never a value read
+ * from the request body or model output.
+ */
+export declare const operatorPrincipalId: (operatorName: string) => string;
+/**
+ * Fixed principal for wakes accepted through the Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`): the delivering authority itself, never an
+ * identity derived from a caller-supplied `from`/agent field on the request.
+ */
+export declare const DELIVERY_PRINCIPAL_ID: "system:moltnet";
+/** Deterministic, non-model-derived event id for a control wake acceptance. */
+export declare const controlWakeAcceptedEventId: (requestId: string) => string;
+/** Deterministic, non-model-derived event id for a control wake denial. */
+export declare const controlWakeDeniedEventId: (requestId: string) => string;
+/**
+ * Deterministic, non-model-derived event id for a Moltnet-delivered wake
+ * acceptance. Distinct from `controlWakeAcceptedEventId` (own `.delivery.`
+ * segment) so the two paths never collide even if a future caller reused a
+ * `requestId` across both endpoints for the same target.
+ */
+export declare const deliveryWakeAcceptedEventId: (requestId: string) => string;
+export interface EmitControlWakeAcceptedInput {
+    causeEventIds?: string[];
+    operatorName: string;
+    requestId: string;
+    runId?: string;
+    runtimeHomePath: string;
+    targetAgentId: string;
+    wakeKind: string;
+}
+/**
+ * Stamps `control.wake.accepted` once root's operator-control endpoint has
+ * verified the bearer token and is about to wake `targetAgentId`.
+ * `principal_id` is always `operator:<operatorName>` (the authenticated
+ * operator behind the verified token), never derived from the request body.
+ * `run_id` defaults to `resolveRunId()` like every other daimon emitter.
+ */
+export declare const emitControlWakeAccepted: (input: EmitControlWakeAcceptedInput) => Promise<CausalEvent<ControlWakeAcceptedPayload>>;
+export interface EmitDeliveryWakeAcceptedInput {
+    causeEventIds?: string[];
+    requestId: string;
+    runId?: string;
+    runtimeHomePath: string;
+    targetAgentId: string;
+    wakeKind: string;
+}
+/**
+ * Stamps `control.wake.accepted` once root's Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`) is about to wake `targetAgentId` on behalf
+ * of an inter-agent message. `principal_id` is always the fixed
+ * `DELIVERY_PRINCIPAL_ID` (`system:moltnet`) — the delivering authority —
+ * never derived from a caller-supplied `from`/agent field, and never
+ * `operator:<name>` (that principal is reserved for the operator-only
+ * control endpoint; see `emitControlWakeAccepted`). `run_id` defaults to
+ * `resolveRunId()` like every other daimon emitter.
+ */
+export declare const emitDeliveryWakeAccepted: (input: EmitDeliveryWakeAcceptedInput) => Promise<CausalEvent<DeliveryWakeAcceptedPayload>>;
+export interface EmitControlWakeDeniedInput {
+    causeEventIds?: string[];
+    operatorName: string;
+    reason: string;
+    requestId: string;
+    runId?: string;
+    runtimeHomePath: string;
+    targetAgentId: string;
+}
+/**
+ * Stamps `control.wake.denied` when root's operator-control endpoint rejects
+ * a wake request over a missing or invalid bearer token. Deny paths must
+ * never drop silently (see `specs/CAUSAL.md` enforcement point #3 / T5):
+ * every 401 the endpoint returns should carry exactly one of these. As with
+ * `emitControlWakeAccepted`, `principal_id` is always the authenticated
+ * operator identity, never a value read from the request.
+ */
+export declare const emitControlWakeDenied: (input: EmitControlWakeDeniedInput) => Promise<CausalEvent<ControlWakeDeniedPayload>>;
+//# sourceMappingURL=controlCausal.d.ts.map

package/dist/observability/controlCausal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controlCausal.d.ts","sourceRoot":"","sources":["../../src/observability/controlCausal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpF;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,0BAA0B,EAAG,uBAAgC,CAAC;AAC3E,eAAO,MAAM,wBAAwB,EAAG,qBAA8B,CAAC;AAEvE,2CAA2C;AAC3C,MAAM,WAAW,0BAA2B,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yCAAyC;AACzC,MAAM,WAAW,wBAAyB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,2BAA4B,SAAQ,0BAA0B;IAC7E,YAAY,EAAE,SAAS,CAAC;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,KAAG,MAAoC,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAG,gBAAyB,CAAC;AAE/D,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,GAAI,WAAW,MAAM,KAAG,MAClB,CAAC;AAE9C,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,GAAI,WAAW,MAAM,KAAG,MAAmD,CAAC;AAEjH;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GAAI,WAAW,MAAM,KAAG,MAClB,CAAC;AAE/C,MAAM,WAAW,4BAA4B;IAC3C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAClC,OAAO,4BAA4B,KAClC,OAAO,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAa9C,CAAC;AAEL,MAAM,WAAW,6BAA6B;IAC5C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,6BAA6B,KACnC,OAAO,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAc/C,CAAC;AAEL,MAAM,WAAW,0BAA0B;IACzC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,0BAA0B,KAChC,OAAO,CAAC,WAAW,CAAC,wBAAwB,CAAC,CAa5C,CAAC"}