dsh-plugin-stardeck 0.20.1

package/lib/index.d.mts

@@ -0,0 +1,534 @@
+import z from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/config.d.ts
+/** Resolved plugin configuration. */
+interface Config {
+  /**
+   * 编制上限: maximum simultaneously active troops per campaign
+   * Default 6.
+   */
+  maxUnits: number;
+  /**
+   * 重试上限: attempts per bounty before it lands in `failed` (below the cap
+   * a failure auto-requeues back onto the board). Default 2.
+   */
+  maxAttempts: number;
+  /**
+   * 外勤小队上限 (v2.0 征召制): maximum concurrently in_progress tasks — each
+   * holds one conscripted commander. Same-workspace tasks always serialize
+   * regardless (the workspace mutex); this caps cross-workspace parallelism.
+   * Default 3.
+   */
+  maxCommanders: number;
+  /**
+   * Absolute path of the global war-state JSON file. Empty resolves to
+   * `$DSH_HOME/warroom-plugin/state.json` (`~/.dsh` when `DSH_HOME` is unset);
+   * task event logs live in a `campaigns/` sibling directory.
+   */
+  statePath: string;
+  /**
+   * War root: parent of all per-task workspaces. Empty resolves to
+   * `<server cwd>/.warroom` — keep it inside the dsh web process's cwd so
+   * the workspace-write sandbox covers troop writes.
+   */
+  warRoot: string;
+  /**
+   * Boot-time override of war mode for headless compositions: `on`/`off`
+   * force at every load; `auto` (default) follows the persisted activation.
+   */
+  active: 'auto' | 'on' | 'off';
+  /**
+   * 演示织换（smoke/playground overlay 专用，缺省 false）：开机时把播种器写进
+   * 事件流的假会话号按 `.demo-sessions.json` manifest 换成宿主真会话——演示板
+   * 上所有「直跳原生会话」的点击才有着落。生产配置绝不开。
+   */
+  demoWeave: boolean;
+  /**
+   * 装配层附加显式开旗（逗号分隔，缺省空）：overlay 自带考题旗用——如 smoke
+   * overlay 开 `staff-auto-close` 让 e2e 考题继续覆盖自动收官机制（该旗默认
+   * OFF——舰长令 2026-09-01 强制人工验收）。env 的 `!name` 仍可压掉它。
+   */
+  extraFeatures: string;
+}
+/** Schemastery configuration validated at plugin load. */
+declare const Config: z<Config>;
+//#endregion
+//#region src/flags.d.ts
+/**
+ * Feature flags (VERIFICATION.md §8.3, P0-3). The closed-loop SOP demands every
+ * new feature ship behind a flag whose OFF state is byte-identical to the
+ * pre-change behavior — so the same regression suite can run flag=on/off and
+ * diff what changed.
+ *
+ * Discipline:
+ * - Flags only ever ENABLE behavior; absence from the env means OFF.
+ * - OFF must equal the old code path exactly — no "off but slightly new".
+ * - A flag graduates (flag deleted, behavior unconditional) only after the
+ *   feature's regression + supervisor thresholds hold (§6 DoD).
+ *
+ * Read once at startup (or per-call in tests) — never hot-reloaded.
+ * @module dsh-plugin-stardeck/flags
+ */
+/** A frozen name → enabled map. Unknown names are simply absent (falsy). */
+type FeatureFlags = Readonly<Record<string, boolean>>;
+declare const FEATURE_FLAGS_ENV = "WARROOM_FEATURES";
+/**
+ * Parse the `WARROOM_FEATURES` environment variable: a comma-separated flag
+ * name list (`WARROOM_FEATURES=thread-paging,button-relay`). Empty/unset →
+ * all flags OFF. Whitespace around names is tolerated; empty segments are
+ * dropped; duplicates collapse.
+ */
+declare function readFeatureFlags(env?: Record<string, string | undefined>): FeatureFlags;
+/** The gate check: false unless the flag was explicitly enabled. */
+declare function featureEnabled(flags: FeatureFlags, name: string): boolean;
+/**
+ * Runtime flag set: DEFAULT_ON 为底，`WARROOM_FEATURES` 覆盖——`name` 显式开
+ * （探针旗如 v5-spike 仍走这里），`!name` 显式关（回归对照/临时熔断用）。
+ * `extra` 是装配层的附加显式开清单（config.extraFeatures，逗号分隔——overlay
+ * 自带考题旗用，免环境变量记忆）；env 的 `!name` 仍可压掉它（env 最后解析）。
+ */
+declare function runtimeFlags(env?: Record<string, string | undefined>, extra?: string): FeatureFlags;
+//#endregion
+//#region src/types.d.ts
+/** A deployed troop, folded from the campaign event log. */
+interface UnitRecord {
+  readonly childId: string;
+  readonly unitName: string;
+  readonly label: string;
+  readonly mission: string;
+  readonly front: string;
+  readonly writes: boolean;
+  readonly deployedAt: string;
+  readonly orders: ReadonlyArray<{
+    ts: string;
+    order: string;
+  }>;
+  lastReport?: string;
+  recalled?: {
+    reason: string;
+    ts: string;
+  };
+  settled?: {
+    stopReason: string;
+    ts: string;
+  };
+}
+/** One commander attempt (执行会话) on a task — the unit the board's
+ * 进行中/已完成/已失败 columns are made of. `sessionId` is the commander's
+ * conversation (claimedBy at claim time); clicking the card opens it. */
+interface AttemptRecord {
+  /** Capability token issued at claim (empty for v0.2 legacy claims). */
+  readonly id: string;
+  /** 1-based attempt number. */
+  readonly n: number;
+  /** The commander session that ran (and still owns) this attempt. */
+  readonly sessionId: string;
+  readonly startedAt: string;
+  endedAt?: string;
+  /** undefined = still live; 'failed' | 'reported' | 'succeeded' once settled. */
+  outcome?: 'failed' | 'reported' | 'succeeded';
+}
+/** Campaign state derived by folding the append-only event log. */
+interface CampaignState {
+  readonly campaignId: string;
+  intent: string;
+  readonly startedAt: string;
+  hqSessionId?: string;
+  title?: string;
+  brief?: string;
+  acceptance?: string;
+  priority?: 'normal' | 'high';
+  /** Bounty rarity (WoW color language); default common. */
+  quality?: QualityTier;
+  /** 前置任务 campaignIds — a bounty unlocks only when all deps are closed. */
+  deps?: readonly string[];
+  /** Daily-quest cron; absent = one-shot bounty. */
+  schedule?: TaskSchedule;
+  /** How many bounty rounds a cron re-trigger has opened (0 = never re-run). */
+  rounds: number;
+  workspacePath?: string;
+  /** V15：工作区绑定形态（投影字段=治 worktree/未分组误判；旧账本无此字段=undefined 走客户端路径启发式）。 */
+  workspaceKind?: 'bound' | 'bound-worktree' | 'instance' | 'auto-worktree' | 'auto-dir';
+  status: TaskStatus;
+  claimedBy?: string;
+  publishedBy?: string;
+  /** V5-R4 (quota-recovery flag): 配额熔断原地暂停位（不改 status/attempt——
+   * 恢复即续作，不烧 maxAttempts 不换令牌）。 */
+  quotaPaused?: boolean;
+  /** Capability token of the CURRENT attempt — stale submits are rejected. */
+  attempt?: {
+    readonly id: string;
+    readonly n: number;
+  };
+  /** Attempts started so far (attempt numbers are 1-based). */
+  attempts: number;
+  /** Every attempt ever started, in order — the board's session cards. */
+  readonly attemptLog: ReadonlyArray<AttemptRecord>;
+  /** Last failure reason (shown while failed / during requeue). */
+  lastError?: string;
+  /** Collected loot (出本掉落) accumulated across submissions. */
+  readonly deliverables: ReadonlyArray<Deliverable>;
+  readonly reports: ReadonlyArray<{
+    ts: string;
+    from: string;
+    text: string;
+    evidence?: SubmissionEvidence;
+  }>;
+  readonly comments: ReadonlyArray<{
+    ts: string;
+    from: string;
+    text: string;
+  }>;
+  /** V4-R2 direct messages (troop-mailbox flag): logged first, delivered marked. */
+  readonly messages: ReadonlyArray<{
+    messageId: string;
+    ts: string;
+    from: string;
+    to: string;
+    text: string;
+    delivered?: boolean;
+  }>;
+  /** V4-R3 intra-task subtask graph (troop-scheduler flag). */
+  readonly subtasks: Map<string, SubtaskRecord>;
+  closedVerdict?: string;
+  plan?: string;
+  readonly units: Map<string, UnitRecord>;
+  /** B1-件⑥：worktree 随链归档释放的账面投影（事件 workspace_released 落 fold）。 */
+  workspaceReleased?: {
+    at: string;
+    path: string;
+    ok: boolean;
+    note?: string;
+  };
+}
+/** One 队内子任务 (V4-R3) — the commander's work breakdown inside a task.
+ * attempt tokens mirror the campaign-level discipline: a stale attemptId on
+ * subtask_updated means ownership changed. `blocked` returns the subtask to
+ * the open pool with its note kept. */
+interface SubtaskRecord {
+  readonly subtaskId: string;
+  readonly title: string;
+  readonly detail?: string;
+  readonly deps: readonly string[];
+  status: 'open' | 'in_progress' | 'completed';
+  claimedBy?: string;
+  claimedAt?: string;
+  updatedAt?: string;
+  /** Capability token of the CURRENT claim. */
+  attempt?: {
+    readonly id: string;
+    readonly n: number;
+  };
+  attempts: number;
+  lastNote?: string;
+  /** V4-R4: owner interrupted but attempt kept (park ≠ revoke). */
+  parked?: boolean;
+}
+/** Task lifecycle on the strategic board. `failed` is a terminal-for-humans
+ * state: retries already exhausted, the 大副 must re-file a new bounty. */
+type TaskStatus = 'draft' | 'published' | 'in_progress' | 'reported' | 'failed' | 'closed';
+/** Bounty quality tier — the WoW rarity color language for task complexity. */
+type QualityTier = 'common' | 'fine' | 'rare' | 'epic' | 'legendary';
+/** KillCredit evidence a commander must attach to war_submit — the system
+ * verifies, troops never self-certify). */
+interface SubmissionEvidence {
+  /** DoD checklist verdicts, one per acceptance item. */
+  readonly checks: ReadonlyArray<{
+    readonly item: string;
+    readonly passed: boolean;
+  }>;
+  /** A test command actually run, with its real exit code. */
+  readonly tests?: {
+    readonly command: string;
+    readonly exitCode: number;
+    readonly passed: number;
+    readonly failed: number;
+  };
+  /** `git diff --stat` style summary line(s). */
+  readonly diffstat?: string;
+  /** Touched file paths. */
+  readonly files?: readonly string[];
+}
+/** A collected loot item shown on the board card (出本掉落). */
+interface Deliverable {
+  readonly kind: 'files' | 'tests' | 'diffstat' | 'note';
+  readonly summary: string;
+  readonly detail?: string;
+  readonly ts: string;
+}
+/** Daily-quest schedule on a bounty. */
+interface TaskSchedule {
+  readonly cron: string;
+  enabled: boolean;
+  nextRunAt?: string;
+  lastTriggeredAt?: string;
+}
+/** The tiny global war state. Task history lives in the append-only event
+ * logs; only this pointer state is a plain JSON file. */
+interface WarGlobalState {
+  version: 2;
+  /** War mode on/off — gates the staff persona and the war_* tool surface. */
+  active: boolean;
+  /** Session id of the 大副部 (the conversation where /war first ran). */
+  hqSessionId?: string;
+  /** The single durable commander child-session id (lazy-spawned on first publish). */
+  commanderChildId?: string;
+  /** V5-R4 (quota-recovery flag): 全局配额熔断标记（flag on 才写）。
+   * 熔断期间停征召停唤醒，在役任务原地 paused——恢复即续作。 */
+  quotaBlocked?: {
+    since: string;
+    code: string;
+  };
+}
+/** Live descendant entry from ctx.subagents.listDescendants (structural slice). */
+interface DescendantFace {
+  readonly kind: string;
+  readonly id: string;
+  readonly activity?: 'running' | 'inactive';
+  readonly mode?: 'one-shot' | 'continuable';
+  readonly label?: string;
+  readonly parentId?: string;
+  readonly depth?: number;
+}
+//#endregion
+//#region src/state.d.ts
+/** The store handle shared across command/tool/dashboard wiring. */
+interface WarStore {
+  get(): WarGlobalState;
+  save(): void;
+}
+//#endregion
+//#region src/relay.d.ts
+/** Structural slice of the harness apiProxy's sessions + workspace domains. */
+interface SessionsApiFace {
+  create(request: {
+    rpcId: string;
+    payload: {
+      workspaceId?: string;
+      cwd?: string;
+    };
+  }): Promise<{
+    result: {
+      ok: true;
+      value: {
+        sessionId: string;
+      };
+    } | {
+      ok: false;
+      error: {
+        code: string;
+        message: string;
+      };
+    };
+  }>;
+  rename(request: {
+    rpcId: string;
+    payload: {
+      sessionId: string;
+      title: string;
+    };
+  }): Promise<{
+    result: {
+      ok: true;
+      value: unknown;
+    } | {
+      ok: false;
+      error: {
+        code: string;
+        message: string;
+      };
+    };
+  }>;
+  prompt(request: {
+    rpcId: string;
+    payload: {
+      sessionId: string;
+      mode: 'queue';
+      content: Array<{
+        type: 'text';
+        text: string;
+      }>;
+    };
+  }): Promise<{
+    result: {
+      ok: true;
+      value: unknown;
+    } | {
+      ok: false;
+      error: {
+        code: string;
+        message: string;
+      };
+    };
+  }>;
+  /** V9.12：演示织换复用既有「演示·」会话用（可选——缺面时退回每次新建）。 */
+  list?(request: {
+    rpcId: string;
+    payload: {
+      cursor?: string;
+    };
+  }): Promise<{
+    result: {
+      ok: true;
+      value: {
+        items: ReadonlyArray<{
+          id: string;
+          title?: string;
+          displayTitle: string;
+        }>;
+      };
+    } | {
+      ok: false;
+      error: {
+        code: string;
+        message: string;
+      };
+    };
+  }>;
+}
+/** Structural slice of the apiProxy workspace domain (registry create is
+ * idempotent over an existing directory). */
+interface WorkspaceApiFace {
+  create(request: {
+    rpcId: string;
+    payload: {
+      path: string;
+    };
+  }): Promise<{
+    result: {
+      ok: true;
+      value: {
+        workspace: {
+          workspaceId: string;
+        };
+      };
+    } | {
+      ok: false;
+      error: {
+        code: string;
+        message: string;
+      };
+    };
+  }>;
+  /** V17 归档：宿主 registry 全局归档集（分组面隐藏；日志与记账保留，无恢复）。 */
+  archiveSession(request: {
+    rpcId: string;
+    payload: {
+      sessionId: string;
+    };
+  }): Promise<{
+    result: {
+      ok: true;
+      value: unknown;
+    } | {
+      ok: false;
+      error: {
+        code: string;
+        message: string;
+      };
+    };
+  }>;
+}
+//#endregion
+//#region src/tools.d.ts
+/** Structural slice of `ctx.subagents` (SubagentRuntime) — the operations warroom uses. */
+interface SubagentsServiceFace {
+  startContinuable(spec: {
+    provider: string;
+    label: string;
+    request: {
+      prompt: ReadonlyArray<{
+        type: 'text';
+        text: string;
+      }>;
+      parent: unknown;
+      persona?: string;
+      toolFilter?: {
+        deny?: string[];
+      };
+      maxDepth?: number;
+      /** Per-child LLM route (V4-R1, behind the troop-llm-routing flag). */
+      agentOptions?: {
+        provider: string;
+        model: string;
+      };
+    };
+    signal: AbortSignal;
+  }): Promise<{
+    childId: string;
+    messageId: string;
+  }>;
+  followup(parent: unknown, childId: string, content: ReadonlyArray<{
+    type: 'text';
+    text: string;
+  }>, options: unknown): Promise<unknown>;
+  interrupt(targetSessionId: string, authority: unknown): void;
+  listDescendants(rootSessionId: string, signal?: AbortSignal): Promise<ReadonlyArray<DescendantFace>>;
+}
+/** Commander conscription operations (v2.0 征召制) implemented by the host
+ * wiring (index.ts): the commander is a top-level session bound to the task
+ * workspace via the host apiProxy (sandbox root + depth 0), gated on
+ * workspace occupancy, global capacity, and a spawn-once-per-task guard. */
+interface CommanderOps {
+  conscript(task: CampaignState, signal: AbortSignal): Promise<{
+    spawned: true;
+    childId: string;
+  } | {
+    spawned: false;
+    reason: string;
+  }>;
+  /** Deliver a notice into one commander session (批注转达). */
+  relayTo(sessionId: string, text: string): Promise<boolean>;
+  /** B1-件⑤ 孤儿 GC：任务终态时清征召器内存表（孤儿/spawned/拒因）并落盘——
+   *  可选面，旧假 commander / 无征召器环境 no-op。 */
+  forget?(taskId: string): void;
+}
+//#endregion
+//#region src/index.d.ts
+declare const name = "warroom-plugin";
+declare const inject: string[];
+/**
+ * The conscriptor (v2.0 征召制): every commander is a TOP-LEVEL session
+ * created via the host apiProxy and bound to the TASK WORKSPACE (registry
+ * workspace.create + sessions.create({workspaceId}) — the
+ * execution-session paradigm). That is what makes the sandbox honest: an
+ * in-process continuable child inherits its PARENT session's write root
+ * (live R8 catch: a warRoot-rooted commander could not write a bound
+ * external workspace), while a session-bound commander roots exactly where
+ * the task lives and sits at delegation depth 0. The 外勤任务简报 prompt carries
+ * the full commander doctrine (no persona field exists on sessions.create).
+ * Gates: spawn-once-per-task, workspace occupancy, global commander cap.
+ * The patrol fuse is the crash-recovery net: stranded published tasks get
+ * ONE relay ping into the 大副部 conversation per plan signature.
+ */
+declare function createConscriptor(deps: {
+  store: WarStore;
+  stateDir: string;
+  warRoot: string;
+  maxUnits: number;
+  maxCommanders: number;
+  maxAttempts: number;
+  subagents: SubagentsServiceFace;
+  /** B1-件⑤ rescue 判据：会话是否有活体 agent（缺席 → rescue 段整体降级为拒因日志）。 */
+  resolveAgent?: (sessionId: string) => unknown;
+  /** B1-件⑤ rescue 通道：宿主 agents.resume({resumeSessionId})（缺席 → 只记拒因不回栏）。 */
+  resumeAgent?: (sessionId: string) => Promise<unknown>;
+}): CommanderOps & {
+  bindRelay(sessions: SessionsApiFace, workspace: WorkspaceApiFace): void;
+  patrolNow(): Promise<void>;
+  snapshot(): {
+    spawned: readonly string[];
+    skips: Readonly<Record<string, string>>;
+  };
+};
+/**
+ * Mount the war room: config, store, roster loader, commander lifecycle,
+ * activation-gated tool surface + staff persona, troop-report capture,
+ * the patrol fuse, the `/war` + `/peace` commands, and (in web
+ * compositions) the strategic board HTTP API.
+ * @param ctx - plugin context (tools + systemPrompt + subagents injected).
+ * @param config - validated plugin configuration.
+ */
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { Config, FEATURE_FLAGS_ENV, apply, createConscriptor, featureEnabled, inject, name, readFeatureFlags, runtimeFlags };