@flowdular/sandbox 0.2.4 → 0.2.6

package/README.md

@@ -133,6 +133,38 @@ Every request to the sandbox API is checked before it does anything:
 sandbox that cannot prove it is loopback never offers a local binary, because a
 local binary carries the operator's own login.
 
+## Model settings
+
+Open the workspace menu and choose **AI models · BYOK**. Select a provider,
+enter its model ID and API key, and supply an API base URL for OpenAI-compatible
+servers or a resource name for Azure. Saving makes BYOK available in the agent
+selector. You can make it the default for new sessions; running turns retain
+the configuration they started with.
+
+Keys are encrypted in local sandbox configuration and never returned to the
+browser. An empty key field preserves the existing key only when the provider
+and destination are unchanged. The settings also let you clear the key or
+remove BYOK entirely.
+
+Provider conversations are scoped to the current specialist, module, task skill,
+write permissions, approved specification and model. A handoff that changes
+that scope starts a fresh conversation with the brief and recent messages;
+continuing the same scope resumes its existing conversation. Legacy shared
+conversations are replaced on the next turn.
+
+For a long CLI conversation, select **Fresh agent context** before sending the
+next message. It starts a new CLI conversation with the original brief and
+recent sandbox messages, preserving draft files, the approved specification
+and the complete sandbox transcript. Earlier tool output is not replayed;
+include any older decision that is not recorded in the spec or recent messages.
+Claude activity is shown from the start of streamed response blocks, with
+completed reasoning and tool events following as they arrive. This does not
+reduce provider queue or inference time.
+
+Source-change logs group repeated saves into a short summary such as
+`Draft blog (96a64f10) · 4 files changed`. These report file changes, not a
+successful build. Use `--verbose` to see individual paths.
+
 ## Sessions
 
 The home dashboard lists the operator's ideas, current stages, recorded token

package/bin/flowdular-sandbox.mjs

@@ -2,6 +2,62 @@
 
 // ../sandbox/bin/flowdular-sandbox.mjs
 import "./register-types.mjs";
+
+// ../sandbox/src/server/reload-log.ts
+import { relative } from "node:path";
+function watchSandboxReloads(server, appRoot2, write, verbose = false) {
+  const groups = /* @__PURE__ */ new Map();
+  let timer;
+  let pendingFiles = 0;
+  const flush = () => {
+    if (timer) clearTimeout(timer);
+    timer = void 0;
+    for (const [label, files] of groups) {
+      if (verbose) {
+        for (const path of files) write(path);
+      } else {
+        write(
+          `${label} \xB7 ${files.size} ${files.size === 1 ? "file" : "files"} changed`
+        );
+      }
+    }
+    groups.clear();
+    pendingFiles = 0;
+  };
+  const changed = (event, path) => {
+    if (!["add", "change", "unlink"].includes(event)) return;
+    const normalized = path.replaceAll("\\", "/");
+    const draft = normalized.match(
+      /\/(?:\.flowdular|\.coreloom)\/sandbox\/sessions\/([^/]+)\/workspace\/modules\/([^/]+)\//
+    );
+    const local = relative(appRoot2, path);
+    if (!draft && (local === ".." || local.startsWith("../") || local.startsWith("..\\")))
+      return;
+    const label = draft ? `Draft ${draft[2]} (${draft[1].slice(0, 8)})` : "Sandbox";
+    const files = groups.get(label) ?? /* @__PURE__ */ new Set();
+    if (!files.has(path)) pendingFiles += 1;
+    files.add(path);
+    groups.set(label, files);
+    if (!timer) {
+      timer = setTimeout(flush, 750);
+      timer.unref?.();
+    }
+    if (pendingFiles >= 256) flush();
+  };
+  const dispose = () => {
+    if (timer) clearTimeout(timer);
+    timer = void 0;
+    groups.clear();
+    pendingFiles = 0;
+    server.watcher.off("all", changed);
+    server.httpServer?.off("close", dispose);
+  };
+  server.watcher.on("all", changed);
+  server.httpServer?.once("close", dispose);
+  return dispose;
+}
+
+// ../sandbox/bin/flowdular-sandbox.mjs
 import process2 from "node:process";
 import { realpathSync } from "node:fs";
 import { dirname, resolve } from "node:path";
@@ -168,18 +224,6 @@ function installOctaneConsoleBridge(verbose, useColor) {
     console.error = originalError;
   };
 }
-function watchReloads(server, root, useColor) {
-  let lastChange = "";
-  let lastChangeAt = 0;
-  server.watcher.on("change", (path) => {
-    const changed = path.startsWith(root) ? path.slice(root.length + 1) : path;
-    const now = Date.now();
-    if (changed === lastChange && now - lastChangeAt < 100) return;
-    lastChange = changed;
-    lastChangeAt = now;
-    console.log(formatDevEvent("reload", changed, useColor));
-  });
-}
 
 // ../sandbox/bin/flowdular-sandbox.mjs
 var appRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -362,7 +406,12 @@ async function startSandbox(argv = process2.argv.slice(2)) {
       ]
     ]
   });
-  watchReloads(server, appRoot, useColor);
+  watchSandboxReloads(
+    server,
+    appRoot,
+    (message) => console.log(formatDevEvent("reload", message, useColor)),
+    options.verbose
+  );
   const close = async () => {
     console.log(`
 ${formatDevEvent("process", "Sandbox stopped.", useColor)}`);

package/internal/coding-agent/src/drivers/claude-code.ts

@@ -30,6 +30,7 @@ const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 interface ContentBlock {
 	readonly type?: string;
 	readonly text?: string;
+	readonly thinking?: string;
 	readonly name?: string;
 	readonly input?: Record<string, unknown>;
 	readonly content?: unknown;
@@ -116,7 +117,7 @@ export function createClaudeCodeDriver(
 		): AsyncIterable<CodingAgentEvent> {
 			const resumeId = request.resumeId ?? null;
 			if (!resumeId) {
-				yield* runSession(request, null);
+				yield* runSession(request, null, Boolean(request.history?.length));
 				return;
 			}
 			try {
@@ -145,6 +146,7 @@ export function createClaudeCodeDriver(
 			'--output-format',
 			'stream-json',
 			'--verbose',
+			'--include-partial-messages',
 			'--permission-mode',
 			'acceptEdits',
 			'--restricted',
@@ -193,6 +195,23 @@ export function createClaudeCodeDriver(
 				continue;
 			}
 
+			if (type === 'stream_event') {
+				const partial = message.event as Record<string, unknown> | undefined;
+				const block = partial?.content_block as
+					| Record<string, unknown>
+					| undefined;
+				if (
+					partial?.type === 'content_block_start' &&
+					(block?.type === 'thinking' || block?.type === 'text')
+				) {
+					yield {
+						type: 'activity',
+						phase: block.type === 'thinking' ? 'thinking' : 'responding',
+					};
+				}
+				continue;
+			}
+
 			if (type === 'assistant') {
 				const content = ((message.message ?? {}) as Record<string, unknown>)
 					.content;
@@ -200,8 +219,8 @@ export function createClaudeCodeDriver(
 					if (block.type === 'text' && block.text?.trim()) {
 						yield { type: 'assistant.message', text: block.text };
 					}
-					if (block.type === 'thinking' && typeof block.text === 'string') {
-						yield { type: 'reasoning', text: block.text };
+					if (block.type === 'thinking' && typeof block.thinking === 'string') {
+						yield { type: 'reasoning', text: block.thinking };
 					}
 					if (block.type === 'tool_use' && block.name) {
 						yield {

package/internal/coding-agent/src/roles/contract.ts

@@ -3,7 +3,9 @@ export const SANDBOX_AGENT_CONTRACT = `You are one coding specialist in a Flowdu
 
 Always-active invariants
 - Write only to the active module and the allowed Session paths. reference/ is read-only. Preserve unrelated work. Never edit platform composition or flowdular.json.
+- Implement only the portions of the selected skill that belong to your current role and Session write paths. Other sections describe your teammates' work; hand those parts off instead of editing their files.
 - Read the one task skill named under Session before editing. Do not load other SKILL.md files or the full skill catalog. Read only the owning code and references needed for this task; copy the example-module shape where relevant.
+- Batch independent reads and searches when the tools allow it. Reuse files already read in this conversation unless they changed. Search for a symbol in its owning package before widening the search. Do not read whole reference trees or node_modules to discover an API. If a required public API is absent, report that blocker rather than repeating broad searches.
 - Module implementation requires operator approval of the exact current spec hash. Agents never approve specs. Any later spec edit, request for changes, or added module invalidates the approval. Stop implementation until it is renewed.
 - Deny by default: explicit endpoint permissions, trusted principal identity, CSRF and bounded inputs. Never accept tenant identity from request input.
 - Use bound SQL and tenant-scoped transactions. Tenant predicates and forced RLS with USING and WITH CHECK are mandatory. No runtime superuser/BYPASSRLS. DDL uses a short migration lease; applied SQL is immutable and mirrored byte for byte.
@@ -39,7 +41,7 @@ export function composeSessionFacts(context: InstructionContext): string {
 		`- Module directory in this workspace: ${context.modulePath}`,
 		`- Session kind: ${context.sessionKind === 'new-module' ? 'new module; author its specification first, then wait for operator approval of the exact spec hash before implementation' : 'change to an existing module; author its spec delta first, then wait for operator approval of the exact spec hash before implementation'}`,
 		`- Blueprint: ${context.blueprint}`,
-		`- Paths you may write: ${context.allowedPaths.join(', ')}`,
+		`- Paths you may write: ${context.allowedPaths.length ? context.allowedPaths.join(', ') : 'none (read-only)'}`,
 	];
 	if (context.skill) {
 		lines.push(`- Task skill: reference/skills/${context.skill}/SKILL.md`);

package/internal/coding-agent/src/roles/registry.ts

@@ -145,12 +145,6 @@ export function composeInstruction(
 		'',
 		role.instruction,
 		'',
-		composeSessionFacts({
-			...context,
-			allowedPaths:
-				context.allowedPaths.length > 0
-					? context.allowedPaths
-					: role.allowedPaths,
-		}),
+		composeSessionFacts(context),
 	].join('\n');
 }

package/internal/coding-agent/src/types.ts

@@ -17,6 +17,7 @@ export type CodingAgentEvent =
 	  }
 	| { readonly type: 'assistant.message'; readonly text: string }
 	| { readonly type: 'reasoning'; readonly text: string }
+	| { readonly type: 'activity'; readonly phase: 'thinking' | 'responding' }
 	| {
 			readonly type: 'tool.started';
 			readonly tool: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/sandbox",
-	"version": "0.2.4",
+	"version": "0.2.6",
 	"description": "The Flowdular sandbox: chat a change, build it behind the gates, preview it in the real application, deliver it as code.",
 	"license": "MIT",
 	"homepage": "https://github.com/flowdular/flowdular/tree/main/packages/sandbox#readme",

package/src/App.tsrx

@@ -1,4 +1,6 @@
-import { useEffect, useMemo } from 'octane';
+import { useEffect, useMemo, useState } from 'octane';
+import { ModelSettingsModal } from './client/ModelSettingsModal.tsrx';
+import type { ConfigurationPatch } from './client/api.ts';
 import { Head, Seo } from '@octanejs/seo';
 import { Alert, BrandMark, Button, Icon, Tag } from '@flowdular/sdk/ui';
 import { useValue } from 'segment-state';
@@ -118,6 +120,7 @@ export function App(props?: RenderRouteProps) @{
 	const [ejectError, setEjectError] = useValue(sandbox.state.ejectError);
 	const [ejecting, setEjecting] = useValue(sandbox.state.ejecting);
 	const [ejectBuild, setEjectBuild] = useValue(sandbox.state.ejectBuild);
+	const [modelSettingsOpen, setModelSettingsOpen] = useState(false);
 	const [menuOpen, setMenuOpen] = useValue(sandbox.state.menuOpen);
 	const [githubSettingsOpen, setGitHubSettingsOpen] = useValue(
 		sandbox.state.githubSettingsOpen,
@@ -280,6 +283,7 @@ export function App(props?: RenderRouteProps) @{
 		roleId: string,
 		moduleDirectory = sandbox.store.get(sandbox.state.turnModule),
 		submittedDraft?: string,
+		freshContext = false,
 	) => {
 		detach();
 		setRunning(true);
@@ -289,6 +293,7 @@ export function App(props?: RenderRouteProps) @{
 			session.id,
 			{
 				message: text,
+				freshContext,
 				role: roleId,
 				...(moduleDirectory ? { module: moduleDirectory } : {}),
 				driver: sandbox.store.get(sandbox.state.driver) || session.driver,
@@ -355,7 +360,7 @@ export function App(props?: RenderRouteProps) @{
 		}
 	};
 
-	const send = (explicit?: string) => {
+	const send = (explicit?: string, freshContext = false) => {
 		const session = currentSession();
 		if (!session || sandbox.store.get(sandbox.state.running)) return;
 		const text = (explicit ?? draft).trim();
@@ -371,6 +376,7 @@ export function App(props?: RenderRouteProps) @{
 			role,
 			undefined,
 			explicit === undefined ? draft : undefined,
+			freshContext,
 		);
 	};
 
@@ -592,6 +598,22 @@ export function App(props?: RenderRouteProps) @{
 		}
 	};
 
+	const saveModels = async (input: ConfigurationPatch) => {
+		setBusy(true);
+		setError('');
+		try {
+			await saveConfiguration(input);
+			await refreshState();
+			if (input.driver && !currentSession()) setDriver(input.driver);
+			setModelSettingsOpen(false);
+			setNotice(t('sandbox.models.saved'));
+		} catch (error) {
+			setError(message(error, t('sandbox.models.error')));
+		} finally {
+			setBusy(false);
+		}
+	};
+
 	const saveGitHub = async (input: GitHubSettingsInput) => {
 		setBusy(true);
 		setError('');
@@ -700,6 +722,11 @@ export function App(props?: RenderRouteProps) @{
 						<span class="sandbox__spacer"></span>
 						<WorkspaceMenu
 							state={state}
+							onModels={() => {
+								setMenuOpen(false);
+								setError('');
+								setModelSettingsOpen(true);
+							}}
 							open={menuOpen}
 							onToggle={() => setMenuOpen(!menuOpen)}
 							onChangeConnection={() => {
@@ -734,6 +761,18 @@ export function App(props?: RenderRouteProps) @{
 							onClose={closeEject}
 						/>
 					}
+					@if (modelSettingsOpen) {
+						<ModelSettingsModal
+							configuration={state.configuration}
+							busy={busy}
+							error={error}
+							onSave={(input) => void saveModels(input)}
+							onClose={() => {
+								setModelSettingsOpen(false);
+								setError('');
+							}}
+						/>
+					}
 					@if (githubSettingsOpen) {
 						<GitHubSettingsModal
 							configuration={state.configuration}
@@ -853,7 +892,7 @@ export function App(props?: RenderRouteProps) @{
 									onModule={setTurnModule}
 									onDriver={setDriver}
 									onMessage={setDraft}
-									onSend={() => send()}
+									onSend={(fresh) => send(undefined, fresh)}
 									onStop={stop}
 									onClearSelection={() => setSelection(null)}
 								/>

package/src/client/ChatPane.tsrx

@@ -56,7 +56,7 @@ export interface ChatPaneProps {
 	readonly onModule: (module: string) => void;
 	readonly onDriver: (driver: string) => void;
 	readonly onMessage: (message: string) => void;
-	readonly onSend: () => void;
+	readonly onSend: (freshContext?: boolean) => void;
 	readonly onStop: () => void;
 	readonly onClearSelection: () => void;
 }
@@ -70,6 +70,8 @@ function eventLabel(entry: ChatEntry): string {
 				driver: event.driver,
 				role: roleLabel(event.role),
 			});
+		case 'activity':
+			return t('sandbox.chat.activity.' + event.phase);
 		case 'reasoning':
 			return event.text.slice(0, 160);
 		case 'tool.started':
@@ -381,9 +383,11 @@ export function ChatPane(props: ChatPaneProps) @{
 		</div>;
 	};
 
+	const [freshContext, setFreshContext] = useState(false);
 	const submit = (event: SubmitEvent) => {
 		event.preventDefault();
-		props.onSend();
+		props.onSend(freshContext);
+		setFreshContext(false);
 	};
 
 	<section class="sandbox__chat">
@@ -602,6 +606,15 @@ export function ChatPane(props: ChatPaneProps) @{
 				onInput={(event) => props.onMessage(event.currentTarget.value)}
 				onPaste={onPaste}
 			></textarea>
+			<label class="ui-checkbox" title={t('sandbox.chat.freshHelp')}>
+				<input
+					type="checkbox"
+					checked={freshContext}
+					disabled={props.running}
+					onChange={(event) => setFreshContext(event.currentTarget.checked)}
+				/>
+				<span>{t('sandbox.chat.fresh')}</span>
+			</label>
 			<div class="chat__composer-row">
 				<button
 					class="chat__attach"

package/src/client/ModelSettingsModal.tsrx

@@ -0,0 +1,161 @@
+import { useState } from 'octane';
+import { Alert, Button, Drawer, FormField } from '@flowdular/sdk/ui';
+import {
+	AI_PROVIDER_CATALOG,
+	AI_PROVIDER_KINDS,
+} from '@flowdular/sdk/ai-provider/catalog';
+import type { ConfigurationPatch } from './api.ts';
+import type { SafeSandboxConfiguration } from '../server/config.ts';
+import { useTranslation } from './i18n.ts';
+
+export function ModelSettingsModal(props: {
+	readonly configuration: SafeSandboxConfiguration;
+	readonly busy: boolean;
+	readonly error: string;
+	readonly onSave: (input: ConfigurationPatch) => void;
+	readonly onClose: () => void;
+}) @{
+	const { t } = useTranslation();
+	const saved = props.configuration.byok;
+	const [kind, setKind] = useState(saved?.kind ?? 'anthropic');
+	const submit = (event: SubmitEvent) => {
+		event.preventDefault();
+		if (props.busy) return;
+		const data = new FormData(event.currentTarget as HTMLFormElement);
+		props.onSave({
+			byokKind: kind,
+			byokModel: String(data.get('model') ?? '').trim(),
+			byokCredential: String(data.get('credential') ?? '').trim(),
+			byokBaseUrl: String(data.get('baseURL') ?? '').trim(),
+			byokResourceName: String(data.get('resourceName') ?? '').trim(),
+			byokClearCredential: data.get('clear') === 'on',
+			...(data.get('default') === 'on' ||
+			props.configuration.mode === 'self-hosted'
+				? { driver: 'byok', driverModel: null }
+				: props.configuration.driver === 'byok' &&
+				props.configuration.mode === 'loopback'
+					? { driver: 'claude-code', driverModel: null }
+					: {}),
+		});
+	};
+	<Drawer
+		open={true}
+		title={t('sandbox.models.title')}
+		subtitle={t('sandbox.models.description')}
+		width="lg"
+		onClose={() => {
+			if (!props.busy) props.onClose();
+		}}
+	>
+		<form class="ui-drawer__form" onSubmit={submit}>
+			<div class="ui-drawer__body">
+				<div class="ui-form">
+					<Alert tone="info">{t('sandbox.models.help')}</Alert>
+					<FormField label={t('sandbox.models.provider')}>
+						<select
+							class="ui-select"
+							value={kind}
+							onChange={(event) => setKind(
+								event.currentTarget.value as typeof kind,
+							)}
+						>
+							@for (const option of AI_PROVIDER_KINDS; key option) {
+								<option
+									value={option}
+								>{AI_PROVIDER_CATALOG[option].label}</option>
+							}
+						</select>
+					</FormField>
+					<FormField label={t('sandbox.models.model')}>
+						<input
+							class="ui-input"
+							name="model"
+							required
+							maxlength={160}
+							defaultValue={saved?.model ?? ''}
+						/>
+					</FormField>
+					<FormField
+						label={t('sandbox.models.key')}
+						help={saved?.credentialFingerprint
+							? t('sandbox.models.keySaved')
+							: t('sandbox.models.keyHelp')}
+					>
+						<input
+							class="ui-input"
+							name="credential"
+							type="password"
+							autocomplete="new-password"
+							maxlength={16384}
+						/>
+					</FormField>
+					<FormField label={t('sandbox.models.url')}>
+						<input
+							class="ui-input"
+							name="baseURL"
+							type="url"
+							required={kind === 'openai-compatible'}
+							maxlength={2048}
+							defaultValue={saved?.baseURL ?? ''}
+						/>
+					</FormField>
+					@if (kind === 'azure') {
+						<FormField label={t('sandbox.models.resource')}>
+							<input
+								class="ui-input"
+								name="resourceName"
+								required
+								maxlength={160}
+								defaultValue={saved?.resourceName ?? ''}
+							/>
+						</FormField>
+					}
+					<label class="ui-checkbox">
+						<input
+							type="checkbox"
+							name="default"
+							disabled={props.configuration.mode === 'self-hosted'}
+							defaultChecked={props.configuration.driver === 'byok' ||
+								props.configuration.mode === 'self-hosted'}
+						/>
+						<span>{t('sandbox.models.default')}</span>
+					</label>
+					@if (saved?.credentialFingerprint) {
+						<label class="ui-checkbox">
+							<input type="checkbox" name="clear" />
+							<span>{t('sandbox.models.clear')}</span>
+						</label>
+					}
+					@if (props.error) {
+						<Alert tone="danger">{props.error}</Alert>
+					}
+				</div>
+			</div>
+			<div class="ui-drawer__foot">
+				<Button disabled={props.busy} onClick={props.onClose}>{t(
+					'sandbox.models.cancel',
+				)}</Button>
+				@if (saved) {
+					<Button
+						variant="danger"
+						disabled={props.busy}
+						onClick={() => props.onSave({
+							byokRemove: true,
+							...(props.configuration.driver === 'byok'
+								? {
+										driver: props.configuration.mode === 'loopback'
+											? 'claude-code'
+											: 'byok',
+										driverModel: null,
+									}
+								: {}),
+						})}
+					>{t('sandbox.models.remove')}</Button>
+				}
+				<Button type="submit" variant="primary" disabled={props.busy}>{t(
+					'sandbox.models.save',
+				)}</Button>
+			</div>
+		</form>
+	</Drawer>
+}

package/src/client/WorkspaceMenu.tsrx

@@ -5,6 +5,7 @@ import { setActiveLocale, SUPPORTED_LOCALES, useTranslation } from './i18n.ts';
 export interface WorkspaceMenuProps {
 	readonly state: SandboxState;
 	readonly open: boolean;
+	readonly onModels: () => void;
 	readonly onToggle: () => void;
 	readonly onChangeConnection: () => void;
 	readonly onDisconnect: () => void;
@@ -60,6 +61,12 @@ export function WorkspaceMenu(props: WorkspaceMenuProps) @{
 					</Tag>
 				</div>
 				<div class="ui-menu__sep"></div>
+				<button
+					class="ui-menu__item"
+					type="button"
+					role="menuitem"
+					onClick={props.onModels}
+				>{t('sandbox.models.title')}</button>
 				<label class="ui-menu__item workspace-menu__language">
 					<Icon name="globe" size={16} />
 					<span>{t('sandbox.workspace.language')}</span>

package/src/client/api.ts

@@ -242,6 +242,8 @@ export interface ConfigurationPatch {
 	readonly driver?: string;
 	readonly driverModel?: string | null;
 	readonly previewData?: 'fixtures' | 'bridge';
+	readonly byokRemove?: boolean;
+	readonly byokClearCredential?: boolean;
 	readonly byokKind?: string;
 	readonly byokModel?: string;
 	readonly byokCredential?: string;
@@ -705,6 +707,7 @@ export function streamTurn(
 	sessionId: string,
 	input: {
 		readonly message: string;
+		readonly freshContext?: boolean;
 		readonly role: string;
 		/* The draft module directory the turn works in; absent lets the sandbox
 		   decide from the last handoff. */

package/src/client/locales/en.json

@@ -462,5 +462,26 @@
 	"eject.explanation.officialModules": "The sandbox will repeat all gates, verify the module in the registry repository and open a pull request. Maintainers decide publication. New modules only; existing registry modules are never overwritten.",
 	"delivery.step.provider": "Check GitHub access",
 	"delivery.step.review": "Record reviewed source",
-	"delivery.step.pack": "Prepare module release"
+	"delivery.step.pack": "Prepare module release",
+	"models.title": "AI models · BYOK",
+	"models.description": "Use your own API key for sandbox coding agents.",
+	"models.help": "Save a provider to make BYOK available in the agent selector. Running turns keep their current configuration.",
+	"models.provider": "Provider",
+	"models.model": "Model ID",
+	"models.key": "API key",
+	"models.keySaved": "A key is saved. Leave empty to keep it for the same provider and address.",
+	"models.keyHelp": "The key is encrypted on the server. Enter a new key when changing provider or address.",
+	"models.url": "API base URL",
+	"models.resource": "Azure resource name",
+	"models.default": "Use BYOK by default for new sessions",
+	"models.clear": "Delete the saved key",
+	"models.cancel": "Cancel",
+	"models.remove": "Remove BYOK",
+	"models.save": "Save",
+	"models.saved": "Model settings saved.",
+	"models.error": "Could not save model settings.",
+	"chat.activity.thinking": "Agent is thinking…",
+	"chat.activity.responding": "Agent is preparing a response…",
+	"chat.fresh": "Fresh agent context",
+	"chat.freshHelp": "The next message starts a fresh context with the brief and recent messages. Draft files, specification and sandbox history are preserved."
 }

package/src/client/locales/pl.json

@@ -462,5 +462,26 @@
 	"eject.explanation.officialModules": "Sandbox powtórzy wszystkie kontrole, zweryfikuje moduł w repozytorium rejestru i otworzy PR. Maintainerzy zdecydują o publikacji. Tylko nowe moduły; istniejące moduły rejestru nie będą nadpisywane.",
 	"delivery.step.provider": "Sprawdzanie dostępu do GitHub",
 	"delivery.step.review": "Zapisywanie dowodów review",
-	"delivery.step.pack": "Przygotowanie wydania modułu"
+	"delivery.step.pack": "Przygotowanie wydania modułu",
+	"models.title": "Modele AI · BYOK",
+	"models.description": "Używaj własnego klucza API dla agentów sandboxa.",
+	"models.help": "Zapisz dostawcę, aby BYOK pojawił się na liście agentów. Trwające tury zachowają obecną konfigurację.",
+	"models.provider": "Dostawca",
+	"models.model": "Identyfikator modelu",
+	"models.key": "Klucz API",
+	"models.keySaved": "Klucz jest zapisany. Puste pole zachowa go dla tego samego dostawcy i adresu.",
+	"models.keyHelp": "Klucz jest szyfrowany na serwerze. Przy zmianie dostawcy lub adresu podaj nowy klucz.",
+	"models.url": "Adres bazowy API",
+	"models.resource": "Nazwa zasobu Azure",
+	"models.default": "Używaj BYOK domyślnie w nowych sesjach",
+	"models.clear": "Usuń zapisany klucz",
+	"models.cancel": "Anuluj",
+	"models.remove": "Usuń BYOK",
+	"models.save": "Zapisz",
+	"models.saved": "Zapisano ustawienia modeli.",
+	"models.error": "Nie udało się zapisać ustawień modeli.",
+	"chat.activity.thinking": "Agent analizuje zadanie…",
+	"chat.activity.responding": "Agent przygotowuje odpowiedź…",
+	"chat.fresh": "Świeży kontekst agenta",
+	"chat.freshHelp": "Następna wiadomość rozpocznie nowy kontekst z briefem i ostatnimi wiadomościami. Pliki, specyfikacja i historia sandboxa pozostaną zachowane."
 }

package/src/server/byok-settings.ts

@@ -0,0 +1,81 @@
+import { isAiProviderKind, AI_PROVIDER_CATALOG } from '@flowdular/sdk/ai-provider';
+import { sealSecret, type ByokProviderConfiguration } from './config.ts';
+import { SandboxSetupError } from './workspace-root.ts';
+
+export async function byokSettings(
+	root: string,
+	value: Record<string, unknown>,
+	previous: ByokProviderConfiguration | null,
+): Promise<ByokProviderConfiguration | null | undefined> {
+	if (value.byokRemove === true) return null;
+	if (value.byokKind === undefined) return undefined;
+	const field = (name: string, max: number): string => {
+		const valueAt = value[name];
+		if (valueAt === undefined || valueAt === null) return '';
+		if (typeof valueAt !== 'string' || valueAt.length > max)
+			throw new SandboxSetupError('INVALID_INPUT', `Invalid ${name}.`);
+		return valueAt.trim();
+	};
+	const kind = field('byokKind', 40);
+	if (!isAiProviderKind(kind))
+		throw new SandboxSetupError('INVALID_INPUT', 'Unknown AI provider.');
+	const model = field('byokModel', 160);
+	if (!model)
+		throw new SandboxSetupError('INVALID_INPUT', 'A model is required.');
+	const baseURL = field('byokBaseUrl', 2048);
+	const resourceName = field('byokResourceName', 160);
+	if (AI_PROVIDER_CATALOG[kind].requires.includes('baseURL') && !baseURL)
+		throw new SandboxSetupError(
+			'INVALID_INPUT',
+			'An API base URL is required.',
+		);
+	if (
+		AI_PROVIDER_CATALOG[kind].requires.includes('resourceName') &&
+		!resourceName
+	)
+		throw new SandboxSetupError(
+			'INVALID_INPUT',
+			'An Azure resource name is required.',
+		);
+	if (baseURL) {
+		let url: URL;
+		try {
+			url = new URL(baseURL);
+		} catch {
+			throw new SandboxSetupError('INVALID_INPUT', 'Invalid API base URL.');
+		}
+		if (
+			!(
+				url.protocol === 'https:' ||
+				(url.protocol === 'http:' &&
+					(url.hostname === 'localhost' ||
+						url.hostname === '[::1]' ||
+						/^127(?:\.\d{1,3}){3}$/.test(url.hostname)))
+			) ||
+			url.username ||
+			url.password ||
+			url.search ||
+			url.hash
+		)
+			throw new SandboxSetupError(
+				'INVALID_INPUT',
+				'API base URL must use HTTPS (HTTP is allowed on loopback), without credentials, query or fragment.',
+			);
+	}
+	const credential = field('byokCredential', 16384);
+	const sameDestination =
+		previous?.kind === kind &&
+		(previous.baseURL ?? '') === baseURL &&
+		(previous.resourceName ?? '') === resourceName;
+	return {
+		kind,
+		model,
+		...(baseURL ? { baseURL } : {}),
+		...(resourceName ? { resourceName } : {}),
+		credential: credential
+			? await sealSecret(root, credential)
+			: value.byokClearCredential === true || !sameDestination
+				? null
+				: (previous?.credential ?? null),
+	};
+}

package/src/server/config.ts

@@ -426,6 +426,8 @@ export interface SafeSandboxConfiguration {
 		readonly kind: AiProviderKind;
 		readonly model: string;
 		readonly credentialFingerprint: string | null;
+		readonly baseURL?: string;
+		readonly resourceName?: string;
 	} | null;
 	readonly github: GitHubDeliveryConfiguration & {
 		readonly tokenFingerprint: string | null;
@@ -446,6 +448,12 @@ export function safeConfiguration(
 		byok: configuration.byok
 			? {
 					kind: configuration.byok.kind,
+					...(configuration.byok.baseURL
+						? { baseURL: configuration.byok.baseURL }
+						: {}),
+					...(configuration.byok.resourceName
+						? { resourceName: configuration.byok.resourceName }
+						: {}),
 					model: configuration.byok.model,
 					credentialFingerprint: secretFingerprint(
 						configuration.byok.credential,

package/src/server/reload-log.ts

@@ -0,0 +1,68 @@
+import { relative } from 'node:path';
+import type { ViteDevServer } from 'vite';
+
+/* Watch notifications describe source changes, not successful preview builds.
+   Collect one bounded burst so atomic saves do not flood the terminal. */
+export function watchSandboxReloads(
+	server: Pick<ViteDevServer, 'watcher' | 'httpServer'>,
+	appRoot: string,
+	write: (message: string) => void,
+	verbose = false,
+): () => void {
+	const groups = new Map<string, Set<string>>();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let pendingFiles = 0;
+	const flush = () => {
+		if (timer) clearTimeout(timer);
+		timer = undefined;
+		for (const [label, files] of groups) {
+			if (verbose) {
+				for (const path of files) write(path);
+			} else {
+				write(
+					`${label} · ${files.size} ${files.size === 1 ? 'file' : 'files'} changed`,
+				);
+			}
+		}
+		groups.clear();
+		pendingFiles = 0;
+	};
+	const changed = (event: string, path: string) => {
+		if (!['add', 'change', 'unlink'].includes(event)) return;
+		const normalized = path.replaceAll('\\', '/');
+		const draft = normalized.match(
+			/\/(?:\.flowdular|\.coreloom)\/sandbox\/sessions\/([^/]+)\/workspace\/modules\/([^/]+)\//,
+		);
+		const local = relative(appRoot, path);
+		if (
+			!draft &&
+			(local === '..' || local.startsWith('../') || local.startsWith('..\\'))
+		)
+			return;
+		const label = draft
+			? `Draft ${draft[2]} (${draft[1]!.slice(0, 8)})`
+			: 'Sandbox';
+		const files = groups.get(label) ?? new Set<string>();
+		if (!files.has(path)) pendingFiles += 1;
+		files.add(path);
+		groups.set(label, files);
+		// Fixed window, not a reset-on-every-event debounce: continuous writes
+		// remain visible and retained notifications cannot grow without a flush.
+		if (!timer) {
+			timer = setTimeout(flush, 750);
+			timer.unref?.();
+		}
+		if (pendingFiles >= 256) flush();
+	};
+	const dispose = () => {
+		if (timer) clearTimeout(timer);
+		timer = undefined;
+		groups.clear();
+		pendingFiles = 0;
+		server.watcher.off('all', changed);
+		server.httpServer?.off('close', dispose);
+	};
+	server.watcher.on('all', changed);
+	server.httpServer?.once('close', dispose);
+	return dispose;
+}

package/src/server/routes.ts

@@ -1,3 +1,4 @@
+import { byokSettings } from './byok-settings.ts';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { ServerRoute, type Context } from '@octanejs/app-core';
@@ -665,6 +666,7 @@ export function createSandboxRoutes(
 		sessionId: string,
 		input: {
 			message: string;
+			freshContext?: boolean;
 			role?: string;
 			module?: string;
 			driver?: string;
@@ -866,7 +868,6 @@ export function createSandboxRoutes(
 				});
 				const value = await body(context.request);
 				const token = optionalText(value, 'platformToken', 4_096);
-				const byokCredential = optionalText(value, 'byokCredential', 16_384);
 				const githubToken = optionalText(value, 'githubToken', 16_384);
 				const configuration = runtime.configuration();
 				if (value.disconnect === true) {
@@ -999,6 +1000,11 @@ export function createSandboxRoutes(
 								}),
 					};
 				}
+				const byok = await byokSettings(
+					runtime.workspaceRoot,
+					value,
+					configuration.byok,
+				);
 				const connection = await runtime.update({
 					...(platformUrl === null ? {} : { platformUrl }),
 					...(token
@@ -1015,23 +1021,7 @@ export function createSandboxRoutes(
 					...(value.previewData === 'fixtures' || value.previewData === 'bridge'
 						? { previewData: value.previewData }
 						: {}),
-					...(value.byokKind === undefined
-						? {}
-						: {
-								byok: {
-									kind: text(value, 'byokKind', 40) as never,
-									model: text(value, 'byokModel', 160),
-									...(optionalText(value, 'byokResourceName', 160)
-										? { resourceName: text(value, 'byokResourceName', 160) }
-										: {}),
-									...(optionalText(value, 'byokBaseUrl', 2_048)
-										? { baseURL: text(value, 'byokBaseUrl', 2_048) }
-										: {}),
-									credential: byokCredential
-										? await sealSecret(runtime.workspaceRoot, byokCredential)
-										: (configuration.byok?.credential ?? null),
-								},
-							}),
+					...(byok === undefined ? {} : { byok }),
 					...(githubPatchRequested ? { github } : {}),
 					...(githubToken
 						? {
@@ -1537,6 +1527,7 @@ export function createSandboxRoutes(
 					sessionId,
 					{
 						message: text(value, 'message', 20_000),
+						freshContext: value.freshContext === true,
 						...(optionalText(value, 'role', 64)
 							? { role: text(value, 'role', 64) }
 							: {}),

package/src/server/turns.ts

@@ -90,6 +90,7 @@ export interface TurnContext {
 }
 
 export interface TurnInput {
+	readonly freshContext?: boolean;
 	readonly sessionId: string;
 	readonly message: string;
 	readonly role?: string;
@@ -687,7 +688,33 @@ export async function* runTurn(
 	);
 
 	const history = historyFrom(await readChat(context.workspaceRoot, session));
-	const resumeId = session.resumeIds[driverId] ?? null;
+	// Provider conversations retain instructions and tool history. Reuse one only
+	// while its role, module, skill, write ceiling, specification and model match.
+	const resumePrefix = `${driverId}:scope:`;
+	const resumeKey =
+		resumePrefix +
+		createHash('sha256')
+			.update(
+				JSON.stringify([
+					instruction,
+					active.specHash ?? null,
+					session.model ?? context.configuration.driverModel,
+				]),
+			)
+			.digest('hex');
+	const previousKeys = Object.keys(session.resumeIds).filter(
+		(key) => key === driverId || key.startsWith(resumePrefix),
+	);
+	const resumeId = input.freshContext
+		? null
+		: (session.resumeIds[resumeKey] ?? null);
+	if (input.freshContext || (!resumeId && previousKeys.length > 0)) {
+		yield await appendChatEntry(context.workspaceRoot, session, {
+			kind: 'system',
+			role: roleId,
+			text: `Starting fresh agent context for ${role.name} in ${active.id} with the current task and write scope. Draft files, approved specification and sandbox history are preserved; the agent receives the brief and recent messages.`,
+		});
+	}
 	let nextResumeId = resumeId;
 	let failed = false;
 	let closing = '';
@@ -709,7 +736,7 @@ export async function* runTurn(
 			systemInstruction: instruction,
 			prompt: attachmentNote ? `${attachmentNote}\n\n${message}` : message,
 			resumeId,
-			history: history.slice(0, -1),
+			history: [{ role: 'user', text: session.brief }, ...history.slice(0, -1)],
 			model: session.model,
 			signal: input.signal,
 		})) {
@@ -962,10 +989,12 @@ export async function* runTurn(
 		);
 	}
 
+	const resumeIds = { ...session.resumeIds };
+	// Retain at most one conversation per driver, including after many handoffs.
+	for (const key of previousKeys) delete resumeIds[key];
+	if (nextResumeId) resumeIds[resumeKey] = nextResumeId;
 	const updated = await updateSession(context.workspaceRoot, session.id, {
-		resumeIds: nextResumeId
-			? { ...session.resumeIds, [driverId]: nextResumeId }
-			: session.resumeIds,
+		resumeIds,
 		state: failed
 			? 'failed'
 			: handoff.kind === 'approval' || handoff.kind === 'question'