@onefl666/dsh-great-plan 0.0.0-stage → 0.6.0

package/lib/host/plan-compaction.js

@@ -0,0 +1,135 @@
+import { EXIT_PLAN_MODE_TOOL, selectPlanCompactionRange } from './plan-range.js';
+
+// The canonical name lives in plan-range.js; re-exported for existing importers.
+export { EXIT_PLAN_MODE_TOOL };
+
+/** The command accepts no arguments; this is its user-visible usage line. */
+export const USAGE = 'Usage: /great-plan-compact (no arguments)';
+
+/**
+ * Stable manual-compaction error codes mapped to user text.
+ *
+ * Every value is user-visible; the Client mirrors each string in
+ * `COMPACT_MESSAGE_KEYS` so it can be localized (cross-side test).
+ */
+export const FAILURES = {
+  busy: 'Compaction is unavailable because another compaction is running.',
+  changed: 'The history selected for compaction changed during the attempt.',
+  summary: 'Compaction could not produce a useful summary.',
+  commit: 'Compaction did not finish cleanly.',
+  persistence: 'Compaction finished, but the session could not be saved.',
+  cancelled: 'Compaction was cancelled.',
+};
+
+/**
+ * Static command failure messages, also mirrored by the Client's
+ * `COMPACT_MESSAGE_KEYS`. Dynamic messages (`...: ${messageOf(error)}`) are
+ * intentionally not listed and fall back to raw English when unmapped.
+ */
+export const MESSAGES = {
+  planStateUnavailable: 'Plan state is unavailable in this composition.',
+  planInactive: 'Plan mode is not active; nothing to compact.',
+  backendUnavailable: 'Compaction is unavailable because no compaction backend is composed.',
+  noReview: 'There is no pending plan review to compact.',
+  empty: 'No compactable history exists before the pending plan.',
+};
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Resolve the composed compaction service for one agent.
+ *
+ * Presets isolate their mounted services, so the agent's preset group owns its
+ * `compaction` instance while the host-plane read only sees globally mounted
+ * compositions. The agent-scoped context is the middle step; the preset
+ * registry is the authoritative source when it exposes the service.
+ *
+ * @param {object | undefined} agent the agent executing the command.
+ * @param {object} [accessors] service readers supplied by the composition.
+ * @param {() => object | undefined} [accessors.getAgentPresets] host-plane preset registry reader.
+ * @param {(agent: object | undefined) => object | undefined} [accessors.getCompaction] host-plane compaction reader.
+ * @returns {object | undefined} the first service that exposes `compactRegion`.
+ */
+export function resolveCompactionService(agent, { getAgentPresets, getCompaction } = {}) {
+  if (agent !== undefined && agent !== null) {
+    // 1. The service mounted in the agent's preset group.
+    try {
+      const scoped = typeof getAgentPresets === 'function'
+        ? getAgentPresets()?.serviceFor?.(agent, 'compaction')
+        : undefined;
+      if (scoped?.compactRegion !== undefined) return scoped;
+    } catch {
+      // An absent or unreadable preset registry falls through.
+    }
+    // 2. The service mounted in the agent's scoped context.
+    try {
+      const scoped = agent?.ctx?.get?.('compaction');
+      if (scoped?.compactRegion !== undefined) return scoped;
+    } catch {
+      // An unreadable scoped context falls through.
+    }
+  }
+  // 3. The host-plane service; a throwing read stays visible to the caller.
+  const fallback = typeof getCompaction === 'function' ? getCompaction(agent) : undefined;
+  return fallback?.compactRegion !== undefined ? fallback : undefined;
+}
+
+export function createCompactCommand({ getProjections, getCompaction, getBalancedAfter, getAgentPresets }) {
+  return {
+    name: 'great-plan-compact',
+    description: 'Compact older plan history before executing (used by Great Plan).',
+    async handler(invocation) {
+      const args = invocation ?? {};
+      const rawInput = typeof args.rawInput === 'string' ? args.rawInput.trim() : '';
+      if (rawInput !== '') return { kind: 'error', text: USAGE };
+      const { agent, signal } = args;
+
+      let plan;
+      try {
+        const projections = getProjections();
+        if (typeof projections?.snapshot !== 'function') return { kind: 'error', text: MESSAGES.planStateUnavailable };
+        plan = projections.snapshot(agent.session, ['plan'])?.values?.plan;
+      } catch (error) {
+        return { kind: 'error', text: `Plan state is unavailable: ${messageOf(error)}` };
+      }
+      if (plan?.active !== true) return { kind: 'error', text: MESSAGES.planInactive };
+
+      let compaction;
+      try {
+        compaction = resolveCompactionService(agent, { getAgentPresets, getCompaction });
+      } catch (error) {
+        return { kind: 'error', text: `Compaction is unavailable: ${messageOf(error)}` };
+      }
+      if (compaction?.compactRegion === undefined) return { kind: 'error', text: MESSAGES.backendUnavailable };
+
+      let balancedAfter;
+      try {
+        balancedAfter = await getBalancedAfter();
+      } catch (error) {
+        return { kind: 'error', text: `Compaction is unavailable because the compaction package could not be loaded: ${messageOf(error)}` };
+      }
+
+      let range;
+      try {
+        range = selectPlanCompactionRange(agent.session, balancedAfter, { planReviewTool: EXIT_PLAN_MODE_TOOL });
+      } catch (error) {
+        return { kind: 'error', text: `Unable to inspect plan history: ${messageOf(error)}` };
+      }
+      if (range.error === 'no-review') return { kind: 'error', text: MESSAGES.noReview };
+      if (range.error === 'empty') return { kind: 'error', text: MESSAGES.empty };
+
+      try {
+        const result = await compaction.compactRegion(range.start, range.end, agent, signal);
+        const items = Array.isArray(result?.shadowedSeqs) ? result.shadowedSeqs.length : 0;
+        const tokens = Number.isFinite(result?.shadowedTokenCount) ? result.shadowedTokenCount : 0;
+        return { kind: 'success', text: `Compacted ${items} history items (~${tokens} tokens).` };
+      } catch (error) {
+        if (signal?.aborted) return { kind: 'error', text: FAILURES.cancelled };
+        const code = typeof error?.code === 'string' ? error.code : undefined;
+        return { kind: 'error', text: Object.hasOwn(FAILURES, code) ? FAILURES[code] : messageOf(error) };
+      }
+    },
+  };
+}

package/lib/host/plan-evidence.js

@@ -0,0 +1,195 @@
+/**
+ * Evidence-first plan handoff prompt section.
+ *
+ * Plan mode already renders the deployment's native `plan:policy` guidance.
+ * This plugin adds one independent section immediately after it, asking the
+ * planner to hand over its investigation together with the plan. It also carries
+ * an optional unlimited-token-budget reminder and a brainstorming paragraph,
+ * each independently switchable from the Settings page. The native policy text
+ * is never replaced or duplicated.
+ */
+
+/** Prompt section name; unique in the global prompt layer. */
+export const PLAN_EVIDENCE_SECTION = 'great-plan:plan-evidence';
+
+/** Used when the instance cannot resolve the centrally owned PLAN_POLICY order. */
+export const PLAN_EVIDENCE_ORDER_FALLBACK = 501;
+
+/** Model-facing collaborative-discovery and Team-Lead guidance; the Settings page can switch it off. */
+export const PLAN_BRAINSTORMING_GUIDANCE = `Discovery and delegation:
+- Assess the goal, success criteria, constraints, and current state; do not quiz the user with a checklist.
+- If an answer could materially change scope or approach, ask one concise question per turn and wait. If the request is clear or the user delegates the choice, proceed.
+- You are the Team Lead. Use \`spawn_teammate\` to start at least 2 exploration teammates in parallel, each with one distinct, concrete scope, and require concise findings cited as path:line-range. Do not investigate their scopes yourself; collect all results and resolve conflicts.
+- Then spawn 1 separate planning teammate to draft a candidate plan from the consolidated evidence. Verify the evidence and the draft yourself before submitting.
+- If \`spawn_teammate\` is unavailable or fails, say so in the plan and continue alone; never invent teammate work.
+- Show alternatives and tradeoffs only when they help the user decide; state the key reason for your recommendation.
+- Separate user requirements from your recommendations, assumptions, and unverified points. Give a brief rationale, not step-by-step chain-of-thought.`;
+
+/** Model-facing unlimited-token-budget reminder; the Settings page can switch it off. */
+export const PLAN_UNLIMITED_BUDGET_GUIDANCE = 'Token budget: unlimited. Never cut investigation, tool calls, or needed questions to save tokens; keep the final plan concise.';
+
+/** Model-facing evidence and executor handoff guidance; always rendered in plan mode. */
+export const PLAN_HANDOFF_GUIDANCE = `Plan as handoff (the executor may get only this plan or a compacted history, so make it self-contained):
+- Background: request, current behavior, constraints, assumptions.
+- Evidence: files/symbols with line ranges (e.g. path/file.js:12-30), searches and commands with key results, docs/skills/URLs used, and how conflicts were resolved. Cite evidence for each design claim; mark anything unverified as an assumption or open question.
+- Handoff: what is settled and must not be re-investigated; which unknowns to verify first.
+Never present a guess as fact or invent paths, APIs, command output, or test results. Re-check citations before submitting. Keep evidence compact: precise pointers, not raw logs or whole files.`;
+
+/** Default guidance (every switch on) appended while plan mode is active. */
+export const PLAN_EVIDENCE_GUIDANCE = `${PLAN_UNLIMITED_BUDGET_GUIDANCE}\n\n${PLAN_BRAINSTORMING_GUIDANCE}\n\n${PLAN_HANDOFF_GUIDANCE}`;
+
+/**
+ * Compose the plan-mode guidance from its independently switchable parts.
+ *
+ * The budget reminder comes first as a general instruction, then the optional
+ * brainstorming guidance, and the evidence/handoff guidance always closes the
+ * section. Disabled parts are omitted entirely, never replaced by placeholders.
+ * With every switch on the precomputed `PLAN_EVIDENCE_GUIDANCE` constant is
+ * returned so the common path allocates nothing per prompt assembly.
+ */
+export function composePlanGuidance({ brainstorming = true, unlimitedBudget = true } = {}) {
+  if (brainstorming !== false && unlimitedBudget !== false) return PLAN_EVIDENCE_GUIDANCE;
+  const parts = [];
+  if (unlimitedBudget !== false) parts.push(PLAN_UNLIMITED_BUDGET_GUIDANCE);
+  if (brainstorming !== false) parts.push(PLAN_BRAINSTORMING_GUIDANCE);
+  parts.push(PLAN_HANDOFF_GUIDANCE);
+  return parts.join('\n\n');
+}
+
+/**
+ * Read one switch from the plugin config.
+ *
+ * A volatile field arrives as a reference object; plain booleans are accepted
+ * for tests and hand-written rows. Every missing, malformed, or unreadable
+ * value keeps the fallback so prompt assembly never fails.
+ */
+function readConfigSwitch(config, field, fallback) {
+  if (config === undefined || config === null || typeof config !== 'object') return fallback;
+  let value;
+  try {
+    value = config[field];
+  } catch {
+    return fallback;
+  }
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === 'boolean') return value;
+  if (typeof value.get === 'function') {
+    try {
+      const live = value.get();
+      return typeof live === 'boolean' ? live : fallback;
+    } catch {
+      return fallback;
+    }
+  }
+  return fallback;
+}
+
+/** Read the brainstorming switch; defaults to enabled. */
+export function readBrainstormingEnabled(config) {
+  return readConfigSwitch(config, 'injectBrainstormingPrompt', true);
+}
+
+/** Read the unlimited-token-budget switch; defaults to enabled. */
+export function readUnlimitedBudgetEnabled(config) {
+  return readConfigSwitch(config, 'injectUnlimitedBudgetPrompt', true);
+}
+
+/**
+ * Resolve one boolean-validated plan-mode state from a planMode-like service.
+ *
+ * A usable state exposes a boolean `active`; a pending selection overrides the
+ * logged state. Missing, malformed, or throwing reads return `undefined` so the
+ * caller can try its next source.
+ */
+function readPlanModeState(readService, agent) {
+  try {
+    const service = readService();
+    if (service === undefined || service === null || typeof service.get !== 'function') return undefined;
+    const state = service.get(agent);
+    if (state !== undefined && state !== null && typeof state === 'object' && typeof state.active === 'boolean') {
+      return state.pending === undefined ? state.active : state.pending === true;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Decide whether plan mode is active for the step being assembled.
+ *
+ * The Host plane cannot rely on its own `planMode` instance: agent presets
+ * commonly mount the plan-mode plugin in an isolated group, so the host-plane
+ * instance does not see the state that the preset drives. The agent's own
+ * scoped context (`agent.ctx`) carries the instance that owns the session's
+ * plan state and the pending selection's direction — the same data source the
+ * native `plan:policy` section reads. The host-plane instance is the fallback
+ * for compositions where plan mode is host-owned, and the shared `plan`
+ * session projection (the unit the compaction command also reads) is the final
+ * synchronous fallback. Every source degrades to inactive instead of throwing.
+ */
+export function readPlanModeActive(agent, getPlanMode, getSessionProjections) {
+  if (agent === undefined || agent === null) return false;
+  // 1. The agent-scoped planMode instance: `get()` returns the logged state
+  //    plus a pending selection whose boolean is the selected direction.
+  const scoped = readPlanModeState(() => agent.ctx?.get?.('planMode'), agent);
+  if (scoped !== undefined) return scoped;
+  // 2. The host-plane planMode instance.
+  const host = readPlanModeState(() => (typeof getPlanMode === 'function' ? getPlanMode() : undefined), agent);
+  if (host !== undefined) return host;
+  // 3. The shared `plan` projection's cropped view { active, pending }. The
+  //    pending direction is not exposed here, so a pending selection counts as
+  //    active; by assembly time the pre-step has already applied pending
+  //    selections, which makes this equivalent to the native section's gate.
+  try {
+    const projections = typeof getSessionProjections === 'function' ? getSessionProjections() : undefined;
+    const session = agent?.session;
+    if (projections !== undefined && projections !== null && session !== undefined && typeof projections.snapshot === 'function') {
+      const state = projections.snapshot(session, ['plan'])?.values?.plan;
+      if (state !== undefined && state !== null && typeof state === 'object' && typeof state.active === 'boolean') {
+        return state.active === true || state.pending === true;
+      }
+    }
+  } catch {
+    // No usable plan state anywhere; treat the step as outside plan mode.
+  }
+  return false;
+}
+
+/**
+ * Register the section right after the native plan policy.
+ *
+ * @param {object} options
+ * @param {object} options.systemPrompt the Host `systemPrompt` service.
+ * @param {() => object | undefined} options.getPlanMode optional host-plane `planMode` reader.
+ * @param {() => object | undefined} [options.getSessionProjections] optional projection service reader.
+ * @param {() => object | undefined} options.getConfig optional live plugin config reader.
+ */
+export function registerPlanEvidenceSection({ systemPrompt, getPlanMode, getSessionProjections, getConfig }) {
+  let order = PLAN_EVIDENCE_ORDER_FALLBACK;
+  try {
+    const resolved = typeof systemPrompt.getSectionOrder === 'function'
+      ? systemPrompt.getSectionOrder('PLAN_POLICY')
+      : undefined;
+    if (Number.isFinite(resolved)) order = resolved + 1;
+  } catch {
+    // Keep the fallback order; an unavailable central table must not break the plugin.
+  }
+  return systemPrompt.section({
+    name: PLAN_EVIDENCE_SECTION,
+    order,
+    text: (context) => {
+      let config;
+      try {
+        config = typeof getConfig === 'function' ? getConfig() : undefined;
+      } catch {
+        config = undefined;
+      }
+      if (!readPlanModeActive(context?.agent, getPlanMode, getSessionProjections)) return '';
+      return composePlanGuidance({
+        brainstorming: readBrainstormingEnabled(config),
+        unlimitedBudget: readUnlimitedBudgetEnabled(config),
+      });
+    },
+  });
+}

package/lib/host/plan-range.js

@@ -0,0 +1,35 @@
+/** The plan-review tool call that marks the pending plan review surface node. */
+export const EXIT_PLAN_MODE_TOOL = 'exit_plan_mode';
+
+/**
+ * Pure plan-compaction range selection.
+ *
+ * The pending plan review is the last surface node: an assistant message
+ * carrying the plan-review tool call (`exit_plan_mode`). The compactable range
+ * starts right after the leading system messages and ends at the last balanced
+ * node before that review, snapping backwards until the tool pairing holds.
+ */
+export function selectPlanCompactionRange(session, balancedAfter, options = {}) {
+  const planReviewTool = typeof options.planReviewTool === 'string'
+    ? options.planReviewTool
+    : EXIT_PLAN_MODE_TOOL;
+  const nodes = session.surface.nodes;
+  if (nodes.length === 0) return { error: 'empty' };
+  const last = session.eventAt(nodes[nodes.length - 1]);
+  if (last?.type !== 'assistant/message') return { error: 'no-review' };
+  const content = last.data?.message?.content;
+  if (!Array.isArray(content) || !content.some((block) => block?.type === 'tool-call' && block.name === planReviewTool)) {
+    return { error: 'no-review' };
+  }
+
+  let startIndex = 0;
+  while (startIndex < nodes.length && session.eventAt(nodes[startIndex])?.type === 'system/message') startIndex += 1;
+
+  let endIndex = nodes.length - 2;
+  while (endIndex >= startIndex) {
+    if (balancedAfter(session, nodes[endIndex]) === true) break;
+    endIndex -= 1;
+  }
+  if (endIndex < startIndex) return { error: 'empty' };
+  return { start: nodes[startIndex], end: nodes[endIndex] };
+}

package/lib/index.js

@@ -0,0 +1,2 @@
+export { Config } from './host/config.js';
+export { apply } from './host/apply.js';

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Great Plan",
+    "description": "Choose the model and reasoning effort, then execute a reviewed plan in place, after compaction, or in a fresh session with the original instructions and runtime context."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "卓越计划",
+    "description": "在执行计划前选择模型与思考强度，并支持直接执行、压缩上下文后执行，或在新会话中携带原始指令与运行环境执行。"
+  }
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@onefl666/dsh-great-plan",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0",
+  "license": "MIT",
+  "author": "onefl666",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "dsh-bundle",
+    "plan-mode",
+    "agent",
+    "web-client"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/onefl666/dsh-great-plan#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onefl666/dsh-great-plan.git"
+  },
+  "bugs": {
+    "url": "https://github.com/onefl666/dsh-great-plan/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "description": "Choose the model and reasoning effort, then execute, compact-and-execute, or start fresh with a reviewed plan.",
+  "icon": "./icon.svg",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/host/*.js",
+    "lib/client.js",
+    "lib/client.*.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-compaction": "^0.2.1-rc.3",
+    "@deepseek-ai/schemastery": "~3.18.5"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-user-questions",
+        "@deepseek-ai/dsh-client-ui-model-selection",
+        "@deepseek-ai/dsh-client-ui-workspace",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-general",
+        "@deepseek-ai/dsh-client-locale"
+      ]
+    }
+  }
+}