@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/agent/agent-projections.d.ts

@@ -0,0 +1,65 @@
+import type { AgentListItemPayload, AgentSnapshotPayload, RecentProviderSessionDescriptorPayload } from "../messages.js";
+import type { StoredAgentRecord } from "./agent-storage.js";
+import type { AgentProvider, AgentRuntimeInfo, ImportableProviderSession } from "./agent-sdk-types.js";
+import type { ManagedAgent } from "./agent-manager.js";
+export type { ManagedAgent };
+interface ProjectionOptions {
+    title?: string | null;
+    createdAt?: string;
+    internal?: boolean;
+    /**
+     * DISPLAY half of the schedule join: the earliest upcoming fire from an ACTIVE
+     * schedule targeting this agent, or null when the caller joined the schedule
+     * store and found nothing that will fire.
+     *
+     * Passed IN rather than read here on purpose: these projections are pure and
+     * synchronous, while the schedule store is async and file-backed. The caller
+     * that already awaits (Session.listAgentPayloads, and the two private builders
+     * it funnels through) does the join once for the whole batch and hands the
+     * answer down. Omitting it leaves `nextFireAt` off the payload entirely, which
+     * the wire schema defines as "not computed" rather than "no schedule".
+     */
+    nextFireAt?: string | null;
+    /**
+     * CLASSIFIER half of the schedule join: whether an active OR paused schedule
+     * targets this agent. Travels with `nextFireAt` from the same caller and the
+     * same store listing, so the pair can never disagree about which listing it
+     * describes.
+     *
+     * Omitting it leaves `hasRoutine` off the payload, which the wire schema
+     * defines as "not computed" and readers treat as false.
+     */
+    hasRoutine?: boolean;
+}
+interface RecentProviderSessionProjectionOptions {
+    providerLabel: string;
+}
+export declare function resolveEffectiveThinkingOptionId(options: {
+    runtimeInfo?: AgentRuntimeInfo | null;
+    configuredThinkingOptionId?: string | null;
+}): string | null;
+/**
+ * Half of the agent predicate (the other half is an active schedule targeting the
+ * agent). Whitespace-only counts as absent: a prompt of spaces configures nothing,
+ * so treating it as present would put an unconfigured session on the Agents page.
+ */
+export declare function deriveHasSystemPrompt(config: {
+    systemPrompt?: string | null;
+} | null | undefined): boolean;
+/**
+ * MCP server NAMES for the wire. The configs themselves never leave the daemon:
+ * their `env` is where tokens live, and this payload reaches the app, the CLI and
+ * every MCP consumer.
+ */
+export declare function deriveMcpServerNames(config: {
+    mcpServers?: Record<string, unknown> | null;
+} | null | undefined): string[] | undefined;
+export declare function toStoredAgentRecord(agent: ManagedAgent, options?: ProjectionOptions): StoredAgentRecord;
+export declare function toAgentPayload(agent: ManagedAgent, options?: ProjectionOptions): AgentSnapshotPayload;
+export declare function buildStoredAgentPayload(record: StoredAgentRecord, validProviders: Iterable<AgentProvider>, options?: Pick<ProjectionOptions, "nextFireAt" | "hasRoutine">): AgentSnapshotPayload;
+export declare function toAgentListItemPayload(agent: AgentSnapshotPayload): AgentListItemPayload;
+export declare function toRecentProviderSessionDescriptorPayload(session: ImportableProviderSession & {
+    provider: string;
+}, options: RecentProviderSessionProjectionOptions): RecentProviderSessionDescriptorPayload;
+export declare function resolveStoredAgentPayloadUpdatedAt(record: StoredAgentRecord): string;
+//# sourceMappingURL=agent-projections.d.ts.map

package/dist/server/server/agent/agent-projections.js

@@ -0,0 +1,548 @@
+import { isStoredAgentProviderAvailable, toAgentPersistenceHandle } from "../persistence-hooks.js";
+function normalizeThinkingOptionId(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : null;
+}
+function normalizeLabels(labels) {
+    if (!labels) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(labels).filter((entry) => typeof entry[1] === "string"));
+}
+export function resolveEffectiveThinkingOptionId(options) {
+    const runtimeInfo = options.runtimeInfo;
+    if (runtimeInfo && "thinkingOptionId" in runtimeInfo) {
+        return normalizeThinkingOptionId(runtimeInfo.thinkingOptionId);
+    }
+    return normalizeThinkingOptionId(options.configuredThinkingOptionId);
+}
+/**
+ * Half of the agent predicate (the other half is an active schedule targeting the
+ * agent). Whitespace-only counts as absent: a prompt of spaces configures nothing,
+ * so treating it as present would put an unconfigured session on the Agents page.
+ */
+export function deriveHasSystemPrompt(config) {
+    const systemPrompt = config?.systemPrompt;
+    return typeof systemPrompt === "string" && systemPrompt.trim().length > 0;
+}
+/**
+ * MCP server NAMES for the wire. The configs themselves never leave the daemon:
+ * their `env` is where tokens live, and this payload reaches the app, the CLI and
+ * every MCP consumer.
+ */
+export function deriveMcpServerNames(config) {
+    const names = Object.keys(config?.mcpServers ?? {});
+    return names.length > 0 ? names : undefined;
+}
+/**
+ * A short durable description (`goal`, `jobToBeDone`) for the wire.
+ *
+ * Whitespace-only collapses to undefined, matching `deriveHasSystemPrompt`: a
+ * goal of spaces states nothing, and emitting it would render an empty line on
+ * every surface that shows the field. The wire schema is `.optional()` and not
+ * nullable, so there is no third state to preserve here: either the agent has
+ * a description or the key is absent.
+ */
+function deriveDurableText(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * `null`/absent both mean "no allowlist"; an empty array means an allowlist that
+ * permits nothing. Those are different facts, so an empty array is preserved and
+ * only a missing field collapses to undefined.
+ */
+function deriveAllowedTools(config) {
+    const allowedTools = config?.allowedTools;
+    if (allowedTools === undefined)
+        return undefined;
+    return allowedTools === null ? null : [...allowedTools];
+}
+/**
+ * The durability fields both projections carry, built once so the two builders
+ * agree by construction instead of by copy.
+ *
+ * Present-vs-absent is load-bearing on every field here and the conditional
+ * spreads are what preserve it: an omitted key means "not computed", which the
+ * wire schema and every reader treat as "no claim made". `nextFireAt: null`
+ * ("joined the schedule store, nothing will fire") is a DIFFERENT fact from an
+ * absent `nextFireAt`, and the same holds for `hasRoutine`. Hence the `in`
+ * checks on `options` rather than a truthiness test on its values.
+ */
+function buildAgentDurabilityFields(config, options) {
+    const allowedTools = deriveAllowedTools(config);
+    const mcpServerNames = deriveMcpServerNames(config);
+    // The TEXT, not a boolean: these are one-line human-authored descriptions
+    // written to be read on the row. See the schema comment on
+    // AgentSnapshotPayloadSchema.goal for why systemPrompt goes the other way.
+    const goal = deriveDurableText(config?.goal);
+    const jobToBeDone = deriveDurableText(config?.jobToBeDone);
+    return {
+        hasSystemPrompt: deriveHasSystemPrompt(config),
+        ...(goal !== undefined ? { goal } : {}),
+        ...(jobToBeDone !== undefined ? { jobToBeDone } : {}),
+        ...(allowedTools !== undefined ? { allowedTools } : {}),
+        ...(mcpServerNames ? { mcpServerNames } : {}),
+        ...(options && "nextFireAt" in options ? { nextFireAt: options.nextFireAt ?? null } : {}),
+        ...(options && "hasRoutine" in options ? { hasRoutine: options.hasRoutine === true } : {}),
+    };
+}
+export function toStoredAgentRecord(agent, options) {
+    const createdAt = options?.createdAt ?? agent.createdAt.toISOString();
+    const config = buildSerializableConfig(agent.config);
+    const persistence = sanitizePersistenceHandle(agent.persistence);
+    const runtimeInfo = sanitizeRuntimeInfo(agent.runtimeInfo);
+    return {
+        id: agent.id,
+        provider: agent.provider,
+        cwd: agent.cwd,
+        workspaceId: agent.workspaceId,
+        createdAt,
+        updatedAt: agent.updatedAt.toISOString(),
+        lastActivityAt: agent.updatedAt.toISOString(),
+        lastUserMessageAt: agent.lastUserMessageAt ? agent.lastUserMessageAt.toISOString() : null,
+        title: options?.title ?? null,
+        labels: agent.labels,
+        digest: agent.digest,
+        lastStatus: agent.lifecycle,
+        lastModeId: agent.currentModeId ?? config?.modeId ?? null,
+        config: config ?? null,
+        runtimeInfo,
+        features: normalizeFeatures(agent.features),
+        persistence,
+        lastError: agent.lastError ?? undefined,
+        requiresAttention: agent.attention.requiresAttention,
+        attentionReason: agent.attention.requiresAttention ? agent.attention.attentionReason : null,
+        attentionTimestamp: agent.attention.requiresAttention
+            ? agent.attention.attentionTimestamp.toISOString()
+            : null,
+        internal: options?.internal,
+    };
+}
+export function toAgentPayload(agent, options) {
+    const runtimeInfo = sanitizeRuntimeInfo(agent.runtimeInfo);
+    const thinkingOptionId = agent.config.thinkingOptionId ?? null;
+    const effectiveThinkingOptionId = resolveEffectiveThinkingOptionId({
+        runtimeInfo,
+        configuredThinkingOptionId: thinkingOptionId,
+    });
+    const payload = {
+        id: agent.id,
+        provider: agent.provider,
+        cwd: agent.cwd,
+        ...(agent.workspaceId ? { workspaceId: agent.workspaceId } : {}),
+        model: agent.config.model ?? null,
+        thinkingOptionId,
+        effectiveThinkingOptionId,
+        ...(runtimeInfo ? { runtimeInfo } : {}),
+        createdAt: agent.createdAt.toISOString(),
+        updatedAt: agent.updatedAt.toISOString(),
+        lastUserMessageAt: agent.lastUserMessageAt ? agent.lastUserMessageAt.toISOString() : null,
+        status: agent.lifecycle,
+        capabilities: cloneCapabilities(agent.capabilities),
+        currentModeId: agent.currentModeId,
+        availableModes: cloneAvailableModes(agent.availableModes),
+        features: normalizeFeatures(agent.features),
+        pendingPermissions: sanitizePendingPermissions(agent.pendingPermissions),
+        persistence: redactPersistenceForWire(sanitizePersistenceHandle(agent.persistence)),
+        title: options?.title ?? null,
+        labels: agent.labels,
+        ...(agent.digest ? { digest: agent.digest } : {}),
+        ...buildAgentDurabilityFields(agent.config, options),
+    };
+    const usage = sanitizeUsage(agent.lastUsage);
+    if (usage !== undefined) {
+        payload.lastUsage = usage;
+    }
+    if (agent.lastError !== undefined) {
+        payload.lastError = agent.lastError;
+    }
+    // Handle attention state
+    payload.requiresAttention = agent.attention.requiresAttention;
+    if (agent.attention.requiresAttention) {
+        payload.attentionReason = agent.attention.attentionReason;
+        payload.attentionTimestamp = agent.attention.attentionTimestamp.toISOString();
+    }
+    else {
+        payload.attentionReason = null;
+        payload.attentionTimestamp = null;
+    }
+    // Live background-shell count, read straight from the provider session so it
+    // rides every snapshot (no separate emit needed). Providers that don't model
+    // background shells omit the getter → treated as 0 and left off the payload.
+    const session = "session" in agent ? agent.session : undefined;
+    const activeBackgroundTaskCount = session?.getActiveBackgroundTaskCount?.() ?? 0;
+    if (activeBackgroundTaskCount > 0) {
+        payload.activeBackgroundTaskCount = activeBackgroundTaskCount;
+    }
+    return payload;
+}
+function buildStoredRuntimeInfo(record) {
+    if (!record.runtimeInfo)
+        return undefined;
+    const ri = record.runtimeInfo;
+    const runtimeInfo = {
+        provider: ri.provider,
+        sessionId: ri.sessionId,
+    };
+    if (Object.prototype.hasOwnProperty.call(ri, "model")) {
+        runtimeInfo.model = ri.model ?? null;
+    }
+    if (Object.prototype.hasOwnProperty.call(ri, "thinkingOptionId")) {
+        runtimeInfo.thinkingOptionId = ri.thinkingOptionId ?? null;
+    }
+    if (Object.prototype.hasOwnProperty.call(ri, "modeId")) {
+        runtimeInfo.modeId = ri.modeId ?? null;
+    }
+    if (ri.extra) {
+        runtimeInfo.extra = ri.extra;
+    }
+    return runtimeInfo;
+}
+/**
+ * Wire-facing persistence handle, with `metadata` stripped.
+ *
+ * `persistence.metadata` is provider-owned resume state and it carries
+ * credentials: on this fleet 5475 of 6373 stored records hold an
+ * `Authorization: Bearer <token>` inside it (the MCP server block the provider
+ * was launched with), and 8 duplicate `config.systemPrompt` there too. Nothing
+ * downstream of the wire reads it: the only client-side use of the handle is
+ * `persistence.sessionId`, so dropping the field costs the app nothing.
+ *
+ * The strip happens HERE and not inside `toAgentPersistenceHandle`, because
+ * that converter has two other callers which are resume paths, not wire paths
+ * (`agent-loading.ts` and the interactive resume in `session.ts`), and both
+ * hand the handle straight to `resumeAgentFromPersistence`, which needs the
+ * metadata intact. Redacting in the shared converter would break resume.
+ */
+function buildStoredPersistenceHandle(record, validProviders) {
+    if (!isStoredAgentProviderAvailable(record, validProviders)) {
+        return null;
+    }
+    const handle = toAgentPersistenceHandle(validProviders, record.persistence);
+    if (!handle) {
+        return null;
+    }
+    const { metadata: _redacted, ...wireSafe } = handle;
+    return wireSafe;
+}
+export function buildStoredAgentPayload(record, validProviders, options) {
+    const defaultCapabilities = {
+        supportsStreaming: false,
+        supportsSessionPersistence: true,
+        supportsDynamicModes: false,
+        supportsMcpServers: false,
+        supportsReasoningStream: false,
+        supportsToolInvocations: true,
+        supportsRewindConversation: false,
+        supportsRewindFiles: false,
+        supportsRewindBoth: false,
+    };
+    const createdAt = new Date(record.createdAt);
+    const updatedAt = new Date(resolveStoredAgentPayloadUpdatedAt(record));
+    const lastUserMessageAt = record.lastUserMessageAt ? new Date(record.lastUserMessageAt) : null;
+    const runtimeInfo = buildStoredRuntimeInfo(record);
+    const providerAvailable = isStoredAgentProviderAvailable(record, validProviders);
+    const persistence = buildStoredPersistenceHandle(record, validProviders);
+    return {
+        id: record.id,
+        provider: record.provider,
+        cwd: record.cwd,
+        ...(record.workspaceId ? { workspaceId: record.workspaceId } : {}),
+        model: record.config?.model ?? null,
+        thinkingOptionId: record.config?.thinkingOptionId ?? null,
+        effectiveThinkingOptionId: resolveEffectiveThinkingOptionId({
+            runtimeInfo,
+            configuredThinkingOptionId: record.config?.thinkingOptionId ?? null,
+        }),
+        ...(runtimeInfo ? { runtimeInfo } : {}),
+        createdAt: createdAt.toISOString(),
+        updatedAt: updatedAt.toISOString(),
+        lastUserMessageAt: lastUserMessageAt ? lastUserMessageAt.toISOString() : null,
+        status: record.lastStatus,
+        capabilities: defaultCapabilities,
+        currentModeId: record.lastModeId ?? null,
+        availableModes: [],
+        pendingPermissions: [],
+        persistence,
+        title: record.title ?? null,
+        requiresAttention: record.requiresAttention ?? false,
+        attentionReason: record.attentionReason ?? null,
+        attentionTimestamp: record.attentionTimestamp ?? null,
+        archivedAt: record.archivedAt ?? null,
+        labels: normalizeLabels(record.labels),
+        ...(record.digest ? { digest: record.digest } : {}),
+        ...(providerAvailable ? {} : { providerUnavailable: true }),
+        ...buildAgentDurabilityFields(record.config, options),
+    };
+}
+export function toAgentListItemPayload(agent) {
+    return {
+        id: agent.id,
+        shortId: agent.id.slice(0, 7),
+        title: agent.title,
+        provider: agent.provider,
+        model: agent.runtimeInfo?.model ?? agent.model,
+        thinkingOptionId: agent.thinkingOptionId,
+        effectiveThinkingOptionId: agent.effectiveThinkingOptionId,
+        status: agent.status,
+        cwd: agent.cwd,
+        createdAt: agent.createdAt,
+        updatedAt: agent.updatedAt,
+        lastUserMessageAt: agent.lastUserMessageAt,
+        archivedAt: agent.archivedAt ?? null,
+        requiresAttention: agent.requiresAttention ?? false,
+        attentionReason: agent.attentionReason ?? null,
+        attentionTimestamp: agent.attentionTimestamp ?? null,
+        labels: agent.labels,
+        ...(agent.digest ? { digest: agent.digest } : {}),
+        ...(agent.activeBackgroundTaskCount
+            ? { activeBackgroundTaskCount: agent.activeBackgroundTaskCount }
+            : {}),
+        ...(agent.pendingPermissions.length > 0
+            ? { pendingPermissionCount: agent.pendingPermissions.length }
+            : {}),
+        ...(agent.providerUnavailable ? { providerUnavailable: true } : {}),
+        // The list item names the CONFIGURED mode `modeId`; the snapshot's
+        // `currentModeId` is the live one. Same value at rest, different questions.
+        modeId: agent.currentModeId ?? null,
+        ...(agent.hasSystemPrompt !== undefined ? { hasSystemPrompt: agent.hasSystemPrompt } : {}),
+        ...(agent.goal !== undefined ? { goal: agent.goal } : {}),
+        ...(agent.jobToBeDone !== undefined ? { jobToBeDone: agent.jobToBeDone } : {}),
+        ...(agent.allowedTools !== undefined ? { allowedTools: agent.allowedTools } : {}),
+        ...(agent.mcpServerNames ? { mcpServerNames: agent.mcpServerNames } : {}),
+        ...(agent.nextFireAt !== undefined ? { nextFireAt: agent.nextFireAt } : {}),
+        ...(agent.hasRoutine !== undefined ? { hasRoutine: agent.hasRoutine } : {}),
+    };
+}
+export function toRecentProviderSessionDescriptorPayload(session, options) {
+    return {
+        providerId: session.provider,
+        providerLabel: options.providerLabel,
+        providerHandleId: session.providerHandleId,
+        cwd: session.cwd,
+        title: session.title,
+        firstPromptPreview: session.firstPromptPreview,
+        lastPromptPreview: session.lastPromptPreview,
+        lastActivityAt: session.lastActivityAt.toISOString(),
+    };
+}
+export function resolveStoredAgentPayloadUpdatedAt(record) {
+    const timestamps = [record.updatedAt, record.lastActivityAt]
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .map((value) => ({
+        raw: value,
+        parsed: Date.parse(value),
+    }))
+        .filter((value) => !Number.isNaN(value.parsed));
+    if (timestamps.length === 0) {
+        return record.updatedAt;
+    }
+    timestamps.sort((a, b) => b.parsed - a.parsed);
+    return timestamps[0].raw;
+}
+function buildSerializableConfig(config) {
+    const serializable = {};
+    if (config.modeId) {
+        serializable.modeId = config.modeId;
+    }
+    if (config.model) {
+        serializable.model = config.model;
+    }
+    if (config.thinkingOptionId) {
+        serializable.thinkingOptionId = config.thinkingOptionId;
+    }
+    if (Object.prototype.hasOwnProperty.call(config, "featureValues")) {
+        const featureValues = sanitizeMetadata(config.featureValues);
+        if (featureValues !== undefined) {
+            serializable.featureValues = featureValues;
+        }
+    }
+    const extra = sanitizeMetadata(config.extra);
+    if (extra !== undefined) {
+        serializable.extra = extra;
+    }
+    if (config.systemPrompt) {
+        serializable.systemPrompt = config.systemPrompt;
+    }
+    if (config.outputLanguage) {
+        serializable.outputLanguage = config.outputLanguage;
+    }
+    if (config.goal) {
+        serializable.goal = config.goal;
+    }
+    if (config.jobToBeDone) {
+        serializable.jobToBeDone = config.jobToBeDone;
+    }
+    if (config.mcpServers) {
+        serializable.mcpServers = config.mcpServers;
+    }
+    if (config.allowedTools?.length) {
+        serializable.allowedTools = [...config.allowedTools];
+    }
+    return Object.keys(serializable).length ? serializable : null;
+}
+function sanitizePendingPermissions(pending) {
+    return Array.from(pending.values()).map((request) => Object.assign({}, request, {
+        input: sanitizeMetadata(request.input),
+        suggestions: sanitizeMetadataArray(request.suggestions),
+        actions: request.actions?.map((action) => Object.assign({}, action)),
+        metadata: sanitizeMetadata(request.metadata),
+    }));
+}
+/**
+ * Drop `persistence.metadata` before a handle crosses the wire.
+ *
+ * The metadata is provider-owned resume state and it carries credentials: on
+ * this fleet 5475 of 6373 stored records hold an `Authorization: Bearer <token>`
+ * inside it (the MCP server block the provider was launched with). Nothing
+ * downstream of the wire reads it, the only client-side use of the handle is
+ * `persistence.sessionId`, so dropping it costs the app nothing.
+ *
+ * This is deliberately NOT folded into `sanitizePersistenceHandle`, and not into
+ * `toAgentPersistenceHandle` either. Both are shared with paths that MUST keep
+ * the metadata: `toStoredAgentRecord` writes it to disk, and `agent-loading.ts`
+ * plus the interactive resume in `session.ts` hand it to
+ * `resumeAgentFromPersistence`. Redacting in either shared helper stops resume
+ * working, which is a worse failure than the leak it fixes.
+ */
+function redactPersistenceForWire(handle) {
+    if (!handle) {
+        return null;
+    }
+    const { metadata: _redacted, ...wireSafe } = handle;
+    return wireSafe;
+}
+function sanitizePersistenceHandle(handle) {
+    if (!handle) {
+        return null;
+    }
+    const sanitized = {
+        provider: handle.provider,
+        sessionId: handle.sessionId,
+    };
+    if (handle.nativeHandle !== undefined) {
+        sanitized.nativeHandle = handle.nativeHandle;
+    }
+    const metadata = sanitizeMetadata(handle.metadata);
+    if (metadata !== undefined) {
+        sanitized.metadata = metadata;
+    }
+    return sanitized;
+}
+function cloneCapabilities(capabilities) {
+    return { ...capabilities };
+}
+function cloneAvailableModes(modes) {
+    return modes.map((mode) => ({ ...mode }));
+}
+function normalizeFeatures(features) {
+    return Array.isArray(features) ? features.map((feature) => ({ ...feature })) : [];
+}
+function sanitizeOptionalJson(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    if (Array.isArray(value)) {
+        const sanitized = value
+            .map((item) => sanitizeOptionalJson(item))
+            .filter((item) => item !== undefined);
+        return sanitized;
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === "object") {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            const sanitized = sanitizeOptionalJson(val);
+            if (sanitized !== undefined) {
+                result[key] = sanitized;
+            }
+        }
+        return Object.keys(result).length ? result : undefined;
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return value;
+    }
+    return undefined;
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sanitizeMetadata(value) {
+    const sanitized = sanitizeOptionalJson(value);
+    if (!sanitized || !isJsonObject(sanitized)) {
+        return undefined;
+    }
+    return sanitized;
+}
+function sanitizeMetadataArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const sanitized = value
+        .map((entry) => sanitizeMetadata(entry))
+        .filter((entry) => entry !== undefined);
+    return sanitized.length > 0 ? sanitized : undefined;
+}
+function assignFiniteNumber(source, target, field) {
+    const raw = source[field];
+    if (typeof raw === "number" && Number.isFinite(raw)) {
+        target[field] = raw;
+        return true;
+    }
+    return raw === undefined || raw === null;
+}
+function sanitizeUsage(value) {
+    const sanitized = sanitizeOptionalJson(value);
+    if (!sanitized || !isJsonObject(sanitized)) {
+        return undefined;
+    }
+    const result = {};
+    const fields = [
+        "inputTokens",
+        "cachedInputTokens",
+        "outputTokens",
+        "totalCostUsd",
+        "contextWindowMaxTokens",
+        "contextWindowUsedTokens",
+    ];
+    for (const field of fields) {
+        if (!assignFiniteNumber(sanitized, result, field)) {
+            return undefined;
+        }
+    }
+    return Object.keys(result).length ? result : undefined;
+}
+function sanitizeRuntimeInfo(runtimeInfo) {
+    if (!runtimeInfo) {
+        return undefined;
+    }
+    const sanitized = {
+        provider: runtimeInfo.provider,
+        sessionId: runtimeInfo.sessionId,
+    };
+    if (runtimeInfo.model !== undefined) {
+        sanitized.model = runtimeInfo.model;
+    }
+    if (runtimeInfo.thinkingOptionId !== undefined) {
+        sanitized.thinkingOptionId = runtimeInfo.thinkingOptionId;
+    }
+    if (runtimeInfo.modeId !== undefined) {
+        sanitized.modeId = runtimeInfo.modeId;
+    }
+    const extra = sanitizeMetadata(runtimeInfo.extra);
+    if (extra !== undefined) {
+        sanitized.extra = extra;
+    }
+    return sanitized;
+}
+//# sourceMappingURL=agent-projections.js.map

package/dist/server/server/agent/agent-prompt.d.ts

@@ -0,0 +1,65 @@
+import type { Logger } from "pino";
+import type { AgentPromptInput, AgentRunOptions } from "./agent-sdk-types.js";
+import type { AgentManager, ManagedAgent } from "./agent-manager.js";
+import type { AgentStorage } from "./agent-storage.js";
+export type AgentRunController = Pick<AgentManager, "getAgent" | "tryRunOutOfBand" | "hasInFlightRun" | "replaceAgentRun" | "streamAgent">;
+export interface StartAgentRunOptions {
+    replaceRunning?: boolean;
+    runOptions?: AgentRunOptions;
+}
+export declare function startAgentRun(agentManager: AgentRunController, agentId: string, prompt: AgentPromptInput, logger: Logger, options?: StartAgentRunOptions): {
+    outOfBand: boolean;
+};
+/**
+ * Clear the archived flag from a stored agent record.
+ * Shared across Session (app/WS), MCP, and CLI so every surface that acts on
+ * an archived agent unarchives it the same way.
+ */
+export declare function unarchiveAgentState(_agentStorage: AgentStorage, agentManager: AgentManager, agentId: string): Promise<boolean>;
+/**
+ * Wrap a body in <paseo-system>…</paseo-system> so the receiving agent
+ * recognizes the prompt as system-injected context — not a user turn.
+ * Used by chat mentions, schedule fires, and notify-on-finish.
+ */
+export declare function formatSystemNotificationPrompt(reason: string): string;
+export declare function isSystemInjectedEnvelope(text: string): boolean;
+export interface SendPromptToAgentParams {
+    agentManager: AgentManager;
+    agentStorage: AgentStorage;
+    agentId: string;
+    /** Prompt to dispatch to the provider (may include image blocks or wrapped text). */
+    prompt: AgentPromptInput;
+    messageId?: string;
+    runOptions?: AgentRunOptions;
+    /** Optional mode to set on the agent before the run starts. */
+    sessionMode?: string;
+    /**
+     * Default true. When false, archived agents are skipped instead of being
+     * unarchived. Use false for system-injected prompts (chat mentions,
+     * schedule fires, notify-on-finish).
+     */
+    unarchive?: boolean;
+    logger: Logger;
+}
+export interface StartCreatedAgentInitialPromptParams {
+    agentManager: AgentManager;
+    agentId: string;
+    snapshot?: ManagedAgent;
+    prompt: AgentPromptInput | null;
+    runOptions?: AgentRunOptions;
+    logger: Logger;
+}
+export declare function waitForAgentRunStartWithTimeout(agentManager: AgentManager, agentId: string): Promise<void>;
+export declare function sendPromptToAgent(params: SendPromptToAgentParams): Promise<{
+    outOfBand: boolean;
+}>;
+export declare function startCreatedAgentInitialPrompt(params: StartCreatedAgentInitialPromptParams): Promise<ManagedAgent>;
+export interface SetupFinishNotificationParams {
+    agentManager: AgentManager;
+    agentStorage: AgentStorage;
+    childAgentId: string;
+    callerAgentId: string;
+    logger: Logger;
+}
+export declare function setupFinishNotification(params: SetupFinishNotificationParams): void;
+//# sourceMappingURL=agent-prompt.d.ts.map