@sayknow-cli/coding-agent 0.3.4 → 0.3.6

package/dist/types/skc-runtime/ledger-event-renderer.d.ts

@@ -1,68 +0,0 @@
-/**
- * Pure parse + summarize for ledger-backed skill observability.
- *
- * Workflow progress for ultragoal/ralplan cannot be observed via subagent tool
- * events (those skills persist through `bash`-backed `skc` CLI calls whose tool
- * `details` carry no structured payload). The durable source of truth is the
- * append-only ledgers:
- *   - ultragoal: `.skc/ultragoal/ledger.jsonl`
- *   - ralplan:   `.skc/plans/ralplan/<run-id>/index.jsonl`
- *
- * This module is I/O-free: callers read the files and pass lines or already-parsed
- * rows. It feeds the compact HUD chip builders in `skill-state/workflow-hud.ts`
- * via the runtime sync paths. Display-string helpers stay theme-free.
- */
-/** Minimal projection of an ultragoal ledger row used for the HUD chip. */
-export interface UltragoalLedgerEventLite {
-    /** Normalized from the row's `event` field, or `type` for reconcile rows. */
-    event: string;
-    goalId?: string;
-    status?: string;
-    timestamp?: string;
-}
-/**
- * Coerce an already-parsed ledger row into the lite shape. Accepts both the
- * `event`-keyed vocabulary (plan_created, goal_started, goal_checkpointed,
- * steering_accepted/rejected, review_blockers_recorded) and the `type`-keyed
- * reconcile-failure row (`type: "reconcile_failed"`). Returns undefined when no
- * event/type discriminator is present.
- */
-export declare function coerceUltragoalLedgerEvent(row: Record<string, unknown>): UltragoalLedgerEventLite | undefined;
-/** Parse a single ultragoal ledger JSONL line; undefined for blank/malformed lines. */
-export declare function parseUltragoalLedgerLine(line: string): UltragoalLedgerEventLite | undefined;
-/** The most recent event, or undefined when the ledger is empty. */
-export declare function latestUltragoalLedgerEvent(events: readonly UltragoalLedgerEventLite[]): UltragoalLedgerEventLite | undefined;
-/**
- * Best-effort latest event from raw ledger text: parses line-by-line and skips
- * blank/malformed rows so a torn or hand-edited ledger never throws on the HUD
- * path. Strict receipt consumers should keep using the validating reader.
- */
-export declare function latestUltragoalLedgerEventFromText(text: string): UltragoalLedgerEventLite | undefined;
-/** Minimal projection of a ralplan `index.jsonl` row. */
-export interface RalplanIndexRow {
-    stage: string;
-    stageN?: number;
-}
-/** Parse a single ralplan index JSONL line; undefined for blank/malformed lines. */
-export declare function parseRalplanIndexLine(line: string): RalplanIndexRow | undefined;
-export interface RalplanIndexSummary {
-    /** Number of consensus iterations (planner/revision boundaries), >= 0. */
-    iteration: number;
-    /** Stage names present in the current (latest) iteration, in append order. */
-    currentStages: string[];
-}
-/**
- * Derive iteration count and current-iteration stage presence from index rows.
- *
- * `stage_n` is NOT used as the iteration key: it is stored verbatim per row and a
- * single planner/architect/critic pass can span multiple stage_n values. Instead,
- * a `planner` or `revision` row opens a new iteration and subsequent rows attach
- * to it. No verdict is derived here (index rows carry none).
- */
-export declare function summarizeRalplanIndex(rows: readonly RalplanIndexRow[]): RalplanIndexSummary;
-/**
- * Compact, theme-free presence string for the ralplan `stages` chip, e.g.
- * `P·A·C`. Collapses past `cap` with a "… N more" suffix. Returns undefined when
- * there are no stages.
- */
-export declare function formatRalplanStagePresence(stages: readonly string[], cap?: number): string | undefined;

package/dist/types/skc-runtime/psmux-detect.d.ts

@@ -1,78 +0,0 @@
-/**
- * Windows psmux detection and tmux-binary resolution.
- *
- * Recent psmux releases (see docs/compatibility.md in the psmux repo) close
- * the round-trip gap for set-option / show-options user options and the
- * set-window-option profile values skc emits, which is what unblocks the
- * native Windows skc --tmux path. This module detects that capability so skc
- * can pick psmux when tmux is missing on Windows, and so callers can decide
- * whether to treat a given tmux binary as psmux (affecting e.g. the untagged
- * diagnostic wording and namespace handling).
- *
- * The probe is intentionally lightweight: it runs a single tmux -V (or
- * --version) once per process and caches the verdict. Cache invalidation
- * knobs:
- *   - force: true re-probes on every call (used by tests).
- *   - SKC_PSMUX_FORCE_DETECT=1 re-probes each call.
- *   - SKC_PSMUX_DETECTION=off skips probing entirely.
- */
-export declare const SKC_PSMUX_COMMAND_ENV = "SKC_PSMUX_COMMAND";
-export declare const SKC_PSMUX_DETECTION_ENV = "SKC_PSMUX_DETECTION";
-export declare const SKC_PSMUX_FORCE_DETECT_ENV = "SKC_PSMUX_FORCE_DETECT";
-/** Names that psmux installs as the canonical executable / alias. */
-export declare const PSMUX_BINARY_NAMES: readonly ["psmux", "pmux", "tmux"];
-export type PsmuxSpawnRunner = (command: string, args: string[]) => {
-    exitCode: number | null;
-    stdout?: string;
-    stderr?: string;
-};
-/**
- * Resolves a tmux-class binary name (e.g. "psmux", "tmux") to an absolute
- * filesystem path or returns null when the binary cannot be located. The
- * default implementation uses `Bun.which`; production callers leave it
- * alone and unit tests inject a stub via `__setBinaryResolverForTests`
- * so the version-banner probe can be exercised hermetically.
- */
-export type BinaryResolver = (candidate: string) => string | null;
-/** @internal Test-only seam; production code never calls this. */
-export declare function __setBinaryResolverForTests(resolver: BinaryResolver | null): void;
-export declare function envDisabled(value: string | undefined): boolean;
-/**
- * Decide whether command resolves to a psmux binary by probing its version
- * output. The result is cached per process unless force is set or
- * SKC_PSMUX_FORCE_DETECT=1.
- */
-export declare function detectPsmux(command: string, options?: {
-    force?: boolean;
-    env?: NodeJS.ProcessEnv;
-    runner?: PsmuxSpawnRunner;
-}): boolean;
-export interface ResolveSkcTmuxBinaryOptions {
-    platform?: NodeJS.Platform;
-    env?: NodeJS.ProcessEnv;
-    runner?: PsmuxSpawnRunner;
-}
-export interface ResolvedTmuxBinary {
-    command: string;
-    isPsmux: boolean;
-    viaExplicitOverride: boolean;
-}
-/**
- * Resolve the tmux command SKC should invoke. Honors the existing
- * SKC_TMUX_COMMAND / SKC_TEAM_TMUX_COMMAND overrides; on Windows when no
- * override is set, psmux (installed as psmux, pmux, or tmux) is picked
- * automatically so the default skc --tmux flow lands on a real multiplexer.
- */
-export declare function resolveSkcTmuxBinary(options?: ResolveSkcTmuxBinaryOptions): ResolvedTmuxBinary;
-/** Test-only helper: drop the in-process detection cache. */
-export declare function clearPsmuxDetectionCache(): void;
-export interface PsmuxProbe {
-    command: string;
-    versionOutput: string;
-    isPsmux: boolean;
-}
-export declare function probePsmux(command: string, options?: {
-    env?: NodeJS.ProcessEnv;
-    runner?: PsmuxSpawnRunner;
-    force?: boolean;
-}): PsmuxProbe;

package/dist/types/skc-runtime/ralplan-runtime.d.ts

@@ -1,25 +0,0 @@
-/**
- * Native implementation of `skc ralplan`.
- *
- * Two invocation shapes are handled natively:
- *
- * 1. **Consensus handoff**: `skc ralplan [--interactive] [--deliberate] [--architect <kind>]
- *    [--critic <kind>] [--session-id <id>] "<task>"` validates the documented flag surface,
- *    seeds `.skc/state/ralplan-state.json`, and updates the shared HUD rail via
- *    `syncSkillActiveState`. The CLI never *runs* the Planner / Architect / Critic loop itself —
- *    that lives in the bundled `/skill:ralplan` skill — but it accepts every documented flag so
- *    scripted users see a useful response and the active run is visible to the TUI.
- *
- * 2. **Artifact write**: `skc ralplan --write --stage <type> --stage_n <N> --artifact
- *    <path-or-string> [--run-id <id>] [--session-id <id>] [--json]` persists Planner / Architect
- *    / Critic / revision / post-interview / ADR / final markdown under `.skc/plans/ralplan/<run-id>/`, maintains
- *    an `index.jsonl` audit log, copies `final` stages to `pending-approval.md`, and advances
- *    the HUD chip to reflect the latest persisted stage.
- */
-export interface RalplanCommandResult {
-    status: number;
-    stdout?: string;
-    stderr?: string;
-}
-export declare function isRalplanArtifactWriteInvocation(args: readonly string[]): boolean;
-export declare function runNativeRalplanCommand(args: string[], cwd?: string): Promise<RalplanCommandResult>;

package/dist/types/skc-runtime/restricted-role-agent-bash.d.ts

@@ -1,2 +0,0 @@
-export declare const SKC_RESTRICTED_ROLE_AGENT_BASH_ENV = "SKC_RESTRICTED_ROLE_AGENT_BASH";
-export declare function isRestrictedRoleAgentBash(): boolean;

package/dist/types/skc-runtime/session-layout.d.ts

@@ -1,59 +0,0 @@
-export declare const SKC_DIR = ".skc";
-export declare const SKC_SESSION_PREFIX = "_session-";
-export declare const SKC_SESSION_ACTIVITY_FILE = ".session-activity.json";
-/** Source that produced a resolved SKC session id, for audit/diagnostics. */
-export type SkcSessionSource = "flag" | "payload" | "env" | "latest";
-export interface SkcSessionContext {
-    skcSessionId: string;
-    sessionRoot: string;
-    source: SkcSessionSource;
-}
-/**
- * Encode a session id into a single safe path segment. Matches the historical
- * encoding used across the runtimes so ids round-trip identically:
- * `encodeURIComponent` plus dot-escaping (dots are legal in filenames but we
- * avoid `.`/`..` traversal ambiguity).
- */
-export declare function encodeSessionSegment(value: string): string;
-/** Inverse of {@link encodeSessionSegment}. */
-export declare function decodeSessionSegment(segment: string): string;
-/** Throw when a session id is missing or blank; never let blank suppress callers. */
-export declare function assertNonEmptySkcSessionId(value: string | undefined, source: string): asserts value is string;
-/**
- * Assert a value is safe to use as a single path segment: non-blank and free of
- * path separators or `.`/`..` traversal. Use for already-safe identifiers
- * (skill modes, slugs) where we want identical filenames but fail closed on
- * traversal rather than silently normalizing out of the intended directory.
- */
-export declare function assertSafePathComponent(value: string, label: string): void;
-/** The shared `.skc/` root (holds shared config; never session-scoped). */
-export declare function skcRoot(cwd: string): string;
-/** The per-session root directory: `<cwd>/.skc/_session-{encodedId}`. */
-export declare function sessionRoot(cwd: string, skcSessionId: string): string;
-/** Directory name (no path) for a session id, e.g. `_session-abc`. */
-export declare function sessionDirName(skcSessionId: string): string;
-/** Return the decoded session id for a `_session-*` directory name, else undefined. */
-export declare function sessionIdFromDirName(name: string): string | undefined;
-/** Authoritative per-session activity marker path. */
-export declare function sessionActivityPath(cwd: string, skcSessionId: string): string;
-export declare function sessionStateDir(cwd: string, skcSessionId: string): string;
-export declare function sessionSpecsDir(cwd: string, skcSessionId: string): string;
-export declare function sessionPlansDir(cwd: string, skcSessionId: string): string;
-export declare function sessionUltragoalDir(cwd: string, skcSessionId: string): string;
-export declare function sessionAuditDir(cwd: string, skcSessionId: string): string;
-export declare function sessionReportsDir(cwd: string, skcSessionId: string): string;
-export declare function sessionLogsDir(cwd: string, skcSessionId: string): string;
-export declare function sessionRuntimeDir(cwd: string, skcSessionId: string): string;
-export declare function sessionRlmDir(cwd: string, skcSessionId: string): string;
-export declare function activeStateDir(cwd: string, skcSessionId: string): string;
-export declare function activeSnapshotPath(cwd: string, skcSessionId: string): string;
-export declare function activeEntryPath(cwd: string, skcSessionId: string, skill: string): string;
-export declare function modeStatePath(cwd: string, skcSessionId: string, mode: string): string;
-export declare function auditPath(cwd: string, skcSessionId: string): string;
-export declare function transactionJournalPath(cwd: string, skcSessionId: string, mutationId: string): string;
-export declare function teamStateRoot(cwd: string, skcSessionId: string): string;
-export declare function workflowGatePath(cwd: string, skcSessionId: string, gateId: string): string;
-export declare function harnessStateRoot(cwd: string, skcSessionId: string): string;
-export declare function coordinatorMcpStateRoot(cwd: string, skcSessionId: string): string;
-export declare function tmuxRuntimeSessionPath(cwd: string, skcSessionId: string, slug: string): string;
-export declare function rlmArtifactRoot(cwd: string, skcSessionId: string, rlmSessionId: string): string;

package/dist/types/skc-runtime/session-resolution.d.ts

@@ -1,47 +0,0 @@
-import { type SkcSessionContext, type SkcSessionSource } from "./session-layout";
-/** Window within which two activity timestamps are treated as an ambiguous tie. */
-export declare const LATEST_SESSION_TIE_WINDOW_MS = 1000;
-export interface SessionIdSources {
-    /** Raw `--session-id` value: `undefined` = flag absent; `""` = present-but-blank (invalid). */
-    flagValue?: string | undefined;
-    payloadSessionId?: unknown;
-    envSessionId?: string | undefined;
-}
-export declare class SessionResolutionError extends Error {
-    readonly code: "blank_flag" | "no_session" | "ambiguous" | "missing_for_write";
-    constructor(message: string, code: "blank_flag" | "no_session" | "ambiguous" | "missing_for_write");
-}
-interface ResolvedFromSources {
-    skcSessionId: string;
-    source: SkcSessionSource;
-}
-/**
- * Resolve a session id from explicit sources only (flag -> payload -> env).
- * Returns `undefined` when none is present. A blank explicit flag throws.
- */
-export declare function resolveSessionIdFromSources(sources: SessionIdSources): ResolvedFromSources | undefined;
-/** Resolve session context for a WRITE command. Errors when no explicit id is present. */
-export declare function resolveSkcSessionForWrite(cwd: string, sources: SessionIdSources): SkcSessionContext;
-/**
- * Resolve session context for a READ/STATUS/CLEAR command. Falls back to the
- * latest active session by activity marker when no explicit id is present.
- */
-export declare function resolveSkcSessionForRead(cwd: string, sources: SessionIdSources): Promise<SkcSessionContext>;
-/**
- * Scan `.skc/_session-*` directories and select the most-recently-active one by
- * its activity marker. Never uses raw directory mtime. Throws on zero candidates
- * or an ambiguous tie.
- */
-export declare function detectLatestSession(cwd: string): Promise<SkcSessionContext>;
-export interface ActivityMarkerInfo {
-    writer: string;
-    /** Relative generated path that was just written, for diagnostics. */
-    path?: string;
-}
-/**
- * Best-effort write of the per-session activity marker. State-command callers
- * MUST treat a thrown error as a command failure (auto-detect depends on it);
- * non-critical writers may swallow it.
- */
-export declare function writeSessionActivityMarker(cwd: string, skcSessionId: string, info: ActivityMarkerInfo): Promise<void>;
-export {};

package/dist/types/skc-runtime/session-state-sidecar.d.ts

@@ -1,27 +0,0 @@
-export declare const SKC_COORDINATOR_SESSION_STATE_FILE_ENV = "SKC_COORDINATOR_SESSION_STATE_FILE";
-export declare const SKC_COORDINATOR_SESSION_ID_ENV = "SKC_COORDINATOR_SESSION_ID";
-export type RuntimeState = "ready_for_input" | "running" | "needs_user_input" | "completed" | "errored";
-interface RuntimeStateEvent {
-    type: string;
-    messages?: unknown[];
-}
-interface RuntimeStateContext {
-    sessionId: string;
-    cwd: string;
-    sessionFile?: string | null;
-}
-export type TerminalRuntimeStateStatus = {
-    terminal: true;
-    state: "completed" | "errored";
-} | {
-    terminal: false;
-    reason: "missing_state_file" | "invalid_json" | "session_id_mismatch" | "cwd_mismatch" | "session_file_mismatch" | "non_terminal_state";
-};
-export declare function readTerminalRuntimeStateMarker(input: {
-    stateFile?: string | null;
-    sessionId?: string | null;
-    cwd?: string | null;
-    sessionFile?: string | null;
-}): Promise<TerminalRuntimeStateStatus>;
-export declare function persistCoordinatorRuntimeStateFromEvent(event: RuntimeStateEvent, context: RuntimeStateContext): Promise<void>;
-export {};

package/dist/types/skc-runtime/state-graph.d.ts

@@ -1,4 +0,0 @@
-import { type CanonicalSkcWorkflowSkill } from "../skill-state/canonical-skills";
-export type StateGraphSkill = CanonicalSkcWorkflowSkill | "all";
-export type StateGraphFormat = "ascii" | "mermaid" | "dot";
-export declare function renderStateGraph(skill: StateGraphSkill, format?: string): string;

package/dist/types/skc-runtime/state-migrations.d.ts

@@ -1,33 +0,0 @@
-import type { CanonicalSkcWorkflowSkill } from "../skill-state/active-state";
-export interface NormalizeLegacyStateResult {
-    state: Record<string, unknown>;
-    changed: boolean;
-}
-export interface MigrateAndPersistLegacyStateArgs {
-    cwd: string;
-    skill: string;
-    statePath: string;
-    sessionId?: string;
-}
-export interface MigrateAndPersistLegacyStateResult {
-    migrated: boolean;
-    path: string;
-}
-export interface MigrateWorkflowStateResult {
-    state: Record<string, unknown>;
-    fromVersion: number;
-    toVersion: number;
-    changed: boolean;
-}
-export type WorkflowStateMigration = (state: Record<string, unknown>, skill: CanonicalSkcWorkflowSkill) => Record<string, unknown>;
-export declare function migrateWorkflowState(raw: Record<string, unknown>, skill: string): MigrateWorkflowStateResult;
-/**
- * Pure legacy state normalizer for background/internal readers.
- *
- * Readers that need compatibility with old on-disk workflow state shapes must call
- * this in-memory helper and must never call `migrateAndPersistLegacyState`. The
- * persist variant is reserved for explicit state migration commands because it is
- * the only path allowed to write normalized upgrades back to `.skc/state/**`.
- */
-export declare function normalizeLegacyState(raw: Record<string, unknown>, skill: string): NormalizeLegacyStateResult;
-export declare function migrateAndPersistLegacyState(args: MigrateAndPersistLegacyStateArgs): Promise<MigrateAndPersistLegacyStateResult>;

package/dist/types/skc-runtime/state-renderer.d.ts

@@ -1,70 +0,0 @@
-import type { CanonicalSkcWorkflowSkill } from "../skill-state/active-state";
-import type { SkillManifest } from "./workflow-manifest";
-export declare const STATE_FIELD_ALLOWLIST: readonly ["skill", "phase", "current_phase", "next", "active", "status", "fresh", "fresh_until", "receipt", "artifact_path", "plan_path", "spec_path", "run_id", "stage", "stage_n", "session_id", "updated_at", "handoff_to", "handoff_from", "counts", "hud"];
-export type StateProjectionField = (typeof STATE_FIELD_ALLOWLIST)[number];
-export interface StateStatusSummary {
-    skill: CanonicalSkcWorkflowSkill;
-    phase: string;
-    active: boolean;
-    fresh: boolean;
-    fresh_until?: string;
-    next: string[];
-    receipt_status: string;
-    storage_path: string;
-}
-export declare function compactProjectStateJson(skill: CanonicalSkcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest): Record<string, unknown>;
-export declare function projectStateFields(skill: CanonicalSkcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest, fields: readonly StateProjectionField[]): Record<string, unknown>;
-export declare function buildStateStatusSummary(skill: CanonicalSkcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest, storagePath: string): StateStatusSummary;
-export declare function renderStateStatusLine(summary: StateStatusSummary): string;
-export declare function renderContractMarkdown(skill: CanonicalSkcWorkflowSkill, contract: unknown): string;
-export declare function renderHistoryMarkdown(history: {
-    entries: unknown[];
-    limit: number;
-    since?: string;
-    truncated: boolean;
-}): string;
-export declare function renderUltragoalStatusMarkdown(summary: {
-    exists: boolean;
-    status: string;
-    paths: {
-        goalsPath: string;
-        ledgerPath?: string;
-    };
-    skcObjective?: string;
-    currentGoal?: {
-        id: string;
-        status: string;
-        title?: string;
-        objective?: string;
-    };
-    counts: Record<string, number>;
-    goals: unknown[];
-    nudgeBudget?: number;
-    nudgeCount?: number;
-    nudgeRemaining?: number;
-    nudgeGoalId?: string;
-    nudgeTargetKind?: string;
-}): string;
-export declare function renderTeamStatusMarkdown(snapshot: {
-    team_name: string;
-    phase: string;
-    tmux_target?: string;
-    tmux_session?: string;
-    state_dir: string;
-    task_total: number;
-    task_counts: Record<string, number>;
-    workers: Array<{
-        id: string;
-        status: string;
-    }>;
-    notification_summary?: {
-        total: number;
-        replay_eligible: number;
-        by_state: Record<string, number>;
-    };
-    integration_by_worker?: Record<string, {
-        status?: string;
-        conflict_files?: string[];
-    }>;
-}): string;
-export declare function renderStateMarkdown(skill: CanonicalSkcWorkflowSkill, stateJson: Record<string, unknown>, manifest: SkillManifest): string;

package/dist/types/skc-runtime/state-runtime.d.ts

@@ -1,38 +0,0 @@
-import { type CanonicalSkcWorkflowSkill } from "../skill-state/active-state";
-/**
- * Native implementation of the `skc state read|write|clear` command surface.
- *
- * Simple file-receipt operations against session-scoped state under
- * `.skc/_session-{id}/state/`. This is the sanctioned CLI mediator for
- * mutation-guarded SKC state — agents call it instead of editing those files directly.
- */
-export interface StateCommandResult {
-    status: number;
-    stdout?: string;
-    stderr?: string;
-}
-/**
- * Reconcile a workflow skill's mode-state + active-state/HUD from a caller-derived
- * payload. Unlike `skc state write`, this is a derived repair: callers reconcile from
- * an authoritative source (e.g. the ultragoal plan/ledger), where intermediate
- * aggregate phases like ultragoal `active -> pending` are legitimate, so it bypasses
- * ONLY verb transition-edge validation while preserving schema validation,
- * unknown-phase rejection, version/checksum stamping, and audit/out-of-band tamper
- * detection. Receipts carry `owner: "skc-runtime"` and `verb: "reconcile"` so the
- * provenance is distinguishable from a user-initiated write.
- */
-export declare function reconcileWorkflowSkillState(options: {
-    cwd: string;
-    mode: CanonicalSkcWorkflowSkill;
-    sessionId?: string;
-    threadId?: string;
-    turnId?: string;
-    active: boolean;
-    phase: string;
-    payload: Record<string, unknown>;
-    sourceRevision?: number;
-}): Promise<{
-    stateFile: string;
-}>;
-export declare function readWorkflowStateJson(cwd: string, skill: CanonicalSkcWorkflowSkill, sessionId?: string): Promise<Record<string, unknown>>;
-export declare function runNativeStateCommand(args: string[], cwd?: string): Promise<StateCommandResult>;