switchboard-cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/compiler.ts

@@ -0,0 +1,183 @@
+import { classifyComplexity } from "./classifier";
+import { createCandidateArtifact, generateFidelityFirstPrompt, selectCompiler } from "./compiler-adapter";
+import { deriveProjectCharter, deriveTaskClauses } from "./project-charter";
+import { chooseRecommendedSurface } from "./router";
+import { LocalSynthesisProvider, slugify } from "./synthesis-provider";
+import type { SynthesisProvider } from "./synthesis-provider";
+import type {
+  ActivationInput,
+  CandidateArtifact,
+  CompilerSelection,
+  ComplexityClassification,
+  ProjectCharter,
+  ProjectContract,
+  ResearchClassification,
+  RoutingResult,
+  SynthesizedSeed,
+  WorkingState,
+} from "./types";
+import { activationInputSchema, projectContractSchema, workingStateSchema } from "./types";
+
+export type CompiledProject = {
+  contract: ProjectContract;
+  charter: ProjectCharter;
+  current: WorkingState;
+  route: RoutingResult;
+  spec_markdown: string;
+  seed: SynthesizedSeed;
+  research: ResearchClassification;
+  complexity: ComplexityClassification;
+  compiler: CompilerSelection;
+  artifact: CandidateArtifact;
+  external_prompt: string | null;
+};
+
+export function compileProjectActivation(
+  rawInput: ActivationInput,
+  provider?: SynthesisProvider,
+): CompiledProject {
+  const input = activationInputSchema.parse(rawInput);
+  const synth = provider ?? new LocalSynthesisProvider();
+
+  // Phase 1: Extract seed (always runs)
+  const seed = synth.extractSeed(input);
+
+  // Phase 2: Classify complexity and select process mode
+  const complexity = classifyComplexity(input, seed);
+
+  // Phase 3: Research classification (skip in minimal mode)
+  const research =
+    complexity.mode === "minimal"
+      ? { angles: [], research_needed: false, summary: "Simple project — research not needed." }
+      : synth.classifyResearchAngles(seed);
+
+  // Phase 4: Select compiler adapter
+  const compiler = selectCompiler(complexity, seed);
+
+  // Phase 5: Route to execution surface (governance mode overrides keywords)
+  const route = chooseRecommendedSurface({
+    repo_present: input.repo_exists,
+    task: input.what_do_you_want_next,
+    seed_confidence: seed.confidence,
+    research_needed: research.research_needed,
+    process_mode: complexity.mode,
+  });
+
+  // Phase 6: Build canonical contract (always runs — this is project identity, not the brief)
+  const taskClauses = deriveTaskClauses({
+    seed,
+    rawIdea: input.raw_idea,
+    constraints: input.constraints,
+    repoExists: input.repo_exists,
+  });
+
+  const contract = projectContractSchema.parse({
+    project_id: slugify(seed.title),
+    title: seed.title,
+    one_liner: seed.one_liner,
+    problem: seed.problem,
+    target_user: seed.target_user,
+    desired_v1_outcome: seed.v1_outcome,
+    non_goals: seed.non_goals,
+    repo_status: input.repo_exists ? "repo-present" : "repo-not-present",
+    task_clauses: taskClauses,
+  });
+
+  // Phase 7: Build open questions (mode-dependent depth)
+  const allQuestions =
+    complexity.mode === "governance"
+      ? [
+          ...seed.missing_inputs,
+          ...seed.open_questions,
+          ...research.angles.map((a) => a.question),
+        ]
+      : [
+          ...seed.missing_inputs,
+          ...seed.open_questions,
+          ...research.angles
+            .filter((a) => a.priority === "blocking")
+            .map((a) => a.question),
+        ];
+
+  const finalQuestions =
+    allQuestions.length > 0
+      ? allQuestions.slice(0, complexity.mode === "governance" ? 8 : 5)
+      : complexity.mode === "minimal"
+        ? []
+        : [
+            input.repo_exists
+              ? "What is the narrowest repo slice that proves the wedge without adding platform breadth?"
+              : "What needs to be clarified before this idea is ready for repo execution?",
+          ];
+
+  // Phase 8: Build working state
+  const stage =
+    complexity.mode === "governance"
+      ? "activation-needs-narrowing"
+      : input.repo_exists
+        ? "activation-compiled"
+        : "activation-shaping";
+
+  const dominantUncertainty =
+    complexity.mode === "governance"
+      ? complexity.rationale
+      : seed.confidence === "low"
+        ? "The idea needs further shaping before it can drive execution."
+        : input.repo_exists
+          ? "Can the next repo slice stay narrow enough to ship without platform sprawl?"
+          : "Is the idea sharp enough to justify starting repo-bound execution yet?";
+
+  const current = workingStateSchema.parse({
+    stage,
+    current_objective: route.next_objective,
+    dominant_uncertainty: dominantUncertainty,
+    open_questions: finalQuestions,
+    primary_artifact_ref: "artifacts/SB_SPEC.md",
+    active_handoff_id: "",
+    last_return_status: "not-started",
+    latest_decisions: [
+      `SB_SPEC.md is the primary artifact for ${seed.title}.`,
+      `Complexity: ${complexity.verdict}. Process mode: ${complexity.mode}.`,
+      `Recommended compiler: ${compiler.compiler_type} (${compiler.recommended_surface}).`,
+    ],
+    latest_blockers:
+      complexity.mode === "governance"
+        ? [`Scope must be narrowed before implementation dispatch. ${complexity.rationale}`]
+        : [],
+    next_recommended_surface: route.primary_recommendation,
+    next_objective: route.next_objective,
+  });
+
+  // Phase 9: Generate internal fallback brief (always produced as candidate)
+  const spec_markdown = synth.generateBrief(input, seed, route);
+  const artifact = createCandidateArtifact(spec_markdown, "internal-fallback");
+
+  // Phase 10: Generate external compiler prompt (when external compiler recommended)
+  const external_prompt =
+    compiler.compiler_type === "fidelity-first"
+      ? generateFidelityFirstPrompt(seed, contract, input.raw_idea, input.constraints)
+      : null;
+
+  // Phase 11: Derive project charter — the official "what was created" object
+  const charter = deriveProjectCharter({
+    contract,
+    seed,
+    complexity,
+    rawIdea: input.raw_idea,
+    constraints: input.constraints,
+  });
+
+  return {
+    contract,
+    charter,
+    current,
+    route,
+    spec_markdown,
+    seed,
+    research,
+    complexity,
+    compiler,
+    artifact,
+    external_prompt,
+  };
+}

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/dispatch-formatter.ts

@@ -0,0 +1,348 @@
+/**
+ * Surface-Aware Dispatch Packet Formatter
+ *
+ * Produces the correct dispatch packet shape for each surface based on
+ * its profile capabilities. This is the bridge between Switchboard's
+ * surface-agnostic routing decisions and the surface-specific packet
+ * formats each execution target expects.
+ *
+ * Switchboard sits ABOVE all surfaces. This module handles the last-mile
+ * adaptation from governed dispatch state to surface-native format.
+ */
+import type {
+  ExecutionHarness,
+  LoopContract,
+  ProjectContract,
+  Surface,
+  SurfaceProfile,
+} from "./types";
+import { getSurfaceProfile } from "./surface-profiles";
+import { getSurfacePlaybook } from "./surface-playbooks";
+
+// ---------------------------------------------------------------------------
+// Dispatch packet types — one per packet_format
+// ---------------------------------------------------------------------------
+
+/** SDK prompt packet: sent programmatically via an API/SDK call. */
+export interface SdkPromptPacket {
+  format: "sdk_prompt";
+  surface: Surface;
+  prompt: string;
+  working_directory: string | null;
+  model_hint: string;
+  async_return: boolean;
+  metadata: DispatchMetadata;
+}
+
+/** Clipboard packet: copy-paste text for human-mediated surfaces. */
+export interface ClipboardPacket {
+  format: "clipboard";
+  surface: Surface;
+  preamble: string;
+  body: string;
+  return_instructions: string;
+  metadata: DispatchMetadata;
+}
+
+/** File drop packet: written to a working directory for file-based surfaces. */
+export interface FileDropPacket {
+  format: "file_drop";
+  surface: Surface;
+  filename: string;
+  content: string;
+  working_directory: string;
+  metadata: DispatchMetadata;
+}
+
+export interface DispatchMetadata {
+  dispatch_id: string;
+  contract_title: string;
+  objective: string;
+  scope_in: string[];
+  scope_out: string[];
+  done_when: string[];
+  return_condition: string;
+  playbook_notes: string[];
+}
+
+export type DispatchPacket = SdkPromptPacket | ClipboardPacket | FileDropPacket;
+
+// ---------------------------------------------------------------------------
+// Formatter input
+// ---------------------------------------------------------------------------
+
+export interface FormatDispatchInput {
+  dispatch_id: string;
+  surface: Surface;
+  prompt: string;
+  contract: ProjectContract;
+  loop: LoopContract;
+  spec_markdown: string;
+  working_directory?: string;
+  model_hint?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Core formatter
+// ---------------------------------------------------------------------------
+
+export function formatDispatchPacket(input: FormatDispatchInput): DispatchPacket {
+  const profile = getSurfaceProfile(input.surface);
+  if (!profile) {
+    throw new Error(`No surface profile for "${input.surface}". Cannot format dispatch packet.`);
+  }
+
+  const metadata = buildMetadata(input);
+
+  switch (profile.packet_format) {
+    case "sdk_prompt":
+      return formatSdkPrompt(input, profile, metadata);
+    case "clipboard":
+      return formatClipboard(input, profile, metadata);
+    case "file_drop":
+      return formatFileDrop(input, profile, metadata);
+    case "sbx_bundle":
+      // SBX bundle is a superset of file_drop for now
+      return formatFileDrop(input, profile, metadata);
+    default: {
+      const _exhaustive: never = profile.packet_format;
+      throw new Error(`Unknown packet format: ${_exhaustive}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Format-specific builders
+// ---------------------------------------------------------------------------
+
+function formatSdkPrompt(
+  input: FormatDispatchInput,
+  profile: SurfaceProfile,
+  metadata: DispatchMetadata,
+): SdkPromptPacket {
+  return {
+    format: "sdk_prompt",
+    surface: input.surface as Surface,
+    prompt: input.prompt,
+    working_directory: profile.capabilities.supports_working_directory
+      ? (input.working_directory ?? null)
+      : null,
+    model_hint: input.model_hint ?? "",
+    async_return: profile.receipt_model === "async_callback",
+    metadata,
+  };
+}
+
+function formatClipboard(
+  input: FormatDispatchInput,
+  _profile: SurfaceProfile,
+  metadata: DispatchMetadata,
+): ClipboardPacket {
+  const playbook = getSurfacePlaybook(input.surface as Surface);
+
+  const preamble = [
+    `# Switchboard Dispatch — ${metadata.contract_title}`,
+    "",
+    `**Surface:** ${input.surface}`,
+    `**Dispatch ID:** ${metadata.dispatch_id}`,
+    `**Objective:** ${metadata.objective}`,
+    "",
+    "## Operating Notes",
+    ...playbook.notes.map(n => `- ${n}`),
+    "",
+  ].join("\n");
+
+  const returnInstructions = [
+    "## Return Instructions",
+    "",
+    `Return when: ${metadata.return_condition}`,
+    "",
+    "Your return must include:",
+    "- status: done | partial | blocked",
+    "- objective_met: yes | no | partial",
+    "- done_when_met: yes | no | partial",
+    "- summary: what you did",
+    "- changed_files: list of files touched",
+    "- evidence: what proves it worked",
+    "- recommended_next_step: what should happen next",
+    "",
+    `Reference dispatch: ${metadata.dispatch_id}`,
+  ].join("\n");
+
+  return {
+    format: "clipboard",
+    surface: input.surface as Surface,
+    preamble,
+    body: input.prompt,
+    return_instructions: returnInstructions,
+    metadata,
+  };
+}
+
+function formatFileDrop(
+  input: FormatDispatchInput,
+  _profile: SurfaceProfile,
+  metadata: DispatchMetadata,
+): FileDropPacket {
+  const content = [
+    "---",
+    `dispatch_id: ${metadata.dispatch_id}`,
+    `surface: ${input.surface}`,
+    `objective: ${metadata.objective}`,
+    `return_condition: ${metadata.return_condition}`,
+    "---",
+    "",
+    input.prompt,
+  ].join("\n");
+
+  return {
+    format: "file_drop",
+    surface: input.surface as Surface,
+    filename: `dispatch-${metadata.dispatch_id}.md`,
+    content,
+    working_directory: input.working_directory ?? ".",
+    metadata,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function buildMetadata(input: FormatDispatchInput): DispatchMetadata {
+  const playbook = getSurfacePlaybook(input.surface as Surface);
+  return {
+    dispatch_id: input.dispatch_id,
+    contract_title: input.contract.title,
+    objective: input.loop.objective,
+    scope_in: input.loop.scope_in,
+    scope_out: input.loop.scope_out,
+    done_when: input.loop.done_when,
+    return_condition: input.loop.return_when,
+    playbook_notes: playbook.notes,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Harness-based formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a dispatch packet from a compiled ExecutionHarness.
+ *
+ * This is the preferred entry point when an ExecutionHarness has already been
+ * compiled. It reads surface identity, capabilities, playbook notes, and
+ * context bindings from the harness instead of re-deriving them from profiles
+ * and playbooks.
+ *
+ * The `prompt` is passed separately because it is execution content, not
+ * execution shape — the harness describes the shape, the prompt is the payload.
+ */
+export function formatFromHarness(
+  harness: ExecutionHarness,
+  prompt: string,
+): DispatchPacket {
+  const metadata: DispatchMetadata = {
+    dispatch_id: harness.dispatch_id,
+    contract_title: harness.governance_envelope.contract_title,
+    objective: harness.objective,
+    scope_in: harness.scope_in,
+    scope_out: harness.scope_out,
+    done_when: harness.done_when,
+    return_condition: harness.return_when,
+    playbook_notes: harness.playbook_notes,
+  };
+
+  switch (harness.packet_format) {
+    case "sdk_prompt":
+      return {
+        format: "sdk_prompt",
+        surface: harness.surface,
+        prompt,
+        working_directory: harness.context_bindings.working_directory,
+        model_hint: harness.context_bindings.model_hint,
+        async_return: harness.context_bindings.async_return,
+        metadata,
+      };
+
+    case "clipboard": {
+      const preamble = [
+        `# Switchboard Dispatch — ${metadata.contract_title}`,
+        "",
+        `**Surface:** ${harness.surface}`,
+        `**Dispatch ID:** ${metadata.dispatch_id}`,
+        `**Objective:** ${metadata.objective}`,
+        "",
+        "## Operating Notes",
+        ...harness.playbook_notes.map(n => `- ${n}`),
+        "",
+      ].join("\n");
+
+      const returnInstructions = [
+        "## Return Instructions",
+        "",
+        `Return when: ${metadata.return_condition}`,
+        "",
+        "Your return must include:",
+        ...harness.return_expectation.required_fields.map(f => `- ${f}`),
+        "",
+        `Reference dispatch: ${metadata.dispatch_id}`,
+      ].join("\n");
+
+      return {
+        format: "clipboard",
+        surface: harness.surface,
+        preamble,
+        body: prompt,
+        return_instructions: returnInstructions,
+        metadata,
+      };
+    }
+
+    case "file_drop":
+    case "sbx_bundle": {
+      const content = [
+        "---",
+        `dispatch_id: ${metadata.dispatch_id}`,
+        `surface: ${harness.surface}`,
+        `objective: ${metadata.objective}`,
+        `return_condition: ${metadata.return_condition}`,
+        "---",
+        "",
+        prompt,
+      ].join("\n");
+
+      return {
+        format: "file_drop",
+        surface: harness.surface,
+        filename: `dispatch-${metadata.dispatch_id}.md`,
+        content,
+        working_directory: harness.context_bindings.working_directory ?? ".",
+        metadata,
+      };
+    }
+
+    default: {
+      const _exhaustive: never = harness.packet_format;
+      throw new Error(`Unknown packet format: ${_exhaustive}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Convenience: check if a surface can be dispatched automatically
+// ---------------------------------------------------------------------------
+
+export function canAutoDispatch(surface: Surface): boolean {
+  const profile = getSurfaceProfile(surface);
+  if (!profile) return false;
+  return profile.capabilities.can_dispatch_programmatically && !profile.capabilities.requires_human_in_loop;
+}
+
+export function getDispatchMode(surface: Surface): "auto" | "manual" | "async" {
+  const profile = getSurfaceProfile(surface);
+  if (!profile) return "manual";
+  if (!profile.capabilities.can_dispatch_programmatically) return "manual";
+  if (profile.receipt_model === "async_callback") return "async";
+  return "auto";
+}

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/dispatch-receipt.ts

@@ -0,0 +1,135 @@
+import type {
+  DispatchReceipt,
+  LoopContract,
+  ProjectContract,
+} from "./types";
+import { dispatchReceiptSchema } from "./types";
+import { createHash, randomBytes } from "crypto";
+
+// ---------------------------------------------------------------------------
+// Packet hashing — deterministic content digest
+// ---------------------------------------------------------------------------
+
+function hashContent(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+
+function buildPacketHash(input: {
+  contract: ProjectContract;
+  loop: LoopContract;
+  specMarkdown: string;
+}): string {
+  const content = [
+    input.contract.project_id,
+    input.contract.title,
+    input.loop.objective,
+    ...input.loop.scope_in,
+    ...input.contract.non_goals,
+    input.specMarkdown.slice(0, 500),
+  ].join("|");
+  return hashContent(content);
+}
+
+function buildPromptHash(prompt: string): string {
+  return hashContent(prompt);
+}
+
+// ---------------------------------------------------------------------------
+// Receipt creation — packet_prepared phase
+// ---------------------------------------------------------------------------
+
+let _packetVersion = 0;
+
+export function createDispatchReceipt(input: {
+  dispatchId: string;
+  contract: ProjectContract;
+  loop: LoopContract;
+  prompt: string;
+  specMarkdown: string;
+  surface: string;
+  surfaceLabel: string;
+  artifactIds?: string[];
+}): DispatchReceipt {
+  _packetVersion++;
+
+  return dispatchReceiptSchema.parse({
+    receipt_id: `rcpt-${randomBytes(8).toString("hex")}`,
+    dispatch_id: input.dispatchId,
+    packet_version: _packetVersion,
+
+    destination_surface: input.surface,
+    destination_label: input.surfaceLabel,
+    governing_contract_id: input.contract.project_id,
+    packet_hash: buildPacketHash({
+      contract: input.contract,
+      loop: input.loop,
+      specMarkdown: input.specMarkdown,
+    }),
+    prompt_hash: buildPromptHash(input.prompt),
+    included_artifact_ids: input.artifactIds ?? ["SB_SPEC.md"],
+
+    phase: "packet_prepared",
+    prepared_at: new Date().toISOString(),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Phase transitions
+// ---------------------------------------------------------------------------
+
+export function commitReceipt(receipt: DispatchReceipt): DispatchReceipt {
+  return dispatchReceiptSchema.parse({
+    ...receipt,
+    phase: "packet_committed",
+    committed_at: new Date().toISOString(),
+  });
+}
+
+export function acknowledgeReceipt(
+  receipt: DispatchReceipt,
+  input: {
+    providerRunRef?: string;
+    modelUsed?: string;
+  },
+): DispatchReceipt {
+  const runRef = input.providerRunRef?.trim() ?? "";
+  const model = input.modelUsed?.trim() ?? "";
+  return dispatchReceiptSchema.parse({
+    ...receipt,
+    phase: "provider_acknowledged",
+    acknowledged_at: new Date().toISOString(),
+    provider_run_ref: runRef,
+    // Operator channel took the job: explicit run ref from provider, or model line from a completed SDK run.
+    provider_ack_available: !!(runRef || model),
+    model_used: model,
+  });
+}
+
+export function linkReturnToReceipt(
+  receipt: DispatchReceipt,
+  input: {
+    returnId: string;
+    deltaId?: string;
+    executionDurationMs?: number;
+  },
+): DispatchReceipt {
+  return dispatchReceiptSchema.parse({
+    ...receipt,
+    phase: "return_received",
+    return_received_at: new Date().toISOString(),
+    return_id: input.returnId,
+    delta_id: input.deltaId ?? "",
+    execution_duration_ms: input.executionDurationMs ?? 0,
+  });
+}
+
+export function failReceipt(
+  receipt: DispatchReceipt,
+  _reason: string,
+): DispatchReceipt {
+  return dispatchReceiptSchema.parse({
+    ...receipt,
+    phase: "failed",
+    failed_at: new Date().toISOString(),
+  });
+}