@huanlin/dsh-plugin-aigc-canvas 0.1.10 → 0.2.1

package/lib/index.js

@@ -1,24 +1,45 @@
-import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { basename, dirname, isAbsolute, join, sep } from "node:path";
 import { WebSocket, WebSocketServer } from "ws";
 import z from "@deepseek-ai/schemastery";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { readFileSync } from "node:fs";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
+//#region src/provider-shape.ts
+/**
+* Pure provider-id validation shared by the host half (Config / ProviderStore)
+* and the client settings page. Kept free of schemastery imports so the
+* client bundle (tsdown purity gate) can inline it.
+*
+* @module @huanlin/dsh-plugin-aigc-canvas/provider-shape
+*/
+/** Provider id pattern: lowercase letters, digits, hyphens; must start with a letter. */
+const PROVIDER_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/**
+* Validate a provider id.
+* @param id - candidate id (as typed into the settings page or passed to the store).
+* @returns an error message, or undefined when valid.
+*/
+function validateProviderId(id) {
+	if (id === "") return "provider id is required";
+	if (!PROVIDER_ID_PATTERN.test(id)) return `invalid provider id: ${JSON.stringify(id)} (must be lowercase, hyphenated, start with a letter)`;
+}
+//#endregion
 //#region src/config.ts
 /**
 * Serializable configuration and defaults for the AIGC canvas host half.
 * The `providers` array holds one or more AIGC provider configs (name /
-* endpoint / apiKey / instructions), editable at runtime through the DSH
-* GUI settings page; cordis.yml `config:` is the first-boot seed only.
+* endpoint / apiKey / instructions). Since dsh 0.1.7-rc.1 the editable
+* fields are `.volatile()` members of the entry's profile-owned Cordis
+* Config (DSH-0.1.7-J1-04): the composition `config:` in cordis.patch.yml is
+* the first-boot seed only, and runtime edits persist per profile under the
+* entry id `dsh-aigc-canvas` through the settings service.
 *
 * @module @huanlin/dsh-plugin-aigc-canvas/config
 */
-/** Provider id pattern: lowercase letters, digits, hyphens; must start with a letter. */
-const PROVIDER_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 /** Schemastery schema for the per-provider auth config. */
 const ProviderAuthSchema = z.object({
 	scheme: z.union([
@@ -41,7 +62,14 @@ const ProviderSchema = z.object({
 	}),
 	builtin: z.boolean().description("Whether this provider is a builtin seed (cordis.yml).").default(false)
 });
-/** Schemastery schema for the plugin configuration. */
+/**
+* Schemastery schema for the plugin's profile-owned Config.
+*
+* `providers` is `.volatile()` (dsh 0.1.7-rc.1 DSH-0.1.7-J1-04): the settings
+* service enumerates the entry's volatile fields for the configuration form,
+* and a committed edit updates the running reference in place. The numeric
+* knobs stay non-volatile (cordis.patch.yml seed only).
+*/
 const Config = z.object({
 	providers: z.array(ProviderSchema).description("One or more AIGC providers; the first is the default.").default([{
 		id: "stub",
@@ -54,7 +82,7 @@ const Config = z.object({
 			name: ""
 		},
 		builtin: true
-	}]),
+	}]).volatile(),
 	requestTimeoutMs: z.number().step(1).min(1e3).default(3e5),
 	mediaSizeLimit: z.number().step(1).min(1024).default(104857600)
 });
@@ -62,11 +90,19 @@ const Config = z.object({
 function isStubEndpoint(endpoint) {
 	return endpoint === "" || endpoint === "stub://aigc-backend";
 }
-/** Validate a provider id; returns an error message or undefined if valid. */
-function validateProviderId(id) {
-	if (id === "") return "provider id is required";
-	if (!PROVIDER_ID_PATTERN.test(id)) return `invalid provider id: ${JSON.stringify(id)} (must be lowercase, hyphenated, start with a letter)`;
-}
+/** The fallback stub provider seeded when no provider is configured at load. */
+const DEFAULT_STUB_PROVIDER = {
+	id: "stub",
+	name: "",
+	endpoint: "stub://aigc-backend",
+	apiKey: "",
+	instructions: "",
+	auth: {
+		scheme: "bearer",
+		name: ""
+	},
+	builtin: true
+};
 /** Migrate + resolve a single provider from config input. */
 function resolveProvider(p) {
 	const auth = p.auth ?? {};
@@ -83,21 +119,35 @@ function resolveProvider(p) {
 		builtin: p.builtin ?? false
 	};
 }
-/** Apply direct-call defaults after Loader schema validation has normally run. */
+/**
+* Normalize a raw provider list (the volatile reference's latest snapshot, a
+* legacy imported document, or a hand-edited override) into resolved
+* providers. Non-object entries are skipped; duplicate ids keep the first
+* occurrence (insertion order preserved).
+* @param raw - the raw list value.
+* @returns the resolved providers, in order, deduplicated by id.
+*/
+function resolveAigcProviders(raw) {
+	if (!Array.isArray(raw)) return [];
+	const byId = /* @__PURE__ */ new Map();
+	for (const item of raw) {
+		if (typeof item !== "object" || item === null || Array.isArray(item)) continue;
+		const resolved = resolveProvider(item);
+		if (!byId.has(resolved.id)) byId.set(resolved.id, resolved);
+	}
+	return [...byId.values()];
+}
+/**
+* Resolve the apply-time seed config (direct-call defaults after Loader
+* schema validation has normally run). The provider list reads the live
+* volatile reference; when it resolves empty at load, the default stub is
+* seeded so the tools always have one provider.
+* @param config - the entry config the Loader passed to `apply`.
+* @returns the fully defaulted seed settings.
+*/
 function resolveAigcConfig(config) {
-	const providers = (config?.providers ?? []).map(resolveProvider);
-	if (providers.length === 0) providers.push({
-		id: "stub",
-		name: "",
-		endpoint: "stub://aigc-backend",
-		apiKey: "",
-		instructions: "",
-		auth: {
-			scheme: "bearer",
-			name: ""
-		},
-		builtin: true
-	});
+	const providers = [...resolveAigcProviders(config?.providers?.get())];
+	if (providers.length === 0) providers.push(DEFAULT_STUB_PROVIDER);
 	return {
 		providers,
 		requestTimeoutMs: config?.requestTimeoutMs ?? 3e5,
@@ -107,184 +157,259 @@ function resolveAigcConfig(config) {
 //#endregion
 //#region src/provider-store.ts
 /**
-* In-memory provider store with CRUD + disk persistence. Holds the
-* canonical list of AIGC providers; tool registration and the settings-
-* page RPC share one instance per plugin fiber. Persisted to
-* `~/.dsh/aigc-canvas/providers.json` so restarts keep user-added
-* providers and instructions.
+* Mutable provider store. Owns the canonical provider list; tool
+* registration shares one instance per plugin fiber.
 *
-* @module @huanlin/dsh-plugin-aigc-canvas/provider-store
-*/
-/** Directory for persisted AIGC canvas state (under the DSH user dir). */
-const DATA_DIR = join(homedir(), ".dsh", "aigc-canvas");
-/** Path to the persisted providers JSON. */
-const PROVIDERS_JSON = join(DATA_DIR, "providers.json");
-/** Atomic write: mkdir + temp file + rename. */
-async function writeJsonAtomic$1(path, value) {
-	const tmp = `${path}.tmp-${process.pid}`;
-	try {
-		await mkdir(dirname(path), { recursive: true });
-		await writeFile(tmp, JSON.stringify(value, null, 2), "utf8");
-		await rename(tmp, path);
-	} catch {}
-}
-/**
-* Mutable provider store. Owns the canonical provider list; the backend
-* client map and RPC handlers share one instance per plugin fiber.
-*
-* Persistence: on construction the store loads `~/.dsh/aigc-canvas/
-* providers.json` (if present) and merges it over the cordis.yml seed —
-* persisted providers win, so user edits and deletions survive restarts.
-* Every mutation writes the list back to disk (fire-and-forget).
+* While no persistence face is attached the in-memory map is canonical
+* (headless mode). Once a face is attached, every read resolves through the
+* face's source and every mutation commits through `persist` before its
+* result is reported — the committed profile config is the single source of
+* truth.
 */
 var ProviderStore = class {
 	providers = /* @__PURE__ */ new Map();
-	dataPath;
-	/** Serializes disk writes so rapid mutations can't interleave. */
-	persistChain = Promise.resolve();
-	constructor(seed, dataPath = PROVIDERS_JSON) {
-		this.dataPath = dataPath;
-		const seedBuiltin = new Map(seed.map((p) => [p.id, p.builtin ?? false]));
-		const sources = loadPersistedSync(dataPath) ?? seed;
-		for (const p of sources) {
-			const resolved = {
-				id: p.id,
-				name: p.name ?? "",
-				endpoint: p.endpoint ?? "stub://aigc-backend",
-				apiKey: p.apiKey ?? "",
-				instructions: p.instructions ?? "",
-				auth: {
-					scheme: p.auth?.scheme ?? "bearer",
-					name: p.auth?.name ?? ""
-				},
-				builtin: seedBuiltin.get(p.id) ?? false
-			};
-			this.providers.set(resolved.id, resolved);
-		}
+	/** Optional persistence face; absent in headless mode. */
+	persistence;
+	/** @param seed - resolved seed providers (the composition layer). */
+	constructor(seed) {
+		for (const provider of seed) this.providers.set(provider.id, provider);
 	}
-	/** Snapshot of all providers, in insertion order. */
+	/**
+	* Attach a persistence face. Subsequent reads derive from the face's
+	* source and mutations commit through it.
+	* @param persistence - the read/write face over the entry's config.
+	*/
+	attachPersistence(persistence) {
+		this.persistence = persistence;
+	}
+	/** The committed provider list (insertion order; duplicates keep the first). */
+	committed() {
+		if (this.persistence === void 0) return [...this.providers.values()];
+		return resolveAigcProviders(this.persistence.source());
+	}
+	/** Snapshot of all providers, in order. */
 	list() {
-		return [...this.providers.values()];
+		return this.committed();
 	}
 	/** Look up one provider by id. */
 	get(id) {
-		return this.providers.get(id);
+		return this.committed().find((provider) => provider.id === id);
 	}
-	/** The default provider (first in insertion order); undefined if empty. */
+	/** The default provider (first in order); undefined if empty. */
 	defaultProvider() {
-		return this.providers.values().next().value;
+		return this.committed()[0];
 	}
 	/** Add a new provider. Returns failure for duplicate id or invalid shape. */
-	add(provider) {
+	async add(provider) {
 		const idError = validateProviderId(provider.id);
 		if (idError !== void 0) return {
 			ok: false,
 			error: idError
 		};
-		if (this.providers.has(provider.id)) return {
+		const committed = this.committed();
+		if (committed.some((p) => p.id === provider.id)) return {
 			ok: false,
 			error: `provider id already exists: ${provider.id}`
 		};
 		const stored = {
-			id: provider.id,
-			name: provider.name ?? "",
-			endpoint: provider.endpoint ?? "stub://aigc-backend",
-			apiKey: provider.apiKey ?? "",
-			instructions: provider.instructions ?? "",
-			auth: {
-				scheme: provider.auth?.scheme ?? "bearer",
-				name: provider.auth?.name ?? ""
-			},
+			...resolveStored(provider),
 			builtin: false
 		};
-		this.providers.set(stored.id, stored);
-		this.persist();
-		return {
-			ok: true,
-			providers: this.list()
-		};
+		return this.commit([...committed, stored]);
 	}
 	/** Update an existing provider. Returns failure if the id is unknown. */
-	update(provider) {
+	async update(provider) {
 		const idError = validateProviderId(provider.id);
 		if (idError !== void 0) return {
 			ok: false,
 			error: idError
 		};
-		const existing = this.providers.get(provider.id);
+		const committed = this.committed();
+		const existing = committed.find((p) => p.id === provider.id);
 		if (existing === void 0) return {
 			ok: false,
 			error: `provider id not found: ${provider.id}`
 		};
 		const stored = {
-			id: provider.id,
-			name: provider.name ?? "",
-			endpoint: provider.endpoint ?? "stub://aigc-backend",
-			apiKey: provider.apiKey ?? "",
-			instructions: provider.instructions ?? "",
+			...resolveStored(provider),
 			auth: {
 				scheme: provider.auth?.scheme ?? existing.auth.scheme,
 				name: provider.auth?.name ?? existing.auth.name
 			},
 			builtin: existing.builtin
 		};
-		this.providers.set(stored.id, stored);
-		this.persist();
-		return {
-			ok: true,
-			providers: this.list()
-		};
+		return this.commit(committed.map((p) => p.id === stored.id ? stored : p));
 	}
 	/**
 	* Replace a provider's usage instructions (called by the model's
 	* aigc_provider_set_instructions tool after it probes the API).
 	*/
-	setInstructions(id, instructions) {
-		const existing = this.providers.get(id);
-		if (existing === void 0) return {
+	async setInstructions(id, instructions) {
+		const committed = this.committed();
+		if (committed.find((p) => p.id === id) === void 0) return {
 			ok: false,
 			error: `provider id not found: ${id}`
 		};
-		const stored = {
-			...existing,
+		return this.commit(committed.map((p) => p.id === id ? {
+			...p,
 			instructions
-		};
-		this.providers.set(stored.id, stored);
-		this.persist();
-		return {
-			ok: true,
-			providers: this.list()
-		};
+		} : p));
 	}
 	/** Remove a provider. Returns failure for unknown id. */
-	remove(id) {
-		if (!this.providers.delete(id)) return {
+	async remove(id) {
+		const committed = this.committed();
+		if (!committed.some((p) => p.id === id)) return {
 			ok: false,
 			error: `provider id not found: ${id}`
 		};
-		this.persist();
-		return {
-			ok: true,
-			providers: this.list()
-		};
+		return this.commit(committed.filter((p) => p.id !== id));
 	}
 	/**
-	* Persist the current provider list to disk (fire-and-forget, serialized).
-	* Only the user-editable fields are written; `builtin` is re-derived from
-	* the seed on load. Failures are swallowed — the in-memory state stays
-	* canonical. Each call snapshots the CURRENT list, so a burst of mutations
-	* ends with the latest state on disk.
+	* Commit a replacement list: through the persistence face when attached
+	* (the post-commit committed value is reported), otherwise into the
+	* in-memory map. A refused persistence write leaves the committed state
+	* untouched and reports `{ ok: false }`.
 	*/
-	persist() {
-		const snapshot = [...this.providers.values()].map(({ builtin: _b, ...rest }) => rest);
-		this.persistChain = this.persistChain.then(() => writeJsonAtomic$1(this.dataPath, snapshot)).catch(() => {});
+	async commit(next) {
+		if (this.persistence === void 0) {
+			this.providers.clear();
+			for (const provider of resolveAigcProviders(next)) this.providers.set(provider.id, provider);
+			return {
+				ok: true,
+				providers: this.list()
+			};
+		}
+		try {
+			await this.persistence.persist(next);
+			return {
+				ok: true,
+				providers: this.list()
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
 	}
 };
-/** Read the persisted providers JSON; returns null when absent/unreadable. */
-function loadPersistedSync(dataPath) {
+/** Normalize one mutation input into its resolved stored shape. */
+function resolveStored(provider) {
+	const auth = provider.auth ?? {};
+	return {
+		id: provider.id,
+		name: provider.name ?? "",
+		endpoint: provider.endpoint ?? "stub://aigc-backend",
+		apiKey: provider.apiKey ?? "",
+		instructions: provider.instructions ?? "",
+		auth: {
+			scheme: auth.scheme ?? "bearer",
+			name: auth.name ?? ""
+		},
+		builtin: provider.builtin ?? false
+	};
+}
+//#endregion
+//#region src/settings.ts
+/**
+* settings.ts — host-side bridge between the entry's profile-owned Config
+* and the plugin's provider store, plus the one-time legacy import.
+*
+* dsh 0.1.7-rc.1 (`DSH-0.1.7-J1-04`) removed the namespace-registration API:
+* a plugin declares a Cordis `Config` (see `config.ts`, `providers` marked
+* `.volatile()`) and only declares the presentation policy for its own page.
+* The bridge exposes:
+*
+*   - `source()`: the raw committed provider list, read from the live
+*     volatile reference on every call, so the tools and RPC surface always
+*     serve the latest accepted value (including edits written by other
+*     surfaces through the settings service).
+*   - `persist(providers)`: commits a replacement list through the settings
+*     service, which writes it into the active profile's `cordis.patch.yml`
+*     under the entry id `dsh-aigc-canvas` and updates the live reference
+*     in place.
+*   - `writable`: whether a settings provider is mounted.
+*
+* On first mount the legacy persistence file of pre-0.1.11 versions
+* (`~/.dsh/aigc-canvas/providers.json`) is imported once (the file is
+* renamed before the import, so a partial import never repeats) and left
+* behind as `providers.json.imported`.
+*
+* @module @huanlin/dsh-plugin-aigc-canvas/settings
+*/
+/** Profile entry id under which the provider list persists (`cordis.patch.yml`). */
+const SETTINGS_NAMESPACE = "dsh-aigc-canvas";
+/** Default legacy persistence path (pre-0.1.11 custom file). */
+const LEGACY_PROVIDERS_JSON = join(homedir(), ".dsh", "aigc-canvas", "providers.json");
+/**
+* Declare the plugin's settings presentation policy and return the bridge.
+*
+* `auto: false` suppresses the schema-generated page: this plugin ships its
+* own editor as the bundle row's `plugins.row.config` entry on the Plugins
+* page.
+*
+* @param ctx - host context.
+* @param entry - the entry's volatile Cordis config.
+* @param options - optional overrides (legacy import path, attach callback).
+* @param options.legacyPath - path of the legacy providers file to import once.
+* @param options.onReady - invoked when the settings provider is mounted (before the legacy import settles).
+* @returns the bridge the provider store consumes.
+*/
+function installAigcSettings(ctx, entry, options = {}) {
+	let settings;
+	ctx.inject(["settings"], (sctx) => {
+		settings = sctx.settings;
+		sctx.effect(() => sctx.settings.configure({ auto: false }, ctx.fiber));
+		options.onReady?.();
+		importLegacyProviders(options.legacyPath ?? LEGACY_PROVIDERS_JSON, sctx.settings, ctx.logger);
+		return () => {
+			settings = void 0;
+		};
+	});
+	return {
+		source: () => {
+			const raw = entry?.providers?.get();
+			return Array.isArray(raw) ? raw : [];
+		},
+		persist: async (providers) => {
+			if (settings === void 0) return;
+			await settings.update(SETTINGS_NAMESPACE, { providers });
+		},
+		get writable() {
+			return settings !== void 0;
+		}
+	};
+}
+/**
+* Import the legacy `providers.json` once: rename the file first (so a
+* partial import never repeats), then commit the parsed list into the
+* profile entry config. Failures are logged, never thrown.
+*
+* @param path - the legacy file path.
+* @param settings - the mounted settings service.
+* @param logger - the host logger.
+*/
+async function importLegacyProviders(path, settings, logger) {
 	try {
-		const raw = readFileSync(dataPath, "utf8");
-		const parsed = JSON.parse(raw);
+		if (!existsSync(path)) return;
+		const imported = `${path}.imported`;
+		await rm(imported, { force: true });
+		await rename(path, imported);
+		const providers = loadLegacyProviders(imported);
+		if (providers === null) return;
+		await settings.update(SETTINGS_NAMESPACE, { providers });
+		logger.info(`dsh-aigc-canvas: imported ${imported} into the profile entry config`);
+	} catch (error) {
+		logger.warn("dsh-aigc-canvas: legacy providers.json import failed:", error);
+	}
+}
+/**
+* Read a legacy providers JSON document; null when absent or unreadable.
+* Mirrors the pre-0.1.11 reader (defensive per-item coercion).
+*/
+function loadLegacyProviders(path) {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
 		if (!Array.isArray(parsed)) return null;
 		const providers = [];
 		for (const item of parsed) {
@@ -1903,7 +2028,7 @@ function mimeFromExt(filePath) {
 *
 * @param ctx - host plugin context (carries the tools service).
 * @param getProvider - live provider getter (takes optional provider id).
-* @param setInstructions - persists usage instructions for one provider (the host's ProviderStore).
+* @param setInstructions - persists usage instructions for one provider (the host's ProviderStore; resolves after the profile-config commit).
 * @param listProviders - returns info for all providers (for aigc_get_provider_info).
 * @param canvas - the canvas registry service (host-owned state).
 * @param resolveCwd - live cwd resolver for one session id.
@@ -2238,16 +2363,16 @@ function registerTools(ctx, getProvider, setInstructions, listProviders, canvas,
 			},
 			render: textRender((v) => `Saved usage instructions for provider "${v.provider_id}".`)
 		},
-		execute: (args) => {
+		execute: async (args) => {
 			if (typeof args.provider_id !== "string" || args.provider_id === "") throw new AigcError("bad-request", "provider_id is required");
 			if (typeof args.instructions !== "string" || args.instructions === "") throw new AigcError("bad-request", "instructions is required");
 			getProvider(args.provider_id);
-			const result = setInstructions(args.provider_id, args.instructions);
+			const result = await setInstructions(args.provider_id, args.instructions);
 			if (!result.ok) throw new AigcError("bad-request", result.error ?? "cannot save instructions");
-			return Promise.resolve({
+			return {
 				ok: true,
 				provider_id: args.provider_id
-			});
+			};
 		}
 	}));
 	register(defineTool({
@@ -2721,10 +2846,10 @@ async function saveResponseToSession(content, ext, sessionId, cwd) {
 //#region src/index.ts
 /**
 * @huanlin/dsh-plugin-aigc-canvas host half: the canvas registry, the provider
-* store (config + per-provider usage instructions), the fenced
-* `/aigc-canvas/api/*` JSON API (provider CRUD + canvas.list/move) +
-* `/aigc-canvas/file` media route + `/aigc-canvas/ws/canvas` push WebSocket,
-* and the `ctx.aigcCanvas` service.
+* store (the entry's profile-owned Config + per-provider usage
+* instructions), the fenced `/aigc-canvas/api/*` JSON API
+* (canvas.list/move/delete/upload) + `/aigc-canvas/file` media route +
+* `/aigc-canvas/ws/canvas` push WebSocket, and the `ctx.aigcCanvas` service.
 *
 * Model-facing tools (see tools.ts): aigc_get_provider_info, the generic
 * aigc_http_request (auto-attaches endpoint + apiKey per provider config),
@@ -2732,10 +2857,13 @@ async function saveResponseToSession(content, ext, sessionId, cwd) {
 * probing the API), aigc_canvas_place / aigc_canvas_link / aigc_canvas_unlink
 * (put files on the free canvas), and aigc_canvas_list_elements.
 *
-* Provider config is editable at runtime: the settings page posts to
-* `/aigc-canvas/api/providers.add|update|remove`, which updates the
-* ProviderStore. Tools read the provider through a getter so they always
-* see the latest configuration.
+* Provider config is profile-owned (dsh 0.1.7-rc.1 DSH-0.1.7-J1-04): the
+* `providers` field of the entry's Cordis Config is `.volatile()` and
+* persists per profile in `cordis.patch.yml` under the entry id
+* `dsh-aigc-canvas`. The settings page reads/writes it through the client
+* `configForms` transport (DSH-0.1.7-J1-27); the model's instruction tool
+* writes through the same settings bridge. Tools read the provider through
+* a getter so they always see the latest committed configuration.
 */
 /** Plugin identity for cordis.yml rows. */
 const name = "dsh-aigc-canvas";
@@ -2764,13 +2892,6 @@ function sessionCwdOf(ctx, sessionId) {
 	if (headerCwd !== void 0 && headerCwd !== "") return headerCwd;
 	throw new AigcError("not-found", `session "${sessionId}" is not registered or has no cwd yet`, 404);
 }
-/** Convert a resolved config to the runtime global settings wire shape. */
-function toGlobalSettings(resolved) {
-	return {
-		requestTimeoutMs: resolved.requestTimeoutMs,
-		mediaSizeLimit: resolved.mediaSizeLimit
-	};
-}
 /**
 * Build a minimal user-role message and inject it into the agent's
 * next-step context (non-waking). Used to notify the model of user-
@@ -2825,7 +2946,7 @@ function kindForExtension(ext) {
 	return "prompt";
 }
 /** Build the JSON API method table. */
-function buildApi(ctx, canvas, store, getResolved) {
+function buildApi(ctx, canvas, getMediaLimit) {
 	return {
 		"canvas.list": async (payload) => {
 			const sessionId = requireString(payload, "sessionId");
@@ -2862,7 +2983,7 @@ function buildApi(ctx, canvas, store, getResolved) {
 			const mediaBase64 = typeof record?.mediaBase64 === "string" ? record.mediaBase64 : "";
 			if (fileName === "" || mediaBase64 === "") throw new AigcError("bad-request", "fileName and mediaBase64 are required strings");
 			const bytes = Buffer.from(mediaBase64, "base64");
-			if (bytes.byteLength > getResolved().mediaSizeLimit) throw new AigcError("fs-error", `uploaded file too large (${bytes.byteLength} bytes)`);
+			if (bytes.byteLength > getMediaLimit()) throw new AigcError("fs-error", `uploaded file too large (${bytes.byteLength} bytes)`);
 			const cwd = sessionCwdOf(ctx, sessionId);
 			const dir = canvasDirFor(cwd, sessionId);
 			await mkdir(dir, { recursive: true });
@@ -2887,36 +3008,6 @@ function buildApi(ctx, canvas, store, getResolved) {
 				ok: true,
 				element: el
 			};
-		},
-		"providers.list": () => {
-			return { providers: store.list() };
-		},
-		"providers.add": (payload) => {
-			const provider = payload?.provider;
-			if (provider === null || typeof provider !== "object" || Array.isArray(provider)) throw new AigcError("bad-request", "expected { provider: AigcProvider }");
-			const result = store.add(provider);
-			if (!result.ok) throw new AigcError("bad-request", result.error);
-			return { providers: result.providers };
-		},
-		"providers.update": (payload) => {
-			const provider = payload?.provider;
-			if (provider === null || typeof provider !== "object" || Array.isArray(provider)) throw new AigcError("bad-request", "expected { provider: AigcProvider }");
-			const result = store.update(provider);
-			if (!result.ok) throw new AigcError("bad-request", result.error);
-			return { providers: result.providers };
-		},
-		"providers.remove": (payload) => {
-			const id = payload?.id;
-			if (typeof id !== "string" || id === "") throw new AigcError("bad-request", "expected { id: string }");
-			const result = store.remove(id);
-			if (!result.ok) throw new AigcError("bad-request", result.error);
-			return { providers: result.providers };
-		},
-		"config.get": () => {
-			return {
-				...toGlobalSettings(getResolved()),
-				providers: store.list()
-			};
 		}
 	};
 }
@@ -2929,11 +3020,9 @@ function apply(ctx, config) {
 	const canvas = createAigcCanvasService((sessionId) => sessionCwdOf(ctx, sessionId), mediaLimit);
 	ctx.provide("aigcCanvas", canvas);
 	const store = new ProviderStore(resolved.providers);
-	const getResolved = () => ({
-		providers: store.list(),
-		requestTimeoutMs: resolved.requestTimeoutMs,
-		mediaSizeLimit: resolved.mediaSizeLimit
-	});
+	const bridge = installAigcSettings(ctx, config, { onReady: () => {
+		store.attachPersistence(bridge);
+	} });
 	const getProvider = (providerId) => {
 		if (providerId !== void 0 && providerId !== "") {
 			const provider = store.get(providerId);
@@ -2956,7 +3045,7 @@ function apply(ctx, config) {
 			isDefault: p.id === defaultId
 		}));
 	};
-	const api = buildApi(ctx, canvas, store, getResolved);
+	const api = buildApi(ctx, canvas, mediaLimit);
 	ctx.effect(() => ctx.webServer.register({
 		kind: "prefix",
 		path: "/aigc-canvas/api",
@@ -3103,4 +3192,4 @@ async function attachCanvasPush(canvas, ws, req) {
 	}
 }
 //#endregion
-export { Config, apply, inject, name };
+export { Config, SETTINGS_NAMESPACE, apply, inject, name };