@ottocode/server 0.1.267 → 0.1.268

package/package.json

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

package/src/events/bus.ts

@@ -1,8 +1,10 @@
-import type { OttoEvent } from './types.ts';
+import type { ClientEvent, NotificationEvent, OttoEvent } from './types.ts';
 
 type Subscriber = (evt: OttoEvent) => void;
+type ClientSubscriber = (evt: ClientEvent) => void;
 
 const subscribers = new Map<string, Set<Subscriber>>(); // sessionId -> subs
+const clientSubscribers = new Set<ClientSubscriber>();
 
 function sanitizeBigInt<T>(obj: T): T {
 	if (obj === null || obj === undefined) return obj;
@@ -34,6 +36,24 @@ export function publish(event: OttoEvent) {
 	}
 }
 
+export function publishClientEvent(event: ClientEvent) {
+	const sanitizedEvent = sanitizeBigInt(event);
+	for (const sub of clientSubscribers) {
+		try {
+			sub(sanitizedEvent);
+		} catch (err) {
+			console.error(
+				`[bus] Client subscriber threw on event ${event.type}:`,
+				err instanceof Error ? err.message : String(err),
+			);
+		}
+	}
+}
+
+export function publishNotification(payload: NotificationEvent) {
+	publishClientEvent({ type: 'notification', payload });
+}
+
 export function subscribe(sessionId: string, handler: Subscriber) {
 	let set = subscribers.get(sessionId);
 	if (!set) {
@@ -46,3 +66,10 @@ export function subscribe(sessionId: string, handler: Subscriber) {
 		if (set && set.size === 0) subscribers.delete(sessionId);
 	};
 }
+
+export function subscribeClientEvents(handler: ClientSubscriber) {
+	clientSubscribers.add(handler);
+	return () => {
+		clientSubscribers.delete(handler);
+	};
+}

package/src/events/types.ts

@@ -34,3 +34,34 @@ export interface OttoEvent<T = unknown> {
 	sessionId: string;
 	payload?: T;
 }
+
+export type NotificationLevel = 'info' | 'success' | 'warning' | 'error';
+
+export interface NotificationAction {
+	label: string;
+	href: string;
+}
+
+export interface NotificationEvent {
+	id: string;
+	level: NotificationLevel;
+	title: string;
+	body?: string;
+	action?: NotificationAction;
+	createdAt: string;
+	expiresAt?: string;
+	source?: 'agent' | 'system' | 'session' | 'auth' | 'billing';
+	sessionId?: string;
+}
+
+export interface SessionStatusEvent {
+	sessionId: string;
+	status: 'running' | 'completed' | 'failed' | 'needs_attention';
+	messageId?: string;
+	createdAt: string;
+}
+
+export type ClientEvent =
+	| { type: 'notification'; payload: NotificationEvent }
+	| { type: 'session.status'; payload: SessionStatusEvent }
+	| { type: 'heartbeat'; payload: { createdAt: string } };

package/src/index.ts

@@ -9,6 +9,7 @@ import { registerOpenApiRoute } from './routes/openapi.ts';
 import { registerSessionsRoutes } from './routes/sessions.ts';
 import { registerSessionMessagesRoutes } from './routes/session-messages.ts';
 import { registerSessionStreamRoute } from './routes/session-stream.ts';
+import { registerClientEventsRoute } from './routes/client-events.ts';
 import { registerAskRoutes } from './routes/ask.ts';
 import { registerConfigRoutes } from './routes/config/index.ts';
 import { registerFilesRoutes } from './routes/files.ts';
@@ -34,8 +35,23 @@ setTerminalManager(globalTerminalManager);
 // Suppress noisy AI SDK provider warnings unless debug mode is enabled.
 installAiSdkWarningHandler();
 
+const corsAllowHeaders = [
+	'Content-Type',
+	'Authorization',
+	'X-Requested-With',
+	'Access-Control-Request-Private-Network',
+];
+
+function applyPrivateNetworkAccessHeaders(app: OpenAPIHono<BlankEnv>) {
+	app.use('*', async (c, next) => {
+		c.header('Access-Control-Allow-Private-Network', 'true');
+		await next();
+	});
+}
+
 function initApp() {
 	const app = new OpenAPIHono<BlankEnv>();
+	applyPrivateNetworkAccessHeaders(app);
 
 	// Enable CORS for localhost and local network access
 	app.use(
@@ -61,7 +77,7 @@ function initApp() {
 				return origin;
 			},
 			allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
-			allowHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+			allowHeaders: corsAllowHeaders,
 			exposeHeaders: ['Content-Length', 'X-Request-Id'],
 			credentials: true,
 			maxAge: 600,
@@ -74,6 +90,7 @@ function initApp() {
 	registerSessionApprovalRoute(app);
 	registerSessionMessagesRoutes(app);
 	registerSessionStreamRoute(app);
+	registerClientEventsRoute(app);
 	registerAskRoutes(app);
 	registerConfigRoutes(app);
 	registerFilesRoutes(app);
@@ -112,6 +129,7 @@ export type StandaloneAppConfig = {
 
 export function createStandaloneApp(_config?: StandaloneAppConfig) {
 	const honoApp = new OpenAPIHono<BlankEnv>();
+	applyPrivateNetworkAccessHeaders(honoApp);
 
 	honoApp.use(
 		'*',
@@ -136,7 +154,7 @@ export function createStandaloneApp(_config?: StandaloneAppConfig) {
 				return origin;
 			},
 			allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
-			allowHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+			allowHeaders: corsAllowHeaders,
 			exposeHeaders: ['Content-Length', 'X-Request-Id'],
 			credentials: true,
 			maxAge: 600,
@@ -149,6 +167,7 @@ export function createStandaloneApp(_config?: StandaloneAppConfig) {
 	registerSessionApprovalRoute(honoApp);
 	registerSessionMessagesRoutes(honoApp);
 	registerSessionStreamRoute(honoApp);
+	registerClientEventsRoute(honoApp);
 	registerAskRoutes(honoApp);
 	registerConfigRoutes(honoApp);
 	registerFilesRoutes(honoApp);
@@ -205,6 +224,7 @@ export type EmbeddedAppConfig = {
 
 export function createEmbeddedApp(config: EmbeddedAppConfig = {}) {
 	const honoApp = new OpenAPIHono<BlankEnv>();
+	applyPrivateNetworkAccessHeaders(honoApp);
 
 	// Store injected config in Hono context for routes to access
 	// Config can be empty - routes will fall back to files/env
@@ -247,7 +267,7 @@ export function createEmbeddedApp(config: EmbeddedAppConfig = {}) {
 				return origin;
 			},
 			allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
-			allowHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+			allowHeaders: corsAllowHeaders,
 			exposeHeaders: ['Content-Length', 'X-Request-Id'],
 			credentials: true,
 			maxAge: 600,
@@ -260,6 +280,7 @@ export function createEmbeddedApp(config: EmbeddedAppConfig = {}) {
 	registerSessionApprovalRoute(honoApp);
 	registerSessionMessagesRoutes(honoApp);
 	registerSessionStreamRoute(honoApp);
+	registerClientEventsRoute(honoApp);
 	registerAskRoutes(honoApp);
 	registerConfigRoutes(honoApp);
 	registerFilesRoutes(honoApp);

package/src/routes/client-events.ts

@@ -0,0 +1,139 @@
+import type { Context } from 'hono';
+import type { Hono } from 'hono';
+import { subscribeClientEvents } from '../events/bus.ts';
+import type { ClientEvent } from '../events/types.ts';
+import { openApiRoute } from '../openapi/route.ts';
+
+const STREAM_DESCRIPTION =
+	'SSE event stream. Events include notification, session.status, and heartbeat.';
+
+function safeStringify(obj: unknown): string {
+	return JSON.stringify(obj, (_key, value) =>
+		typeof value === 'bigint' ? Number(value) : value,
+	);
+}
+
+function handleClientEventsStream(c: Context) {
+	const headers = new Headers({
+		'Content-Type': 'text/event-stream',
+		'Cache-Control': 'no-cache, no-transform',
+		Connection: 'keep-alive',
+	});
+
+	const encoder = new TextEncoder();
+
+	const stream = new ReadableStream<Uint8Array>({
+		start(controller) {
+			const write = (evt: ClientEvent) => {
+				let line: string;
+				try {
+					line =
+						`event: ${evt.type}\n` +
+						`data: ${safeStringify(evt.payload ?? {})}\n\n`;
+				} catch {
+					line = `event: ${evt.type}\ndata: {}\n\n`;
+				}
+				controller.enqueue(encoder.encode(line));
+			};
+
+			const unsubscribe = subscribeClientEvents(write);
+			controller.enqueue(encoder.encode(': connected client-events\n\n'));
+			const hb = setInterval(() => {
+				try {
+					write({
+						type: 'heartbeat',
+						payload: { createdAt: new Date().toISOString() },
+					});
+				} catch {
+					clearInterval(hb);
+				}
+			}, 5000);
+
+			const signal = c.req.raw?.signal as AbortSignal | undefined;
+			signal?.addEventListener('abort', () => {
+				clearInterval(hb);
+				unsubscribe();
+				try {
+					controller.close();
+				} catch {}
+			});
+		},
+	});
+
+	return new Response(stream, { headers });
+}
+
+export function registerClientEventsRoute(app: Hono) {
+	openApiRoute(
+		app,
+		{
+			method: 'get',
+			path: '/v1/events/stream',
+			operationId: 'subscribeClientEventsStream',
+			tags: ['stream'],
+			summary: 'Subscribe to global client event stream (SSE)',
+			description:
+				'App-level SSE stream for notifications and lightweight cross-session status updates.',
+			parameters: [
+				{
+					in: 'query',
+					name: 'project',
+					required: false,
+					schema: { type: 'string' },
+					description:
+						'Project root override (defaults to current working directory).',
+				},
+			],
+			responses: {
+				'200': {
+					description: 'text/event-stream',
+					content: {
+						'text/event-stream': {
+							schema: {
+								type: 'string',
+								description: STREAM_DESCRIPTION,
+							},
+						},
+					},
+				},
+			},
+		},
+		handleClientEventsStream,
+	);
+	openApiRoute(
+		app,
+		{
+			method: 'post',
+			path: '/v1/events/stream',
+			operationId: 'subscribeClientEventsStreamPost',
+			tags: ['stream'],
+			summary: 'Subscribe to global client event stream (SSE) using POST',
+			description:
+				'Compatibility alias for app-level SSE over tunnels/proxies that do not support GET streams.',
+			parameters: [
+				{
+					in: 'query',
+					name: 'project',
+					required: false,
+					schema: { type: 'string' },
+					description:
+						'Project root override (defaults to current working directory).',
+				},
+			],
+			responses: {
+				'200': {
+					description: 'text/event-stream',
+					content: {
+						'text/event-stream': {
+							schema: {
+								type: 'string',
+								description: STREAM_DESCRIPTION,
+							},
+						},
+					},
+				},
+			},
+		},
+		handleClientEventsStream,
+	);
+}

package/src/runtime/session/queue.ts

@@ -1,5 +1,5 @@
 import type { ProviderName } from '../provider/index.ts';
-import { publish } from '../../events/bus.ts';
+import { publish, publishClientEvent } from '../../events/bus.ts';
 import type { ToolApprovalMode } from '../tools/approval.ts';
 import type { ReasoningLevel } from '@ottocode/sdk';
 
@@ -234,6 +234,17 @@ export function setCurrentMessage(sessionId: string, messageId: string | null) {
 	if (state) {
 		state.currentMessageId = messageId;
 		publishQueueState(sessionId);
+		if (messageId) {
+			publishClientEvent({
+				type: 'session.status',
+				payload: {
+					sessionId,
+					status: 'running',
+					messageId,
+					createdAt: new Date().toISOString(),
+				},
+			});
+		}
 	}
 }
 
@@ -243,6 +254,15 @@ export function dequeueJob(sessionId: string): RunOpts | undefined {
 	if (job && state) {
 		state.currentMessageId = job.assistantMessageId;
 		publishQueueState(sessionId);
+		publishClientEvent({
+			type: 'session.status',
+			payload: {
+				sessionId,
+				status: 'running',
+				messageId: job.assistantMessageId,
+				createdAt: new Date().toISOString(),
+			},
+		});
 	}
 	return job;
 }

package/src/runtime/stream/error-handler.ts

@@ -2,7 +2,7 @@ import type { getDb } from '@ottocode/database';
 import { messages, messageParts } from '@ottocode/database/schema';
 import { eq } from 'drizzle-orm';
 import { APICallError } from 'ai';
-import { publish } from '../../events/bus.ts';
+import { publish, publishClientEvent } from '../../events/bus.ts';
 import { toErrorPayload } from '../errors/handling.ts';
 import type { RunOpts } from '../session/queue.ts';
 import type { ToolAdapterContext } from '../../tools/adapter.ts';
@@ -349,5 +349,28 @@ export function createErrorHandler(
 				autoCompacted: isPromptTooLong && !opts.isCompactCommand,
 			},
 		});
+
+		const createdAt = new Date().toISOString();
+		publishClientEvent({
+			type: 'session.status',
+			payload: {
+				sessionId: opts.sessionId,
+				status: 'failed',
+				messageId: opts.assistantMessageId,
+				createdAt,
+			},
+		});
+		publishClientEvent({
+			type: 'notification',
+			payload: {
+				id: crypto.randomUUID(),
+				level: 'error',
+				title: 'Session failed',
+				body: displayMessage,
+				source: 'session',
+				sessionId: opts.sessionId,
+				createdAt,
+			},
+		});
 	};
 }

package/src/runtime/stream/finish-handler.ts

@@ -1,7 +1,7 @@
 import type { getDb } from '@ottocode/database';
 import { messages, messageParts } from '@ottocode/database/schema';
 import { eq } from 'drizzle-orm';
-import { publish } from '../../events/bus.ts';
+import { publish, publishClientEvent } from '../../events/bus.ts';
 import { estimateModelCostUsd } from '@ottocode/sdk';
 import type { RunOpts } from '../session/queue.ts';
 import { markSessionCompacted } from '../message/compaction.ts';
@@ -84,5 +84,32 @@ export function createFinishHandler(
 				finishReason: fin.finishReason,
 			},
 		});
+
+		const createdAt = new Date().toISOString();
+		const status = fin.finishReason === 'error' ? 'failed' : 'completed';
+		publishClientEvent({
+			type: 'session.status',
+			payload: {
+				sessionId: opts.sessionId,
+				status,
+				messageId: opts.assistantMessageId,
+				createdAt,
+			},
+		});
+		publishClientEvent({
+			type: 'notification',
+			payload: {
+				id: crypto.randomUUID(),
+				level: status === 'failed' ? 'error' : 'success',
+				title: status === 'failed' ? 'Session failed' : 'Session completed',
+				body:
+					status === 'failed'
+						? 'An assistant run ended with an error.'
+						: 'An assistant run finished successfully.',
+				source: 'session',
+				sessionId: opts.sessionId,
+				createdAt,
+			},
+		});
 	};
 }