@cursor/bdk 0.2.1

package/src/internal/framework-file-storage.ts

@@ -0,0 +1,357 @@
+/**
+ * Framework-level file storage for v2 hosted engines.
+ *
+ * Hosted deployments carry two file stores with different audiences:
+ *
+ * - the **user-level** store (`AGENT_SERVE_STORE_SOURCE_ID`) holds
+ *   author-facing bytes — `ctx.host.files`, skills, memory, artifacts — and
+ *   is browsable from the dashboard and mountable on cloud-runtime VMs;
+ * - the **framework-level** store (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`)
+ *   holds engine-owned session state — session records, event transcripts,
+ *   hosted-execution run logs, the continuation index, and the SDK
+ *   conversation mirror — and is never mounted into author code or models.
+ *   The authenticated dashboard may read diagnostic families, but never the
+ *   continuation index.
+ *
+ * This module puts framework session state on the framework store. The
+ * {@link storageKeys} scheme was designed for exactly this: keys are a
+ * stable versioned contract that sinks may route on, so
+ * {@link composeFrameworkStorage} splits one {@link StorageConfig} by key
+ * kind — `session` / `session-events` / `session-runs` / `logs` /
+ * `continuation` go to the framework file store (file-shaped; the store
+ * accepts values up to 64 MiB per
+ * object without chunking, versus the KV proxy's 1 MiB row cap), while
+ * author `kv`, eval runs, and conditional writes stay on the control-plane
+ * KV proxy (the dashboard reads them there, and CAS needs a database).
+ *
+ * v2 only, by construction: the composite is selected in
+ * framework-storage-selection.ts, which v1 never reaches with a
+ * platform-selected definition.
+ */
+
+import type { FileSink } from "../files.js";
+import type { StorageConfig, StorageEntry } from "../storage.js";
+import { AGENTSDK_STORAGE_KEY_ROOT } from "../storage-protocol.js";
+import type { JsonValue } from "../types.js";
+import { mapBounded } from "./bounded.js";
+
+/**
+ * Key kinds (`agentsdk/v1/{agent}/{kind}/…`) that live on the framework
+ * file store. Everything else stays on the KV sink.
+ */
+const FRAMEWORK_FILE_KINDS: ReadonlySet<string> = new Set([
+  "session",
+  "session-events",
+  "session-runs",
+  "logs",
+  "continuation",
+]);
+
+/**
+ * Whether a framework-minted key (or list prefix) belongs on the framework
+ * file store. Prefixes used by the coordinator are always at least
+ * kind-scoped (`…/{agent}/session/`), so a prefix routes wholly to one side.
+ */
+export function isFrameworkFileKey(key: string): boolean {
+  if (!key.startsWith(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
+    return false;
+  }
+  const rest = key.slice(AGENTSDK_STORAGE_KEY_ROOT.length + 1);
+  const agentEnd = rest.indexOf("/");
+  if (agentEnd === -1) {
+    return false;
+  }
+  const afterAgent = rest.slice(agentEnd + 1);
+  const kindEnd = afterAgent.indexOf("/");
+  const kind = kindEnd === -1 ? afterAgent : afterAgent.slice(0, kindEnd);
+  return FRAMEWORK_FILE_KINDS.has(kind);
+}
+
+/**
+ * The KV core over a {@link FileSink}: one JSON document per key.
+ * `putMany` stays optional — the KV-proxy core has no batch write, and the
+ * composite falls back to sequential puts on a side without one.
+ */
+export type FileSinkStorageCore = Required<Pick<StorageConfig, "put" | "get" | "delete" | "list">> &
+  Pick<StorageConfig, "putMany">;
+
+/** Parallel per-key reads backing `list` (each is presign + object GET). */
+const LIST_READ_CONCURRENCY = 8;
+
+/**
+ * A storage key whose path the file store cannot represent (an empty, `.`,
+ * or `..` segment — possible only through caller-controlled segments such
+ * as continuation tokens or a caller-supplied session id). Such an object
+ * can never exist in the store, so reads are a definitive miss rather than
+ * a per-request 400 that the lazy-restore path would propagate forever.
+ */
+function isUnrepresentableFileKey(key: string): boolean {
+  return key.split("/").some(segment => segment === "" || segment === "." || segment === "..");
+}
+
+/**
+ * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
+ * framework-minted (URI-encoded, length-bounded segments — see
+ * {@link storageKeys}), so they are used as file keys verbatim; values are
+ * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
+ * corrupt document must fail the follow-up rather than read as a miss, and
+ * the startup bulk restore already logs-and-skips a throwing `list`.
+ */
+export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
+  return {
+    async put(key, value): Promise<void> {
+      if (isUnrepresentableFileKey(key)) {
+        // Loud rather than silent: the coordinator logs and drops failed
+        // mirror writes (at-most-once), and awaited callers must not
+        // believe an impossible write landed.
+        throw new Error(
+          `framework file storage: key "${key}" has a path segment the store cannot represent`,
+        );
+      }
+      await sink.put(key, encodeDocument(key, value));
+    },
+    async putMany(entries): Promise<Array<{ key: string; error?: unknown }>> {
+      const results: Array<{ key: string; error?: unknown }> = entries.map(entry => ({
+        key: entry.key,
+      }));
+      const writable: Array<{ index: number; key: string; body: Uint8Array }> = [];
+      for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (entry === undefined) {
+          continue;
+        }
+        if (isUnrepresentableFileKey(entry.key)) {
+          results[index] = {
+            key: entry.key,
+            error: new Error(
+              `framework file storage: key "${entry.key}" has a path segment the store cannot represent`,
+            ),
+          };
+          continue;
+        }
+        writable.push({
+          index,
+          key: entry.key,
+          body: encodeDocument(entry.key, entry.value),
+        });
+      }
+      if (writable.length === 0) {
+        return results;
+      }
+      if (sink.putMany !== undefined) {
+        // The point of the batch: one backend round trip for the flush.
+        const settled = await sink.putMany(writable.map(({ key, body }) => ({ key, body })));
+        for (let i = 0; i < writable.length; i += 1) {
+          const target = writable[i];
+          const outcome = settled[i];
+          if (target === undefined) {
+            continue;
+          }
+          if (outcome?.status === "rejected") {
+            results[target.index] = { key: target.key, error: outcome.reason };
+          }
+        }
+        return results;
+      }
+      // No batch support: sequential puts, preserving the sink's strict
+      // one-at-a-time ordering contract.
+      for (const target of writable) {
+        try {
+          await sink.put(target.key, target.body);
+        } catch (error) {
+          results[target.index] = { key: target.key, error };
+        }
+      }
+      return results;
+    },
+    async get(key): Promise<JsonValue | undefined> {
+      if (isUnrepresentableFileKey(key)) {
+        return undefined;
+      }
+      const body = await sink.get(key);
+      if (body === undefined) {
+        return undefined;
+      }
+      return decodeDocument(key, body instanceof Uint8Array ? body : body.body);
+    },
+    async delete(key): Promise<void> {
+      if (isUnrepresentableFileKey(key)) {
+        return;
+      }
+      await sink.delete(key);
+    },
+    async list(prefix): Promise<StorageEntry[]> {
+      const entries = await sink.list(prefix);
+      // FileSink.list returns metadata only, so the values are their own
+      // reads. Prefer the sink's batched read — on the hosted sink that is
+      // one control-plane call per 100 keys instead of one per key, which is
+      // what keeps a big restore under the store's per-deployment rate
+      // budget — and fall back to bounded per-key gets elsewhere.
+      const bodies =
+        sink.getMany !== undefined
+          ? await sink.getMany(entries.map(entry => entry.key))
+          : await mapBounded(entries, LIST_READ_CONCURRENCY, entry => sink.get(entry.key));
+      const out: StorageEntry[] = [];
+      for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        const body = bodies[index];
+        if (entry === undefined || body === undefined) {
+          // Deleted between list and read; a miss is not corruption.
+          continue;
+        }
+        out.push({
+          key: entry.key,
+          value: decodeDocument(entry.key, body instanceof Uint8Array ? body : body.body),
+        });
+      }
+      return out;
+    },
+  };
+}
+
+function frameworkFileKind(key: string): string | undefined {
+  if (!key.startsWith(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
+    return undefined;
+  }
+  const rest = key.slice(AGENTSDK_STORAGE_KEY_ROOT.length + 1);
+  const agentEnd = rest.indexOf("/");
+  if (agentEnd === -1) {
+    return undefined;
+  }
+  const afterAgent = rest.slice(agentEnd + 1);
+  const kindEnd = afterAgent.indexOf("/");
+  return kindEnd === -1 ? afterAgent : afterAgent.slice(0, kindEnd);
+}
+
+function isLogKey(key: string): boolean {
+  return frameworkFileKind(key) === "logs";
+}
+
+function encodeDocument(key: string, value: JsonValue): Uint8Array {
+  // start.log is raw UTF-8, not a JSON document. Stringify would quote
+  // every line and store a JSON string literal instead of the tee.
+  if (isLogKey(key)) {
+    return new TextEncoder().encode(typeof value === "string" ? value : JSON.stringify(value));
+  }
+  return new TextEncoder().encode(JSON.stringify(value));
+}
+
+function decodeDocument(key: string, bytes: Uint8Array): JsonValue {
+  const text = new TextDecoder().decode(bytes);
+  if (isLogKey(key)) {
+    return text;
+  }
+  try {
+    return JSON.parse(text) as JsonValue;
+  } catch (error) {
+    throw new Error(
+      `framework file storage: stored document at "${key}" is not JSON (${
+        error instanceof Error ? error.message : String(error)
+      })`,
+    );
+  }
+}
+
+/**
+ * Split one storage core by key kind: framework session state to `files`,
+ * everything else to `kv`. Spread over the KV backend when building the
+ * full definition so its `evals` group (and the cursor-hosted marker)
+ * rides along untouched; wrap the KV `cas` group with
+ * {@link frameworkGuardedCas} rather than spreading it as-is.
+ */
+export function composeFrameworkStorage(input: {
+  kv: FileSinkStorageCore;
+  files: FileSinkStorageCore;
+}): FileSinkStorageCore & Pick<StorageConfig, "listNewest"> {
+  const route = (key: string): FileSinkStorageCore =>
+    isFrameworkFileKey(key) ? input.files : input.kv;
+  return {
+    put: (key, value, ctx) => route(key).put(key, value, ctx),
+    async putMany(entries, ctx) {
+      // Partition by destination store, batch each side, and reassemble
+      // per-entry outcomes in input order.
+      const indexed = entries.map((entry, index) => ({ entry, index }));
+      const results: Array<{ key: string; error?: unknown }> = entries.map(entry => ({
+        key: entry.key,
+      }));
+      for (const core of [input.files, input.kv]) {
+        const side = indexed.filter(({ entry }) => route(entry.key) === core);
+        if (side.length === 0) {
+          continue;
+        }
+        if (core.putMany === undefined) {
+          // No batch write on this side (the KV proxy): sequential puts,
+          // preserving the strict one-at-a-time ordering it promises.
+          for (const { entry, index } of side) {
+            try {
+              await core.put(entry.key, entry.value, ctx);
+            } catch (error) {
+              results[index] = { key: entry.key, error };
+            }
+          }
+          continue;
+        }
+        const settled = await core.putMany(
+          side.map(({ entry }) => entry),
+          ctx,
+        );
+        for (let i = 0; i < side.length; i += 1) {
+          const target = side[i];
+          const outcome = settled[i];
+          if (target !== undefined && outcome !== undefined) {
+            results[target.index] = outcome;
+          }
+        }
+      }
+      return results;
+    },
+    get: (key, ctx) => route(key).get(key, ctx),
+    delete: (key, ctx) => route(key).delete(key, ctx),
+    list: (prefix, ctx) => route(prefix).list(prefix, ctx),
+    // Session records — the only `listNewest` consumer — are framework file
+    // keys, and the file store has no write-time ordering. Spreading the KV
+    // backend's `listNewest` through would query rows that live elsewhere
+    // (stale KV leftovers, or nothing), so the composed core explicitly has
+    // none and the engine falls back to the routed `list`.
+    listNewest: undefined,
+  };
+}
+
+/**
+ * The KV backend's conditional writes, refusing framework-file keys.
+ *
+ * CAS runs on the KV proxy (a database row version); the plain core routes
+ * framework session state to the file store. A future coordination path
+ * that CASes a `session/` or `continuation/` key would otherwise read and
+ * write a different store than the plain path — silent split-brain. Fail
+ * loudly instead; nothing in the package CASes those kinds today.
+ */
+export function frameworkGuardedCas(
+  cas: NonNullable<StorageConfig["cas"]>,
+): NonNullable<StorageConfig["cas"]> {
+  const refuse = (key: string): void => {
+    if (isFrameworkFileKey(key)) {
+      throw new Error(
+        `framework file storage: conditional writes are KV-only, but "${key}" routes to the framework file store`,
+      );
+    }
+  };
+  return {
+    getWithVersion: (key, ctx) => {
+      refuse(key);
+      return cas.getWithVersion(key, ctx);
+    },
+    putIfAbsent: (key, value, ctx) => {
+      refuse(key);
+      return cas.putIfAbsent(key, value, ctx);
+    },
+    putIfVersion: (key, value, expectedVersion, ctx) => {
+      refuse(key);
+      return cas.putIfVersion(key, value, expectedVersion, ctx);
+    },
+    listKeys: (prefix, ctx) => {
+      refuse(prefix);
+      return cas.listKeys(prefix, ctx);
+    },
+  };
+}

package/src/internal/framework-storage-selection.ts

@@ -0,0 +1,156 @@
+/**
+ * Which backend framework session state is mirrored to.
+ *
+ * Framework state — session records, event chunks, the continuation index —
+ * is how a session outlives the process that served it. On architecture v1
+ * that mirror exists only when the agent author wrote `agent/storage.ts`,
+ * which makes platform durability an agent-level decision: of the
+ * first-party agents, some choose `cursorHostedStorage()` and some choose
+ * `fileKv()` (pod-local disk, lost on pod replacement), and one selects
+ * between them at runtime by reading the deployment-id environment variable
+ * itself.
+ *
+ * That selection is a hosting-mode question, not an authoring question.
+ * Architecture v2 moves it here: `agent/storage.ts` is rejected at
+ * discovery (error diagnostic, so serve and deploy fail early), and the
+ * platform picks the default. Architecture v1 with no authored file now
+ * uses the same hosted-vs-self-hosted split, so deleting `agent/storage.ts`
+ * (required to deploy the same tree onto v2) does not drop the Cursor-hosted
+ * session mirror on a still-v1 pod.
+ *
+ * - **Cursor-managed hosting** (the deployment-generation environment
+ *   variable is set, same signal that registers `GET /v1/manifest`):
+ *   the deployment's **framework-level file store**
+ *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`, bound at task time) holds
+ *   session records, event transcripts, and the continuation index —
+ *   file-shaped state on file storage, apart from the author-facing user
+ *   store. Author `host.kv`, eval runs, and conditional writes ride the
+ *   AgentSDK v2 KV proxy (cursor-hosted-v2.ts), which resolves the
+ *   pod service account to the factorydb deployment row (the v1 Bugbot
+ *   proxy cannot resolve v2 pods at all). Framework session state never
+ *   routes to the KV proxy — the composite splits by key kind — so
+ *   transcripts stay off the author-reachable KV namespace. The API key
+ *   resolves through the full credential chain on every call because hosted
+ *   freeze snapshots listen unsigned and the binder drops the key file
+ *   after restore.
+ * - **Self-hosted**: no mirror. `--state-root` is the durable copy, which
+ *   is correct when the operator owns the disk.
+ *
+ * v1 still honors an authored `agent/storage.ts` when present. Hosted v1
+ * pods with no authored file get the Cursor-hosted lazy mirror (gated on
+ * `AGENT_SERVE_DEPLOYMENT_ID`, the same signal the previous authored sinks
+ * used). Self-hosted v1 with no authored file stays disk-only.
+ *
+ * Local disk is not part of this decision. `<stateRoot>/sessions/<id>/`
+ * already holds `session.json` and `events.ndjson` unconditionally, through
+ * the session store; what this selects is the durable mirror *beyond* the
+ * pod's filesystem.
+ */
+
+import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
+import { defineStorage, type StorageDefinition } from "../storage.js";
+import {
+  AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
+  cursorHostedStorage,
+} from "../storage-backends/cursor-hosted.js";
+import { cursorHostedStorageV2 } from "../storage-backends/cursor-hosted-v2.js";
+import type { AgentArchitecture } from "../types.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
+import {
+  composeFrameworkStorage,
+  fileSinkStorageCore,
+  frameworkGuardedCas,
+} from "./framework-file-storage.js";
+import { resolveAgentV2Hosting } from "./v2-hosting.js";
+
+export interface FrameworkStorageSelectionInput {
+  /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
+  readonly authored: StorageDefinition | undefined;
+  /** {@link AgentConfig.architecture}; discovery fills `"v2"` when omitted. */
+  readonly architecture?: AgentArchitecture | undefined;
+  /** Environment override for tests; defaults to `process.env`. */
+  readonly env?: Record<string, string | undefined>;
+}
+
+/**
+ * Pick the backend for framework session state.
+ *
+ * Returns `undefined` when there is no mirror, in which case the pod's local
+ * disk is the only copy.
+ */
+export function selectFrameworkStorageDefinition(
+  input: FrameworkStorageSelectionInput,
+): StorageDefinition | undefined {
+  if (input.architecture !== "v2") {
+    if (input.authored !== undefined) {
+      return input.authored;
+    }
+    const env = input.env ?? process.env;
+    if ((env[AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR] ?? "").trim() !== "") {
+      // Hosted v1 pod with no authored sink: keep the Cursor-hosted
+      // mirror (lazy restore) so agents can delete `agent/storage.ts`
+      // without losing durability while they still run architecture v1.
+      return defineStorage({
+        name: "cursor-hosted (lazy restore)",
+        policy: { restore: "off" },
+        ...cursorHostedStorage(),
+      });
+    }
+    return undefined;
+  }
+  if (input.authored !== undefined) {
+    // Discovery rejects agent/storage.ts on v2 before an engine is built;
+    // an authored definition reaching this point is a wiring bug. Raise
+    // rather than silently discard what the author believes is configured.
+    throw new Error(
+      'defineStorage (agent/storage.ts) is not supported on architecture "v2": storage is platform-selected. Delete the file.',
+    );
+  }
+  const hosting = resolveAgentV2Hosting({
+    architecture: input.architecture,
+    env: input.env as NodeJS.ProcessEnv | undefined,
+  });
+  if (hosting.kind !== "cursor-managed") {
+    // Self-hosted v2: the state root is the durable copy.
+    return undefined;
+  }
+  // Hosted v2 pods wake per delivery: bulk-restoring up to the default
+  // 1000 sessions on every boot is waste (and against the file-store
+  // backend it is per-key HTTP round trips before the listener even
+  // comes up). Follow-ups restore lazily by continuation or session id;
+  // GET /v1/sessions lists from the sink either way.
+  //
+  // Events flush at turn end. drainSessionDurability still forces the
+  // record onto the sink before the execution reply.
+  const policy = {
+    restore: "off",
+  } as const;
+  // Full chain (env → bind file → stored login): frozen engines listen
+  // unsigned and bind store ids + CURSOR_API_KEY at task time, after this
+  // definition is constructed.
+  const resolveApiKey = (): string | undefined => resolveApiKeySync()?.apiKey;
+  // v2 pods carry a factorydb-bound service account, which the v1 Bugbot
+  // storage proxy cannot resolve; author KV, CAS coordination, and the
+  // eval/A-B tables speak the AgentSDK v2 KV proxy instead. It also carries
+  // the cursor-hosted marker, so GET /v1/sessions prefers the durable list
+  // (session records are on the framework store, which the composed core
+  // lists).
+  const kv = cursorHostedStorageV2({ resolveApiKey });
+  return defineStorage({
+    name: "cursor-hosted (framework files)",
+    policy,
+    ...kv,
+    ...composeFrameworkStorage({
+      kv,
+      files: fileSinkStorageCore(
+        cursorHostedFiles({
+          resolveStoreSourceId: () => hosting.resolveStoreIds().frameworkStoreSourceId,
+          resolveApiKey,
+        }),
+      ),
+    }),
+    // CAS stays on the KV proxy but must refuse framework-file keys, or a
+    // future coordination path would split-brain against the plain core.
+    cas: frameworkGuardedCas(kv.cas),
+  });
+}

package/src/internal/frontmatter.ts

@@ -0,0 +1,108 @@
+/**
+ * Frontmatter parsers. Authored markdown (skill descriptions, schedule cron
+ * expressions) uses the flat `key: value` scalar subset; Cursor plugin
+ * markdown is full YAML (folded descriptions, lists).
+ */
+
+import { JSON_SCHEMA, load as parseYaml } from "js-yaml";
+
+export interface ParsedFrontmatter {
+  data: Record<string, string>;
+  body: string;
+}
+
+export interface ParsedYamlFrontmatter {
+  data: Record<string, unknown>;
+  body: string;
+  /** Why the block did not parse as a YAML mapping; `data` is then empty. */
+  error?: string;
+}
+
+const FRONTMATTER_OPEN = /^---\s*$/;
+const YAML_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/;
+
+/** YAML frontmatter with the JSON schema (no custom tags). */
+export function parseYamlFrontmatter(source: string): ParsedYamlFrontmatter {
+  const match = YAML_FRONTMATTER.exec(source);
+  if (match === null) {
+    return { data: {}, body: source };
+  }
+  const body = match[2] ?? "";
+  let data: unknown;
+  try {
+    data = parseYaml(match[1] ?? "", { schema: JSON_SCHEMA });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { data: {}, body, error: message };
+  }
+  if (data === undefined || data === null) {
+    return { data: {}, body };
+  }
+  if (typeof data !== "object" || Array.isArray(data)) {
+    return { data: {}, body, error: "frontmatter is not a mapping" };
+  }
+  return { data: data as Record<string, unknown>, body };
+}
+
+export function parseFrontmatter(source: string): ParsedFrontmatter {
+  const lines = source.split(/\r?\n/);
+  if (lines.length === 0 || !FRONTMATTER_OPEN.test(lines[0] ?? "")) {
+    return { data: {}, body: source };
+  }
+
+  let closeIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (FRONTMATTER_OPEN.test(lines[i] ?? "")) {
+      closeIndex = i;
+      break;
+    }
+  }
+  if (closeIndex === -1) {
+    return { data: {}, body: source };
+  }
+
+  const data: Record<string, string> = {};
+  for (const line of lines.slice(1, closeIndex)) {
+    if (line.trim() === "" || line.trim().startsWith("#")) {
+      continue;
+    }
+    const separator = line.indexOf(":");
+    if (separator === -1) {
+      continue;
+    }
+    const key = line.slice(0, separator).trim();
+    if (key === "") {
+      continue;
+    }
+    data[key] = unquote(line.slice(separator + 1).trim());
+  }
+
+  const body = lines
+    .slice(closeIndex + 1)
+    .join("\n")
+    .replace(/^\n+/, "");
+  return { data, body };
+}
+
+export function serializeFrontmatter(data: Record<string, string>): string {
+  const lines = Object.entries(data).map(([key, value]) => `${key}: ${quoteIfNeeded(value)}`);
+  return `---\n${lines.join("\n")}\n---\n`;
+}
+
+function unquote(value: string): string {
+  if (
+    value.length >= 2 &&
+    ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'")))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function quoteIfNeeded(value: string): string {
+  if (/[:#'"\n]/.test(value)) {
+    return JSON.stringify(value);
+  }
+  return value;
+}