feat(byoc): runtime config, sessions and vaults updates

Change-Id: I5d340bb58f1d0d9a68607024aa49fe0b37c1eab6
Co-developed-by: Qoder <noreply@qoder.com>

Author: heimanba

apps/server/src/lib/build-runtime-config.ts

@@ -33,6 +33,10 @@ export async function buildRuntimeConfig(): Promise<LoadedProjectConfig> {
 	// Every provider provisions a cloud sandbox environment; bailian additionally installs
 	// `bailian-cli` in it. The vault is provider-conditional: bailian holds its DASHSCOPE_API_KEY;
 	// other providers currently define no vault.
+	//
+	// Metadata stamps (`agents.base` / `agents.vault`) let the webui identify managed base
+	// resources via remote listing (findBaseEnvironment / findBaseVault), complementing the
+	// state-tracked identity the plan/apply engine provides.
 	const vaults = vault
 		? {
 				[vault.name]: {
@@ -45,13 +49,15 @@ export async function buildRuntimeConfig(): Promise<LoadedProjectConfig> {
 						secret_value: requireEnv(cred.secret_name),
 						...(cred.networking ? { networking: cred.networking } : {}),
 					})),
+					metadata: { "agents.vault": "true" },
 				},
 			}
 		: {};
 	const environments = {
 		[environment.name]: {
 			...(environment.description ? { description: environment.description } : {}),
 			config: environment.config,
+			metadata: { "agents.base": "true" },
 		},
 	};
 

apps/server/src/lib/state-scope.ts

@@ -1,16 +1,75 @@
-import { resolve } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
 import { LocalFileStateBackend, type StateScope } from "@openagentpack/sdk";
 import { RUNTIME_PROJECT_NAME } from "@/lib/build-runtime-config";
 
-// Historical on-disk state anchor. Previously derived via deriveStatePath() from the
-// demo file examples/bailian/bailian-cli/agents.yaml → agents.state.json. We pin the default
-// to that exact location so previously provisioned remote_ids (agents/vault/environment)
-// keep resolving and are not re-created. Override with AGENTS_STATE_PATH.
-const DEFAULT_STATE_PATH = "examples/bailian/bailian-cli/agents.state.json";
+/**
+ * Default playground state lives in the user home directory, alongside the
+ * provider config (~/.agents/config.json). This avoids colliding with CLI
+ * example configs that happen to live in the repo's examples/ directory.
+ *
+ * Override with AGENTS_STATE_PATH for custom deployment layouts.
+ */
+const DEFAULT_STATE_PATH = join(homedir(), ".agents", "playground.state.json");
+
+/**
+ * Legacy state path. Before this migration the server stored its state inside
+ * the repo's example directory. We migrate it once so previously-provisioned
+ * remote_ids are preserved.
+ */
+const LEGACY_STATE_PATH = "examples/bailian/bailian-cli/agents.state.json";
+
+let migrationChecked = false;
+
+/**
+ * One-time migration: if the legacy state file exists and the new default does
+ * not, copy it over and log a warning. Idempotent — subsequent calls after a
+ * successful migration (or when no migration is needed) are no-ops. A failed
+ * copy allows retry on the next call so transient I/O errors don't permanently
+ * disable migration for the process lifetime.
+ */
+function ensureMigrated(newPath: string, cwd: string): void {
+	if (migrationChecked) return;
+
+	if (existsSync(newPath)) {
+		migrationChecked = true;
+		return;
+	}
+	const legacyPath = resolve(cwd, LEGACY_STATE_PATH);
+	if (!existsSync(legacyPath)) {
+		migrationChecked = true;
+		return;
+	}
+
+	try {
+		mkdirSync(dirname(newPath), { recursive: true });
+		copyFileSync(legacyPath, newPath);
+		// Rename the legacy file so a version rollback won't silently read stale state.
+		try {
+			renameSync(legacyPath, `${legacyPath}.migrated`);
+		} catch {
+			// Non-fatal: the copy succeeded, state is in the new location.
+		}
+		migrationChecked = true;
+		console.warn(
+			`[state] Migrated playground state from legacy path:\n` +
+				`         ${legacyPath}\n` +
+				`       → ${newPath}\n` +
+				`       The legacy file has been renamed to ${legacyPath}.migrated.`,
+		);
+	} catch (error) {
+		// Don't set migrationChecked — allow retry on next call.
+		console.warn(`[state] Failed to migrate legacy state file: ${error instanceof Error ? error.message : error}`);
+	}
+}
 
 export function resolveStatePath(env: NodeJS.ProcessEnv = process.env, cwd: string = process.cwd()): string {
 	const configured = env.AGENTS_STATE_PATH?.trim();
-	return configured ? resolve(cwd, configured) : resolve(cwd, DEFAULT_STATE_PATH);
+	if (configured) return resolve(cwd, configured);
+
+	ensureMigrated(DEFAULT_STATE_PATH, cwd);
+	return DEFAULT_STATE_PATH;
 }
 
 export function deriveWebUiStateScope(): StateScope {

apps/server/src/routes/vaults.ts

@@ -68,8 +68,8 @@ vaultsRoute.openapi(createVaultRoute, async (c) => {
 	const secretValue = key ?? (primarySecret ? requireEnv(primarySecret) : "");
 	const vault = await withAgentRuntime(DEFAULT_AGENT_ID, (ctx) =>
 		createCloudVault(ctx, name, {
-			// display_name carries the base-vault identity (Agents/secrets) — a vault has no
-			// separate `name` field, so findBaseVault nets it by display_name + the stamp.
+			// display_name is used as the vault's human-readable label on the provider.
+			// findBaseVault identifies the managed vault by its metadata stamp (agents.vault).
 			display_name: name,
 			metadata,
 			credentials: structure.credentials.map((cred) => ({

apps/server/src/schemas/sessions.ts

@@ -38,7 +38,7 @@ export const SessionDeleteResponseSchema = z
 	})
 	.openapi("SessionDeleteResponse");
 
-// Mode A REST request ergonomics (server-owned input, not the shared DTO).
+// REST request ergonomics (server-owned input, not the shared DTO).
 export const SessionsQuerySchema = z.object({
 	// Non-numeric values resolve to `undefined` so the handler clamps to a
 	// default instead of the request being rejected with a 400.
@@ -71,8 +71,7 @@ export const SessionParamsSchema = z.object({
 export const CreateSessionBodySchema = z.object({
 	agentId: z.string(),
 	prompt: z.string().min(1),
-	// Required: a session must be pinned to a cloud environment (sandbox). Both transports
-	// enforce this so Mode A (REST/OpenAPI) and Mode B (console) reject env-less creates.
+	// Required: a session must be pinned to a cloud environment (sandbox).
 	environmentId: z.string().min(1),
 	// Optional: cloud vault ids to bind a user-supplied credential so the sandbox receives it.
 	// Top-level binding shape matches the console createSession.

apps/server/src/schemas/vaults.ts

@@ -10,9 +10,8 @@ export const CloudVaultsResponseSchema = z.object({
 export const CreateVaultBodySchema = z.object({
 	name: z.string().min(1),
 	metadata: z.record(z.string(), z.string()).optional(),
-	// The DASHSCOPE_API_KEY stored as the vault's credential secret value. Optional: Mode B
-	// supplies the user's key; Mode A (local) omits it and the server injects it from its own
-	// DASHSCOPE_API_KEY env. (Mode B never reaches this REST route — it goes via console RPC.)
+	// The DASHSCOPE_API_KEY stored as the vault's credential secret value. Optional:
+	// when omitted the server injects it from its own DASHSCOPE_API_KEY env.
 	key: z.string().min(1).optional(),
 });
 

apps/server/src/services/agents/catalog.ts

@@ -3,6 +3,7 @@ import {
 	DEFAULT_PLAYBOOK_PROVIDER,
 	getDefaultPlaybook,
 	getPlaybook,
+	getVaultProfile,
 	type PlaybookTemplate,
 	type ResolvedPlaybook,
 	resolvePlaybookModel,
@@ -80,9 +81,10 @@ export function compileAgentRuntime(
 	const config = cloneConfig(baseConfig);
 	const resolved = resolveSeedPlaybook(effectiveId, provider);
 	const runtimeAgentId = resolved.agent.name;
-	const built = buildAgentDecl(undefined, toAgentBuildInput(resolved, provider, modelOverride));
-	// The agent declares neither environment nor vault: base resources are provisioned eagerly
-	// and bound per-session via explicit environment_id + vault_ids.
+	const built = buildAgentDecl(undefined, toAgentBuildInput(resolved, provider, baseConfig, modelOverride));
+	// The agent declares environment and vault so syncAgentResources manages them
+	// through the plan/apply engine — giving base resources state tracking, drift
+	// detection, and the same content-hash identity as agent/skill resources.
 
 	config.agents = {
 		...(config.agents ?? {}),
@@ -154,12 +156,45 @@ export function computeAgentConfigHash(config: ResolvedProjectConfig, agentId: s
 	return createHash("sha256").update(stableStringify({ agentId, config })).digest("hex").slice(0, 16);
 }
 
-function toAgentBuildInput(resolved: ResolvedPlaybook, provider: string, modelOverride?: string): AgentBuildInput {
+function toAgentBuildInput(
+	resolved: ResolvedPlaybook,
+	provider: string,
+	baseConfig: ResolvedProjectConfig,
+	modelOverride?: string,
+): AgentBuildInput {
 	const model = resolvePlaybookModel(resolved, provider, modelOverride);
+	// Resolve environment and vault names from the assembled config so the compiled
+	// agent declares them. This lets syncAgentResources manage base resources
+	// through the plan/apply engine, giving them state tracking and drift detection.
+	// Invariant: buildRuntimeConfig produces exactly one environment (and at most one
+	// vault for providers that need credentials). If this assumption breaks, the agent
+	// would silently bind the wrong resource — fail fast instead.
+	const envKeys = Object.keys(baseConfig.environments ?? {});
+	if (envKeys.length !== 1) {
+		throw new Error(
+			`Expected exactly 1 environment in runtime config, got ${envKeys.length}. ` +
+				`The agent compile path assumes a single base environment per provider.`,
+		);
+	}
+	const environmentName = envKeys[0]!;
+	const vaultProfile = getVaultProfile(provider);
+	let vaultName: string | undefined;
+	if (vaultProfile) {
+		const vaultKeys = Object.keys(baseConfig.vaults ?? {});
+		if (vaultKeys.length !== 1) {
+			throw new Error(
+				`Expected exactly 1 vault in runtime config for provider '${provider}', got ${vaultKeys.length}. ` +
+					`The agent compile path assumes a single base vault per provider.`,
+			);
+		}
+		vaultName = vaultKeys[0]!;
+	}
 	return {
 		description: resolved.agent.description,
 		model,
 		instructions: resolved.agent.system,
+		environment: environmentName,
+		vault: vaultName,
 		provider,
 		builtinTools: resolved.agent.builtinTools,
 		skills: resolved.agent.skills.map((skill) =>

apps/server/src/services/files/upload.ts

@@ -47,8 +47,7 @@ export async function listUserFiles(): Promise<ProviderFileInfo[]> {
 
 /**
  * Resolve a short-lived presigned download URL for a file (e.g. an agent-delivered artifact).
- * Throws when the resolved provider has no download endpoint (bailian/claude); the webui's Mode A
- * transport surfaces that as an error, while Mode B never calls this route.
+ * Throws when the resolved provider has no download endpoint (bailian/claude).
  */
 export async function getUserFileDownloadUrl(id: string): Promise<{ url: string; expires_at?: string }> {
 	return withAgentRuntime(DEFAULT_AGENT_ID, async (ctx, compiled) => {

apps/server/src/services/sessions/playbook-session-adapter/index.ts

@@ -26,10 +26,10 @@ import {
 	sendPlaybookSessionMessage,
 } from "./sessions";
 
-export type { ModeAPlaybookSessionDetail } from "./sessions";
+export type { PlaybookSessionDetail } from "./sessions";
 
-export function createModeAPlaybookSessionRuntime() {
-	return createPlaybookSessionRuntime<ModeAPlaybookSessionDetail, ProviderSessionEvent, Session, RemotePlaybookAgent>({
+export function createServerPlaybookSessionRuntime() {
+	return createPlaybookSessionRuntime<PlaybookSessionDetail, ProviderSessionEvent, Session, RemotePlaybookAgent>({
 		identity: {
 			appId: getPlaybookAppId(),
 			expectedAgentName: getSeedPlaybookAgentName,
@@ -95,4 +95,4 @@ export function createModeAPlaybookSessionRuntime() {
 	});
 }
 
-type ModeAPlaybookSessionDetail = import("./sessions").ModeAPlaybookSessionDetail;
+type PlaybookSessionDetail = import("./sessions").PlaybookSessionDetail;

apps/server/src/services/sessions/playbook-session-adapter/sessions.ts

@@ -16,26 +16,26 @@ import { withAgentRuntime } from "@/services/runtime-factory";
 import { createEventBuffer, seedCompletedBuffer } from "@/services/sessions/event-buffer";
 import { sortByUpdatedDesc, toSession } from "./dto";
 
-export type ModeAPlaybookSessionDetail = {
+export type PlaybookSessionDetail = {
 	session: Session;
 	events: ProviderSessionEvent[];
 	eventsNextPageToken?: string;
 };
 
-export type ModeASessionEventsPage = {
+export type SessionEventsPage = {
 	events: ProviderSessionEvent[];
 	eventsNextPageToken?: string;
 };
 
-type ModeAListPlaybookSessionsInput = {
+type ListPlaybookSessionsInput = {
 	playbookId?: string;
 	remoteAgentId?: string;
 	limit?: number;
 	pageToken?: string;
 };
 
 export async function listPlaybookSessions(
-	input: ModeAListPlaybookSessionsInput,
+	input: ListPlaybookSessionsInput,
 ): Promise<{ sessions: Session[]; nextPageToken?: string }> {
 	const limit = input.limit ?? 50;
 	const page = input.pageToken?.trim() || undefined;
@@ -77,7 +77,7 @@ async function listProviderSessionEventsPage(
 	sessionId: string,
 	provider: string,
 	options: { pageToken?: string; limit?: number } = {},
-): Promise<ModeASessionEventsPage> {
+): Promise<SessionEventsPage> {
 	const limit = options.limit ?? 100;
 	const eventList = await listSessionEvents(ctx, sessionId, {
 		provider,
@@ -96,7 +96,7 @@ export async function listProviderSessionEvents(
 	agentId = DEFAULT_AGENT_ID,
 	pageToken?: string,
 	limit?: number,
-): Promise<ModeASessionEventsPage> {
+): Promise<SessionEventsPage> {
 	const catalogAgentId = getSessionAgent(agentId) ? agentId : DEFAULT_AGENT_ID;
 	return withAgentRuntime(catalogAgentId, async (ctx, compiled) => {
 		const agent = getAgent(ctx, compiled.agentId);
@@ -107,7 +107,7 @@ export async function listProviderSessionEvents(
 export async function readProviderSessionDetail(
 	sessionId: string,
 	agentId = DEFAULT_AGENT_ID,
-): Promise<ModeAPlaybookSessionDetail> {
+): Promise<PlaybookSessionDetail> {
 	const catalogAgentId = getSessionAgent(agentId) ? agentId : DEFAULT_AGENT_ID;
 	return withAgentRuntime(catalogAgentId, async (ctx, compiled) => {
 		const agent = getAgent(ctx, compiled.agentId);

apps/server/src/services/sessions/runner.ts

@@ -16,8 +16,8 @@ import {
 import { DEFAULT_AGENT_ID, getSessionAgent } from "@/services/agents/catalog";
 import { loadAgentRuntimeInput, withAgentRuntime } from "@/services/runtime-factory";
 import {
-	createModeAPlaybookSessionRuntime,
-	type ModeAPlaybookSessionDetail,
+	createServerPlaybookSessionRuntime,
+	type PlaybookSessionDetail,
 } from "@/services/sessions/playbook-session-adapter";
 import { listProviderSessionEvents } from "@/services/sessions/playbook-session-adapter/sessions";
 
@@ -43,9 +43,9 @@ export async function updatePlaybookAgentModel(slug: string, model: string): Pro
 import { createEventBuffer, seedCompletedBuffer } from "@/services/sessions/event-buffer";
 
 /** A session plus its raw provider events (events are mapped to the contract at the route boundary). */
-export type SessionWithEvents = ModeAPlaybookSessionDetail;
+export type SessionWithEvents = PlaybookSessionDetail;
 
-const playbookSessionRuntime = createModeAPlaybookSessionRuntime();
+const playbookSessionRuntime = createServerPlaybookSessionRuntime();
 
 export async function listSessionsForAgent(input: {
 	agentId?: string;