clawconnect-agent 0.2.6 → 0.2.8

package/dist/openclaw/relay/openclaw-active-run-state.js

@@ -0,0 +1,283 @@
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { getActiveProfile, profileDisplayName } from "../../config/profile.js";
+export const OPENCLAW_ACTIVE_RUN_TTL_MS = 10 * 60_000;
+export const OPENCLAW_TERMINAL_RUN_GRACE_MS = 60_000;
+// Serializes only this process. The per-record lock below is the cross-process
+// guard; a single aggregate JSON file would let manager/CLI read-modify-write
+// operations overwrite each other's unrelated runs.
+let mutationChain = Promise.resolve();
+/** Exact Host ownership key. Relay display canonicalization is separate. */
+export function normalizeOpenClawHostSessionKey(sessionKey) {
+    return sessionKey.trim() || "main";
+}
+export function openClawRunScopeKey(params) {
+    return JSON.stringify([
+        profileDisplayName(params.profile ?? getActiveProfile()),
+        params.gatewayId.trim(),
+        normalizeOpenClawHostSessionKey(params.sessionKey),
+    ]);
+}
+/** Map a Host key to the mobile/Relay display alias only at the upload boundary. */
+export function canonicalOpenClawRelaySessionKey(sessionKey) {
+    const normalized = normalizeOpenClawHostSessionKey(sessionKey);
+    const match = /^agent:[^:]+:(.+)$/i.exec(normalized);
+    return (match?.[1] ?? normalized) || "main";
+}
+export async function recordOpenClawActiveRun(params) {
+    const gatewayId = params.gatewayId.trim();
+    const sourceRunId = params.sourceRunId.trim();
+    const sessionKey = normalizeOpenClawHostSessionKey(params.sessionKey);
+    if (!gatewayId || !sourceRunId)
+        return undefined;
+    const nowMs = params.nowMs ?? Date.now();
+    const now = new Date(nowMs).toISOString();
+    const run = {
+        profile: profileDisplayName(params.profile ?? getActiveProfile()),
+        gatewayId,
+        sessionKey,
+        sourceRunId,
+        ...(params.providerRunId?.trim() ? { providerRunId: params.providerRunId.trim() } : {}),
+        state: "active",
+        createdAt: now,
+        updatedAt: now,
+        expiresAt: new Date(nowMs + OPENCLAW_ACTIVE_RUN_TTL_MS).toISOString(),
+    };
+    await mutateStore(async () => {
+        const path = recordPath(run);
+        await withRecordLock(path, async () => {
+            await writeRecordAtomic(path, run);
+        });
+    });
+    return run;
+}
+export async function updateOpenClawActiveRunProviderId(params) {
+    const sourceRunId = params.sourceRunId.trim();
+    const providerRunId = params.providerRunId.trim();
+    if (!sourceRunId || !providerRunId)
+        return;
+    const candidate = {
+        profile: profileDisplayName(params.profile ?? getActiveProfile()),
+        gatewayId: params.gatewayId.trim(),
+        sessionKey: normalizeOpenClawHostSessionKey(params.sessionKey),
+        sourceRunId,
+    };
+    const nowMs = params.nowMs ?? Date.now();
+    await mutateStore(async () => {
+        const path = recordPath(candidate);
+        await withRecordLock(path, async () => {
+            const existing = await readRecord(path);
+            if (!existing || isExpired(existing, nowMs)) {
+                if (existing)
+                    await unlink(path).catch(() => undefined);
+                return;
+            }
+            existing.providerRunId = providerRunId;
+            existing.updatedAt = new Date(nowMs).toISOString();
+            await writeRecordAtomic(path, existing);
+        });
+    });
+}
+/** Return only the explicitly named run; never select a latest/unique candidate. */
+export async function resolveOpenClawActiveRun(params) {
+    const gatewayId = params.gatewayId.trim();
+    const sessionKey = normalizeOpenClawHostSessionKey(params.sessionKey);
+    if (!gatewayId)
+        return undefined;
+    const nowMs = params.nowMs ?? Date.now();
+    const profile = profileDisplayName(params.profile ?? getActiveProfile());
+    const requestedSourceRunId = params.sourceRunId.trim();
+    if (!gatewayId || !requestedSourceRunId)
+        return undefined;
+    const runs = await readRuns();
+    for (const { path, run } of runs) {
+        if (isExpired(run, nowMs)) {
+            await removeExpiredRecord(path, run, nowMs);
+            continue;
+        }
+        if (run.profile === profile
+            && run.gatewayId === gatewayId
+            && run.sessionKey === sessionKey
+            && run.sourceRunId === requestedSourceRunId) {
+            return run;
+        }
+    }
+    return undefined;
+}
+export async function markOpenClawActiveRunTerminal(params) {
+    const sourceRunId = params.sourceRunId.trim();
+    if (!sourceRunId)
+        return;
+    const nowMs = params.nowMs ?? Date.now();
+    const candidate = {
+        profile: profileDisplayName(params.profile ?? getActiveProfile()),
+        gatewayId: params.gatewayId.trim(),
+        sessionKey: normalizeOpenClawHostSessionKey(params.sessionKey),
+        sourceRunId,
+    };
+    await mutateStore(async () => {
+        const path = recordPath(candidate);
+        await withRecordLock(path, async () => {
+            const existing = await readRecord(path);
+            if (!existing || isExpired(existing, nowMs)) {
+                if (existing)
+                    await unlink(path).catch(() => undefined);
+                return;
+            }
+            existing.state = "terminal";
+            existing.updatedAt = new Date(nowMs).toISOString();
+            existing.expiresAt = new Date(nowMs + OPENCLAW_TERMINAL_RUN_GRACE_MS).toISOString();
+            await writeRecordAtomic(path, existing);
+        });
+    });
+}
+export async function clearOpenClawActiveRun(params) {
+    const profile = profileDisplayName(params.profile ?? getActiveProfile());
+    const gatewayId = params.gatewayId.trim();
+    const sessionKey = normalizeOpenClawHostSessionKey(params.sessionKey);
+    const requestedSourceRunId = params.sourceRunId?.trim();
+    await mutateStore(async () => {
+        for (const { path, run } of await readRuns()) {
+            if (run.profile !== profile
+                || run.gatewayId !== gatewayId
+                || run.sessionKey !== sessionKey
+                || (requestedSourceRunId && run.sourceRunId !== requestedSourceRunId))
+                continue;
+            await withRecordLock(path, async () => {
+                const current = await readRecord(path);
+                if (current && current.sourceRunId === run.sourceRunId)
+                    await unlink(path).catch(() => undefined);
+            });
+        }
+    });
+}
+function recordKey(run) {
+    return createHash("sha256")
+        .update(JSON.stringify([run.profile, run.gatewayId, run.sessionKey, run.sourceRunId]))
+        .digest("hex");
+}
+function recordPath(run) {
+    return join(storeDirectory(), `${recordKey(run)}.json`);
+}
+function storeDirectory() {
+    const configured = process.env.CLAWCONNECT_OPENCLAW_ACTIVE_RUN_STORE?.trim();
+    return configured
+        ? `${configured}.records`
+        : join(homedir(), ".clawconnect", "openclaw", "active-runs");
+}
+function isExpired(run, nowMs) {
+    const expiresAt = Date.parse(run.expiresAt);
+    return !Number.isFinite(expiresAt) || nowMs >= expiresAt;
+}
+async function readRuns() {
+    const directory = storeDirectory();
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return [];
+        return [];
+    }
+    const runs = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const path = join(directory, name);
+        const run = await readRecord(path);
+        if (run)
+            runs.push({ path, run });
+    }
+    return runs;
+}
+async function readRecord(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (typeof parsed.profile !== "string"
+            || typeof parsed.gatewayId !== "string"
+            || typeof parsed.sessionKey !== "string"
+            || typeof parsed.sourceRunId !== "string"
+            || (parsed.state !== "active" && parsed.state !== "terminal")
+            || typeof parsed.createdAt !== "string"
+            || typeof parsed.updatedAt !== "string"
+            || typeof parsed.expiresAt !== "string")
+            return undefined;
+        return parsed;
+    }
+    catch {
+        await quarantineCorruptStore(path);
+        return undefined;
+    }
+}
+async function writeRecordAtomic(path, run) {
+    await mkdir(dirname(path), { recursive: true });
+    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempPath, JSON.stringify(run, null, 2), "utf8");
+    await rename(tempPath, path);
+}
+async function removeExpiredRecord(path, run, nowMs) {
+    await withRecordLock(path, async () => {
+        const current = await readRecord(path);
+        if (current && current.sourceRunId === run.sourceRunId && isExpired(current, nowMs)) {
+            await unlink(path).catch(() => undefined);
+        }
+    });
+}
+async function mutateStore(mutator) {
+    const run = mutationChain.then(mutator);
+    mutationChain = run.catch(() => undefined);
+    await run;
+}
+async function withRecordLock(path, fn) {
+    const lockPath = `${path}.lock`;
+    await mkdir(dirname(path), { recursive: true });
+    let handle;
+    for (let attempt = 0; attempt < 200; attempt += 1) {
+        try {
+            handle = await open(lockPath, "wx");
+            break;
+        }
+        catch (error) {
+            if (!isAlreadyExists(error))
+                throw error;
+            try {
+                const lockAgeMs = Date.now() - (await stat(lockPath)).mtimeMs;
+                if (lockAgeMs > 30_000) {
+                    await unlink(lockPath).catch(() => undefined);
+                    continue;
+                }
+            }
+            catch {
+                // A concurrent owner may have released the lock between stat/unlink.
+            }
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+    }
+    if (!handle)
+        throw new Error("openclaw_active_run_lock_timeout");
+    try {
+        return await fn();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+        await unlink(lockPath).catch(() => undefined);
+    }
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+function isAlreadyExists(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+async function quarantineCorruptStore(path) {
+    try {
+        await copyFile(path, `${path}.corrupt-${Date.now()}`);
+    }
+    catch {
+        // Best effort only; fail closed when the state cannot be read.
+    }
+}
+//# sourceMappingURL=openclaw-active-run-state.js.map

package/dist/openclaw/relay/openclaw-active-run-state.js.map

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

package/dist/openclaw/relay/openclaw-message-tool-real-shape.fixture.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sanitized fixture captured from the installed OpenClaw transcript_events
+ * shape (toolResult.details.sourceReply), with local paths and run IDs replaced
+ * by test values. The installed AssistantMessage.openclawDelivery type does
+ * not contain the identity fields; those live on this structured tool result.
+ */
+export declare function realOpenClawMessageToolResultFixture(params: {
+    runId: string;
+    toolCallId: string;
+    idempotencyKey: string;
+    mediaUrls: string[];
+}): Record<string, unknown>;

package/dist/openclaw/relay/openclaw-message-tool-real-shape.fixture.js

@@ -0,0 +1,48 @@
+/**
+ * Sanitized fixture captured from the installed OpenClaw transcript_events
+ * shape (toolResult.details.sourceReply), with local paths and run IDs replaced
+ * by test values. The installed AssistantMessage.openclawDelivery type does
+ * not contain the identity fields; those live on this structured tool result.
+ */
+export function realOpenClawMessageToolResultFixture(params) {
+    const firstUrl = params.mediaUrls[0] ?? "";
+    return {
+        role: "toolResult",
+        toolCallId: params.toolCallId,
+        toolName: "message",
+        content: [{ type: "text", text: "Sent visible reply to the current source conversation via internal-ui." }],
+        details: {
+            status: "ok",
+            deliveryStatus: "sent",
+            channel: "webchat",
+            target: "current-run",
+            sourceReplyDeliveryMode: "message_tool_only",
+            idempotencyKey: params.idempotencyKey,
+            sourceReplyTranscriptOwner: true,
+            sourceReplySink: "internal-ui",
+            sourceReply: {
+                text: "",
+                mediaUrl: firstUrl,
+                mediaUrls: params.mediaUrls,
+                attachments: params.mediaUrls.map((url, index) => ({
+                    name: `image-${index + 1}.png`,
+                    mimeType: "image/png",
+                    trustedLocalMedia: true,
+                    url,
+                })),
+                trustedLocalMedia: true,
+            },
+            mediaUrl: firstUrl,
+            mediaUrls: params.mediaUrls,
+            dryRun: false,
+            messageDelivery: {
+                status: "settled",
+                partialDelivery: false,
+                createdThreadIds: [],
+            },
+        },
+        isError: false,
+        __openclaw: { runId: params.runId },
+    };
+}
+//# sourceMappingURL=openclaw-message-tool-real-shape.fixture.js.map

package/dist/openclaw/relay/openclaw-message-tool-real-shape.fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw-message-tool-real-shape.fixture.js","sourceRoot":"","sources":["../../../src/openclaw/relay/openclaw-message-tool-real-shape.fixture.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,oCAAoC,CAAC,MAKpD;IACC,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,QAAQ,EAAE,SAAS;QACnB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,wEAAwE,EAAE,CAAC;QAC3G,OAAO,EAAE;YACP,MAAM,EAAE,IAAI;YACZ,cAAc,EAAE,MAAM;YACtB,OAAO,EAAE,SAAS;YAClB,MAAM,EAAE,aAAa;YACrB,uBAAuB,EAAE,mBAAmB;YAC5C,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,0BAA0B,EAAE,IAAI;YAChC,eAAe,EAAE,aAAa;YAC9B,WAAW,EAAE;gBACX,IAAI,EAAE,EAAE;gBACR,QAAQ,EAAE,QAAQ;gBAClB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;oBACjD,IAAI,EAAE,SAAS,KAAK,GAAG,CAAC,MAAM;oBAC9B,QAAQ,EAAE,WAAW;oBACrB,iBAAiB,EAAE,IAAI;oBACvB,GAAG;iBACJ,CAAC,CAAC;gBACH,iBAAiB,EAAE,IAAI;aACxB;YACD,QAAQ,EAAE,QAAQ;YAClB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,MAAM,EAAE,KAAK;YACb,eAAe,EAAE;gBACf,MAAM,EAAE,SAAS;gBACjB,eAAe,EAAE,KAAK;gBACtB,gBAAgB,EAAE,EAAE;aACrB;SACF;QACD,OAAO,EAAE,KAAK;QACd,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE;KACpC,CAAC;AACJ,CAAC"}

package/dist/openclaw/relay/openclaw-source-commit-watcher.d.ts

@@ -0,0 +1,23 @@
+import { type SourceCommit } from "../../core/relay/source-commit.js";
+export type OpenClawSourceCommitWatcher = {
+    notify(): void;
+    rescan(): void;
+    close(): void;
+};
+/**
+ * SQLite/WAL notifications are only wake-up signals. The caller supplies an
+ * authoritative cursor reader, which is read synchronously in a serialized
+ * observer. Watching both the database directory and the database file keeps
+ * the observer alive across SQLite WAL rotation and atomic replacement. The
+ * low-frequency anti-entropy rescan is deliberately only a liveness aid: the
+ * cursor reader still owns identity/order and the observer only advances after
+ * the downstream append path succeeds.
+ */
+export declare function watchOpenClawSourceCommit(options: {
+    databasePath: string;
+    readCursor: () => SourceCommit | null | Promise<SourceCommit | null>;
+    onCommit: (commit: SourceCommit, previousCommittedThroughSeq: number | undefined) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+    rescanIntervalMs?: number;
+    initialWatermarkMode?: "latest" | "from_zero";
+}): OpenClawSourceCommitWatcher;

package/dist/openclaw/relay/openclaw-source-commit-watcher.js

@@ -0,0 +1,65 @@
+import { watch } from "node:fs";
+import { dirname, basename } from "node:path";
+import { createSourceCommitObserver } from "../../core/relay/source-commit.js";
+/**
+ * SQLite/WAL notifications are only wake-up signals. The caller supplies an
+ * authoritative cursor reader, which is read synchronously in a serialized
+ * observer. Watching both the database directory and the database file keeps
+ * the observer alive across SQLite WAL rotation and atomic replacement. The
+ * low-frequency anti-entropy rescan is deliberately only a liveness aid: the
+ * cursor reader still owns identity/order and the observer only advances after
+ * the downstream append path succeeds.
+ */
+export function watchOpenClawSourceCommit(options) {
+    const observer = createSourceCommitObserver({
+        readCursor: options.readCursor,
+        onCommit: options.onCommit,
+        onError: options.onError,
+        initialWatermarkMode: options.initialWatermarkMode,
+    });
+    const watchers = [];
+    const watchedDirectory = dirname(options.databasePath);
+    const databaseName = basename(options.databasePath);
+    const notify = () => observer.notify();
+    const rescanIntervalMs = options.rescanIntervalMs ?? 5_000;
+    let rescanTimer;
+    // Directory events cover create/rename/reopen and -wal/-shm churn. The
+    // direct file watch reduces latency for ordinary commits. Neither watcher
+    // performs correctness work; the cursor reader remains authoritative.
+    try {
+        watchers.push(watch(watchedDirectory, (_eventType, changedName) => {
+            if (!changedName || String(changedName) === databaseName || String(changedName).startsWith(`${databaseName}-`)) {
+                notify();
+            }
+        }));
+    }
+    catch {
+        // The caller still gets an immediate rescan and can continue using live
+        // gateway events if the source is not present yet.
+    }
+    try {
+        watchers.push(watch(options.databasePath, notify));
+    }
+    catch {
+        // The directory watch can be re-established when the file appears.
+    }
+    if (Number.isFinite(rescanIntervalMs) && rescanIntervalMs > 0) {
+        // Node's fs.watch can coalesce/drop SQLite WAL notifications. This timer
+        // is intentionally low frequency and does not participate in ordering.
+        rescanTimer = setInterval(notify, Math.floor(rescanIntervalMs));
+        rescanTimer.unref?.();
+    }
+    observer.rescan();
+    return {
+        notify,
+        rescan: observer.rescan,
+        close() {
+            for (const fileWatcher of watchers)
+                fileWatcher.close();
+            if (rescanTimer)
+                clearInterval(rescanTimer);
+            observer.close();
+        },
+    };
+}
+//# sourceMappingURL=openclaw-source-commit-watcher.js.map

package/dist/openclaw/relay/openclaw-source-commit-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openclaw-source-commit-watcher.js","sourceRoot":"","sources":["../../../src/openclaw/relay/openclaw-source-commit-watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAkB,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,0BAA0B,EAAqB,MAAM,mCAAmC,CAAC;AAQlG;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAOzC;IACC,MAAM,QAAQ,GAAG,0BAA0B,CAAC;QAC1C,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;KACnD,CAAC,CAAC;IACH,MAAM,QAAQ,GAAgB,EAAE,CAAC;IACjC,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACvD,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,GAAS,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC7C,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,KAAK,CAAC;IAC3D,IAAI,WAAuD,CAAC;IAE5D,uEAAuE;IACvE,0EAA0E;IAC1E,sEAAsE;IACtE,IAAI,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,EAAE;YAChE,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW,CAAC,KAAK,YAAY,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,UAAU,CAAC,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC;gBAC/G,MAAM,EAAE,CAAC;YACX,CAAC;QACH,CAAC,CAAC,CAAC,CAAC;IACN,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,mDAAmD;IACrD,CAAC;IACD,IAAI,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;IACrE,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,gBAAgB,GAAG,CAAC,EAAE,CAAC;QAC9D,yEAAyE;QACzE,uEAAuE;QACvE,WAAW,GAAG,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC;QAChE,WAAW,CAAC,KAAK,EAAE,EAAE,CAAC;IACxB,CAAC;IACD,QAAQ,CAAC,MAAM,EAAE,CAAC;IAClB,OAAO;QACL,MAAM;QACN,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,KAAK;YACH,KAAK,MAAM,WAAW,IAAI,QAAQ;gBAAE,WAAW,CAAC,KAAK,EAAE,CAAC;YACxD,IAAI,WAAW;gBAAE,aAAa,CAAC,WAAW,CAAC,CAAC;YAC5C,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/openclaw/relay/outgoing-media-relay.d.ts

@@ -1,4 +1,6 @@
 import { type FileUploadResult } from "../../core/relay/file-upload.js";
+import { type GatewaySessionDefaults } from "./session-context.js";
+declare const OPENCLAW_DELIVERY_CONTRACT = "openclaw.message-tool-delivery.v1";
 export type OutgoingMediaRelayOptions = {
     relayServerUrl: string;
     relaySecret: string;
@@ -7,14 +9,39 @@ export type OutgoingMediaRelayOptions = {
     recordsDir?: string;
     stateDir?: string;
     cache?: Map<string, FileUploadResult>;
+    /**
+     * Legacy caller context. Deliberately ignored: attachment publication must
+     * come from typed content blocks or structured OpenClaw delivery metadata,
+     * never from natural-language intent in this field.
+     */
     userMessage?: string;
     /**
      * A live gateway event can arrive a few milliseconds before OpenClaw commits
-     * its managed outgoing-media record.  Only that path should briefly wait for
-     * the record instead of publishing an unavailable image placeholder.
+     * its managed outgoing-media record. Only that file-availability path may
+     * briefly wait for the record; this never delays timeline identity, ordering,
+     * or message projection correctness.
      */
     waitForOutgoingMediaRecord?: boolean;
+    /** Session defaults used to canonicalize OpenClaw relation scopes. */
+    sessionDefaults?: GatewaySessionDefaults;
+};
+type OpenClawDeliveryReceipt = {
+    contract: typeof OPENCLAW_DELIVERY_CONTRACT;
+    toolName: "message";
+    toolCallId: string;
+    idempotencyKey: string;
+    sourceRunId: string;
+    mediaUrls: string[];
 };
 export declare function relayOutgoingMediaInPayload(payload: unknown, opts: OutgoingMediaRelayOptions): Promise<unknown>;
+/**
+ * Adapt the shape emitted by the currently deployed OpenClaw message tool.
+ * The installed OpenClaw type declares `openclawDelivery.mediaUrls` only as a
+ * display projection. The authoritative toolResult carries the delivery
+ * status, tool call, idempotency key, run metadata, and trusted local media
+ * list in `details.sourceReply`; only that explicit relation becomes the
+ * internal typed v1 receipt. Generic mediaUrls stay inert.
+ */
+export declare function adaptOpenClawMessageToolDelivery(value: unknown, expectedSourceRunId?: string): OpenClawDeliveryReceipt | undefined;
 export declare function relayOutgoingMediaInHistoryResponse(response: unknown, opts: OutgoingMediaRelayOptions): Promise<unknown>;
-export declare function extractDeliverablePathCandidates(text: string): string[];
+export {};