@yanlinglabs/winter-agent-sdk 0.0.20 → 0.0.22

package/dist/{index-qst9rwbb.js → index-0xks1t4r.js}

@@ -118,7 +118,7 @@ function resolveWinterHome2(env, brand) {
     return override;
   const profile = e[envName2(b, "PROFILE")];
   const dirName = profile !== undefined && profile.trim() === "dev" ? `${b.homeDirName}-dev` : b.homeDirName;
-  return join(homedir(), dirName);
+  return join(homedir(), dirName, "sdk");
 }
 function resolveKeychainServiceForProfile2(brand, env, hostSetKeychainService) {
   if (hostSetKeychainService)

package/dist/index.d.ts

@@ -32,6 +32,8 @@ export { resolveWinterHome, resolveKeychainServiceForProfile, isUnset } from "./
 export { transcriptProjectKey, TRANSCRIPT_PROJECT_KEY_MAX_LENGTH, isVendorCompliantProjectKey } from "./paths/project-key.js";
 export { compatibilityKeys } from "./paths/keys.js";
 export type { CompatibilityKeys } from "./paths/keys.js";
+export { globalConfigFileName } from "./paths/global-config.js";
+export { storeHomeEnvName, pluginCacheDirEnvName, providerManagedByHostEnvName, disableCronEnvName } from "./paths/host-env.js";
 export { WinterCompatibilitySessionStore, WinterStoreError, WinterStoreLeaseError, DIALECT_RECORD_ENTRY_TYPE, PROVIDER_STATE_FILE_SUFFIX, } from "./store/session-store.js";
 export type { SessionKey, SessionStoreEntry, SessionSummaryEntry, SessionStore } from "./store/session-store.js";
 export { forkSessionByKey } from "./store/fork-session.js";
@@ -49,3 +51,7 @@ export type { PermissionUpdate, PermissionUpdateDestination, RuleSource } from "
 export type { CanUseTool, PermissionResult, PermissionDecisionClassification, PermissionRequestPayload } from "./permissions/types.js";
 export { HOOK_EVENTS } from "./permissions/types.js";
 export type { HookEvent, HookEventName, HookSource, HookPermissionDecision, BaseHookInput, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, UserPromptSubmitHookInput, StopHookInput, SessionStartHookInput, SessionEndHookInput, NotificationHookInput, PermissionRequestHookInput, PermissionDeniedHookInput, GenericHookInput, HookInput, AsyncHookJSONOutput, SyncHookJSONOutput, HookJSONOutput, PreToolUseHookSpecificOutput, PostToolUseHookSpecificOutput, PostToolUseFailureHookSpecificOutput, UserPromptSubmitHookSpecificOutput, StopHookSpecificOutput, SessionStartHookSpecificOutput, NotificationHookSpecificOutput, PermissionRequestHookSpecificOutput, PermissionDeniedHookSpecificOutput, GenericHookSpecificOutput, HookSpecificOutput, HookCallback, HookCallbackMatcher, HookInvocationPayload, } from "./permissions/types.js";
+export { CATALOG_TAG_RENAMES } from "@yanlinglabs/winter-provider-catalog";
+export { PluginManagerError, listMarketplaces, addMarketplace, removeMarketplace, updateMarketplace, installPlugin, uninstallPlugin, setPluginEnabled, updatePlugin, listPlugins } from "./plugins/manage.js";
+export type { PluginScope, PluginManagerOptions, MarketplaceInfo, InstalledPlugin, PluginListing } from "./plugins/manage.js";
+export { resolveMarketplacePluginPath } from "./plugins/marketplace-path.js";

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   DIALECT_RECORD_ENTRY_TYPE2,
   PROVIDER_STATE_FILE_SUFFIX2,
   WinterCompatibilitySessionStore2
-} from "./index-qst9rwbb.js";
+} from "./index-0xks1t4r.js";
 import {
   deliveryUncertain2,
   refused2,
@@ -1021,7 +1021,7 @@ function query(args) {
   return gen;
 }
 // src/version.ts
-var SDK_VERSION = "0.0.20";
+var SDK_VERSION = "0.0.22";
 // src/paths/project-key.ts
 var TRANSCRIPT_PROJECT_KEY_MAX_LENGTH = 64;
 var VENDOR_PROJECT_KEY_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
@@ -1110,6 +1110,23 @@ function compatibilityKeys(cwd) {
   const memoryKey = commonRoot === null ? cwdKey : transcriptProjectKey(commonRoot);
   return { transcriptProjectKey: cwdKey, memoryProjectKey: memoryKey, tempProjectKey: cwdKey };
 }
+// src/paths/global-config.ts
+function globalConfigFileName(brand) {
+  return `${brand.homeDirName}.json`;
+}
+// src/paths/host-env.ts
+function storeHomeEnvName(brand) {
+  return envName2(brand, "STORE_HOME");
+}
+function pluginCacheDirEnvName(brand) {
+  return envName2(brand, "PLUGIN_CACHE_DIR");
+}
+function providerManagedByHostEnvName(brand) {
+  return envName2(brand, "PROVIDER_MANAGED_BY_HOST");
+}
+function disableCronEnvName(brand) {
+  return envName2(brand, "DISABLE_CRON");
+}
 // src/store/fork-session.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 var IDENTITY_FIELDS = ["providerId", "modelKey", "adapterId", "adapterVersion", "catalogVersion", "authRef", "classifierPin"];
@@ -1442,6 +1459,45 @@ function unionRuleArray(tiersLowestFirst, key) {
   }
   return out.length > 0 ? out : undefined;
 }
+function unionSandboxFilesystemArray(tiersLowestFirst, key) {
+  const seen = new Set;
+  const out = [];
+  for (const tier of tiersLowestFirst) {
+    const sandbox = tier.values["sandbox"];
+    if (!isPlainObject2(sandbox))
+      continue;
+    const filesystem = sandbox["filesystem"];
+    if (!isPlainObject2(filesystem))
+      continue;
+    for (const rule of stringArrayOrUndefined(filesystem[key]) ?? []) {
+      if (seen.has(rule))
+        continue;
+      seen.add(rule);
+      out.push(rule);
+    }
+  }
+  return out.length > 0 ? out : undefined;
+}
+function unionSandboxFilesystemDenyArrays(effective, tiersLowestFirst) {
+  const mergedSandbox = effective["sandbox"];
+  const mergedFilesystem = isPlainObject2(mergedSandbox) ? mergedSandbox["filesystem"] : undefined;
+  const filesystem = isPlainObject2(mergedFilesystem) ? { ...mergedFilesystem } : {};
+  let any = isPlainObject2(mergedFilesystem);
+  for (const key of ["allowWrite", "denyWrite", "allowRead", "denyRead"]) {
+    const unioned = unionSandboxFilesystemArray(tiersLowestFirst, key);
+    if (unioned === undefined)
+      delete filesystem[key];
+    else {
+      filesystem[key] = unioned;
+      any = true;
+    }
+  }
+  if (!any)
+    return;
+  const sandbox = isPlainObject2(mergedSandbox) ? { ...mergedSandbox } : {};
+  sandbox["filesystem"] = filesystem;
+  effective["sandbox"] = sandbox;
+}
 function restrictProviderEnables(effective, tiersLowestFirst) {
   const disabled = new Set;
   for (const tier of tiersLowestFirst) {
@@ -1540,6 +1596,7 @@ async function resolveSettingsDetailed(opts = {}) {
   const overlayFilteredTiers = lowestFirst.map((entry) => ({ values: tierContribution(entry.values, entry.source === "project", trustedWorkspace) }));
   unionPermissionRuleArrays(effective, overlayFilteredTiers);
   restrictProviderEnables(effective, overlayFilteredTiers);
+  unionSandboxFilesystemDenyArrays(effective, overlayFilteredTiers);
   if (!trustedWorkspace) {
     const projectIndex = lowestFirst.findIndex((e) => e.source === "project");
     if (projectIndex !== -1) {
@@ -1740,9 +1797,394 @@ var HOOK_EVENTS = [
   "FileChanged",
   "DirectoryAdded"
 ];
+
+// src/index.ts
+import { CATALOG_TAG_RENAMES } from "@yanlinglabs/winter-provider-catalog";
+
+// src/plugins/manage.ts
+import { mkdir, open, readFile as readFile2, rename, rmdir, unlink, writeFile } from "node:fs/promises";
+import { dirname as dirname3, isAbsolute as isAbsolute2, join as join3, resolve as resolve2 } from "node:path";
+import { randomBytes } from "node:crypto";
+
+// src/plugins/marketplace-path.ts
+import { resolve, sep } from "node:path";
+var BARE_SOURCE_NAME = /^[A-Za-z0-9][-A-Za-z0-9._]*$/;
+function isBareSourceName(source) {
+  return BARE_SOURCE_NAME.test(source) && !source.includes("..");
+}
+function normalizePluginRoot(pluginRoot) {
+  if (typeof pluginRoot !== "string" || pluginRoot === "" || pluginRoot.startsWith("/") || pluginRoot.includes("\\") || pluginRoot.includes(":"))
+    return;
+  const stripped = pluginRoot.replace(/^\.\//, "").replace(/\/+$/, "");
+  if (stripped === "" || stripped === ".")
+    return ".";
+  if (stripped.split("/").some((segment) => segment === "" || segment === "." || segment === ".."))
+    return;
+  return stripped;
+}
+function withPluginRootPrefix(source, normalizedRoot) {
+  if (normalizedRoot === undefined || !isBareSourceName(source))
+    return source;
+  return normalizedRoot === "." ? `./${source}` : `./${normalizedRoot}/${source}`;
+}
+function schemaSourcePath(source) {
+  const normalized = source === "." ? "./" : source;
+  return normalized.startsWith("./") ? normalized : undefined;
+}
+function resolveWithinBase(base, relativePath) {
+  const normalizedBase = resolve(base);
+  const resolved = resolve(base, relativePath);
+  if (resolved !== normalizedBase && !resolved.startsWith(normalizedBase + sep)) {
+    throw new Error(`Path traversal detected: "${relativePath}" would escape the base directory`);
+  }
+  return resolved;
+}
+function resolveMarketplacePluginPath(installLocation, pluginRoot, source) {
+  if (typeof source !== "string" || source === "")
+    return;
+  const normalizedRoot = normalizePluginRoot(pluginRoot);
+  const prefixed = withPluginRootPrefix(source, normalizedRoot);
+  const sourcePath = schemaSourcePath(prefixed);
+  if (sourcePath === undefined)
+    return;
+  try {
+    return resolveWithinBase(installLocation, sourcePath);
+  } catch {
+    return;
+  }
+}
+
+// src/plugins/manage.ts
+class PluginManagerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PluginManagerError";
+  }
+}
+function installedPluginsPath(o) {
+  return join3(o.pluginsRoot, "installed_plugins.json");
+}
+function knownMarketplacesPath(o) {
+  return join3(o.pluginsRoot, "known_marketplaces.json");
+}
+function isEnoent(err) {
+  return err?.code === "ENOENT";
+}
+var RETRYABLE_RENAME_CODES = new Set(["EXDEV", "EPERM", "EEXIST", "EBUSY"]);
+async function writeJsonAtomicNoLock(path, data) {
+  const body = `${JSON.stringify(data, null, 2)}
+`;
+  const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
+  let created = false;
+  try {
+    const handle = await open(tmp, "wx", 384);
+    created = true;
+    try {
+      await handle.writeFile(body, "utf8");
+    } finally {
+      await handle.close();
+    }
+    await rename(tmp, path);
+  } catch (err) {
+    const code = err?.code;
+    if (code === undefined || !RETRYABLE_RENAME_CODES.has(code))
+      throw err;
+    await writeFile(path, body, { encoding: "utf8", mode: 384 });
+    if (created) {
+      try {
+        await unlink(tmp);
+      } catch (cleanupErr) {
+        if (!isEnoent(cleanupErr))
+          throw cleanupErr;
+      }
+    }
+  }
+}
+async function readInstalledPluginsFile(o) {
+  try {
+    const raw = await readFile2(installedPluginsPath(o), "utf8");
+    const parsed = JSON.parse(raw);
+    const plugins = parsed !== null && typeof parsed === "object" && typeof parsed.plugins === "object" && parsed.plugins !== null ? parsed.plugins : {};
+    return { version: 2, plugins };
+  } catch (err) {
+    if (isEnoent(err))
+      return { version: 2, plugins: {} };
+    throw err;
+  }
+}
+var MARKETPLACES_LOCK_ATTEMPTS = 25;
+var MARKETPLACES_LOCK_RETRY_DELAY_MS = 20;
+async function withMarketplacesLock(path, fn) {
+  const lockPath = `${path}.lock`;
+  let acquired = false;
+  for (let attempt = 0;attempt < MARKETPLACES_LOCK_ATTEMPTS; attempt++) {
+    try {
+      await mkdir(lockPath);
+      acquired = true;
+      break;
+    } catch (err) {
+      if (err?.code !== "EEXIST")
+        throw err;
+      await new Promise((r) => setTimeout(r, MARKETPLACES_LOCK_RETRY_DELAY_MS));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    if (acquired) {
+      try {
+        await rmdir(lockPath);
+      } catch (err) {
+        if (!isEnoent(err))
+          throw err;
+      }
+    }
+  }
+}
+async function readKnownMarketplacesFile(o) {
+  try {
+    const raw = await readFile2(knownMarketplacesPath(o), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (err) {
+    if (isEnoent(err))
+      return {};
+    throw err;
+  }
+}
+async function writeKnownMarketplacesFile(path, file) {
+  await writeJsonAtomicNoLock(path, file);
+}
+async function readDirectoryMarketplaceManifest(marketplaceDir) {
+  const manifestPath = join3(marketplaceDir, ".claude-plugin", "marketplace.json");
+  let raw;
+  try {
+    raw = await readFile2(manifestPath, "utf8");
+  } catch (err) {
+    if (isEnoent(err))
+      throw new PluginManagerError(`${manifestPath}: no marketplace manifest there (expected .claude-plugin/marketplace.json under ${marketplaceDir})`);
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new PluginManagerError(`${manifestPath}: malformed JSON (${err.message})`);
+  }
+  if (typeof parsed !== "object" || parsed === null)
+    throw new PluginManagerError(`${manifestPath}: expected a JSON object at the top level`);
+  const obj = parsed;
+  if (typeof obj.name !== "string" || obj.name.length === 0)
+    throw new PluginManagerError(`${manifestPath}: missing required "name"`);
+  if (!Array.isArray(obj.plugins))
+    throw new PluginManagerError(`${manifestPath}: missing required "plugins" array`);
+  return {
+    name: obj.name,
+    plugins: obj.plugins,
+    ...obj.version !== undefined ? { version: obj.version } : {},
+    ...obj.description !== undefined ? { description: obj.description } : {},
+    ...obj.metadata !== undefined ? { metadata: obj.metadata } : {}
+  };
+}
+function classifySource(source) {
+  if (/^https?:\/\//i.test(source))
+    return { kind: "url", locator: source };
+  if (/^git@[^:]+:/i.test(source) || /^git\+/i.test(source) || /\.git$/i.test(source))
+    return { kind: "git", locator: source };
+  if (/^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?\/[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/.test(source) && !source.includes("..")) {
+    return { kind: "github", locator: source };
+  }
+  return { kind: "directory", locator: isAbsolute2(source) ? source : resolve2(source) };
+}
+function marketplaceInfoOf(name, record) {
+  const kind = record.source.source;
+  const source = record.source.path ?? record.source.url ?? record.source.repo ?? record.installLocation;
+  return { name, source, kind, path: record.installLocation };
+}
+function parseSpec(spec) {
+  const at = spec.lastIndexOf("@");
+  if (at <= 0 || at === spec.length - 1) {
+    throw new PluginManagerError(`plugin spec must be "<name>@<marketplace>" (got ${JSON.stringify(spec)}) -- bare-name marketplace inference is not implemented in this build`);
+  }
+  return { name: spec.slice(0, at), marketplace: spec.slice(at + 1) };
+}
+function keyFor(name, marketplace) {
+  return `${name}@${marketplace}`;
+}
+async function readEnabledFromSettings(o, scope, key) {
+  const loaded = await loadSettingsFile(o.settingsPathFor(scope));
+  return loaded.values.enabledPlugins?.[key] === true;
+}
+function assertSettingsWritable(loaded, path) {
+  if (loaded.present && !loaded.loaded) {
+    throw new PluginManagerError(`${path}: cannot update enabledPlugins -- the file exists but ${loaded.error ?? "could not be read"}; fix it by hand first`);
+  }
+}
+async function setEnabledInSettings(o, scope, key, enabled) {
+  const path = o.settingsPathFor(scope);
+  const loaded = await loadSettingsFile(path);
+  assertSettingsWritable(loaded, path);
+  const settings = { ...loaded.values };
+  const enabledPlugins = { ...settings.enabledPlugins ?? {} };
+  if (enabled === undefined)
+    delete enabledPlugins[key];
+  else
+    enabledPlugins[key] = enabled;
+  settings.enabledPlugins = enabledPlugins;
+  await mkdir(dirname3(path), { recursive: true });
+  await writeJsonAtomicNoLock(path, settings);
+}
+async function listMarketplaces(o) {
+  const file = await readKnownMarketplacesFile(o);
+  return Object.entries(file).map(([name, rec]) => marketplaceInfoOf(name, rec));
+}
+async function addMarketplace(o, source) {
+  const classification = classifySource(source);
+  if (classification.kind !== "directory") {
+    throw new PluginManagerError(`marketplace source kind "${classification.kind}" is not supported in this build (no network) -- only local directory marketplaces can be added; got ${JSON.stringify(source)}`);
+  }
+  const dir = classification.locator;
+  const manifest = await readDirectoryMarketplaceManifest(dir);
+  await mkdir(o.pluginsRoot, { recursive: true });
+  const path = knownMarketplacesPath(o);
+  const record = {
+    source: { source: "directory", path: dir },
+    installLocation: dir,
+    lastUpdated: new Date().toISOString(),
+    autoUpdate: false
+  };
+  await withMarketplacesLock(path, async () => {
+    const file = await readKnownMarketplacesFile(o);
+    file[manifest.name] = record;
+    await writeKnownMarketplacesFile(path, file);
+  });
+  return marketplaceInfoOf(manifest.name, record);
+}
+async function removeMarketplace(o, name) {
+  const path = knownMarketplacesPath(o);
+  await withMarketplacesLock(path, async () => {
+    const file = await readKnownMarketplacesFile(o);
+    if (!(name in file))
+      throw new PluginManagerError(`marketplace "${name}" is not known`);
+    delete file[name];
+    await writeKnownMarketplacesFile(path, file);
+  });
+}
+async function updateMarketplace(o, name) {
+  const path = knownMarketplacesPath(o);
+  await withMarketplacesLock(path, async () => {
+    const file = await readKnownMarketplacesFile(o);
+    const names = name !== undefined ? [name] : Object.keys(file);
+    for (const n of names) {
+      const rec = file[n];
+      if (rec === undefined)
+        throw new PluginManagerError(`marketplace "${n}" is not known`);
+      if (rec.source.source !== "directory") {
+        throw new PluginManagerError(`marketplace "${n}" has source kind "${rec.source.source}", which this build cannot refresh (no network)`);
+      }
+      await readDirectoryMarketplaceManifest(rec.installLocation);
+      rec.lastUpdated = new Date().toISOString();
+    }
+    await writeKnownMarketplacesFile(path, file);
+  });
+}
+async function resolvePluginSourcePath(o, name, marketplace) {
+  const marketplaces = await readKnownMarketplacesFile(o);
+  const rec = marketplaces[marketplace];
+  if (rec === undefined)
+    throw new PluginManagerError(`marketplace "${marketplace}" is not known -- add it first`);
+  if (rec.source.source !== "directory") {
+    throw new PluginManagerError(`marketplace "${marketplace}" has source kind "${rec.source.source}", which this build cannot install from (no network)`);
+  }
+  const manifest = await readDirectoryMarketplaceManifest(rec.installLocation);
+  const entry = manifest.plugins.find((p) => p.name === name);
+  if (entry === undefined)
+    throw new PluginManagerError(`plugin "${name}" is not listed by marketplace "${marketplace}"`);
+  if (typeof entry.source !== "string") {
+    throw new PluginManagerError(`plugin "${name}@${marketplace}" declares a non-local source, which this build cannot install (no network)`);
+  }
+  const installPath = resolveMarketplacePluginPath(rec.installLocation, manifest.metadata?.pluginRoot, entry.source);
+  if (installPath === undefined) {
+    throw new PluginManagerError(`plugin "${name}@${marketplace}" declares a source (${JSON.stringify(entry.source)}) this build refuses to resolve -- it must be a "./relative/path" under the marketplace root (or a bare name when the marketplace's own metadata.pluginRoot is set), and must not escape the marketplace directory`);
+  }
+  return { installPath, version: entry.version };
+}
+async function installPlugin(o, spec, scope) {
+  const { name, marketplace } = parseSpec(spec);
+  const settingsPath = o.settingsPathFor(scope);
+  assertSettingsWritable(await loadSettingsFile(settingsPath), settingsPath);
+  const { installPath, version } = await resolvePluginSourcePath(o, name, marketplace);
+  const key = keyFor(name, marketplace);
+  await mkdir(o.pluginsRoot, { recursive: true });
+  const now = new Date().toISOString();
+  const record = { scope, installPath, installedAt: now, ...version !== undefined ? { version } : {} };
+  const file = await readInstalledPluginsFile(o);
+  const existing = file.plugins[key] ?? [];
+  file.plugins[key] = [...existing.filter((r) => r.scope !== scope), record];
+  await writeJsonAtomicNoLock(installedPluginsPath(o), file);
+  await setEnabledInSettings(o, scope, key, true);
+  return { id: name, installPath, scope, ...version !== undefined ? { version } : {} };
+}
+async function uninstallPlugin(o, spec, scope) {
+  const { name, marketplace } = parseSpec(spec);
+  const key = keyFor(name, marketplace);
+  const settingsPath = o.settingsPathFor(scope);
+  assertSettingsWritable(await loadSettingsFile(settingsPath), settingsPath);
+  const file = await readInstalledPluginsFile(o);
+  const existing = file.plugins[key];
+  const remaining = (existing ?? []).filter((r) => r.scope !== scope);
+  if (existing === undefined || remaining.length === existing.length) {
+    throw new PluginManagerError(`plugin "${key}" is not installed at scope "${scope}"`);
+  }
+  if (remaining.length > 0)
+    file.plugins[key] = remaining;
+  else
+    delete file.plugins[key];
+  await writeJsonAtomicNoLock(installedPluginsPath(o), file);
+  await setEnabledInSettings(o, scope, key, undefined);
+}
+async function setPluginEnabled(o, spec, scope, enabled) {
+  const { name, marketplace } = parseSpec(spec);
+  const key = keyFor(name, marketplace);
+  const file = await readInstalledPluginsFile(o);
+  if (!(file.plugins[key]?.some((r) => r.scope === scope) ?? false)) {
+    throw new PluginManagerError(`plugin "${key}" is not installed at scope "${scope}"`);
+  }
+  await setEnabledInSettings(o, scope, key, enabled);
+}
+async function updatePlugin(o, spec) {
+  const { name, marketplace } = parseSpec(spec);
+  const key = keyFor(name, marketplace);
+  const file = await readInstalledPluginsFile(o);
+  const records = file.plugins[key];
+  if (records === undefined || records.length === 0)
+    throw new PluginManagerError(`plugin "${key}" is not installed`);
+  const { installPath, version } = await resolvePluginSourcePath(o, name, marketplace);
+  const now = new Date().toISOString();
+  const updated = records.map((r) => ({ ...r, installPath, lastUpdated: now, ...version !== undefined ? { version } : {} }));
+  file.plugins[key] = updated;
+  await writeJsonAtomicNoLock(installedPluginsPath(o), file);
+  const last = updated[updated.length - 1];
+  return { id: name, installPath, scope: last.scope, ...version !== undefined ? { version } : {} };
+}
+async function listPlugins(o) {
+  const file = await readInstalledPluginsFile(o);
+  const out = [];
+  for (const [key, records] of Object.entries(file.plugins)) {
+    const at = key.lastIndexOf("@");
+    const name = at > 0 ? key.slice(0, at) : key;
+    const marketplace = at > 0 ? key.slice(at + 1) : "";
+    for (const rec of records) {
+      const enabled = await readEnabledFromSettings(o, rec.scope, key);
+      out.push({ id: name, installPath: rec.installPath, scope: rec.scope, enabled, marketplace, ...rec.version !== undefined ? { version: rec.version } : {} });
+    }
+  }
+  return out;
+}
 export {
   AbortError,
   BRAND_TOKEN_RE2 as BRAND_TOKEN_RE,
+  CATALOG_TAG_RENAMES,
   CLIConnectionError,
   DEFAULT_COMPACTION_THRESHOLD,
   DEFAULT_CONTEXT_WINDOW_TOKENS,
@@ -1763,6 +2205,7 @@ export {
   PROJECT_PERMISSIVE_KEYS,
   PROTOCOL_VERSION,
   PROVIDER_STATE_FILE_SUFFIX2 as PROVIDER_STATE_FILE_SUFFIX,
+  PluginManagerError,
   ProcessError,
   ProtocolDecodeError,
   ProtocolError,
@@ -1780,11 +2223,13 @@ export {
   WinterSDKError,
   WinterStoreError2 as WinterStoreError,
   WinterStoreLeaseError2 as WinterStoreLeaseError,
+  addMarketplace,
   applyWorkspaceTrust,
   compatibilityKeys,
   decodeFrame,
   defaultSpawn,
   deleteSession,
+  disableCronEnvName,
   encodeFrame,
   envName2 as envName,
   filterEscalatingDefaultMode,
@@ -1793,6 +2238,8 @@ export {
   getSessionInfo,
   getSessionMessages,
   getSubagentMessages,
+  globalConfigFileName,
+  installPlugin,
   isDeliveryOutcome,
   isGlobalAgentMessage,
   isListedRuntimeObjectArray,
@@ -1808,25 +2255,36 @@ export {
   isUnset2 as isUnset,
   isVendorCompliantProjectKey,
   isWinterMcpServerInstance,
+  listMarketplaces,
+  listPlugins,
   listSessions,
   listSubagents,
   loadSettingsFile,
   mcpToolName2 as mcpToolName,
+  pluginCacheDirEnvName,
+  providerManagedByHostEnvName,
   providerSettingsFrom,
   query,
+  removeMarketplace,
   renameSession,
   resolveBrand2 as resolveBrand,
   resolveFacetTarget,
   resolveKeychainServiceForProfile2 as resolveKeychainServiceForProfile,
+  resolveMarketplacePluginPath,
   resolveRuntimeExecutable,
   resolveSettings,
   resolveSettingsDetailed,
   resolveWebToolsConfig,
   resolveWinterHome2 as resolveWinterHome,
+  setPluginEnabled,
   settingsPathFor,
   splitFrames,
+  storeHomeEnvName,
   tagSession,
   transcriptProjectKey,
+  uninstallPlugin,
+  updateMarketplace,
+  updatePlugin,
   userAgent2 as userAgent,
   validateModelSlots
 };

package/dist/paths/global-config.d.ts

@@ -0,0 +1,7 @@
+import type { BrandProfile } from "../brand.js";
+/**
+ * `<brand.homeDirName>.json` -- `.winter.json` for Winter's own brand. `brand.homeDirName` is
+ * documented (`brand.ts`) as never containing a slash, so this is always a single path segment,
+ * safe to `join` onto any directory without further validation.
+ */
+export declare function globalConfigFileName(brand: Pick<BrandProfile, "homeDirName">): string;

package/dist/paths/home.d.ts

@@ -19,9 +19,21 @@ export type HomeBrand = Pick<BrandProfile, "envPrefix" | "homeDirName">;
  * (packages/runtime/src/brand-gate.test.ts, rules 9 and 10) is what keeps it that way.
  *
  * PRECEDENCE (WS-01 §2.2, and the same rule the current daemon has always had): an explicit
- * `<PREFIX>HOME` wins over EVERYTHING, including the dev profile. `<PREFIX>PROFILE=dev` selects
- * `~/<homeDirName>-dev` — the dev/dist split, so a development build can never share a home (or a
- * transcript store, or a settings file) with the copy a user actually runs.
+ * `<PREFIX>HOME` wins over EVERYTHING, including the dev profile and the WS-21 `sdk` suffix below.
+ * `<PREFIX>PROFILE=dev` selects `~/<homeDirName>-dev/sdk` — the dev/dist split, so a development
+ * build can never share a home (or a transcript store, or a settings file) with the copy a user
+ * actually runs.
+ *
+ * WS-21 §6.3 item 8: the DEFAULT (no `<PREFIX>HOME`, no explicit `brand`-threaded value) is now
+ * `~/<homeDirName>/sdk`, not `~/<homeDirName>` -- Contract A's `sdkHomeOf(home) = join(home, "sdk")`,
+ * inlined here rather than imported (the router that exports it is a separate package this SDK
+ * never depends on). `brand.homeDirName` cannot contain a slash (`brand.ts`'s own validation), so
+ * this is always exactly one extra path segment. This changes ONLY the bare-default case: every
+ * router-routed session gets an EXPLICIT `WINTER_HOME` (the Global Constraints list: "only the
+ * router sets ... WINTER_HOME"), which still wins outright, and the daemon's own pre-router-link
+ * fallback threads its own value too (`session-driver.ts`'s `WINTER_HOME` default, unaffected by
+ * this function). A bare `winter` invocation with no env override is the only caller this moves --
+ * consistent with the shared runtime home being the thing the SDK itself now means by "home".
  */
 export declare function resolveWinterHome(env?: Record<string, string | undefined>, brand?: HomeBrand): string;
 /**

package/dist/paths/host-env.d.ts

@@ -0,0 +1,11 @@
+import { type BrandProfile } from "../brand.js";
+type EnvPrefixBrand = Pick<BrandProfile, "envPrefix">;
+/** `WINTER_STORE_HOME` -- the shared runtime home's durable-paths root (spec §3.7). No claude twin. */
+export declare function storeHomeEnvName(brand: EnvPrefixBrand): string;
+/** `WINTER_PLUGIN_CACHE_DIR` -- the twin of `CLAUDE_CODE_PLUGIN_CACHE_DIR` (F15). */
+export declare function pluginCacheDirEnvName(brand: EnvPrefixBrand): string;
+/** `WINTER_PROVIDER_MANAGED_BY_HOST` -- the twin of `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` (F20). */
+export declare function providerManagedByHostEnvName(brand: EnvPrefixBrand): string;
+/** `WINTER_DISABLE_CRON` -- the twin of `CLAUDE_CODE_DISABLE_CRON` (F19a). */
+export declare function disableCronEnvName(brand: EnvPrefixBrand): string;
+export {};

package/dist/plugins/manage.d.ts

@@ -0,0 +1,37 @@
+export declare class PluginManagerError extends Error {
+    constructor(message: string);
+}
+export type PluginScope = "user" | "project" | "local";
+export interface PluginManagerOptions {
+    /** claude's plugins root (WS-21 §6.3 item 5: `storeHome/plugins`) -- `installed_plugins.json` and `known_marketplaces.json` live directly under it. */
+    pluginsRoot: string;
+    /** The `enabledPlugins` carrier for one scope -- the settings file at that tier (the shared runtime home's own `settings.json` for `user`; the project dir's `settings.json`/`settings.local.json` for `project`/`local`). */
+    settingsPathFor(scope: PluginScope): string;
+}
+export interface MarketplaceInfo {
+    name: string;
+    /** The human-facing locator: the directory path, the repo `owner/repo`, or the URL -- whichever the source kind carries. */
+    source: string;
+    kind: "directory" | "git" | "github" | "url";
+    /** Where the marketplace's own content lives on disk. For `directory`, this IS the source (read in place, F15). */
+    path: string;
+}
+export interface InstalledPlugin {
+    id: string;
+    version?: string;
+    installPath: string;
+    scope: PluginScope;
+}
+export interface PluginListing extends InstalledPlugin {
+    enabled: boolean;
+    marketplace: string;
+}
+export declare function listMarketplaces(o: PluginManagerOptions): Promise<MarketplaceInfo[]>;
+export declare function addMarketplace(o: PluginManagerOptions, source: string): Promise<MarketplaceInfo>;
+export declare function removeMarketplace(o: PluginManagerOptions, name: string): Promise<void>;
+export declare function updateMarketplace(o: PluginManagerOptions, name?: string): Promise<void>;
+export declare function installPlugin(o: PluginManagerOptions, spec: string, scope: PluginScope): Promise<InstalledPlugin>;
+export declare function uninstallPlugin(o: PluginManagerOptions, spec: string, scope: PluginScope): Promise<void>;
+export declare function setPluginEnabled(o: PluginManagerOptions, spec: string, scope: PluginScope, enabled: boolean): Promise<void>;
+export declare function updatePlugin(o: PluginManagerOptions, spec: string): Promise<InstalledPlugin>;
+export declare function listPlugins(o: PluginManagerOptions): Promise<PluginListing[]>;

package/dist/plugins/marketplace-path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolve one marketplace manifest plugin entry's install path -- the ONE function
+ * `packages/runtime/src/plugins/installed.ts` (the daemon's own directory-marketplace fallback,
+ * SV-4) and `packages/sdk/src/plugins/manage.ts` (`resolvePluginSourcePath`, the CLI-facing install
+ * command) both call, so the two can never resolve the identical manifest entry to two different
+ * paths. `undefined` for anything invalid or refused -- a bare name with no usable `pluginRoot`, an
+ * absolute/malformed source, or a path that would escape `installLocation` -- NEVER a throw a
+ * caller must remember to catch; each caller renders its own typed rejection from `undefined`.
+ */
+export declare function resolveMarketplacePluginPath(installLocation: string, pluginRoot: unknown, source: unknown): string | undefined;

package/dist/protocol/config.d.ts

@@ -88,7 +88,9 @@ export interface SandboxSettingsConfig {
     filesystem?: {
         allowWrite?: string[];
         denyWrite?: string[];
+        allowRead?: string[];
         denyRead?: string[];
+        allowGitConfig?: boolean;
     };
     network?: {
         allowedDomains?: string[];
@@ -219,6 +221,17 @@ export interface RuntimeConfig {
     resumeDropsTurn?: boolean;
     persistSession?: boolean;
     winterHome?: string;
+    /**
+     * WS-21 §3.7/§6.3 item 11: the shared runtime home's durable-paths root (`storeHomeEnvName`'s
+     * value) and the claude-`CLAUDE_CODE_PLUGIN_CACHE_DIR` twin, next to `winterHome` for a host that
+     * assembles `--config-json` directly rather than only setting the child's env. The CANONICAL
+     * channel is still the child's own env (`production-wiring.ts` reads `config.storeHome ??
+     * env[storeHomeEnvName(brand)]`, the same precedence `winterHome` already has over
+     * `resolveWinterHome(env, brand)`) -- these two fields exist so a host with no separate env-setting
+     * step has an equivalent one.
+     */
+    storeHome?: string;
+    pluginCacheDir?: string;
     allowedTools?: string[];
     disallowedTools?: string[];
     permissions?: {

package/dist/settings/types.d.ts

@@ -5,7 +5,7 @@ import type { BrandProfile } from "../brand.js";
  * caller can thread three fields rather than construct one.
  */
 export type SettingsBrand = Pick<BrandProfile, "envPrefix" | "homeDirName" | "projectDirName">;
-import type { ModelSlotSetting } from "../protocol/config.js";
+import type { ModelSlotSetting, SandboxSettingsConfig } from "../protocol/config.js";
 /** The three settings FILE tiers a session may load. `sdk.d.ts:7917`, verbatim and in pinned order. */
 export type SettingSource = "user" | "project" | "local";
 /** Pinned order (`sdk.d.ts:7917`). Also the value `settingSources: undefined` means (all three). */
@@ -39,6 +39,35 @@ export interface SettingsPermissionsBlock {
 }
 export interface Settings {
     permissions?: SettingsPermissionsBlock;
+    /**
+     * SV-11 (WS-21 fix round 9, security): the CC-shaped sandbox configuration surface, same shape as
+     * `RuntimeConfig.sandbox` (`protocol/config.ts`'s own `SandboxSettingsConfig`, kept structurally
+     * identical to `packages/runtime/src/sandbox/profile.ts`'s `SandboxSettings` for the same
+     * WS-02 §3 reason that type's own header states). Before this field existed, Winter's runtime read
+     * ONLY the host-supplied `RuntimeConfig.sandbox`, ignoring `settings.json`'s own `sandbox` block
+     * entirely -- a denied write from a plain, un-escalated `sandbox.filesystem.denyWrite` path went
+     * through unsandboxed, silently, because nothing ever threaded that key into the running sandbox at
+     * all (not a merge-precedence bug; there was no merge). `production-wiring.ts` now feeds the host's
+     * own `RuntimeConfig.sandbox` into this resolution as the `flag` tier (claude's own architecture:
+     * its SDK `Options` occupies the identical tier position for this same setting), and reads the
+     * result back off `effective.sandbox` into the config it actually hands the engine.
+     *
+     * ALL FOUR `filesystem` arrays -- `allowWrite`, `denyWrite`, `allowRead`, `denyRead` -- UNION
+     * across every tier (deep-merge's ordinary replace-by-higher-tier would let a higher tier
+     * silently drop a lower tier's own restriction -- the identical fail-open shape
+     * `permissions.deny`'s own union exists to prevent; see `unionSandboxFilesystemDenyArrays` below).
+     * CORRECTED in fix round 10, item C: round 9 reasoned `allowWrite` should NOT union (a widening
+     * key should never accumulate) and used the ordinary replace-by-higher-tier merge for it instead
+     * -- the controller's round-10 ruling reverses this, dump-confirmed against claude's own live
+     * sandbox-reconciliation code unioning its OWN rule-derived allowWrite set with the native
+     * sandbox's currently-configured one (`xr=se([...yr,...$r.filter(...)])`, not a replacement).
+     * Claude itself unions the widening array too; ported here to match. `allowRead` (also new this
+     * round) is claude's own read carve-out (`getFsReadConfig`'s `allowWithinDeny`) -- carried and
+     * unioned identically for merge-parity, though `packages/runtime/src/sandbox/profile.ts`'s own
+     * `buildSeatbeltProfile` does not yet enforce it (a disclosed, fails-CLOSED gap: see that file's
+     * own `SandboxFilesystemSettings.allowRead` doc comment).
+     */
+    sandbox?: SandboxSettingsConfig;
     hooks?: SettingsHooksConfig;
     env?: Record<string, string>;
     apiKeyHelper?: string;

package/dist/tools/index.js

@@ -8,7 +8,7 @@ import {
 import {
   resolveWinterHome2,
   WinterCompatibilitySessionStore2
-} from "../index-qst9rwbb.js";
+} from "../index-0xks1t4r.js";
 
 // src/tools/schemas.ts
 var SEND_MESSAGE_TO_MAX = 300;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanlinglabs/winter-agent-sdk",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -45,15 +45,15 @@
     }
   },
   "dependencies": {
-    "@yanlinglabs/winter-provider-catalog": "0.0.20"
+    "@yanlinglabs/winter-provider-catalog": "0.0.22"
   },
   "optionalDependencies": {
-    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.20"
+    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.22"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",
-    "@yanlinglabs/winter-conformance": "0.0.20",
-    "winter-agent-runtime": "0.0.20"
+    "@yanlinglabs/winter-conformance": "0.0.22",
+    "winter-agent-runtime": "0.0.22"
   },
   "scripts": {}
 }