@ran-sh/dsh-crew 1.6.2 → 1.7.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "Dispatch subtasks to DeepSeek Harness (DSH) agents as native subagents with live progress",
   "author": {
     "name": "ZSeven-W"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ran-sh/dsh-crew",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "bin": {

package/src/install/crew-skill.mjs

@@ -0,0 +1,91 @@
+// On-demand Crew guidance, installed as a user skill.
+//
+// Crew used to inject a "capability-aware delegation policy" block into the
+// host's global instruction file. That made every host session — Codex, ZCode —
+// carry Crew's delegation rules whether or not the operator wanted Crew that
+// turn, which shapes how the host does its own work.
+//
+// The guidance now lives in a skill instead, loaded only when the operator asks
+// for Crew. Nothing about the host's default behaviour changes; the knowledge is
+// there the moment it is wanted.
+//
+// Each host reads its own skill directory, so the skill is copied to all of them
+// — the same layout the Oracle skill uses, plus the shared `~/.agents/skills`
+// that ZCode reads. Installing a skill replaces writing a policy block, so the
+// host installers also *remove* any block a previous release left behind.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+export const CREW_SKILL_NAME = 'dsh-crew';
+
+/**
+ * Skill roots, in the order they are installed. `.agents/skills` is the shared
+ * directory ZCode reads; the other two are what Codex and Claude Code read. The
+ * Codex one is resolved through `CODEX_HOME` because Codex may point elsewhere —
+// writing only to `~/.codex` would put the skill where Codex never looks.
+ */
+export function crewSkillRoots({ home = homedir(), env = process.env } = {}) {
+  const codexHome = typeof env?.CODEX_HOME === 'string' && env.CODEX_HOME.trim()
+    ? resolve(env.CODEX_HOME.trim())
+    : join(home, '.codex');
+  return [
+    join(home, '.agents', 'skills'),
+    join(codexHome, 'skills'),
+    join(home, '.claude', 'skills'),
+  ];
+}
+
+export function crewSkillFiles({ home = homedir(), env = process.env } = {}) {
+  return crewSkillRoots({ home, env }).map((root) => join(root, CREW_SKILL_NAME, 'SKILL.md'));
+}
+
+/** The skill template shipped in the payload. */
+export function crewSkillSource({ root }) {
+  return join(root, 'skills', CREW_SKILL_NAME, 'SKILL.md');
+}
+
+export function readCrewSkill({ root }) {
+  const file = crewSkillSource({ root });
+  return existsSync(file) ? readFileSync(file, 'utf8') : null;
+}
+
+/**
+ * Copy the skill template into every host skill directory. Idempotent: a file
+ * that already matches is left alone, so a repeat install stays quiet.
+ */
+export function installCrewSkill({ home = homedir(), root, env = process.env } = {}) {
+  if (!root) return { ok: false, code: 'CREW_SKILL_SOURCE_REQUIRED' };
+  const content = readCrewSkill({ root });
+  if (content === null) return { ok: false, code: 'CREW_SKILL_TEMPLATE_MISSING', source: crewSkillSource({ root }) };
+  const written = [];
+  const files = crewSkillFiles({ home, env });
+  for (const file of files) {
+    let current = null;
+    try { current = readFileSync(file, 'utf8'); } catch { /* absent or unreadable */ }
+    if (current === content) continue;
+    try {
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, content);
+      written.push(file);
+    } catch (error) {
+      return { ok: false, code: 'CREW_SKILL_WRITE_FAILED', file, error: String(error?.message ?? error) };
+    }
+  }
+  return { ok: true, changed: written.length > 0, written, files, file: files[0] };
+}
+
+/**
+ * Remove the installed skill from every host directory. Only Crew's own skill
+ * folder is touched, so a user's other skills are never affected.
+ */
+export function removeCrewSkill({ home = homedir(), env = process.env } = {}) {
+  const removed = [];
+  for (const dir of crewSkillRoots({ home, env }).map((root) => join(root, CREW_SKILL_NAME))) {
+    if (!existsSync(dir)) continue;
+    try { rmSync(dir, { recursive: true, force: true }); removed.push(dir); }
+    catch { /* best effort: a locked file is not worth failing an uninstall */ }
+  }
+  return { ok: true, changed: removed.length > 0, removed, file: removed[0] ?? null };
+}

package/src/install/install-legacy.mjs

@@ -7,7 +7,8 @@ import { createHash } from 'node:crypto';
 import { dirname, join, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { normalizeModelPriority } from '../model-routing.mjs';
+import { normalizeModelPriority } from '../model-routing.mjs';
+import { crewSkillFiles, installCrewSkill, readCrewSkill, removeCrewSkill } from './crew-skill.mjs';
 import { zcodeStatus } from './zcode.mjs';
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
@@ -94,32 +95,13 @@ export function stripKnownLegacyCodexPolicy(text, { knownHashes = CODEX_LEGACY_P
   return `${keptPrefix}${match[0]}${keptSuffix}`;
 }
 
-function installGlobalCodexPolicy({ home, root, env = process.env }) {
-  const file = join(codexHomeDir(home, env), 'AGENTS.md');
-  const block = managedPolicyBlock(root);
-  if (!block) return { ok: false, action: 'global policy template missing' };
-  mkdirSync(dirname(file), { recursive: true });
-  const current = readText(file) ?? '';
-  const managed = new RegExp(`${POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
-  const template = readText(join(root, 'codex', 'AGENTS.md'))?.trim() ?? '';
-  let next;
-  if (managed.test(current)) next = current.replace(managed, block);
-  else if (current.trim() === template) next = `${block}\n`;
-  else next = `${current.trimEnd()}${current.trim() ? '\n\n' : ''}${block}\n`;
-  next = stripKnownLegacyCodexPolicy(next);
-  if (next !== current) {
-    backup(file);
-    writeFileSync(file, next);
-  }
-  return { ok: true, action: `global policy: ${file}` };
+/** The installed skill is present and still matches the payload template. */
+function crewSkillInstalled({ home, root, env = process.env }) {
+  const expected = readCrewSkill({ root });
+  if (expected === null) return false;
+  // Every host directory must hold the current template, not just the first.
+  return crewSkillFiles({ home, env }).every((file) => readText(file) === expected);
 }
-
-function globalCodexPolicyReady({ home, root = ROOT, env = process.env }) {
-  const block = managedPolicyBlock(root);
-  const text = readText(join(codexHomeDir(home, env), 'AGENTS.md'));
-  return !!block && typeof text === 'string' && text.includes(block);
-}
-
 function uninstallGlobalCodexPolicy({ home, env = process.env }) {
   const file = join(codexHomeDir(home, env), 'AGENTS.md');
   const current = readText(file);
@@ -432,7 +414,7 @@ export function installStatus({ home = homedir(), root = ROOT, env = process.env
     status_prompt: expectedStatusPrompt !== null && readText(join(codexRoot, 'prompts', 'dsh-status.md')) === expectedStatusPrompt,
     mcp: !!expectedTarget && mcpTarget === expectedTarget,
     target_alignment: !!expectedTarget && workerTarget === expectedTarget && reviewerTarget === expectedTarget && mcpTarget === expectedTarget,
-    global_policy: globalCodexPolicyReady({ home, root, env }),
+    skill: crewSkillInstalled({ home, root, env }),
   };
   const codexInstalled = Object.values(components).some(Boolean)
     || existsSync(join(codexRoot, 'agents', 'ds-flash.toml'))
@@ -466,6 +448,8 @@ export function uninstallCodex({ home = homedir(), env = process.env } = {}) {
   }
   const policyAction = uninstallGlobalCodexPolicy({ home, env });
   if (policyAction) actions.push(policyAction);
+  const skillAction = removeCrewSkill({ home, env });
+  if (skillAction.changed) actions.push(...skillAction.removed.map((dir) => `removed: ${dir}`));
   // Remove only the dsh-crew entry from [mcp_servers], keeping any other
   // MCP servers the user configured.
   const configFile = join(codexHomeDir(home, env), 'config.toml');
@@ -622,9 +606,15 @@ export function installCodex({ home = homedir(), scope, root = ROOT, env = proce
   if (scope !== 'project') {
     const act = writeGlobalCodexMcpServer(home, renderedPath, env);
     actions.push(...act);
-    const policy = installGlobalCodexPolicy({ home, root, env });
-    if (!policy.ok) return { ok: false, actions: [...actions, policy.action] };
-    actions.push(policy.action);
+    // Crew guidance is a skill now, loaded only when the operator asks for it.
+    // Removing the policy block here cleans up what an earlier release put in
+    // the host instruction file; ignoring the result keeps the first install on
+    // a machine that never had one quiet.
+    const droppedPolicy = uninstallGlobalCodexPolicy({ home, env });
+    if (droppedPolicy) actions.push(`removed delegating policy block: ${join(codexHomeDir(home, env), 'AGENTS.md')}`);
+    const skill = installCrewSkill({ home, root, env });
+    if (!skill.ok) return { ok: false, actions: [...actions, `crew skill: ${skill.code}`] };
+    actions.push(...skill.written.map((file) => `skill: ${file}`));
   }
   return { ok: true, actions };
 }

package/src/install/zcode.mjs

@@ -9,6 +9,8 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 
+import { crewSkillFiles, installCrewSkill, readCrewSkill, removeCrewSkill } from './crew-skill.mjs';
+
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const HOST = 'zcode';
 const SERVER = 'dsh-crew';
@@ -103,27 +105,6 @@ function expectedTarget({ root = ROOT } = {}) {
   return resolve(join(root, 'src', 'server.mjs'));
 }
 
-function managedPolicyBlock(root) {
-  const template = readText(join(root, 'zcode', 'AGENTS.md'))?.trim();
-  return template ? `${POLICY_START}\n${template}\n${POLICY_END}` : null;
-}
-
-function installPolicy({ home, root }) {
-  const file = join(home, '.zcode', 'AGENTS.md');
-  const block = managedPolicyBlock(root);
-  if (!block) return { ok: false, code: 'ZCODE_POLICY_TEMPLATE_MISSING' };
-  mkdirSync(dirname(file), { recursive: true });
-  const current = readText(file) ?? '';
-  const escapedStart = POLICY_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const escapedEnd = POLICY_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const managed = new RegExp(`${escapedStart}[\\s\\S]*?${escapedEnd}`, 'm');
-  const next = managed.test(current)
-    ? current.replace(managed, block)
-    : `${current.trimEnd()}${current.trim() ? '\n\n' : ''}${block}\n`;
-  if (next !== current) { backup(file); writeFileSync(file, next); }
-  return { ok: true, file };
-}
-
 function removePolicy({ home }) {
   const file = join(home, '.zcode', 'AGENTS.md');
   const current = readText(file);
@@ -277,7 +258,8 @@ function updateMcp({ home, root }) {
   return { ok: true, changed, config_file: source.file, config_kind: source.kind, target };
 }
 
-export function installZCode({ home = homedir(), root = ROOT } = {}) {
+export function installZCode({ home = homedir(), root = ROOT, env = process.env } = {}) {
+  const actions = [];
   const templates = templateFiles({ home, root });
   const missing = templates.find(({ source }) => !existsSync(source));
   if (missing) return { ok: false, code: 'ZCODE_TEMPLATE_MISSING', source: missing.source };
@@ -287,8 +269,14 @@ export function installZCode({ home = homedir(), root = ROOT } = {}) {
   // failed install is transaction-like and leaves user files untouched.
   const mcp = updateMcp({ home, root });
   if (!mcp.ok) return mcp;
-  const policy = installPolicy({ home, root });
-  if (!policy.ok) return policy;
+  // Crew guidance is a skill now, loaded only when the operator asks for it.
+  // The removal cleans up the policy block an earlier release wrote into the
+  // host instruction file; ignoring its result keeps a first install quiet.
+  const droppedPolicy = removePolicy({ home });
+  if (droppedPolicy) actions.push('policy: removed managed ZCode block');
+  const skill = installCrewSkill({ home, root, env });
+  if (!skill.ok) return { ok: false, code: skill.code, source: skill.source };
+  actions.push(...skill.written.map((file) => `skill: ${file}`));
   const installed = installTemplates({ home, root, priorFiles });
   if (!installed.ok) return installed;
   cleanupPriorMcpSources({ owned: previousOwnership, exceptFile: mcp.config_file });
@@ -303,16 +291,20 @@ export function installZCode({ home = homedir(), root = ROOT } = {}) {
     files: installed.records,
     configFiles: [currentSourceRecord, ...priorSourceRecords],
   });
-  return { ok: true, ...mcp, policy_file: policy.file, files: installed.actions };
+  return { ok: true, ...mcp, skill_files: skill.written, files: installed.actions };
 }
 
-function zcodeComponents({ home = homedir(), root = ROOT } = {}) {
+function zcodeComponents({ home = homedir(), root = ROOT, env = process.env } = {}) {
   const expected = normalizePath(expectedTarget({ root }));
   const source = configSource({ home });
   const configured = serverTarget(source.servers[SERVER]);
   const owned = ownership({ home });
-  const expectedPolicy = managedPolicyBlock(root);
-  const installedPolicy = readText(join(home, '.zcode', 'AGENTS.md'));
+  // The guidance is a skill now; a policy block in the host instruction file is
+  // no longer written and no longer part of readiness.
+  const expectedSkill = readCrewSkill({ root });
+  // A block written by an earlier release still counts as an installed
+  // footprint, so uninstall knows there is something of ours to clean up.
+  const legacyPolicyText = readText(join(home, '.zcode', 'AGENTS.md'));
   const templates = templateFiles({ home, root });
   const templateReady = (entry) => {
     if (!entry) return false;
@@ -335,7 +327,7 @@ function zcodeComponents({ home = homedir(), root = ROOT } = {}) {
   });
   const components = {
     mcp: configured === expected,
-    policy: !!expectedPolicy && typeof installedPolicy === 'string' && installedPolicy.includes(expectedPolicy),
+    skill: expectedSkill !== null && readText(crewSkillFiles({ home, env })[0]) === expectedSkill,
     worker_agent: templateReady(templateBySuffix(join('agents', 'ds-worker.md'))),
     reviewer_agent: templateReady(templateBySuffix(join('agents', 'ds-reviewer.md'))),
     config_prompt: templateReady(templateBySuffix(join('commands', 'dsh-config.md'))),
@@ -345,9 +337,9 @@ function zcodeComponents({ home = homedir(), root = ROOT } = {}) {
       && normalizePath(owned.target) === expected
       && ownershipFilesReady,
   };
-  const policyFootprint = typeof installedPolicy === 'string'
-    && installedPolicy.includes(POLICY_START)
-    && installedPolicy.includes(POLICY_END);
+  const policyFootprint = typeof legacyPolicyText === 'string'
+    && legacyPolicyText.includes(POLICY_START)
+    && legacyPolicyText.includes(POLICY_END);
   const installed = Object.hasOwn(source.servers, SERVER)
     || !!owned
     || policyFootprint
@@ -355,8 +347,8 @@ function zcodeComponents({ home = homedir(), root = ROOT } = {}) {
   return { components, source, expected, configured, owned, installed };
 }
 
-export function zcodeStatus({ home = homedir(), root = ROOT } = {}) {
-  const { components, source, expected, configured, installed } = zcodeComponents({ home, root });
+export function zcodeStatus({ home = homedir(), root = ROOT, env = process.env } = {}) {
+  const { components, source, expected, configured, installed } = zcodeComponents({ home, root, env });
   const missing = Object.entries(components).filter(([, value]) => !value).map(([key]) => key);
   return {
     installed,
@@ -369,7 +361,7 @@ export function zcodeStatus({ home = homedir(), root = ROOT } = {}) {
   };
 }
 
-export function uninstallZCode({ home = homedir() } = {}) {
+export function uninstallZCode({ home = homedir(), env = process.env } = {}) {
   const actions = [];
   const owned = ownership({ home });
   if (owned) {
@@ -381,6 +373,8 @@ export function uninstallZCode({ home = homedir() } = {}) {
     rmSync(OWNERSHIP_FILE({ home }), { force: true });
   }
   if (removePolicy({ home })) actions.push('policy: removed managed ZCode block');
+  const skillAction = removeCrewSkill({ home, env });
+  if (skillAction.changed) actions.push(...skillAction.removed.map((dir) => `removed: ${dir}`));
   const managedFiles = Array.isArray(owned?.files) && owned.files.length
     ? owned.files
     : ['agents/ds-worker.md', 'agents/ds-reviewer.md', 'commands/dsh-config.md', 'commands/dsh-status.md']

package/src/runtime-identity.mjs

@@ -36,7 +36,7 @@ export {
 // included in the identity contract.
 const RUNTIME_ID = randomUUID();
 
-export const RUNTIME_VERSION = '1.6.2';
+export const RUNTIME_VERSION = '1.7.0';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([