@kynver-app/runtime 0.1.39 → 0.1.47

package/dist/command-center-contract-cli.d.ts

@@ -0,0 +1 @@
+export declare function runCommandCenterContractCli(args: Record<string, string | boolean>): Promise<void>;

package/dist/completion-ack.d.ts

@@ -0,0 +1,10 @@
+import type { HarnessWorkerRecord } from "./status.js";
+export type CompletionOutcome = "acknowledged" | "skipped_already_acked" | "structural_blocker";
+export interface CompletionAckFields {
+    completionReportedAt: string;
+    completionOutcome: "acknowledged" | "rejected";
+    completionResponse?: unknown;
+}
+export declare function hasCompletionAck(worker: HarnessWorkerRecord): boolean;
+export declare function persistCompletionAck(worker: HarnessWorkerRecord, runId: string, fields: CompletionAckFields): void;
+export declare function clearCompletionAck(worker: HarnessWorkerRecord, runId: string): void;

package/dist/completion-response.d.ts

@@ -0,0 +1,15 @@
+/** Parsed outcome from POST /harness/completion (AgentOS handleHarnessWorkerCompletion). */
+export type HarnessCompletionRouteOutcome = "review_scheduled" | "review_already_scheduled" | "needs_attention" | "mirror_only" | "task_not_found" | "task_not_harness" | "skipped_terminal_task";
+export interface HarnessCompletionResponseSummary {
+    routeOutcome: HarnessCompletionRouteOutcome | null;
+    /** True when the board task should have moved into review (or already was). */
+    taskAdvanced: boolean;
+    detail: string | null;
+}
+/**
+ * Classify a 2xx harness completion response. HTTP success alone is not enough:
+ * `needs_attention` (policy gate, dirty tree, missing artifact) still leaves the
+ * linked AgentTask blocked while the worker sidecar would otherwise report done.
+ */
+export declare function summarizeHarnessCompletionResponse(parsed: unknown): HarnessCompletionResponseSummary;
+export declare function completionPostSucceeded(summary: HarnessCompletionResponseSummary): boolean;

package/dist/config.d.ts

@@ -0,0 +1,61 @@
+export interface KynverUserConfig {
+    apiBaseUrl?: string;
+    agentOsSlug?: string;
+    agentOsId?: string;
+    defaultRepo?: string;
+    workerProvider?: string;
+    /** Default Claude model when dispatch does not infer or pass `--model`. */
+    defaultModel?: string;
+    harnessRoot?: string;
+    /** Max concurrent workers on this machine. Omit to auto-size from RAM. */
+    maxConcurrentWorkers?: number;
+    /** @internal Advanced tuning — not required for setup. */
+    perWorkerMemBytes?: number;
+    /** @internal Advanced tuning — not required for setup. */
+    memReserveBytes?: number;
+    /** @internal Advanced tuning — not required for setup. */
+    memUtilization?: number;
+}
+export declare function loadUserConfig(): KynverUserConfig;
+export declare function saveUserConfig(config: KynverUserConfig): void;
+/** Persist path fields with `~` instead of absolute home directories. */
+export declare function normalizeConfigPaths(config: KynverUserConfig): KynverUserConfig;
+/** Values for setup output (never emit `/home/<user>/…`). */
+export declare function presentUserConfig(config: KynverUserConfig): KynverUserConfig;
+export declare function loadApiKey(): string | undefined;
+export declare function saveApiKey(apiKey: string): void;
+export declare function loadRunnerToken(agentOsId?: string): string | undefined;
+export declare function saveRunnerToken(agentOsId: string, token: string): void;
+export declare function resolveBaseUrl(argsBaseUrl?: string): string;
+export declare function resolveCallbackSecret(argsSecret?: string, agentOsId?: string): string;
+export declare function resolveCallbackSecretWithMint(argsSecret?: string, agentOsId?: string, opts?: {
+    baseUrl?: string;
+}): Promise<string>;
+/**
+ * Force-mint a fresh scoped runner token for `agentOsId`, bypassing any cached
+ * or env token. Recovery path for a callback that 401s because the configured
+ * token is revoked, expired, or scoped to a *different* workspace (the
+ * self-linked repair case). Requires an API key + base URL to mint; returns
+ * `null` when a fresh token cannot be obtained, so the caller degrades to a
+ * structural blocker instead of papering the worker over as done.
+ */
+export declare function refreshRunnerToken(agentOsId: string, opts?: {
+    baseUrl?: string;
+}): Promise<string | null>;
+export declare function refreshRunnerTokenForAuthFailure(rejectedSecret: string, agentOsId: string, opts?: {
+    baseUrl?: string;
+}): Promise<{
+    ok: true;
+    token: string;
+} | {
+    ok: false;
+    reason: string;
+}>;
+export declare function fetchRunnerCredential(agentOsId: string, opts?: {
+    baseUrl?: string;
+    apiKey?: string;
+}): Promise<string>;
+export declare function mintRunnerCredential(args: Record<string, string | boolean>): Promise<void>;
+export declare function parseArgs(argv: string[]): Record<string, string | boolean>;
+export declare function runSetup(args: Record<string, string | boolean>): Promise<void>;
+export declare function runLogin(args: Record<string, string | boolean>): Promise<void>;

package/dist/daemon.d.ts

@@ -0,0 +1,5 @@
+export declare function runDaemon(args: Record<string, string | boolean>): Promise<void>;
+export { runPipelineTick } from "./pipeline-tick.js";
+export { dispatchRun } from "./dispatch.js";
+export { sweepRun } from "./sweep.js";
+export { completeWorker } from "./worker-ops.js";

package/dist/disk-gate.d.ts

@@ -0,0 +1,9 @@
+import type { DispatchNextDiskGateShape } from "./callbacks.js";
+export interface ObserveDiskGateInput {
+    diskPath?: string;
+    diskFreeWarnBytes?: number;
+    diskFreeCriticalBytes?: number;
+    diskMaxUsedPercent?: number;
+    diskHardMaxUsedPercent?: number;
+}
+export declare function observeRunnerDiskGate(input?: ObserveDiskGateInput): DispatchNextDiskGateShape;

package/dist/dispatch.d.ts

@@ -0,0 +1,16 @@
+import { runDirectory } from "./run-store.js";
+import type { InstructionPolicyEvidenceSnapshot, PersonaContextEvidenceSnapshot } from "./status.js";
+export declare const DEFAULT_DISPATCH_LEASE_MS: number;
+export interface HarnessWorkerDispatchContext {
+    instructionPolicyMarkdown: string | null;
+    instructionPolicyFingerprint: string | null;
+    instructionPolicyEvidence: InstructionPolicyEvidenceSnapshot | null;
+    personaMarkdown: string | null;
+    personaSlug: string | null;
+    personaEvidence: PersonaContextEvidenceSnapshot | null;
+    personaInjectionReady: boolean;
+}
+export declare function readHarnessWorkerContext(decision: Record<string, unknown>): HarnessWorkerDispatchContext | null;
+export declare function buildDispatchTaskText(task: Record<string, unknown>, agentOsId: string): string;
+export declare function dispatchRun(args: Record<string, string | boolean>): Promise<Record<string, unknown> | void>;
+export { runDirectory };

package/dist/doctor/doctor.types.d.ts

@@ -0,0 +1,25 @@
+export type DoctorCheckStatus = "pass" | "warn" | "fail";
+export interface DoctorCheck {
+    id: string;
+    label: string;
+    status: DoctorCheckStatus;
+    summary: string;
+    remediation?: string;
+    details?: Record<string, unknown>;
+}
+export interface DoctorSection {
+    id: string;
+    label: string;
+    checks: DoctorCheck[];
+}
+export interface RuntimeTakeoverDoctorReport {
+    command: "doctor runtime-takeover";
+    ready: boolean;
+    summary: string;
+    counts: {
+        pass: number;
+        warn: number;
+        fail: number;
+    };
+    sections: DoctorSection[];
+}

package/dist/doctor/index.d.ts

@@ -0,0 +1,4 @@
+export type { DoctorCheck, DoctorCheckStatus, DoctorSection, RuntimeTakeoverDoctorReport, } from "./doctor.types.js";
+export { assessRuntimeTakeoverReadiness, } from "./runtime-takeover.js";
+export { defaultRuntimeTakeoverProbes, type CommandProbeResult, type RuntimeTakeoverProbes, } from "./runtime-takeover.probes.js";
+export { runRuntimeTakeoverDoctorCli } from "./runtime-takeover-cli.js";

package/dist/doctor/runtime-takeover-cli.d.ts

@@ -0,0 +1 @@
+export declare function runRuntimeTakeoverDoctorCli(): void;

package/dist/doctor/runtime-takeover.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeTakeoverDoctorReport } from "./doctor.types.js";
+import { type RuntimeTakeoverProbes } from "./runtime-takeover.probes.js";
+export declare function assessRuntimeTakeoverReadiness(probes?: RuntimeTakeoverProbes): RuntimeTakeoverDoctorReport;

package/dist/doctor/runtime-takeover.probes.d.ts

@@ -0,0 +1,37 @@
+import { type KynverUserConfig } from "../config.js";
+export interface CommandProbeResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    error?: string;
+}
+export interface RuntimeTakeoverProbes {
+    packageVersion(): string;
+    commandOnPath(bin: string): CommandProbeResult;
+    kynverVersion(bin: string): CommandProbeResult;
+    loadConfig(): KynverUserConfig;
+    configFilePath(): string;
+    credentialsFilePath(): string;
+    readCredentials(): {
+        hasApiKey: boolean;
+        runnerTokenPrefix?: string;
+        runnerTokenAgentOsId?: string;
+    };
+    envSnapshot(): {
+        kynverApiUrl?: string;
+        openclawCronFireBaseUrl?: string;
+        kynverRunnerTokenPrefix?: string;
+        kynverRuntimeSecret: boolean;
+        openclawCronSecret: boolean;
+        kynverHarnessRoot?: string;
+        opusHarnessRoot?: string;
+        kynverSchedulerProvider?: string;
+    };
+    harnessRoot(): string;
+    legacyOpenclawHarnessRoot(): string;
+    pathExists(target: string): boolean;
+    pathWritable(target: string): boolean;
+    vercelVersion(): CommandProbeResult;
+    vercelWhoami(): CommandProbeResult;
+}
+export declare const defaultRuntimeTakeoverProbes: RuntimeTakeoverProbes;

package/dist/exit-classify.d.ts

@@ -0,0 +1,12 @@
+export interface ExitClassification {
+    /** True when the failure is a structural blocker an operator must fix. */
+    blocked: boolean;
+    /** Precise, human-readable reason for the blocker. */
+    reason: string;
+}
+/**
+ * Classify a dead worker's error/stderr output. Returns a structured blocker when
+ * the text matches a known startup/config failure, or null when it does not (the
+ * caller should fall back to the generic needs_attention path).
+ */
+export declare function classifyExitFailure(errorText: string | null | undefined): ExitClassification | null;

package/dist/exited-salvage.d.ts

@@ -0,0 +1,22 @@
+import type { GitAncestry } from "./git.js";
+export type ExitedSalvageKind = "none" | "uncommitted" | "committed_ahead" | "both";
+export interface ExitedSalvageAssessment {
+    kind: ExitedSalvageKind;
+    /** True when the worktree has reviewable uncommitted and/or committed-ahead work. */
+    salvageable: boolean;
+    uncommittedCount: number;
+    headCommit: string | null;
+    /** Board / attention reason — stable prefix for downstream parsers. */
+    attentionReason: string;
+}
+/**
+ * Classify a dead worker with no `finalResult`. Returns null when the worker is
+ * still alive or already recorded a final result.
+ */
+export declare function assessExitedWorkerSalvage(input: {
+    alive: boolean;
+    finalResult: unknown;
+    changedFiles?: string[];
+    gitAncestry?: GitAncestry | null;
+    headCommit?: string | null;
+}): ExitedSalvageAssessment | null;

package/dist/finalize.d.ts

@@ -0,0 +1,16 @@
+export interface RunFinalizeResult {
+    runId: string;
+    from: string;
+    to: string;
+}
+/**
+ * Finalize runs that are still marked active but have no live workers.
+ *
+ * The harness creates one run per task and never closed them out, leaving dozens
+ * of "running" runs that bloated disk and broke operator views (and made cleanup
+ * unsafe to reason about). Active-worker accounting already excludes dead workers,
+ * so this is about run-status hygiene + enabling safe pruning of finished runs.
+ *
+ * Returns the runs whose status changed.
+ */
+export declare function finalizeStaleRuns(): RunFinalizeResult[];

package/dist/fortress-engagement-gate.d.ts

@@ -0,0 +1,5 @@
+/** Parse dispatch-next skip decisions for Security Fortress engagement gates. */
+export declare function isEngagementRequiredSkip(skip: {
+    skipReason?: string;
+    reason?: string;
+}): boolean;

package/dist/git.d.ts

@@ -0,0 +1,37 @@
+export interface GitOptions {
+    allowFailure?: boolean;
+    throwError?: boolean;
+}
+export declare function git(cwd: string, args: string[], options?: GitOptions): string;
+export declare function ensureGitRepo(repo: string): void;
+export declare function gitStatusShort(worktreePath: string): string[];
+export interface GitCaptureResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error: string | null;
+}
+export declare function gitCapture(cwd: string, args: string[]): GitCaptureResult;
+export declare function gitIsAncestor(cwd: string, ancestor: string, descendant: string): {
+    isAncestor: boolean | null;
+    error: string | null;
+};
+export type GitAncestryRelation = "synced" | "merged" | "ahead" | "diverged" | "unknown";
+export interface GitAncestry {
+    checked: boolean;
+    base: string;
+    head: string | null;
+    baseHead: string | null;
+    baseIsAncestorOfHead: boolean | null;
+    headIsAncestorOfBase: boolean | null;
+    relation: GitAncestryRelation;
+    error?: string;
+}
+export interface GitAncestryOptions {
+    /** Branch or ref name (e.g. origin/main). Used when baseCommit is unset. */
+    base?: string;
+    /** Pinned SHA the worktree was created from — preferred over a moving branch ref. */
+    baseCommit?: string;
+}
+export declare function computeGitAncestry(worktreePath: string, baseOrOptions?: string | GitAncestryOptions): GitAncestry;
+export { scrubClaudeEnv, scrubWorkerEnv } from "./worker-env.js";

package/dist/github-repo.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Parse `owner/repo` from a git remote URL (HTTPS or git@github.com:…).
+ * Uses URL pathname parsing so repo names are not truncated at dots (e.g. Kynver).
+ */
+export declare function parseGithubOwnerRepo(remoteUrl: string): string | null;

package/dist/harness-verify-cli.d.ts

@@ -0,0 +1 @@
+export declare function runHarnessVerifyCli(args: Record<string, string | boolean>): void;

package/dist/harness-verify.d.ts

@@ -0,0 +1,19 @@
+import { type BoundedBuildExecResult } from "./bounded-build/index.js";
+/** Default expensive checks for harness / plan runtime verification. */
+export declare const DEFAULT_HARNESS_VERIFY_COMMANDS: readonly ["npm run typecheck", "npm run test"];
+export interface HarnessVerifyStep {
+    command: string;
+    result: BoundedBuildExecResult;
+}
+export interface HarnessVerifySummary {
+    passed: boolean;
+    steps: HarnessVerifyStep[];
+}
+/**
+ * Run plan/harness verification commands with memory-bounded subprocess execution.
+ * Parallel worktrees remain allowed — each call admits by MemAvailable at start.
+ */
+export declare function runHarnessVerifyCommands(cwd: string, commands?: readonly string[], opts?: {
+    waitForAdmissionMs?: number;
+    timeoutMs?: number;
+}): HarnessVerifySummary;

package/dist/heartbeat.d.ts

@@ -0,0 +1,22 @@
+export interface ParsedHeartbeat {
+    heartbeatCount: number;
+    lastHeartbeatAt: string | null;
+    lastHeartbeatPhase: string | null;
+    lastHeartbeatSummary: string | null;
+    heartbeatBlocker: string | null;
+    timestampAnomalies: ParsedHeartbeatTimestampAnomaly[];
+}
+export interface ParsedHeartbeatTimestampAnomaly {
+    kind: "future_heartbeat_timestamp";
+    observedAt: string;
+    clampedTo: string;
+}
+/** Worker contract: append `phase: "complete"` when productively finished. */
+export declare function isTerminalHeartbeatPhase(phase: string | null | undefined): boolean;
+/**
+ * When stdout has no stream-json `result` yet (common for Cursor workers mid-exit),
+ * treat the worker's completion heartbeat as a synthetic final result so lifecycle
+ * sync, completion replay, and resource gates advance.
+ */
+export declare function terminalFinalResultFromHeartbeat(heartbeat: ParsedHeartbeat): string | null;
+export declare function parseHeartbeat(file: string): ParsedHeartbeat;

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+export { PACKAGE_VERSION } from "./package-version.js";
+export { buildDispatchTaskText, dispatchRun, DEFAULT_DISPATCH_LEASE_MS } from "./dispatch.js";
+export { observeRunnerDiskGate } from "./disk-gate.js";
+export { postJson, type DispatchNextDiskGateShape } from "./callbacks.js";
+export { parseClaudeStream, parseHarnessStream, summarizeEvent, summarizeShellToolCallEvent, } from "./stream.js";
+export { classifyNpmAuditOutcome, classifyShellCommandOutcome, summarizeNpmAuditReport, type NpmAuditSummary, type ShellCommandOutcome, type ShellCommandOutcomeKind, } from "./shell-command-outcome.js";
+export { parseHeartbeat, isTerminalHeartbeatPhase, terminalFinalResultFromHeartbeat, } from "./heartbeat.js";
+export { computeWorkerStatus, computeAttention, isFinishedWorkerStatus, isLandingBlockedWorkerStatus, deriveRunStatus, type RawHarnessWorkerStatus, type HarnessWorkerRecord, type WorkerAttention, } from "./status.js";
+export { assessWorkerLanding, type WorkerLandingVerdict } from "./landing-gate.js";
+export { isEngagementRequiredSkip } from "./fortress-engagement-gate.js";
+export { assessWorkerLandingContract, landingContractAttentionReason, type WorkerLandingContract, type WorkerLandingContractVerdict, type TargetPrReconciliation, } from "./landing-contract-gate.js";
+export { assessExitedWorkerSalvage, type ExitedSalvageAssessment, type ExitedSalvageKind, } from "./exited-salvage.js";
+export { buildPrompt } from "./prompt.js";
+export { assessPrHandoffRequirement, ensurePrReadyHandoff, extractPrUrlFromText, } from "./pr-handoff/index.js";
+export { normalizeCursorModelAlias, preflightCursorModel } from "./providers/model-preflight.js";
+export { redactHarness } from "./redact.js";
+export { scrubWorkerEnv, scrubClaudeEnv, auditWorkerEnv, listForbiddenWorkerEnvKeys, isForbiddenWorkerEnvKey, FORBIDDEN_WORKER_ENV_KEYS, type WorkerEnvAudit, } from "./worker-env.js";
+export { validateRunId, validateWorkerName, validateRepo, validateOwnedPaths, validateTailLines, } from "./validate.js";
+export { spawnWorkerProcess, startWorker } from "./supervisor.js";
+export { createRun, listRuns } from "./worktree.js";
+export { sweepRun } from "./sweep.js";
+export { completeWorker, runStatus, workerStatus, tailWorker, stopWorker } from "./worker-ops.js";
+export { autoCompleteWorker, autoCompleteWorkerCli, spawnCompletionSidecar, type AutoCompleteArgs, type AutoCompleteOutcome, type SpawnSidecarOptions, type SpawnedSidecar, } from "./auto-complete.js";
+export { loadUserConfig, saveUserConfig, resolveBaseUrl, resolveCallbackSecret, resolveCallbackSecretWithMint, parseArgs, } from "./config.js";
+export { getHarnessPaths, resolveHarnessRoot } from "./paths.js";
+export { usage, main } from "./cli.js";
+export { reconcileRunsCli, reconcileStaleWorkers, type ReconcileStaleWorkersResult, type StaleWorkerReconcileOutcome } from "./stale-reconcile.js";
+export { runDaemon } from "./daemon.js";
+export { runHarnessVerifyCommands, DEFAULT_HARNESS_VERIFY_COMMANDS, type HarnessVerifySummary, type HarnessVerifyStep, } from "./harness-verify.js";
+export { runBoundedBuildCheck, assessBuildAdmission, mergeNodeOptionsForBuildCheck, buildSystemdRunArgv, isSystemdRunAvailable, readMemAvailableBytes, type BoundedBuildExecResult, type BuildAdmissionVerdict, } from "./bounded-build/index.js";
+export { assessAutoCompleteEligibility, classifyWorkerHealth, getMonitorStatus, listMonitors, runMonitorTick, spawnMonitorSidecar, type AutoCompleteAssessment, type MonitorTickResult, type TaskLeaseSnapshot, type WorkerHealthClass, type WorkerMonitorView, } from "./monitor/index.js";
+export { persistPlan, drainPlanOutbox, listOutboxItems, formatPlanOutboxHandoffBlock, extractPlanOutboxFromTask, hashPlanBody, type PersistPlanInput, type PersistPlanResult, type PlanPersistUserStatus, } from "./plan-persist/index.js";
+export { classifyVercelUrl, collectVercelEvidence, evidenceFromGitHubVercelStatus, isDashboardVercelUrl, isVercelStatusContext, pickVercelStatusContext, resolveVercelInspectTarget, type CollectVercelEvidenceInput, type GitHubCommitStatusRow, type VercelEvidenceResult, type VercelEvidenceStatus, } from "./vercel/index.js";