@aitne/daemon 0.1.10 → 0.1.11

package/dist/core/dispatcher-task-delivery.js

@@ -0,0 +1,555 @@
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
+import { EventPriority, createEvent, } from "@aitne/shared";
+import { getBrowserTask, listUndeliveredBrowserTaskReports, markBrowserTaskDelivered, } from "../db/browser-task-store.js";
+import { getClarification, listUndeliveredClarifications, markClarificationDelivered, } from "../db/browser-task-clarifications-store.js";
+import { getBackgroundTask, listUndeliveredBackgroundTaskReports, markBackgroundTaskDelivered, } from "../db/background-task-store.js";
+import { getClarification as getBackgroundClarification, listUndeliveredClarifications as listUndeliveredBackgroundClarifications, markClarificationDelivered as markBackgroundClarificationDelivered, } from "../db/background-task-clarifications-store.js";
+import { parseChannelRef } from "../db/browser-automation-purchase-primary-channels-store.js";
+import { isInQuietHoursAt } from "./quiet-hours.js";
+import { DASHBOARD_CHAT_SCOPE, DASHBOARD_SCOPE_KEY, OWNER_DM_SCOPE, OWNER_SCOPE_KEY, } from "../messaging/constants.js";
+import { classifyOwnerDmActivity, } from "./context-builder-conversation.js";
+import { recordProactiveForwardDeliveries, } from "./channel-timeline.js";
+import { createLogger } from "../logging.js";
+const logger = createLogger("dispatcher-task-delivery");
+export const TASK_DELIVERY_GATE_KEYS = [
+    `${OWNER_DM_SCOPE}:${OWNER_SCOPE_KEY}`,
+    `${DASHBOARD_CHAT_SCOPE}:${DASHBOARD_SCOPE_KEY}`,
+];
+const REPORT_DRAFT_CAP = 3_800;
+export function createBrowserTaskResultDeliveryEvent(input) {
+    const draft = input.report.length > REPORT_DRAFT_CAP
+        ? `${input.report.slice(0, REPORT_DRAFT_CAP)}\n\n[... truncated; open the browser-task detail page for the full report]`
+        : input.report;
+    return Object.assign(createEvent({
+        type: "task.delivery",
+        source: "browser_task",
+        priority: EventPriority.HIGH,
+        data: {},
+    }), {
+        taskContext: {
+            taskKind: "browser_task",
+            taskId: input.taskId,
+            deliveryType: "task_result",
+            title: input.title,
+            draft,
+            report: input.report,
+            originatingChannel: input.originatingChannel,
+            screenshotKeys: [...(input.screenshotKeys ?? [])],
+        },
+    });
+}
+export function createBrowserTaskClarificationDeliveryEvent(input) {
+    const draft = [
+        `Browser task "${input.title}" needs your input.`,
+        `Question: ${input.question}`,
+        input.contextSummary ? `Context: ${input.contextSummary}` : null,
+        "Reply here with the answer; I will pass it back to the task.",
+    ]
+        .filter((line) => line !== null && line.length > 0)
+        .join("\n");
+    return Object.assign(createEvent({
+        type: "task.delivery",
+        source: "browser_task",
+        priority: EventPriority.HIGH,
+        data: {},
+    }), {
+        taskContext: {
+            taskKind: "browser_task",
+            taskId: input.taskId,
+            deliveryType: "task_clarification",
+            title: input.title,
+            draft,
+            report: input.question,
+            originatingChannel: input.originatingChannel,
+            clarificationId: input.clarificationId,
+            contextSummary: input.contextSummary,
+            screenshotKeys: input.screenshotKey ? [input.screenshotKey] : [],
+        },
+    });
+}
+export function createBackgroundTaskResultDeliveryEvent(input) {
+    return Object.assign(createEvent({
+        type: "task.delivery",
+        source: "background_task",
+        priority: EventPriority.HIGH,
+        data: {},
+    }), {
+        taskContext: {
+            taskKind: "background_task",
+            taskId: input.taskId,
+            deliveryType: "task_result",
+            title: input.title,
+            // The worker-authored `draft` IS the natural-language summary;
+            // unlike browser_task (which truncates the raw report), the
+            // background worker already produced a clean draft + a separate
+            // verbatim report. Idle sends the draft; the active turn reads
+            // the full report (injected below) and weaves.
+            draft: input.draft,
+            report: input.report,
+            originatingChannel: input.originatingChannel,
+            screenshotKeys: [],
+            assets: [...(input.assets ?? [])],
+        },
+    });
+}
+export function createBackgroundTaskClarificationDeliveryEvent(input) {
+    const draft = [
+        `The background task "${input.title}" needs your input.`,
+        `Question: ${input.question}`,
+        input.contextSummary ? `Context: ${input.contextSummary}` : null,
+        "Reply here with the answer; I will pass it back to the task.",
+    ]
+        .filter((line) => line !== null && line.length > 0)
+        .join("\n");
+    return Object.assign(createEvent({
+        type: "task.delivery",
+        source: "background_task",
+        priority: EventPriority.HIGH,
+        data: {},
+    }), {
+        taskContext: {
+            taskKind: "background_task",
+            taskId: input.taskId,
+            deliveryType: "task_clarification",
+            title: input.title,
+            draft,
+            report: input.question,
+            originatingChannel: input.originatingChannel,
+            clarificationId: input.clarificationId,
+            contextSummary: input.contextSummary,
+            screenshotKeys: [],
+        },
+    });
+}
+/**
+ * BACKGROUND_TASK_RUNNER_DESIGN.md §2.3 / §13 Decision 4 (Phase 4, opt-in)
+ * — wrap a routine autonomous forward as a `task.delivery` event so it
+ * flows through the same gate + activity-branch machinery: an active owner
+ * gets a woven delivery turn, an idle owner the verbatim send + record.
+ * Carries no DB row (synthetic id, no `delivered_at` recovery — autonomous
+ * forwards are fire-and-forget, exactly as the verbatim path is today).
+ */
+export function createAutonomousForwardDeliveryEvent(input) {
+    return Object.assign(createEvent({
+        type: "task.delivery",
+        source: "autonomous_forward",
+        priority: EventPriority.HIGH,
+        ...(input.correlationId ? { correlationId: input.correlationId } : {}),
+        data: {},
+    }), {
+        taskContext: {
+            taskKind: "autonomous_forward",
+            taskId: randomUUID(),
+            deliveryType: "task_result",
+            title: input.title ?? "update",
+            // The forward content is both the idle-send body and the active
+            // turn's grounding — there is no separate verbatim/summary split.
+            draft: input.content,
+            report: input.content,
+            originatingChannel: input.originatingChannel,
+            screenshotKeys: [],
+        },
+    });
+}
+/** The asset key the dispatch arm puts resolved refs under on the
+ *  synthetic `scheduled.dm` event so the result processor can attach them
+ *  to the woven reply. */
+export const TASK_DELIVERY_ATTACHMENTS_KEY = "task_delivery_attachments";
+/**
+ * The canonical deliverable-asset list for a payload. Prefers an explicit
+ * `assets` manifest (background-task workers populate it); falls back to
+ * folding legacy browser-task `screenshotKeys` into screenshot assets so
+ * the Phase-1 source keeps working unchanged. Empty ⇒ nothing to present.
+ */
+function effectiveAssets(payload) {
+    if (payload.assets && payload.assets.length > 0) {
+        return payload.assets;
+    }
+    return (payload.screenshotKeys ?? []).map((key) => ({
+        filename: basename(key),
+        kind: "screenshot",
+        screenshotKey: key,
+    }));
+}
+/**
+ * The agent-facing slice of the asset list — filename / kind / label only.
+ * Internal locations (screenshotKey, absolute path) are deliberately
+ * withheld from the LLM context: the daemon attaches the bytes, and the
+ * agent references assets by name/kind. Detail/paths for a later re-send
+ * come from the artifact API, not the conversation.
+ */
+function assetManifest(assets) {
+    return assets.map((a) => ({
+        filename: a.filename,
+        kind: a.kind,
+        ...(a.label ? { label: a.label } : {}),
+    }));
+}
+async function resolveDeliveryAttachments(deps, platform, payload) {
+    const assets = effectiveAssets(payload);
+    if (assets.length === 0 || !deps.resolveAssets)
+        return [];
+    try {
+        return await deps.resolveAssets(platform, assets);
+    }
+    catch (err) {
+        // Assets are a best-effort enrichment of the text draft — a resolver
+        // failure must never block the result/clarification DM itself.
+        logger.warn({ err, taskId: payload.taskId, deliveryType: payload.deliveryType }, "task.delivery asset resolution failed; sending text only");
+        return [];
+    }
+}
+export async function handleTaskDeliveryInsideGate(deps, event) {
+    const payload = event.taskContext;
+    if (payload.taskKind !== "browser_task"
+        && payload.taskKind !== "background_task"
+        && payload.taskKind !== "autonomous_forward") {
+        logger.warn({ taskKind: payload.taskKind, taskId: payload.taskId }, "task.delivery skipped: unsupported task kind");
+        return;
+    }
+    const now = deps.nowFn?.() ?? Date.now();
+    // `autonomous_forward` carries no DB row, so the row-keyed dedup /
+    // delivered_at checks below do not apply — it is fire-and-forget (the
+    // verbatim path it replaces had no recovery either). Browser/background
+    // task deliveries keep the full idempotency contract.
+    if (payload.taskKind !== "autonomous_forward") {
+        if (await backfillDeliveredAtIfMessageExists(deps.db, payload, now)) {
+            return;
+        }
+        if (isDeliveryAlreadyMarked(deps.db, payload)) {
+            return;
+        }
+    }
+    // No deliverable channel ⇒ the report/clarification is still filed on
+    // the row, but there is nowhere to DM it (`browser_task.originating_channel`
+    // is nullable — e.g. synthetic / channel-less runs). Mark delivered so
+    // the boot/periodic recovery sweep (which selects `delivered_at IS NULL`)
+    // does not re-enqueue this task on every 30 s tick, and so the active
+    // branch never spends a full LLM turn on something it cannot deliver.
+    // Matches the pre-Phase-1 notifier's "skip once" behaviour, minus the
+    // churn. Logged as a degrade per the project's "no silent drops" posture.
+    const channel = resolveDeliveryChannel(payload);
+    if (!channel) {
+        logger.warn({
+            taskId: payload.taskId,
+            deliveryType: payload.deliveryType,
+            originatingChannel: payload.originatingChannel,
+        }, "task.delivery dropped: no parseable originating channel; report "
+            + "filed on the row, marking delivered to stop recovery churn");
+        markDeliveredAt(deps.db, payload, now);
+        return;
+    }
+    const activity = classifyOwnerDmActivity({ db: deps.db, config: deps.config }, now);
+    if (activity === "active") {
+        await deliverActive(deps, event, activity, channel);
+        return;
+    }
+    // Idle/asleep + quiet hours ⇒ defer. The design (§4.5 / §10.6) routes
+    // the idle branch through the proactive quiet-hours suppression so a
+    // task finishing at 03:00 does not ping a sleeping owner. The idle send
+    // uses `replyTo` (to hit the originating channel), which bypasses
+    // NotificationManager's own quiet-hours gate — so we gate here instead.
+    // Leaving `delivered_at` NULL lets the boot/periodic recovery sweep
+    // re-deliver once the window lifts (and re-classify: if the owner is
+    // active by then, it weaves into the live thread instead).
+    if (isQuietHoursNow(deps.config, now)) {
+        logger.info({
+            taskId: payload.taskId,
+            deliveryType: payload.deliveryType,
+        }, "task.delivery idle send deferred — quiet hours; recovery sweep will "
+            + "re-deliver after the window");
+        return;
+    }
+    await deliverIdle(deps, event, channel);
+}
+function isQuietHoursNow(config, nowMs) {
+    return isInQuietHoursAt(new Date(nowMs), {
+        start: config.quietHoursStart,
+        end: config.quietHoursEnd,
+        timezone: config.timezone || undefined,
+    });
+}
+async function deliverActive(deps, event, activity, channel) {
+    const payload = event.taskContext;
+    const attachments = await resolveDeliveryAttachments(deps, channel.platform, payload);
+    const scheduledEvent = createScheduledDmDeliveryEvent(event, activity, attachments, channel);
+    try {
+        await deps.executeScheduledTask(scheduledEvent);
+    }
+    catch (err) {
+        logger.warn({ err, taskId: payload.taskId, deliveryType: payload.deliveryType }, "task.delivery active turn failed; falling back to direct draft");
+        // Reuse the already-resolved attachments — re-resolving would
+        // re-ingest dashboard files and could diverge from what the active
+        // turn was given.
+        await deliverIdle(deps, event, channel, attachments);
+        return;
+    }
+    const now = deps.nowFn?.() ?? Date.now();
+    if (await backfillDeliveredAtIfMessageExists(deps.db, payload, now)) {
+        return;
+    }
+    logger.warn({ taskId: payload.taskId, deliveryType: payload.deliveryType }, "task.delivery active turn produced no tagged message; falling back to direct draft");
+    await deliverIdle(deps, event, channel, attachments);
+}
+async function deliverIdle(deps, event, channel, preResolvedAttachments) {
+    const payload = event.taskContext;
+    const attachments = preResolvedAttachments
+        ?? (await resolveDeliveryAttachments(deps, channel.platform, payload));
+    await deps.notificationMgr.send(payload.draft, event, {
+        priority: "normal",
+        category: "agent",
+        replyTo: {
+            platform: channel.platform,
+            channel: channel.channelId,
+            threadId: null,
+        },
+        ...(attachments.length > 0 ? { attachments } : {}),
+    });
+    const dispatchId = randomUUID();
+    const now = deps.nowFn?.() ?? Date.now();
+    const recordAndMark = deps.db.transaction(() => {
+        recordProactiveForwardDeliveries({
+            db: deps.db,
+            config: deps.config,
+            deliveries: [
+                {
+                    platform: channel.platform,
+                    channel: channel.channelId,
+                },
+            ],
+            content: payload.draft,
+            dispatchId,
+            dispatchIds: [dispatchId],
+            notificationType: notificationTypeFor(payload),
+            extraMetadata: taskDeliveryMetadata(payload, false),
+        });
+        markDeliveredAt(deps.db, payload, now);
+    });
+    recordAndMark();
+}
+function createScheduledDmDeliveryEvent(event, activity, attachments, channel) {
+    const payload = event.taskContext;
+    const manifest = assetManifest(effectiveAssets(payload));
+    return Object.assign(createEvent({
+        type: "scheduled.dm",
+        source: "task.delivery",
+        priority: EventPriority.HIGH,
+        correlationId: event.correlationId,
+        data: {
+            reply_target: {
+                platform: channel.platform,
+                channel: channel.channelId,
+                threadId: null,
+                // Audit-only label (not consumed for routing) — use the actual task
+                // kind so background_task / autonomous_forward weaves aren't all
+                // mislabelled as browser_task in telemetry.
+                sender: payload.taskKind,
+            },
+            task_delivery_record: {
+                notificationType: notificationTypeFor(payload),
+                metadata: taskDeliveryMetadata(payload, true),
+            },
+            // Resolved deliverable files — the result processor attaches these to
+            // the woven reply so the owner receives them inline (the active turn
+            // is a no-tool DM turn and cannot self-attach). Empty ⇒ omitted.
+            ...(attachments.length > 0
+                ? { [TASK_DELIVERY_ATTACHMENTS_KEY]: [...attachments] }
+                : {}),
+        },
+    }), {
+        task: `task delivery: ${payload.title}`,
+        taskContext: {
+            task_delivery: {
+                taskKind: payload.taskKind,
+                taskId: payload.taskId,
+                deliveryType: payload.deliveryType,
+                title: payload.title,
+                draft: payload.draft,
+                report: payload.report ?? payload.draft,
+                clarificationId: payload.clarificationId ?? null,
+                contextSummary: payload.contextSummary ?? null,
+                // Agent-facing asset manifest (filename/kind/label only). Present
+                // only when the task produced deliverables — the skill references
+                // them, and the daemon attaches the bytes. Empty ⇒ no asset block.
+                assets: manifest,
+                activity,
+            },
+        },
+    });
+}
+function resolveDeliveryChannel(payload) {
+    return payload.originatingChannel
+        ? parseChannelRef(payload.originatingChannel)
+        : null;
+}
+function notificationTypeFor(payload) {
+    if (payload.taskKind === "autonomous_forward")
+        return "proactive_forward";
+    return payload.deliveryType === "task_clarification"
+        ? "task_clarification"
+        : "task_result";
+}
+function taskDeliveryMetadata(payload, activeTurn) {
+    return {
+        taskKind: payload.taskKind,
+        taskId: payload.taskId,
+        ...(activeTurn ? { deliveredTaskId: payload.taskId } : {}),
+        deliveryType: payload.deliveryType,
+        ...(payload.clarificationId
+            ? { clarificationId: payload.clarificationId }
+            : {}),
+    };
+}
+function isDeliveryAlreadyMarked(db, payload) {
+    if (payload.deliveryType === "task_result") {
+        const deliveredAt = payload.taskKind === "background_task"
+            ? (getBackgroundTask(db, payload.taskId)?.deliveredAt ?? null)
+            : (getBrowserTask(db, payload.taskId)?.deliveredAt ?? null);
+        return deliveredAt !== null;
+    }
+    if (!payload.clarificationId)
+        return false;
+    const clarDeliveredAt = payload.taskKind === "background_task"
+        ? (getBackgroundClarification(db, payload.clarificationId)?.deliveredAt ?? null)
+        : (getClarification(db, payload.clarificationId)?.deliveredAt ?? null);
+    return clarDeliveredAt !== null;
+}
+async function backfillDeliveredAtIfMessageExists(db, payload, nowMs) {
+    if (!hasExistingTaskDeliveryMessage(db, payload))
+        return false;
+    markDeliveredAt(db, payload, nowMs);
+    return true;
+}
+function hasExistingTaskDeliveryMessage(db, payload) {
+    const params = [
+        notificationTypeFor(payload),
+        payload.taskKind,
+        payload.taskId,
+        payload.taskId,
+    ];
+    const clarificationClause = payload.clarificationId
+        ? "AND json_extract(m.metadata, '$.clarificationId') = ?"
+        : "";
+    if (payload.clarificationId) {
+        params.push(payload.clarificationId);
+    }
+    const row = db
+        .prepare(`SELECT 1 AS found
+         FROM messages m
+        WHERE m.role = 'assistant'
+          AND json_extract(m.metadata, '$.notificationType') = ?
+          AND json_extract(m.metadata, '$.taskKind') = ?
+          AND (
+            json_extract(m.metadata, '$.taskId') = ?
+            OR json_extract(m.metadata, '$.deliveredTaskId') = ?
+          )
+          ${clarificationClause}
+        LIMIT 1`)
+        .get(...params);
+    return row !== undefined;
+}
+function markDeliveredAt(db, payload, nowMs) {
+    // `autonomous_forward` is fire-and-forget with no backing task row
+    // (its `taskId` is a synthetic UUID). There is nothing to stamp
+    // `delivered_at` on — writing to `browser_task` here would be an
+    // UPDATE against the wrong table that matches zero rows.
+    if (payload.taskKind === "autonomous_forward")
+        return;
+    if (payload.deliveryType === "task_result") {
+        if (payload.taskKind === "background_task") {
+            markBackgroundTaskDelivered(db, payload.taskId, nowMs);
+        }
+        else {
+            markBrowserTaskDelivered(db, payload.taskId, nowMs);
+        }
+        return;
+    }
+    if (payload.clarificationId) {
+        if (payload.taskKind === "background_task") {
+            markBackgroundClarificationDelivered(db, payload.clarificationId, nowMs);
+        }
+        else {
+            markClarificationDelivered(db, payload.clarificationId, nowMs);
+        }
+    }
+}
+export async function enqueueUndeliveredBrowserTaskDeliveries(params) {
+    const nowMs = params.nowMs ?? Date.now();
+    const limit = params.limit ?? 20;
+    let enqueued = 0;
+    // Recovery is text-only for reports: the `finish`-tool screenshot keys
+    // are not persisted on the `browser_task` row, so a report re-delivered
+    // after a crash cannot re-attach its screenshots (clarifications can —
+    // their `screenshotKey` IS persisted, see below). Acceptable: recovery
+    // only fires on the rare write-then-crash-before-DM window, and the text
+    // report still reaches the owner. (Open clarifications keep their image.)
+    for (const row of listUndeliveredBrowserTaskReports(params.db, limit)) {
+        if (!row.report)
+            continue;
+        await params.eventBus.put(createBrowserTaskResultDeliveryEvent({
+            taskId: row.id,
+            originatingChannel: row.originatingChannel,
+            title: row.description,
+            report: row.report,
+        }));
+        enqueued += 1;
+    }
+    // The list query INNER JOINs `browser_task` (state='awaiting_user') and
+    // folds in the task's channel + description, so no second fetch — and no
+    // unreachable "task missing" guard — is needed.
+    for (const clarification of listUndeliveredClarifications(params.db, nowMs, limit)) {
+        await params.eventBus.put(createBrowserTaskClarificationDeliveryEvent({
+            taskId: clarification.taskId,
+            originatingChannel: clarification.taskOriginatingChannel,
+            title: clarification.taskDescription,
+            clarificationId: clarification.id,
+            question: clarification.question,
+            contextSummary: clarification.contextSummary,
+            screenshotKey: clarification.screenshotKey,
+        }));
+        enqueued += 1;
+    }
+    return enqueued;
+}
+/**
+ * BACKGROUND_TASK_RUNNER_DESIGN.md §10.2 — delivery recovery sweep for
+ * background tasks. Re-enqueues `task.delivery` events for completed
+ * notify=true artifacts whose DM was never sent/recorded
+ * (`delivered_at IS NULL`) plus undelivered open clarifications. Run on
+ * the housekeeping tick (boot + periodic). Idempotent against the
+ * in-gate message-existence dedup — a re-enqueue after a successful send
+ * only back-fills `delivered_at`, never double-sends (§4.4).
+ */
+export async function enqueueUndeliveredBackgroundTaskDeliveries(params) {
+    const nowMs = params.nowMs ?? Date.now();
+    const limit = params.limit ?? 20;
+    let enqueued = 0;
+    for (const row of listUndeliveredBackgroundTaskReports(params.db, limit)) {
+        if (!row.draft)
+            continue;
+        await params.eventBus.put(createBackgroundTaskResultDeliveryEvent({
+            taskId: row.id,
+            originatingChannel: row.originatingChannel,
+            title: row.title ?? row.brief.slice(0, 80),
+            draft: row.draft,
+            report: row.report ?? row.draft,
+        }));
+        enqueued += 1;
+    }
+    // As above, the clarification list JOINs `background_task` and folds in
+    // the task's channel + title/brief, so the sweep needs no re-fetch and no
+    // unreachable "task missing" guard.
+    for (const clarification of listUndeliveredBackgroundClarifications(params.db, nowMs, limit)) {
+        await params.eventBus.put(createBackgroundTaskClarificationDeliveryEvent({
+            taskId: clarification.taskId,
+            originatingChannel: clarification.taskOriginatingChannel,
+            title: clarification.taskTitle ?? clarification.taskBrief.slice(0, 80),
+            clarificationId: clarification.id,
+            question: clarification.question,
+            contextSummary: clarification.contextSummary,
+        }));
+        enqueued += 1;
+    }
+    return enqueued;
+}

package/dist/core/dispatcher-types.d.ts

@@ -5,12 +5,12 @@
  * the daemon — adapter / service interfaces (`IDashboardStream`,
  * `INotificationManager`, `ISessionManager`, `IMessageRecorder`,
  * `IContextBuilder`, `IAuditLogger`), the `GetTaskFlow` callback, and the
- * value types used at API boundaries (`TriggerHourlyCheckOptions`,
- * `TriggerHourlyCheckResult`, `InFlightExecutionInfo`, `SetupMode`,
+ * value types used at API boundaries (`TriggerActivityScanOptions`,
+ * `TriggerActivityScanResult`, `InFlightExecutionInfo`, `SetupMode`,
  * `BangCommandDetail`, `ReplyActivityHandle`). It also hosts two pure
  * helpers that have no dependence on dispatcher instance state:
  * `buildLogErrorContext` (recovers backend/quota failure metadata from a
- * thrown error) and `parseStage2Verdict` (extracts the Stage 2 hourly-check
+ * thrown error) and `parseStage2Verdict` (extracts the Stage 2 activity-scan
  * triage JSON verdict from an LLM response).
  *
  * The dispatcher re-exports the public-surface members of this file so that
@@ -18,6 +18,7 @@
  * without modification — phase D-1 of `docs/design/appendices/file-split-plan.md`.
  */
 import type { Event, MessageEvent, AgentResult, BackendId, IntegrationKey, IntegrationState } from "@aitne/shared";
+import type { OutboundAttachmentRef } from "../adapters/types.js";
 import type { SessionInfoPayload } from "../api/chat-binding-query.js";
 import type { DeferredSessionEffects } from "./session-manager.js";
 export interface ReplyActivityHandle {
@@ -114,6 +115,15 @@ export interface INotificationManager {
          * WIKI_BUILDER_DESIGN.md §3.4-bis (completion notification path).
          */
         replyTo?: MessageReplyTarget;
+        /**
+         * Outbound media attachments, delivered alongside `message` in a
+         * single adapter send. Only honoured on the direct `replyTo` path
+         * (the manager hands them to `messageHub.sendToPlatform`); ignored
+         * on the proactive/batch paths. Used by the background task-delivery
+         * idle branch to re-attach browser-task screenshots inline
+         * (BACKGROUND_TASK_RUNNER_DESIGN.md Phase 1).
+         */
+        attachments?: readonly OutboundAttachmentRef[];
     }): Promise<void>;
     beginReplyActivity(event: MessageEvent): Promise<ReplyActivityHandle>;
 }
@@ -268,6 +278,21 @@ export interface IAuditLogger {
         trigger: "reactive" | "autonomous";
         backend?: BackendId;
         costSource?: AgentResult["costSource"];
+        /**
+         * Terminal result override for the success path. Defaults to
+         * `"success"`. The only other legal value here is `"partial"` — a
+         * session that ended cleanly (no backend error) but failed a post-run
+         * outcome check, e.g. RESEARCH_CLUSTER_COST_FIX_PLAN F5's
+         * journal-write verification. Hard errors take the `logError` path
+         * (`result='failed'`); this override never expresses failure.
+         */
+        result?: "success" | "partial";
+        /**
+         * Outcome-failure marker persisted to `agent_actions.error` when a run
+         * is downgraded to `result:"partial"` (F5: `'journal_write_missing'`).
+         * Paired with `result:"partial"`; ignored on a plain success.
+         */
+        error?: string;
         /**
          * Whether the agent made at least one PUT/PATCH call to /api/context/*.
          * Used for observer-event observability — see Phase 6 of
@@ -367,13 +392,27 @@ export interface IAuditLogger {
          */
         dailyWrite?: DailyWriteAuditDetail | null;
     }): void;
-    logSkip(event: Event, reason: string, trigger: "reactive" | "autonomous"): void;
+    logSkip(event: Event, reason: string, trigger: "reactive" | "autonomous", 
+    /** Optional structured context for the `detail` JSON column (N2/N3). */
+    detail?: Record<string, unknown>): void;
     logError(event: Event, error: Error, trigger: "reactive" | "autonomous", context?: {
         durationMs?: number;
         backendId?: BackendId;
         modelId?: string;
         failureKind?: string;
         failureCode?: string;
+        /**
+         * PREPASS_COST_REDUCTION_PLAN.md N1 — recovered spend for a failed
+         * turn the provider already billed. Only real recovered figures;
+         * never a guess (see `AuditLogger.logError`).
+         */
+        costUsd?: number;
+        costSource?: string;
+        tokensInput?: number;
+        tokensOutput?: number;
+        tokensCacheCreation?: number;
+        tokensCacheRead?: number;
+        numTurns?: number;
         /**
          * Pre-pass fan-out failure block. Mirrors the `prePass` payload on
          * `logAction` so `MetricsCollector.collectPrePassMetrics` can see
@@ -474,7 +513,7 @@ export interface BangCommandDetail {
     status: "ok" | "skipped" | "unknown" | "invalid_args" | "paused_decline" | "paused_blocked";
     [extra: string]: unknown;
 }
-export type TriggerHourlyCheckSkipReason = "morning_routine_active" | "hourly_check_in_progress" | "below_threshold" | "setup_incomplete" | "setup_in_progress" | "vault_degraded" | "user_paused" | "morning_routine_pending_for_today" | "gate_stage0_silent" | "gate_stage2_log_only";
+export type TriggerActivityScanSkipReason = "morning_routine_active" | "activity_scan_in_progress" | "below_threshold" | "setup_incomplete" | "setup_in_progress" | "vault_degraded" | "user_paused" | "morning_routine_pending_for_today" | "gate_stage0_silent" | "gate_stage2_log_only";
 export type SetupMode = "initial" | "update";
 /**
  * Unwrap the partial-run context the audit logger needs for a failed
@@ -489,16 +528,16 @@ export declare function buildLogErrorContext(err: unknown, durationMs: number):
     failureKind?: string;
     failureCode?: string;
 };
-export interface TriggerHourlyCheckOptions {
+export interface TriggerActivityScanOptions {
     force?: boolean;
     /** Optional model hint — injected as `requestedModel` on the enqueued
-     *  routine.hourly_check event so the user can force an Opus run from
+     *  routine.activity_scan event so the user can force an Opus run from
      *  /api/agent/run-now without touching process_backend_config. */
     requestedModel?: "sonnet" | "opus";
 }
-export interface TriggerHourlyCheckResult {
+export interface TriggerActivityScanResult {
     status: "queued" | "skipped";
-    reason?: TriggerHourlyCheckSkipReason;
+    reason?: TriggerActivityScanSkipReason;
     pendingCount?: number;
     minObservations: number;
     forced: boolean;