@ottocode/server 0.1.260 → 0.1.261

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ottocode/server",
-	"version": "0.1.260",
+	"version": "0.1.261",
 	"description": "HTTP API server for ottocode",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -61,8 +61,9 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@ottocode/database": "0.1.260",
-		"@ottocode/sdk": "0.1.260",
+		"@ottocode/database": "0.1.261",
+		"@ottocode/sdk": "0.1.261",
+		"@hono/zod-openapi": "^1.1.5",
 		"ai-sdk-ollama": "^3.8.3",
 		"drizzle-orm": "^0.44.5",
 		"hono": "^4.9.9",

package/src/index.ts

@@ -1,4 +1,5 @@
-import { Hono } from 'hono';
+import { OpenAPIHono } from '@hono/zod-openapi';
+import type { BlankEnv } from 'hono/types';
 import { cors } from 'hono/cors';
 import type { ProviderId, AuthInfo } from '@ottocode/sdk';
 import { TerminalManager } from '@ottocode/sdk';
@@ -34,7 +35,7 @@ setTerminalManager(globalTerminalManager);
 installAiSdkWarningHandler();
 
 function initApp() {
-	const app = new Hono();
+	const app = new OpenAPIHono<BlankEnv>();
 
 	// Enable CORS for localhost and local network access
 	app.use(
@@ -110,7 +111,7 @@ export type StandaloneAppConfig = {
 };
 
 export function createStandaloneApp(_config?: StandaloneAppConfig) {
-	const honoApp = new Hono();
+	const honoApp = new OpenAPIHono<BlankEnv>();
 
 	honoApp.use(
 		'*',
@@ -203,7 +204,7 @@ export type EmbeddedAppConfig = {
 };
 
 export function createEmbeddedApp(config: EmbeddedAppConfig = {}) {
-	const honoApp = new Hono();
+	const honoApp = new OpenAPIHono<BlankEnv>();
 
 	// Store injected config in Hono context for routes to access
 	// Config can be empty - routes will fall back to files/env

package/src/openapi/register.ts

@@ -0,0 +1,92 @@
+import type { OpenAPIHono, RouteConfig } from '@hono/zod-openapi';
+import { z } from '@hono/zod-openapi';
+import type {
+	MediaTypeObject,
+	OperationObject,
+	ReferenceObject,
+	RequestBodyObject,
+	ResponseObject,
+} from 'openapi3-ts/oas30';
+import { schemas } from './schemas';
+
+export type HttpMethod = RouteConfig['method'];
+
+function isReferenceObject(value: unknown): value is ReferenceObject {
+	return Boolean(
+		value &&
+			typeof value === 'object' &&
+			'$ref' in value &&
+			typeof (value as { $ref?: unknown }).$ref === 'string',
+	);
+}
+
+function schemaToZod(schema: unknown) {
+	if (!schema || isReferenceObject(schema)) {
+		return z.any().openapi(schema as Record<string, unknown>);
+	}
+	return z.any().openapi(schema as Record<string, unknown>);
+}
+
+function convertContent(content: ResponseObject['content']) {
+	if (!content) return undefined;
+	return Object.fromEntries(
+		Object.entries(content).map(([contentType, mediaType]) => [
+			contentType,
+			{
+				...(mediaType as MediaTypeObject),
+				schema: schemaToZod((mediaType as MediaTypeObject).schema),
+			},
+		]),
+	);
+}
+
+function convertRequestBody(
+	requestBody: OperationObject['requestBody'],
+): RouteConfig['request'] extends { body?: infer Body } ? Body : never {
+	if (!requestBody || isReferenceObject(requestBody))
+		return requestBody as never;
+	const body = requestBody as RequestBodyObject;
+	return {
+		...body,
+		content: convertContent(body.content) ?? {},
+	} as never;
+}
+
+function convertResponses(
+	operation: OperationObject,
+): RouteConfig['responses'] {
+	return Object.fromEntries(
+		Object.entries(operation.responses ?? {}).map(([status, response]) => {
+			if (isReferenceObject(response)) return [status, response];
+			return [
+				status,
+				{
+					...(response as ResponseObject),
+					content: convertContent((response as ResponseObject).content),
+				},
+			];
+		}),
+	) as RouteConfig['responses'];
+}
+
+export function buildRouteConfig(
+	method: HttpMethod,
+	path: string,
+	operation: OperationObject,
+): RouteConfig {
+	return {
+		...operation,
+		method,
+		path,
+		request: {
+			body: convertRequestBody(operation.requestBody),
+		},
+		responses: convertResponses(operation),
+	} as RouteConfig;
+}
+
+export function registerOpenApiComponents(app: OpenAPIHono) {
+	for (const [name, schema] of Object.entries(schemas)) {
+		app.openAPIRegistry.registerComponent('schemas', name, schema as never);
+	}
+}

package/src/openapi/route.ts

@@ -0,0 +1,22 @@
+import { createRoute, type OpenAPIHono } from '@hono/zod-openapi';
+import type { Handler, Hono } from 'hono';
+import type { OperationObject } from 'openapi3-ts/oas30';
+import { buildRouteConfig, type HttpMethod } from './register.ts';
+
+type InlineRouteConfig = OperationObject & {
+	method: HttpMethod;
+	path: string;
+};
+
+export function openApiRoute(
+	app: Hono,
+	route: InlineRouteConfig,
+	handler: Handler,
+) {
+	const openApiApp = app as OpenAPIHono;
+	const { method, path, ...operation } = route;
+	return openApiApp.openapi(
+		createRoute(buildRouteConfig(method, path, operation)),
+		handler as never,
+	);
+}

package/src/routes/ask.ts

@@ -8,116 +8,227 @@ import { handleAskRequest } from '../runtime/ask/service.ts';
 import { serializeError } from '../runtime/errors/api-error.ts';
 import { logger } from '@ottocode/sdk';
 import type { EmbeddedAppConfig } from '../index.ts';
+import { openApiRoute } from '../openapi/route.ts';
 
 export function registerAskRoutes(app: Hono) {
-	app.post('/v1/ask', async (c) => {
-		const projectRoot = c.req.query('project') || process.cwd();
-		const body = (await c.req.json().catch(() => ({}))) as Record<
-			string,
-			unknown
-		>;
-		const prompt = typeof body.prompt === 'string' ? body.prompt : '';
-		if (!prompt.trim().length) {
-			return c.json({ error: 'Prompt is required.' }, 400);
-		}
-
-		const embeddedConfig = (
-			c as unknown as {
-				get: (key: 'embeddedConfig') => EmbeddedAppConfig | undefined;
+	openApiRoute(
+		app,
+		{
+			method: 'post',
+			path: '/v1/ask',
+			tags: ['ask'],
+			operationId: 'ask',
+			summary: 'Send a prompt using the ask service',
+			description:
+				'Streamlined endpoint used by the CLI to send prompts and receive assistant responses. Creates sessions as needed and reuses the last session when requested.',
+			parameters: [
+				{
+					in: 'query',
+					name: 'project',
+					required: false,
+					schema: {
+						type: 'string',
+					},
+					description:
+						'Project root override (defaults to current working directory).',
+				},
+			],
+			requestBody: {
+				required: true,
+				content: {
+					'application/json': {
+						schema: {
+							type: 'object',
+							required: ['prompt'],
+							properties: {
+								prompt: {
+									type: 'string',
+									description: 'User prompt to send to the assistant.',
+								},
+								agent: {
+									type: 'string',
+									description: 'Optional agent name to use for this request.',
+								},
+								provider: {
+									$ref: '#/components/schemas/Provider',
+									description:
+										'Optional provider override. When omitted the agent and config defaults apply.',
+								},
+								model: {
+									type: 'string',
+									description:
+										'Optional model override for the selected provider.',
+								},
+								reasoningText: {
+									type: 'boolean',
+									description:
+										'Enable extended thinking / reasoning for models that support it.',
+								},
+								reasoningLevel: {
+									type: 'string',
+									enum: ['minimal', 'low', 'medium', 'high', 'max', 'xhigh'],
+									description:
+										'Optional reasoning intensity override for supported providers/models.',
+								},
+								sessionId: {
+									type: 'string',
+									description: 'Send the prompt to a specific session.',
+								},
+								last: {
+									type: 'boolean',
+									description:
+										'If true, reuse the most recent session for the project.',
+								},
+								jsonMode: {
+									type: 'boolean',
+									description:
+										'Request structured JSON output when supported by the agent.',
+								},
+							},
+						},
+					},
+				},
+			},
+			responses: {
+				'202': {
+					description: 'Accepted',
+					content: {
+						'application/json': {
+							schema: {
+								$ref: '#/components/schemas/AskResponse',
+							},
+						},
+					},
+				},
+				'400': {
+					description: 'Bad Request',
+					content: {
+						'application/json': {
+							schema: {
+								type: 'object',
+								properties: {
+									error: {
+										type: 'string',
+									},
+								},
+								required: ['error'],
+							},
+						},
+					},
+				},
+			},
+		},
+		async (c) => {
+			const projectRoot = c.req.query('project') || process.cwd();
+			const body = (await c.req.json().catch(() => ({}))) as Record<
+				string,
+				unknown
+			>;
+			const prompt = typeof body.prompt === 'string' ? body.prompt : '';
+			if (!prompt.trim().length) {
+				return c.json({ error: 'Prompt is required.' }, 400);
 			}
-		).get('embeddedConfig');
 
-		// Hybrid fallback: Use embedded config if provided, otherwise fall back to files/env
-		let injectableConfig: InjectableConfig | undefined;
-		let injectableCredentials: InjectableCredentials | undefined;
-		let skipFileConfig = false;
+			const embeddedConfig = (
+				c as unknown as {
+					get: (key: 'embeddedConfig') => EmbeddedAppConfig | undefined;
+				}
+			).get('embeddedConfig');
 
-		if (embeddedConfig && Object.keys(embeddedConfig).length > 0) {
-			// Has embedded config - build injectable config from it
-			const defaults = embeddedConfig.defaults;
-			const hasDefaults =
-				defaults ||
-				embeddedConfig.provider ||
-				embeddedConfig.model ||
-				embeddedConfig.agent;
+			// Hybrid fallback: Use embedded config if provided, otherwise fall back to files/env
+			let injectableConfig: InjectableConfig | undefined;
+			let injectableCredentials: InjectableCredentials | undefined;
+			let skipFileConfig = false;
 
-			if (hasDefaults) {
-				injectableConfig = {
-					provider: defaults?.provider ?? embeddedConfig.provider,
-					model: defaults?.model ?? embeddedConfig.model,
-					agent: defaults?.agent ?? embeddedConfig.agent,
-				};
-			}
+			if (embeddedConfig && Object.keys(embeddedConfig).length > 0) {
+				// Has embedded config - build injectable config from it
+				const defaults = embeddedConfig.defaults;
+				const hasDefaults =
+					defaults ||
+					embeddedConfig.provider ||
+					embeddedConfig.model ||
+					embeddedConfig.agent;
 
-			// Convert embedded auth to injectable credentials
-			const hasAuth = embeddedConfig.auth || embeddedConfig.apiKey;
-			if (hasAuth) {
-				if (embeddedConfig.auth) {
-					injectableCredentials = {} as InjectableCredentials;
-					for (const [provider, auth] of Object.entries(embeddedConfig.auth)) {
-						if ('apiKey' in auth) {
-							(injectableCredentials as Record<string, { apiKey: string }>)[
-								provider
-							] = { apiKey: auth.apiKey };
-						}
-					}
-				} else if (embeddedConfig.apiKey && embeddedConfig.provider) {
-					injectableCredentials = {
-						[embeddedConfig.provider]: { apiKey: embeddedConfig.apiKey },
+				if (hasDefaults) {
+					injectableConfig = {
+						provider: defaults?.provider ?? embeddedConfig.provider,
+						model: defaults?.model ?? embeddedConfig.model,
+						agent: defaults?.agent ?? embeddedConfig.agent,
 					};
 				}
 
-				// Only skip file config if we have credentials injected
-				skipFileConfig = true;
+				// Convert embedded auth to injectable credentials
+				const hasAuth = embeddedConfig.auth || embeddedConfig.apiKey;
+				if (hasAuth) {
+					if (embeddedConfig.auth) {
+						injectableCredentials = {} as InjectableCredentials;
+						for (const [provider, auth] of Object.entries(
+							embeddedConfig.auth,
+						)) {
+							if ('apiKey' in auth) {
+								(injectableCredentials as Record<string, { apiKey: string }>)[
+									provider
+								] = { apiKey: auth.apiKey };
+							}
+						}
+					} else if (embeddedConfig.apiKey && embeddedConfig.provider) {
+						injectableCredentials = {
+							[embeddedConfig.provider]: { apiKey: embeddedConfig.apiKey },
+						};
+					}
+
+					// Only skip file config if we have credentials injected
+					skipFileConfig = true;
+				}
+				// If no auth provided, skipFileConfig stays false -> will use ensureProviderEnv -> auth.json fallback
 			}
-			// If no auth provided, skipFileConfig stays false -> will use ensureProviderEnv -> auth.json fallback
-		}
 
-		const request: AskServerRequest = {
-			projectRoot,
-			prompt,
-			agent: typeof body.agent === 'string' ? body.agent : undefined,
-			provider: typeof body.provider === 'string' ? body.provider : undefined,
-			model: typeof body.model === 'string' ? body.model : undefined,
-			reasoningText:
-				typeof body.reasoningText === 'boolean'
-					? body.reasoningText
-					: undefined,
-			reasoningLevel:
-				typeof body.reasoningLevel === 'string'
-					? (body.reasoningLevel as AskServerRequest['reasoningLevel'])
-					: undefined,
-			sessionId:
-				typeof body.sessionId === 'string' ? body.sessionId : undefined,
-			last: Boolean(body.last),
-			jsonMode: Boolean(body.jsonMode),
-			skipFileConfig:
-				skipFileConfig ||
-				(typeof body.skipFileConfig === 'boolean'
-					? body.skipFileConfig
-					: false),
-			config:
-				injectableConfig ||
-				(body.config && typeof body.config === 'object'
-					? (body.config as InjectableConfig)
-					: undefined),
-			credentials:
-				injectableCredentials ||
-				(body.credentials && typeof body.credentials === 'object'
-					? (body.credentials as InjectableCredentials)
-					: undefined),
-			agentPrompt:
-				typeof body.agentPrompt === 'string' ? body.agentPrompt : undefined,
-			tools: Array.isArray(body.tools) ? body.tools : undefined,
-		};
+			const request: AskServerRequest = {
+				projectRoot,
+				prompt,
+				agent: typeof body.agent === 'string' ? body.agent : undefined,
+				provider: typeof body.provider === 'string' ? body.provider : undefined,
+				model: typeof body.model === 'string' ? body.model : undefined,
+				reasoningText:
+					typeof body.reasoningText === 'boolean'
+						? body.reasoningText
+						: undefined,
+				reasoningLevel:
+					typeof body.reasoningLevel === 'string'
+						? (body.reasoningLevel as AskServerRequest['reasoningLevel'])
+						: undefined,
+				sessionId:
+					typeof body.sessionId === 'string' ? body.sessionId : undefined,
+				last: Boolean(body.last),
+				jsonMode: Boolean(body.jsonMode),
+				skipFileConfig:
+					skipFileConfig ||
+					(typeof body.skipFileConfig === 'boolean'
+						? body.skipFileConfig
+						: false),
+				config:
+					injectableConfig ||
+					(body.config && typeof body.config === 'object'
+						? (body.config as InjectableConfig)
+						: undefined),
+				credentials:
+					injectableCredentials ||
+					(body.credentials && typeof body.credentials === 'object'
+						? (body.credentials as InjectableCredentials)
+						: undefined),
+				agentPrompt:
+					typeof body.agentPrompt === 'string' ? body.agentPrompt : undefined,
+				tools: Array.isArray(body.tools) ? body.tools : undefined,
+			};
 
-		try {
-			const response = await handleAskRequest(request);
-			return c.json(response, 202);
-		} catch (err) {
-			logger.error('Ask request failed', err);
-			const errorResponse = serializeError(err);
-			return c.json(errorResponse, errorResponse.error.status || 400);
-		}
-	});
+			try {
+				const response = await handleAskRequest(request);
+				return c.json(response, 202);
+			} catch (err) {
+				logger.error('Ask request failed', err);
+				const errorResponse = serializeError(err);
+				return c.json(errorResponse, errorResponse.error.status || 400);
+			}
+		},
+	);
 }