@deepblend/dsh-blender-preset 0.1.0

package/lib/deploy.js

@@ -0,0 +1,217 @@
+/**
+ * @deepblend/dsh-blender-preset — the deployment rule.
+ *
+ * WHAT THIS FILE IS
+ * -----------------
+ * One answer to "what files is a preset made of, and how does an installed copy
+ * differ from the shipped one". Three callers need that answer and must not be
+ * allowed to disagree:
+ *
+ *   - `lib/index.js`, the plugin row that deploys the presets when the profile
+ *     composes this package (the path a plugin-market user takes);
+ *   - `deepblend/tools/install-presets.mjs`, the repository's operator tool;
+ *   - `deepblend/tools/sync-plugin-presets.mjs`, which keeps the copy this
+ *     package ships identical to `deepblend/presets/` (SPEC §5.2).
+ *
+ * A rule reachable only through one of them is a rule the other two can drift
+ * from silently — which is the failure this repository has paid for repeatedly
+ * (D38, D43, D57, D60: a list copied into a second place rots in the copy).
+ *
+ * WHY THE WHOLE DIRECTORY TRAVELS
+ * -------------------------------
+ * `REQUIRED_FILES` is what a preset cannot be without, not what is copied. The
+ * rest of the directory travels too: a preset's `skills/` directory is loaded
+ * through `customSkillDirs`, resolved against the composition's own base URL, so
+ * copying a fixed file list silently drops the skill the persona tells the model
+ * to load — the preset mounts, every tool arrives, and the skill is simply not
+ * in the catalog.
+ *
+ * THREE STATES, NOT TWO
+ * ---------------------
+ * `absent` (nothing of this preset is installed) is a state, not drift: that is
+ * every fresh machine, and reporting it as drift is what made the operator tool
+ * exit 1 on a machine where nothing was wrong. `partial` is drift, because a
+ * half-present preset is broken rather than absent.
+ *
+ * Owner: DeepBlend Studio — M6 (plugin-market packaging)
+ * Plane: Agent preset
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * The presets this package ships, resolved relative to this module.
+ *
+ * A URL rather than a path computed from `process.cwd()`: the package is
+ * installed into a profile's `node_modules` and the process may be started from
+ * anywhere, so its own location is the only stable anchor.
+ */
+export const PRESET_SOURCE = fileURLToPath(new URL('../presets/', import.meta.url))
+
+/** The writable preset root under the harness home (`@deepseek-ai/dsh-agent-presets`). */
+export const USER_PRESET_DIR = '.agent-presets'
+
+/** Files a preset directory cannot be without. A preset missing one is not deployed at all. */
+export const REQUIRED_FILES = ['preset.yml', 'agent.cordis.yml']
+
+/** Directories inside a preset that are never part of it. */
+export const IGNORED_DIRECTORIES = new Set(['node_modules', '.git'])
+
+/**
+ * The harness home this process would deploy into.
+ *
+ * `DSH_HOME` first because that is what the launcher itself honours, so a plugin
+ * running inside a deployment writes to the same home the deployment reads.
+ *
+ * @returns {string}
+ */
+export function dshHome() {
+  return process.env.DSH_HOME ?? join(homedir(), '.dsh')
+}
+
+/** The default target root: `<DSH_HOME>/.agent-presets`. */
+export function defaultTarget() {
+  return join(dshHome(), USER_PRESET_DIR)
+}
+
+/**
+ * Every file under `directory`, as paths relative to it, in a stable order.
+ *
+ * Sorted because the result is compared between two trees: an unsorted walk
+ * makes a difference report depend on the filesystem's own order.
+ *
+ * @param {string} directory
+ * @returns {string[]}
+ */
+export function filesUnder(directory) {
+  const found = []
+  for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRECTORIES.has(entry.name)) continue
+      for (const nested of filesUnder(join(directory, entry.name))) found.push(join(entry.name, nested))
+    } else if (entry.isFile()) {
+      found.push(entry.name)
+    }
+  }
+  return found
+}
+
+/**
+ * The preset ids a source root holds, in a stable order.
+ *
+ * @param {string} [source]
+ * @returns {string[]}
+ */
+export function presetIds(source = PRESET_SOURCE) {
+  if (!existsSync(source)) return []
+  return readdirSync(source)
+    .filter(name => statSync(join(source, name)).isDirectory())
+    .sort()
+}
+
+/**
+ * What a preset's `preset.yml` and composition directory look like to a deployer.
+ *
+ * @typedef {object} PresetPlan
+ * @property {string} id
+ * @property {string} source
+ * @property {string} target
+ * @property {string[]} files        every file the shipped copy has
+ * @property {string[]} missing      shipped files the target does not have
+ * @property {string[]} drifted      shipped files whose bytes differ
+ * @property {string[]} stale        target files the shipped copy no longer has
+ * @property {boolean} absent        the target holds none of this preset
+ * @property {string|null} problem   why this preset cannot be deployed at all
+ */
+
+/**
+ * Compare one shipped preset against one installed copy, writing nothing.
+ *
+ * @param {object} input
+ * @param {string} input.source - the shipped preset directory.
+ * @param {string} input.target - where the preset would be installed.
+ * @param {string} [input.id] - the preset id, for the report.
+ * @returns {PresetPlan}
+ */
+export function planPreset({ source, target, id = source.split('/').pop() }) {
+  const missingRequired = REQUIRED_FILES.filter(file => !existsSync(join(source, file)))
+  if (missingRequired.length > 0) {
+    // A preset without its composition is not a preset; refusing beats writing half of one.
+    return {
+      id, source, target,
+      files: [], missing: [], drifted: [], stale: [], absent: !existsSync(target),
+      problem: `missing ${missingRequired.join(', ')} in the shipped copy`,
+    }
+  }
+
+  const files = filesUnder(source)
+  const targetFiles = existsSync(target) ? filesUnder(target) : []
+  const missing = []
+  const drifted = []
+  for (const file of files) {
+    const installed = join(target, file)
+    if (!existsSync(installed)) {
+      missing.push(file)
+      continue
+    }
+    if (readFileSync(join(source, file), 'utf8') !== readFileSync(installed, 'utf8')) drifted.push(file)
+  }
+  return {
+    id, source, target, files, missing, drifted,
+    stale: targetFiles.filter(file => !files.includes(file)),
+    // "Nothing of this preset is here" — the state every fresh machine is in, and not drift.
+    absent: targetFiles.length === 0,
+    problem: null,
+  }
+}
+
+/**
+ * Deploy one planned preset: write what differs, remove what the shipped copy no
+ * longer has, and leave everything else alone.
+ *
+ * The target is a user-owned root — a person may have authored presets of their
+ * own beside these — so this only ever touches the files of the preset it was
+ * given, and never the root itself.
+ *
+ * @param {PresetPlan} plan
+ * @returns {{written: string[], removed: string[]}}
+ */
+export function applyPreset(plan) {
+  if (plan.problem !== null) return { written: [], removed: [] }
+  const written = []
+  const removed = []
+  for (const stale of plan.stale) {
+    rmSync(join(plan.target, stale), { force: true })
+    removed.push(stale)
+  }
+  for (const file of [...plan.missing, ...plan.drifted]) {
+    const to = join(plan.target, file)
+    mkdirSync(join(to, '..'), { recursive: true })
+    copyFileSync(join(plan.source, file), to)
+    written.push(file)
+  }
+  return { written, removed }
+}
+
+/**
+ * Deploy every preset a source root holds, and report what each one needed.
+ *
+ * @param {object} [options]
+ * @param {string} [options.source] - the shipped preset root.
+ * @param {string} [options.target] - the installed preset root.
+ * @param {string[]} [options.ids] - restrict to these preset ids.
+ * @returns {Array<{id: string, plan: PresetPlan, written: string[], removed: string[]}>}
+ */
+export function deployPresets({ source = PRESET_SOURCE, target = defaultTarget(), ids } = {}) {
+  const wanted = ids === undefined ? presetIds(source) : ids
+  const reports = []
+  for (const id of wanted) {
+    const plan = planPreset({ source: join(source, id), target: join(target, id), id })
+    const { written, removed } = applyPreset(plan)
+    reports.push({ id, plan, written, removed })
+  }
+  return reports
+}

package/lib/index.js

@@ -0,0 +1,144 @@
+/**
+ * @deepblend/dsh-blender-preset
+ *
+ * The **Agent-preset plane** deliverable (SPEC §4.2, §5.2).
+ *
+ * WHY THIS PACKAGE EXISTS
+ * -----------------------
+ * The tools a session may see belong to an AGENT PRESET, not to the Host
+ * composition (SPEC §4.3): registering them process-wide would hand every
+ * session in the deployment the Blender toolset. That is why they are not in the
+ * bundle's patch.
+ *
+ * But a preset is a directory under `<DSH_HOME>/.agent-presets/`, and
+ * `dsh plugin add` installs a package — it does not write a user's preset root.
+ * So a plugin whose value IS its preset has to deliver one, and the ecosystem's
+ * pattern for that is a deployer row: the bundle mounts this package, and the
+ * package installs the preset it ships. `dsh-expert-orchestrator` is the same
+ * shape, and it is on the plugin list.
+ *
+ * WHAT IT TOUCHES
+ * ---------------
+ * Exactly `<DSH_HOME>/.agent-presets/<id>/` for the preset ids it ships, and
+ * nothing else. The root is a user-owned, writable directory — a person may have
+ * authored presets of their own beside these — so this never removes the root,
+ * never touches another preset, and never deletes a file that the shipped copy
+ * still has.
+ *
+ * The write is IDEMPOTENT and reports rather than insists: a file whose bytes
+ * already match is not rewritten, a stale file left by an earlier release is
+ * removed, and a home that cannot be written is logged and left alone. A plugin
+ * that throws while a profile composes would take the whole deployment down over
+ * a convenience copy, which is the wrong trade in both directions.
+ *
+ * WHY DEPLOYING IS THE DEFAULT
+ * ----------------------------
+ * An installed preset that has to be installed again by hand is the failure this
+ * exists to remove: `dsh plugin add` is the whole install, and the session list
+ * then shows "DeepBlend Studio". `deploy: false` is for a deployment that
+ * manages its preset root itself (a fleet, or a test), and it is honoured
+ * without a warning because it is a decision rather than a mistake.
+ *
+ * Owner: DeepBlend Studio — M6 (plugin-market packaging)
+ * Plane: Agent preset
+ */
+
+import z from '@deepseek-ai/schemastery'
+
+import { PRESET_SOURCE, defaultTarget, deployPresets, presetIds } from './deploy.js'
+
+/** Plugin name, surfaced in loader diagnostics. */
+export const name = 'deepblend-blender-preset'
+
+/**
+ * No service is consumed and none is published.
+ *
+ * The deployment reads its own package and writes a directory, so there is
+ * nothing to wait for — and publishing a service from a row would make the
+ * preset that mounts it collide on a second session (SPEC §4.4). This row lives
+ * in the HOST composition precisely because it must happen once per process.
+ */
+export const inject = []
+
+/** The shipped preset ids, for a composition that wants to name them. */
+export const SHIPPED_PRESETS = Object.freeze(presetIds())
+
+export const Config = z.object({
+  /** Deploy the shipped presets when this row composes. */
+  deploy: z.boolean().default(true),
+  /**
+   * Which preset ids to deploy. Empty means every preset this package ships,
+   * which is the right default: a preset added to the package should arrive
+   * without a composition change.
+   */
+  presets: z.array(z.string()).default([]),
+  /** The preset root to deploy into; empty means `<DSH_HOME>/.agent-presets`. */
+  target: z.string().default(''),
+})
+
+/** The scope every line this row logs carries. */
+export const LOG_SCOPE = 'deepblend-preset'
+
+/**
+ * Deploy the shipped presets, and report what it took.
+ *
+ * Exported so the contract layer can drive it without composing a profile — the
+ * same reason `host/lib/frame-ledger.js` exports its measurement.
+ *
+ * @param {object} config - the validated row configuration.
+ * @param {{info?: Function, warn?: Function}} [logger]
+ * @returns {{deployed: Array<{id: string, written: number, removed: number}>, skipped: string[], failed: string[]}}
+ */
+export function deployShippedPresets(config, logger) {
+  const target = config.target === '' ? defaultTarget() : config.target
+  const ids = config.presets.length === 0 ? presetIds(PRESET_SOURCE) : config.presets
+  const reports = []
+  const skipped = []
+  const failed = []
+
+  for (const id of ids) {
+    try {
+      const [report] = deployPresets({ source: PRESET_SOURCE, target, ids: [id] })
+      if (report === undefined) {
+        skipped.push(id)
+        continue
+      }
+      if (report.plan.problem !== null) {
+        // Refusing beats writing half a preset: a directory without its
+        // composition still occupies the id in the roster.
+        failed.push(`${id}: ${report.plan.problem}`)
+        logger?.warn?.(`${LOG_SCOPE}: ${id} was not deployed — ${report.plan.problem}`)
+        continue
+      }
+      reports.push({ id, written: report.written.length, removed: report.removed.length })
+    } catch (cause) {
+      // A read-only or missing home is the operator's business, not a reason to
+      // fail the composition. The session list simply will not show the preset,
+      // and this line says why.
+      failed.push(`${id}: ${cause instanceof Error ? cause.message : String(cause)}`)
+      logger?.warn?.(`${LOG_SCOPE}: could not deploy ${id} into ${target}: ${String(cause)}`)
+    }
+  }
+  return { deployed: reports, skipped, failed }
+}
+
+/**
+ * The row's apply: deploy once per composition, then stay out of the way.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {z.infer<typeof Config>} config
+ */
+export function apply(ctx, config) {
+  if (!config.deploy) {
+    ctx.logger?.info?.(`${LOG_SCOPE}: deployment is switched off for this row; the preset root is left as it is`)
+    return
+  }
+  const { deployed, failed } = deployShippedPresets(config, ctx.logger)
+  if (deployed.length === 0 && failed.length === 0) return
+  const summary = deployed
+    .map(entry => `${entry.id} (${entry.written} written, ${entry.removed} removed)`)
+    .join(', ')
+  if (deployed.length > 0) {
+    ctx.logger?.info?.(`${LOG_SCOPE}: deployed into ${config.target === '' ? defaultTarget() : config.target} — ${summary}`)
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@deepblend/dsh-blender-preset",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "DeepBlend Agent-preset plane: ships the DeepBlend Studio agent presets and the deployer row that installs them into the DSH home.",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./deploy": {
+      "default": "./lib/deploy.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "presets"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pearjelly/deep-blend.git"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0 <5",
+    "@deepseek-ai/schemastery": ">=3.18.0 <4"
+  },
+  "dependencies": {}
+}

package/presets/deepblend/agent.cordis.yml

@@ -0,0 +1,218 @@
+# The `deepblend` agent preset: DeepBlend Studio's PRODUCT mode.
+#
+# `deepblend-dev` is the mode this repository is developed in: a full coding agent
+# with a shell, a filesystem and the ability to run the test suite. This file is
+# what a USER runs, and its whole design is what it does NOT contain.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# SPEC §6.4 is the specification for this row set, and it is a CLOSED list:
+#
+#   keep    Persona · Agent Instructions · Plan · Ask User · Jobs Control ·
+#           DeepBlend Tool · DeepBlend Skill · Compaction · Present ·
+#           optionally read-only file tools
+#   remove  any shell · any file write · any web download · any code execution ·
+#           the creator's `tool-cordis` · any Python execution tool
+#
+# Every row below is on that list, and every absence is a decision. The
+# acceptance criteria M5 is checked against (`SPEC §20`) are all about absence:
+# no shell, no arbitrary Python, no creator tool, all high-risk operations
+# controlled. So the interesting content of this file is the comment explaining
+# each row that is NOT here.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# WHY `tool-fs` IS ABSENT, AND `tool-fs-search` IS NOT
+#
+# SPEC calls for "optionally read-only file tools". `@deepseek-ai/dsh-tool-fs`
+# registers FOUR tools in one row — `read`, `write`, `edit` and `read_image` —
+# and its config surface is read limits only. There is no read-only subset to
+# configure, so mounting it would hand this preset arbitrary file WRITE, which is
+# the first thing SPEC §6.4 removes. Measured, not assumed:
+#
+#     $ grep -ohE 'name: "[a-z_]+"' …/dsh-tool-fs/lib/index.js | sort -u
+#     name: "edit"   name: "read"   name: "read_image"   name: "write"
+#
+# `@deepseek-ai/dsh-tool-fs-search` registers exactly `glob` and `grep` — listing
+# paths and searching contents, both read-only — so THAT is the read-only file
+# capability, and the model reaches every artifact it needs through the blender_*
+# tools in any case: previews and contact sheets come back inside tool results as
+# images (M2's whole design), not through a file reader.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# WHAT IS DELIBERATELY MISSING, AND WHY
+#
+#   tool-bash / tool-pwsh          arbitrary shell            (SPEC §6.4, §11.1)
+#   tool-fs                        arbitrary file write        (see above)
+#   tool-web                       arbitrary web download      (SPEC §6.4)
+#   tool-cordis                    creator mode, mounts model-written JS
+#   tool-todo / tool-goal /
+#   command-goal                   not on the list. A goal is a
+#                                  long-running-objective feature; SPEC's closed
+#                                  set does not include it, and the least-surprise
+#                                  reading of "keep only these" is to keep only
+#                                  these. `command-compact` stays because it is
+#                                  part of the Compaction group SPEC requires.
+#   delegation / workflow / ralph  subagents and workflows are not on the list
+#                                  either, and every one of them would be a way
+#                                  to reach a capability this preset just removed
+#                                  (a subagent runs a preset too).
+#
+# The last line is the one worth keeping in mind: this file is a permissions
+# boundary, and a delegation row is a hole in it unless the delegated preset is
+# equally narrow.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# THE SKILL TRAVELS INSIDE THIS DIRECTORY
+#
+# `skills/deepblend-studio/SKILL.md` is loaded by the `skill-filesystem` row
+# below, which points at `skills/` resolved against `baseUrl` — the preset
+# composition's own directory, per `@deepseek-ai/dsh-agent-presets`. That is the
+# shipped convention (the deployment's `cordis` preset does exactly this for its
+# two skills) and it means deploying this preset deploys its documentation: no
+# second location to keep in step.
+#
+# `install-presets.mjs` copies the whole directory rather than a fixed file list
+# for that reason.
+
+# ── identity ────────────────────────────────────────────────────────────────
+
+# The product persona. `{{model}}` and `{{cwd}}` resolve from the agent's own
+# route and workspace.
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    prefix: >-
+      You are DeepBlend Studio, a 3D animation agent powered by the {{model}} model.
+      You plan, inspect and control Blender through the blender_* tools: a scene is
+      a SceneSpec document, every accepted change is an immutable revision, and you
+      look at a scene with previews before you commit hours to a final render.
+      Load the deepblend-studio skill before starting real work.
+    suffix: Your working directory is {{cwd}}.
+
+- id: agent-instructions
+  name: '@deepseek-ai/dsh-agent-instructions'
+  config:
+    maxBytes: 65536
+
+# ── plan mode (SPEC §6.4 "Plan") ─────────────────────────────────────────────
+#
+# Plan state is per-agent by nature, so the entry-local realm is the correct
+# lifetime rather than a workaround: without it a row would publish into the root
+# realm and `dsh-agent-presets` would reject the mount.
+- id: planning
+  name: cordis:group
+  group: true
+  isolate:
+    planMode: true
+  config:
+    - id: plan-mode
+      name: '@deepseek-ai/dsh-plan-mode'
+      config:
+        section: |
+              You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+              Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+              The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+              Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+              Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+              When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+
+# ── the questions a person must answer (SPEC §6.4 "Ask User") ────────────────
+
+- id: tool-ask-user
+  name: '@deepseek-ai/dsh-tool-ask-user'
+
+# ── background work (SPEC §6.4 "Jobs Control") ───────────────────────────────
+#
+# Only the model-facing controls. The task REGISTRY stays in the host composition,
+# where `tool-bash` and the render reconciler resolve it — an entry-local realm
+# here would be invisible to them, and the tools would answer "background jobs
+# unavailable" while sitting in the catalog. A long final render is exactly the
+# work this preset must be able to collect and stop.
+- id: tool-jobs
+  name: '@deepseek-ai/dsh-tool-jobs'
+
+# ── the DeepBlend skill (SPEC §6.4 "DeepBlend Skill") ────────────────────────
+
+# The skill REGISTRY is a host service layered per scope; these rows register
+# into THIS preset's layer, so they need no realm. `customSkillDirs` is the one
+# `!!js` expression in this file, and it works here — unlike in the bundle patch,
+# which is composed by a loader whose context has no `process` (M0 §4.2, and the
+# header of `bundle/cordis.patch.yml`). A preset composition IS read by `Include`,
+# which rewrites `baseUrl` to the composition's own directory; the deployment's
+# shipped `cordis` preset uses the same expression for its own two skills.
+- id: skill-filesystem
+  name: '@deepseek-ai/dsh-skill-filesystem'
+  config:
+    customSkillDirs:
+      - !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('skills/', baseUrl))"
+
+- id: tool-skill
+  name: '@deepseek-ai/dsh-tool-skill'
+
+# ── read-only file access (SPEC §6.4 "可选只读文件工具") ──────────────────────
+#
+# `glob` and `grep` only — see the header for why `tool-fs` cannot be narrowed
+# and is therefore absent altogether.
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+  config:
+    sampleOverCapGlobResults: false
+
+# ── compaction (SPEC §6.4 "Compaction") ──────────────────────────────────────
+#
+# `compaction-basic` reads `toolResultPruner` through `ctx.get`, so the pruner
+# must share this realm rather than sit outside it. `tokenMeter` is deliberately
+# NOT here: the meter stays on the host plane and owns the context-meter units the
+# browser reads for every session, so it must not come and go with a preset.
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    compaction: true
+    toolResultPruner: true
+  config:
+    - id: compaction-basic
+      name: '@deepseek-ai/dsh-compaction-basic'
+
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+
+    - id: tool-result-pruner
+      name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+      config:
+        thresholdChars: 8192
+        headChars: 4096
+        tailChars: 1024
+
+# ── deliverables (SPEC §6.4 "Present/Deliverable") ───────────────────────────
+#
+# How a user receives an artifact the agent produced. It needs `fs` and
+# `sessionProjections` from the host; it registers into `tools` and provides
+# nothing, so it needs no realm.
+- id: present
+  name: '@deepseek-ai/dsh-tool-present'
+
+# ── DeepBlend Studio ────────────────────────────────────────────────────────
+
+# The model-visible DeepBlend tools. This row CONSUMES the `blenderStudio`
+# service published by the `@deepblend/dsh-blender-bundle` HOST composition — it
+# publishes nothing, so it needs no realm and is safe to mount per session
+# (SPEC §4.3/§4.4).
+#
+# WHAT THE CATALOG IS IS NOT WRITTEN HERE. The tool names, the count and the
+# per-milestone groupings live in `packages/deepblend/tool/lib/`, and
+# `composition/tool-plane-m3.e2e.mjs` owns the current total. This block used to
+# be the kind of comment that goes on stating a count after the next milestone
+# changed it — the copy nobody runs is the one that rots (D38, D43, D60) — so it
+# points at the package instead.
+#
+# `blender_asset_ingest` is still absent: its host service and approval boundary
+# are M5 work (SPEC §11). So is `blender_revision_restore`, which SPEC §11 lists
+# and two of this repository's own documents tell a user to call — see
+# `milestone-status.md` §16 for the measured gap.
+- id: deepblend-tool
+  name: '@deepblend/dsh-blender-tool'

package/presets/deepblend/preset.yml

@@ -0,0 +1,9 @@
+# WHY THERE IS NO `order` KEY, when every preset the deployment ships declares one.
+#
+# The roster sorts by `order` and treats an absent one as `Number.POSITIVE_INFINITY`
+# (`@deepseek-ai/dsh-agent-presets`, "ordered by id" is the tie-break), so this preset appears after the four
+# built-ins and among any other unordered ones by id. That is the intended position for a plugin's preset, and it
+# is the more robust spelling: a declared number would tie with a future built-in that picks the same one, while
+# an absent one always follows the deployment's own. Measured by reading the sort, not assumed.
+name: DeepBlend Studio
+description: 用 DeepSeek-Flash 规划、检查并控制 Blender 产出 3D 动画的专用 Agent：只会看场景、改场景、渲预览、判读测量并交付视频，没有 Shell、没有任意文件写入、没有任意 Python。

package/presets/deepblend/skills/deepblend-studio/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: deepblend-studio
+description: Use when planning or producing a 3D animation with DeepBlend Studio — setting up a shot or product scene, bringing the user's own 3D model into a project, changing a Blender scene through SceneSpec patches, rendering and judging a preview, repairing a scene that measures badly, running, checking, cancelling or resuming a long final render, or delivering a finished video. Also use when a previous session's revision has to be restored.
+---
+
+# DeepBlend Studio
+
+You drive a Blender workbench. The scene is not a `.blend` file you edit — it is a
+**SceneSpec** document, and every accepted change compiles that document into a new,
+immutable **revision**. Everything you do is one of: read a revision, propose a patch
+that becomes a revision, render a revision, or judge what a render measured.
+
+## The cost asymmetry decides everything
+
+Two kinds of render exist and they differ by three orders of magnitude:
+
+| | `blender_preview_render` / `blender_preview_views` | `blender_final_render` |
+|---|---|---|
+| What it is for | looking at the scene | producing the deliverable |
+| Resolution / engine | 640×360, fast engine, few samples | whatever the `final` profile says (typically 1920×1080, Cycles, hundreds of samples) |
+| Measured cost | seconds for the whole image | **19.6–41.4 s for ONE frame** on the machine this was built on |
+| A typical job | — | 450 frames ≈ **3.4 hours** |
+
+So: **look with previews, and never start a final render to find out what something
+looks like.** A final render is the last step of a decision you have already made,
+not a way to make one. If you catch yourself wanting "just one frame to check", that
+is a preview.
+
+A final render is also the one operation that may need approval (SPEC §15.1), and it
+is the one that can outlive the process. Treat starting it as a commitment — and know
+the way out: **`blender_job_cancel`** stops it and *measures* that the renderer is gone
+rather than assuming the signal landed. Cancelling keeps every frame already written, so
+a cancelled render is resumable with `blender_final_render {resumeJobId}`, and a partially
+written frame is re-rendered rather than kept. Cancel a render you no longer want; never
+start a second one beside it, because a project can only have one delivery render at a
+time (`RENDER_JOB_CONFLICT`).
+
+## The order that works
+
+1. **`blender_capabilities`** — what this Blender can actually do: engines, formats,
+   GPU. Call it once per session before promising anything. It reports absence as
+   data (`installed: false` plus a warning), never as a crash.
+2. **`blender_project_create`** — a project owns a SceneSpec, a revision history and
+   the render output. The first revision is `r0001`.
+3. **`blender_asset_ingest`** — only if the user brought a model file. It is a two-step
+   contract and the second step is easy to forget; see "Bringing in a model" below.
+4. **`blender_scene_get`** — read before writing. Patching without reading is how a
+   stale `baseRevision` produces a refusal you then have to diagnose.
+5. **`blender_scene_patch`** — the ONLY way to change a scene. There is no free-form
+   edit and no script. See "Revision discipline" below.
+6. **`blender_preview_render` / `blender_preview_views`** — look at it. `preview_views`
+   renders several declared views in one Blender launch and returns a contact sheet.
+7. **`blender_visual_review`** — ask for a measured judgement (see "Who decides what").
+8. **`blender_visual_autofix`** — hand the loop a goal and let it iterate, when the
+   problem is one the measurements can see.
+9. **`blender_final_render`** — only once the preview is right. It returns as soon as
+   the job is durable, not when it finishes.
+10. **`blender_job_status`** — poll it, or come back to it in a later turn. A render
+    that outlives the process is still there: the store is on disk.
+11. **`blender_export`** — publish the delivery package when you want it verified and
+    described rather than merely finished.
+
+`blender_scene_validate` fits anywhere: it checks a scene, or a patch you have not
+committed yet (`dryRun`), without touching the project. Use it when a patch is refused
+and the reason is not obvious.
+
+## Bringing in a model the user already has
+
+`blender_asset_ingest` copies a file into the project; it **does not touch the scene**.
+Two steps follow it, and a scene that skips the second one has an asset nobody uses:
+
+1. `blender_asset_ingest {projectId, sourcePath}` — a local file, no approval. Pass
+   `sourceUrl` instead and the call **pauses to ask the operator**, because it leaves
+   the machine. Use `sourcePath` whenever the file is already there.
+2. `blender_scene_patch {op: "asset.add", asset: {id, type, path, sha256}}` — declare it,
+   using the `assetId`, project-relative `path` and `sha256` the ingest returned. This is
+   what commits it: one accepted patch, one new revision, like every other change.
+3. `blender_scene_patch {op: "entity.add", …}` with `type: "asset-instance"` and that
+   `assetId` — now something in the scene uses it.
+
+`blender_scene_validate` is the check that the format is one this Blender build can
+import. Setting `license` on anything you downloaded is worth the argument: an asset
+whose provenance is unrecorded is one nobody can safely ship.
+
+## Revision discipline
+
+- **One successful patch = one immutable revision.** Nothing rewrites history.
+- **A failed patch changes nothing.** The current revision's directory is never opened
+  for writing, so a refusal costs you a message, not your work.
+- **Retrying is safe.** An omitted idempotency key is derived from the patch itself, so
+  an accidental resend returns the first result instead of making a second revision.
+  Pass an explicit key only when you deliberately want the same operations twice.
+- **Going back is `blender_revision_restore`**, which moves the pointer forward to a
+  copy — it does not delete anything. Use it when a change measured worse.
+- **Long renders resume; they do not restart.** `blender_final_render` with a
+  `resumeJobId` renders only the frames that are missing or corrupt. The frames on disk
+  are the authority, not the job record, so a render killed mid-frame resumes correctly.
+  Never start a fresh render of a job that already has frames.
+- **A render you no longer want is cancelled, not abandoned.** `blender_job_cancel` takes
+  the job id, stops the renderer and reports whether the process is actually gone.
+
+## Who decides what
+
+This is the part most likely to be got wrong, and the workbench is built to make it
+hard to get wrong:
+
+- **The score and the issues are measured, not reported.** The host computes them
+  deterministically from the rendered pixels — composition, exposure, occlusion. The
+  same scene scores the same twice, and a contract test asserts that.
+- **You are the only one who can see meaning.** The measurements cannot tell a watch
+  dial that is *supposed* to be bright from one that is blown out, or a screen that is
+  *supposed* to be hidden from one that is occluded by mistake. When a scene measures
+  well and still looks wrong, that judgement is yours to state, with the view and the
+  object named.
+- **`blender_visual_review` returns three things separately**: the measured score,
+  the measured issues, and what the vision model *reported*. A reported finding is kept
+  only if the view exists, the category is in the closed set, and the evidence is not
+  empty. Never present a reported finding as a measurement.
+- **Autofix only adopts a fix that measurably improved the score.** A round that did not
+  improve is rolled back — the revision stays in history, but the project does not move
+  to a worse version. If the loop stops short of the goal it hands back the open issues
+  with their measurements and the revisions it tried; that handover is the state to
+  continue from, not a failure to re-run.
+
+## Reading the evidence you get back
+
+- Preview results carry the **contact sheet** as an image. That image is what the vision
+  model sees, so you and it are looking at the same thing.
+- An issue names **the number that triggered it** and the view it was measured in. Quote
+  those when you explain a problem; "it looks off" is not something a user can act on.
+- A revision manifest records what was done, by whom, and which previews it produced.
+  `blender_project_get` summarises the history — read it before proposing a change that
+  depends on what already happened.
+
+## Practical rules
+
+- Prefer **one patch that changes one thing**. A patch that moves the camera, the lights
+  and a material at once cannot be scored back to a cause.
+- Give every revision a **note**: the model reading the history later is usually you.
+- Do not promise a resolution, a duration or a frame count before `blender_capabilities`
+  and the project's own render profile have told you what is possible.
+- The workbench UI shows the same authoritative state you are reading. If a user says the
+  panel disagrees with you, the panel is reading the host and the host is reading disk —
+  find the difference rather than assuming either side.

package/presets/deepblend-dev/agent.cordis.yml

@@ -0,0 +1,285 @@
+# The `deepblend-dev` agent preset: DeepBlend Studio's development mode.
+#
+# It was copied from the deployment's `standard` preset (SPEC §6.2: a custom preset
+# starts as a copy of an existing one) and differs from it in exactly one row —
+# `deepblend-tool`, at the end of this file. The header used to still say it WAS the
+# `standard` preset, which is the kind of inherited sentence nothing ever re-reads;
+# it is corrected here because this file is now the repository's source of truth and
+# `deepblend/tools/install-presets.mjs` deploys it.
+#
+# This file is an AGENT-PLANE composition. The roster mounts it ONCE under a
+# standing scope; every session naming it joins by scope parentage, so the
+# tools and prompt sections registered here cover each joined agent while a
+# session's own state stays keyed per Session/Agent inside the plugins. The
+# host composition (`base.cordis.yml` + `web.cordis.yml`) keeps everything a
+# preset must not own: the registries themselves, the sandbox and approval
+# stack, persistence, and the model route.
+#
+# A service row here MUST sit inside a group carrying an `isolate` realm.
+# Without one it publishes into the root realm, where it is process-global —
+# another preset publishing the same name collides, and a host reader would
+# resolve one preset's instance for every session; `dsh-agent-presets` rejects
+# that at mount. `true` means an entry-local realm: this standing mount's own
+# private instance, apart from every other preset's. (A shared label does NOT
+# pool instances — `provide()` throws on the second registration under the
+# same realm symbol; labels join REALMS, and are not what this file needs.)
+
+# ── identity ────────────────────────────────────────────────────────────────
+
+# The preset's own persona, shadowing the deployment default for this agent.
+# `{{model}}` and `{{cwd}}` resolve from the agent's own route and workspace.
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    suffix: Your working directory is {{cwd}}.
+    prefix: >-
+      You are a coding agent powered by the {{model}} model.
+
+- id: agent-instructions
+  name: '@deepseek-ai/dsh-agent-instructions'
+  config:
+    maxBytes: 65536
+
+# ── shell ───────────────────────────────────────────────────────────────────
+
+# `shell-env` stays in the HOST composition: `apps/cli/src/web.ts` injects it to
+# publish `DSH_WEB_URL`/`DSH_WEB_MODE`, and a host row that injects a service is
+# the criterion for host-plane ownership — injection resolves before any session
+# exists, so there is no agent to key by. Behind a preset realm those variables
+# never reached the model's shell at all. Both shell tools consume the host
+# registry from here; their executors (`bash-sandbox`/`pwsh-sandbox`) are
+# host-plane too.
+- id: tool-bash
+  name: '@deepseek-ai/dsh-tool-bash'
+  disabled: !!js process.platform === 'win32'
+
+- id: tool-pwsh
+  name: '@deepseek-ai/dsh-tool-pwsh'
+  disabled: !!js process.platform !== 'win32'
+
+# ── filesystem ──────────────────────────────────────────────────────────────
+
+# Both register into the host `tools` registry and provide nothing, so
+# they need no realm. The `fs` service and its policy stay in the host.
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'
+
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+  config:
+    sampleOverCapGlobResults: false
+
+# ── background jobs ────────────────────────────────────────────────────────
+
+# Only the model-facing controls. The task REGISTRY stays on the host plane:
+# its producers sit outside any realm this file could put it in — `tool-bash`
+# above resolves it with `ctx.get`, and an entry-local realm here is invisible
+# to every sibling row, so `run_in_background` would answer "background jobs
+# unavailable" while these controls sat in the catalog. The registry is keyed by
+# owning agent anyway, so one host instance serves every session. What a preset
+# chooses is whether its agent can collect and stop background work at all.
+- id: tool-jobs
+  name: '@deepseek-ai/dsh-tool-jobs'
+
+# ── skills ──────────────────────────────────────────────────────────────────
+
+# The skill REGISTRY lives in the host composition and is layered per scope:
+# these rows register into THIS preset's layer of it, so they need no realm.
+# `skill-filesystem` contributes local-root discovery for agents on this preset, and
+# `tool-skill` gives them the catalog and loader; the merged catalog also
+# carries whatever the deployment registered globally (repository plugins).
+- id: skill-filesystem
+  name: '@deepseek-ai/dsh-skill-filesystem'
+
+- id: tool-skill
+  name: '@deepseek-ai/dsh-tool-skill'
+
+# ── goals ───────────────────────────────────────────────────────────────────
+
+# The goal service and session driver stay on the host plane, where the Gateway
+# can resolve them. The human command and model-facing tool register into this
+# preset's scoped layers.
+- id: command-goal
+  name: '@deepseek-ai/dsh-command-goal'
+
+- id: tool-goal
+  name: '@deepseek-ai/dsh-tool-goal'
+
+# ── plan mode ───────────────────────────────────────────────────────────────
+
+# Plan state is per-agent by nature, so an entry-local realm is not a
+# workaround here — it is the correct lifetime.
+- id: planning
+  name: cordis:group
+  group: true
+  isolate:
+    planMode: true
+  config:
+    - id: plan-mode
+      name: '@deepseek-ai/dsh-plan-mode'
+      config:
+        section: |
+              You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+              Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+              The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+              Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+              Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+              When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+
+# ── compaction ──────────────────────────────────────────────────────────────
+
+# `compaction-basic` reads `toolResultPrune` through `ctx.get`, so the pruner must
+# share this realm rather than sit outside it.
+#
+# `tokenMeter` is deliberately NOT in this realm: the meter stays on the HOST
+# plane, and the rows here resolve that one instance. It takes no configuration,
+# keys every fold by Session, and owns the context-meter projection units the
+# browser reads for every session — behind a realm those units would come and go
+# with whichever presets happen to be mounted. What a preset chooses is whether
+# its agent compacts at all, which is `compaction-basic` below.
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    compaction: true
+    toolResultPruner: true
+  config:
+    - id: compaction-basic
+      name: '@deepseek-ai/dsh-compaction-basic'
+
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+
+    - id: tool-result-pruner
+      name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+      config:
+        thresholdChars: 8192
+        headChars: 4096
+        tailChars: 1024
+
+# ── delegation and workflows ────────────────────────────────────────────────
+
+# The `subagents` registry and its spawn/fork backends live in the HOST
+# composition: the registry is a process singleton whose cross-session queries
+# the api-proxy serves to the browser, and a provider name may only be
+# registered once. This preset contributes the delegation TOOLS, which resolve
+# that host registry.
+#
+# `workflows` is different — nothing outside an agent reads it — so every row
+# that reaches it shares one entry-local realm here, and a consumer left
+# outside would resolve a host registry this preset does not populate.
+- id: delegation
+  name: cordis:group
+  group: true
+  isolate:
+    workflowEngine: true
+  config:
+    - id: tool-subagent-control
+      name: '@deepseek-ai/dsh-tool-subagent-control'
+
+    - id: tool-subagent-list-agents
+      name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+
+    - id: tool-subagent
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: spawn
+        toolName: subagent
+        modelSelectionSettings: true
+        backgroundMode: continuable
+
+    # Fork omits model selection so provider/model stay equal to the parent and
+    # the inherited history remains eligible for KV Cache reuse. This preset
+    # keeps fork continuable; parent and child inherit the same messaging tool,
+    # while the parent id and return guidance follow the inherited history.
+    - id: tool-subagent-fork
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: fork
+        toolName: subagent_fork
+        backgroundMode: continuable
+
+    # Production dsh does not install these optional providers. Install the
+    # matching Bundle in this Profile and restart the Host, then copy this
+    # preset and remove `disabled` from the matching tool row. Host availability
+    # alone grants no tool.
+    - id: tool-subagent-codex
+      name: '@deepseek-ai/dsh-tool-subagent'
+      disabled: true
+      config:
+        provider: codex
+        toolName: subagent_codex
+        backgroundMode: one-shot
+        maxDepth: provider-managed
+
+    - id: tool-subagent-claude-code
+      name: '@deepseek-ai/dsh-tool-subagent'
+      disabled: true
+      config:
+        provider: claude-code
+        toolName: subagent_claude_code
+        backgroundMode: one-shot
+        maxDepth: provider-managed
+
+    - id: workflow-worker-thread
+      name: '@deepseek-ai/dsh-workflow-worker-thread'
+      config:
+        provider: spawn
+
+    - id: tool-workflow
+      name: '@deepseek-ai/dsh-tool-workflow'
+
+    - id: tool-ralph
+      name: '@deepseek-ai/dsh-tool-ralph'
+      config:
+        subagentProvider: spawn
+        maxRounds: 64
+
+# ── remaining model-facing rows ─────────────────────────────────────────────
+
+- id: tool-ask-user
+  name: '@deepseek-ai/dsh-tool-ask-user'
+
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
+
+# The `web` service and its search provider stay in the host composition; only
+# the model-facing tool is per-session.
+- id: tool-web
+  name: '@deepseek-ai/dsh-tool-web'
+  config:
+    fetch: true
+    searchTimeoutMs: 60000
+
+- id: present
+  name: '@deepseek-ai/dsh-tool-present'
+
+# ── DeepBlend Studio ────────────────────────────────────────────────────────
+
+# The model-visible DeepBlend tools. This row CONSUMES the `blenderStudio`
+# service published by the `@deepblend/dsh-blender-bundle` Host composition —
+# it publishes nothing, so it needs no `isolate` realm and is safe to mount
+# per session (SPEC §4.3/§4.4).
+#
+# WHAT THE CATALOG IS IS NOT WRITTEN HERE. The tool names, the count and the
+# per-milestone groupings live in `packages/deepblend/tool/lib/`, and each
+# milestone's suite asserts that its own batch is complete and usable
+# (`composition/tool-plane-m3.e2e.mjs` owns the current total).
+#
+# This block used to enumerate the tools and state a count, and it went on stating
+# it after the next milestone registered the ones it described as not yet arrived.
+# The copy nobody runs is always the one that rots (architecture-decisions D38,
+# D43, D60), so it is pointed at rather than restated. What DOES belong here is
+# the rule that outlives every milestone: a tool the model can see is a promise
+# the runtime must keep. As of M5 that list is COMPLETE — every tool SPEC §11 names is
+# registered — so the rule no longer has an example of something held back, which is
+# the state it was written to reach.
+- id: deepblend-tool
+  name: '@deepblend/dsh-blender-tool'

package/presets/deepblend-dev/preset.yml

@@ -0,0 +1,2 @@
+name: DeepBlend 开发模式
+description: 开发与调试 DeepBlend Studio 的完整编码 Agent：在标准模式全部能力之上提供 Blender 能力检测工具，用于开发 Blender Runtime、检查项目文件、执行测试与查看日志产物。