@hyperdrive.bot/paseo-server 0.2.6

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

@@ -0,0 +1,230 @@
+import { ensureAgentLoaded } from "./agent-loading.js";
+export 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)) {
+        return { outOfBand: true };
+    }
+    const shouldReplace = Boolean(options?.replaceRunning && agentManager.hasInFlightRun(agentId));
+    const runOptions = options?.runOptions;
+    const iterator = shouldReplace
+        ? agentManager.replaceAgentRun(agentId, prompt, runOptions)
+        : agentManager.streamAgent(agentId, prompt, runOptions);
+    logger.trace({
+        agentId,
+        provider: snapshot?.provider,
+        providerSessionId: snapshot?.persistence?.sessionId ?? undefined,
+        shouldReplace,
+    }, "agent.session.start_stream.iterator_returned");
+    void (async () => {
+        try {
+            for await (const _ of iterator) {
+                // Events are broadcast via AgentManager subscribers.
+            }
+            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 { outOfBand: false };
+}
+/**
+ * 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) {
+    const unarchived = await agentManager.unarchiveSnapshot(agentId);
+    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);
+}
+const AGENT_RUN_START_TIMEOUT_MS = 15000;
+export async function waitForAgentRunStartWithTimeout(agentManager, agentId) {
+    const startAbort = new AbortController();
+    const startTimeout = setTimeout(() => startAbort.abort("timeout"), 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 `{ outOfBand: false }`) — 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 { outOfBand: false };
+        }
+        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, messageId: params.messageId }
+        : params.runOptions;
+    return startAgentRun(params.agentManager, params.agentId, params.prompt, params.logger, {
+        replaceRunning: true,
+        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 = startAgentRun(params.agentManager, params.agentId, params.prompt, params.logger, {
+        runOptions: params.runOptions,
+    });
+    if (!dispatchResult.outOfBand) {
+        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;
+}
+function formatFinishNotificationBody(params) {
+    const statusLine = `Agent ${params.childAgentId} (${params.title}) ${params.reason}.`;
+    const lastAssistantMessage = params.lastAssistantMessage?.trim();
+    if (!lastAssistantMessage) {
+        return statusLine;
+    }
+    return `${statusLine}\n\n<agent-response>\n${lastAssistantMessage}\n</agent-response>`;
+}
+export function setupFinishNotification(params) {
+    const { agentManager, agentStorage, childAgentId, callerAgentId, logger } = params;
+    let hasSeenRunning = false;
+    let fired = false;
+    let unsubscribe = null;
+    async function notify(reason) {
+        if (fired) {
+            return;
+        }
+        fired = true;
+        unsubscribe?.();
+        const callerRecord = await agentStorage.get(callerAgentId);
+        if (callerRecord?.archivedAt) {
+            return;
+        }
+        const record = await agentStorage.get(childAgentId);
+        const title = record?.title ?? childAgentId;
+        const lastAssistantMessage = await agentManager.getLastAssistantMessage(childAgentId);
+        const body = formatFinishNotificationBody({
+            childAgentId,
+            title,
+            reason,
+            lastAssistantMessage,
+        });
+        await sendPromptToAgent({
+            agentManager,
+            agentStorage,
+            agentId: callerAgentId,
+            prompt: formatSystemNotificationPrompt(body),
+            unarchive: false,
+            logger,
+        });
+    }
+    unsubscribe = agentManager.subscribe((event) => {
+        if (fired) {
+            return;
+        }
+        if (event.type === "agent_state") {
+            if (event.agent.lifecycle === "running") {
+                hasSeenRunning = true;
+                return;
+            }
+            if (event.agent.lifecycle === "error") {
+                void notify("errored");
+                return;
+            }
+            if (event.agent.lifecycle === "idle" && hasSeenRunning) {
+                void notify("finished");
+                return;
+            }
+            if (event.agent.lifecycle === "closed") {
+                fired = true;
+                unsubscribe?.();
+                return;
+            }
+            return;
+        }
+        if (event.event.type === "permission_requested") {
+            void notify("needs permission");
+        }
+    }, { 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") {
+        unsubscribe();
+        return;
+    }
+    if (childSnapshot.lifecycle === "running") {
+        hasSeenRunning = true;
+    }
+    else if (childSnapshot.lifecycle === "error") {
+        void notify("errored");
+    }
+}
+//# sourceMappingURL=agent-prompt.js.map

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

@@ -0,0 +1,67 @@
+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 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

package/dist/server/server/agent/agent-response-loop.js

@@ -0,0 +1,326 @@
+import { z } from "zod";
+import Ajv from "ajv";
+export class StructuredAgentResponseError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "StructuredAgentResponseError";
+        this.lastResponse = options.lastResponse;
+        this.validationErrors = options.validationErrors;
+    }
+}
+export class StructuredAgentFallbackError extends Error {
+    constructor(attempts) {
+        const summary = attempts
+            .map((attempt) => {
+            const modelSuffix = attempt.model ? ` (${attempt.model})` : "";
+            if (!attempt.available) {
+                return `${attempt.provider}${modelSuffix}: unavailable${attempt.error ? ` (${attempt.error})` : ""}`;
+            }
+            return `${attempt.provider}${modelSuffix}: failed${attempt.error ? ` (${attempt.error})` : ""}`;
+        })
+            .join("; ");
+        super(summary.length > 0
+            ? `Structured generation failed for all providers: ${summary}`
+            : "Structured generation failed for all providers");
+        this.name = "StructuredAgentFallbackError";
+        this.attempts = attempts;
+    }
+}
+// Re-export from the legacy module path so existing server consumers keep working.
+export { DEFAULT_STRUCTURED_GENERATION_PROVIDERS } from "./structured-generation-providers.js";
+function isZodSchema(value) {
+    return typeof value?.safeParse === "function";
+}
+function buildZodValidator(schema, schemaName) {
+    const jsonSchema = z.toJSONSchema(schema, {
+        target: "draft-07",
+        unrepresentable: "any",
+        io: "input",
+    });
+    if (typeof jsonSchema.title !== "string") {
+        jsonSchema.title = schemaName;
+    }
+    return {
+        jsonSchema,
+        validate: (value) => {
+            const result = schema.safeParse(value);
+            if (result.success) {
+                return { ok: true, value: result.data };
+            }
+            const errors = result.error.issues.map((issue) => {
+                const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+                return `${path}: ${issue.message}`;
+            });
+            return { ok: false, errors };
+        },
+    };
+}
+function buildJsonSchemaValidator(schema) {
+    const AjvConstructor = Ajv;
+    const ajv = new AjvConstructor({ allErrors: true, strict: false });
+    const validate = ajv.compile(schema);
+    return {
+        jsonSchema: schema,
+        validate: (value) => {
+            const ok = validate(value);
+            if (ok) {
+                return { ok: true, value: value };
+            }
+            const errors = (validate.errors ?? []).map((error) => {
+                const path = error.instancePath && error.instancePath.length > 0 ? error.instancePath : "(root)";
+                const message = error.message ?? "is invalid";
+                return `${path}: ${message}`;
+            });
+            return { ok: false, errors };
+        },
+    };
+}
+function buildValidator(schema, schemaName) {
+    if (isZodSchema(schema)) {
+        return buildZodValidator(schema, schemaName);
+    }
+    return buildJsonSchemaValidator(schema);
+}
+function buildBasePrompt(prompt, jsonSchema) {
+    const schemaText = JSON.stringify(jsonSchema, null, 2);
+    return [
+        prompt.trim(),
+        "",
+        "You must respond with JSON only that matches this JSON Schema:",
+        schemaText,
+    ].join("\n");
+}
+function buildRetryPrompt(basePrompt, errors) {
+    const formattedErrors = errors.map((error) => `- ${error}`).join("\n");
+    return [
+        basePrompt,
+        "",
+        "Previous response was invalid with validation errors:",
+        formattedErrors.length > 0 ? formattedErrors : "- Unknown validation error",
+        "",
+        "Respond again with JSON only that matches the schema.",
+    ].join("\n");
+}
+function extractJsonFromMarkdown(text) {
+    const fencedMatch = text.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+    if (fencedMatch) {
+        return fencedMatch[1].trim();
+    }
+    const extracted = extractFirstJsonSnippet(text);
+    if (extracted) {
+        return extracted;
+    }
+    return text.trim();
+}
+function tryParseJson(candidate) {
+    try {
+        JSON.parse(candidate);
+        return candidate;
+    }
+    catch {
+        return null;
+    }
+}
+function extractBalancedJsonCandidate(source, start) {
+    const open = source[start];
+    const close = open === "{" ? "}" : "]";
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < source.length; i += 1) {
+        const ch = source[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === open) {
+            depth += 1;
+            continue;
+        }
+        if (ch !== close) {
+            continue;
+        }
+        depth -= 1;
+        if (depth !== 0) {
+            continue;
+        }
+        const candidate = source.slice(start, i + 1).trim();
+        const parsed = tryParseJson(candidate);
+        if (parsed !== null) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function extractFirstJsonSnippet(text) {
+    const source = text.trim();
+    if (!source) {
+        return null;
+    }
+    // Try to find the first valid JSON object/array within a larger response.
+    // This is intentionally provider-agnostic and improves resilience when models
+    // add extra prose before/after the JSON.
+    const startIndexes = [];
+    for (let i = 0; i < source.length; i += 1) {
+        const ch = source[i];
+        if (ch === "{" || ch === "[") {
+            startIndexes.push(i);
+        }
+    }
+    for (const start of startIndexes) {
+        const candidate = extractBalancedJsonCandidate(source, start);
+        if (candidate !== null) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export async function getStructuredAgentResponse(options) {
+    const { caller, prompt, schema, maxRetries = 2, schemaName = "Response" } = options;
+    const validator = buildValidator(schema, schemaName);
+    const basePrompt = buildBasePrompt(prompt, validator.jsonSchema);
+    let attemptPrompt = basePrompt;
+    let lastResponse = "";
+    let lastErrors = [];
+    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+        const response = await caller(attemptPrompt);
+        lastResponse = response;
+        const jsonText = extractJsonFromMarkdown(response);
+        let parsed;
+        try {
+            parsed = JSON.parse(jsonText);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            lastErrors = [`Invalid JSON: ${message}`];
+            if (attempt === maxRetries) {
+                break;
+            }
+            attemptPrompt = buildRetryPrompt(basePrompt, lastErrors);
+            continue;
+        }
+        const validation = validator.validate(parsed);
+        if (validation.ok) {
+            return validation.value;
+        }
+        lastErrors = validation.errors;
+        if (attempt === maxRetries) {
+            break;
+        }
+        attemptPrompt = buildRetryPrompt(basePrompt, lastErrors);
+    }
+    throw new StructuredAgentResponseError("Agent response did not match the required JSON schema", {
+        lastResponse,
+        validationErrors: lastErrors,
+    });
+}
+export async function generateStructuredAgentResponse(options) {
+    const { manager, agentConfig, agentId, persistSession, prompt, schema, maxRetries, schemaName } = options;
+    const agent = await manager.createAgent(agentConfig, agentId, { persistSession });
+    try {
+        const caller = async (nextPrompt) => {
+            const result = await manager.runAgent(agent.id, nextPrompt);
+            if (typeof result.finalText === "string" && result.finalText.length > 0) {
+                return result.finalText;
+            }
+            // Fallback for providers that may not populate finalText consistently.
+            const lastAssistant = result.timeline.findLast((item) => item.type === "assistant_message");
+            return lastAssistant?.text ?? "";
+        };
+        return await getStructuredAgentResponse({
+            caller,
+            prompt,
+            schema,
+            maxRetries,
+            schemaName,
+        });
+    }
+    finally {
+        try {
+            await manager.closeAgent(agent.id);
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    }
+}
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+export async function generateStructuredAgentResponseWithFallback(options) {
+    const { manager, cwd, prompt, schema, providers, agentConfigOverrides, persistSession, maxRetries, schemaName, logger, runner, } = options;
+    if (providers.length === 0) {
+        throw new StructuredAgentFallbackError([]);
+    }
+    const runStructured = runner ??
+        ((input) => generateStructuredAgentResponse(input));
+    const attempts = [];
+    for (const candidate of providers) {
+        const availabilityEntry = await manager.getProviderAvailability(candidate.provider);
+        if (!availabilityEntry.available) {
+            const reason = availabilityEntry.error ?? "unavailable";
+            attempts.push({
+                provider: candidate.provider,
+                model: candidate.model ?? null,
+                available: false,
+                error: availabilityEntry.error ?? null,
+            });
+            logger?.warn({ provider: candidate.provider, model: candidate.model, schemaName, reason }, "Structured generation: skipping unavailable provider");
+            continue;
+        }
+        try {
+            const result = await runStructured({
+                manager,
+                prompt,
+                schema,
+                maxRetries,
+                schemaName,
+                persistSession,
+                agentConfig: {
+                    ...agentConfigOverrides,
+                    provider: candidate.provider,
+                    cwd,
+                    ...(candidate.model ? { model: candidate.model } : {}),
+                    ...(candidate.thinkingOptionId ? { thinkingOptionId: candidate.thinkingOptionId } : {}),
+                },
+            });
+            if (attempts.length > 0) {
+                logger?.info({
+                    provider: candidate.provider,
+                    model: candidate.model,
+                    schemaName,
+                    priorAttempts: attempts,
+                }, "Structured generation: succeeded after fallback");
+            }
+            return result;
+        }
+        catch (error) {
+            attempts.push({
+                provider: candidate.provider,
+                model: candidate.model ?? null,
+                available: true,
+                error: errorMessage(error),
+            });
+            logger?.warn({ err: error, provider: candidate.provider, model: candidate.model, schemaName }, "Structured generation: provider failed, trying next");
+        }
+    }
+    throw new StructuredAgentFallbackError(attempts);
+}
+//# sourceMappingURL=agent-response-loop.js.map

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

@@ -0,0 +1,18 @@
+import type express from "express";
+import type pino from "pino";
+import type { AgentManager } from "./agent-manager.js";
+/**
+ * Registers HTTP routes that implement the chat-actions bundle bridges:
+ *
+ * - `POST /agents/:agentId/rewind`       — Story 2.2 (Rewind to here)
+ * - `POST /agents/:agentId/edit-message` — Story 2.4 (Edit a user message)
+ *
+ * Both reuse `truncateSessionAt` (Story 2.1) and look up the agent's
+ * (sessionId, cwd) via `AgentManager.getAgent`. The legacy session JSONL is
+ * never mutated — the fork lives at a brand-new sessionId.
+ *
+ * Loopback-only, single-user trust model (gated by daemon password Bearer auth
+ * via `createRequireBearerMiddleware`, same as the other Express routes).
+ */
+export declare function registerAgentRoutes(app: express.Express, agentManager: AgentManager, logger: pino.Logger): void;
+//# sourceMappingURL=agent-routes.d.ts.map