@vantran-se/openchamber-web 1.22.1 → 1.23.0

package/server/lib/openchamber-sessions/routes.js

@@ -253,6 +253,40 @@ const latestCompletedAssistantMessageID = async ({ client, sessionID, directory
   return asNonEmptyString(latest?.id);
 };
 
+/**
+ * Upper bound on one archive batch.
+ *
+ * The batch is applied one session at a time against OpenCode, so an unbounded
+ * list would hold a request open for as long as the list is large. Callers with
+ * more sessions than this send several batches and keep their own partial
+ * results.
+ */
+const MAX_ARCHIVE_BATCH = 500;
+
+const parseArchiveRequest = (payload) => {
+  const rawIds = payload?.ids;
+  if (!Array.isArray(rawIds) || rawIds.length === 0) {
+    return { ok: false, error: 'ids must be a non-empty array of session ids' };
+  }
+  if (rawIds.length > MAX_ARCHIVE_BATCH) {
+    return { ok: false, error: `ids must contain at most ${MAX_ARCHIVE_BATCH} session ids` };
+  }
+
+  const ids = [];
+  for (const value of rawIds) {
+    const id = asNonEmptyString(value);
+    if (!id) return { ok: false, error: 'ids must contain non-empty session ids' };
+    ids.push(id);
+  }
+
+  const archivedAt = payload?.archivedAt;
+  if (archivedAt !== undefined && (!Number.isSafeInteger(archivedAt) || archivedAt <= 0)) {
+    return { ok: false, error: 'archivedAt must be a positive integer timestamp' };
+  }
+
+  return { ok: true, ids, archivedAt: archivedAt ?? Date.now() };
+};
+
 const resolveRequestedDirectory = async ({ payload, readSettingsFromDiskMigrated, sanitizeProjects, validateDirectoryPath }) => {
   const projectID = asNonEmptyString(payload?.projectId) || asNonEmptyString(payload?.projectID);
   if (projectID) {
@@ -579,6 +613,64 @@ export const createOpenChamberSessionService = (dependencies) => {
     return { model, agent, variant, promptDispatched: true, dispatchedAsCommand: Boolean(resolvedCommand) };
   };
 
+  /**
+   * Archive a batch of sessions in one request.
+   *
+   * The UI archives every session linked to a worktree before removing it.
+   * Doing that from the browser costs one request per session plus a store
+   * reconciliation between each of them, which is what made deleting a
+   * worktree with many sessions take tens of seconds. Here the batch stays on
+   * the server, next to OpenCode, and the client reconciles once.
+   *
+   * Sessions are updated one at a time on purpose: they are archived against a
+   * single OpenCode instance, and a fan-out of concurrent writes would trade a
+   * UI stall for server event-loop starvation. One failed session never stops
+   * the batch — it is reported in `failedIds` while the rest still archive, so
+   * callers keep the partial-failure behaviour they already show.
+   */
+  const archive = async (payload = {}) => {
+    const parsed = parseArchiveRequest(payload);
+    if (!parsed.ok) {
+      throw new OpenChamberControlError(parsed.error, 400);
+    }
+
+    const resolvedDirectory = await resolveRequestedDirectory({
+      payload,
+      readSettingsFromDiskMigrated,
+      sanitizeProjects,
+      validateDirectoryPath,
+    });
+    if (!resolvedDirectory.ok) {
+      throw new OpenChamberControlError(resolvedDirectory.error, resolvedDirectory.status || 400);
+    }
+
+    if (typeof waitForOpenCodeReady === 'function') await waitForOpenCodeReady(10_000, 250);
+
+    const directory = resolvedDirectory.directory;
+    const baseUrl = buildOpenCodeUrl('/', '').replace(/\/$/, '');
+    const client = createOpencodeClient({ baseUrl, headers: getOpenCodeAuthHeaders() });
+
+    const archived = [];
+    const failedIds = [];
+    for (const sessionID of parsed.ids) {
+      try {
+        const response = await client.session.update({
+          sessionID,
+          directory,
+          time: { archived: parsed.archivedAt },
+        });
+        const session = response?.data;
+        if (session?.id) archived.push(session);
+        else failedIds.push(sessionID);
+      } catch (error) {
+        console.warn('[OpenChamberSessions] failed to archive session', sessionID, error);
+        failedIds.push(sessionID);
+      }
+    }
+
+    return { directory, archived, failedIds };
+  };
+
   const create = async (payload = {}) => {
     const title = asNonEmptyString(payload.title);
     const prompt = asNonEmptyString(payload.prompt);
@@ -813,6 +905,7 @@ export const createOpenChamberSessionService = (dependencies) => {
 
   return {
     create,
+    archive,
     send: (sessionID, payload) => runExisting('send', sessionID, payload),
     fork: (sessionID, payload) => runExisting('fork', sessionID, payload),
   };
@@ -843,6 +936,15 @@ export const registerOpenChamberSessionRoutes = (app, dependencies) => {
     }
   });
 
+  app.post('/api/openchamber/sessions/archive', express.json({ limit: '1mb' }), async (req, res) => {
+    try {
+      return res.json(await service.archive(req.body && typeof req.body === 'object' ? req.body : {}));
+    } catch (error) {
+      console.error('[OpenChamberSessions] failed to archive sessions:', error);
+      return sendServiceError(res, error, 'Failed to archive sessions');
+    }
+  });
+
   app.post(
     '/api/openchamber/sessions/:sessionId/send',
     express.json({ limit: '1mb' }),

package/server/lib/openchamber-sessions/routes.test.js

@@ -17,6 +17,7 @@ const getWorktreeBootstrapStatusMock = vi.fn(async () => ({
 const sessionCreateMock = vi.fn(async () => ({ data: { id: 'ses_123' } }));
 const sessionForkMock = vi.fn(async () => ({ data: { id: 'ses_fork', title: 'Forked session' } }));
 const sessionMessagesMock = vi.fn(async () => ({ data: [] }));
+const sessionUpdateMock = vi.fn(async ({ sessionID }) => ({ data: { id: sessionID, time: { archived: 1 } } }));
 
 let existingSessionMessages = [];
 let dispatchedUserMessageSeq = 0;
@@ -78,6 +79,7 @@ vi.mock('@opencode-ai/sdk/v2', () => ({
       fork: sessionForkMock,
       messages: sessionMessagesMock,
       command: sessionCommandMock,
+      update: sessionUpdateMock,
     },
     command: {
       list: commandListMock,
@@ -132,6 +134,92 @@ describe('openchamber session routes', () => {
     sessionCommandMock.mockResolvedValue({ data: {} });
     commandListMock.mockReset();
     commandListMock.mockResolvedValue({ data: [] });
+    sessionUpdateMock.mockReset();
+    sessionUpdateMock.mockImplementation(async ({ sessionID }) => ({ data: { id: sessionID, time: { archived: 1 } } }));
+  });
+
+  describe('archiving a batch of sessions', () => {
+    it('archives every id against the resolved directory and returns the archived sessions', async () => {
+      const { app } = createApp();
+      const response = await request(app)
+        .post('/api/openchamber/sessions/archive')
+        .send({ directory: '/repo/app', ids: ['ses_a', 'ses_b'], archivedAt: 1700 })
+        .expect(200);
+
+      expect(response.body.directory).toBe('/repo/app');
+      expect(response.body.archived.map((session) => session.id)).toEqual(['ses_a', 'ses_b']);
+      expect(response.body.failedIds).toEqual([]);
+      expect(sessionUpdateMock).toHaveBeenCalledTimes(2);
+      expect(sessionUpdateMock).toHaveBeenCalledWith({
+        sessionID: 'ses_a',
+        directory: '/repo/app',
+        time: { archived: 1700 },
+      });
+    });
+
+    it('keeps archiving after a failed session and reports it as failed', async () => {
+      sessionUpdateMock.mockImplementation(async ({ sessionID }) => {
+        if (sessionID === 'ses_b') throw new Error('session.update failed');
+        return { data: { id: sessionID } };
+      });
+
+      const { app } = createApp();
+      const response = await request(app)
+        .post('/api/openchamber/sessions/archive')
+        .send({ directory: '/repo/app', ids: ['ses_a', 'ses_b', 'ses_c'] })
+        .expect(200);
+
+      expect(response.body.archived.map((session) => session.id)).toEqual(['ses_a', 'ses_c']);
+      expect(response.body.failedIds).toEqual(['ses_b']);
+    });
+
+    it('reports a session the server did not confirm as failed instead of archived', async () => {
+      sessionUpdateMock.mockImplementation(async ({ sessionID }) => (
+        sessionID === 'ses_b' ? { data: null } : { data: { id: sessionID } }
+      ));
+
+      const { app } = createApp();
+      const response = await request(app)
+        .post('/api/openchamber/sessions/archive')
+        .send({ directory: '/repo/app', ids: ['ses_a', 'ses_b'] })
+        .expect(200);
+
+      expect(response.body.archived.map((session) => session.id)).toEqual(['ses_a']);
+      expect(response.body.failedIds).toEqual(['ses_b']);
+    });
+
+    it('rejects an empty batch, an oversized batch, and non-string ids', async () => {
+      const { app } = createApp();
+
+      await request(app).post('/api/openchamber/sessions/archive').send({ directory: '/repo/app', ids: [] }).expect(400);
+      await request(app)
+        .post('/api/openchamber/sessions/archive')
+        .send({ directory: '/repo/app', ids: Array.from({ length: 501 }, (_, index) => `ses_${index}`) })
+        .expect(400);
+      await request(app)
+        .post('/api/openchamber/sessions/archive')
+        .send({ directory: '/repo/app', ids: ['ses_a', ''] })
+        .expect(400);
+      await request(app)
+        .post('/api/openchamber/sessions/archive')
+        .send({ directory: '/repo/app', ids: ['ses_a'], archivedAt: -1 })
+        .expect(400);
+
+      expect(sessionUpdateMock).not.toHaveBeenCalled();
+    });
+
+    it('rejects a directory the runtime does not accept', async () => {
+      const { app } = createApp({
+        validateDirectoryPath: async () => ({ ok: false, error: 'Invalid directory' }),
+      });
+
+      await request(app)
+        .post('/api/openchamber/sessions/archive')
+        .send({ directory: '/elsewhere', ids: ['ses_a'] })
+        .expect(400);
+
+      expect(sessionUpdateMock).not.toHaveBeenCalled();
+    });
   });
 
   it('creates a session for a directory', async () => {

package/server/lib/opencode/DOCUMENTATION.md

@@ -34,6 +34,8 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/startup-performance.js`: opt-in startup phase diagnostics with fixed labels and numeric metadata allowlists.
 - `packages/web/server/lib/agent-tool/runtime.js`: managed OpenCode custom-tool materialization, environment injection, loopback authentication, and fixed CLI action dispatch.
 - `packages/web/server/lib/system-prompt/runtime.js`: opt-in managed OpenCode system-prompt optimizer materialization and plugin injection.
+- `packages/web/server/lib/mcp-reconnect/runtime.js`: always-on managed OpenCode plugin that reconnects MCP servers OpenCode marked `failed`, with per-server backoff.
+- `packages/web/server/lib/opencode/managed-plugin-config.js`: the one `OPENCODE_CONFIG_CONTENT` merge every managed plugin (agent tools, system prompt optimizer, MCP reconnect) appends itself through.
 - `packages/web/server/lib/opencode/server-utils-runtime.js`: shared server runtime utilities for OpenCode proxy wiring, OpenCode port/readiness helpers, and snapshot fetchers.
 - `packages/web/server/lib/opencode/openchamber-routes.js`: OpenChamber update and models metadata route registration.
 - `packages/web/server/lib/opencode/pwa-manifest-routes.js`: PWA manifest route registration with recent-session shortcut resolution and short-lived caching.
@@ -61,12 +63,12 @@ This module provides OpenCode server integration utilities for the web server ru
 
 ## Public exports (providers.js)
 - `getProviderSources(providerId, workingDirectory)`: Resolves which OpenCode config layers define a provider.
-- `upsertProviderConfig(providerId, config, workingDirectory, scope?, options?)`: Validates and writes a custom OpenAI-compatible provider block (`npm`, `name`, `options.baseURL`, `models`, optional `env`/`headers`) into the user/project/custom config layer. Does not store API keys. Requires `config.env` or `options.hasStoredAuth` (auth already written via OpenCode `auth.set`). Edit flows must pass the provider's effective existing layer (`custom` > `project` > `user`) so updates do not create a global user override.
-- `validateCustomProviderConfig(providerId, config, options?)`: Structural validation for custom provider payloads (id format, http(s) base URL, models, credentials via `env` or `hasStoredAuth`).
+- `upsertProviderConfig(providerId, config, workingDirectory, scope?, options?)`: Validates and writes a custom provider block (`npm`, `name`, `options.baseURL`, `models`, optional `env`/`headers`) into the user/project/custom config layer. The adapter may be OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages. Existing provider, option, and retained-model fields not managed by the form are preserved; omitted models, headers, and env credentials remain explicit removals. Updating a legacy `providers` entry migrates it to the canonical `provider` key. Does not store API keys. Requires `config.env` or `options.hasStoredAuth` (auth already written via OpenCode `auth.set`). Edit flows must pass the provider's effective existing layer (`custom` > `project` > `user`) so updates do not create a global user override.
+- `validateCustomProviderConfig(providerId, config, options?)`: Structural validation for custom provider payloads (id format, adapter allowlist `@ai-sdk/openai-compatible`/`@ai-sdk/openai`/`@ai-sdk/anthropic`, http(s) base URL, models, credentials via `env` or `hasStoredAuth`).
 - `removeProviderConfig(providerId, workingDirectory, scope?)`: Removes a provider block from the selected config layer.
 
 ## Public exports (shared.js)
-- `OPENCODE_CONFIG_DIR`, `AGENT_DIR`, `COMMAND_DIR`, `SKILL_DIR`, `CONFIG_FILE`: Path constants. `OPENCODE_CONFIG` is resolved at call time for the custom config layer path.
+- `OPENCODE_CONFIG_DIR`, `AGENT_DIR`, `COMMAND_DIR`, `SKILL_DIR`, `CONFIG_FILE`: Path constants rooted at `$XDG_CONFIG_HOME/opencode` when `XDG_CONFIG_HOME` is non-empty, otherwise `~/.config/opencode`. These constants are evaluated when the module loads; no files are migrated. `OPENCODE_CONFIG` remains a separate explicit config-file path and is resolved at call time for the custom config layer; it does not replace the global config directory.
 - `AGENT_SCOPE`, `COMMAND_SCOPE`, `SKILL_SCOPE`: Scope constants with USER and PROJECT values.
 - `ensureDirs()`: Creates required OpenCode directories.
 - `parseMdFile(filePath)`, `writeMdFile(filePath, frontmatter, body)`: Markdown file operations with YAML frontmatter.
@@ -130,7 +132,8 @@ The runtime maintains active-session count incrementally from idempotent activit
   - `killProcessOnPort(port)`
 
 Managed OpenCode launch also merges the environment returned by the agent-tool
-runtime. PATH and `OPENCODE_SERVER_PASSWORD` remain lifecycle-owned and cannot
+runtime, the opt-in system prompt optimizer, and the always-on MCP reconnect
+plugin, each appending its `file://` entry to the previous one's config. PATH and `OPENCODE_SERVER_PASSWORD` remain lifecycle-owned and cannot
 be replaced by injected values. External OpenCode processes receive no
 OpenChamber tool injection. Managed launch env strips AppImage `ARGV0` before
 spawn so zsh-backed OpenCode tools do not rewrite child argv[0] to the AppImage
@@ -208,7 +211,13 @@ Managed health failures are classified as `timeout`, `connection_refused`, `conn
   - `writeSettingsToDisk(settings)`
   - `persistSettings(changes)`
 - Persistent permission auto-accept policy is stored under `permissionAutoAccept`; execution ownership lives in `lib/permission-auto-accept/`.
-- Shared sidebar preferences are stored as validated top-level fields: `sidebarProjectDisplayMode`, `sidebarSessionGroupingMode`, `sidebarProjectSortOrder`, and `sidebarShowRecentSection`. Device-local picker selection and sticky-header state do not enter `settings.json`.
+- Queued follow-up messages live in `<data-dir>/message-queue.json`, not in settings; execution ownership lives in `lib/message-queue/`.
+- Shared sidebar preferences are stored as validated top-level fields: `sidebarProjectDisplayMode`, `sidebarSessionGroupingMode`, `sidebarProjectSortOrder`, and `sidebarShowRecentSection`. Device-local picker selection and sticky-header state do not enter either settings file.
+- Two files (`settings-files.js`): `settings.json` holds instance facts and any legacy or unknown keys; `preferences.json` beside it holds every key the generated registry snapshot (`settings-registry.json`) marks `profile`, as `{ version: 1, fields: { key: { value, updatedAt, surfaces? } } }`. Keys the snapshot marks `perSurface` are stored per surface kind: `GET`/`PUT /api/config/settings` read the client's kind from the `surface` query parameter (`settingsSurfaceOf`; the legacy `x-openchamber-surface` header is still honoured, but a header forces a CORS preflight that cross-origin shells and older instances refuse, so clients must not send one) (`web`, `desktop`, `vscode`, `mobile`; anything else means base), `persistSettings(changes, { surface })` writes a changed per-surface key under `surfaces[surface]` and never touches its base, and `readSettingsFromDisk({ surface })` resolves that kind's value first, the base otherwise. Callers without a surface (migrations, the seed, server-side feature writers) read and write the base. `readSettingsFromDisk()` returns the merged document and seeds `preferences.json` once from an existing `settings.json` (which it leaves intact). An existing `preferences.json` that fails to parse is a failure, not an empty profile: it is never seeded or overwritten, the merged read serves the instance part, and `persistSettings` drops profile keys with a warning until the file is fixed or removed. `writeSettingsToDisk(document)` splits by scope and writes `settings.json` as the instance part plus a copy of the profile's base values (`legacySettingsDocumentOf`): a build from before the split reads only that file, so a rollback keeps the user's preferences, while current builds ignore the copy because `preferences.json` wins in the merge; device keys are dropped from writes. Modules that read one profile key off the disk on a hot path use `readMergedSettingsSync`.
+
+## Public exports (settings-files.js)
+- `parsePreferencesDocument(raw)`, `serializePreferencesDocument(fields)`, `flattenPreferences(fields)`, `buildPreferencesFields(previousFields, document, now)`, `instancePartOf(document)`, `seedPreferencesFrom(document, now)`, `readMergedSettingsSync({ fs, path, settingsFilePath })`, `getSettingsScope(key)`, `isProfileSettingsKey(key)`, `isDeviceSettingsKey(key)`, `preferencesFilePathFor(settingsFilePath, path)`.
+- The VS Code extension host writes the same two files with the same shape (`packages/vscode/src/settings-files.ts`); format changes go to both.
 
 ## Public exports (settings-helpers.js)
 - `createSettingsHelpers(dependencies)`: creates settings helper runtime for settings request/response shaping.
@@ -359,9 +368,20 @@ before starting managed OpenCode. The managed custom tool therefore receives
 an authoritative loopback callback URL even when OpenChamber binds port `0`.
 
 ## Public exports (openchamber-routes.js)
+Browser completion checks use `appType=web&updateStatus=true` to stay on the
+Desktop Host's native updater. A rejected native restart is retained in the
+server process and returned to these polls as `DESKTOP_UPDATE_RESTART_FAILED`;
+ordinary availability checks remain usable so a browser reload can offer a
+retry. Starting another installation clears the previous restart error.
+The shared UI's `lib/web-update.ts` parses install/check responses and waits
+for the installed native target version, rather than treating absence of a
+newer release as installation success. Poll requests have individual deadlines
+within a ten-minute overall deadline.
+
 - `registerOpenChamberRoutes(app, dependencies)`: registers OpenChamber endpoints:
   - `GET /api/openchamber/update-check`
   - `POST /api/openchamber/update-install`
+    - Desktop-managed hosts delegate authenticated Web update requests to the Electron main process, which checks, downloads, and applies the update through `electron-updater` before restarting the host.
     - Foreground servers running under a systemd user unit queue installation in
       a separate transient unit and restart the configured service afterwards.
       `OPENCHAMBER_SYSTEMD_UNIT` overrides the default `openchamber.service`.
@@ -417,7 +437,7 @@ an authoritative loopback callback URL even when OpenChamber binds port `0`.
 
 ## Storage and configuration
 - Provider auth: `~/.local/share/opencode/auth.json`.
-- User config: `~/.config/opencode/opencode.json`.
+- User config: `$XDG_CONFIG_HOME/opencode/opencode.json`, falling back to `~/.config/opencode/opencode.json` when unset or blank.
 - Project config: `<workingDirectory>/.opencode/opencode.json` or `opencode.json`.
 - Custom config: `OPENCODE_CONFIG` env var path.
 - Rate limit config: `OPENCHAMBER_RATE_LIMIT_MAX_ATTEMPTS`, `OPENCHAMBER_RATE_LIMIT_NO_IP_MAX_ATTEMPTS` env vars.
@@ -429,3 +449,7 @@ an authoritative loopback callback URL even when OpenChamber binds port `0`.
 - Config merging follows priority: custom > project > user.
 - UI auth uses scrypt for password hashing with constant-time comparison.
 - Tunnel auth treats `host.docker.internal` as local-only when the socket remote IP is private/loopback.
+
+The behavior `GET /api/behavior/agents-md` response includes `path`, the effective
+server-side filename, whether or not the file exists. Settings displays this
+path without deriving a directory from the browser environment.

package/server/lib/opencode/bootstrap-runtime.js

@@ -63,6 +63,7 @@ export const createBootstrapRuntime = (dependencies) => {
       getCachedZenModels,
       setAutoAcceptSession,
       agentToolRuntime,
+      desktopUpdater,
     } = options;
 
     const uiAuthController = createUiAuth({
@@ -153,6 +154,7 @@ export const createBootstrapRuntime = (dependencies) => {
       readSettingsFromDiskMigrated,
       fetchFreeZenModels,
       getCachedZenModels,
+      desktopUpdater,
     });
 
     return {

package/server/lib/opencode/config-paths.test.js

@@ -0,0 +1,116 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+const originalOpenCodeConfig = process.env.OPENCODE_CONFIG;
+
+afterEach(() => {
+  if (originalXdgConfigHome === undefined) delete process.env.XDG_CONFIG_HOME;
+  else process.env.XDG_CONFIG_HOME = originalXdgConfigHome;
+  if (originalOpenCodeConfig === undefined) delete process.env.OPENCODE_CONFIG;
+  else process.env.OPENCODE_CONFIG = originalOpenCodeConfig;
+  vi.resetModules();
+});
+
+async function loadOpenCodeModules() {
+  vi.resetModules();
+  return Promise.all([
+    import('./shared.js'),
+    import('./agents.js'),
+    import('./commands.js'),
+    import('./skills.js'),
+    import('./snippets.js'),
+    import('./plugins.js'),
+    import('./routes.js'),
+  ]);
+}
+
+describe('OpenCode global config paths', () => {
+  it('derives all shared constants from a non-empty XDG_CONFIG_HOME', async () => {
+    const xdgConfigHome = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-xdg-'));
+    process.env.XDG_CONFIG_HOME = xdgConfigHome;
+
+    const [{ OPENCODE_CONFIG_DIR, AGENT_DIR, COMMAND_DIR, SKILL_DIR, CONFIG_FILE }] = await loadOpenCodeModules();
+    const configDir = path.join(xdgConfigHome, 'opencode');
+    expect(OPENCODE_CONFIG_DIR).toBe(configDir);
+    expect(AGENT_DIR).toBe(path.join(configDir, 'agents'));
+    expect(COMMAND_DIR).toBe(path.join(configDir, 'commands'));
+    expect(SKILL_DIR).toBe(path.join(configDir, 'skills'));
+    expect(CONFIG_FILE).toBe(path.join(configDir, 'config.json'));
+
+    fs.rmSync(xdgConfigHome, { recursive: true, force: true });
+  });
+
+  it.each([undefined, '  '])('falls back to ~/.config/opencode when XDG_CONFIG_HOME is %s', async (xdgConfigHome) => {
+    if (xdgConfigHome === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = xdgConfigHome;
+
+    const [{ OPENCODE_CONFIG_DIR }] = await loadOpenCodeModules();
+    expect(OPENCODE_CONFIG_DIR).toBe(path.join(os.homedir(), '.config', 'opencode'));
+  });
+
+  it('keeps global CRUD below XDG_CONFIG_HOME while project files stay in the project', async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-config-paths-'));
+    const xdgConfigHome = path.join(root, 'xdg');
+    const projectDir = path.join(root, 'project');
+    process.env.XDG_CONFIG_HOME = xdgConfigHome;
+    delete process.env.OPENCODE_CONFIG;
+
+    const [, agents, commands, skills, snippets, plugins] = await loadOpenCodeModules();
+    agents.createAgent('global-agent', { description: 'Global', prompt: 'Global prompt' }, projectDir, 'user');
+    commands.createCommand('global-command', { description: 'Global', template: 'Global template' }, projectDir, 'user');
+    skills.createSkill('global-skill', { description: 'Global', instructions: 'Global instructions' }, projectDir, 'user');
+    snippets.createSnippet('global-snippet', { content: 'Global snippet' }, projectDir, 'global');
+    plugins.createPluginEntry({ spec: 'global-plugin', scope: 'user' }, projectDir);
+
+    const configDir = path.join(xdgConfigHome, 'opencode');
+    expect(fs.existsSync(path.join(configDir, 'agents', 'global-agent.md'))).toBe(true);
+    expect(fs.existsSync(path.join(configDir, 'commands', 'global-command.md'))).toBe(true);
+    expect(fs.existsSync(path.join(configDir, 'skills', 'global-skill', 'SKILL.md'))).toBe(true);
+    expect(fs.existsSync(path.join(configDir, 'snippet', 'global-snippet.md'))).toBe(true);
+    expect(JSON.parse(fs.readFileSync(path.join(configDir, 'config.json'), 'utf8')).plugin).toEqual(['global-plugin']);
+
+    agents.createAgent('project-agent', { description: 'Project', prompt: 'Project prompt' }, projectDir, 'project');
+    commands.createCommand('project-command', { description: 'Project', template: 'Project template' }, projectDir, 'project');
+    skills.createSkill('project-skill', { description: 'Project', instructions: 'Project instructions' }, projectDir, 'project');
+
+    expect(fs.existsSync(path.join(projectDir, '.opencode', 'agents', 'project-agent.md'))).toBe(true);
+    expect(fs.existsSync(path.join(projectDir, '.opencode', 'commands', 'project-command.md'))).toBe(true);
+    expect(fs.existsSync(path.join(projectDir, '.opencode', 'skills', 'project-skill', 'SKILL.md'))).toBe(true);
+
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('writes global AGENTS.md below XDG_CONFIG_HOME', async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-agents-md-'));
+    process.env.XDG_CONFIG_HOME = path.join(root, 'xdg');
+    delete process.env.OPENCODE_CONFIG;
+
+    const [, , , , , , routes] = await loadOpenCodeModules();
+    const handlers = new Map();
+    const app = {
+      get(route, ...callbacks) { handlers.set(`GET ${route}`, callbacks.at(-1)); },
+      put(route, ...callbacks) { handlers.set(`PUT ${route}`, callbacks.at(-1)); },
+      post() {},
+      delete() {},
+    };
+    routes.registerOpenCodeRoutes(app, {});
+
+    const response = { json: vi.fn(), status: vi.fn(() => response) };
+    await handlers.get('GET /api/behavior/agents-md')({}, response);
+    expect(response.json).toHaveBeenLastCalledWith({
+      content: '', exists: false, path: path.join(process.env.XDG_CONFIG_HOME, 'opencode', 'AGENTS.md'),
+    });
+
+    await handlers.get('PUT /api/behavior/agents-md')({ body: { content: 'Global behavior' } }, response);
+
+    expect(fs.readFileSync(path.join(process.env.XDG_CONFIG_HOME, 'opencode', 'AGENTS.md'), 'utf8')).toBe('Global behavior');
+    await handlers.get('GET /api/behavior/agents-md')({}, response);
+    expect(response.json).toHaveBeenLastCalledWith({
+      content: 'Global behavior', exists: true, path: path.join(process.env.XDG_CONFIG_HOME, 'opencode', 'AGENTS.md'),
+    });
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+});

package/server/lib/opencode/core-routes.js

@@ -1065,6 +1065,7 @@ export const registerCommonRequestMiddleware = (app, dependencies) => {
       req.path.startsWith('/api/push') ||
       req.path.startsWith('/api/notifications') ||
       req.path.startsWith('/api/permission-auto-accept') ||
+      req.path.startsWith('/api/message-queue') ||
       req.path.startsWith('/api/provider') ||
       req.path.startsWith('/api/session-folders') ||
       req.path.startsWith('/api/small-model') ||

package/server/lib/opencode/feature-routes-runtime.js

@@ -10,9 +10,11 @@ import { registerDevServerRoutes } from '../dev-servers/routes.js';
 import { registerMagicPromptRoutes } from '../magic-prompts/routes.js';
 import { registerSessionFoldersRoutes } from '../session-folders/routes.js';
 import { registerProjectContextRoutes } from '../project-context/routes.js';
+import { registerProjectSetupRoutes } from '../projects/routes.js';
 import { registerAgentMemoryRoutes } from '../agent-memory/routes.js';
 import { registerSessionKnowledgeRoutes } from '../session-knowledge/routes.js';
 import { registerPermissionAutoAcceptRoutes } from '../permission-auto-accept/runtime.js';
+import { registerMessageQueueRoutes } from '../message-queue/runtime.js';
 import { registerConfigEntityRoutes } from './config-entity-routes.js';
 import { registerSettingsUtilityRoutes } from './core-routes.js';
 import { registerProjectIconRoutes } from './project-icon-routes.js';
@@ -97,6 +99,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
       createFsSearchRuntime,
       openchamberDataDir,
       openchamberUserConfigRoot,
+      managedChatsRoot,
       normalizeDirectoryPath,
       resolveProjectDirectory,
       resolveOptionalProjectDirectory,
@@ -132,6 +135,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
       writeSseEvent,
       emitSessionCreatedEvent,
       permissionAutoAcceptRuntime,
+      messageQueueRuntime,
     } = routeDependencies;
 
     registerSettingsUtilityRoutes(app, {
@@ -141,6 +145,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
     });
 
     registerPermissionAutoAcceptRoutes(app, permissionAutoAcceptRuntime);
+    registerMessageQueueRoutes(app, messageQueueRuntime);
 
     registerOpenCodeRoutes(app, {
       crypto,
@@ -310,6 +315,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
       openchamberDataDir,
     });
     registerProjectContextRoutes(app, { projectContextRuntime });
+    registerProjectSetupRoutes(app, { projectConfigRuntime });
     registerAgentMemoryRoutes(app, { agentMemoryRuntime, isAgentMemoryEnabled });
     registerSessionKnowledgeRoutes(app, { sessionKnowledgeRuntime });
 
@@ -329,6 +335,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
       buildAugmentedPath,
       resolveGitBinaryForSpawn,
       openchamberUserConfigRoot,
+      managedChatsRoot,
     });
   };
 

package/server/lib/opencode/input-history-scope.js

@@ -0,0 +1,14 @@
+export const DEFAULT_INPUT_HISTORY_SCOPE = 'session';
+export const DEFAULT_INPUT_HISTORY_LIMIT = 40;
+const MIN_INPUT_HISTORY_LIMIT = 1;
+const MAX_INPUT_HISTORY_LIMIT = 100;
+
+export const isInputHistoryScope = (value) => (
+  value === 'global' || value === 'session'
+);
+
+export const isInputHistoryLimit = (value) => (
+  Number.isInteger(value)
+  && value >= MIN_INPUT_HISTORY_LIMIT
+  && value <= MAX_INPUT_HISTORY_LIMIT
+);

package/server/lib/opencode/managed-plugin-config.js

@@ -0,0 +1,35 @@
+import { parse as parseJsonc } from 'jsonc-parser';
+
+const isJsonObject = (value) => value !== null && value !== undefined && Object.getPrototypeOf(value) === Object.prototype;
+
+/**
+ * Append a managed OpenChamber plugin to the `plugin` list of an
+ * `OPENCODE_CONFIG_CONTENT` value.
+ *
+ * Existing entries are preserved; an earlier entry for the same URL is dropped
+ * so a restart never registers the same plugin twice. Every managed plugin
+ * (agent tools, system prompt optimizer, MCP reconnect) goes through this one
+ * merge so they compose in any order.
+ *
+ * @param {string | undefined} rawConfig the current `OPENCODE_CONFIG_CONTENT`, JSONC or unset
+ * @param {string} pluginUrl `file://` URL of the materialized plugin
+ * @param {string} purpose short noun phrase for the error message, e.g. "managed tool"
+ * @returns {string} the merged config as JSON
+ */
+export const appendManagedPlugin = (rawConfig, pluginUrl, purpose) => {
+  const errors = [];
+  const text = (rawConfig ?? '').trim();
+  const parsed = text ? parseJsonc(text, errors, { allowTrailingComma: true }) : {};
+  if (errors.length > 0 || !isJsonObject(parsed)) {
+    throw new Error(`OPENCODE_CONFIG_CONTENT must contain a valid JSON object before OpenChamber can inject its ${purpose}`);
+  }
+  if (parsed.plugin !== undefined && !Array.isArray(parsed.plugin)) {
+    throw new Error(`OPENCODE_CONFIG_CONTENT plugin must be an array before OpenChamber can inject its ${purpose}`);
+  }
+  const configured = Array.isArray(parsed.plugin) ? parsed.plugin : [];
+  parsed.plugin = [
+    ...configured.filter((value) => value !== pluginUrl && (!Array.isArray(value) || value[0] !== pluginUrl)),
+    pluginUrl,
+  ];
+  return JSON.stringify(parsed);
+};