@ottocode/server 0.1.260 → 0.1.261

package/src/routes/session-messages.ts

@@ -13,170 +13,350 @@ import { eq, inArray } from 'drizzle-orm';
 import { dispatchAssistantMessage } from '../runtime/message/service.ts';
 import { logger } from '@ottocode/sdk';
 import { serializeError } from '../runtime/errors/api-error.ts';
+import { openApiRoute } from '../openapi/route.ts';
 
 type MessagePartRow = typeof messageParts.$inferSelect;
 type SessionRow = typeof sessions.$inferSelect;
 
 export function registerSessionMessagesRoutes(app: Hono) {
 	// List messages for a session
-	app.get('/v1/sessions/:id/messages', async (c) => {
-		try {
-			const projectRoot = c.req.query('project') || process.cwd();
-			const cfg = await loadConfig(projectRoot);
-			const db = await getDb(cfg.projectRoot);
-			const id = c.req.param('id');
-			const rows = await db
-				.select()
-				.from(messages)
-				.where(eq(messages.sessionId, id))
-				.orderBy(messages.createdAt);
-			const without = c.req.query('without');
-			if (without !== 'parts') {
-				const ids = rows.map((m) => m.id);
-				const parts = ids.length
-					? await db
-							.select()
-							.from(messageParts)
-							.where(inArray(messageParts.messageId, ids))
-					: [];
-				const partsByMsg = new Map<string, MessagePartRow[]>();
-				for (const p of parts) {
-					const existing = partsByMsg.get(p.messageId);
-					if (existing) existing.push(p);
-					else partsByMsg.set(p.messageId, [p]);
-				}
-				const wantParsed = (() => {
-					const q = (c.req.query('parsed') || '').toLowerCase();
-					return q === '1' || q === 'true' || q === 'yes';
-				})();
-				function parseContent(raw: string): Record<string, unknown> | string {
-					try {
-						const v = JSON.parse(String(raw ?? ''));
-						if (v && typeof v === 'object' && !Array.isArray(v))
-							return v as Record<string, unknown>;
-					} catch {}
-					return raw;
-				}
-				const enriched = rows.map((m) => {
-					const parts = (partsByMsg.get(m.id) ?? []).sort(
-						(a, b) => a.index - b.index,
-					);
-					const mapped = parts.map((p) => {
-						const parsed = parseContent(p.content);
-						return wantParsed
-							? { ...p, content: parsed }
-							: { ...p, contentJson: parsed };
+	openApiRoute(
+		app,
+		{
+			method: 'get',
+			path: '/v1/sessions/{id}/messages',
+			tags: ['messages'],
+			operationId: 'listMessages',
+			summary: 'List messages for a session',
+			parameters: [
+				{
+					in: 'query',
+					name: 'project',
+					required: false,
+					schema: {
+						type: 'string',
+					},
+					description:
+						'Project root override (defaults to current working directory).',
+				},
+				{
+					in: 'path',
+					name: 'id',
+					required: true,
+					schema: {
+						type: 'string',
+					},
+				},
+				{
+					in: 'query',
+					name: 'without',
+					required: false,
+					schema: {
+						type: 'string',
+						enum: ['parts'],
+					},
+					description:
+						'Exclude parts from the response. By default, parts are included.',
+				},
+			],
+			responses: {
+				'200': {
+					description: 'OK',
+					content: {
+						'application/json': {
+							schema: {
+								type: 'array',
+								items: {
+									allOf: [
+										{
+											$ref: '#/components/schemas/Message',
+										},
+										{
+											type: 'object',
+											properties: {
+												parts: {
+													type: 'array',
+													items: {
+														$ref: '#/components/schemas/MessagePart',
+													},
+												},
+											},
+											required: [],
+										},
+									],
+								},
+							},
+						},
+					},
+				},
+			},
+		},
+		async (c) => {
+			try {
+				const projectRoot = c.req.query('project') || process.cwd();
+				const cfg = await loadConfig(projectRoot);
+				const db = await getDb(cfg.projectRoot);
+				const id = c.req.param('id');
+				const rows = await db
+					.select()
+					.from(messages)
+					.where(eq(messages.sessionId, id))
+					.orderBy(messages.createdAt);
+				const without = c.req.query('without');
+				if (without !== 'parts') {
+					const ids = rows.map((m) => m.id);
+					const parts = ids.length
+						? await db
+								.select()
+								.from(messageParts)
+								.where(inArray(messageParts.messageId, ids))
+						: [];
+					const partsByMsg = new Map<string, MessagePartRow[]>();
+					for (const p of parts) {
+						const existing = partsByMsg.get(p.messageId);
+						if (existing) existing.push(p);
+						else partsByMsg.set(p.messageId, [p]);
+					}
+					const wantParsed = (() => {
+						const q = (c.req.query('parsed') || '').toLowerCase();
+						return q === '1' || q === 'true' || q === 'yes';
+					})();
+					function parseContent(raw: string): Record<string, unknown> | string {
+						try {
+							const v = JSON.parse(String(raw ?? ''));
+							if (v && typeof v === 'object' && !Array.isArray(v))
+								return v as Record<string, unknown>;
+						} catch {}
+						return raw;
+					}
+					const enriched = rows.map((m) => {
+						const parts = (partsByMsg.get(m.id) ?? []).sort(
+							(a, b) => a.index - b.index,
+						);
+						const mapped = parts.map((p) => {
+							const parsed = parseContent(p.content);
+							return wantParsed
+								? { ...p, content: parsed }
+								: { ...p, contentJson: parsed };
+						});
+						return { ...m, parts: mapped };
 					});
-					return { ...m, parts: mapped };
-				});
-				return c.json(enriched);
+					return c.json(enriched);
+				}
+				return c.json(rows);
+			} catch (error) {
+				logger.error('Failed to list session messages', error);
+				const errorResponse = serializeError(error);
+				return c.json(errorResponse, errorResponse.error.status || 500);
 			}
-			return c.json(rows);
-		} catch (error) {
-			logger.error('Failed to list session messages', error);
-			const errorResponse = serializeError(error);
-			return c.json(errorResponse, errorResponse.error.status || 500);
-		}
-	});
+		},
+	);
 
 	// Post a user message and get assistant reply (non-streaming for v0)
-	app.post('/v1/sessions/:id/messages', async (c) => {
-		try {
-			const projectRoot = c.req.query('project') || process.cwd();
-			const cfg = await loadConfig(projectRoot);
-			const db = await getDb(cfg.projectRoot);
-			const sessionId = c.req.param('id');
-			const body = await c.req.json().catch(() => ({}));
+	openApiRoute(
+		app,
+		{
+			method: 'post',
+			path: '/v1/sessions/{id}/messages',
+			tags: ['messages'],
+			operationId: 'createMessage',
+			summary: 'Send a user message and enqueue assistant run',
+			parameters: [
+				{
+					in: 'query',
+					name: 'project',
+					required: false,
+					schema: {
+						type: 'string',
+					},
+					description:
+						'Project root override (defaults to current working directory).',
+				},
+				{
+					in: 'path',
+					name: 'id',
+					required: true,
+					schema: {
+						type: 'string',
+					},
+				},
+			],
+			requestBody: {
+				required: true,
+				content: {
+					'application/json': {
+						schema: {
+							type: 'object',
+							required: ['content'],
+							properties: {
+								content: {
+									type: 'string',
+								},
+								agent: {
+									type: 'string',
+									description: 'Agent name. Defaults to config if omitted.',
+								},
+								provider: {
+									$ref: '#/components/schemas/Provider',
+								},
+								model: {
+									type: 'string',
+								},
+								userContext: {
+									type: 'string',
+									description:
+										'Optional user-provided context to include in the system prompt.',
+								},
+								reasoningText: {
+									type: 'boolean',
+									description:
+										'Enable extended thinking / reasoning for models that support it.',
+								},
+								reasoningLevel: {
+									type: 'string',
+									enum: ['minimal', 'low', 'medium', 'high', 'max', 'xhigh'],
+									description:
+										'Reasoning intensity level for providers/models that support it.',
+								},
+							},
+						},
+					},
+				},
+			},
+			responses: {
+				'202': {
+					description: 'Accepted',
+					content: {
+						'application/json': {
+							schema: {
+								type: 'object',
+								properties: {
+									messageId: {
+										type: 'string',
+									},
+								},
+								required: ['messageId'],
+							},
+						},
+					},
+				},
+				'400': {
+					description: 'Bad Request',
+					content: {
+						'application/json': {
+							schema: {
+								type: 'object',
+								properties: {
+									error: {
+										type: 'string',
+									},
+								},
+								required: ['error'],
+							},
+						},
+					},
+				},
+			},
+		},
+		async (c) => {
+			try {
+				const projectRoot = c.req.query('project') || process.cwd();
+				const cfg = await loadConfig(projectRoot);
+				const db = await getDb(cfg.projectRoot);
+				const sessionId = c.req.param('id');
+				const body = await c.req.json().catch(() => ({}));
 
-			// DEBUG: Log received body
-			logger.info('[API] Received message request', {
-				sessionId,
-				hasContent: !!body?.content,
-				hasUserContext: !!body?.userContext,
-				userContext: body?.userContext
-					? `${String(body.userContext).substring(0, 50)}...`
-					: 'NONE',
-			});
+				// DEBUG: Log received body
+				logger.info('[API] Received message request', {
+					sessionId,
+					hasContent: !!body?.content,
+					hasUserContext: !!body?.userContext,
+					userContext: body?.userContext
+						? `${String(body.userContext).substring(0, 50)}...`
+						: 'NONE',
+				});
 
-			// Load session to inherit its provider/model/agent by default
-			const sessionRows = await db
-				.select()
-				.from(sessions)
-				.where(eq(sessions.id, sessionId));
-			if (!sessionRows.length) {
-				logger.warn('Session not found', { sessionId });
-				return c.json({ error: 'Session not found' }, 404);
-			}
-			const sess: SessionRow = sessionRows[0];
-			const provider = body?.provider ?? sess.provider ?? cfg.defaults.provider;
-			const modelName = body?.model ?? sess.model ?? cfg.defaults.model;
-			const agent = body?.agent ?? sess.agent ?? cfg.defaults.agent;
-			const content = body?.content ?? '';
-			const userContext = body?.userContext;
-			const images = Array.isArray(body?.images) ? body.images : undefined;
-			const files = Array.isArray(body?.files) ? body.files : undefined;
+				// Load session to inherit its provider/model/agent by default
+				const sessionRows = await db
+					.select()
+					.from(sessions)
+					.where(eq(sessions.id, sessionId));
+				if (!sessionRows.length) {
+					logger.warn('Session not found', { sessionId });
+					return c.json({ error: 'Session not found' }, 404);
+				}
+				const sess: SessionRow = sessionRows[0];
+				const provider =
+					body?.provider ?? sess.provider ?? cfg.defaults.provider;
+				const modelName = body?.model ?? sess.model ?? cfg.defaults.model;
+				const agent = body?.agent ?? sess.agent ?? cfg.defaults.agent;
+				const content = body?.content ?? '';
+				const userContext = body?.userContext;
+				const images = Array.isArray(body?.images) ? body.images : undefined;
+				const files = Array.isArray(body?.files) ? body.files : undefined;
 
-			// DEBUG: Log extracted userContext
-			logger.info('[API] Extracted userContext', {
-				userContext: userContext
-					? `${String(userContext).substring(0, 50)}...`
-					: 'NONE',
-				typeOf: typeof userContext,
-			});
+				// DEBUG: Log extracted userContext
+				logger.info('[API] Extracted userContext', {
+					userContext: userContext
+						? `${String(userContext).substring(0, 50)}...`
+						: 'NONE',
+					typeOf: typeof userContext,
+				});
 
-			const reasoning =
-				body?.reasoningText ?? cfg.defaults.reasoningText ?? false;
-			const reasoningLevel =
-				(body?.reasoningLevel as ReasoningLevel | undefined) ??
-				cfg.defaults.reasoningLevel ??
-				'high';
+				const reasoning =
+					body?.reasoningText ?? cfg.defaults.reasoningText ?? false;
+				const reasoningLevel =
+					(body?.reasoningLevel as ReasoningLevel | undefined) ??
+					cfg.defaults.reasoningLevel ??
+					'high';
 
-			// Validate model capabilities if tools are allowed for this agent
-			const wantsToolCalls = true; // agent toolset may be non-empty
-			try {
-				validateProviderModel(provider, modelName, cfg, { wantsToolCalls });
-			} catch (err) {
-				logger.error('Model validation failed', err, { provider, modelName });
-				const message = err instanceof Error ? err.message : String(err);
-				return c.json({ error: message }, 400);
-			}
-			// Enforce provider auth: only allow providers/models the user authenticated for
-			const authorized = await isProviderAuthorized(cfg, provider);
-			if (!authorized) {
-				logger.warn('Provider not authorized', { provider });
-				return c.json(
-					{
-						error: `Provider ${provider} is not configured. Run \`otto auth login\` to add credentials.`,
-					},
-					400,
-				);
-			}
-			await ensureProviderEnv(cfg, provider);
-			const providerDefinition = getProviderDefinition(cfg, provider);
+				// Validate model capabilities if tools are allowed for this agent
+				const wantsToolCalls = true; // agent toolset may be non-empty
+				try {
+					validateProviderModel(provider, modelName, cfg, { wantsToolCalls });
+				} catch (err) {
+					logger.error('Model validation failed', err, { provider, modelName });
+					const message = err instanceof Error ? err.message : String(err);
+					return c.json({ error: message }, 400);
+				}
+				// Enforce provider auth: only allow providers/models the user authenticated for
+				const authorized = await isProviderAuthorized(cfg, provider);
+				if (!authorized) {
+					logger.warn('Provider not authorized', { provider });
+					return c.json(
+						{
+							error: `Provider ${provider} is not configured. Run \`otto auth login\` to add credentials.`,
+						},
+						400,
+					);
+				}
+				await ensureProviderEnv(cfg, provider);
+				const providerDefinition = getProviderDefinition(cfg, provider);
 
-			const { assistantMessageId } = await dispatchAssistantMessage({
-				cfg,
-				db,
-				session: sess,
-				agent,
-				provider,
-				model: modelName,
-				content,
-				oneShot: Boolean(body?.oneShot),
-				userContext,
-				reasoningText:
-					providerDefinition?.compatibility === 'ollama'
-						? (body?.reasoningText ?? false)
-						: reasoning,
-				reasoningLevel,
-				images,
-				files,
-			});
-			return c.json({ messageId: assistantMessageId }, 202);
-		} catch (error) {
-			logger.error('Failed to create session message', error);
-			const errorResponse = serializeError(error);
-			return c.json(errorResponse, errorResponse.error.status || 500);
-		}
-	});
+				const { assistantMessageId } = await dispatchAssistantMessage({
+					cfg,
+					db,
+					session: sess,
+					agent,
+					provider,
+					model: modelName,
+					content,
+					oneShot: Boolean(body?.oneShot),
+					userContext,
+					reasoningText:
+						providerDefinition?.compatibility === 'ollama'
+							? (body?.reasoningText ?? false)
+							: reasoning,
+					reasoningLevel,
+					images,
+					files,
+				});
+				return c.json({ messageId: assistantMessageId }, 202);
+			} catch (error) {
+				logger.error('Failed to create session message', error);
+				const errorResponse = serializeError(error);
+				return c.json(errorResponse, errorResponse.error.status || 500);
+			}
+		},
+	);
 }

package/src/routes/session-stream.ts

@@ -2,6 +2,7 @@ import type { Context } from 'hono';
 import type { Hono } from 'hono';
 import { subscribe } from '../events/bus.ts';
 import type { OttoEvent } from '../events/types.ts';
+import { openApiRoute } from '../openapi/route.ts';
 
 function safeStringify(obj: unknown): string {
 	return JSON.stringify(obj, (_key, value) =>
@@ -57,6 +58,86 @@ function handleSessionStream(c: Context) {
 }
 
 export function registerSessionStreamRoute(app: Hono) {
-	app.get('/v1/sessions/:id/stream', handleSessionStream);
-	app.post('/v1/sessions/:id/stream', handleSessionStream);
+	openApiRoute(
+		app,
+		{
+			method: 'get',
+			path: '/v1/sessions/{id}/stream',
+			tags: ['stream'],
+			operationId: 'subscribeSessionStream',
+			summary: 'Subscribe to session event stream (SSE)',
+			parameters: [
+				{
+					in: 'query',
+					name: 'project',
+					required: false,
+					schema: {
+						type: 'string',
+					},
+					description:
+						'Project root override (defaults to current working directory).',
+				},
+				{
+					in: 'path',
+					name: 'id',
+					required: true,
+					schema: {
+						type: 'string',
+					},
+				},
+			],
+			responses: {
+				'200': {
+					description: 'text/event-stream',
+					content: {
+						'text/event-stream': {
+							schema: {
+								type: 'string',
+								description:
+									'SSE event stream. Events include session.created, message.created, message.part.delta, tool.call, tool.delta, tool.result, message.completed, error.',
+							},
+						},
+					},
+				},
+			},
+		},
+		handleSessionStream,
+	);
+	openApiRoute(
+		app,
+		{
+			method: 'post',
+			path: '/v1/sessions/{id}/stream',
+			tags: ['stream'],
+			operationId: 'subscribeSessionStreamPost',
+			summary: 'Subscribe to session event stream (SSE) using POST',
+			parameters: [
+				{
+					in: 'query',
+					name: 'project',
+					required: false,
+					schema: { type: 'string' },
+					description:
+						'Project root override (defaults to current working directory).',
+				},
+				{
+					in: 'path',
+					name: 'id',
+					required: true,
+					schema: { type: 'string' },
+				},
+			],
+			responses: {
+				'200': {
+					description: 'text/event-stream',
+					content: {
+						'text/event-stream': {
+							schema: { type: 'string' },
+						},
+					},
+				},
+			},
+		},
+		handleSessionStream,
+	);
 }