@xzzpig/pi-openspec-x 0.1.0

package/src/index.ts

@@ -0,0 +1,173 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { loadOpsxConfig, type OpsxConfig } from "./config.ts";
+import {
+  createOpsxAgentsSessionStartHandler,
+  registerOpsxAgents,
+} from "./agents.ts";
+import {
+  probeGoalXDependency,
+  probeSandboxDependency,
+  probeSubagentsDependency,
+  noteSandboxUnavailable,
+  describeError,
+  requireGoalXSupport,
+} from "./dependencies.ts";
+import { createResourcesDiscoverHandler } from "./discover.ts";
+import { createOpsxRecoverySessionStartHandler } from "./goal-base.ts";
+import {
+  registerOpsxAuditorResolver,
+  buildOpsxAuditorOverride,
+} from "./final-gate.ts";
+import {
+  registerFlowRenderers,
+  createStatusSnapshotTurnEndHandler,
+  type OpsxFlowState,
+} from "./flow-entries.ts";
+import {
+  registerImplementFlow,
+  activeImplementFlow,
+} from "./implement-command.ts";
+import { createOpsxSessionStartHandler } from "./mode.ts";
+import { registerPlanFlow, activePlanSession } from "./plan-command.ts";
+import { registerRollbackFlow } from "./rollback-command.ts";
+import { registerPlanGateTools } from "./plan-gate.ts";
+import { registerProgressObserver } from "./progress-observer.ts";
+import { registerReportTools } from "./report-tools.ts";
+import { buildSandboxProfiles } from "./sandbox-profiles.ts";
+
+// Read once at extension load (merge semantics in loadOpsxConfig).
+const config: OpsxConfig = loadOpsxConfig();
+
+/**
+ * pi-openspec-x extension entry point.
+ *
+ * pi-sandbox is probed lazily through a dynamic import (dependencies.ts): on
+ * success the three opsx sandbox profiles (D4: opsx-planner / opsx-agent /
+ * opsx-reviewer) are registered into pi-sandbox's runtime registry — in-memory
+ * for the session lifetime, never written to a user's sandbox.json, a
+ * user-defined same-name profile always keeping priority. On failure the
+ * reason is recorded as dependency state and the extension continues: the
+ * official-track skills and every other capability keep working, and a later
+ * request for a restricted mode is refused with a typed
+ * OpsxDependencyMissingError (fail-closed) instead of the extension (or the
+ * official track) dying at load time.
+ *
+ * Registers the resources_discover handler, which:
+ * - generates (and caches, keyed by CLI version) the official-track
+ *   openspec-* skills under `<agentDir>/cache/pi-openspec-x/skills/` and
+ *   exposes the directory to pi via `skillPaths`;
+ * - warns once per project when static `<cwd>/.pi/skills/openspec-*`
+ *   directories collide with the generated skills.
+ *
+ * Registers the session_start handler that clears a stale `active_agent`
+ * identity left in the session file by an earlier session (pi-agent-role's
+ * semantics; see mode.ts).
+ *
+ * Registers the three child reporting tools (report_gap_analysis,
+ * report_plan_review, report_work) that the opsx subagents submit their
+ * structured results through.
+ *
+ * pi-subagents is probed the same lazy way: on success the four opsx
+ * subagents (opsx-gap-analysis / opsx-plan-review / opsx-worker / opsx-reviewer) are
+ * registered into pi-subagents' runtime registry via the owner's event bus
+ * (D3). A missing pi-subagents costs only the enhanced flow's subagents —
+ * the official track and direct main-session implementation are unaffected.
+ * Because the owner listener only exists once pi-subagents has loaded (load
+ * order between extensions is not guaranteed), a failed init-time attempt is
+ * retried on session_start.
+ *
+ * Missing openspec CLI: no skills are registered and no error escapes — a
+ * one-time notice is sent instead.
+ */
+export default async function piOpenspecX(pi: ExtensionAPI): Promise<void> {
+  const probe = await probeSandboxDependency();
+  if (probe.module) {
+    try {
+      probe.module.registerSandboxProfiles(buildSandboxProfiles(config));
+    } catch (error) {
+      // Invalid profile definitions are recorded like any other sandbox
+      // failure: the official track keeps working, restricted modes are
+      // refused with the actual reason.
+      noteSandboxUnavailable(
+        `registering the opsx sandbox profiles failed: ${describeError(error)}`,
+      );
+    }
+  }
+
+  registerReportTools(pi);
+  // Parent-side projection of the subagents' structured progress (task 9.2).
+  registerProgressObserver(pi);
+  // Progress lines for the flow entries (task 9.1).
+  registerFlowRenderers(pi);
+  // `/opsx:plan`: planner mode + append-only phase injection (task 7.1).
+  registerPlanFlow(pi);
+  // REJECT rollback with backup (spec: REJECT 回滚带备份).
+  registerRollbackFlow(pi);
+  // Parent-side plan gate tools: ledger recording + user approval (7.2/7.3).
+  registerPlanGateTools(pi);
+  // `/opsx:implement`: mode selection + goal-based implementation (task 8.1).
+  registerImplementFlow(pi);
+
+  await probeSubagentsDependency();
+  // Record goal-x availability for the /opsx:implement fail-closed gate
+  // (task 6.6). A missing/incompatible goal-x never blocks extension load.
+  const goalXProbe = await probeGoalXDependency();
+  if (goalXProbe.available) {
+    // S2 seam: make the custom opsx-reviewer visible to goal-x's completion
+    // audit preflight for the whole session (task 8.3). Ordinary goals never
+    // resolve through this resolver (it only answers "opsx-reviewer").
+    registerOpsxAuditorResolver(goalXProbe.module);
+  }
+  registerOpsxAgents(pi);
+  const disposeAgentsSessionStart = pi.on(
+    "session_start",
+    createOpsxAgentsSessionStartHandler(pi),
+  );
+
+  const disposeResourcesDiscover = pi.on(
+    "resources_discover",
+    createResourcesDiscoverHandler(pi),
+  );
+  const disposeSessionStart = pi.on(
+    "session_start",
+    createOpsxSessionStartHandler(pi),
+  );
+  // Read-only recovery entry: if the goal base holds an unfinished opsx
+  // implementation goal, point the user at goal-x's /goal-resume (task 6.4).
+  const disposeRecoverySessionStart = pi.on(
+    "session_start",
+    createOpsxRecoverySessionStartHandler(pi, {
+      // The S1 override is in-memory; re-install it (task 8.3).
+      installAuditor: (goalId) => {
+        requireGoalXSupport().setGoalAuditorOverride(goalId, {
+          ...buildOpsxAuditorOverride(),
+        });
+      },
+    }),
+  );
+  // Per-turn status snapshot (custom entry; survives compaction) — task 9.1.
+  const disposeStatusSnapshot = pi.on(
+    "turn_end",
+    createStatusSnapshotTurnEndHandler(
+      pi,
+      (sessionId): OpsxFlowState | undefined => {
+        const plan = activePlanSession(sessionId);
+        if (plan) return { mode: "plan", changeId: plan.changeId };
+        const impl = activeImplementFlow(sessionId);
+        if (impl)
+          return {
+            mode: impl.mode,
+            changeId: impl.changeId,
+            phase: impl.phase,
+          };
+        return undefined;
+      },
+    ),
+  );
+  void disposeAgentsSessionStart;
+  void disposeResourcesDiscover;
+  void disposeSessionStart;
+  void disposeRecoverySessionStart;
+  void disposeStatusSnapshot;
+}

package/src/lifecycle.ts

@@ -0,0 +1,156 @@
+/**
+ * Lifecycle bus events and the pi-notify bridge (design D9; openspec change
+ * add-pi-openspec-x, tasks 9.3 and 9.4).
+ *
+ * Every key flow node publishes one versioned lifecycle event on the single
+ * channel `pi-openspec-x:lifecycle:v1` (payload carries the change id and a
+ * structured `type`), so third parties — for example pi-sentinel's `event:`
+ * trigger — can subscribe declaratively.
+ *
+ * pi-notify is bridged by LITERAL channel name, never by importing the package:
+ * `pi-notify:publish` carries `{ eventId, source, label? }`, and a silent UI
+ * span is claimed with `pi-notify:ui_span_silent` before a blocking dialog
+ * opens. When pi-notify is absent the emits are harmless no-ops on a bus with
+ * no listener; nothing here throws or depends on the package.
+ */
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+
+/** The one versioned lifecycle channel. */
+export const OPSX_LIFECYCLE_CHANNEL = "pi-openspec-x:lifecycle:v1";
+
+/** pi-notify's publish channel (literal; no import). */
+export const PI_NOTIFY_PUBLISH_CHANNEL = "pi-notify:publish";
+/** pi-notify's silent-UI-span channel (literal; no import). */
+export const PI_NOTIFY_UI_SPAN_SILENT_CHANNEL = "pi-notify:ui_span_silent";
+/** The source name every pi-notify payload carries. */
+export const PI_NOTIFY_SOURCE = "pi-openspec-x";
+
+export type OpsxLifecycleEventType =
+  | "plan_started"
+  | "phase_changed"
+  | "review_verdict"
+  | "approval_wait"
+  | "plan_approved"
+  | "implement_started"
+  | "task_dispatched"
+  | "task_completed"
+  | "final_verdict"
+  | "flow_completed"
+  | "mode_exited";
+
+/** The structured lifecycle payload consumers can rely on. */
+export interface OpsxLifecyclePayload {
+  version: 1;
+  type: OpsxLifecycleEventType;
+  /** The openspec change this flow belongs to. */
+  change: string;
+  /** ISO timestamp. */
+  at: string;
+  mode?: "plan" | "agent" | "direct";
+  phase?: string;
+  round?: number;
+  verdict?: string;
+  taskId?: string;
+  message?: string;
+}
+
+export type OpsxLifecycleInput = Omit<
+  OpsxLifecyclePayload,
+  "version" | "at"
+> & {
+  at?: string;
+};
+
+/** Minimal bus view; the real `pi.events` EventBus satisfies it. */
+export type EventEmitterLike = Pick<EventBus, "emit">;
+
+/**
+ * Publish one lifecycle event. A throwing bus never breaks the flow: the
+ * payload is still returned for tests and local logging.
+ */
+export function publishLifecycle(
+  events: EventEmitterLike,
+  input: OpsxLifecycleInput,
+): OpsxLifecyclePayload {
+  const payload: OpsxLifecyclePayload = {
+    version: 1,
+    ...input,
+    at: input.at ?? new Date().toISOString(),
+  };
+  try {
+    events.emit(OPSX_LIFECYCLE_CHANNEL, payload);
+  } catch {
+    // Observability is best-effort.
+  }
+  return payload;
+}
+
+/** pi-notify's notification event ids this plugin uses. */
+export type PiNotifyEventId =
+  | "input-required"
+  | "task-completed"
+  | "integration-error";
+
+export interface PiNotifyPayload {
+  eventId: PiNotifyEventId;
+  source: string;
+  label?: string;
+}
+
+/**
+ * Publish one pi-notify notification. Returns the payload; a missing
+ * pi-notify simply means no listener sees it.
+ */
+export function publishNotify(
+  events: EventEmitterLike,
+  input: { eventId: PiNotifyEventId; label?: string },
+): PiNotifyPayload {
+  const payload: PiNotifyPayload = {
+    eventId: input.eventId,
+    source: PI_NOTIFY_SOURCE,
+    ...(input.label ? { label: input.label } : {}),
+  };
+  try {
+    events.emit(PI_NOTIFY_PUBLISH_CHANNEL, payload);
+  } catch {
+    // Best-effort.
+  }
+  return payload;
+}
+
+/**
+ * Claim the next UI span as silent before opening a blocking dialog that is
+ * not an agent-waiting prompt.
+ */
+export function emitSilentUiSpan(
+  events: EventEmitterLike,
+  reason?: string,
+): void {
+  try {
+    events.emit(PI_NOTIFY_UI_SPAN_SILENT_CHANNEL, reason ? { reason } : {});
+  } catch {
+    // Best-effort.
+  }
+}
+
+/** The flow nodes that map onto a pi-notify event id. */
+export const NOTIFY_NODE_EVENT_ID: Record<
+  "approval_wait" | "flow_completed" | "gate_error",
+  PiNotifyEventId
+> = {
+  approval_wait: "input-required",
+  flow_completed: "task-completed",
+  gate_error: "integration-error",
+};
+
+/** Publish the pi-notify notification for a flow node. */
+export function notifyFlowNode(
+  events: EventEmitterLike,
+  node: keyof typeof NOTIFY_NODE_EVENT_ID,
+  label?: string,
+): PiNotifyPayload {
+  return publishNotify(events, {
+    eventId: NOTIFY_NODE_EVENT_ID[node],
+    ...(label ? { label } : {}),
+  });
+}

package/src/mode.ts

@@ -0,0 +1,285 @@
+/**
+ * Restricted-mode activation channel for pi-openspec-x (design D4).
+ *
+ * Entering a restricted mode writes the same session-entry channel
+ * pi-agent-role owns — the `active_agent` custom entry, byte-identical in
+ * shape — so pi-permission-system resolves the identity without knowing about
+ * this package. The sharing is one-way at the channel level only: `/role`'s
+ * agent enumeration lists configured agents, not runtime agents (verified in
+ * the 5.3 investigation), so an opsx mode never appears in its menu. Adopt,
+ * inspect, or clear an opsx mode through the opsx commands; only the entry
+ * shape, not the `/role` surface, is shared:
+ *
+ * 1. the `active_agent` session identity entry, byte-identical in shape to
+ *    pi-agent-role's (`{ name: string | null }`);
+ * 2. pi-sandbox's per-session `SandboxService.setProfile` with the matching
+ *    opsx profile.
+ *
+ * Stale-entry cleanup on `session_start` copies pi-agent-role's semantics
+ * verbatim (see `clearStaleActiveAgentIdentity`): entries are deliberately
+ * indistinguishable across the two packages, and a session start means the
+ * selection that produced any persisted identity no longer exists.
+ *
+ * Fail-closed asymmetry: entering throws a typed
+ * {@link OpsxDependencyMissingError} when pi-sandbox is unavailable — a
+ * restricted mode must never run unsandboxed. Leaving never throws for a
+ * missing dependency: exiting only removes restrictions, so it must always
+ * be possible and is reported as an outcome instead.
+ */
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionHandler,
+  SessionStartEvent,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+  describeError,
+  loadSessionSandboxService,
+  OpsxDependencyMissingError,
+  requireRestrictedModeSupport,
+  SANDBOX_MISSING_CONSEQUENCE,
+  type SandboxServiceLike,
+} from "./dependencies.ts";
+
+/**
+ * Entry type pi-permission-system resolves into an agent identity; the exact
+ * contract pi-agent-role broadcasts on (broadcast.ts ACTIVE_AGENT_ENTRY_TYPE).
+ */
+export const ACTIVE_AGENT_ENTRY_TYPE = "active_agent";
+
+/** Restricted modes available to the opsx workflow (each maps 1:1 to a profile). */
+export type OpsxMode = "planner" | "agent";
+
+/**
+ * Identity (active_agent name) and sandbox profile per restricted mode. The
+ * names equal the registered profile names so /role interop and pi-sandbox
+ * resolve the same string.
+ */
+const MODE_IDS: Record<
+  OpsxMode,
+  { agentName: string; sandboxProfile: string }
+> = {
+  planner: { agentName: "opsx-planner", sandboxProfile: "opsx-planner" },
+  agent: { agentName: "opsx-agent", sandboxProfile: "opsx-agent" },
+};
+
+export interface OpsxModeNotice {
+  message: string;
+  severity: "warning" | "error";
+}
+
+export interface OpsxModeOutcome {
+  /** True when no channel reported an error. */
+  ok: boolean;
+  notices: OpsxModeNotice[];
+}
+
+export interface OpsxModeDeps {
+  /**
+   * Session id provider, defaulting to none (pi-sandbox then resolves the
+   * service only when exactly one session published one). Command handlers
+   * pass `() => ctx.sessionManager.getSessionId()`.
+   */
+  sessionId?: () => string | undefined;
+  /** Injectable service locator (tests); defaults to the recorded pi-sandbox module. */
+  loadService?: (
+    sessionId: string | undefined,
+  ) => Promise<SandboxServiceLike | undefined>;
+}
+
+function defaultLoadService(
+  sessionId: string | undefined,
+): Promise<SandboxServiceLike | undefined> {
+  return loadSessionSandboxService(sessionId);
+}
+
+function resolveSessionId(deps: OpsxModeDeps): string | undefined {
+  try {
+    return deps.sessionId?.();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Enter a restricted mode: apply the sandbox profile first, then record the
+ * `active_agent` identity. All-or-nothing — on any failure nothing (or
+ * nothing observable) is applied and the session stays unrestricted:
+ *
+ * - dependency missing → typed {@link OpsxDependencyMissingError}, nothing done;
+ * - profile rejected by pi-sandbox → error, no identity entry written;
+ * - identity entry write fails → the profile is rolled back before throwing.
+ *
+ * A succeeded selection that carries a message (pi-sandbox warns when the
+ * sandbox switch is currently off) is returned as a warning notice: the mode
+ * is recorded, and the caller must surface that isolation is not active.
+ */
+export async function enterOpsxMode(
+  pi: ExtensionAPI,
+  mode: OpsxMode,
+  deps: OpsxModeDeps = {},
+): Promise<OpsxModeOutcome> {
+  const { agentName, sandboxProfile } = MODE_IDS[mode];
+  // Fail-closed gate first: no identity entry may claim a mode whose sandbox
+  // cannot back it.
+  requireRestrictedModeSupport();
+
+  const service = await (deps.loadService ?? defaultLoadService)(
+    resolveSessionId(deps),
+  );
+  if (!service) {
+    throw new OpsxDependencyMissingError(
+      "pi-sandbox session service",
+      "no sandbox service is published for this session (pi-sandbox not loaded, or its session_start has not run)",
+      SANDBOX_MISSING_CONSEQUENCE,
+    );
+  }
+
+  // Profile before entry: "restricted mode entered" must mean both channels
+  // applied, and a rejected profile must leave the session untouched.
+  let result: { ok: boolean; message?: string };
+  try {
+    result = await service.setProfile(sandboxProfile);
+  } catch (error) {
+    throw new Error(
+      `Sandbox profile '${sandboxProfile}' could not be applied; refusing to enter restricted mode '${agentName}' (fail-closed): ${describeError(error)}`,
+    );
+  }
+  if (!result.ok) {
+    throw new Error(
+      `Sandbox profile '${sandboxProfile}' was rejected; refusing to enter restricted mode '${agentName}' (fail-closed): ${result.message ?? "unknown reason"}`,
+    );
+  }
+
+  try {
+    pi.appendEntry(ACTIVE_AGENT_ENTRY_TYPE, { name: agentName });
+  } catch (error) {
+    // Roll the profile back so nothing claims a restriction the identity
+    // entry denies.
+    try {
+      await service.setProfile(undefined);
+    } catch {
+      // Best effort; the thrown error below is what the caller sees.
+    }
+    throw new Error(
+      `Could not record the ${agentName} session identity: ${describeError(error)}`,
+    );
+  }
+
+  return {
+    ok: true,
+    notices: result.message
+      ? [{ message: result.message, severity: "warning" }]
+      : [],
+  };
+}
+
+/**
+ * Leave the restricted mode, mirroring pi-agent-role's exit (applyRoleSelection
+ * with a cleared selection): null the identity entry and clear the sandbox
+ * profile back to the session default. Best-effort by design — every failure
+ * becomes a notice, never an exception, so exiting is always possible.
+ */
+export async function exitOpsxMode(
+  pi: ExtensionAPI,
+  deps: OpsxModeDeps = {},
+): Promise<OpsxModeOutcome> {
+  const notices: OpsxModeNotice[] = [];
+
+  try {
+    pi.appendEntry(ACTIVE_AGENT_ENTRY_TYPE, { name: null });
+  } catch (error) {
+    notices.push({
+      message: `Could not clear the session agent identity: ${describeError(error)}`,
+      severity: "error",
+    });
+  }
+
+  const service = await (deps.loadService ?? defaultLoadService)(
+    resolveSessionId(deps),
+  );
+  if (!service) {
+    notices.push({
+      message:
+        "pi-sandbox is unavailable in this session; there is no sandbox profile to restore.",
+      severity: "warning",
+    });
+  } else {
+    try {
+      const result = await service.setProfile(undefined);
+      if (!result.ok) {
+        notices.push({
+          message: result.message ?? "Sandbox profile could not be cleared.",
+          severity: "error",
+        });
+      }
+    } catch (error) {
+      notices.push({
+        message: `Sandbox profile could not be cleared: ${describeError(error)}`,
+        severity: "error",
+      });
+    }
+  }
+
+  return {
+    ok: notices.every((notice) => notice.severity !== "error"),
+    notices,
+  };
+}
+
+/**
+ * Build the `session_start` handler that drops an `active_agent` identity a
+ * previous session persisted in the same session file. Register alongside the
+ * resources_discover handler; the semantics are pi-agent-role's, unmodified.
+ */
+export function createOpsxSessionStartHandler(
+  pi: ExtensionAPI,
+): ExtensionHandler<SessionStartEvent> {
+  return (_event: SessionStartEvent, ctx: ExtensionContext): void => {
+    clearStaleActiveAgentIdentity(pi, ctx);
+  };
+}
+
+/**
+ * Remove an `active_agent` identity left behind by a previous session in the
+ * same session file (pi-agent-role's semantics, kept byte-compatible because
+ * the entries are shared): every session starts from no role, so a tail entry
+ * with a non-empty name is stale — without the cleanup the permission system
+ * would keep applying an agent scope that no longer has a role behind it.
+ */
+function clearStaleActiveAgentIdentity(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): void {
+  if (!hasPersistedActiveAgent(ctx)) return;
+  try {
+    pi.appendEntry(ACTIVE_AGENT_ENTRY_TYPE, { name: null });
+  } catch {
+    // Best effort: the identity is advisory and a session that cannot be
+    // written must not fail startup.
+  }
+}
+
+function hasPersistedActiveAgent(ctx: ExtensionContext): boolean {
+  try {
+    const entries = ctx.sessionManager.getEntries();
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+      const entry = entries[index] as {
+        type?: string;
+        customType?: string;
+        data?: { name?: unknown };
+      };
+      if (
+        entry?.type !== "custom" ||
+        entry.customType !== ACTIVE_AGENT_ENTRY_TYPE
+      )
+        continue;
+      const name = entry.data?.name;
+      return typeof name === "string" && name.length > 0;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}