dsh-strata-sync 0.0.0-stage → 0.8.1

package/dist/index.js

@@ -0,0 +1,538 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { discoverStrata, planBudget, StrataSyncError } from './core.mjs';
+import { installSummaryGuidance } from './summary.mjs';
+
+export const inject = ['configEditor', 'connection', 'agents', 'credentials', 'agentPresets'];
+export const Config = z.object({
+  providerId: z.string().default(''),
+  autoSync: z.boolean().default(false),
+  followLoadedModel: z.boolean().default(true),
+  outputTokens: z.number().step(1).min(1),
+});
+
+const PACKAGE = 'dsh-strata-sync';
+const COMPACTION = '@deepseek-ai/dsh-compaction-basic';
+const PRESET = '@deepseek-ai/dsh-agent-preset';
+const CHANNEL = '/api/strata-sync';
+// Survives plugin hot reloads, but not a new DSH host process. One completed attempt per profile.
+const startupKey = Symbol.for('dsh-strata-sync/startup');
+const startupProfiles = globalThis[startupKey] ??= new Map();
+const clone = (value) => structuredClone(value);
+const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const own = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+export function capabilityChanges(capabilities, route, configured = {}) {
+  const edits = {}, warnings = [];
+  if (capabilities.input) edits.input = capabilities.input;
+  if (capabilities.reasoning) {
+    const supported = capabilities.reasoning.efforts;
+    if (route.reasoning !== undefined && !own(supported, route.reasoning)) warnings.push('REASONING_DEFAULT_CONFLICT');
+    else {
+      edits.reasoningEfforts = supported;
+      edits.compat = clone(capabilities.reasoning.compat);
+    }
+  }
+  return { edits, warnings };
+}
+export function mergeCapabilityEdits(model, route, edits) {
+  const result = clone(edits);
+  if (edits.compat) result.compat = { ...model.compat, ...edits.compat,
+    chatTemplateKwargs: { ...route.compat?.chatTemplateKwargs, ...model.compat?.chatTemplateKwargs, ...edits.compat.chatTemplateKwargs } };
+  return result;
+}
+function refuse(code, message) { const error = new Error(message); error.code = code; throw error; }
+function payload(value, keys = []) {
+  if (!object(value) || Object.keys(value).some((key) => !keys.includes(key))) refuse('invalid-request', 'Invalid Strata Sync request.');
+  return value;
+}
+
+/** Native DSH plugin; the server is only queried, never configured or restarted. */
+export function apply(ctx, initialConfig) {
+  let settings = { providerId: '', autoSync: false, followLoadedModel: true, ...initialConfig };
+  let closed = false;
+  let inFlight = false;
+  let writeBarrier;
+  let releaseWrite;
+  let lastPreview = null;
+  let lastApplied = null;
+  let lastError = null;
+  let lastFingerprint = null;
+  const previewSnapshots = new WeakMap();
+  function ensureOpen() { if (closed) refuse('disposed', 'Strata Sync was disabled or reloaded; this operation was cancelled.'); }
+
+  function entry(name, id) {
+    const found = ctx.configEditor.entries().filter((row) => row.options.name === name && (id === undefined || row.options.id === id) && row.fiber?.state === 2);
+    if (found.length !== 1) refuse('unsupported-profile', `Exactly one active ${name} entry is required.`);
+    return found[0];
+  }
+  function compactionOwners() {
+    const owners = [];
+    for (const row of ctx.configEditor.entries()) {
+      if (row.fiber?.state !== 2) continue;
+      const { id, name } = row.options;
+      const config = clone(row.options.config ?? {});
+      if (name === COMPACTION) owners.push({ id, name, config, targets: [{ id, path: [], config }] });
+      if (name !== PRESET) continue;
+      const targets = [];
+      const walk = (rows, path, labels = []) => {
+        if (!Array.isArray(rows)) return;
+        for (const [index, child] of rows.entries()) {
+          // Do not enable disabled branches or guess unevaluated !!js expressions.
+          if (!object(child) || child.disabled) continue;
+          const childPath = [...path, index, 'config'];
+          const childLabels = [...labels, child.id ?? String(index)];
+          if (child.name === COMPACTION) targets.push({ id: `${config.id}/${childLabels.join('/')}`, path: childPath, config: clone(child.config ?? {}) });
+          if (child.group === true) walk(child.config, childPath, childLabels);
+        }
+      };
+      walk(config.plugins, ['plugins']);
+      if (targets.length) owners.push({ id, name, presetId: config.id, config, targets });
+    }
+    if (!owners.length) refuse('unsupported-profile', 'No active profile or enabled agent-preset compaction configuration is available. Enable a supported DSH agent preset first.');
+    return owners;
+  }
+  function snapshot() {
+    refreshSettings();
+    const llmEntry = entry('@deepseek-ai/dsh-llm-pi-ai');
+    const owners = compactionOwners();
+    const defaultEntry = settings.followLoadedModel ? entry('@deepseek-ai/dsh-agent-default-model') : null;
+    return { llmEntry, owners, defaultEntry,
+      llm: clone(llmEntry.options.config ?? {}),
+      defaults: defaultEntry ? clone(defaultEntry.options.config ?? {}) : null,
+      settings: publicSettings() };
+  }
+  function snapshotRevision(value) {
+    return hash({ llmId: value.llmEntry.options.id, llm: value.llm, owners: value.owners,
+      defaultId: value.defaultEntry?.options.id ?? null, defaults: value.defaults, settings: value.settings });
+  }
+  function assertSnapshot(before) {
+    if (snapshotRevision(before) !== snapshotRevision(snapshot())) {
+      refuse('stale-preview', 'The DSH settings changed during discovery. Review a fresh preview.');
+    }
+  }
+  async function checkPresets(owners) {
+    for (const owner of owners) {
+      if (!owner.presetId) continue;
+      const state = await ctx.agentPresets.resolve(owner.presetId);
+      ensureOpen();
+      if (state.broken) refuse('preset-unavailable', `The DSH agent preset ${owner.presetId} could not activate. Fix its configuration in DSH Settings before syncing.`);
+    }
+  }
+  function providerChoice(providers, requested = settings.providerId) {
+    if (requested) {
+      if (typeof requested !== 'string' || !own(providers, requested)) refuse('provider-missing', 'Choose an existing Strata provider in DSH Models settings.');
+      return requested;
+    }
+    const candidates = Object.keys(providers).filter((id) => /strata/i.test(id));
+    if (candidates.length !== 1) refuse('provider-required', 'Choose which existing provider connects to Strata Server.');
+    return candidates[0];
+  }
+  function busy() {
+    // DSH 0.2.1-rc.3 reports maintenance as idle while manual compaction can still run.
+    return ctx.agents.list().some((agent) => agent.status !== 'idle' || agent.phase?.kind === 'maintenance');
+  }
+  function refreshSettings() {
+    settings = { providerId: '', autoSync: false, followLoadedModel: true, ...entry(PACKAGE).options.config };
+  }
+  function publicSettings(value = settings) {
+    return { providerId: value.providerId ?? '', autoSync: value.autoSync ?? false,
+      followLoadedModel: value.followLoadedModel ?? true, outputTokens: value.outputTokens ?? null };
+  }
+  function status() {
+    refreshSettings();
+    let providers = [];
+    try {
+      const rows = entry('@deepseek-ai/dsh-llm-pi-ai').options.config?.providers ?? {};
+      providers = Object.entries(rows).map(([id, route]) => {
+        let baseURL = '';
+        try { const url = new URL(route.baseURL); if (!url.username && !url.password && !url.search) baseURL = url.href; } catch {}
+        return { id, baseURL };
+      });
+    } catch { /* The page remains usable when the required provider is absent. */ }
+    return { ...publicSettings(), settingsRevision: hash(publicSettings()),
+      busy: busy() || !!writeBarrier, providers, lastPreview, lastApplied, lastError };
+  }
+  async function credential(providerId, route) {
+    if (route.apiKeyEnv) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(route.apiKeyEnv)) refuse('credential-unavailable', 'The provider credential reference is invalid.');
+      const resolved = await ctx.credentials.resolve(route.apiKeyEnv);
+      if (!resolved?.value) refuse('credential-unavailable', 'The existing provider credential is unavailable. Reconnect it in DSH Models settings.');
+      return resolved.value;
+    }
+    if (/^[a-z][a-z0-9-]*$/.test(providerId)) {
+      const record = await ctx.credentials.readRecord(`llm-pi-ai/${providerId}`);
+      if (record?.kind === 'api-key' && typeof record.key === 'string') return record.key;
+      if (record?.kind === 'grant') refuse('credential-unavailable', 'This plugin supports API-key Strata connections, not OAuth grants.');
+    }
+    return undefined; // Unauthenticated local Strata servers are also supported.
+  }
+  async function summaryContext(options) {
+    ensureOpen();
+    refreshSettings();
+    const routes = entry('@deepseek-ai/dsh-llm-pi-ai').options.config?.providers ?? {};
+    const providerId = providerChoice(routes);
+    if (options.provider !== providerId) return null;
+    const route = clone(routes[providerId]);
+    if (route.api && route.api !== 'openai-completions') return null;
+    if (!Array.isArray(route.models) || Object.keys(route.modelOverrides ?? {}).length) return null;
+    const model = route.models.find(row => row.id === options.model);
+    if (!Number.isSafeInteger(model?.contextWindow) || model.contextWindow < 1) return null;
+    const revision = hash({ route, settings: publicSettings() });
+    const apiKey = await credential(providerId, route);
+    ensureOpen();
+    const discovered = await discoverStrata(route.baseURL, apiKey, {
+      modelId: options.model, timeout: 2000, signal: options.signal,
+    });
+    ensureOpen();
+    refreshSettings();
+    const current = entry('@deepseek-ai/dsh-llm-pi-ai').options.config?.providers ?? {};
+    if (hash({ route: current[providerId], settings: publicSettings() }) !== revision || !discovered.verifiedServer) return null;
+    // A server/client mismatch must not enlarge the target past either capacity.
+    return Math.min(discovered.model.contextWindow, model.contextWindow);
+  }
+  installSummaryGuidance(ctx, summaryContext);
+  async function preview(request = {}) {
+    ensureOpen();
+    payload(request, ['providerId', 'outputTokens']);
+    const before = snapshot();
+    await checkPresets(before.owners);
+    ensureOpen();
+    const providerId = providerChoice(before.llm.providers ?? {}, request.providerId);
+    const route = before.llm.providers[providerId];
+    if (route.api && route.api !== 'openai-completions') refuse('unsupported-provider', 'Strata Sync currently supports the openai-completions adapter.');
+    if (!Array.isArray(route.models) || route.models.length === 0 || Object.keys(route.modelOverrides ?? {}).length) {
+      refuse('unsupported-route', 'Use a dedicated Strata provider with an explicit models list and no modelOverrides. Catalog-backed routes are not supported for synchronization.');
+    }
+    const outputTokens = request.outputTokens === null ? undefined : request.outputTokens ?? settings.outputTokens;
+    if (outputTokens !== undefined && (!Number.isSafeInteger(outputTokens) || outputTokens < 1)) refuse('invalid-budget', 'Output tokens must be a positive integer.');
+    const apiKey = await credential(providerId, route);
+    ensureOpen();
+    const discovered = await discoverStrata(route.baseURL, apiKey);
+    ensureOpen();
+    assertSnapshot(before);
+    const budget = planBudget(discovered.model.contextWindow, { outputTokens, serverOutputTokens: discovered.model.serverOutputTokens });
+    const configured = (route.models ?? []).find((model) => model.id === discovered.model.id);
+    const capabilities = discovered.model.capabilities;
+    const { edits: capabilityEdits, warnings: capabilityWarnings } = capabilityChanges(capabilities, route, configured);
+    const capabilityStatus = { input: capabilityEdits.input ? 'confirmed' : 'preserved',
+      reasoning: capabilityEdits.reasoningEfforts ? 'confirmed' : 'preserved' };
+    discovered.warnings.push(...capabilityWarnings);
+    const compactions = before.owners.flatMap((owner) => owner.targets.map((target) => {
+      const base = target.config;
+      const policy = (base.modelPolicies ?? []).find((row) => row.provider === providerId && row.model === discovered.model.id);
+      return { target: target.id, presetId: owner.presetId ?? null, current: {
+        headroomTokens: policy?.headroomTokens ?? base.headroomTokens ?? 65536,
+        summaryMaxTokens: policy?.maxTokens ?? base.maxTokens ?? policy?.headroomTokens ?? base.headroomTokens ?? 65536,
+        thresholdRatio: policy?.thresholdRatio ?? base.thresholdRatio ?? 0.8,
+        retainRatio: policy?.retainTokens !== undefined ? null : policy?.retainRatio ?? (base.retainTokens !== undefined ? null : base.retainRatio ?? 0.16),
+        retainTokens: policy?.retainRatio !== undefined ? null : policy?.retainTokens ?? base.retainTokens ?? null,
+      } };
+    }));
+    const current = { model: before.defaults?.provider === providerId ? before.defaults.model : null,
+      contextWindow: configured?.contextWindow ?? null, outputTokens: configured?.maxTokens ?? null };
+    const desired = {
+      ...(settings.followLoadedModel ? { model: discovered.model.id } : {}),
+      contextWindow: budget.contextWindow, outputTokens: budget.outputTokens,
+    };
+    const changes = Object.entries(desired).filter(([field, after]) => current[field] !== after).map(([field, after]) => ({ field, before: current[field] ?? null, after }));
+    for (const [field, after] of Object.entries(capabilityEdits)) {
+      let previous = configured?.[field];
+      if (field === 'compat') previous = { thinkingFormat: configured?.compat?.thinkingFormat,
+        supportsReasoningEffort: configured?.compat?.supportsReasoningEffort,
+        chatTemplateKwargs: Object.fromEntries(Object.keys(after.chatTemplateKwargs).map(key=>[key,configured?.compat?.chatTemplateKwargs?.[key]])) };
+      if (JSON.stringify(previous) !== JSON.stringify(after)) changes.push({ field,
+        before: field === 'compat' ? 'Existing request mapping' : previous ?? null, after });
+    }
+    const compactionDesired = { headroomTokens: budget.headroomTokens, summaryMaxTokens: budget.summaryMaxTokens,
+      thresholdRatio: budget.thresholdRatio, retainRatio: budget.retainRatio, retainTokens: null };
+    for (const state of compactions) for (const [field, after] of Object.entries(compactionDesired)) {
+      if (state.current[field] !== after) changes.push({ target: state.target, field, before: state.current[field], after });
+    }
+    // A mixed value is intentionally null; per-target values and differences remain explicit.
+    for (const field of Object.keys(compactionDesired)) {
+      const values = compactions.map((state) => state.current[field]);
+      current[field] = values.every((value) => value === values[0]) ? values[0] : null;
+    }
+    // Fingerprint includes private config only as a one-way digest; no secret crosses the UI boundary.
+    const fingerprint = hash({ providerId, model: discovered.model, budget, profileRevision: snapshotRevision(before) });
+    const warnings = [...discovered.warnings ?? [], ...(before.owners.some((owner) => owner.targets.some((target) => target.config.auto === false)) ? ['DSH_AUTO_COMPACTION_DISABLED'] : [])];
+    const presetIds = before.owners.flatMap((owner) => owner.presetId ? [owner.presetId] : []);
+    const view = { providerId, server: { baseURL: discovered.baseURL, model: discovered.model, warnings }, budget, current, compactions, capabilityEdits, capabilityStatus,
+      presetIds, needsNewConversation: presetIds.length > 0, changes, fingerprint, busy: busy() };
+    previewSnapshots.set(view, before);
+    lastPreview = view;
+    lastError = null;
+    return view;
+  }
+  function appliedSummary(view, backupPath, applied) {
+    return { at: new Date().toISOString(), modelId: view.server.model.id, providerId: view.providerId, backupPath, applied,
+      budget: clone(view.budget), capabilityStatus: clone(view.capabilityStatus), warnings: clone(view.server.warnings),
+      serverOutputTokens: view.server.model.serverOutputTokens ?? null, outputLimitStatus: view.server.model.outputLimitStatus,
+      needsNewConversation: view.needsNewConversation };
+  }
+  async function backup() {
+    ensureOpen();
+    const documentPath = ctx.configEditor.documentPath;
+    const backupDir = join(dirname(documentPath), 'backups', 'strata-sync');
+    await mkdir(backupDir, { recursive: true, mode: 0o700 });
+    ensureOpen();
+    const filename = `${new Date().toISOString().replace(/[:.]/g, '-')}-${randomUUID()}.yml`;
+    const backupPath = join(backupDir, filename);
+    const contents = await readFile(documentPath);
+    ensureOpen();
+    await writeFile(backupPath, contents, { mode: 0o600, flag: 'wx' });
+    ensureOpen();
+    return backupPath;
+  }
+  async function applyPreview(request) {
+    ensureOpen();
+    payload(request, ['fingerprint', 'providerId', 'outputTokens']);
+    if (typeof request.fingerprint !== 'string' || !request.fingerprint) refuse('preview-required', 'Preview the proposed changes before applying them.');
+    if (busy()) refuse('busy', 'A DSH task is running. Wait until all tasks are idle before syncing.');
+    const view = await preview({ ...(request.providerId ? { providerId: request.providerId } : {}), ...(own(request, 'outputTokens') ? { outputTokens: request.outputTokens } : {}) });
+    ensureOpen();
+    if (view.fingerprint !== request.fingerprint) refuse('stale-preview', 'The server or DSH settings changed. Review a fresh preview.');
+    const before = previewSnapshots.get(view);
+    assertSnapshot(before);
+    if (view.changes.length === 0) {
+      lastApplied = appliedSummary(view, null, false);
+      return { applied: false, backupPath: null, preview: view };
+    }
+    if (busy()) refuse('busy', 'A DSH task started. Sync has been deferred.');
+    writeBarrier = new Promise((resolve) => { releaseWrite = resolve; });
+    let backupPath;
+    const completed = [];
+    try {
+      backupPath = await backup();
+      ensureOpen();
+      assertSnapshot(before);
+      if (busy()) refuse('busy', 'A DSH task started. Sync has been deferred.');
+      const modelId = view.server.model.id;
+      const llmNext = clone(before.llm);
+      const route = llmNext.providers[view.providerId];
+      route.models ??= [];
+      let model = route.models.find((row) => row.id === modelId);
+      if (!model) { model = { id: modelId, name: view.server.model.name ?? modelId }; route.models.push(model); }
+      Object.assign(model, { contextWindow: view.budget.contextWindow, maxTokens: view.budget.outputTokens });
+      Object.assign(model, mergeCapabilityEdits(model, route, view.capabilityEdits));
+      const edits = [
+        [before.llmEntry.options.name, before.llmEntry.options.id, before.llm, llmNext],
+        ...before.owners.map((owner) => {
+          const next = clone(owner.config);
+          for (const target of owner.targets) {
+            let compaction = next;
+            for (const key of target.path) compaction = compaction[key] ??= {};
+            compaction.modelPolicies ??= [];
+            let policy = compaction.modelPolicies.find((row) => row.provider === view.providerId && row.model === modelId);
+            if (!policy) { policy = { provider: view.providerId, model: modelId }; compaction.modelPolicies.push(policy); }
+            Object.assign(policy, { headroomTokens: view.budget.headroomTokens, maxTokens: view.budget.summaryMaxTokens,
+              thresholdRatio: view.budget.thresholdRatio, retainRatio: view.budget.retainRatio });
+            delete policy.retainTokens;
+          }
+          return [owner.name, owner.id, owner.config, next];
+        }),
+        ...(settings.followLoadedModel ? [[before.defaultEntry.options.name, before.defaultEntry.options.id, before.defaults, { ...before.defaults, provider: view.providerId, model: modelId }]] : []),
+      ];
+      // Validate every owner before the first write; inactive placeholders are never edited.
+      for (const [name, id] of edits) entry(name, id);
+      for (const [name, id, original, next] of edits) {
+        ensureOpen();
+        if (hash(original) === hash(next)) continue;
+        await ctx.configEditor.edit(entry(name, id), (current) => {
+          ensureOpen();
+          if (busy()) refuse('busy', 'A DSH task started. Sync has been deferred.');
+          // ConfigEditor may queue this callback behind another settings edit.
+          // Recheck every owner when our first write actually begins.
+          if (completed.length === 0) assertSnapshot(before);
+          if (hash(current) !== hash(original)) refuse('concurrent-change', 'DSH settings changed during sync. Preview again.');
+          return next;
+        });
+        completed.push([name, id, original, next]);
+        if (name === PRESET) await checkPresets([{ presetId: next.id }]);
+      }
+      lastApplied = appliedSummary(view, backupPath, true);
+      lastFingerprint = view.fingerprint;
+      lastError = null;
+      return { applied: true, backupPath, preview: view };
+    } catch (error) {
+      let rollbackFailed = false;
+      for (const [name, id, original, written] of completed.reverse()) {
+        try {
+          await ctx.configEditor.edit(entry(name, id), (current) => {
+            if (hash(current) !== hash(written)) refuse('concurrent-change', 'A later settings edit prevents automatic rollback.');
+            return original;
+          });
+        } catch { rollbackFailed = true; }
+      }
+      if (rollbackFailed) refuse('rollback-required', `Sync was interrupted. Restore the saved profile backup: ${backupPath}`);
+      throw error;
+    } finally {
+      releaseWrite?.();
+      writeBarrier = undefined;
+      releaseWrite = undefined;
+    }
+  }
+  async function configure(request) {
+    ensureOpen();
+    payload(request, ['providerId', 'autoSync', 'followLoadedModel', 'outputTokens', 'expectedRevision']);
+    refreshSettings();
+    if (typeof request.expectedRevision !== 'string' || request.expectedRevision !== hash(publicSettings())) {
+      refuse('stale-settings', 'Sync preferences changed. Reload the latest preferences before saving.');
+    }
+    if (busy()) refuse('busy', 'Wait until all DSH tasks are idle before changing sync settings.');
+    const next = { ...settings };
+    if (own(request, 'providerId')) {
+      if (typeof request.providerId !== 'string') refuse('invalid-request', 'Provider must be a string.');
+      next.providerId = request.providerId;
+    }
+    for (const key of ['autoSync', 'followLoadedModel']) {
+      if (!own(request, key)) continue;
+      if (typeof request[key] !== 'boolean') refuse('invalid-request', `${key} must be a boolean.`);
+      next[key] = request[key];
+    }
+    if (own(request, 'outputTokens')) {
+      if (request.outputTokens === null) delete next.outputTokens;
+      else if (Number.isSafeInteger(request.outputTokens) && request.outputTokens > 0) next.outputTokens = request.outputTokens;
+      else refuse('invalid-budget', 'Output tokens must be a positive integer, or null for automatic budgeting.');
+    }
+    const self = entry(PACKAGE);
+    const original = clone(self.options.config ?? {});
+    // Editing our own entry can dispose this plugin before edit() resolves.
+    // Build the response while this Cordis scope is still alive; never read its
+    // injected services after Loader replaces it.
+    const response = { ...status(), providerId: next.providerId, autoSync: next.autoSync,
+      followLoadedModel: next.followLoadedModel, outputTokens: next.outputTokens ?? null,
+      settingsRevision: hash(publicSettings(next)), lastPreview: null, lastError: null };
+    await backup();
+    ensureOpen();
+    await ctx.configEditor.edit(self, (current) => {
+      ensureOpen();
+      if (hash(current) !== hash(original) || hash(publicSettings(current)) !== request.expectedRevision) {
+        refuse('stale-settings', 'Sync preferences changed while saving. Reload the latest preferences.');
+      }
+      if (busy()) refuse('busy', 'Wait until all DSH tasks are idle before changing sync settings.');
+      return next;
+    });
+    settings = next;
+    lastPreview = null;
+    lastError = null;
+    return response;
+  }
+  function safeError(error) {
+    // Discovery errors contain fixed messages or HTTP status numbers, never response bodies.
+    if (error instanceof StrataSyncError) return { code: error.code, message: error.message, details: {} };
+    // Adapter/network exceptions may contain credential-bearing URLs or response bodies.
+    // Only messages deliberately raised here are exposed verbatim.
+    const known = ['disposed','invalid-request','invalid-budget','provider-missing','provider-required','unsupported-profile','unsupported-provider','unsupported-route','credential-unavailable','preview-required','busy','stale-preview','stale-settings','concurrent-change','rollback-required','preset-unavailable'];
+    return { code: known.includes(error?.code) ? error.code : 'sync-failed',
+      message: known.includes(error?.code) ? error.message : 'Unable to synchronize. Check the Strata endpoint, connection, API-key credential and supported model metadata.', details: {} };
+  }
+  async function run(action) {
+    ensureOpen();
+    if (inFlight) refuse('busy', 'Another sync operation is running.');
+    inFlight = true;
+    try { return await action(); } finally { inFlight = false; }
+  }
+  async function dispatch(endpoint, data) {
+    try {
+      if (endpoint === 'status') { payload(data); return { ok: true, value: status() }; }
+      const actions = { preview: () => preview(data), apply: () => applyPreview(data), configure: () => configure(data) };
+      if (!own(actions, endpoint)) refuse('invalid-request', 'Unknown Strata Sync action.');
+      return { ok: true, value: await run(actions[endpoint]) };
+    } catch (error) { lastError = safeError(error); return { ok: false, error: lastError }; }
+  }
+  // Native Connection exact routes inherit its Host/Origin/authentication fence.
+  // createSharedFetchHandler only invokes these routes for owner Peers. Keep the
+  // existing /api Typert interceptor untouched and retain the standard RPC envelope.
+  for (const endpoint of ['status', 'preview', 'apply', 'configure']) {
+    ctx.connection.fetch.register({
+      path: `${CHANNEL}/${endpoint}`, methods: ['POST'], requestBody: 'streaming',
+      fetch: async (request) => {
+        let rpcId = 'invalid-request';
+        try {
+          if (request.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase() !== 'application/json') {
+            return new Response('Expected application/json', { status: 415 });
+          }
+          const maximumBytes = 8192;
+          if (Number(request.headers.get('content-length') ?? 0) > maximumBytes) return new Response('Request too large', { status: 413 });
+          const reader = request.body?.getReader();
+          if (!reader) refuse('invalid-request', 'Missing request body.');
+          const chunks = [];
+          let size = 0;
+          try {
+            for (;;) {
+              const chunk = await reader.read();
+              if (chunk.done) break;
+              size += chunk.value.byteLength;
+              if (size > maximumBytes) { await reader.cancel(); return new Response('Request too large', { status: 413 }); }
+              chunks.push(Buffer.from(chunk.value));
+            }
+          } finally { reader.releaseLock(); }
+          let envelope;
+          try { envelope = JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+          catch { refuse('invalid-request', 'Invalid JSON request.'); }
+          payload(envelope, ['type', 'rpcId', 'method', 'payload']);
+          if (envelope.type !== 'client-request' || typeof envelope.rpcId !== 'string' || !envelope.rpcId || envelope.rpcId.length > 128
+            || envelope.method !== `strata-sync/${endpoint}` || !own(envelope, 'payload')) refuse('invalid-request', 'Invalid RPC envelope.');
+          rpcId = envelope.rpcId;
+          return Response.json({ type: 'server-response', rpcId, result: await dispatch(endpoint, envelope.payload) });
+        } catch (error) {
+          return Response.json({ type: 'server-response', rpcId, result: { ok: false, error: safeError(error) } }, { status: 400 });
+        }
+      },
+    });
+  }
+  ctx.on('agent/pre-step', async (_event, next) => {
+    if (writeBarrier) await writeBarrier;
+    return next();
+  }, { prepend: true });
+  const profile = ctx.configEditor.documentPath;
+  if (!startupProfiles.has(profile)) startupProfiles.set(profile, { pending: !!settings.autoSync });
+  const startup = startupProfiles.get(profile);
+  let timer;
+  const poll = async () => {
+    if (closed || !startup.pending) return;
+    try {
+      refreshSettings();
+      if (!settings.autoSync) { startup.pending = false; clearInterval(timer); return; }
+      if (busy() || inFlight || startup.running) return;
+    } catch (error) {
+      // The host can withdraw a required entry during reload. Do not leave an
+      // unhandled timer rejection or retry an unsupported profile indefinitely.
+      lastError = safeError(error);
+      startup.pending = false;
+      clearInterval(timer);
+      return;
+    }
+    // Discovery can outlive an idle period. Busy/disposed attempts keep the one
+    // startup operation pending; successful/no-op and terminal errors consume it.
+    startup.running = true;
+    let deferred = false;
+    try {
+      await run(async () => {
+        const view = await preview();
+        if (view.changes.length && view.fingerprint !== lastFingerprint) await applyPreview({ fingerprint: view.fingerprint, providerId: view.providerId });
+      });
+    } catch (error) {
+      lastError = safeError(error);
+      deferred = error?.code === 'busy' || (closed && error?.code === 'disposed');
+    } finally {
+      startup.running = false;
+      if (!deferred) { startup.pending = false; clearInterval(timer); }
+    }
+  };
+  // DSH 0.2.1-rc.3 can activate us inside HMR's AsyncLocalStorage transaction.
+  // A timer otherwise inherits that transaction forever, so later ConfigEditor
+  // edits are rejected as nested HMR transactions. Mirror Hmr.watchConfig():
+  // detach only timer creation, while every write still uses ConfigEditor and
+  // its normal runExclusive queue. `executing` is a version-specific host seam.
+  // This timer only waits for startup readiness/idle; no recurring server polling.
+  const createTimer = () => setInterval(() => { void poll(); }, 1_000);
+  const executing = ctx.get('hmr')?.executing;
+  if (startup.pending) timer = typeof executing?.exit === 'function' ? executing.exit(createTimer) : createTimer();
+  timer?.unref?.();
+  ctx.effect(() => () => { closed = true; clearInterval(timer); releaseWrite?.(); }, 'strata-sync: startup lifetime');
+}

package/dist/summary.mjs

@@ -0,0 +1,96 @@
+/** A one-sentence, per-request supplement to DSH's native summary instruction. */
+const NATIVE_OPENING = 'You are now acting as a compaction engine for this AI coding assistant.';
+const NATIVE_HEADINGS = ['Primary Request and Intent', 'Key Technical Concepts', 'Files and Code',
+  'Errors and Fixes', 'Pending Jobs', 'Current Work', 'Next Step', 'Critical Context'];
+const GUIDANCE_PREFIX = 'Keep the entire checkpoint, including all required headings, within a target of ';
+const positive = value => Number.isSafeInteger(value) && value > 0;
+// Eight mandatory headings need enough space for a meaningful checkpoint. Do
+// not round a tiny target UP; leave native behavior intact instead.
+export const MIN_SUMMARY_TARGET = 256;
+
+export function planSummaryTarget(contextWindow, summaryMaxTokens, sourceTokens) {
+  if (![contextWindow, summaryMaxTokens, sourceTokens].every(positive)) return null;
+  const target = Math.floor(Math.min(contextWindow / 16, summaryMaxTokens / 2, sourceTokens / 2));
+  return target >= MIN_SUMMARY_TARGET ? target : null;
+}
+
+export function summaryInstruction(target) {
+  if (!positive(target)) throw new TypeError('A positive integer summary target is required.');
+  return `${GUIDANCE_PREFIX}${target} tokens by retaining only information essential to continue the remaining work, consolidating prior summaries, and removing redundant or obsolete details.`;
+}
+
+/** Recognize the shipped native prompt, without storing or replacing its text. */
+export function nativeSummaryMessage(options) {
+  if (options?.purpose !== 'compaction' || !Array.isArray(options.messages)) return null;
+  const message = options.messages.at(-1);
+  if (message?.role !== 'user' || message.content?.length !== 1 || message.content[0]?.type !== 'text') return null;
+  const text = message.content[0].text;
+  if (typeof text !== 'string' || !text.startsWith(NATIVE_OPENING) || text.includes(GUIDANCE_PREFIX)) return null;
+  // Normalize only the recognition view, never the user's native prompt bytes.
+  const recognition = text.replace(/\r\n/g, '\n');
+  let position = 0;
+  for (const heading of NATIVE_HEADINGS) {
+    const next = recognition.indexOf(`\n## ${heading}\n`, position);
+    if (next < position) return null;
+    position = next + heading.length + 4;
+  }
+  if (!recognition.includes('\nRules:\n') || !recognition.includes('Do not copy it forward verbatim:')) return null;
+  return message;
+}
+
+/** Match DSH's text heuristic: four characters/token plus block/role framing.
+ * Price only the selected conversation span, never the system prompt, tool
+ * schemas, or final summary instruction. Unknown attachment pricing falls
+ * back to native behavior rather than inventing a visual/file token count.
+ */
+export function estimateSummarySource(messages) {
+  if (!Array.isArray(messages) || messages.length < 2) return null;
+  let tokens = 0;
+  for (const message of messages.slice(0, -1)) {
+    if (message?.role === 'system') continue;
+    if (!['user', 'assistant', 'tool'].includes(message?.role) || !Array.isArray(message.content)) return null;
+    tokens += 4;
+    for (const block of message.content) {
+      if (['text', 'reasoning'].includes(block?.type) && typeof block.text === 'string') {
+        tokens += 4 + Math.ceil(block.text.length / 4);
+      } else if (block?.type === 'tool-call' && typeof block.name === 'string' && typeof block.arguments === 'string') {
+        tokens += 4 + Math.ceil(block.name.length / 4) + Math.ceil(block.arguments.length / 4);
+      } else return null;
+    }
+  }
+  return positive(tokens) ? tokens : null;
+}
+
+/** The native waterfall's next() closes over options, so replace only its
+ * messages property for the lifetime of this stream; never mutate frozen
+ * messages or recursively dispatch a second LLM request.
+ */
+export function installSummaryGuidance(ctx, resolveContext) {
+  let closed = false;
+  const remove = ctx.on('llm/stream', (options, next) => {
+    const native = nativeSummaryMessage(options);
+    const descriptor = options && Object.getOwnPropertyDescriptor(options, 'messages');
+    if (closed || !native || !descriptor?.writable || options.signal?.aborted) return next();
+    const sourceTokens = estimateSummarySource(options.messages);
+    if (!positive(sourceTokens) || !positive(options.maxTokens)) return next();
+    return (async function* () {
+      const original = options.messages;
+      let augmented;
+      try {
+        let contextWindow;
+        try { contextWindow = await resolveContext(options); }
+        catch { /* Metadata/compatibility failure must not break native inference. */ }
+        const target = planSummaryTarget(contextWindow, options.maxTokens, sourceTokens);
+        if (!closed && !options.signal?.aborted && target !== null && options.messages === original) {
+          const last = { ...native, content: [{ ...native.content[0], text: `${native.content[0].text}\n- ${summaryInstruction(target)}` }] };
+          augmented = [...original.slice(0, -1), last];
+          options.messages = augmented;
+        }
+        yield* next();
+      } finally {
+        if (augmented && options.messages === augmented) options.messages = original;
+      }
+    })();
+  });
+  ctx.effect(() => () => { closed = true; remove?.(); }, 'strata-sync: summary guidance lifetime');
+}