import { negotiateProviderCapabilities, requireProviderCapabilities, type ProviderConfigState, type ProviderConnection, type ProviderEvent, type ProviderInput, type ProviderPersistence, type ProviderRegistration, type ProviderSessionConfig, } from "@getpaseo/plugin/server/provider"; import { randomUUID } from "node:crypto"; import { providerResultKind } from "../shared/provider-result.js"; const CAPABILITIES = [ "prompt.message", "prompt.command", "prompt.steer", "session.archive", "session.configure", "session.list", "session.persistence", "session.subsession", "session.unarchive", "timeline.plugin", ] as const; interface ExampleSession { config: ProviderSessionConfig; persistence: ProviderPersistence; turn: number; activeTurnId: string | null; } export function createDirectExampleProvider(): ProviderRegistration { return { id: "direct-example", label: "Direct provider example", description: "A complete provider implemented directly against Paseo's provider boundary", icon: "icon.svg", async connect(request) { if (!request.versions.includes(1)) throw new Error("Provider protocol version 1 is required"); return createConnection(negotiateProviderCapabilities(request.capabilities, CAPABILITIES)); }, }; } function createConnection(capabilities: readonly string[]): ProviderConnection { const listeners = new Set<(event: ProviderEvent) => void>(); const sessions = new Map(); const archived = new Set(); let closed = false; const emit = (event: ProviderEvent) => { if (closed) return; for (const listener of listeners) listener(event); }; return { version: 1, capabilities, async send(input) { if (closed) throw new Error("Provider connection is closed"); validateAdmission(input, { sessions, capabilities }); queueMicrotask(() => { if (!closed) dispatch(input, { sessions, archived, emit, capabilities }); }); }, onEvent(listener) { listeners.add(listener); return () => listeners.delete(listener); }, async close() { if (closed) return; closed = true; sessions.clear(); listeners.clear(); }, }; } function validateAdmission( input: ProviderInput, state: Pick, ): void { if (input.type === "session.open") { if (state.sessions.has(input.sessionId)) { throw new Error(`Session already exists: ${input.sessionId}`); } requireProviderCapabilities(state.capabilities, input); return; } if (!("sessionId" in input)) { requireProviderCapabilities(state.capabilities, input); return; } const session = state.sessions.get(input.sessionId); if (!session) throw new Error(`Unknown session: ${input.sessionId}`); requireProviderCapabilities(state.capabilities, input); } interface ExampleState { sessions: Map; archived: Set; emit(event: ProviderEvent): void; capabilities: readonly string[]; } function dispatch(input: ProviderInput, state: ExampleState): void { switch (input.type) { case "catalog": state.emit({ type: "catalog", requestId: input.requestId, catalog: { models: [{ id: "example-1", label: "Example 1" }], modes: [{ id: "build", label: "Build" }], defaultModel: "example-1", defaultMode: "build", }, }); return; case "sessions": state.emit({ type: "sessions", requestId: input.requestId, sessions: [...state.sessions.values()].map((session) => ({ persistence: session.persistence, cwd: session.config.cwd, title: session.config.title, })), }); return; case "session.open": openSession(input, state); return; case "session.prompt": promptSession(input, state); return; case "session.configure": configureSession(input, state); return; case "session.interrupt": state.emit({ type: "request.completed", requestId: input.requestId }); return; case "session.permission": state.emit({ type: "session.permission_resolved", sessionId: input.sessionId, permissionId: input.permissionId, }); return; case "session.revert": state.emit({ type: "request.completed", requestId: input.requestId }); return; case "session.archive": state.archived.add(persistenceKey(input.persistence)); state.emit({ type: "request.completed", requestId: input.requestId }); return; case "session.unarchive": state.archived.delete(persistenceKey(input.persistence)); state.emit({ type: "request.completed", requestId: input.requestId }); return; case "session.close": state.sessions.delete(input.sessionId); state.emit({ type: "session.closed", sessionId: input.sessionId }); state.emit({ type: "request.completed", requestId: input.requestId }); } } function openSession( input: Extract, state: ExampleState, ): void { const persistence = input.persistence ?? { version: 1, data: { nativeSessionId: `example:${input.sessionId}` }, }; const session: ExampleSession = { config: input.config, persistence, turn: 0, activeTurnId: null, }; state.sessions.set(input.sessionId, session); state.emit({ type: "session.opened", requestId: input.requestId, sessionId: input.sessionId, capabilities: state.capabilities, restoration: "core", persistence, title: input.config.title, cwd: input.config.cwd, }); state.emit({ type: "session.config", sessionId: input.sessionId, config: configState(session) }); state.emit({ type: "session.commands", sessionId: input.sessionId, commands: [{ name: "reset", description: "Reset the example provider state" }], }); if (input.history === "replay" && input.persistence) { state.emit({ type: "timeline.item", sessionId: input.sessionId, item: { type: "assistant_message", id: "replayed-1", text: "Restored from persistence" }, }); } state.emit({ type: "session.ready", requestId: input.requestId, sessionId: input.sessionId }); } function promptSession( input: Extract, state: ExampleState, ): void { const session = requireSession(state, input.sessionId); if (input.prompt.delivery === "steer") { if (!session.activeTurnId) { state.emit({ type: "session.prompt_result", sessionId: input.sessionId, clientMessageId: input.prompt.clientMessageId, result: { type: "failed", error: { message: "There is no active turn to steer" } }, }); return; } state.emit({ type: "session.prompt_result", sessionId: input.sessionId, clientMessageId: input.prompt.clientMessageId, result: { type: "steer", turnId: session.activeTurnId }, }); return; } if (input.prompt.input.type === "command") { if (input.prompt.input.name !== "reset") { state.emit({ type: "session.prompt_result", sessionId: input.sessionId, clientMessageId: input.prompt.clientMessageId, result: { type: "failed", error: { message: "Unknown command" } }, }); return; } session.turn = 0; state.emit({ type: "session.notice", sessionId: input.sessionId, notice: { id: "reset", severity: "info", title: "Example state reset" }, }); state.emit({ type: "session.prompt_result", sessionId: input.sessionId, clientMessageId: input.prompt.clientMessageId, result: { type: "completed" }, }); return; } session.turn += 1; const turnId = `turn-${session.turn}`; session.activeTurnId = turnId; const text = input.prompt.input.content .filter((part) => part.type === "text") .map((part) => part.text) .join("\n"); state.emit({ type: "timeline.item", sessionId: input.sessionId, item: { type: "user_message", id: `user-${session.turn}`, text, clientMessageId: input.prompt.clientMessageId, }, }); state.emit({ type: "session.prompt_result", sessionId: input.sessionId, clientMessageId: input.prompt.clientMessageId, result: { type: "turn", turnId }, }); state.emit({ type: "session.turn", sessionId: input.sessionId, turnId, state: "started" }); state.emit({ type: "timeline.item", sessionId: input.sessionId, item: { type: "assistant_message", id: `assistant-${session.turn}`, text: `Echo: ${text}` }, }); state.emit({ type: "timeline.item", sessionId: input.sessionId, item: { type: "plugin", id: `provider-result-${session.turn}`, pluginId: "provider-direct-example", kind: providerResultKind, version: 1, data: { label: "Provider result", detail: `Echoed turn ${session.turn}` }, }, }); publishChild(input.sessionId, session.turn, state); session.persistence = { version: 1, data: { nativeSessionId: `example:${input.sessionId}`, turns: session.turn }, }; state.emit({ type: "session.persistence", sessionId: input.sessionId, persistence: session.persistence, }); state.emit({ type: "session.turn", sessionId: input.sessionId, turnId, state: "completed" }); session.activeTurnId = null; } function publishChild(parentSessionId: string, turn: number, state: ExampleState): void { const sessionId = randomUUID(); state.emit({ type: "session.opened", sessionId, parentSessionId, capabilities: [], restoration: "parent", title: "Example child", cwd: requireSession(state, parentSessionId).config.cwd, }); state.emit({ type: "timeline.item", sessionId, item: { type: "plugin", id: `child-result-${turn}`, pluginId: "provider-direct-example", kind: providerResultKind, version: 1, data: { label: "Child result", detail: "Completed" }, }, }); state.emit({ type: "session.ready", sessionId }); } function configureSession( input: Extract, state: ExampleState, ): void { const session = requireSession(state, input.sessionId); const changes = input.changes; session.config = { ...session.config, model: changes.model === null ? undefined : (changes.model ?? session.config.model), mode: changes.mode === null ? undefined : (changes.mode ?? session.config.mode), thinkingOption: changes.thinkingOption === null ? undefined : (changes.thinkingOption ?? session.config.thinkingOption), settings: changes.settings ? { ...session.config.settings, ...changes.settings } : session.config.settings, }; state.emit({ type: "session.config", sessionId: input.sessionId, config: configState(session) }); state.emit({ type: "request.completed", requestId: input.requestId }); } function configState(session: ExampleSession): ProviderConfigState { return { model: session.config.model ?? "example-1", mode: session.config.mode ?? "build", thinkingOption: session.config.thinkingOption, models: [{ id: "example-1", label: "Example 1" }], modes: [{ id: "build", label: "Build" }], thinkingOptions: [], settings: [ { type: "toggle", id: "concise", label: "Concise responses", value: session.config.settings.concise === true, }, { type: "select", id: "voice", label: "Voice", value: typeof session.config.settings.voice === "string" ? session.config.settings.voice : null, options: [ { label: "Calm", value: "calm" }, { label: "Direct", value: "direct" }, ], }, ], }; } function requireSession(state: ExampleState, sessionId: string): ExampleSession { const session = state.sessions.get(sessionId); if (!session) throw new Error(`Unknown session: ${sessionId}`); return session; } function persistenceKey(persistence: ProviderPersistence): string { return JSON.stringify(persistence); }