opencode-swarm-plugin 0.15.0 → 0.17.0

package/src/schemas/mandate.ts

@@ -0,0 +1,232 @@
+/**
+ * Mandate schemas for voting system
+ *
+ * Agents file and vote on ideas, tips, lore, snippets, and feature requests.
+ * High-consensus items become "mandates" that influence future behavior.
+ *
+ * Vote decay and scoring patterns match learning.ts (90-day half-life).
+ */
+import { z } from "zod";
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+/**
+ * Content types for mandate entries
+ */
+export const MandateContentTypeSchema = z.enum([
+  "idea",
+  "tip",
+  "lore",
+  "snippet",
+  "feature_request",
+]);
+export type MandateContentType = z.infer<typeof MandateContentTypeSchema>;
+
+/**
+ * Mandate status lifecycle
+ *
+ * - candidate: New entry, collecting votes
+ * - established: Has some consensus but not enough for mandate status
+ * - mandate: High consensus (net_votes >= 5 AND vote_ratio >= 0.7)
+ * - rejected: Strong negative consensus or explicitly rejected
+ */
+export const MandateStatusSchema = z.enum([
+  "candidate",
+  "established",
+  "mandate",
+  "rejected",
+]);
+export type MandateStatus = z.infer<typeof MandateStatusSchema>;
+
+/**
+ * Vote type
+ */
+export const VoteTypeSchema = z.enum(["upvote", "downvote"]);
+export type VoteType = z.infer<typeof VoteTypeSchema>;
+
+// ============================================================================
+// Entry Schema
+// ============================================================================
+
+/**
+ * A mandate entry represents a proposal from an agent
+ *
+ * Entries can be ideas, tips, lore, code snippets, or feature requests.
+ * Other agents vote on entries to reach consensus.
+ */
+export const MandateEntrySchema = z.object({
+  /** Unique ID for this entry */
+  id: z.string(),
+  /** The actual content of the mandate */
+  content: z.string().min(1, "Content required"),
+  /** Type of content */
+  content_type: MandateContentTypeSchema,
+  /** Agent that created this entry */
+  author_agent: z.string(),
+  /** When this entry was created (ISO-8601) */
+  created_at: z.string().datetime({ offset: true }),
+  /** Current status */
+  status: MandateStatusSchema.default("candidate"),
+  /** Optional tags for categorization and search */
+  tags: z.array(z.string()).default([]),
+  /** Optional metadata (e.g., code language for snippets) */
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type MandateEntry = z.infer<typeof MandateEntrySchema>;
+
+// ============================================================================
+// Vote Schema
+// ============================================================================
+
+/**
+ * A vote on a mandate entry
+ *
+ * Each agent can vote once per entry (upvote or downvote).
+ * Votes decay with 90-day half-life matching learning.ts patterns.
+ */
+export const VoteSchema = z.object({
+  /** Unique ID for this vote */
+  id: z.string(),
+  /** The mandate entry this vote applies to */
+  mandate_id: z.string(),
+  /** Agent that cast this vote */
+  agent_name: z.string(),
+  /** Type of vote */
+  vote_type: VoteTypeSchema,
+  /** When this vote was cast (ISO-8601) */
+  timestamp: z.string().datetime({ offset: true }),
+  /** Raw vote weight before decay (default: 1.0) */
+  weight: z.number().min(0).max(1).default(1.0),
+});
+export type Vote = z.infer<typeof VoteSchema>;
+
+// ============================================================================
+// Score Schema
+// ============================================================================
+
+/**
+ * Calculated score for a mandate entry
+ *
+ * Scores are recalculated periodically with decay applied.
+ * Uses same decay formula as learning.ts (90-day half-life).
+ */
+export const MandateScoreSchema = z.object({
+  /** The mandate entry this score applies to */
+  mandate_id: z.string(),
+  /** Net votes (upvotes - downvotes) with decay applied */
+  net_votes: z.number(),
+  /** Vote ratio: upvotes / (upvotes + downvotes) */
+  vote_ratio: z.number().min(0).max(1),
+  /** Final decayed score for ranking */
+  decayed_score: z.number(),
+  /** When this score was last calculated (ISO-8601) */
+  last_calculated: z.string().datetime({ offset: true }),
+  /** Raw vote counts (before decay) */
+  raw_upvotes: z.number().int().min(0),
+  raw_downvotes: z.number().int().min(0),
+  /** Decayed vote counts */
+  decayed_upvotes: z.number().min(0),
+  decayed_downvotes: z.number().min(0),
+});
+export type MandateScore = z.infer<typeof MandateScoreSchema>;
+
+// ============================================================================
+// Decay Configuration
+// ============================================================================
+
+/**
+ * Configuration for mandate decay calculation
+ *
+ * Matches learning.ts decay patterns.
+ */
+export interface MandateDecayConfig {
+  /** Half-life for vote decay in days */
+  halfLifeDays: number;
+  /** Net votes threshold for mandate status */
+  mandateNetVotesThreshold: number;
+  /** Vote ratio threshold for mandate status */
+  mandateVoteRatioThreshold: number;
+  /** Net votes threshold for established status */
+  establishedNetVotesThreshold: number;
+  /** Negative net votes threshold for rejected status */
+  rejectedNetVotesThreshold: number;
+}
+
+export const DEFAULT_MANDATE_DECAY_CONFIG: MandateDecayConfig = {
+  halfLifeDays: 90,
+  mandateNetVotesThreshold: 5,
+  mandateVoteRatioThreshold: 0.7,
+  establishedNetVotesThreshold: 2,
+  rejectedNetVotesThreshold: -3,
+};
+
+// ============================================================================
+// API Schemas
+// ============================================================================
+
+/**
+ * Arguments for creating a mandate entry
+ */
+export const CreateMandateArgsSchema = z.object({
+  content: z.string().min(1, "Content required"),
+  content_type: MandateContentTypeSchema,
+  tags: z.array(z.string()).default([]),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type CreateMandateArgs = z.infer<typeof CreateMandateArgsSchema>;
+
+/**
+ * Arguments for casting a vote
+ */
+export const CastVoteArgsSchema = z.object({
+  mandate_id: z.string(),
+  vote_type: VoteTypeSchema,
+  weight: z.number().min(0).max(1).default(1.0),
+});
+export type CastVoteArgs = z.infer<typeof CastVoteArgsSchema>;
+
+/**
+ * Arguments for querying mandates
+ */
+export const QueryMandatesArgsSchema = z.object({
+  status: MandateStatusSchema.optional(),
+  content_type: MandateContentTypeSchema.optional(),
+  tags: z.array(z.string()).optional(),
+  author_agent: z.string().optional(),
+  limit: z.number().int().positive().default(20),
+  min_score: z.number().optional(),
+});
+export type QueryMandatesArgs = z.infer<typeof QueryMandatesArgsSchema>;
+
+/**
+ * Result of score calculation
+ */
+export const ScoreCalculationResultSchema = z.object({
+  mandate_id: z.string(),
+  previous_status: MandateStatusSchema,
+  new_status: MandateStatusSchema,
+  score: MandateScoreSchema,
+  status_changed: z.boolean(),
+});
+export type ScoreCalculationResult = z.infer<
+  typeof ScoreCalculationResultSchema
+>;
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export const mandateSchemas = {
+  MandateContentTypeSchema,
+  MandateStatusSchema,
+  VoteTypeSchema,
+  MandateEntrySchema,
+  VoteSchema,
+  MandateScoreSchema,
+  CreateMandateArgsSchema,
+  CastVoteArgsSchema,
+  QueryMandatesArgsSchema,
+  ScoreCalculationResultSchema,
+};

package/src/swarm.ts

@@ -2039,7 +2039,9 @@ async function runVerificationGate(
 
       if (!ubsStep.passed) {
         ubsStep.error = `Found ${ubsResult.summary.critical} critical bugs`;
-        blockers.push(`UBS: ${ubsResult.summary.critical} critical bugs found`);
+        blockers.push(
+          `UBS found ${ubsResult.summary.critical} critical bug(s). Try: Run 'ubs scan ${filesTouched.join(" ")}' to see details, fix critical bugs in reported files, or use skip_ubs_scan=true to bypass (not recommended).`,
+        );
       }
 
       steps.push(ubsStep);
@@ -2060,7 +2062,7 @@ async function runVerificationGate(
   steps.push(typecheckStep);
   if (!typecheckStep.passed && !typecheckStep.skipped) {
     blockers.push(
-      `Typecheck: ${typecheckStep.error?.slice(0, 100) || "failed"}`,
+      `Typecheck failed: ${typecheckStep.error?.slice(0, 100) || "type errors found"}. Try: Run 'tsc --noEmit' to see full errors, check tsconfig.json configuration, or fix reported type errors in modified files.`,
     );
   }
 
@@ -2068,7 +2070,9 @@ async function runVerificationGate(
   const testStep = await runTestVerification(filesTouched);
   steps.push(testStep);
   if (!testStep.passed && !testStep.skipped) {
-    blockers.push(`Tests: ${testStep.error?.slice(0, 100) || "failed"}`);
+    blockers.push(
+      `Tests failed: ${testStep.error?.slice(0, 100) || "test failures"}. Try: Run 'bun test ${testStep.command.split(" ").slice(2).join(" ")}' to see full output, check test assertions, or fix failing tests in modified files.`,
+    );
   }
 
   // Build summary
@@ -2150,10 +2154,12 @@ async function runUbsScan(files: string[]): Promise<UbsScanResult | null> {
     } catch (error) {
       // UBS output wasn't JSON - this is an error condition
       console.error(
-        `[swarm] CRITICAL: UBS scan failed to parse JSON output:`,
+        `[swarm] CRITICAL: UBS scan failed to parse JSON output because output is malformed:`,
         error,
       );
-      console.error(`[swarm] Raw output:`, output);
+      console.error(
+        `[swarm] Raw output: ${output}. Try: Run 'ubs doctor' to check installation, verify UBS version with 'ubs --version' (need v1.0.0+), or check if UBS supports --json flag.`,
+      );
       return {
         exitCode: result.exitCode,
         bugs: [],
@@ -2320,7 +2326,10 @@ export const swarm_complete = tool({
                 error: s.error?.slice(0, 200),
               })),
             },
-            hint: "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
+            hint:
+              verificationResult.blockers.length > 0
+                ? `Fix these issues: ${verificationResult.blockers.map((b, i) => `${i + 1}. ${b}`).join(", ")}. Use skip_verification=true only as last resort.`
+                : "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
             gate_function:
               "IDENTIFY → RUN → READ → VERIFY → CLAIM (you are at VERIFY, claim blocked)",
           },
@@ -2345,12 +2354,18 @@ export const swarm_complete = tool({
         return JSON.stringify(
           {
             success: false,
-            error: "UBS found critical bugs - fix before completing",
+            error: `UBS found ${ubsResult.summary.critical} critical bug(s) that must be fixed before completing`,
             ubs_scan: {
               critical_count: ubsResult.summary.critical,
               bugs: ubsResult.bugs.filter((b) => b.severity === "critical"),
             },
-            hint: "Fix the critical bugs and try again, or use skip_ubs_scan=true to bypass",
+            hint: `Fix these critical bugs: ${ubsResult.bugs
+              .filter((b) => b.severity === "critical")
+              .map((b) => `${b.file}:${b.line} - ${b.message}`)
+              .slice(0, 3)
+              .join(
+                "; ",
+              )}. Try: Run 'ubs scan ${args.files_touched?.join(" ") || "."} --json' for full report, fix reported issues, or use skip_ubs_scan=true to bypass (not recommended).`,
           },
           null,
           2,
@@ -2398,7 +2413,7 @@ export const swarm_complete = tool({
 
     if (closeResult.exitCode !== 0) {
       throw new SwarmError(
-        `Failed to close bead: ${closeResult.stderr.toString()}`,
+        `Failed to close bead because bd close command failed: ${closeResult.stderr.toString()}. Try: Verify bead exists and is not already closed with 'bd show ${args.bead_id}', check if bead ID is correct with 'beads_query()', or use beads_close tool directly.`,
         "complete",
       );
     }