Function getSwarm

Parameters

• artifact: {
      aborted?: boolean;
      assumptions?: string[];
      citations?: { context: string; doi?: string; text: string; url: string }[];
      cost?: {
          breakdown?: Record<string, number>;
          cachedReadTokens?: number;
          cacheSavingsUSD?: number;
          inputTokens?: number;
          llmCalls?: number;
          outputTokens?: number;
          totalUSD: number;
      };
      decisions?: {
          actor?: string;
          choice: string;
          outcome?: | "risky_success"
          | "risky_failure"
          | "conservative_success"
          | "conservative_failure";
          rationale?: string;
          reasoning?: string;
          scenarioExtensions?: Record<string, unknown>;
          time: number;
      }[];
      disclaimer?: string;
      finalState?: {
          capacities?: Record<string, number>;
          environment?: Record<string, string | number | boolean>;
          metrics: Record<string, number>;
          politics?: Record<string, string | number | boolean>;
          scenarioExtensions?: Record<string, unknown>;
          statuses?: Record<string, string | boolean>;
      };
      finalSwarm?: {
          agents: {
              age?: number;
              agentId: string;
              alive: boolean;
              childrenIds?: string[];
              department: string;
              featured?: boolean;
              generation?: number;
              marsborn?: boolean;
              mood?: string;
              name: string;
              partnerId?: string;
              psychScore?: number;
              rank?: "junior"
              | "senior"
              | "lead"
              | "chief";
              role: string;
              shortTermMemory?: string[];
          }[];
          births?: number;
          deaths?: number;
          morale?: number;
          population: number;
          scenarioExtensions?: Record<string, unknown>;
          time: number;
          turn: number;
      };
      fingerprint?: Record<string, string | number>;
      forgedTools?: {
          approved: boolean;
          confidence?: number;
          department?: string;
          description?: string;
          name: string;
      }[];
      intervention?: {
          adherenceProfile?: { expected: number; risks?: string[] };
          category?: string;
          description: string;
          duration?: { unit: string; value: number };
          id: string;
          mechanism?: string;
          name: string;
          scenarioExtensions?: Record<string, unknown>;
          targetBehaviors?: string[];
      };
      leveragePoints?: string[];
      metadata: {
          completedAt?: string;
          forkedFrom?: { atTurn: number; parentRunId: string };
          mode: "turn-loop" | "batch-trajectory" | "batch-point";
          runId: string;
          scenario: { id: string; name: string; version?: string };
          scenarioExtensions?: Record<string, unknown>;
          seed?: number;
          startedAt: string;
      };
      overview?: string;
      providerError?: | {
          actionUrl?: string;
          kind: "unknown"
          | "auth"
          | "quota"
          | "rate_limit"
          | "network";
          message: string;
          provider: string;
      }
      | null;
      riskFlags?: {
          detail: string;
          label: string;
          scenarioExtensions?: Record<string, unknown>;
          severity: "low" | "medium" | "high";
      }[];
      scenarioExtensions?: Record<string, unknown>;
      specialistNotes?: {
          confidence?: number;
          detail?: {
              citations?: {
                  context: string;
                  doi?: string;
                  text: string;
                  url: string;
              }[];
              openQuestions?: string[];
              opportunities?: {
                  description: string;
                  impact: "low"
                  | "medium"
                  | "high";
              }[];
              recommendedActions?: string[];
              risks?: {
                  description: string;
                  severity: "low"
                  | "medium"
                  | "high"
                  | "critical";
              }[];
          };
          domain: string;
          scenarioExtensions?: Record<string, unknown>;
          summary: string;
          trajectory?: "positive" | "negative" | "neutral" | "mixed";
      }[];
      subject?: {
          conditions?: string[];
          id: string;
          markers?: {
              category?: string;
              id: string;
              interpretation?: string;
              value?: string;
          }[];
          name: string;
          personality?: Record<string, number>;
          profile?: Record<string, unknown>;
          scenarioExtensions?: Record<string, unknown>;
          signals?: {
              label: string;
              recordedAt?: string;
              unit?: string;
              value: string | number;
          }[];
      };
      trajectory?: {
          points?: {
              metrics: Record<string, number>;
              scenarioExtensions?: Record<string, unknown>;
              time: number;
          }[];
          timepoints?: {
              confidence?: number;
              highlightMetrics?: {
                  color?: string;
                  direction?: "up"
                  | "down"
                  | "stable";
                  label: string;
                  value: string;
              }[];
              label: string;
              narrative?: string;
              reasoning?: string;
              scenarioExtensions?: Record<string, unknown>;
              score?: { label: string; max: number; min: number; value: number };
              time: number;
              worldSnapshot?: {
                  capacities?: Record<string, number>;
                  environment?: Record<string, (...) | (...) | (...) | (...)>;
                  metrics: Record<string, number>;
                  politics?: Record<string, (...) | (...) | (...) | (...)>;
                  scenarioExtensions?: Record<string, unknown>;
                  statuses?: Record<string, (...) | (...) | (...)>;
              };
          }[];
          timeUnit: { plural: string; singular: string };
      };
  }

  • Optionalaborted?: boolean

  • Optionalassumptions?: string[]

    Assumptions held true during the simulation.

  • Optionalcitations?: { context: string; doi?: string; text: string; url: string }[]

  • Optionalcost?: {
        breakdown?: Record<string, number>;
        cachedReadTokens?: number;
        cacheSavingsUSD?: number;
        inputTokens?: number;
        llmCalls?: number;
        outputTokens?: number;
        totalUSD: number;
    }

    • Optionalbreakdown?: Record<string, number>

      Per-site / per-model breakdown: { director: 0.12, departments: 0.34 }.

    • OptionalcachedReadTokens?: number

    • OptionalcacheSavingsUSD?: number

    • OptionalinputTokens?: number

    • OptionalllmCalls?: number

    • OptionaloutputTokens?: number

    • totalUSD: number

  • Optionaldecisions?: {
        actor?: string;
        choice: string;
        outcome?:
            | "risky_success"
            | "risky_failure"
            | "conservative_success"
            | "conservative_failure";
        rationale?: string;
        reasoning?: string;
        scenarioExtensions?: Record<string, unknown>;
        time: number;
    }[]

    Every decision made during the run — one per commander choice in turn-loop.

  • Optionaldisclaimer?: string

    Scenario-supplied disclaimer (digital-twin simulations use this for medical / professional caveats).

  • OptionalfinalState?: {
        capacities?: Record<string, number>;
        environment?: Record<string, string | number | boolean>;
        metrics: Record<string, number>;
        politics?: Record<string, string | number | boolean>;
        scenarioExtensions?: Record<string, unknown>;
        statuses?: Record<string, string | boolean>;
    }

    • Optionalcapacities?: Record<string, number>

      Capacity constraints: life support, housing, budget.

    • Optionalenvironment?: Record<string, string | number | boolean>

      Environmental conditions: weather, radiation, depth, altitude.

    • metrics: Record<string, number>

      Numeric gauges: food, power, population, morale, VO2max, whatever.

    • Optionalpolitics?: Record<string, string | number | boolean>

      Political/social pressures. Values may be numeric or categorical.

    • OptionalscenarioExtensions?: Record<string, unknown>

    • Optionalstatuses?: Record<string, string | boolean>

      Categorical state: governance status, alignment, phase.

  • OptionalfinalSwarm?: {
        agents: {
            age?: number;
            agentId: string;
            alive: boolean;
            childrenIds?: string[];
            department: string;
            featured?: boolean;
            generation?: number;
            marsborn?: boolean;
            mood?: string;
            name: string;
            partnerId?: string;
            psychScore?: number;
            rank?: "junior" | "senior" | "lead" | "chief";
            role: string;
            shortTermMemory?: string[];
        }[];
        births?: number;
        deaths?: number;
        morale?: number;
        population: number;
        scenarioExtensions?: Record<string, unknown>;
        time: number;
        turn: number;
    }

    Final agent-swarm roster at end-of-run. Pairs with finalState: the world snapshot is the macro view (metrics, statuses), the swarm snapshot is the micro view (every agent's role, mood, family edges, memory). Populated in turn-loop runs that exercised the swarm. Use WorldModel.swarm() for the live equivalent during a run.

    • agents: {
          age?: number;
          agentId: string;
          alive: boolean;
          childrenIds?: string[];
          department: string;
          featured?: boolean;
          generation?: number;
          marsborn?: boolean;
          mood?: string;
          name: string;
          partnerId?: string;
          psychScore?: number;
          rank?: "junior" | "senior" | "lead" | "chief";
          role: string;
          shortTermMemory?: string[];
      }[]

      Every agent in the swarm at snapshot time, alive or dead.

    • Optionalbirths?: number

      Number of births this turn.

    • Optionaldeaths?: number

      Number of deaths this turn.

    • Optionalmorale?: number

      Aggregate morale 0..1 (population-weighted).

    • population: number

      Aggregate counts derived from agents.

    • OptionalscenarioExtensions?: Record<string, unknown>

    • time: number

      Scenario time at snapshot (years/quarters/ticks per scenario).

    • turn: number

      Turn number this snapshot was taken at (0-indexed).

  • Optionalfingerprint?: Record<string, string | number>

    Loose classification scores. Paracosm heritage; scenarios may extend.

  • OptionalforgedTools?: {
        approved: boolean;
        confidence?: number;
        department?: string;
        description?: string;
        name: string;
    }[]

  • Optionalintervention?: {
        adherenceProfile?: { expected: number; risks?: string[] };
        category?: string;
        description: string;
        duration?: { unit: string; value: number };
        id: string;
        mechanism?: string;
        name: string;
        scenarioExtensions?: Record<string, unknown>;
        targetBehaviors?: string[];
    }

    Intervention being tested on the subject.

  • OptionalleveragePoints?: string[]

    Actionable leverage points for consumers of the artifact.

  • metadata: {
        completedAt?: string;
        forkedFrom?: { atTurn: number; parentRunId: string };
        mode: "turn-loop" | "batch-trajectory" | "batch-point";
        runId: string;
        scenario: { id: string; name: string; version?: string };
        scenarioExtensions?: Record<string, unknown>;
        seed?: number;
        startedAt: string;
    }

    Required. Identifies the run + scenario + mode.

    • OptionalcompletedAt?: string

    • OptionalforkedFrom?: { atTurn: number; parentRunId: string }

      When this run was produced by forking a prior run, records the parent run-id + the turn at which the fork happened. Consumers walking a fork chain follow this link transitively through stored artifacts. Omitted for fresh (non-forked) runs.

      Added in 0.7.x with the WorldModel.fork() API. Additive + optional; no COMPILE_SCHEMA_VERSION bump required.

    • mode: "turn-loop" | "batch-trajectory" | "batch-point"

    • runId: string

      Unique identifier for this run. UUID, slug, or host-assigned id.

    • scenario: { id: string; name: string; version?: string }

      • id: string

      • name: string

      • Optionalversion?: string

        Scenario version; not artifact version. Optional.

    • OptionalscenarioExtensions?: Record<string, unknown>

    • Optionalseed?: number

      Absent for non-deterministic runs (LLM-only synthesis without a seeded kernel).

    • startedAt: string

  • Optionaloverview?: string

    Short headline summary. Digital-twin overview, paracosm verdict's summary, a game's end-of-run narrator line.

  • OptionalproviderError?:
        | {
            actionUrl?: string;
            kind: "unknown"
            | "auth"
            | "quota"
            | "rate_limit"
            | "network";
            message: string;
            provider: string;
        }
        | null

  • OptionalriskFlags?: {
        detail: string;
        label: string;
        scenarioExtensions?: Record<string, unknown>;
        severity: "low" | "medium" | "high";
    }[]

    Risk callouts. Maps to digital-twin risk_flags after camelCase rename.

  • OptionalscenarioExtensions?: Record<string, unknown>

  • OptionalspecialistNotes?: {
        confidence?: number;
        detail?: {
            citations?: {
                context: string;
                doi?: string;
                text: string;
                url: string;
            }[];
            openQuestions?: string[];
            opportunities?: { description: string; impact: "low"
            | "medium"
            | "high" }[];
            recommendedActions?: string[];
            risks?: {
                description: string;
                severity: "low" | "medium" | "high" | "critical";
            }[];
        };
        domain: string;
        scenarioExtensions?: Record<string, unknown>;
        summary: string;
        trajectory?: "positive" | "negative" | "neutral" | "mixed";
    }[]

    Specialist analyses across domains. Flat list; multiple entries per domain/turn OK.

  • Optionalsubject?: {
        conditions?: string[];
        id: string;
        markers?: {
            category?: string;
            id: string;
            interpretation?: string;
            value?: string;
        }[];
        name: string;
        personality?: Record<string, number>;
        profile?: Record<string, unknown>;
        scenarioExtensions?: Record<string, unknown>;
        signals?: {
            label: string;
            recordedAt?: string;
            unit?: string;
            value: string | number;
        }[];
    }

    Subject being simulated (person, character, organism, vessel, etc.).

  • Optionaltrajectory?: {
        points?: {
            metrics: Record<string, number>;
            scenarioExtensions?: Record<string, unknown>;
            time: number;
        }[];
        timepoints?: {
            confidence?: number;
            highlightMetrics?: {
                color?: string;
                direction?: "up"
                | "down"
                | "stable";
                label: string;
                value: string;
            }[];
            label: string;
            narrative?: string;
            reasoning?: string;
            scenarioExtensions?: Record<string, unknown>;
            score?: { label: string; max: number; min: number; value: number };
            time: number;
            worldSnapshot?: {
                capacities?: Record<string, number>;
                environment?: Record<string, (...) | (...) | (...) | (...)>;
                metrics: Record<string, number>;
                politics?: Record<string, (...) | (...) | (...) | (...)>;
                scenarioExtensions?: Record<string, unknown>;
                statuses?: Record<string, (...) | (...) | (...)>;
            };
        }[];
        timeUnit: { plural: string; singular: string };
    }

    Labeled trajectory of the simulation. trajectory.points for sparklines, trajectory.timepoints for rich labeled snapshots. Both optional; at least one populated in turn-loop and batch-trajectory modes.

    • Optionalpoints?: {
          metrics: Record<string, number>;
          scenarioExtensions?: Record<string, unknown>;
          time: number;
      }[]

      Lightweight per-sample metric records; good for sparklines.

    • Optionaltimepoints?: {
          confidence?: number;
          highlightMetrics?: {
              color?: string;
              direction?: "up" | "down" | "stable";
              label: string;
              value: string;
          }[];
          label: string;
          narrative?: string;
          reasoning?: string;
          scenarioExtensions?: Record<string, unknown>;
          score?: { label: string; max: number; min: number; value: number };
          time: number;
          worldSnapshot?: {
              capacities?: Record<string, number>;
              environment?: Record<string, (...) | (...) | (...) | (...)>;
              metrics: Record<string, number>;
              politics?: Record<string, (...) | (...) | (...) | (...)>;
              scenarioExtensions?: Record<string, unknown>;
              statuses?: Record<string, (...) | (...) | (...)>;
          };
      }[]

      Rich labeled snapshots with narrative + score; good for timepoint cards.

    • timeUnit: { plural: string; singular: string }