@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/orchestration-shell/reducer.d.ts

@@ -0,0 +1,8 @@
+import { OrchestrationAction, OrchestrationState } from './types';
+/** Max conversation-buffer size per §5.1 line 469 ("bounded ring buffer (last 500 entries)"). */
+export declare const CONVERSATION_BUFFER_MAX = 500;
+/**
+ * Pure reducer. Returns a NEW state object on every dispatch — never
+ * mutates `state` in place. Map fields are cloned via `new Map(state.x)`.
+ */
+export declare function reducer(state: OrchestrationState, action: OrchestrationAction): OrchestrationState;

package/dist/orchestration-shell/root-discovery.d.ts

@@ -0,0 +1,25 @@
+export declare const DEFAULT_DISCOVERY_MAX_DEPTH = 2;
+export declare const DEFAULT_DISCOVERY_MAX_ROOTS = 25;
+type DiscoveryReason = 'git' | 'manifest' | 'fallback';
+export interface DiscoveredRepositoryRoot {
+    rootPath: string;
+    reason: DiscoveryReason;
+    manifestFile?: string;
+}
+export interface RepositoryRootDiscoveryResult {
+    launchDir: string;
+    rootPaths: string[];
+    roots: DiscoveredRepositoryRoot[];
+    maxDepth: number;
+    maxRoots: number;
+    omittedRootCount: number;
+    omittedAncestorRoots: string[];
+    prunedDirectoryCount: number;
+    capped: boolean;
+}
+export declare function discoverRepositoryRoots(deps?: {
+    launchDir?: string;
+    maxDepth?: number;
+    maxRoots?: number;
+}): Promise<RepositoryRootDiscoveryResult>;
+export {};

package/dist/orchestration-shell/route-browse.d.ts

@@ -0,0 +1,20 @@
+import type { OrchestrationStore } from './store';
+import type { LocalGemmaAdvisoryRunner } from '../planner/local-advisory';
+export interface RouteBrowseDeps {
+    store: OrchestrationStore;
+    /** Undefined when the local model isn't installed/enabled → no-model advisory. */
+    localAdvisoryRunner?: LocalGemmaAdvisoryRunner;
+    userPrompt: string;
+    browseUrls?: string[];
+    browseQuery?: string;
+    /** Recent conversation turns (for context-aware search-query formulation). */
+    priorTurns?: string[];
+    /** Esc-abort signal (shell-owned AbortController). */
+    signal?: AbortSignal;
+}
+/**
+ * Orchestrate a `browse` route. Fetch an explicit URL, or run a keyless web
+ * search and read the top result, then answer via local Gemma. Mirrors
+ * routeBrainstorm/routeFamiliarize (no-model advisory, clean failures, no crash).
+ */
+export declare function routeBrowse(deps: RouteBrowseDeps): Promise<void>;

package/dist/orchestration-shell/slash-router.d.ts

@@ -0,0 +1,64 @@
+import { OrchestrationAction, Tier } from './types';
+/**
+ * Side effects a handler can request the entrypoint to dispatch.
+ * The router itself never touches the store — keeps slash handling
+ * pure for unit testing.
+ *
+ * Widened to a 3-arm union by CP-1.d per `PHASE-CP-1-D-DESIGN.md` §4.8
+ * (lines 1060-1066). `[ADDITIVE WIDENING — CP-1.d]` — the §16 LOCK #10
+ * slash-command CATALOG (names + ownership patterns) is unchanged; the
+ * internal side-effect kind is implementation detail of the orchestration
+ * shell and never crosses the AppSync boundary.
+ */
+export type ShellAction = {
+    kind: 'EXIT';
+} | {
+    kind: 'REGENERATE_STRUCTURAL_SUMMARY';
+} | {
+    kind: 'OPT_IN_BODY_PATH';
+    path: string;
+};
+export interface SlashOutput {
+    /** Verbatim user input (including leading `/`). Echoed in the conversation entry. */
+    command: string;
+    /** Rendered text shown inline in `<ConversationPane>` (per §11). */
+    output: string;
+    /** Optional side effect; only `/quit` populates it in CP-1.a. */
+    sideEffect?: ShellAction;
+}
+/**
+ * Public, render-safe view of a catalog row for the autocomplete dropdown
+ * (`<InputBar>`). Carries no handler — keeps the UI decoupled from dispatch.
+ */
+export interface SlashCommandInfo {
+    name: string;
+    blurb: string;
+}
+/** True if `command` is a shell-exit command (`/quit` / `/exit`). */
+export declare function isExitCommand(command: string): boolean;
+/**
+ * §16 LOCK #10 + §5.1.5 + §11 row. Routes user input that starts with
+ * `/`. Per §17 Q3 RESOLVED disposition: EXACT-MATCH only. Unknown
+ * commands return a help hint.
+ */
+export declare function routeSlashCommand(input: string): SlashOutput;
+/**
+ * Render-safe catalog view for the autocomplete dropdown (TUI redesign
+ * 2026-06-29). Returns `{ name, blurb }` in `/help` order, filtered to the
+ * commands the given `tier` can RUN (so a Pro user isn't suggested Max-only
+ * `/audit` or `/team`). `tier` omitted → the full catalog. The deferred
+ * `/attach` is excluded (it is not a runnable command). The orchestration TUI
+ * only renders for Pro/Max, so FREE is effectively unreachable here.
+ */
+export declare function listSlashCommands(tier?: Tier): SlashCommandInfo[];
+/**
+ * Convenience helper for callers that wire the side effect directly
+ * into the store. CP-1.a's `cli.ts` uses this; CP-1.b/c may dispatch
+ * the resulting `slash-output` action plus the side effect.
+ */
+export declare function applySlashOutput(output: SlashOutput): {
+    storeAction: Extract<OrchestrationAction, {
+        type: 'SLASH_OUTPUT';
+    }>;
+    exit: boolean;
+};

package/dist/orchestration-shell/slash-routes/continuation.d.ts

@@ -0,0 +1,71 @@
+import type { ContinuationPacketReader } from '../../continuation/packet-reader';
+import type { AgentKind } from '../../continuation/types';
+export interface ContinuationCliResult {
+    exitCode: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    stdout: string;
+}
+/**
+ * Valid `CONTINUE_WITH` target agents (#585 #C10M-1) — the closed enum the CLI
+ * validates user input against. Exported so the local `/continue accept` path in
+ * `index.ts` can validate the SERVER echo's `target_agent` through the SAME
+ * gate (first-wins: the echo's agent is authoritative, fail closed on anything
+ * outside this set).
+ */
+export declare const VALID_TARGET_AGENTS: ReadonlyArray<AgentKind>;
+/**
+ * PHASE-CP-10-MIN (#585) — the active-task context the `/continue request`
+ * subcommand needs to build the `PacketWriteInput`. Resolved by the entrypoint
+ * from the QuorumLoop's active loop state. `null` when no task is active.
+ */
+export interface ActiveContinuationRequestContext {
+    taskId: string;
+    gateId: string;
+    roundNumber: number;
+    brief: string;
+    sourceAgent: AgentKind;
+}
+/**
+ * PHASE-CP-10-MIN (#585) — the active continuation-handoff PROMPT context the
+ * `/continue accept` subcommand needs. Resolved by the entrypoint via Option A
+ * (the most-recent unresolved `continuation_offer_handoff` gate-prompt — from
+ * the store, or a `listEvents` piggyback). `null` when no offer is active.
+ */
+export interface ActiveContinuationOfferContext {
+    taskId: string;
+    gateId: string;
+    sessionId: string;
+    currentRound: number;
+    offerId: string;
+}
+export interface ContinuationCliDeps {
+    reader: ContinuationPacketReader;
+    /**
+     * PHASE-CP-10-MIN (#585) #C10M-9/16 — `/continue request <target?>`: fire the
+     * `user_requested` continuation trigger for the active task. The entrypoint
+     * wires this to abort the running implementor (Codex-H1) THEN call
+     * `QuorumLoop.requestContinuation()` (the §3.5 H1 path — `writer.write()` →
+     * server stamps + emits the prompt). Resolves the minted `offerId` (or null
+     * on failure). ABSENT → `request` reports "unavailable".
+     */
+    request?: (ctx: ActiveContinuationRequestContext, targetAgent: AgentKind | undefined) => Promise<{
+        offerId: string;
+    } | null>;
+    /** Resolve the active-task request context (loop state). `null` if no active task. */
+    getActiveRequestContext?: () => ActiveContinuationRequestContext | null;
+    /**
+     * PHASE-CP-10-MIN (#585) #C10M-9/11 — `/continue accept <target>`: the
+     * rescue/headless path. The entrypoint wires this to call
+     * `applyUserDecision({decision:'continue_with', notes: encrypt(target)})` AND
+     * drive the local `resumeFromContinuation` (with the `resumedOffers` dedupe).
+     * Resolves true on success. ABSENT → `accept` reports "unavailable".
+     */
+    accept?: (ctx: ActiveContinuationOfferContext, targetAgent: AgentKind) => Promise<boolean>;
+    /** Resolve the active continuation-handoff offer context. `null` if none. */
+    getActiveOfferContext?: () => ActiveContinuationOfferContext | null;
+}
+/**
+ * Dispatch a single `/continuation` invocation. Returns the exit code
+ * + stdout the shell should render. Caller wires `exitCode` into the
+ * `codevibe status` top-level binary's `process.exit(...)`.
+ */
+export declare function runContinuationCli(deps: ContinuationCliDeps, args: string[]): Promise<ContinuationCliResult>;

package/dist/orchestration-shell/slash-routes/reviewers.d.ts

@@ -0,0 +1,41 @@
+import type { AppSyncClient } from '../../appsync';
+import type { ReviewerAgentSpec, UserReviewerPolicySnapshot } from '../../types/reviewer';
+import { detectInstalledAgents } from '../../orchestration';
+/**
+ * Human-readable, ANSI-free rendering of a reviewer-policy snapshot. Renders ONLY
+ * the readable+writable policy surface (detected agents + the reviewer panel). The
+ * legacy `orchestrationEnabledDefault` opt-in was removed in CP-1 (2.0
+ * orchestration is shell-driven, not a stored flag — `queries.ts` does not select
+ * it: selecting it 401s on a post-CP-1 schema), so it is intentionally NOT shown
+ * (it would always render a misleading default).
+ */
+export declare function formatReviewerPolicy(snapshot: UserReviewerPolicySnapshot): string;
+/**
+ * Fetches + formats the user's reviewer panel. Re-pushes the locally detected
+ * agents (idempotent) and renders the returned snapshot. Never throws — returns
+ * a friendly error line so `/reviewers` can't crash the shell turn.
+ */
+export declare function runReviewersCli(client: AppSyncClient): Promise<string>;
+/**
+ * Tier-agnostic payload for opening the `/reviewer-setup` wizard: the host's
+ * detected agents + the user's current policy. The caller folds in the session
+ * `tier` to build the full `ReviewerWizardState`.
+ */
+export interface ReviewerWizardData {
+    installedAgents: ReturnType<typeof detectInstalledAgents>;
+    currentSeats: ReviewerAgentSpec[] | null;
+}
+/**
+ * Gathers everything the interactive wizard needs to render synchronously:
+ * detects installed agents (the only valid reviewer choices) and reads back the
+ * current policy via the idempotent `updateAvailableAgents` round-trip. Never
+ * throws — returns a `{ ok:false, message }` the caller surfaces as an advisory
+ * (no agents installed, or a transport error) instead of opening an empty modal.
+ */
+export declare function loadReviewerWizardData(client: AppSyncClient, detectFn?: typeof detectInstalledAgents): Promise<{
+    ok: true;
+    data: ReviewerWizardData;
+} | {
+    ok: false;
+    message: string;
+}>;

package/dist/orchestration-shell/slash-suggest.d.ts

@@ -0,0 +1,29 @@
+import type { SlashCommandInfo } from './slash-router';
+/**
+ * True when the current input is a slash COMMAND still being typed — a `/`
+ * followed by zero or more NON-space chars (no space yet). Once a space is
+ * typed the command is complete and the user is entering args, so the
+ * dropdown hides. A bare `/` qualifies (shows the full list).
+ */
+export declare function isSlashCommandInProgress(value: string): boolean;
+/**
+ * Prefix-filters the (already tier-filtered) catalog by the in-progress
+ * command token, case-insensitively, preserving catalog order. Returns `[]`
+ * when the value is not a command-in-progress (so the caller hides the
+ * dropdown). A bare `/` returns the whole list.
+ */
+export declare function filterSlashSuggestions(value: string, commands: SlashCommandInfo[]): SlashCommandInfo[];
+/**
+ * Builds a single dropdown row as ONE physical line (≤ `maxCols`) so it can
+ * never wrap and inflate the dropdown's row count on a narrow terminal
+ * (Stage-2 r4). The marker (`❯ `/`  `) + padded name come first; the blurb is
+ * appended ONLY if there's room (no dangling trailing space when it doesn't
+ * fit), and the whole row is truncated to `maxCols`.
+ */
+export declare function formatSuggestionRow(opts: {
+    name: string;
+    blurb: string;
+    highlighted: boolean;
+    maxCols: number;
+    namePad: number;
+}): string;

package/dist/orchestration-shell/status-format.d.ts

@@ -0,0 +1,59 @@
+/** The planner runtime kind resolved once at boot (NOT a live probe). */
+export type PlannerRuntimeKind = 'hosted' | 'local_gemma_qat' | 'local_unavailable';
+/**
+ * Truncate `s` to at most `max` columns with a trailing ellipsis. (Uses JS
+ * string length as a column proxy — adequate for the width-1 glyphs we render.)
+ */
+export declare function truncate(s: string, max: number): string;
+export interface PlannerBadge {
+    /** User-facing badge text. */
+    text: string;
+    /** Ink color when the badge is a warning; omitted → render dim. */
+    color?: string;
+}
+/**
+ * Abbreviates an absolute project path for the status bar:
+ *   - `$HOME` prefix → `~`
+ *   - if still wider than `maxCols`, left-truncate with a leading `…` so the
+ *     most-specific (rightmost) directories stay visible.
+ *
+ * Pure: `homedir` is injected (no `os` dependency here) so tests can pin it.
+ */
+export declare function formatProjectPath(projectPath: string, homedir: string, maxCols: number): string;
+/**
+ * Strips a model tag for display: `gemma4:latest` → `gemma4`. Falls back to a
+ * neutral label when nothing usable is provided.
+ */
+export declare function prettyModelLabel(model: string | null | undefined): string;
+/**
+ * Maps the boot-time planner runtime kind → the right-hand status badge.
+ *   - `local_gemma_qat`  → dim `<label> · local`   (no color → caller renders dim)
+ *   - `local_unavailable`→ yellow degraded warning  (the ONE state worth surfacing —
+ *     NL routing is off; only deterministic slash commands work)
+ *   - `hosted`           → null (hosted planner retired → no badge)
+ *
+ * The badge is a boot-time FACT, not a live health light — copy avoids implying
+ * liveness (see design doc "Architecture grounding").
+ */
+export declare function plannerBadge(kind: PlannerRuntimeKind, label: string): PlannerBadge | null;
+export interface StatusLayout {
+    /** Combined `<cwd> · <tier>` for the left, truncated to fit. */
+    leftText: string;
+    /** Badge text for the right (possibly truncated; '' when no badge). */
+    badgeText: string;
+}
+/**
+ * Computes the one-line status-bar layout so `leftText` + the badge ALWAYS fit
+ * within `columns` at ANY width (Stage-2). The badge is truncated so the
+ * ` · <tier>` always has room; the left (`<cwd> · <tier>`) is then truncated to
+ * the remaining width — on a sub-tier-width terminal the cwd vanishes and even
+ * the tier shrinks rather than wrapping. `.length` is the column proxy (the
+ * glyphs we render are width-1). Pure → unit-tested directly.
+ */
+export declare function computeStatusLayout(args: {
+    cwd: string;
+    tier: string;
+    homedir: string;
+    columns: number;
+    badge: PlannerBadge | null;
+}): StatusLayout;

package/dist/orchestration-shell/sticky-preference.d.ts

@@ -0,0 +1,24 @@
+import { Mode, Tier } from './types';
+/**
+ * Filesystem location of the sticky preference file.
+ */
+export declare function stickyPreferenceFilePath(): string;
+/**
+ * §2 LOCK lines 103-116. Reads the sticky preference. Returns `null`
+ * on every failure mode the design names:
+ *   - file missing
+ *   - malformed JSON
+ *   - schema-version mismatch
+ *   - `pickedByTier === 'PRO'` but current tier is now `FREE`
+ *     (tier downgrade INVALIDATES the sticky)
+ */
+export declare function readStickyPreference(currentTier?: Tier): Promise<Mode | null>;
+/**
+ * Writes the sticky preference. Creates the parent directory if
+ * missing. Used by the orchestration-mode entrypoint after a user
+ * picks a mode via the interactive prompt.
+ */
+export declare function writeStickyPreference(args: {
+    mode: Mode;
+    pickedByTier: 'PRO' | 'MAX';
+}): Promise<void>;

package/dist/orchestration-shell/store.d.ts

@@ -0,0 +1,17 @@
+import { Session } from '../types';
+import { OrchestrationAction, OrchestrationState } from './types';
+export interface OrchestrationStore {
+    getState(): OrchestrationState;
+    dispatch(action: OrchestrationAction): void;
+    /**
+     * Subscribe to state changes. Returns an unsubscribe fn. The
+     * listener fires AFTER each dispatch with the new state.
+     */
+    subscribe(listener: (state: OrchestrationState) => void): () => void;
+}
+export interface CreateOrchestrationStoreArgs {
+    session: Session;
+    /** Optional initial state override for tests. */
+    initial?: Partial<OrchestrationState>;
+}
+export declare function createOrchestrationStore(args: CreateOrchestrationStoreArgs): OrchestrationStore;

package/dist/orchestration-shell/task-progress.d.ts

@@ -0,0 +1,122 @@
+/**
+ * One desktop-local progress phase. Discriminated by `phase`. Every variant is
+ * counts + labels + paths only — NEVER plaintext (see the module invariant).
+ */
+export type TaskProgressEvent = ({
+    phase: 'shadow_created';
+    round: number;
+} | {
+    phase: 'implementor_running';
+    round: number;
+    elapsedMs: number;
+    filesChanged?: number;
+} | {
+    phase: 'diff_captured';
+    round: number;
+    files: number;
+    created: number;
+    modified: number;
+    deleted: number;
+} | {
+    phase: 'submitting_diff';
+    round: number;
+} | {
+    phase: 'reviewers_dispatched';
+    gateId: string;
+    seats: number;
+} | {
+    phase: 'seat_update';
+    gateId: string;
+    seatId: number;
+    seatLabel: string;
+    state: 'running' | 'verdict_submitted';
+} | {
+    phase: 'verdicts_progress';
+    gateId: string;
+    received: number;
+    expected: number;
+} | {
+    phase: 'revise_round';
+    round: number;
+    feedbackSummary?: string;
+} | {
+    phase: 'round_failed';
+    round: number;
+    reason: string;
+} | {
+    phase: 'continuation_offered';
+    round: number;
+    reason: string;
+} | {
+    phase: 'declared_tests_skipped';
+    round: number;
+    paths: string[];
+} | {
+    phase: 'promoting';
+    files: number;
+} | {
+    phase: 'promoted';
+    files: number;
+} | {
+    phase: 'discarding';
+} | {
+    phase: 'discarded';
+} | {
+    phase: 'waiting_user';
+} | {
+    phase: 'planner_classifying';
+} | {
+    phase: 'familiarizing';
+} | {
+    phase: 'progress_cleared';
+}) & {
+    epoch?: number;
+    tokens?: number;
+};
+/** The callback the QuorumLoop invokes on each progress phase. */
+export type OnProgress = (event: TaskProgressEvent) => void;
+/**
+ * Format an elapsed-ms duration for the live timer: `M:SS` under an hour,
+ * `H:MM:SS` at/over an hour (design §6; matches Codex/Claude). Floored at 0 so an
+ * NTP backward step shows `0:00`, never a negative/huge value.
+ */
+export declare function formatElapsed(elapsedMs: number): string;
+export { finiteToken, unwrapClaudeJson } from '../reviewer/token-usage';
+/**
+ * [Phase 2 · P2-5] Humanize a token COUNT for the ` · ↓ <tokens>` segment. Pure;
+ * the input is an already-finite-non-negative integer (from `finiteToken`/
+ * `tokensFor`), defensively re-clamped so a stray caller can never render `NaN`.
+ *   • `n >= 999500` → `(n/1e6).toFixed(1)+'M'` (the 999500 boundary avoids
+ *     `999999 → "1000k"`).
+ *   • `n >= 1000`   → `v=n/1000`; `(v>=10 ? v.toFixed(0) : v.toFixed(1))+'k'`
+ *     (so `1.0k`/`9.9k` carry one decimal but `10k`/`57k`/`999k` carry none).
+ *   • else          → `String(n)`.
+ * The caller renders ONLY when `tokens && tokens > 0` (a `0`/absent count omits
+ * the whole segment), so `formatTokens(0)` is never surfaced.
+ */
+export declare function formatTokens(n: number): string;
+/**
+ * Whether a phase is a transient/spinner phase (an ephemeral live status line)
+ * vs a milestone that persists in scrollback. `implementor_running` (a ticking
+ * line) is the canonical spinner phase; `promoting`/`discarding` show a spinner
+ * while in flight. Everything else is a one-shot milestone.
+ *
+ * TODO(cleanup): production-UNUSED after the live-task-timer reducer rewrite (the
+ * reducer now classifies via the OPENER/REFRESH-ONLY/CLOSER trichotomy, not this
+ * helper). Kept + unit-tested for now; remove once single-track progress is stable.
+ */
+export declare function isSpinnerPhase(phase: TaskProgressEvent['phase']): boolean;
+/**
+ * Render the user-facing ONE-LINE text for a progress event. Pure (no plaintext
+ * — only counts/labels/paths/elapsed). The TUI shows spinner phases as an
+ * ephemeral live line and milestone phases as persisted scrollback entries.
+ */
+export declare function renderProgressLine(event: TaskProgressEvent): string;
+/**
+ * The BOUNDED label for the ephemeral LIVE line (design §5). Identical to
+ * `renderProgressLine` for the short phases, but path-bearing phases collapse to a
+ * count so the live line stays short (the FULL path list still persists in
+ * scrollback via `renderProgressLine`). The component additionally truncates this
+ * to the terminal width, timer-last, so the clock is never clipped.
+ */
+export declare function liveLabel(event: TaskProgressEvent): string;