@matamt-dbg/dsh-studio 0.4.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matamt-dbg/dsh-studio",
-  "version": "0.4.0",
+  "version": "0.6.1",
   "description": "DSH Studio: build, edit and apply DeepSeek Harness agent presets — tools, prompts, Configs and role-based subagents — from the web GUI.",
   "keywords": [
     "deepseek-harness",
@@ -24,7 +24,8 @@
     "./policy": "./policy.js",
     "./roles": "./roles.js",
     "./batch": "./batch.js",
-    "./judge": "./judge.js"
+    "./judge": "./judge.js",
+    "./loop": "./loop.js"
   },
   "files": [
     "index.js",
@@ -33,6 +34,7 @@
     "roles.js",
     "batch.js",
     "judge.js",
+    "loop.js",
     "skills",
     "cordis.patch.yml"
   ],
@@ -40,14 +42,14 @@
     "js-yaml": "^4.3.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-app-boot": "0.2.0-rc.2 || 0.2.1-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2 || 0.2.1-alpha.2",
-    "@deepseek-ai/dsh": "0.2.0-rc.2 || 0.2.1-alpha.2",
-    "@deepseek-ai/dsh-scope": "0.2.0-rc.2 || 0.2.1-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2 || 0.2.1-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.2.0-rc.2 || 0.2.1-alpha.2",
-    "@deepseek-ai/dsh-jobs": "0.2.0-rc.2 || 0.2.1-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.2.0-rc.2 || 0.2.1-alpha.2",
+    "@deepseek-ai/dsh-app-boot": "0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-rc.1 || 0.2.1-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-rc.1 || 0.2.1-rc.2",
+    "@deepseek-ai/dsh": "0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-rc.1 || 0.2.1-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-rc.1 || 0.2.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-rc.1 || 0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-rc.1 || 0.2.1-rc.2",
+    "@deepseek-ai/dsh-jobs": "0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-rc.1 || 0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-rc.1 || 0.2.1-rc.2",
     "@deepseek-ai/cordis-plugin-include": "*"
   },
   "peerDependenciesMeta": {

package/policy.js

@@ -66,6 +66,17 @@ function sectionsOnlyFor(hidden, kept) {
   return [...owned(hidden)].filter((section) => !still.has(section));
 }
 
+// src/host/role-child-policy-contract.ts
+function isStudioChild(id) {
+  return typeof id === "string" && id.startsWith("studio-child-");
+}
+function roleChildPolicy(ctx, agent) {
+  if (!isStudioChild(agent.id)) return void 0;
+  const owner = ctx.get("studioChildPolicies");
+  if (!owner) throw new Error("Studio child policy owner is unavailable");
+  return owner.forAgent(agent);
+}
+
 // src/host/preset-policy.ts
 var POLICY_SECTION_ORDERS = Object.freeze({
   "tool:jobs": "TOOL_JOBS",
@@ -198,6 +209,8 @@ function apply(ctx, config) {
   const registry = ctx.get("agents");
   const hideable = config.childToolFilter?.deny ?? [];
   const policyFor = (agent) => {
+    const fixed = roleChildPolicy(ctx, agent);
+    if (fixed) return childPolicy(config, fixed.deny);
     if (!hideable.length) return config;
     const provided = (name2) => scopeOf(ctx) === void 0 || ctx.tools.get(name2, scopeOf(ctx)) !== void 0;
     const hidden = hideable.filter((name2) => agent.ctx.tools.get(name2, agent) === void 0 && provided(name2));

package/roles.js

@@ -25,6 +25,7 @@ async function validateRoleModel(llm, role, signal) {
 
 // src/host/role-tool.ts
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import { dirname as dirname2 } from "node:path";
 import { ReasoningEffortId as ReasoningEffortId2 } from "@deepseek-ai/dsh-llm";
 
 // src/role-settings.ts
@@ -73,31 +74,217 @@ function roleToolFilter(role, presetDefault = []) {
   return own.mode === "replace" ? [...own.deny] : [.../* @__PURE__ */ new Set([...presetDefault, ...own.deny])];
 }
 
+// src/session-roles.ts
+var PARENT_ROLE = { name: "Subagent", role: "subagent", model: "inherit", reasoning: "inherit", spawn: "fresh", persona: "" };
+var emptySessionRoles = () => ({ version: 1, roles: [] });
+var object2 = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+var validated = (roles) => executableRoles(parseRoles(roles));
+function parseSessionRoles(input) {
+  if (!object2(input) || input.version !== 1) throw new Error("Invalid session roles record");
+  return { version: 1, roles: validated(input.roles) };
+}
+function mergeRoles(preset, record) {
+  const own = new Map(record.roles.map((role) => [role.role, role]));
+  const merged = preset.map((role) => {
+    const copy = own.get(role.role);
+    return copy ? { ...copy, source: "session" } : { ...role, source: "preset" };
+  });
+  const presetIds = new Set(preset.map((role) => role.role));
+  for (const role of record.roles) if (!presetIds.has(role.role)) merged.push({ ...role, source: "session" });
+  return merged;
+}
+function selectRole(merged, roleId) {
+  return merged.length ? merged.find((role) => role.role === roleId) : PARENT_ROLE;
+}
+
 // src/package-name.ts
 var PACKAGE_NAME = "@matamt-dbg/dsh-studio";
 var POLICY_PLUGIN = `${PACKAGE_NAME}/policy`;
 var ROLE_PLUGIN = `${PACKAGE_NAME}/roles`;
 var BATCH_PLUGIN = `${PACKAGE_NAME}/batch`;
 var JUDGE_PLUGIN = `${PACKAGE_NAME}/judge`;
+var LOOP_PLUGIN = `${PACKAGE_NAME}/loop`;
 
 // src/delegation.ts
 var ROLE_TOOL = "subagent_role";
+var LEGACY_ROLE_TOOL = "studio_role";
+var GENERIC_DELEGATION_TOOLS = ["subagent", "subagent_fork", "list_subagent_models"];
+
+// src/optimized-preset.ts
+var OPTIMIZED_TOOLS = [
+  "read_batch",
+  "read",
+  "write",
+  "edit",
+  "glob",
+  "grep",
+  "job_output",
+  "job_list",
+  "job_kill",
+  "skill",
+  "ask_user_question",
+  "web_search",
+  "web_fetch",
+  "present",
+  "bash",
+  "read_image",
+  "exit_plan_mode",
+  "send_message",
+  "interrupt_agent",
+  "list_agents",
+  "workflow",
+  "subagent_role"
+];
+var ALLOWED_TOOLS = /* @__PURE__ */ new Set([...OPTIMIZED_TOOLS, ...GENERIC_DELEGATION_TOOLS, LEGACY_ROLE_TOOL]);
+
+// src/host/preset-store.ts
+import { createScope } from "@deepseek-ai/dsh-scope";
+
+// src/host/preset-policy.ts
+import { scopeChainOf, scopeOf } from "@deepseek-ai/dsh-scope";
+var POLICY_SECTION_ORDERS = Object.freeze({
+  "tool:jobs": "TOOL_JOBS",
+  "tool:bash": "TOOL_BASH",
+  "tool:pwsh": "TOOL_PWSH",
+  "tool:read": "TOOL_READ",
+  "tool:write": "TOOL_WRITE",
+  "tool:edit": "TOOL_EDIT",
+  "tool:glob": "TOOL_GLOB",
+  "tool:grep": "TOOL_GREP",
+  "tool:web_fetch": "TOOL_WEB_FETCH",
+  "tool:web_search": "TOOL_WEB_SEARCH",
+  "tool:goal": "TOOL_GOAL",
+  "tool:workflow": "TOOL_WORKFLOW"
+});
+
+// src/config-overrides.ts
+var LEGACY_DROPPED_PACKAGES = Object.freeze([
+  "@deepseek-ai/dsh-agent-instructions",
+  "@deepseek-ai/dsh-time-context",
+  "@deepseek-ai/dsh-skill-filesystem",
+  "@deepseek-ai/dsh-compaction-basic",
+  "@deepseek-ai/dsh-command-compact",
+  "@deepseek-ai/dsh-compaction-tool-result-pruner"
+]);
+var CONFIG_REQUIRES = Object.freeze({
+  "@deepseek-ai/dsh-command-compact": "@deepseek-ai/dsh-compaction-basic"
+});
+
+// src/host/preset-store.ts
+import { dirname, join } from "node:path";
+import { dump } from "js-yaml";
+import { entryListSchema as entryListSchema2 } from "@deepseek-ai/cordis-plugin-include";
+
+// src/provider-fields.ts
+var field = (key, type, value, minimum) => ({ key, type, ...value === void 0 ? {} : { value }, ...minimum === void 0 ? {} : { minimum } });
+var providerFields = {
+  "@deepseek-ai/dsh-compaction-basic": [field("thresholdRatio", "number", 0.8, 0), field("headroomTokens", "number", 65536, 1), field("retainRatio", "number", 0.16, 0), field("retainTokens", "number", void 0, 0), field("summarizationProvider", "string", ""), field("summarizationModel", "string", ""), field("maxTokens", "number", void 0, 1), field("compactionRetries", "number", 1, 0), field("maxOverflowRetries", "number", 1, 0), field("auto", "boolean", true)],
+  "@deepseek-ai/dsh-compaction-tool-result-pruner": [field("thresholdChars", "number", 8192, 1), field("headChars", "number", 4096, 0), field("tailChars", "number", 1024, 0)],
+  "@deepseek-ai/dsh-agent-tool-presentation": [{ key: "mode", type: "string", options: ["native", "ptc"] }],
+  "@deepseek-ai/dsh-persona": [field("prefix", "string"), field("suffix", "string", ""), field("includeRuntimeContext", "boolean", true)],
+  "@deepseek-ai/dsh-agent-instructions": [field("maxBytes", "number", 65536), field("maxSourceBytes", "number", void 0, 1), field("projectRootMarkers", "string[]"), field("instructionFileCandidates", "string[]"), field("localInstructionFileCandidates", "string[]")],
+  "@deepseek-ai/dsh-time-context": [field("timeZone", "string"), field("refreshIntervalMs", "number", void 0, 0)],
+  "@deepseek-ai/dsh-skill-filesystem": [field("providerName", "string", "filesystem"), field("includeDefaultRoots", "boolean", true), field("dshHome", "string"), field("agentsHome", "string"), field("customSkillDirs", "string[]", []), field("bundledSkillDir", "string"), field("watch", "boolean", true), field("watchUsePolling", "boolean", false), field("watchStabilityThresholdMs", "number", 200, 0), field("watchPollIntervalMs", "number", 100, 1), field("watchMaxProjects", "number", 128, 1), field("watchFollowSymlinks", "boolean", true)]
+};
+
+// src/host/composition-plan.ts
+import { load } from "js-yaml";
+import { entryListSchema } from "@deepseek-ai/cordis-plugin-include";
+
+// src/host/preset-store.ts
+function studioStorePath(env = process.env, profile) {
+  const directory = profile?.dir ?? env.DSH_PROFILE_DIR;
+  if (!directory) throw new Error("Studio preset persistence requires a profile");
+  return join(directory, "studio-data", "presets.json");
+}
+
+// src/host/session-role-store.ts
+import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { join as join2 } from "node:path";
+var SESSION_ID = /^[\w-]{1,200}$/;
+var sessionRolesRoot = (dataDir) => join2(dataDir, "session-roles");
+function sessionRolesFile(root, sessionId) {
+  if (typeof sessionId !== "string" || !SESSION_ID.test(sessionId)) throw new Error(`Invalid session id for session roles: ${JSON.stringify(sessionId)}`);
+  return join2(root, `${sessionId}.json`);
+}
+async function readSessionRoles(root, sessionId) {
+  const file = sessionRolesFile(root, sessionId);
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return emptySessionRoles();
+    throw error;
+  }
+  try {
+    return parseSessionRoles(JSON.parse(text));
+  } catch (error) {
+    throw new Error(`Invalid session roles for session ${sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+// src/host/session-root.ts
+var MAX_HOPS = 64;
+async function resolveRootSession(sessionId, lookup, known) {
+  let current = sessionId;
+  let header = known ?? await lookup(current);
+  const seen = /* @__PURE__ */ new Set([current]);
+  for (let hop = 0; hop < MAX_HOPS && header?.origin === "subagent" && header.parentSession; hop++) {
+    const parent = header.parentSession;
+    if (seen.has(parent)) break;
+    const next = await lookup(parent);
+    if (!next) break;
+    seen.add(parent);
+    current = parent;
+    header = next;
+  }
+  return current;
+}
+function headerLookup(ctx, signal) {
+  return async (sessionId) => {
+    const live = ctx.get("sessions")?.get(sessionId);
+    if (live) return live.header;
+    const controller = ctx.get("sessionController");
+    if (!controller) return void 0;
+    try {
+      return (await controller.inspect(sessionId, signal)).meta;
+    } catch {
+      signal?.throwIfAborted();
+      return void 0;
+    }
+  };
+}
 
 // src/host/role-tool.ts
 var name = "studio-role";
 var inject = ["tools", "subagents", "llm"];
-var PARENT_ROLE = { name: "Subagent", role: "subagent", model: "inherit", reasoning: "inherit", spawn: "fresh", persona: "" };
+var ROLE_TOOL_DESCRIPTION = "Delegate a self-contained task to a subagent. Use action=list to see the specialist roles; when none are listed, a call starts a child with the same model and settings as you. Calls return a native child agent id; the child reports back through normal subagent delivery.";
+var ROLE_PARAMETER_DESCRIPTION = "Role identifier from action=list; required for call when roles are listed.";
+function sessionRolesDirectory(ctx) {
+  try {
+    return sessionRolesRoot(dirname2(studioStorePath(process.env, ctx.get?.("profileContext"))));
+  } catch {
+    return void 0;
+  }
+}
 function apply(ctx, config) {
   const roles = executableRoles(parseRoles(config.roles));
   const deny = config.toolFilter?.deny;
   if (deny !== void 0 && (!Array.isArray(deny) || deny.some((name2) => typeof name2 !== "string" || !name2))) throw new Error("Invalid subagent tool filter");
   const presetDefault = deny ?? [];
+  const directory = sessionRolesDirectory(ctx);
+  async function sessionRoles(agent, signal) {
+    if (!directory || !agent?.id) return emptySessionRoles();
+    const root = await resolveRootSession(agent.id, headerLookup(ctx, signal), agent.session?.header);
+    signal.throwIfAborted();
+    return readSessionRoles(directory, root);
+  }
   ctx.tools.register(defineTool({
     name: ROLE_TOOL,
-    description: roles.length ? "Discover saved specialist roles or delegate a task to one. Calls return a native child agent id; the child reports back through normal subagent delivery." : "Delegate a self-contained task to a subagent that starts with the same model and settings as you. Calls return a native child agent id; the child reports back through normal subagent delivery.",
+    description: ROLE_TOOL_DESCRIPTION,
     parameters: {
       action: { type: "string", enum: ["list", "call"], required: true, description: "list discovers role identifiers and settings; call delegates a task." },
-      role: { type: "string", description: roles.length ? "Saved role identifier, required for call." : "Not needed; no specialist roles are defined, so every call starts a child matching the parent." },
+      role: { type: "string", description: ROLE_PARAMETER_DESCRIPTION },
       task: { type: "string", description: "Self-contained task for the specialist, required for call. Fork roles also inherit the conversation." }
     },
     output: {
@@ -106,9 +293,10 @@ function apply(ctx, config) {
     },
     isConcurrencySafe: () => true,
     async execute(args, exec) {
-      if (args.action === "list") return { result: JSON.stringify({ roles: roles.map(({ persona: _persona, ...role2 }) => role2) }) };
-      if (args.action !== "call") throw new Error("Unknown Studio role action");
-      const role = roles.length ? roles.find((role2) => role2.role === args.role) : PARENT_ROLE;
+      if (args.action !== "list" && args.action !== "call") throw new Error("Unknown Studio role action");
+      const merged = mergeRoles(roles, await sessionRoles(exec.agent, exec.signal));
+      if (args.action === "list") return { result: JSON.stringify({ roles: merged.map(({ persona: _persona, ...role2 }) => role2) }) };
+      const role = selectRole(merged, args.role);
       if (!role) throw new Error("Unknown Studio role; use action=list to discover roles");
       if (typeof args.task !== "string" || !args.task.trim()) throw new Error("Role call requires a task");
       if (!exec.agent) throw new Error("Studio role call requires a calling agent");
@@ -122,30 +310,50 @@ function apply(ctx, config) {
       }
       if (role.reasoning !== "inherit") agentOptions.reasoningEffort = ReasoningEffortId2(role.reasoning);
       const maxDepth = ctx.subagents.resolveMaxDepth();
-      const hidden = roleToolFilter(roles.length ? role : void 0, presetDefault);
+      const hidden = roleToolFilter(role, presetDefault);
       const toolFilter = hidden.length ? { deny: hidden } : void 0;
+      const provider = role.spawn === "fork" ? "fork" : "spawn";
+      const backend = ctx.subagents.getProvider?.(provider);
+      const capabilities = backend?.capabilities;
+      const needsPolicyOwner = capabilities !== void 0 && "agentPreset" in capabilities && (capabilities.persona !== true || capabilities.toolFilter !== true);
+      let prepared;
+      if (needsPolicyOwner) {
+        const owner = ctx.get("studioChildPolicies");
+        if (!owner) throw new Error("Studio child policy owner is unavailable; no child was started");
+        prepared = await owner.prepare(exec.agent.id, hidden, role.persona || void 0);
+      }
       const spec = {
-        provider: role.spawn === "fork" ? "fork" : "spawn",
+        provider,
         label: role.name,
+        ...prepared ? { childId: prepared.childId } : {},
         request: {
           parent: exec.agent,
           prompt: [{ type: "text", text: args.task }],
           ...Object.keys(agentOptions).length ? { agentOptions } : {},
-          ...role.persona ? { persona: role.persona } : {},
+          ...!prepared && role.persona ? { persona: role.persona } : {},
           ...maxDepth === void 0 ? {} : { maxDepth },
-          ...toolFilter ? { toolFilter } : {}
+          ...!prepared && toolFilter ? { toolFilter } : {}
         },
         signal: exec.signal
       };
       const native = ctx.subagents;
-      const started = typeof native.startActivation === "function" ? await native.startActivation({ ...spec, delivery: "parent" }) : native.startContinuable ? await native.startContinuable(spec) : (() => {
-        throw new Error("This DSH runtime lacks a native child start API");
-      })();
-      return { result: JSON.stringify({ kind: "activation", subagentId: started.childId, role: role.role }) };
+      try {
+        exec.signal.throwIfAborted();
+        const started = typeof native.startActivation === "function" ? await native.startActivation({ ...spec, delivery: "parent" }) : native.startContinuable ? await native.startContinuable(spec) : (() => {
+          throw new Error("This DSH runtime lacks a native child start API");
+        })();
+        if (prepared && started.childId !== prepared.childId) throw new Error("DSH did not preserve the Studio child policy identity");
+        return { result: JSON.stringify({ kind: "activation", subagentId: started.childId, role: role.role }) };
+      } catch (error) {
+        await prepared?.abandon();
+        throw error;
+      }
     }
   }));
 }
 export {
+  ROLE_PARAMETER_DESCRIPTION,
+  ROLE_TOOL_DESCRIPTION,
   apply,
   inject,
   name

package/skills/studio-pixie-hook-guide/SKILL.md

@@ -20,8 +20,9 @@ Help the user build a Pixie Gate: a task the Pixie model runs at one point of an
    | `turn-end` | The agent's final answer |
 
 2. Write the task (`instruction`) in plain words. Say which of the five output fields to use: verdict (`pass`/`stop`), reason, replacement, addition, note. Check the guide's application table: at `tool-before` and `turn-end` replacement and addition become notes; at `turn-end` stop asks the agent to redo with the reason.
-3. For a judgment (yes/no threshold, picking one of fixed options, a graded score), write a hook script that calls `pixie judge` and decides the outcome itself: exit 10 to pass untouched, exit 11 to print the gate output, exit 0 only when Pixie should interpret the result. Gates have no judge option; the engine (LLM or TypeSafe Jev) is set in Studio → Pixie → Gates → Decision engine.
-4. Use a hook script only when the two fields cannot express the flow: conditions (only some tools), loops, or external measurement. Prefer no script.
+3. When the user already has a Pixie Loop recipe for the check, prefer the gate's **Pixie Loop recipe** advanced option (`advanced.loop: { recipe, mode: "check" | "repair" }`) with no script: check stops with Pixie's feedback, repair replaces the content once it passes (user-message, agent-message, tool-after only). It cannot be combined with `advanced.script`.
+4. For a judgment (yes/no threshold, picking one of fixed options, a graded score), write a hook script that calls `pixie judge` and decides the outcome itself: exit 10 to pass untouched, exit 11 to print the gate output, exit 0 only when Pixie should interpret the result. Gates have no judge option; the engine (LLM or TypeSafe Jev) is set in Studio → Pixie → Gates → Decision engine.
+5. Use a hook script only when the two fields cannot express the flow: conditions (only some tools), loops, or external measurement. Prefer no script.
 
 ## Write a script
 
@@ -29,10 +30,11 @@ Help the user build a Pixie Gate: a task the Pixie model runs at one point of an
 - Read the target from stdin. Print what the task needs to stdout (256 KB max); print a JSON object to fill `{{hooks.<name>.data}}`. `<name>` is the file name without its last extension.
 - Exit 0 to run the Pixie task, 10 to skip the gate, 11 to apply stdout as the gate output (a JSON object with optional `verdict`, `reason`, `replace`, `append`, `note`; no Pixie call). Anything else is an error. A gate whose script always exits 10 or 11 may have an empty task; exit 0 then fails.
 - Use `pixie ask "<instruction>" [--input]` and `pixie judge [--type bool|select|score] --question "…" [--json] [--input]`. bool takes `--threshold` (default 0.5) and optional `--true`/`--false` meanings, prints the yes probability, exits 0 at or above the threshold and 1 below; select takes two or more `--option name="description"` and prints the chosen name; score takes 2–10 `--level "description"` (lowest first) and prints the score. `--json` prints `{"type","label","answer","engine"}`. Errors exit 2 and never become a "no". With `--input` the helper reads stdin; otherwise it uses the gate target. At most 20 helper calls per run.
+- Use `pixie loop --recipe <name> [--mode check|repair] [--json] [--input]` to run a saved Pixie Loop recipe on the input: exit 0 when it passes (stdout: the input, or the repaired text for `repair`), exit 1 with the reason when it does not, exit 2 on errors. Newlines in stdout become `\n`; use `--json` (`passed`, `output`, `reason`, `feedback`) to read them safely. One loop is one helper call. Recipes with `act`, episodes, or selection are refused.
 - Write the whole judgment in `--question`: question IDs never reach the model. For several inputs (source and translation, answer and evidence), pipe a JSON object built with `jq` and name its fields in backticks in the question.
 - The script runs in the session working directory under the session sandbox. Do not write files unless the session can write; never try to escape the sandbox.
 - In the task, reference only `{{hooks.<name>.text}}` and `{{hooks.<name>.data}}` of the chosen script.
-- At `turn-end`, a note concluded with exit 11 shows under that turn's answer in the chat. Start it with a bracketed label line (e.g. `[한국어 번역]`) to title the block; a label containing `not verified`/`미확인` gets a warning badge.
+- At every point, the gate's **Show the result in the chat** setting (`advanced.showInChat`, on by default) decides whether the result shows right under what it checked (the message, the tool call, or the turn's answer), whoever concluded it: the note if any, otherwise the verdict and reason. It is never written to the session log. For a note, start it with a bracketed label line (e.g. `[한국어 번역]`) to title the block; a label containing `not verified`/`미확인` gets a warning badge.
 
 Test a script by hand before relying on it: `printf 'sample' | PIXIE_POINT=tool-after PIXIE_TOOL_NAME=grep ./script.sh; echo $?`. The helper only works inside a real gate run.
 
@@ -42,7 +44,7 @@ Do not edit `definitions.json` unless the user asks you to; prefer guiding them
 
 ```json
 { "id": "<uuid>", "name": "…", "enabled": true, "when": "user-message", "instruction": "…",
-  "advanced": { "confirmReplace": false, "onError": "pass", "agents": "root", "timeoutMs": 60000, "maxSteers": 1, "script": "optional.sh" },
+  "advanced": { "confirmReplace": false, "onError": "pass", "agents": "root", "timeoutMs": 60000, "maxSteers": 1, "showInChat": true, "script": "optional.sh", "loop": { "recipe": "optional-recipe", "mode": "check" } },
   "presetIds": ["<preset id>"], "disabledPresetIds": ["<attached preset where it is off>"] }
 ```
 

package/skills/studio-pixie-hook-guide/guide.md

@@ -55,12 +55,14 @@ When the verdict is stop, the replacement and addition never reach the main mode
 
 | Option | Default | Description |
 | --- | --- | --- |
+| Pixie Loop recipe | None | Judge with a saved [Pixie Loop recipe](pixie-loop.md#recipes) instead of the task. **Check** stops when the content does not pass, with Pixie's feedback as the reason. **Repair** reworks the content until it passes and replaces it (user message, agent message, and tool result points only). Cannot be combined with a hook script |
 | Pixie hook script | None | A script run before the task. See [below](#pixie-hook-scripts) |
+| Show the result in the chat | On | Shows the result right under what the gate checked. See [Chat notes](#chat-notes-and-per-session-switches) |
 | Confirm before replacing | Off | Stops a real replacement and shows it as a suggestion (message points) |
-| On error | Pass | Pass or stop on model or script errors and timeouts |
-| Target agents | Root (child for agent messages) | Root, child, or any |
-| Time limit | 60 s | Script, helper, and model calls together |
-| Redo limit | 1 | Corrections per turn at the answer-end point |
+| If Pixie fails | Continue as usual | Continue as usual or stop it on model or script errors and timeouts |
+| Target agents | Main agent (Subagents for agent messages) | Main agent, Subagents, or All |
+| Time limit (seconds) | 60 | Script, helper, and model calls together |
+| Redo limit per turn | 1 | Corrections per turn at the answer-end point |
 
 ## Pixie hook scripts
 
@@ -111,14 +113,16 @@ Inside a script, the `pixie` command calls the Pixie model. It is first on the s
 ```sh
 pixie ask "<instruction>" [--input]
 pixie judge [--type bool|select|score] --question "<question>" [type arguments] [--json] [--input]
+pixie loop --recipe <name> [--mode check|repair] [--json] [--input]
 ```
 
 - With `--input` the helper reads its input from stdin; otherwise it uses the gate target.
 - `ask` prints the answer and exits 0, using the Pixie model.
 - `judge` judges with the [decision engine](#decision-engine); types and output follow the table there.
+- `loop` runs a saved [Pixie Loop recipe](pixie-loop.md#recipes) on one input. `check` (default) exits 0 and prints the input when it passes, otherwise exits 1 and prints the reason. `repair` reworks it until it passes and prints the result with exit 0, or exits 1 with the reason. Newlines become `\n`. `--json` prints `{"recipe","mode","passed","output"?,"feedback"?,"reason","runId"}`. One run counts as one helper call; the recipe's attempt limit and the gate time limit bound its model calls. Recipes that run commands (`act`), episodes, and selections are not allowed. Runs are recorded in Pixie tab → Loops.
 - Usage, token, limit, and model errors exit 2 with a message on stderr. A failed helper call never decides the gate; the script's exit code does.
 - Limits: 20 calls and 256 KB per request for each run. Calls follow the gate time limit and cancellation; their usage is added to the gate and listed under **Helper calls** in the run record.
-- A token reaches only that run's ask and judge. The helper uses a Studio route on the DSH web server, so it is unavailable without one (for example, headless).
+- A token reaches only that run's ask, judge, and loop. The helper uses a Studio route on the DSH web server, so it is unavailable without one (for example, headless).
 
 ## Decision engine
 
@@ -236,12 +240,31 @@ On start, Studio installs a skill with this guide and the hook rules into `<DSH
 
 ## Chat notes and per-session switches
 
-**Chat notes:** when a hook script at the turn-end point concludes with a note (exit 11), for example a translation, the note appears as a block right under that turn's answer.
+**Chat notes:** a gate with **Show the result in the chat** on (Advanced; on by default) shows its result as a block right under what it checked, whether the script (exit 11) or Pixie concluded it. The setting decides; the output does not. The block is drawn from Studio's gate records and is never written to the session log.
 
+| Point | Where the block appears |
+| --- | --- |
+| You send an instruction / agents message each other | Right under that message, outside the turn's folded steps. A subagent's message shows in the subagent's chat |
+| Before a tool runs / a tool result arrives | Right under that tool call, inside the turn's steps (expand the turn to see it). Before and after results of one call show together |
+| The agent finishes its answer | Right under that turn's answer |
+
+A rejected instruction has no message in the chat, so its result stays in the Pixie tab only.
+
+![Gate results under the instruction, the Read and Bash calls, and the answer](../images/en/pixie-gate-chat-results.png)
+
+When the turn is folded, the instruction and answer results stay visible; tool results fold with the steps.
+
+![The same turn folded](../images/en/pixie-gate-chat-results-folded.png)
+
+Turn the setting off in the gate editor under **Advanced → Show the result in the chat**. The gate still runs and its record stays in the Pixie tab.
+
+![Show the result in the chat](../images/en/pixie-gate-show-in-chat.png)
+
+- The block shows the note when there is one, for example a translation. Without a note it shows the verdict with its reason, and any replacement or addition in a collapsed section. A failed run shows one error line.
 - If the note's first line starts with a bracketed label such as `[한국어 번역]`, the label becomes the block title. A label containing `not verified` (or `미확인`) gets a **not verified** badge.
 - The body renders as Markdown. The block offers **Hide**, **Open in Pixie tab**, and **Turn off in this session**.
-- It appears after the script finishes; there is no progress indicator. Skipped turns (exit 10), turns Pixie concluded, and turns without a note get no block. If the gate ran more than once in a turn, only the last note shows.
-- The original answer stays as it is; it cannot be collapsed or replaced.
+- It appears after the gate finishes; there is no progress indicator. Skipped turns (exit 10), cancelled runs, and runs whose gate had the setting off get no block. Each run keeps the setting it started with. If a gate ran more than once at the same place, only the last result shows.
+- The result block does not change the checked message, tool call, or answer. **Hide** collapses only the gate result.
 
 **Per-session switches:** at the top of **Pixie** tab → **Gates**, **Gates in this session** lists every gate that applies to this session's preset with a switch that turns it off for this session only. **Turn off in this session** on a chat block is the same switch.
 

package/skills/studio-pixie-loop-guide/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: studio-pixie-loop-guide
+description: Write DSH Studio `pixie_loop` specs — many independent items judged by the same criteria (translation review, copy edits, per-file audits), experiments judged by running each output (selectors, regexes), step-by-step episodes, and picking one listed option per item or step (e.g. game actions), all outside your context with the Pixie model and the decision engine. Use when the user asks to batch, review, translate, try, or choose over many items with Pixie or Jev, or to write or debug a pixie_loop spec.
+---
+
+# DSH Studio Pixie Loop
+
+`pixie_loop` runs work → code checks → decision-engine judgment → Pixie feedback → retry for each item, outside your context, and returns only counts, a results file, and the items that never passed. The full contract and worked examples are in `guide.md` next to this file. Read it before writing a spec.
+
+## Decide whether it fits
+
+Use `pixie_loop` only when all hold:
+
+- There are several independent items (usually 5 or more).
+- One fixed set of criteria judges every item.
+- The worker needs no tools: everything it needs fits in the item input and `shared`. If an output must be run to be judged, one fixed `act` command can run it.
+- The result can be judged from text (an act command's output counts).
+
+Otherwise: one judgment → `judge`; multi-step work with files or tools → `subagent_role`; branching or many cooperating agents → `workflow` (only when the user asks for one); a check at a set moment of the agent's work → Pixie Gate (`studio-pixie-hook-guide`). Tell the user which and why.
+
+## Write the spec
+
+1. **Items.** Give each a stable unique `id` (a key, a file path). Under ~20 short items use `items.inline`; otherwise write a JSONL file with one `{"id","input"}` per line and pass `items.path`. Inputs up to 32,000 characters; a file item must fit on one line under the read tool's line limit. For file audits, read the files yourself and put their contents in the inputs.
+2. **work.instruction.** What to do with one input, and the output format. Say "Reply with the output only."
+3. **shared.** Glossary, style rules, and examples every item needs. Never put other items here.
+4. **Criteria.** Plain English sentences, one property each, about `input` and `output`. Name failure types ("say whether it is a mistranslation, terminology, tone, or omission"). Give `checks` instead when the user already has exact questions; each question needs a pass rule (`noul` → `{min}`, `choice` → `{accept}` leaving a failing option, `score` → `{min}` level).
+5. **codeChecks.** Put every exact requirement here, not in criteria: `placeholders` when inputs contain `{x}`, `{{x}}`, `%s`, or tags; `regex` with `expect` `match`/`no-match` for required or forbidden text; `json` with `keys` when the output must be JSON.
+6. **Calibration.** At least one realistic pass example and one realistic fail example per criterion. Use real inputs. The run refuses to start if the checks do not separate them; then reword the failing question or switch to `checks`.
+7. **Limits.** `limits.tokens` ≈ items × attempts × (input + output + shared tokens) × 3 for checks and feedback, plus headroom; `limits.timeMs` generous. Defaults: `maxAttempts` 3, `concurrency` 4.
+8. **Act (optional).** When an output only proves itself by running it, add `act: { tool: "bash", command: "… {{output}} …", safeToRepeat: true }`. Values are quoted for you: write placeholders as separate words, never inside quotes or glued to text. Only use commands that are safe to run again; set `isolated: true` only when each item uses its own state. Write a small probe script that prints just what the judgment needs, and give each calibration example an `observation`. Add `extract` when observations are long.
+9. **Episodes and selection (optional).** `mode: "episode"` makes each output one step that act runs, until the checks say the goal is reached. `select` lets the decision engine pick one option from JSON `{"options": [...]}` in the input or (episodes) the observation; the worker writes nothing. Never invent options yourself; they must come from the source. Set `minConfidence` when a wrong pick is costly.
+10. **Route (optional).** `route: { question: "<choice id>" }` groups results by that answer.
+11. **output** path for the results JSONL. Use `run_in_background: true` for long runs; keep working and collect with `job_output`.
+
+## Recipes
+
+If the user has a saved recipe for the job (Studio → Pixie → Gates → Loop recipes), prefer `{ "recipe": "<name>", "items": ..., "output": ... }`; its checks were calibrated when saved. Recipes are also what gates (Check/Repair) and hook scripts (`pixie loop --recipe`) run; for gate and hook work see `studio-pixie-hook-guide`. Recipes with `act`, episodes, or selection run only through the tool.
+
+## After the run
+
+- Report the counts and the results file. Do not re-run passed items.
+- Handle each `escalated` item yourself (fix it, or ask the user), using its failed checks and feedback. Feedback is Pixie's guess, not the verdict.
+- `errors` are engine or model failures, not fails. Rerun only those ids if the cause is transient.
+- `stopped` means a limit was reached: rerun with only the ids missing from the results file.
+- If the start was refused (`Calibration failed`, `could not compile`), fix the spec; do not loosen the criteria until bad examples pass.
+- Merge results into the target files yourself; `pixie_loop` writes only the results file.
+
+The user can inspect every attempt in **Pixie tab → Loops**. Item contents go to the Pixie model provider and the decision engine; tell the user before sending sensitive material.