@obversa/runtime 0.1.0

package/dist/core/stats.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Stats collector. Subscribes to the event stream and accumulates everything
+ * a host status view needs: per-loop iteration counts, review
+ * pass/fail tallies, token usage by model, errors, and wall-clock timing.
+ */
+import type { LoopEvent, Outcome } from './types.js';
+export interface LoopStat {
+    path: string;
+    iterations: number;
+    reviewsPassed: number;
+    reviewsFailed: number;
+    lastStatus?: Outcome['status'];
+}
+export interface ModelUsage {
+    model: string;
+    calls: number;
+    reportedCalls: number;
+    unknownUsageCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+}
+export interface ErrorEntry {
+    path: string;
+    code: string;
+    message: string;
+    ts: number;
+}
+export interface StatsSnapshot {
+    startedAt: number;
+    elapsedMs: number;
+    loopRuns: LoopStat[];
+    models: ModelUsage[];
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    /**
+     * What the whole run created and read from cache. The per-model breakdown
+     * carried these already; the run-wide totals did not, so nothing could
+     * answer "what did this run read from cache" without summing models by hand.
+     */
+    totalCacheCreationInputTokens: number;
+    totalCacheReadInputTokens: number;
+    /**
+     * How many calls reported no usage at all. The per-call line says "usage
+     * unknown" rather than inventing a zero; without this the aggregate quietly
+     * drops those calls and a total that might be missing three of them looks
+     * complete.
+     */
+    totalUnmeasuredCalls: number;
+    agentCalls: number;
+    errors: ErrorEntry[];
+}
+export declare class Stats {
+    private readonly startedAt;
+    private readonly loopRuns;
+    private readonly models;
+    private readonly errors;
+    record(event: LoopEvent): void;
+    snapshot(): StatsSnapshot;
+    private loopFor;
+    private modelFor;
+}

package/dist/core/team.d.ts

@@ -0,0 +1,34 @@
+import type { CallbackGateDefinition } from '../callback/gate.js';
+import type { EngineRef } from '../engines/engine.js';
+import { type ReviewPanelConfig } from './feedback.js';
+import type { Job, Outcome } from './types.js';
+export interface TeamAgent {
+    name: string;
+    role: string;
+    brief: string;
+    engine: EngineRef;
+}
+export type TeamReview = {
+    kind: 'panel';
+    config: ReviewPanelConfig;
+} | {
+    kind: 'callback';
+    definition: CallbackGateDefinition;
+};
+export interface TeamConfig {
+    task: string;
+    agents: readonly TeamAgent[];
+    review?: TeamReview;
+}
+export interface TeamAgentResult {
+    name: string;
+    role: string;
+    outcome: Outcome;
+}
+export interface TeamResult {
+    task: string;
+    agents: readonly TeamAgentResult[];
+    integrated: boolean;
+    review?: Outcome;
+}
+export declare function team(config: TeamConfig): Job;

package/dist/core/text.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared text helpers, so the same trim/truncate logic isn't re-implemented
+ * (subtly differently) across modules.
+ */
+/** Collapse all runs of whitespace to single spaces, and trim. */
+export declare function oneLine(text: string): string;
+/** Truncate to `max` chars, appending a `\n…` marker when it overflows. */
+export declare function truncate(s: string, max: number): string;

package/dist/core/tournament.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tournament runs alternative approaches to the same task. Where a DAG fans out
+ * disjoint work and lands all of it, a tournament runs N candidates, each in its own
+ * isolated worktree, judges them, lands only the winner and discards the rest.
+ *
+ * It composes over the worktree primitives, no new machinery. Only one branch is ever
+ * merged (the winner, off an unchanged HEAD), so there is no conflict to resolve.
+ */
+import type { Job, JobContext, Outcome } from './types.js';
+export interface TournamentConfig {
+    name: string;
+    /** Candidates to run. */
+    n: number;
+    /** Build the candidate job for attempt `i` (0-based): same task, varied angle. */
+    candidate: (i: number) => Job;
+    /**
+     * Score a finished candidate (higher wins). Run against the candidate's own
+     * context, so it can read the candidate's workspace. The highest-scoring
+     * passing candidate lands back; ties break to the earliest.
+     */
+    judge: (outcome: Outcome, ctx: JobContext) => number | Promise<number>;
+    /** Max candidates running at once. Default `n`. */
+    concurrency?: number;
+}
+export declare function tournament(config: TournamentConfig): Job;