@antelopejs/dms-ai 0.0.5 → 0.1.0

package/README.md

@@ -7,8 +7,9 @@
 </div>
 
 An AntelopeJS DMS development assistant. It adds an owner-only AI workspace to the dashboard and
-runs Claude Code in a local sidecar that can inspect the loaded modules and their declared skills,
-edit the host project, and stream activity back to the dashboard.
+runs a coding agent in a local sidecar that can inspect the loaded modules and their declared skills,
+edit the host project, and stream activity back to the dashboard. Claude Code drives it by default;
+OpenAI's Codex is selectable once its CLI is installed.
 
 ## Installation
 
@@ -22,6 +23,55 @@ The module starts its bundled sidecar with the project as its working directory.
 set `DMS_AI=0` before starting the backend to disable the sidecar. If
 `@antelopejs/dms-builder` is installed, the assistant also exposes its builder integration.
 
+## Agent providers
+
+The assistant runs on either Claude Code or Codex, picked in the AI settings page. Both go through
+the same seam, so the chat, the tool calls, the permission prompts and the file-change animation
+behave the same either way. `GET /settings` reports which ones this install can actually drive:
+
+```json
+{ "provider": "claude", "providers": { "claude": { "available": true }, "codex": { "available": false, "reason": "Install @openai/codex, at the exact version dms-ai pins, to enable this provider." } } }
+```
+
+`claude` is the default *choice*, not a fallback. A provider that this install cannot drive — its
+package uninstalled, its API key gone from the environment — fails the turn with that reason in the
+chat, and the conversation is never quietly handed to the other backend: someone who picked OpenAI
+may have picked it precisely so their code does not reach Anthropic.
+
+Switching provider disposes the live sessions of the previous one — an open conversation loses its
+in-agent context, its transcript is kept.
+
+### Enabling Codex
+
+1. **Install the `codex` CLI.** It is an *optional* peer dependency, so it is never installed for
+   you: the platform packages weigh ~324 MB unpacked, and only the installs that want Codex should
+   pay for them. Use the exact version this module pins, in `peerDependencies["@openai/codex"]`:
+
+   ```bash
+   pnpm add @openai/codex@0.154.0
+   ```
+
+   The app-server protocol is versioned by binary and OpenAI publishes roughly ten versions a
+   month. The sidecar ships protocol types generated from the pinned version and checks
+   `codex --version` against it at spawn, refusing to start on a mismatch rather than speaking a
+   protocol its types do not describe. The refusal names both versions, so an upgrade says what to
+   pin back to. To run a newer binary anyway — at the risk of a protocol its types do not
+   describe — set `DMS_AI_CODEX_ALLOW_VERSION_MISMATCH=1`; the drift is then logged once, at startup, instead of
+   blocking the provider.
+
+2. **Provide an API key.** Export `OPENAI_API_KEY` in the host process environment. The binary does
+   not read that variable itself: the sidecar writes it into an `auth.json` (mode `0600`) inside a
+   `CODEX_HOME` dedicated to the conversation. On Windows that mode is not enforced by the
+   filesystem, so the file is only as private as the directory it sits in. ChatGPT login is not
+   supported here — it shares a token refresh with the user's own `codex` install.
+
+3. **Restart the sidecar**, then pick *OpenAI (Codex)* in the AI settings page.
+
+Linux, macOS and Windows are all supported. One app-server process runs per conversation, and the
+sidecar records its pid so a previous run's orphans are killed at startup — through procfs on
+Linux, `ps` on macOS and `taskkill /T` on Windows, which is also what takes the sandboxed children
+of the app-server with it.
+
 ## Vue frontend
 
 The module registers `frontend-vue` through `AddFrontendModule` with the Vue 3 renderer. The host DMS supplies authentication and shared state.
@@ -33,6 +83,7 @@ Install dependencies and run the backend and sidecar checks from the repository
 ```bash
 pnpm install
 pnpm build
+pnpm build:sidecar
 pnpm test
 ```
 

package/dist/routes/settings.d.ts

@@ -1,9 +1,16 @@
+type ProviderName = "claude" | "codex";
+interface ProviderAvailability {
+    available: boolean;
+    reason?: string;
+}
 interface AiSettings {
+    provider: ProviderName;
     mode: "normal" | "acceptEdits" | "plan" | "auto";
     thinking: "off" | "low" | "medium" | "high";
     generationMode: "safe" | "vibe";
     allowLocalSkills: boolean;
     builderAvailable: boolean;
+    providers: Record<ProviderName, ProviderAvailability>;
 }
 declare const AISettingsController_base: import("@antelopejs/interface-api").ControllerClass<object>;
 export declare class AISettingsController extends AISettingsController_base {

package/dist/routes/settings.js

@@ -18,11 +18,13 @@ const auth_1 = require("@antelopejs/interface-dms/auth");
 const module_1 = require("../constants/module");
 const proxy_1 = require("./proxy");
 const DEFAULT_SETTINGS = {
+    provider: "claude",
     mode: "normal",
     thinking: "medium",
     generationMode: "safe",
     allowLocalSkills: false,
     builderAvailable: false,
+    providers: { claude: { available: true }, codex: { available: false } },
 };
 let AISettingsController = class AISettingsController extends (0, interface_api_1.Controller)(module_1.ROUTE_PREFIX) {
     getSettings() {

package/dist/routes/settings.js.map

@@ -1 +1 @@
-{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/routes/settings.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,6DAA2E;AAC3E,yDAA+D;AAC/D,gDAAmD;AACnD,mCAAiD;AAYjD,MAAM,gBAAgB,GAAe;IACnC,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,QAAQ;IAClB,cAAc,EAAE,MAAM;IACtB,gBAAgB,EAAE,KAAK;IACvB,gBAAgB,EAAE,KAAK;CACxB,CAAC;AAGK,IAAM,oBAAoB,GAA1B,MAAM,oBAAqB,SAAQ,IAAA,0BAAU,EAAC,qBAAY,CAAC;IAEhE,WAAW;QACT,OAAO,IAAA,kBAAU,EAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IACnD,CAAC;IAGD,cAAc,CAAa,IAAa;QACtC,OAAO,IAAA,kBAAU,EAAC,WAAW,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC;IACzD,CAAC;CACF,CAAA;AAVY,oDAAoB;AAE/B;IADC,IAAA,mBAAG,EAAC,WAAW,CAAC;;;;uDAGhB;AAGD;IADC,IAAA,mBAAG,EAAC,WAAW,CAAC;IACD,WAAA,IAAA,wBAAQ,GAAE,CAAA;;;;0DAEzB;+BATU,oBAAoB;IADhC,IAAA,oBAAa,GAAE;GACH,oBAAoB,CAUhC"}
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/routes/settings.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,6DAA2E;AAC3E,yDAA+D;AAC/D,gDAAmD;AACnD,mCAAiD;AAwBjD,MAAM,gBAAgB,GAAe;IACnC,QAAQ,EAAE,QAAQ;IAClB,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,QAAQ;IAClB,cAAc,EAAE,MAAM;IACtB,gBAAgB,EAAE,KAAK;IACvB,gBAAgB,EAAE,KAAK;IACvB,SAAS,EAAE,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE;CACxE,CAAC;AAGK,IAAM,oBAAoB,GAA1B,MAAM,oBAAqB,SAAQ,IAAA,0BAAU,EAAC,qBAAY,CAAC;IAEhE,WAAW;QACT,OAAO,IAAA,kBAAU,EAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IACnD,CAAC;IAGD,cAAc,CAAa,IAAa;QACtC,OAAO,IAAA,kBAAU,EAAC,WAAW,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC;IACzD,CAAC;CACF,CAAA;AAVY,oDAAoB;AAE/B;IADC,IAAA,mBAAG,EAAC,WAAW,CAAC;;;;uDAGhB;AAGD;IADC,IAAA,mBAAG,EAAC,WAAW,CAAC;IACD,WAAA,IAAA,wBAAQ,GAAE,CAAA;;;;0DAEzB;+BATU,oBAAoB;IADhC,IAAA,oBAAa,GAAE;GACH,oBAAoB,CAUhC"}

package/frontend-vue/app/components/SettingsView.vue

@@ -4,23 +4,33 @@ import { computed, onMounted, ref } from 'vue'
 type Mode = 'normal' | 'acceptEdits' | 'plan' | 'auto'
 type Thinking = 'off' | 'low' | 'medium' | 'high'
 type GenerationMode = 'safe' | 'vibe'
+type ProviderName = 'claude' | 'codex'
+
+interface ProviderAvailability {
+	available: boolean
+	reason?: string
+}
 
 interface AiSettings {
+	provider: ProviderName
 	mode: Mode
 	thinking: Thinking
 	generationMode: GenerationMode
 	allowLocalSkills: boolean
 	builderAvailable: boolean
+	providers: Record<ProviderName, ProviderAvailability>
 }
 
 const { $authFetch } = useAuthFetch()
 
 const settings = ref<AiSettings>({
+	provider: 'claude',
 	mode: 'normal',
 	thinking: 'medium',
 	generationMode: 'safe',
 	allowLocalSkills: false,
 	builderAvailable: false,
+	providers: { claude: { available: true }, codex: { available: false } },
 })
 const loading = ref(false)
 const saving = ref(false)
@@ -37,6 +47,23 @@ const MODE_OPTIONS: Array<{ value: Mode; label: string; hint: string }> = [
 	{ value: 'auto', label: 'Auto', hint: 'Auto-approve every tool action' },
 ]
 
+const PROVIDER_OPTIONS: Array<{
+	value: ProviderName
+	label: string
+	model: string
+}> = [
+	{ value: 'claude', label: 'Anthropic (Claude)', model: 'Claude Opus 4.x' },
+	{ value: 'codex', label: 'OpenAI (Codex)', model: 'GPT-5.x (Codex default)' },
+]
+
+// One control, two meanings: a token budget on Claude, a reasoning effort level
+// on Codex, which has no "off" and maps it to its lowest level.
+const THINKING_HINTS: Record<ProviderName, string> = {
+	claude: 'Thinking budget handed to the model.',
+	codex:
+		'Reasoning effort handed to the model. Codex has no "off": it maps to the lowest level.',
+}
+
 const THINKING_OPTIONS: Array<{ value: Thinking; label: string }> = [
 	{ value: 'off', label: 'Off' },
 	{ value: 'low', label: 'Low' },
@@ -71,6 +98,39 @@ async function persist(): Promise<void> {
 	}
 }
 
+function availabilityOf(name: ProviderName): ProviderAvailability {
+	return settings.value.providers?.[name] ?? { available: false }
+}
+
+function providerLabel(option: (typeof PROVIDER_OPTIONS)[number]): string {
+	return availabilityOf(option.value).available
+		? option.label
+		: `${option.label} — unavailable`
+}
+
+const activeProvider = computed(() => settings.value.provider)
+
+const providerReason = computed(
+	() => availabilityOf(settings.value.provider).reason ?? null,
+)
+
+const activeModel = computed(
+	() =>
+		PROVIDER_OPTIONS.find((o) => o.value === settings.value.provider)?.model ??
+		'',
+)
+
+function onProvider(event: Event): void {
+	const next = (event.target as HTMLSelectElement).value as ProviderName
+	if (!availabilityOf(next).available) {
+		// The option is disabled, so this only fires on a stale DOM; snap back.
+		;(event.target as HTMLSelectElement).value = settings.value.provider
+		return
+	}
+	settings.value.provider = next
+	void persist()
+}
+
 function onMode(event: Event): void {
 	settings.value.mode = (event.target as HTMLSelectElement).value as Mode
 	void persist()
@@ -123,14 +183,33 @@ const SELECT_CLASS =
 				<div class="flex flex-col gap-4 p-5">
 					<div>
 						<label class="mb-1.5 block text-xs font-medium text-toned">Provider</label>
-						<select :class="SELECT_CLASS" disabled>
-							<option>Anthropic (Claude)</option>
+						<select
+							:class="SELECT_CLASS"
+							:value="activeProvider"
+							:disabled="loading || saving"
+							@change="onProvider"
+						>
+							<option
+								v-for="option in PROVIDER_OPTIONS"
+								:key="option.value"
+								:value="option.value"
+								:disabled="!availabilityOf(option.value).available"
+							>
+								{{ providerLabel(option) }}
+							</option>
 						</select>
+						<p v-if="providerReason" class="mt-1.5 text-xs text-error">
+							{{ providerReason }}
+						</p>
+						<p class="mt-1.5 text-xs text-dimmed">
+							Switching provider ends the live context of open conversations;
+							their transcripts are kept.
+						</p>
 					</div>
 					<div>
 						<label class="mb-1.5 block text-xs font-medium text-toned">Model</label>
 						<select :class="SELECT_CLASS" disabled>
-							<option>Claude Opus 4.x</option>
+							<option>{{ activeModel }}</option>
 						</select>
 					</div>
 				</div>
@@ -181,6 +260,9 @@ const SELECT_CLASS =
 								{{ option.label }}
 							</option>
 						</select>
+						<p class="mt-1.5 text-xs text-dimmed">
+							{{ THINKING_HINTS[settings.provider] }}
+						</p>
 					</div>
 					<div>
 						<label class="flex items-start gap-3">

package/frontend-vue/app/plugins/ai.client.ts

@@ -1,4 +1,8 @@
-import { defineDmsPlugin, useDmsRouter } from '#dms/frontend-module'
+import {
+	type DmsAppContext,
+	defineDmsPlugin,
+	useDmsRouter,
+} from '#dms/frontend-module'
 import {
 	SIDECAR_HOST_NAME,
 	SIDECAR_INFO_PATH,
@@ -14,6 +18,7 @@ import { registerLauncherAction } from '../runtime/header-action'
 import { createHostCommandDispatcher } from '../runtime/host-commands'
 import { installNavigationCompleteEmitter } from '../runtime/navigation-complete'
 import { injectOverlay } from '../runtime/overlay'
+import { runWhenLoggedIn } from '../runtime/session-gate'
 import { installToggleShortcut } from '../runtime/shortcuts'
 import {
 	createSidecarStatusController,
@@ -30,10 +35,7 @@ function buildIframeUrl(port: number, token: string): string {
 	return `${SIDECAR_PROBE_HOST}:${port}/?theme=${mode}#token=${encodeURIComponent(token)}`
 }
 
-export default defineDmsPlugin(async ({ vueApp }) => {
-	if (!import.meta.env.DEV) return
-	const { loggedIn } = useUserSession()
-	if (!loggedIn.value) return
+async function startAssistant({ vueApp }: DmsAppContext): Promise<void> {
 	const { $authFetch } = useAuthFetch()
 	const controller = createSidecarStatusController(() =>
 		$authFetch(SIDECAR_INFO_PATH),
@@ -106,4 +108,14 @@ export default defineDmsPlugin(async ({ vueApp }) => {
 	}
 	vueApp.onUnmount(stop)
 	import.meta.hot?.dispose(stop)
+}
+
+export default defineDmsPlugin((context) => {
+	if (!import.meta.env.DEV) return
+	const { loggedIn } = useUserSession()
+	const stopGate = runWhenLoggedIn(
+		() => loggedIn.value,
+		() => void context.runWithContext(() => startAssistant(context)),
+	)
+	context.vueApp.onUnmount(stopGate)
 })

package/frontend-vue/app/runtime/session-gate.ts

@@ -0,0 +1,22 @@
+import { watch } from 'vue'
+
+// Plugins run once, when the Vue app boots, on whatever page the browser landed
+// on. Landing on the sign-in screen means there is no session yet, and signing
+// in is a client-side navigation that never re-creates the app: a plugin that
+// gave up there would stay silent until the next full page load. Wait for the
+// session to appear instead, then run exactly once.
+export function runWhenLoggedIn(
+	isLoggedIn: () => boolean,
+	start: () => void,
+): () => void {
+	if (isLoggedIn()) {
+		start()
+		return () => undefined
+	}
+	const stop = watch(isLoggedIn, (loggedIn) => {
+		if (!loggedIn) return
+		stop()
+		start()
+	})
+	return stop
+}

package/frontend-vue/tests/session-gate.test.ts

@@ -0,0 +1,39 @@
+import { nextTick, ref } from 'vue'
+import { describe, expect, it, vi } from 'vitest'
+import { runWhenLoggedIn } from '../app/runtime/session-gate'
+
+describe('session gate', () => {
+	it('starts immediately when the session is already hydrated', () => {
+		const start = vi.fn()
+		runWhenLoggedIn(() => true, start)
+		expect(start).toHaveBeenCalledTimes(1)
+	})
+
+	it('starts once the session appears, and only once', async () => {
+		const loggedIn = ref(false)
+		const start = vi.fn()
+		runWhenLoggedIn(() => loggedIn.value, start)
+		expect(start).not.toHaveBeenCalled()
+
+		loggedIn.value = true
+		await nextTick()
+		expect(start).toHaveBeenCalledTimes(1)
+
+		loggedIn.value = false
+		await nextTick()
+		loggedIn.value = true
+		await nextTick()
+		expect(start).toHaveBeenCalledTimes(1)
+	})
+
+	it('never starts once the gate is stopped', async () => {
+		const loggedIn = ref(false)
+		const start = vi.fn()
+		const stop = runWhenLoggedIn(() => loggedIn.value, start)
+
+		stop()
+		loggedIn.value = true
+		await nextTick()
+		expect(start).not.toHaveBeenCalled()
+	})
+})

package/frontend-vue/tests/sidecar-guest.test.ts

@@ -1,13 +1,29 @@
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import ts from 'typescript'
+import { nextTick, ref, type Ref } from 'vue'
 import { expect, it, vi } from 'vitest'
+import { runWhenLoggedIn } from '../app/runtime/session-gate'
 
 interface PluginExports {
-	default: (context: unknown) => Promise<void>
+	default: (context: unknown) => void | Promise<void>
 }
 
-it('does not invoke authenticated fetching or inject the assistant for a guest', async () => {
+interface PluginHarness {
+	useAuthFetch: ReturnType<typeof vi.fn>
+	run: () => void | Promise<void>
+}
+
+const SESSION_GATE_MODULE = '../runtime/session-gate'
+const SIDECAR_STATUS_MODULE = '../runtime/sidecar-status'
+
+// A first probe reporting "no assistant here" stops the startup right after the
+// authenticated fetch, which is all these tests need to observe.
+const silentController = {
+	createSidecarStatusController: () => ({ init: async () => false }),
+}
+
+function loadPlugin(loggedIn: Ref<boolean>): PluginHarness {
 	const source = readFileSync(
 		resolve(__dirname, '../app/plugins/ai.client.ts'),
 		'utf8',
@@ -16,30 +32,48 @@ it('does not invoke authenticated fetching or inject the assistant for a guest',
 		source
 			.replace('import.meta.env.DEV', 'true')
 			.replace('import.meta.hot', 'undefined'),
-		{
-			compilerOptions: { module: ts.ModuleKind.CommonJS },
-		},
+		{ compilerOptions: { module: ts.ModuleKind.CommonJS } },
 	)
 	const exports = {} as PluginExports
-	const useAuthFetch = vi.fn(() => {
-		throw new Error('A guest must not enter session recovery')
-	})
-	const requireModule = (name: string) =>
-		name === '#dms/frontend-module'
-			? { defineDmsPlugin: (plugin: unknown) => plugin }
-			: {}
+	const useAuthFetch = vi.fn(() => ({ $authFetch: vi.fn() }))
+	const requireModule = (name: string) => {
+		if (name === '#dms/frontend-module') {
+			return { defineDmsPlugin: (plugin: unknown) => plugin }
+		}
+		if (name === SESSION_GATE_MODULE) return { runWhenLoggedIn }
+		if (name === SIDECAR_STATUS_MODULE) return silentController
+		return {}
+	}
 	new Function(
 		'require',
 		'exports',
 		'useUserSession',
 		'useAuthFetch',
 		compiled.outputText,
-	)(
-		requireModule,
-		exports,
-		() => ({ loggedIn: { value: false } }),
+	)(requireModule, exports, () => ({ loggedIn }), useAuthFetch)
+	return {
 		useAuthFetch,
-	)
-	await exports.default({})
-	expect(useAuthFetch).not.toHaveBeenCalled()
+		run: () =>
+			exports.default({
+				vueApp: { onUnmount: vi.fn() },
+				runWithContext: (callback: () => unknown) => callback(),
+			}),
+	}
+}
+
+it('does not invoke authenticated fetching or inject the assistant for a guest', async () => {
+	const plugin = loadPlugin(ref(false))
+	await plugin.run()
+	expect(plugin.useAuthFetch).not.toHaveBeenCalled()
+})
+
+it('starts the assistant when a guest signs in without reloading the page', async () => {
+	const loggedIn = ref(false)
+	const plugin = loadPlugin(loggedIn)
+	await plugin.run()
+	expect(plugin.useAuthFetch).not.toHaveBeenCalled()
+
+	loggedIn.value = true
+	await nextTick()
+	expect(plugin.useAuthFetch).toHaveBeenCalledTimes(1)
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-ai",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -38,6 +38,7 @@
     "lint:fix": "oxlint --disable-nested-config --fix --max-warnings=1000000 && oxfmt --disable-nested-config . && cd frontend-vue && pnpm lint:fix && cd ../sidecar && pnpm lint:fix",
     "typecheck": "tsc --noEmit && cd frontend-vue && pnpm typecheck && cd ../sidecar && pnpm typecheck",
     "test": "cd sidecar && pnpm test && cd ../frontend-vue && pnpm test",
+    "test:sidecar-smoke": "pnpm run build:sidecar && node --test tests/sidecar-build.test.cjs",
     "test:frontend-registration": "pnpm run build && node --test tests/frontend-registration.test.cjs",
     "test:release-script": "node --test tests/release-script.test.cjs",
     "test:e2e": "cd sidecar && pnpm test:e2e",
@@ -52,6 +53,7 @@
     "@antelopejs/interface-dms": ">=0.0.1 <1.0.0",
     "@anthropic-ai/claude-agent-sdk": "^0.2.131",
     "@anthropic-ai/claude-code": "^2.1.131",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "ws": "^8.18.0",
     "zod": "^4.0.0"
   },
@@ -67,6 +69,14 @@
     "rimraf": "^6.1.3",
     "typescript": "^5.9.3"
   },
+  "peerDependencies": {
+    "@openai/codex": "0.154.0"
+  },
+  "peerDependenciesMeta": {
+    "@openai/codex": {
+      "optional": true
+    }
+  },
   "optionalDependencies": {
     "@antelopejs/interface-dms-builder": ">=0.0.1 <1.0.0"
   },