dsh-subagent-profile 0.2.0 → 0.3.0

package/lib/core/profile-provider.mjs

@@ -0,0 +1,241 @@
+// lib/core/profile-provider.mjs — `profile` 子 Agent provider
+// （setup/start/prepareContinuable），从 index.mjs 的
+// `ctx.subagents.registerProvider({...})` 块逐字拆出。仅引用 lib + shims；
+// 无 @deepseek-ai 依赖（shims 是唯一入口）。
+//
+// Injection: every apply-closure / ctx dependency is an explicit parameter —
+//   subagents   the registry this provider is registered into
+//               (subagents.registerProvider is called by the factory),
+//   store       the profile store (getAllowFailOpen for the cost guard),
+//   getEnabled  reads the apply-closure `enabled` flag (start fails loud when
+//               off),
+//   logger      ctx.logger (decision-level child log).
+// The factory returns whatever registerProvider returns (the caller keeps the
+// original `if (typeof disposeProvider === 'function') ctx.effect(...)` shape).
+//
+// start 按预检段（runStartPreflight）/ 结算+取消接线段（wireChildLifecycle）
+// 拆为模块级私有函数；start 内嵌 setup 按 ①-⑦ 步拆 setupChild +
+// restrictChildTools。行为逐字不变。
+
+import { randomUUID } from 'node:crypto';
+import {
+  appendDelegatedPolicyOverrides,
+  assertSubagentMaxDepth,
+  captureDelegatedPolicyOverrides,
+  createUserMessage,
+  readResult,
+  resolveChildAgentOptions,
+  resolveChildDepth,
+} from './shims.mjs';
+import { GUIDANCE_PREFIX } from './pure.mjs';
+import { computeEffectiveAllow } from './intersection.mjs';
+import { resolveWhitelist } from './whitelist.mjs';
+import { assertCostGuard } from './cost-guard.mjs';
+import { DELEGATION_CONTEXT, buildDispatchMeta } from './delegation.mjs';
+
+// --- start 预检段（从 start 拆出）-------------------------------------------------
+
+// start 前置校验：enabled / profile 存在 / 策略捕获 / whitelist /
+// cost guard / 深度断言与 childDepth / childId / swapPreset / meta /
+// agentOptions，一次性返回 start 后续段所需的全部状态。
+async function runStartPreflight(request, deps) {
+  if (!deps.getEnabled()) {
+    throw new Error('dispatch: the subagent-profile plugin is disabled (re-enable it in 设置 → 子 Agent 方案)');
+  }
+  const profile = request.profile;
+  if (profile === undefined) {
+    throw new Error('dispatch: request.profile is missing (the dispatch tool must resolve a profile before starting)');
+  }
+  const parent = request.parent;
+  // 同步捕获委派策略，在首个 await 之前——之后的父会话切换属于父的未来，
+  // 不属于本 child（shipped captureDelegatedPolicyOverrides）。
+  const delegated = captureDelegatedPolicyOverrides(parent);
+  // 权威 preset whitelist 检查（对照运行时名册）。
+  const whitelist = new Set(await resolveWhitelist(parent.ctx.get('agentPresets')));
+  if (typeof profile.preset === 'string' && profile.preset !== 'inherit' && !whitelist.has(profile.preset)) {
+    throw new Error(`dispatch: preset "${profile.preset}" is not in the target-preset whitelist`);
+  }
+  // 权威 cost guard（运行时推导；硬上限始终生效，llm 能力核验由 allowFailOpen 门控）。
+  await assertCostGuard(parent, profile, deps.store.getAllowFailOpen(), deps.logger);
+  // Delegation depth: shipped helpers — assert the cap value, then resolve
+  // the child depth (parent floor + 1) and enforce the cap.
+  assertSubagentMaxDepth(profile.maxDepth);
+  const childDepth = resolveChildDepth(parent, profile.maxDepth);
+  const childId = randomUUID();
+  const parentAgentPresets = parent.ctx.get('agentPresets');
+  const parentComposed = parentAgentPresets !== undefined ? parentAgentPresets.composedPreset(parent.ctx) : undefined;
+  const swapPreset = typeof profile.preset === 'string' && profile.preset !== 'inherit' && profile.preset !== parentComposed;
+  const meta = buildProviderMeta(parent, profile, swapPreset, childDepth);
+  const agentOptions = buildProviderAgentOptions(parent, profile, childDepth);
+  return { parent, profile, delegated, childId, swapPreset, meta, agentOptions };
+}
+
+// agentPreset 仅在存在 preset 名册时记录（否则整体省略）。该 meta 是自定义的
+// ——非 shipped childSessionMeta——因为 swap 记录的是 profile.preset 而非父的
+// composedPreset。纯组装在 lib/core/delegation.mjs：buildDispatchMeta。
+function buildProviderMeta(parent, profile, swapPreset, childDepth) {
+  const parentAgentPresets = parent.ctx.get('agentPresets');
+  const parentComposed = parentAgentPresets !== undefined ? parentAgentPresets.composedPreset(parent.ctx) : undefined;
+  return buildDispatchMeta({
+    cwd: parent.session.header.cwd,
+    hasPresets: parentAgentPresets !== undefined,
+    swapPreset,
+    preset: profile.preset,
+    parentComposed,
+    parentSession: parent.session.header.id,
+    childDepth
+  });
+}
+
+// agentOptions: shipped resolveChildAgentOptions — parent route inherited
+// unless the profile overrides provider/model/maxTokens, stamped with the
+// child's own delegation depth.
+function buildProviderAgentOptions(parent, profile, childDepth) {
+  return resolveChildAgentOptions(parent, {
+    ...(profile.provider !== undefined ? { provider: profile.provider } : {}),
+    ...(profile.model !== undefined ? { model: profile.model } : {}),
+    ...(profile.maxTokens !== undefined ? { maxTokens: profile.maxTokens } : {})
+  }, childDepth);
+}
+
+// start 主体：预检 → 建 child（setup 装配）→ 结算/取消接线，行为逐字不变。
+async function startProvider(request, deps) {
+  const { parent, profile, delegated, childId, swapPreset, meta, agentOptions } = await runStartPreflight(request, deps);
+  if (request.signal !== undefined && request.signal.aborted) {
+    throw new Error('dispatch: subagent request was aborted before child publication');
+  }
+  const handle = await parent.ctx.agents.create({
+    sessionId: childId,
+    meta,
+    agentOptions,
+    signal: request.signal,
+    setup: (childCtx) => setupChild(childCtx, { parent, profile, swapPreset, delegated, request }),
+  });
+  return wireChildLifecycle(handle, request, childId, swapPreset, profile, deps.logger);
+}
+
+// --- start 内嵌 setup(childCtx)：按 ①-⑦ 步装配子 Agent 会话（从 start 拆出）-------
+
+async function setupChild(childCtx, { parent, profile, swapPreset, delegated, request }) {
+  // ① Preset composition: explicit swap mounts the target preset; otherwise
+  // compose from the parent. Rosterless + explicit swap fails loud.
+  const childPresets = childCtx.get('agentPresets');
+  if (swapPreset) {
+    if (childPresets === undefined) {
+      throw new Error('dispatch: cannot swap preset in a rosterless deployment');
+    }
+    await childPresets.mount(childCtx, profile.preset);
+  } else if (childPresets !== undefined) {
+    childPresets.composeFrom(childCtx, parent.ctx);
+  }
+  // ② Tool intersection（safety gate 1，实现见 restrictChildTools）。
+  restrictChildTools(childCtx, parent, profile);
+  // ③ Delegation scope declaration (when systemPrompt is available).
+  const systemPrompt = childCtx.get('systemPrompt');
+  if (systemPrompt !== undefined) {
+    systemPrompt.context({ name: 'subagent:delegation', order: 120, text: DELEGATION_CONTEXT });
+  }
+  // ④ Persona shadow (overrides deployment:persona at order 0). 双防线 prefix.
+  if (profile.persona !== undefined && systemPrompt !== undefined) {
+    systemPrompt.section({
+      name: 'deployment:persona',
+      order: 0,
+      text: profile.persona.length > 0 ? `${GUIDANCE_PREFIX}${profile.persona}` : profile.persona,
+    });
+  }
+  // ⑤ Reasoning-effort injection into every child request.
+  if (profile.reasoningEffort !== undefined) {
+    childCtx.on('agent/request', async (_payload, next) => {
+      const resolved = await next();
+      return { ...resolved, reasoningEffort: profile.reasoningEffort };
+    });
+  }
+  // ⑥ Descriptor append inside the child's first turn.
+  let appended = false;
+  childCtx.on('agent/pre-step', async ({ agent }, next) => {
+    const decision = await next();
+    if (!appended && decision.kind === 'enter') {
+      appended = true;
+      agent.session.append('subagent/descriptor', request.descriptor);
+    }
+    return decision;
+  });
+  // ⑦ Delegation policy appends (shipped helper).
+  appendDelegatedPolicyOverrides(childCtx.agent.session, delegated);
+}
+
+// ② Tool intersection (safety gate 1): parent set ∩ child set, minus
+// run_code, minus deny, then narrowed by allow when present (pure core in
+// lib/core/intersection.mjs: computeEffectiveAllow).
+function restrictChildTools(childCtx, parent, profile) {
+  const parentNames = new Set(parent.ctx.tools.schemas(parent).map((schema) => schema.name));
+  const childNames = childCtx.tools.schemas(childCtx.agent).map((schema) => schema.name);
+  const effective = computeEffectiveAllow(parentNames, childNames, profile.toolFilter);
+  // shipped restrict 不对 allow:[] throw——在此 fail-loud，让空交集显式化
+  // （throw ⇒ setupAndPublish 回滚创建）。
+  if (effective.length === 0) {
+    throw new Error('dispatch: child tool intersection is empty (zero tools)');
+  }
+  // restrict throws on unknown/scope-local/reserved allow sets: wrap
+  // in a clean error and rethrow to trigger creation rollback.
+  try {
+    childCtx.tools.restrict({ allow: effective });
+  } catch (error) {
+    throw new Error(`dispatch: child tool restriction failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+
+// --- 结算 + 取消接线段（从 start 拆出）--------------------------------------------
+
+// 发布后取消接线（drivePublishedRun）：调用方 signal 取消 child，
+// 已取消时 result 闭包跳过 followup。
+function wireChildLifecycle(handle, request, childId, swapPreset, profile, logger) {
+  const child = handle.agent;
+  const boundary = child.session.events.length;
+  const flags = { cancelled: false };
+  const onAbort = () => {
+    flags.cancelled = true;
+    child.cancel({ kind: 'parent' });
+  };
+  const signal = request.signal;
+  if (signal !== undefined) {
+    signal.addEventListener('abort', onAbort, { once: true });
+    if (signal.aborted) onAbort();
+  }
+  const result = (async () => {
+    try {
+      if (!flags.cancelled) {
+        child.followup(createUserMessage({ content: request.prompt, source: { kind: 'user' } }));
+        await child.whenIdle();
+      }
+      const settled = readResult(child, boundary, flags.cancelled);
+      // Decision-level log at result settlement (readResult, before return).
+      logger.info('[dsh-subagent-profile] child:', JSON.stringify({ childId, preset: profile.preset ?? 'inherit', swapPreset, stopReason: settled.stopReason }));
+      return settled;
+    } finally {
+      if (signal !== undefined) signal.removeEventListener('abort', onAbort);
+    }
+  })();
+  return {
+    id: childId,
+    localAgent: child,
+    result,
+    async dispose() {
+      if (signal !== undefined) signal.removeEventListener('abort', onAbort);
+      flags.cancelled = true;
+      const settled = await Promise.allSettled([handle.dispose(), result]);
+      if (settled[0].status === 'rejected') throw settled[0].reason;
+    }
+  };
+}
+
+export function createProfileProvider({ subagents, store, getEnabled, logger }) {
+  const deps = { store, getEnabled, logger };
+  return subagents.registerProvider({
+    name: 'profile',
+    capabilities: { outputSchema: false, depthLimit: true, toolFilter: true, persona: true },
+    inheritsParentContext: false,
+    start: (request) => startProvider(request, deps),
+    prepareContinuable: async () => ({})
+  });
+}

package/lib/core/profiles-store.mjs

@@ -0,0 +1,226 @@
+// lib/core/profiles-store.mjs — profile registry store and enable/disable switch
+// (moved verbatim from index.mjs and refactored into a factory; import-free —
+// node builtins + lib/core/pure.mjs only, no @deepseek-ai dependency).
+//
+// `dshHome()` and `BUILTIN_SEEDS` are module-level exports shared by the
+// factory and by lib/core/http-routes.mjs (the settings HTTP handlers look up seeds). The
+// per-apply store is constructed by `createProfileStore({ dshHome, logger })`,
+// replacing the apply-closure singleton: every apply() call gets its own
+// profiles Map / deletedBuiltins Set / allowFailOpen flag, exactly like the
+// original closure state.
+//
+// 工厂内嵌的 loadProfiles/persistProfiles/loadEnabled/persistEnabled/
+// resolveProfile 按行门抽为模块级函数，per-apply 状态收集进 `state` 对象
+// 注入；返回面与拆分前逐字一致。
+
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { sanitizeProfile } from './pure.mjs';
+
+// Resolve the DSH home directory (env override wins, platform fallback) — the
+// same policy as the dsh-persona-ref bundle: user profiles persist to
+// ~/.dsh/subagent-profiles.json, stable across harness working directories.
+export function dshHome() {
+  const raw = process.env.DSH_HOME;
+  if (typeof raw === 'string' && raw.trim() !== '') {
+    const trimmed = raw.trim();
+    if (trimmed === '~') return homedir();
+    if (trimmed.startsWith('~/') || trimmed.startsWith('~\\')) return join(homedir(), trimmed.slice(2));
+    return trimmed;
+  }
+  return join(homedir(), '.dsh');
+}
+
+// 1. Profile registry (per-instance state; a bundle row is process-level, so
+//    this Map is the singleton store, exactly like the dynamic plugin's).
+//    Builtin seeds carry `builtin: true` so reset/remove can identify them and
+//    a modified builtin stays distinguishable from a pure user profile.
+//    Descriptions are semantic: one-line positioning + when to use, to help
+//    the model choose. reasoningEffort levels verified against the
+//    llm-deepseek adapter (off/high/max; see resolveModel gating on
+//    connection.defaults.thinking — this deployment leaves thinking unset,
+//    so the full set is advertised for deepseek-v4-flash).
+export const BUILTIN_SEEDS = [
+  { id: 'swap-standard', name: '标准编码', description: '切换到 standard 预设的完整编码工具集。当父会话不是 standard、但子任务需要完整编码能力时用。', preset: 'standard', builtin: true },
+  { id: 'researcher', name: '调研检索', description: '关闭深度推理省 token，继承父工具。适合查资料、汇总、背景调研，不适合改代码。', reasoningEffort: 'off', persona: 'You are a research subagent: search, read, and summarize only. Do not modify code or files.', builtin: true }
+];
+
+// --- 模块级 store 函数（从工厂拆出；per-apply 状态经 `state` 注入）---------------
+
+function resolveProfile(profiles, id) {
+  const found = profiles.get(id);
+  if (found === undefined) throw new Error(`dispatch: unknown profile "${id}"`);
+  if (found.enabled === false) throw new Error(`dispatch: profile "${id}" is disabled`);
+  return found;
+}
+
+// Two file shapes: v1 = a bare array; v2 = { version:2,
+// profiles:[...], allowFailOpen:<bool> }. Returns { entries, version } or
+// { entries: undefined } for an unrecognized shape.
+function classifyProfileFile(parsed) {
+  if (Array.isArray(parsed)) return { entries: parsed, version: 1 };
+  if (parsed !== null && typeof parsed === 'object' && Array.isArray(parsed.profiles)) {
+    return { entries: parsed.profiles, version: parsed.version ?? 2 };
+  }
+  return { entries: undefined, version: undefined };
+}
+
+// Per-entry sanitize (strict=false): over-limit fields are dropped (field
+// removed) + warned; an over-length persona is KEPT + warned (never silently
+// truncated). A bad entry is skipped (fail-soft). Returns
+// 'loaded' | 'skipped' | 'deleted' so loadProfiles can keep its counters.
+function applyProfileEntry(raw, profiles, deletedBuiltins, logger) {
+  if (!raw || typeof raw !== 'object' || typeof raw.id !== 'string' || raw.id.length === 0) {
+    logger.warn('[dsh-subagent-profile] skipping malformed profile entry:', raw === null ? String(raw) : typeof raw);
+    return 'skipped';
+  }
+  const { clean, warnings } = sanitizeProfile(raw, { strict: false });
+  for (const warning of warnings) {
+    logger.warn(`[dsh-subagent-profile] profile "${raw.id}" ${warning.field} 被跳过或提示：${warning.reason}`);
+  }
+  if (clean.deleted === true) {
+    if (clean.builtin === true) {
+      profiles.delete(clean.id);
+      deletedBuiltins.add(clean.id);
+    }
+    return 'deleted';
+  }
+  const existing = profiles.get(clean.id);
+  if (existing !== undefined && existing.builtin === true) {
+    profiles.set(clean.id, { ...clean, builtin: true, persisted: true });
+  } else {
+    profiles.set(clean.id, { ...clean, persisted: true });
+  }
+  return 'loaded';
+}
+
+// 1b. User profile persistence. The settings service cannot serve this
+// plugin (its write path hard-requires register(ns, schema) + a schemastery
+// schema), so user profiles are persisted to ~/.dsh/subagent-profiles.json
+// through node:fs — a bundle has node globals, unlike the dynamic-plugin
+// sandbox that needed the optional `fs` service. Loaded once at startup; the
+// add/remove HTTP routes rewrite the file. Persistence is an enhancement, not
+// a hard dependency: any failure only warns and the builtin seeds work.
+function loadProfiles(state, logger) {
+  if (!existsSync(state.profilesFile)) return;
+  try {
+    const parsed = JSON.parse(readFileSync(state.profilesFile, 'utf8'));
+    const { entries, version } = classifyProfileFile(parsed);
+    if (entries === undefined) {
+      logger.warn('[dsh-subagent-profile] persisted profile file has an unrecognized shape; ignoring');
+      return;
+    }
+    if (version !== 2) {
+      // v1 (or an unversioned array): migrate in memory, keep fail-open compat.
+      state.allowFailOpen = true;
+      logger.warn('[dsh-subagent-profile] v1 数据：fail-open 兼容模式');
+    } else {
+      // v2 缺 allowFailOpen 字段时按 fail-open 兼容（显式 false 才关闭）；
+      // 全新部署默认已定：fail-loud（初始 allowFailOpen=false）。
+      state.allowFailOpen = parsed.allowFailOpen !== false;
+    }
+    let loaded = 0;
+    let skipped = 0;
+    for (const raw of entries) {
+      const status = applyProfileEntry(raw, state.profiles, state.deletedBuiltins, logger);
+      if (status === 'loaded') loaded++;
+      else if (status === 'skipped') skipped++;
+    }
+    // Silent success: report how many persisted profiles came in (skipped
+    // when none — a missing/empty file is the normal first boot).
+    if (loaded > 0) logger.info(`[dsh-subagent-profile] loaded ${loaded} persisted profile(s)`);
+    if (skipped > 0) logger.warn(`[dsh-subagent-profile] skipped ${skipped} malformed profile entry(ies)`);
+  } catch (error) {
+    logger.warn('[dsh-subagent-profile] persisted profile load failed:', error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * Persist every `persisted: true` profile plus builtin-delete tombstones.
+ * Atomic write: write `<profilesFile>.tmp` in the same directory,
+ * then `renameSync` over the target (a crash leaves the old file intact, never
+ * a truncated one). Fail-visible: a failure does NOT throw and does NOT
+ * roll back the in-memory `profiles` Map — it returns `{ persisted: false }` so
+ * the caller can signal "已保存但未持久化" while the in-memory state keeps
+ * driving this process. Always writes the v2 envelope shape.
+ */
+function persistProfiles(state, logger) {
+  const entries = [];
+  for (const profile of state.profiles.values()) {
+    if (profile.persisted !== true) continue;
+    const clean = {};
+    for (const [key, value] of Object.entries(profile)) {
+      if (value === undefined || key === 'persisted') continue;
+      clean[key] = value;
+    }
+    entries.push(clean);
+  }
+  for (const id of state.deletedBuiltins) {
+    entries.push({ id, builtin: true, deleted: true });
+  }
+  const payload = { version: 2, profiles: entries, allowFailOpen: state.allowFailOpen };
+  const tmp = `${state.profilesFile}.tmp`;
+  try {
+    writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+    renameSync(tmp, state.profilesFile);
+    return { persisted: true };
+  } catch (error) {
+    // Best-effort cleanup of the partial tmp file (rename never ran).
+    try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    logger.warn('[dsh-subagent-profile] persisted profile write failed:', error instanceof Error ? error.message : String(error));
+    return { persisted: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+// The plugin's enable/disable switch. Persisted beside the profile list so a
+// user can turn the dispatch tool off without uninstalling the bundle. Default
+// is enabled; a missing/unreadable file falls back to enabled.
+function loadEnabled(state) {
+  try {
+    if (existsSync(state.stateFile)) {
+      const parsed = JSON.parse(readFileSync(state.stateFile, 'utf8'));
+      return parsed && parsed.enabled !== false;
+    }
+  } catch {
+    // fall through to enabled
+  }
+  return true;
+}
+
+function persistEnabled(state, enabled) {
+  try {
+    writeFileSync(state.stateFile, JSON.stringify({ enabled }, null, 2), 'utf8');
+  } catch {
+    // best effort — the in-memory state still drives this process
+  }
+}
+
+// Build one store instance. `dshHome` is the already-resolved home directory
+// string (from the exported dshHome()); `logger` is the apply-time ctx.logger.
+// Per-apply state (profiles / deletedBuiltins / paths / allowFailOpen) collects
+// into `state` for the moved module-level functions. The returned surface is
+// identical to the pre-split factory.
+export function createProfileStore({ dshHome, logger }) {
+  const profiles = new Map(BUILTIN_SEEDS.map((p) => [p.id, { ...p }]));
+  const deletedBuiltins = new Set();
+  const state = {
+    profiles,
+    deletedBuiltins,
+    profilesFile: join(dshHome, 'subagent-profiles.json'),
+    stateFile: join(dshHome, 'subagent-profiles.state.json'),
+    allowFailOpen: false,
+  };
+  return {
+    profiles,
+    deletedBuiltins,
+    resolveProfile: (id) => resolveProfile(profiles, id),
+    loadProfiles: () => loadProfiles(state, logger),
+    persistProfiles: () => persistProfiles(state, logger),
+    loadEnabled: () => loadEnabled(state),
+    persistEnabled: (enabled) => persistEnabled(state, enabled),
+    // getAllowFailOpen: the cost guard must read the migration flag at dispatch
+    // time; loadProfiles/persistProfiles own the mutation.
+    getAllowFailOpen: () => state.allowFailOpen,
+  };
+}