@camerontaylor/paseo-server 0.8.0-fork.1

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

@@ -0,0 +1,359 @@
+import { ensureAgentLoaded } from "./agent-loading.js";
+import { isStaleProviderSessionError } from "./stale-provider-session-error.js";
+import { getParentAgentIdFromLabels } from "@camerontaylor/paseo-protocol/agent-labels";
+async function steerOrReplaceActiveRun(agentManager, agentId, prompt, options) {
+    if (options?.activeTurnBehavior !== "steer") {
+        return null;
+    }
+    const steerOptions = options.clearPendingPermissions
+        ? { ...options.runOptions, clearPendingPermissions: true }
+        : options.runOptions;
+    const result = await agentManager.steerOrReplaceActiveTurn(agentId, prompt, steerOptions);
+    if (result.status === "steered") {
+        return { disposition: "steered" };
+    }
+    if (result.status === "replaced") {
+        return { disposition: "turn_started", iterator: result.iterator };
+    }
+    return null;
+}
+async function startOrReplaceRun(agentManager, agentId, prompt, options) {
+    const replaced = Boolean(options?.replaceRunning && agentManager.hasInFlightRun(agentId));
+    const iterator = replaced
+        ? await agentManager.replaceAgentRun(agentId, prompt, options?.runOptions)
+        : agentManager.streamAgent(agentId, prompt, options?.runOptions);
+    return { iterator, replaced };
+}
+async function drainAgentRunIterator(iterator) {
+    for await (const _ of iterator) {
+        // Events are broadcast via AgentManager subscribers.
+    }
+}
+export async function startAgentRun(agentManager, agentId, prompt, logger, options) {
+    const snapshot = agentManager.getAgent(agentId);
+    logger.trace({
+        agentId,
+        provider: snapshot?.provider,
+        providerSessionId: snapshot?.persistence?.sessionId ?? undefined,
+        turnId: snapshot?.activeForegroundTurnId ?? undefined,
+        promptType: typeof prompt === "string" ? "string" : "structured",
+        hasRunOptions: Boolean(options?.runOptions),
+        replaceRunning: Boolean(options?.replaceRunning),
+    }, "agent.session.start_stream.request");
+    // Out-of-band commands (e.g. /goal pause) must run WITHOUT canceling an
+    // in-flight turn — replaceAgentRun would interrupt the running turn. The
+    // intercept lives at this layer so it covers every prompt entrypoint.
+    if (agentManager.tryRunOutOfBand(agentId, prompt, options?.runOptions)) {
+        return { disposition: "out_of_band" };
+    }
+    try {
+        return await startAgentRunInner(agentManager, agentId, prompt, logger, options);
+    }
+    catch (error) {
+        if (!isStaleProviderSessionError(error))
+            throw error;
+        logger.info({ agentId, err: error }, "Provider session went stale; reopening from persistence");
+        // The live session belongs to a retired plugin runtime. Reload swaps in a
+        // fresh session on the current runtime while preserving history and labels.
+        await agentManager.reloadAgentSession(agentId);
+        return await startAgentRunInner(agentManager, agentId, prompt, logger, options);
+    }
+}
+async function startAgentRunInner(agentManager, agentId, prompt, logger, options) {
+    const snapshot = agentManager.getAgent(agentId);
+    const steered = await steerOrReplaceActiveRun(agentManager, agentId, prompt, options);
+    if (steered?.disposition === "steered") {
+        return steered;
+    }
+    const { iterator, replaced } = steered
+        ? { iterator: steered.iterator, replaced: true }
+        : await startOrReplaceRun(agentManager, agentId, prompt, options);
+    logger.trace({
+        agentId,
+        provider: snapshot?.provider,
+        providerSessionId: snapshot?.persistence?.sessionId ?? undefined,
+        shouldReplace: replaced,
+    }, "agent.session.start_stream.iterator_returned");
+    void (async () => {
+        try {
+            try {
+                await drainAgentRunIterator(iterator);
+            }
+            catch (error) {
+                if (!isStaleProviderSessionError(error))
+                    throw error;
+                logger.info({ agentId, err: error }, "Provider session went stale; reopening from persistence");
+                await agentManager.reloadAgentSession(agentId);
+                const retry = await startOrReplaceRun(agentManager, agentId, prompt, options);
+                await drainAgentRunIterator(retry.iterator);
+            }
+            logger.trace({
+                agentId,
+                provider: snapshot?.provider,
+                providerSessionId: snapshot?.persistence?.sessionId ?? undefined,
+            }, "agent.session.iterator.drained");
+        }
+        catch (error) {
+            logger.trace({
+                agentId,
+                provider: snapshot?.provider,
+                providerSessionId: snapshot?.persistence?.sessionId ?? undefined,
+                err: error,
+            }, "agent.session.iterator.error");
+            logger.error({ err: error, agentId }, "Agent stream failed");
+        }
+    })();
+    return { disposition: "turn_started" };
+}
+/**
+ * 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 async function unarchiveAgentState(_agentStorage, agentManager, agentId, updates) {
+    const unarchived = await agentManager.unarchiveSnapshot(agentId, updates);
+    if (!unarchived)
+        return false;
+    agentManager.notifyAgentState(agentId);
+    return true;
+}
+/**
+ * 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 function formatSystemNotificationPrompt(reason) {
+    return `<paseo-system>\n${reason}\n</paseo-system>`;
+}
+const SYSTEM_ENVELOPE_PATTERN = /^<paseo-system>\n[\s\S]*\n<\/paseo-system>$/;
+export function isSystemInjectedEnvelope(text) {
+    return SYSTEM_ENVELOPE_PATTERN.test(text);
+}
+/**
+ * Outer bound on a run reaching "started" after dispatch.
+ *
+ * This wraps provider startup, so it MUST stay larger than the slowest provider's own
+ * startup budget — otherwise it aborts a start the provider was still allowed to be
+ * working on, and the provider's budget can never apply. OpenCode is the slowest today:
+ * up to 30s for the server to boot (OPENCODE_SERVER_STARTUP_TIMEOUT_MS) and then a
+ * session.create on the same budget, so this is deliberately set well above 30s.
+ *
+ * Not derived from the provider constant on purpose: this module is provider-agnostic
+ * and must not depend on a specific provider's internals.
+ */
+const AGENT_RUN_START_TIMEOUT_MS = 60000;
+export async function waitForAgentRunStartWithTimeout(agentManager, agentId) {
+    const provider = agentManager.getAgent(agentId)?.provider ?? "provider";
+    const startAbort = new AbortController();
+    const startTimeout = setTimeout(() => startAbort.abort(new Error(`${provider} run did not start within ${AGENT_RUN_START_TIMEOUT_MS / 1000} seconds (phase: run start)`)), AGENT_RUN_START_TIMEOUT_MS);
+    try {
+        await agentManager.waitForAgentRunStart(agentId, { signal: startAbort.signal });
+    }
+    finally {
+        clearTimeout(startTimeout);
+    }
+}
+/**
+ * Full send-prompt orchestration: (optional unarchive) → load → (optional
+ * mode change) → start run.
+ *
+ * Every surface that sends a prompt to an agent (Session/WS, MCP, CLI-through-MCP,
+ * chat mentions, notify-on-finish) MUST go through this so behavior can never
+ * drift between them.
+ *
+ * When `unarchive` is false and the agent is archived, the call is a silent
+ * no-op (returns the normal turn-start disposition) — the agent is not run.
+ */
+export async function sendPromptToAgent(params) {
+    const unarchive = params.unarchive ?? true;
+    const record = await params.agentStorage.get(params.agentId);
+    if (record?.archivedAt) {
+        if (!unarchive) {
+            return { disposition: "turn_started" };
+        }
+        await unarchiveAgentState(params.agentStorage, params.agentManager, params.agentId);
+    }
+    await ensureAgentLoaded(params.agentId, {
+        agentManager: params.agentManager,
+        agentStorage: params.agentStorage,
+        logger: params.logger,
+    });
+    if (params.sessionMode) {
+        await params.agentManager.setAgentMode(params.agentId, params.sessionMode);
+    }
+    const runOptions = params.messageId
+        ? { ...params.runOptions, clientMessageId: params.messageId }
+        : params.runOptions;
+    return await startAgentRun(params.agentManager, params.agentId, params.prompt, params.logger, {
+        replaceRunning: true,
+        activeTurnBehavior: params.activeTurnBehavior,
+        clearPendingPermissions: params.clearPendingPermissions,
+        runOptions,
+    });
+}
+export async function startCreatedAgentInitialPrompt(params) {
+    const currentSnapshot = params.agentManager.getAgent(params.agentId) ?? params.snapshot ?? null;
+    if (!currentSnapshot) {
+        throw new Error(`Agent ${params.agentId} not found`);
+    }
+    if (params.prompt === null) {
+        return currentSnapshot;
+    }
+    const dispatchResult = await startAgentRun(params.agentManager, params.agentId, params.prompt, params.logger, {
+        runOptions: params.runOptions,
+    });
+    if (dispatchResult.disposition === "turn_started") {
+        await waitForAgentRunStartWithTimeout(params.agentManager, params.agentId);
+    }
+    const refreshedSnapshot = params.agentManager.getAgent(params.agentId) ?? params.snapshot ?? null;
+    if (!refreshedSnapshot) {
+        throw new Error(`Agent ${params.agentId} not found`);
+    }
+    return refreshedSnapshot;
+}
+const FINISH_NOTIFICATION_MESSAGE_LIMIT = 4000;
+function formatFinishNotificationBody(params) {
+    const statusLine = `Agent ${params.childAgentId} (${params.title}) ${params.reason}.`;
+    const sections = [statusLine];
+    if (params.reason === "needs permission" && params.permissionRequest) {
+        sections.push("Respond with `respond_to_permission` using the `agentId` and `requestId` below.", `<permission-request>\n${JSON.stringify({
+            agentId: params.childAgentId,
+            requestId: params.permissionRequest.id,
+            request: params.permissionRequest,
+        }, null, 2)}\n</permission-request>`);
+    }
+    let lastAssistantMessage = params.lastAssistantMessage?.trim();
+    if (lastAssistantMessage) {
+        if (lastAssistantMessage.length > FINISH_NOTIFICATION_MESSAGE_LIMIT) {
+            const omitted = lastAssistantMessage.length - FINISH_NOTIFICATION_MESSAGE_LIMIT;
+            lastAssistantMessage = `${lastAssistantMessage.slice(0, FINISH_NOTIFICATION_MESSAGE_LIMIT)}\n[truncated ${omitted} chars; use get_agent_activity for the full response]`;
+        }
+        sections.push(`<agent-response>\n${lastAssistantMessage}\n</agent-response>`);
+    }
+    return sections.join("\n\n");
+}
+export function setupFinishNotification(params) {
+    const { agentManager, agentStorage, childAgentId, callerAgentId, requireParentOwnership = false, logger, } = params;
+    let hasSeenRunning = false;
+    let stopped = false;
+    const notifiedPermissionRequestIds = new Set();
+    let unsubscribe = null;
+    let notificationQueue = Promise.resolve();
+    function stop() {
+        if (stopped)
+            return;
+        stopped = true;
+        unsubscribe?.();
+    }
+    async function notify(reason, permissionRequest) {
+        const callerRecord = await agentStorage.get(callerAgentId);
+        if (callerRecord?.archivedAt) {
+            return;
+        }
+        const record = await agentStorage.get(childAgentId);
+        if (requireParentOwnership && getParentAgentIdFromLabels(record?.labels) !== callerAgentId) {
+            return;
+        }
+        const title = record?.title ?? childAgentId;
+        const lastAssistantMessage = await agentManager.getLastAssistantMessage(childAgentId);
+        const body = formatFinishNotificationBody({
+            childAgentId,
+            title,
+            reason,
+            lastAssistantMessage,
+            permissionRequest,
+        });
+        await sendPromptToAgent({
+            agentManager,
+            agentStorage,
+            agentId: callerAgentId,
+            prompt: formatSystemNotificationPrompt(body),
+            activeTurnBehavior: "steer",
+            unarchive: false,
+            logger,
+        });
+    }
+    function notifySafely(reason, options = {}) {
+        if (stopped)
+            return;
+        if (options.terminal ?? true)
+            stop();
+        notificationQueue = notificationQueue
+            .then(() => notify(reason, options.permissionRequest))
+            .catch((error) => {
+            logger.error({ err: error, childAgentId, callerAgentId, reason }, "Failed to notify caller agent");
+        });
+    }
+    unsubscribe = agentManager.subscribe((event) => {
+        if (stopped) {
+            return;
+        }
+        if (event.type === "agent_state") {
+            for (const requestId of notifiedPermissionRequestIds) {
+                if (!event.agent.pendingPermissions.has(requestId)) {
+                    notifiedPermissionRequestIds.delete(requestId);
+                }
+            }
+            if (event.agent.lifecycle === "running") {
+                if (event.agent.pendingPermissions.size === 0) {
+                    hasSeenRunning = true;
+                }
+                return;
+            }
+            if (event.agent.lifecycle === "error") {
+                notifySafely("errored");
+                return;
+            }
+            if (event.agent.lifecycle === "idle" && hasSeenRunning) {
+                notifySafely("finished");
+                return;
+            }
+            if (event.agent.lifecycle === "closed") {
+                notifySafely("was closed");
+                return;
+            }
+            return;
+        }
+        if (event.type === "timeline_replacement") {
+            return;
+        }
+        if (event.event.type === "permission_requested") {
+            // A permission pause is an intermediate checkpoint. Forget the run
+            // observed before it so an idle state during follow-up startup cannot
+            // masquerade as the final completion.
+            hasSeenRunning = false;
+            if (!notifiedPermissionRequestIds.has(event.event.request.id)) {
+                notifiedPermissionRequestIds.add(event.event.request.id);
+                notifySafely("needs permission", {
+                    terminal: false,
+                    permissionRequest: event.event.request,
+                });
+            }
+            return;
+        }
+        if (event.event.type === "permission_resolved") {
+            notifiedPermissionRequestIds.delete(event.event.requestId);
+            const childAgent = agentManager.getAgent(childAgentId);
+            if (childAgent?.pendingPermissions.size === 0) {
+                hasSeenRunning = childAgent.lifecycle === "running";
+            }
+        }
+    }, { agentId: childAgentId, replayState: false });
+    // Check if the child is already running (catches the case where
+    // the lifecycle flipped before our subscribe call was processed).
+    // Do NOT treat an immediate "idle" as "finished" — the agent may
+    // not have started yet (streamAgent sets a pending run before
+    // transitioning to "running").
+    const childSnapshot = agentManager.getAgent(childAgentId);
+    if (!childSnapshot || childSnapshot.lifecycle === "closed") {
+        stop();
+        return;
+    }
+    if (childSnapshot.lifecycle === "running") {
+        hasSeenRunning = true;
+    }
+    else if (childSnapshot.lifecycle === "error") {
+        notifySafely("errored");
+    }
+}
+//# sourceMappingURL=agent-prompt.js.map

package/dist/server/server/agent/agent-response-loop.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import type { AgentProvider, AgentSessionConfig } from "./agent-sdk-types.js";
+import type { AgentManager } from "./agent-manager.js";
+export interface StructuredGenerationLogger {
+    info: (obj: object, msg?: string) => void;
+    warn: (obj: object, msg?: string) => void;
+}
+export type JsonSchema = Record<string, unknown>;
+export type AgentCaller = (prompt: string) => Promise<string>;
+export declare class StructuredAgentResponseError extends Error {
+    readonly lastResponse: string;
+    readonly validationErrors: string[];
+    constructor(message: string, options: {
+        lastResponse: string;
+        validationErrors: string[];
+    });
+}
+export interface StructuredGenerationProvider {
+    provider: AgentProvider;
+    model?: string;
+    thinkingOptionId?: string;
+}
+export interface StructuredGenerationAttempt {
+    provider: AgentProvider;
+    model: string | null;
+    available: boolean;
+    error: string | null;
+}
+export declare class StructuredAgentFallbackError extends Error {
+    readonly attempts: StructuredGenerationAttempt[];
+    constructor(attempts: StructuredGenerationAttempt[]);
+}
+export interface StructuredAgentResponseOptions<T> {
+    caller: AgentCaller;
+    prompt: string;
+    schema: z.ZodType<T> | JsonSchema;
+    maxRetries?: number;
+    schemaName?: string;
+}
+export interface StructuredAgentGenerationOptions<T> {
+    manager: AgentManager;
+    agentConfig: AgentSessionConfig;
+    agentId?: string;
+    persistSession?: boolean;
+    prompt: string;
+    schema: z.ZodType<T> | JsonSchema;
+    maxRetries?: number;
+    schemaName?: string;
+}
+export interface StructuredAgentGenerationWithFallbackOptions<T> {
+    manager: AgentManager;
+    cwd: string;
+    prompt: string;
+    schema: z.ZodType<T> | JsonSchema;
+    providers: readonly StructuredGenerationProvider[];
+    agentConfigOverrides?: Omit<AgentSessionConfig, "provider" | "cwd" | "model" | "thinkingOptionId">;
+    persistSession?: boolean;
+    maxRetries?: number;
+    schemaName?: string;
+    logger?: StructuredGenerationLogger;
+    runner?: <TResult>(options: StructuredAgentGenerationOptions<TResult>) => Promise<TResult>;
+}
+export { DEFAULT_STRUCTURED_GENERATION_PROVIDERS } from "./structured-generation-providers.js";
+export declare function buildStructuredAgentResponsePrompt(options: {
+    prompt: string;
+    schema: z.ZodType | JsonSchema;
+    schemaName?: string;
+}): string;
+export declare function getStructuredAgentResponse<T>(options: StructuredAgentResponseOptions<T>): Promise<T>;
+export declare function generateStructuredAgentResponse<T>(options: StructuredAgentGenerationOptions<T>): Promise<T>;
+export declare function generateStructuredAgentResponseWithFallback<T>(options: StructuredAgentGenerationWithFallbackOptions<T>): Promise<T>;
+//# sourceMappingURL=agent-response-loop.d.ts.map