@mono-agent/agent-app 0.3.0 → 0.4.1

package/dist/recipes/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/recipes/types.ts"],"names":[],"mappings":"AA0EA,wEAAwE;AACxE,MAAM,UAAU,mBAAmB,CACjC,MAAmB,EACnB,YAA+B,EAAE;IAEjC,MAAM,MAAM,GAAuC,EAAE,CAAC;IACtD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC;IAC1D,CAAC;IACD,iFAAiF;IACjF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/request-model-override.d.ts

@@ -0,0 +1,67 @@
+import type { LocalProviderDefinition, LocalProviderRuntimeOptions, RuntimeModelReference } from "@mono-agent/runtime-adapter";
+/**
+ * Per-request runtime-options extension that applies a per-turn model/effort
+ * override carried on webhook (`metadata.webhook`), cron (`metadata.cron`), or
+ * interactive TUI (`metadata.tui`) request metadata — an operator can pick a
+ * per-session model/effort from the TUI just as a trigger can pin one. The
+ * adapters carry the override as raw strings; this is the
+ * first place with both the model parser and the effort enum, so validation
+ * lives here. An invalid value is WARNED and IGNORED (the turn falls back to the
+ * harness default) rather than failing — a bad dynamic webhook `model` must not
+ * 500 the request.
+ *
+ * Execution mode is NOT set here: the harness derives it from the effective model
+ * plus the host's configured executionMode (keeping a compatible host mode, e.g.
+ * claude in `cli`, and only falling back to the model default for an incompatible
+ * one, e.g. a `codex:*` override under an `sdk` host).
+ *
+ * A model override OWNS the local-provider endpoint block. Whenever a VALID model
+ * override is applied, this extension SETS the four endpoint fields
+ * (`customProvider`/`customModel`/`modelCapabilities`/`isPrivateProvider`):
+ *   - LOCAL override (`sdk === "pi"` with a configured provider id): recompute the
+ *     block for the OVERRIDE model via `runtimeOptionsForLocalProvider`.
+ *   - CLOUD/registry override, an UNCONFIGURED local provider id, or a
+ *     misconfigured provider: set the four fields to `null` to explicitly CLEAR
+ *     the host default's block.
+ * This is required because the host default block is computed ONCE from
+ * `config.runtime.model` at harness creation, and the pi runtime routes on
+ * `customProvider` PRESENCE alone — so a cloud override under an all-LOCAL default
+ * would otherwise inherit the default's local endpoint and send the cloud model to
+ * localhost (same mis-route for an unconfigured local provider id). The harness
+ * `mergeRuntimeOptions` applies the override AFTER the host default
+ * (last-writer-wins) and reads `null` on these keys as "delete", so a set block
+ * REPLACES the default and a null CLEARS it. An effort-only / no-model turn leaves
+ * the block untouched (the default's block is correct for the default model).
+ */
+export interface RequestModelOverrideLogger {
+    warn?(message: string, metadata?: Record<string, unknown>): void;
+}
+export interface RequestModelOverrideOptions {
+    readonly logger?: RequestModelOverrideLogger;
+    /**
+     * Configured local providers (`config.providers?.local`). When an override
+     * names a model one of these serves, the extension recomputes the provider
+     * endpoint block so the override reaches the right local endpoint instead of
+     * inheriting the host default's block.
+     */
+    readonly localProviders?: readonly LocalProviderDefinition[];
+}
+interface RequestModelOverrideInput {
+    readonly request: {
+        readonly metadata?: Record<string, unknown>;
+    };
+}
+interface RequestModelOverrideResult {
+    readonly runtimeOptions: {
+        model?: RuntimeModelReference;
+        effort?: string;
+        customProvider?: LocalProviderRuntimeOptions["customProvider"] | null;
+        customModel?: LocalProviderRuntimeOptions["customModel"] | null;
+        modelCapabilities?: LocalProviderRuntimeOptions["modelCapabilities"] | null;
+        isPrivateProvider?: LocalProviderRuntimeOptions["isPrivateProvider"] | null;
+    };
+    readonly cleanup: () => Promise<void>;
+}
+export declare function createRequestModelOverrideRuntimeExtension(options?: RequestModelOverrideOptions): (input: RequestModelOverrideInput) => Promise<RequestModelOverrideResult>;
+export {};
+//# sourceMappingURL=request-model-override.d.ts.map

package/dist/request-model-override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-model-override.d.ts","sourceRoot":"","sources":["../src/request-model-override.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,2BAA2B,EAC3B,qBAAqB,EACtB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAClE;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,0BAA0B,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC9D;AAED,UAAU,yBAAyB;IACjC,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;CACnE;AAED,UAAU,0BAA0B;IAClC,QAAQ,CAAC,cAAc,EAAE;QACvB,KAAK,CAAC,EAAE,qBAAqB,CAAC;QAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;QAIhB,cAAc,CAAC,EAAE,2BAA2B,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC;QACtE,WAAW,CAAC,EAAE,2BAA2B,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;QAChE,iBAAiB,CAAC,EAAE,2BAA2B,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC;QAC5E,iBAAiB,CAAC,EAAE,2BAA2B,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC;KAC7E,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAID,wBAAgB,0CAA0C,CACxD,OAAO,CAAC,EAAE,2BAA2B,GACpC,CAAC,KAAK,EAAE,yBAAyB,KAAK,OAAO,CAAC,0BAA0B,CAAC,CAoC3E"}

package/dist/request-model-override.js

@@ -0,0 +1,96 @@
+import { EFFORT_LEVELS } from "@mono-agent/config";
+import { parseMonoRuntimeModelReference, runtimeOptionsForLocalProvider } from "@mono-agent/runtime-adapter";
+const EFFORT_SET = new Set(EFFORT_LEVELS);
+export function createRequestModelOverrideRuntimeExtension(options) {
+    const logger = options?.logger;
+    const localProviders = options?.localProviders;
+    return async (input) => {
+        const { model: rawModel, effort: rawEffort } = readOverride(input.request.metadata);
+        const runtimeOptions = {};
+        if (rawModel !== undefined) {
+            let parsed;
+            try {
+                parsed = parseMonoRuntimeModelReference(rawModel);
+            }
+            catch (error) {
+                logger?.warn?.("Ignoring invalid per-request model override.", {
+                    model: rawModel,
+                    reason: error instanceof Error ? error.message : String(error),
+                });
+            }
+            if (parsed !== undefined) {
+                runtimeOptions.model = parsed;
+                applyLocalProviderBlock(runtimeOptions, parsed, rawModel, localProviders, logger);
+            }
+        }
+        if (rawEffort !== undefined) {
+            if (EFFORT_SET.has(rawEffort)) {
+                runtimeOptions.effort = rawEffort;
+            }
+            else {
+                logger?.warn?.("Ignoring invalid per-request effort override.", {
+                    effort: rawEffort,
+                    valid: [...EFFORT_SET],
+                });
+            }
+        }
+        return { runtimeOptions, cleanup: async () => { } };
+    };
+}
+/**
+ * OWN the endpoint block for a valid model override. For a model served by a
+ * configured LOCAL provider, `runtimeOptionsForLocalProvider` yields the block and
+ * we SET all four fields. For a cloud/registry model or an unconfigured provider
+ * id it returns `{}`, so `x ?? null` sets each field to `null` — the harness merge
+ * reads that as an explicit CLEAR of the host default's local block (undefined
+ * would silently inherit it and mis-route the run to localhost). A genuinely
+ * MISCONFIGURED provider (e.g. an untrusted public HTTP baseUrl) throws; that is
+ * warned-and-ignored and treated as non-local (block cleared) so a bad override
+ * never fails the turn — the model ref still applies.
+ */
+function applyLocalProviderBlock(runtimeOptions, model, rawModel, localProviders, logger) {
+    let local;
+    try {
+        local = runtimeOptionsForLocalProvider(model, localProviders);
+    }
+    catch (error) {
+        logger?.warn?.("Ignoring local-provider endpoint for per-request model override.", {
+            model: rawModel,
+            reason: error instanceof Error ? error.message : String(error),
+        });
+        local = {};
+    }
+    runtimeOptions.customProvider = local.customProvider ?? null;
+    runtimeOptions.customModel = local.customModel ?? null;
+    runtimeOptions.modelCapabilities = local.modelCapabilities ?? null;
+    runtimeOptions.isPrivateProvider = local.isPrivateProvider ?? null;
+}
+/**
+ * Read model/effort from webhook, cron, or TUI request metadata. Webhook takes
+ * precedence, then cron, then an interactive TUI per-session override — a turn
+ * is only ever one of the three. A turn carrying none of these blocks (e.g. an
+ * ordinary chat turn) returns `{}` and the extension is a no-op.
+ */
+function readOverride(metadata) {
+    if (!isRecord(metadata)) {
+        return {};
+    }
+    const source = isRecord(metadata.webhook)
+        ? metadata.webhook
+        : isRecord(metadata.cron)
+            ? metadata.cron
+            : isRecord(metadata.tui)
+                ? metadata.tui
+                : undefined;
+    if (source === undefined) {
+        return {};
+    }
+    return {
+        ...(typeof source.model === "string" ? { model: source.model } : {}),
+        ...(typeof source.effort === "string" ? { effort: source.effort } : {}),
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//# sourceMappingURL=request-model-override.js.map

package/dist/request-model-override.js.map

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

package/dist/runs-health.d.ts

@@ -0,0 +1,22 @@
+import { type RecordedRunListItem } from "@mono-agent/observability";
+export declare const RUNS_HEALTH_MAX_RUNS = 50;
+export declare const RUNS_HEALTH_RECENT_RUNS = 5;
+export type RunsHealthStatus = "ok" | "waiting" | "disabled";
+export interface RunsHealthDisplay {
+    readonly status: RunsHealthStatus;
+    readonly details: readonly string[];
+}
+export interface BuildRunsHealthDisplayInput {
+    readonly artifactDir: string;
+    readonly totalRuns?: number;
+    readonly runs: readonly RecordedRunListItem[];
+    readonly warnings: readonly string[];
+    readonly selectedSkills?: readonly string[];
+    readonly includeSelectedSkills?: boolean;
+    readonly runOwnerAlive?: boolean;
+    readonly nowMs?: number;
+    readonly maxRuns?: number;
+}
+export declare function buildRunsHealthDisplay(input: BuildRunsHealthDisplayInput): RunsHealthDisplay;
+export declare function formatSelectedSkillsLine(selectedSkills: readonly string[] | undefined): string;
+//# sourceMappingURL=runs-health.d.ts.map

package/dist/runs-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs-health.d.ts","sourceRoot":"","sources":["../src/runs-health.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,mBAAmB,EAEzB,MAAM,2BAA2B,CAAC;AAEnC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,UAAU,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAKD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,iBAAiB,CAuE5F;AAED,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,CAM9F"}

package/dist/runs-health.js

@@ -0,0 +1,144 @@
+import { describeRunFailureKind, RUNS_HEALTH_STALE_RUNNING_MS, } from "@mono-agent/observability";
+export const RUNS_HEALTH_MAX_RUNS = 50;
+export const RUNS_HEALTH_RECENT_RUNS = 5;
+const RUN_SUMMARY_STATUSES = ["running", "succeeded", "failed", "cancelled", "interrupted"];
+const FAILED_LIKE_RUN_STATUSES = new Set(["failed", "cancelled", "interrupted"]);
+export function buildRunsHealthDisplay(input) {
+    const maxRuns = input.maxRuns ?? RUNS_HEALTH_MAX_RUNS;
+    const now = input.nowMs ?? Date.now();
+    const totalRuns = input.totalRuns ?? input.runs.length;
+    const details = [
+        ...(input.includeSelectedSkills ? [formatSelectedSkillsLine(input.selectedSkills)] : []),
+        `Artifact dir: ${input.artifactDir}`,
+        `Recorded runs: ${totalRuns} total; showing ${input.runs.length} recent (max ${maxRuns}).`,
+    ];
+    let hasWarnings = false;
+    for (const warning of input.warnings) {
+        hasWarnings = true;
+        details.push(`[WARN] Run artifact reader: ${warning}`);
+    }
+    if (input.runs.length === 0) {
+        details.push("No runs recorded yet.");
+        return { status: hasWarnings ? "waiting" : "disabled", details };
+    }
+    details.push(`Last runs: ${formatRunExamples(input.runs, now)}.`);
+    const statusCounts = statusHistogram(input.runs);
+    details.push(`Recent status counts: ${RUN_SUMMARY_STATUSES.map((status) => `${status}=${statusCounts[status]}`).join(", ")}.`);
+    const staleRunning = input.runs.filter((run) => isStaleRunningRun(run, now));
+    if (staleRunning.length > 0) {
+        hasWarnings = true;
+        details.push(`[WARN] Stale running runs older than ${RUNS_HEALTH_STALE_RUNNING_MS / 60_000}m: ${formatRunExamples(staleRunning, now)}.`);
+    }
+    const runningWhileOwnerGone = input.runOwnerAlive === false
+        ? input.runs.filter((run) => run.status === "running")
+        : [];
+    if (runningWhileOwnerGone.length > 0) {
+        hasWarnings = true;
+        details.push(`[WARN] Running summaries while process is gone: ${formatRunExamples(runningWhileOwnerGone, now)}.`);
+    }
+    const unsuccessful = input.runs.filter((run) => FAILED_LIKE_RUN_STATUSES.has(run.status));
+    if (unsuccessful.length > 0) {
+        hasWarnings = true;
+        details.push(`[WARN] Recent non-successful runs: ${formatRunExamples(unsuccessful, now)}.`);
+    }
+    if (statusCounts.cancelled > 0) {
+        hasWarnings = true;
+        details.push(`[WARN] Cancelled recent runs: ${statusCounts.cancelled}.`);
+    }
+    if (statusCounts.interrupted > 0) {
+        hasWarnings = true;
+        details.push(`[WARN] Interrupted recent runs: ${statusCounts.interrupted}.`);
+    }
+    const failureKindCounts = failureKindHistogram(input.runs);
+    if (failureKindCounts.length > 0) {
+        hasWarnings = true;
+        details.push(`[WARN] Failure kinds: ${failureKindCounts.map(([kind, count]) => `${kind}=${count}`).join(", ")}.`);
+        for (const [kind, count] of failureKindCounts) {
+            const description = describeRunFailureKind({ failureKind: kind });
+            const prefix = description.known ? description.kind : `${description.kind} (unclassified)`;
+            details.push(`[WARN] ${description.label} [${prefix}, ${count} recent]: ${description.explanation} Next: ${description.nextStep}`);
+        }
+    }
+    else {
+        details.push("Failure kinds: none in recent window.");
+    }
+    return { status: hasWarnings ? "waiting" : "ok", details };
+}
+export function formatSelectedSkillsLine(selectedSkills) {
+    if (selectedSkills === undefined) {
+        return "Active skills: unavailable.";
+    }
+    const names = selectedSkills.map((skill) => skill.trim()).filter(Boolean);
+    return names.length === 0 ? "Active skills: none." : `Active skills: ${names.join(", ")}.`;
+}
+function statusHistogram(runs) {
+    const counts = {
+        running: 0,
+        succeeded: 0,
+        failed: 0,
+        cancelled: 0,
+        interrupted: 0,
+    };
+    for (const run of runs) {
+        counts[run.status] += 1;
+    }
+    return counts;
+}
+function isStaleRunningRun(run, now) {
+    if (run.status !== "running" || run.startedAt === undefined) {
+        return false;
+    }
+    const startedAtMs = Date.parse(run.startedAt);
+    return Number.isFinite(startedAtMs) && now - startedAtMs > RUNS_HEALTH_STALE_RUNNING_MS;
+}
+function failureKindHistogram(runs) {
+    const counts = new Map();
+    for (const run of runs) {
+        const failureKind = displayFailureKind(run);
+        if (failureKind !== undefined) {
+            counts.set(failureKind, (counts.get(failureKind) ?? 0) + 1);
+        }
+    }
+    return [...counts.entries()].sort(([leftKind, leftCount], [rightKind, rightCount]) => rightCount - leftCount || leftKind.localeCompare(rightKind));
+}
+function displayFailureKind(run) {
+    const failureKind = run.failureKind?.trim();
+    if (failureKind !== undefined && failureKind.length > 0) {
+        return failureKind;
+    }
+    if (!FAILED_LIKE_RUN_STATUSES.has(run.status)) {
+        return undefined;
+    }
+    return describeRunFailureKind({ status: run.status }).kind;
+}
+function formatRunExamples(runs, nowMs) {
+    const shown = runs.slice(0, RUNS_HEALTH_RECENT_RUNS).map((run) => `${run.runId} ${run.status} ${formatRelativeAge(runTimestamp(run), nowMs)}`);
+    const remaining = runs.length - shown.length;
+    return remaining > 0 ? `${shown.join(", ")} and ${remaining} more` : shown.join(", ");
+}
+function runTimestamp(run) {
+    return run.endedAt ?? run.updatedAt ?? run.startedAt;
+}
+function formatRelativeAge(timestamp, nowMs) {
+    if (timestamp === undefined) {
+        return "age unknown";
+    }
+    const parsed = Date.parse(timestamp);
+    if (!Number.isFinite(parsed)) {
+        return "age unknown";
+    }
+    const elapsedSeconds = Math.max(0, Math.floor((nowMs - parsed) / 1000));
+    if (elapsedSeconds < 60) {
+        return `${elapsedSeconds}s ago`;
+    }
+    const elapsedMinutes = Math.floor(elapsedSeconds / 60);
+    if (elapsedMinutes < 60) {
+        return `${elapsedMinutes}m ago`;
+    }
+    const elapsedHours = Math.floor(elapsedMinutes / 60);
+    if (elapsedHours < 48) {
+        return `${elapsedHours}h ago`;
+    }
+    return `${Math.floor(elapsedHours / 24)}d ago`;
+}
+//# sourceMappingURL=runs-health.js.map

package/dist/runs-health.js.map

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

package/dist/seen-conversations.d.ts

@@ -0,0 +1,22 @@
+import type { ChannelId } from "./channels.js";
+/** A real conversation the agent has handled, recovered from run artifacts. */
+export interface SeenConversation {
+    /** The base (de-bucketed) conversationId to use as a `notify` destination. */
+    readonly conversationId: string;
+    readonly channelId: ChannelId;
+    /** ISO timestamp of the most recent run on this conversation, if recorded. */
+    readonly lastSeen?: string;
+}
+export interface ListSeenOptions {
+    /** Cap on the number of (newest-first) summary files read. Default 2000. */
+    readonly limit?: number;
+}
+/**
+ * Distinct push-channel conversationIds the agent has actually handled, read from
+ * the run-artifact summaries in `artifactDir`. Synthetic ids (`cron:`/`webhook:`/…)
+ * are dropped via {@link channelIdForConversation}; daily-rollover buckets are
+ * stripped to the base id (the form a `notify` destination uses) and deduped to the
+ * most recent sighting. Sorted newest-first. A missing dir yields an empty list.
+ */
+export declare function listSeenNotifyDestinations(artifactDir: string, options?: ListSeenOptions): Promise<readonly SeenConversation[]>;
+//# sourceMappingURL=seen-conversations.d.ts.map

package/dist/seen-conversations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seen-conversations.d.ts","sourceRoot":"","sources":["../src/seen-conversations.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG/C,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAQD;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAwDtC"}

package/dist/seen-conversations.js

@@ -0,0 +1,120 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { channelIdForConversation } from "./proactive-notify.js";
+const DEFAULT_LIMIT = 2000;
+const SUMMARY_SUFFIX = ".summary.json";
+const ROLLOVER_BUCKET = /#\d{4}-\d{2}-\d{2}$/u;
+/** Max summary files statted concurrently, to bound open fds and avoid EMFILE. */
+const STAT_BATCH_SIZE = 64;
+/**
+ * Distinct push-channel conversationIds the agent has actually handled, read from
+ * the run-artifact summaries in `artifactDir`. Synthetic ids (`cron:`/`webhook:`/…)
+ * are dropped via {@link channelIdForConversation}; daily-rollover buckets are
+ * stripped to the base id (the form a `notify` destination uses) and deduped to the
+ * most recent sighting. Sorted newest-first. A missing dir yields an empty list.
+ */
+export async function listSeenNotifyDestinations(artifactDir, options = {}) {
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    let entries;
+    try {
+        entries = await readdir(artifactDir);
+    }
+    catch {
+        // Dir absent (agent never ran) or unreadable → nothing seen yet.
+        return [];
+    }
+    const summaries = entries.filter((name) => name.endsWith(SUMMARY_SUFFIX));
+    // Summary filenames are conversationId-based with no embedded time ordering, so a
+    // full stat pass is required to learn each file's mtime before we can take the
+    // newest `limit`. We stat in bounded batches (not one big Promise.all over every
+    // summary) to keep open file descriptors capped and avoid EMFILE/IO spikes on a
+    // busy agent with thousands of artifacts.
+    const withMtime = [];
+    for (let i = 0; i < summaries.length; i += STAT_BATCH_SIZE) {
+        const batch = summaries.slice(i, i + STAT_BATCH_SIZE);
+        const stated = await Promise.all(batch.map(async (name) => {
+            try {
+                return { name, mtimeMs: (await stat(join(artifactDir, name))).mtimeMs };
+            }
+            catch {
+                return { name, mtimeMs: 0 };
+            }
+        }));
+        withMtime.push(...stated);
+    }
+    // Newest files first, then cap, so a busy agent's scan stays bounded.
+    withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const latest = new Map();
+    for (const { name } of withMtime.slice(0, limit)) {
+        const parsed = await readSummary(join(artifactDir, name));
+        if (parsed === undefined) {
+            continue;
+        }
+        const channelId = channelIdForConversation(parsed.conversationId);
+        if (channelId === undefined) {
+            continue; // synthetic / non-push destination
+        }
+        const conversationId = parsed.conversationId.replace(ROLLOVER_BUCKET, "");
+        const seen = {
+            conversationId,
+            channelId,
+            ...(parsed.lastSeen === undefined ? {} : { lastSeen: parsed.lastSeen }),
+        };
+        const prior = latest.get(conversationId);
+        if (prior === undefined || isNewer(seen.lastSeen, prior.lastSeen)) {
+            latest.set(conversationId, seen);
+        }
+    }
+    return [...latest.values()].sort((a, b) => compareLastSeen(b.lastSeen, a.lastSeen));
+}
+async function readSummary(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof json !== "object" || json === null) {
+        return undefined;
+    }
+    const record = json;
+    const conversationId = record.conversationId;
+    if (typeof conversationId !== "string" || conversationId.length === 0) {
+        return undefined;
+    }
+    const lastSeen = firstString(record.endedAt, record.updatedAt, record.startedAt);
+    return { conversationId, ...(lastSeen === undefined ? {} : { lastSeen }) };
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function isNewer(candidate, current) {
+    return compareLastSeen(candidate, current) > 0;
+}
+/** Compare ISO timestamps; a missing timestamp sorts oldest. */
+function compareLastSeen(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (a === undefined) {
+        return -1;
+    }
+    if (b === undefined) {
+        return 1;
+    }
+    return a < b ? -1 : 1;
+}
+//# sourceMappingURL=seen-conversations.js.map

package/dist/seen-conversations.js.map

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

package/dist/sessions.d.ts

@@ -0,0 +1,21 @@
+import type { MonoAgentAppConfigInput } from "./app-config.js";
+export interface PurgeSessionsResult {
+    /** The resolved sessions root, or undefined when sessions are in-memory only. */
+    readonly root?: string;
+    /** True when an on-disk sessions store existed and was removed. */
+    readonly removed: boolean;
+    /** Count of removed `*.jsonl` session files (best-effort; 0 when none/unknown). */
+    readonly files: number;
+}
+/**
+ * Remove the durable pi-session store so the next start begins with fresh sessions
+ * instead of resuming persisted transcripts. A no-op (`removed: false`) when no
+ * on-disk store is configured (in-memory sessions) or the directory does not exist.
+ *
+ * The runtime recreates the directory on the next session, and the agent's durable
+ * memory lives elsewhere (`memory.path`), so this drops only resumable conversation
+ * transcripts — not the knowledge base. Stop the worker before calling this so it is
+ * not writing sessions while they are deleted.
+ */
+export declare function purgeSessions(input: MonoAgentAppConfigInput): Promise<PurgeSessionsResult>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgBhG"}

package/dist/sessions.js

@@ -0,0 +1,45 @@
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveAppSessionsRoot } from "./app-config.js";
+/**
+ * Remove the durable pi-session store so the next start begins with fresh sessions
+ * instead of resuming persisted transcripts. A no-op (`removed: false`) when no
+ * on-disk store is configured (in-memory sessions) or the directory does not exist.
+ *
+ * The runtime recreates the directory on the next session, and the agent's durable
+ * memory lives elsewhere (`memory.path`), so this drops only resumable conversation
+ * transcripts — not the knowledge base. Stop the worker before calling this so it is
+ * not writing sessions while they are deleted.
+ */
+export async function purgeSessions(input) {
+    const root = await resolveAppSessionsRoot(input);
+    if (root === undefined) {
+        return { removed: false, files: 0 };
+    }
+    let files = 0;
+    try {
+        files = await countSessionFiles(root);
+    }
+    catch {
+        // The store may not exist yet; treat it as nothing to remove.
+        return { root, removed: false, files: 0 };
+    }
+    await rm(root, { recursive: true, force: true });
+    return { root, removed: true, files };
+}
+/** Recursively count `*.jsonl` session files under a sessions root. */
+async function countSessionFiles(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    let total = 0;
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            total += await countSessionFiles(full);
+        }
+        else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+            total += 1;
+        }
+    }
+    return total;
+}
+//# sourceMappingURL=sessions.js.map

package/dist/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAYzD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAA8B;IAChE,MAAM,IAAI,GAAG,MAAM,sBAAsB,CAAC,KAAK,CAAC,CAAC;IACjD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACtC,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;QAC9D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACxC,CAAC;AAED,uEAAuE;AACvE,KAAK,UAAU,iBAAiB,CAAC,GAAW;IAC1C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,KAAK,IAAI,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3D,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/setup.d.ts

@@ -0,0 +1,29 @@
+import type { WithChannel } from "./init.js";
+import type { AgentRecipe, RecipeInputValues } from "./recipes/index.js";
+export interface SetupPromptSource {
+    question(prompt: string): Promise<string>;
+}
+export interface SecretChecklistItem {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly envVar?: string;
+}
+export interface CollectSetupOptions {
+    readonly prompt: SetupPromptSource;
+    readonly recipe?: AgentRecipe;
+    readonly model?: string;
+    readonly fallbackModels?: readonly string[];
+    readonly withChannels?: readonly WithChannel[];
+    readonly recipes?: readonly AgentRecipe[];
+}
+export interface CollectedSetupOptions {
+    readonly recipe: AgentRecipe;
+    readonly recipeInputs: RecipeInputValues;
+    readonly fallbackModels: readonly string[];
+    readonly withChannels: readonly WithChannel[];
+    readonly secrets: readonly SecretChecklistItem[];
+}
+export declare function collectSetupOptions(options: CollectSetupOptions): Promise<CollectedSetupOptions>;
+export declare function renderSetupRecipeMenu(recipes?: readonly AgentRecipe[]): string;
+//# sourceMappingURL=setup.d.ts.map

package/dist/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAe,MAAM,oBAAoB,CAAC;AAEtF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAClD;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAwBtG;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,SAAS,WAAW,EAAmB,GAAG,MAAM,CAO9F"}