Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions docs/design/2026-09-01-standalone-initial-model-options.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Standalone Initial Model Options

## Problem

Web Shell defers standalone session creation until the first prompt. During that pending state the session provider intentionally clears session-scoped model data, so a fresh standalone page renders an empty model picker. Once the first session is created, the attached session supplies the model list and the picker starts working.

The initial selection also cannot be treated as a post-create preference. Standalone creation already accepts `modelServiceId`; applying the selection with a later best-effort `setModel` can silently run the first prompt with the daemon default when the switch fails.

## Design

The daemon exposes a capability-gated, read-only `GET /standalone/session-options` route. The route is owned by the internal Conversations runtime used for standalone sessions. It acquires that exact runtime, participates in its activity lease, verifies the internal root and runtime generation, and reads the runtime's provider status. The response omits the internal workspace path and ACP-channel state.

The TypeScript SDK validates the response at runtime and exposes it only when `standalone_session_options_v1` is advertised. Older daemons therefore keep their existing behavior without receiving an unsupported request.

While Web Shell is connected in a pending standalone context, the session provider reads the standalone options and maps them into the existing `models`, `currentModel`, `currentMode`, and `contextWindow` connection fields. This reuses the existing model picker and reasoning controls without introducing a second application-level model state machine. A failed or unsupported catalog read leaves those fields empty and does not block the first prompt.

When the first standalone prompt creates a session, Web Shell passes the selected `modelServiceId` in the create request and skips the post-attach model switch. A selected reasoning effort is still applied after attach because it is session configuration, but it is not persisted into the internal Conversations workspace settings. Workspace session creation remains unchanged.

## Boundaries

- The route never accepts `cwd` or `workspaceCwd` and never falls back to the primary workspace.
- Reading options must not create a standalone session or a per-session directory.
- The response must not expose the internal Conversations workspace path.
- Runtime replacement, quarantine, or generation changes fail closed.
- A missing capability or failed options request does not block prompt submission; the daemon default is used when no model is selected.
- Standalone create keeps its existing stable UUID, outcome-unknown recovery, and no-automatic-retry behavior.
- Workspace, Live, Recents, lifecycle menus, uploads, and daemon lifecycle behavior are out of scope.

## Verification

Unit tests cover runtime ownership and redaction, route behavior, capability advertisement, SDK validation, deferred Web Shell hydration, stale/failing option reads, and atomic standalone creation. Browser E2E verifies that a fresh standalone page shows models before creating a session, opening the picker does not create a session, and the selected model is sent in the first standalone create request.
5 changes: 5 additions & 0 deletions packages/cli/src/serve/capabilities.ts
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,7 @@ export const SERVE_CAPABILITY_REGISTRY = {
session_organization: { since: 'v1' },
session_export: { since: 'v1' },
standalone_sessions_v1: { since: 'v1' },
standalone_session_options_v1: { since: 'v1' },
session_transcript: { since: 'v1' },
session_transcript_pagination: { since: 'v1' },
// Daemon supports the MCP client guardrail surface: an in-process
Expand Down Expand Up @@ -579,6 +580,10 @@ export const CONDITIONAL_SERVE_FEATURES: ReadonlyMap<
'standalone_sessions_v1',
(toggles) => toggles.standaloneSessionsAvailable === true,
],
[
'standalone_session_options_v1',
(toggles) => toggles.standaloneSessionsAvailable === true,
],
['mcp_workspace_pool', (toggles) => toggles.mcpPoolActive === true],
['mcp_pool_restart', (toggles) => toggles.mcpPoolActive === true],
[
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,8 @@ interface Harness {
restoreStagedStandaloneDirectory: ReturnType<typeof vi.fn>;
removeStagedStandaloneDirectory: ReturnType<typeof vi.fn>;
confirmStandaloneRootDurability: ReturnType<typeof vi.fn>;
getWorkspaceProvidersStatus: ReturnType<typeof vi.fn>;
assertExactRoot: ReturnType<typeof vi.fn>;
}

function createHarness(): Harness {
Expand Down Expand Up @@ -168,6 +170,15 @@ function createHarness(): Harness {
deleteSessionAttachments: vi.fn(async () => undefined),
markSessionCatalogChanged: vi.fn(),
};
const getWorkspaceProvidersStatus = vi.fn(async () => ({
v: 1 as const,
workspaceCwd: root.canonicalRoot,
initialized: true,
acpChannelLive: false,
current: { authType: 'openai', modelId: 'qwen-test' },
approvalMode: 'default' as const,
providers: [],
}));
const runtime = {
workspaceId: 'conversations',
workspaceCwd: root.canonicalRoot,
Expand All @@ -177,7 +188,8 @@ function createHarness(): Harness {
trusted: true,
removable: false,
bridge: bridge as unknown as AcpSessionBridge,
} as WorkspaceRuntime;
workspaceService: { getWorkspaceProvidersStatus },
} as unknown as WorkspaceRuntime;
const reservation = { release: vi.fn() };
const restoreReservation = { release: vi.fn() };
let runtimeQuarantined = false;
Expand Down Expand Up @@ -216,6 +228,7 @@ function createHarness(): Harness {
const restoreStagedStandaloneDirectory = vi.fn(async () => identity);
const removeStagedStandaloneDirectory = vi.fn(async () => undefined);
const confirmStandaloneRootDurability = vi.fn(async () => undefined);
const assertExactRoot = vi.fn(async () => root);
const lifecycle = new SessionArchiveCoordinator();
const options: StandaloneSessionServiceOptions = {
ensureRuntime,
Expand All @@ -229,7 +242,7 @@ function createHarness(): Harness {
quarantineRuntime,
runRuntimeActivity: async (_runtime, operation) => operation(),
workspace: {
assertExactRoot: vi.fn(async () => root),
assertExactRoot,
prepareStandaloneDirectory: vi.fn(async () => ({
identity,
created: true,
Expand Down Expand Up @@ -272,6 +285,8 @@ function createHarness(): Harness {
restoreStagedStandaloneDirectory,
removeStagedStandaloneDirectory,
confirmStandaloneRootDurability,
getWorkspaceProvidersStatus,
assertExactRoot,
};
}

Expand Down Expand Up @@ -431,6 +446,44 @@ afterEach(() => {
});

describe('StandaloneSessionService', () => {
it('reads options from the exact runtime without exposing its cwd', async () => {
const harness = createHarness();

const options = await harness.service.getOptions();

expect(harness.ensureRuntime).toHaveBeenCalledOnce();
expect(harness.assertExactRoot).toHaveBeenCalledWith(root.canonicalRoot);
expect(harness.getWorkspaceProvidersStatus).toHaveBeenCalledWith({
route: 'GET /standalone/session-options',
workspaceCwd: root.canonicalRoot,
});
expect(options).toEqual({
v: 1,
initialized: true,
current: { authType: 'openai', modelId: 'qwen-test' },
approvalMode: 'default',
providers: [],
});
expect(options).not.toHaveProperty('workspaceCwd');
expect(options).not.toHaveProperty('acpChannelLive');
expect(harness.bridge.spawnStandaloneSession).not.toHaveBeenCalled();
});

it('fails closed when provider status belongs to another runtime', async () => {
const harness = createHarness();
harness.getWorkspaceProvidersStatus.mockResolvedValueOnce({
v: 1,
workspaceCwd: '/other',
initialized: true,
providers: [],
});

await expect(harness.service.getOptions()).rejects.toMatchObject({
code: 'conversation_runtime_ownership_compromised',
retryable: false,
});
});

it('creates a durable standalone session without admitting a prompt', async () => {
mockDurableStandalone();
const harness = createHarness();
Expand Down
38 changes: 38 additions & 0 deletions packages/cli/src/serve/conversations/standalone-session-service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ import type {
BridgeSessionSummary,
BridgeStandaloneRestoreSessionRequest,
} from '@qwen-code/acp-bridge/bridgeTypes';
import type { ServeWorkspaceProvidersStatus } from '@qwen-code/acp-bridge/status';
import { STANDALONE_SESSION_SOURCE_TYPE } from '@qwen-code/acp-bridge/sessionSource';
import {
readSessionPrs,
Expand Down Expand Up @@ -118,6 +119,11 @@ export interface CreatedStandaloneSession {
workingDirectory: { state: 'ready' };
}

export type StandaloneSessionOptions = Omit<
ServeWorkspaceProvidersStatus,
'workspaceCwd' | 'acpChannelLive'
>;

export interface StandaloneSessionDirectoryResult {
sessionId: string;
projectlessOutputDirectory: string;
Expand Down Expand Up @@ -483,6 +489,38 @@ export class StandaloneSessionService {

constructor(private readonly options: StandaloneSessionServiceOptions) {}

async getOptions(): Promise<StandaloneSessionOptions> {
const runtime = await this.options.ensureRuntime();
return this.options.runRuntimeActivity(runtime, async () => {
Comment thread
doudouOUC marked this conversation as resolved.
Resolved
Comment thread
doudouOUC marked this conversation as resolved.
Resolved
Comment thread
doudouOUC marked this conversation as resolved.
Resolved
this.options.assertRuntimeCurrent(runtime);
await this.options.workspace.assertExactRoot(runtime.workspaceCwd);
this.options.assertRuntimeCurrent(runtime);
const status = await runtime.workspaceService.getWorkspaceProvidersStatus(
{
route: 'GET /standalone/session-options',
workspaceCwd: runtime.workspaceCwd,
},
);
this.options.assertRuntimeCurrent(runtime);
if (status.workspaceCwd !== runtime.workspaceCwd) {
throw new ConversationRuntimeOwnershipError(
'conversation_runtime_ownership_compromised',
false,
);
}
return {
v: status.v,
initialized: status.initialized,
...(status.current !== undefined ? { current: status.current } : {}),
...(status.approvalMode !== undefined
? { approvalMode: status.approvalMode }
: {}),
providers: status.providers,
...(status.errors !== undefined ? { errors: status.errors } : {}),
};
});
}

freezeForTerminalQuarantine(runtime: WorkspaceRuntime): void {
this.terminal = true;
for (const entry of this.creating.values()) {
Expand Down
29 changes: 29 additions & 0 deletions packages/cli/src/serve/routes/standalone-sessions.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,13 @@ function createHarness({
isWorkspaceTrusted?: () => boolean;
} = {}) {
const service = {
getOptions: vi.fn(async () => ({
v: 1 as const,
initialized: true,
current: { authType: 'openai', modelId: 'qwen-test' },
approvalMode: 'default' as const,
providers: [],
})),
create: vi.fn(async () => ({
session: {
sessionId,
Expand Down Expand Up @@ -102,6 +109,28 @@ function createHarness({
describe('standalone session routes', () => {
beforeEach(() => vi.restoreAllMocks());

it('returns session options without accepting workspace inputs', async () => {
const { app, service } = createHarness();

const response = await request(app).get('/standalone/session-options');

expect(response.status).toBe(200);
expect(response.body).toEqual({
v: 1,
initialized: true,
current: { authType: 'openai', modelId: 'qwen-test' },
approvalMode: 'default',
providers: [],
});
expect(service.getOptions).toHaveBeenCalledOnce();

const invalid = await request(app).get(
'/standalone/session-options?cwd=/tmp',
);
expect(invalid.status).toBe(400);
expect(service.getOptions).toHaveBeenCalledOnce();
});

it('creates a prompt-less standalone session without workspace inputs', async () => {
const { app, service } = createHarness();

Expand Down
10 changes: 10 additions & 0 deletions packages/cli/src/serve/routes/standalone-sessions.ts
Original file line number Diff line number Diff line change
Expand Up @@ -266,6 +266,16 @@ export function registerStandaloneSessionRoutes(
}
};

app.get('/standalone/session-options', (req, res) =>
handle('GET /standalone/session-options', req, res, async () => {
if (Object.keys(req.query).length > 0) {
sendInvalidRequest(res, 'The request query contains unknown fields.');
return;
}
res.status(200).json(await deps.service.getOptions());
}),
);

app.post('/standalone/sessions', deps.mutate({ strict: true }), (req, res) =>
handle('POST /standalone/sessions', req, res, async () => {
const body = requireExactBody(req, res, [
Expand Down
17 changes: 15 additions & 2 deletions packages/cli/src/serve/server.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -712,7 +712,11 @@ const EXPECTED_REGISTERED_FEATURES = [
return [feature, 'scheduled_task_session_reuse'];
}
if (feature === 'session_export') {
return [feature, 'standalone_sessions_v1'];
return [
feature,
'standalone_sessions_v1',
'standalone_session_options_v1',
];
}
return [feature];
}).filter(
Expand Down Expand Up @@ -2939,7 +2943,10 @@ describe('createServeApp', () => {
);
continue;
}
if (feature === 'standalone_sessions_v1') {
if (
feature === 'standalone_sessions_v1' ||
feature === 'standalone_session_options_v1'
) {
expect(predicate({ standaloneSessionsAvailable: true })).toBe(true);
expect(predicate({ standaloneSessionsAvailable: false })).toBe(false);
expect(predicate({})).toBe(false);
Expand Down Expand Up @@ -36955,6 +36962,9 @@ describe('Live conversation runtime lifecycle', () => {
expect(partialCapabilities.body.features).not.toContain(
'standalone_sessions_v1',
);
expect(partialCapabilities.body.features).not.toContain(
'standalone_session_options_v1',
);

const complete = setupLiveRuntime();
const completeRoute = await supertest(complete.app)
Expand All @@ -36968,6 +36978,9 @@ describe('Live conversation runtime lifecycle', () => {
expect(completeCapabilities.body.features).toContain(
'standalone_sessions_v1',
);
expect(completeCapabilities.body.features).toContain(
'standalone_session_options_v1',
);
});

it('blocks REST close and archive for active Live sessions until the call stops', async () => {
Expand Down
14 changes: 14 additions & 0 deletions packages/sdk-typescript/src/daemon/DaemonClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -241,6 +241,7 @@ import type {
import { parseSseStream } from './sse.js';
import {
DaemonStandaloneCreationOutcomeUnknownError,
STANDALONE_SESSION_OPTIONS_CAPABILITY,
STANDALONE_SESSIONS_CAPABILITY,
isStandaloneCreationOutcomeUnknown,
isStandaloneSessionNotFoundError,
Expand All @@ -252,6 +253,7 @@ import {
parseStandaloneLookup,
parseStandaloneMetadataResult,
parseStandaloneSession,
parseStandaloneSessionOptions,
parseUnarchiveStandaloneSessionsResult,
type CreateStandaloneSessionOptions,
type DaemonArchiveStandaloneSessionsResult,
Expand All @@ -261,6 +263,7 @@ import {
type DaemonStandaloneDirectoryResult,
type DaemonStandaloneMetadataResult,
type DaemonStandaloneSession,
type DaemonStandaloneSessionOptions,
type DaemonStandaloneSessionListOptions,
type DaemonStandaloneSessionListPage,
type DaemonStandaloneSessionLookup,
Expand Down Expand Up @@ -2643,6 +2646,17 @@ export class DaemonClient {

// -- Sessions ----------------------------------------------------------

async getStandaloneSessionOptions(): Promise<DaemonStandaloneSessionOptions> {
await this.requireCapability(STANDALONE_SESSION_OPTIONS_CAPABILITY);
const route = 'GET /standalone/session-options';
const response = await this.jsonRequest<unknown>(
'/standalone/session-options',
route,
{ mode: 'rest' },
);
return parseStandaloneSessionOptions(response, route);
}

async createStandaloneSession(
options: CreateStandaloneSessionOptions = {},
): Promise<DaemonStandaloneSession> {
Expand Down
2 changes: 2 additions & 0 deletions packages/sdk-typescript/src/daemon/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ export {
export {
DaemonStandaloneCreationOutcomeUnknownError,
DaemonStandaloneProtocolError,
STANDALONE_SESSION_OPTIONS_CAPABILITY,
STANDALONE_SESSIONS_CAPABILITY,
isStandaloneCreationOutcomeUnknown,
isStandaloneSessionNotFoundError,
Expand All @@ -80,6 +81,7 @@ export {
type DaemonStandaloneFields,
type DaemonStandaloneMetadataResult,
type DaemonStandaloneSession,
type DaemonStandaloneSessionOptions,
type DaemonStandaloneSessionCreating,
type DaemonStandaloneSessionListOptions,
type DaemonStandaloneSessionListPage,
Expand Down
Loading
Loading