@sayknow-cli/coding-agent 0.4.1 → 0.4.3

package/dist/types/setup/credential-auto-import.d.ts

@@ -0,0 +1,93 @@
+import type { AuthCredentialIfAbsentReason, AuthCredentialIfAbsentSnapshotResult, AuthStorage } from "@sayknow-cli/ai";
+import type { ModelRegistry } from "../config/model-registry";
+import { type CredentialDiscoveryResult, type CredentialOrigin, type DiscoveryOptions, type ImportableCredential } from "./credential-import";
+export declare const CREDENTIAL_AUTO_IMPORT_ROTATION_WARNING = "Refreshing in skc may log out the Claude/Codex CLI because OAuth refresh tokens can rotate.";
+export declare const CREDENTIAL_AUTO_IMPORT_PERSISTENCE_WARNING = "Credential import preference could not be saved; external credentials may be offered again.";
+export declare const CREDENTIAL_AUTO_IMPORT_REFRESH_WARNING = "Imported credentials were saved, but provider availability could not be refreshed.";
+export declare const CREDENTIAL_AUTO_IMPORT_DISCOVERY_WARNING = "External credential discovery could not be completed. Use /provider to import credentials manually.";
+export declare const CREDENTIAL_AUTO_IMPORT_RETRY_WARNING = "Some external credentials could not be imported. Use /provider to retry.";
+export declare const CREDENTIAL_AUTO_IMPORT_STATE_UNREADABLE_WARNING = "Credential import preference could not be read. External credential discovery was skipped; use /provider to import credentials manually.";
+export type CredentialAutoImportSourceLabel = "claude-code-file" | "claude-code-keychain" | "codex-file";
+export type CredentialAutoImportTrigger = "startup" | "bare-login" | "setup-cli";
+export type InitialImportResolution = "accepted" | "declined";
+export type CredentialAutoImportStateProblem = "invalid-initial-import-resolution" | "invalid-last-import-version" | "malformed-json" | "malformed-root";
+export interface CredentialAutoImportStateFile {
+    lastImportVersion?: string;
+    initialImportResolution?: InitialImportResolution;
+}
+export interface CredentialAutoImportStateReadResult {
+    state: CredentialAutoImportStateFile;
+    problems: CredentialAutoImportStateProblem[];
+    unreadable: boolean;
+}
+export interface CredentialAutoImportStateMutation {
+    lastImportVersion?: string;
+    initialImportResolution?: InitialImportResolution;
+}
+export interface CredentialAutoImportStateStore {
+    read: () => Promise<CredentialAutoImportStateReadResult>;
+    write: (mutation: CredentialAutoImportStateMutation) => Promise<boolean>;
+}
+export interface CredentialAutoImportStateStoreDependencies {
+    withFileLock?: <T>(filePath: string, transaction: () => Promise<T>) => Promise<T>;
+    rename?: (oldPath: string, newPath: string) => Promise<void>;
+}
+export declare function getCredentialAutoImportStatePath(agentDir?: string): string;
+export declare function createCredentialAutoImportStateStore(agentDir?: string, dependencies?: CredentialAutoImportStateStoreDependencies): CredentialAutoImportStateStore;
+export declare function readCredentialAutoImportState(agentDir?: string): Promise<CredentialAutoImportStateReadResult>;
+export declare function isCredentialAutoImportStateResolvedForVersion(state: CredentialAutoImportStateFile, version: string): boolean;
+export declare function readCredentialImportMarker(agentDir?: string): Promise<string | undefined>;
+export declare function writeCredentialImportMarker(version: string, agentDir?: string): Promise<boolean>;
+export declare enum CredentialAutoImportFailureClass {
+    DiscoveryUnavailable = "discovery-unavailable",
+    SourceUnreadable = "source-unreadable",
+    SourceMalformed = "source-malformed",
+    KeychainDenied = "keychain-denied",
+    WriteInvalid = "write-invalid",
+    WriteConflict = "write-conflict",
+    BrokerUnavailable = "broker-unavailable",
+    BrokerUnsupported = "broker-unsupported",
+    Unknown = "unknown"
+}
+export interface CredentialAutoImportSkipped {
+    credential: ImportableCredential;
+    reason: AuthCredentialIfAbsentReason;
+    entries: AuthCredentialIfAbsentSnapshotResult["entries"];
+}
+export interface CredentialAutoImportFailure {
+    credential?: ImportableCredential;
+    origin?: CredentialOrigin;
+    source?: string;
+    failureClass: CredentialAutoImportFailureClass;
+}
+export interface CredentialAutoImportResult {
+    imported: ImportableCredential[];
+    skipped: CredentialAutoImportSkipped[];
+    failures: CredentialAutoImportFailure[];
+    discovered: boolean;
+    discovery?: CredentialDiscoveryResult;
+    globalDiscoveryFailure?: CredentialAutoImportFailure;
+}
+export declare function formatCredentialAutoImportCandidateLabel(candidate: Pick<ImportableCredential, "provider" | "origin">): string;
+export declare function formatCredentialAutoImportPrompt(candidates: readonly Pick<ImportableCredential, "provider" | "origin">[]): string;
+export declare function logCredentialAutoImportFailures(trigger: CredentialAutoImportTrigger, failures: readonly Pick<CredentialAutoImportFailure, "failureClass">[]): void;
+export type CredentialAutoImportAuthStorage = Pick<AuthStorage, "importCredentialIfAbsent">;
+export interface CredentialAutoImportOptions {
+    authStorage: CredentialAutoImportAuthStorage;
+    discover?: (options?: DiscoveryOptions) => Promise<CredentialDiscoveryResult>;
+    discoveryOptions?: DiscoveryOptions;
+    trigger: CredentialAutoImportTrigger;
+    sourceLabel?: CredentialAutoImportSourceLabel;
+}
+export declare function runExternalCredentialAutoImport({ authStorage, discover, discoveryOptions, }: CredentialAutoImportOptions): Promise<CredentialAutoImportResult>;
+export declare function buildCredentialAutoImportNotice(result: Pick<CredentialAutoImportResult, "imported">): string | undefined;
+export declare function formatCredentialAutoImportResult(result: CredentialAutoImportResult): string[];
+export interface StartupCredentialAutoImportOptions {
+    authStorage: CredentialAutoImportOptions["authStorage"];
+    modelRegistry: Pick<ModelRegistry, "refresh">;
+    discover?: CredentialAutoImportOptions["discover"];
+    version?: string;
+    agentDir?: string;
+    stateStore?: CredentialAutoImportStateStore;
+}
+export declare function runStartupCredentialAutoImportIfNeeded({ authStorage: activeAuthStorage, modelRegistry: activeModelRegistry, discover, version, agentDir, stateStore, }: StartupCredentialAutoImportOptions): Promise<string | undefined>;

package/dist/types/setup/credential-import.d.ts

@@ -0,0 +1,82 @@
+import type { AuthCredential } from "@sayknow-cli/ai";
+/** skc provider ids that external credentials map onto. */
+export type ExternalProvider = "anthropic" | "openai-codex";
+/** Where a discovered credential came from. */
+export type CredentialOrigin = "claude-code-file" | "claude-code-keychain" | "codex-file";
+export declare const AUTO_IMPORT_OAUTH_PROVIDER_ORIGINS: Record<ExternalProvider, ReadonlySet<CredentialOrigin>>;
+/** Human labels for providers, used in redacted summaries. */
+export declare const EXTERNAL_PROVIDER_LABELS: Record<ExternalProvider, string>;
+/** A credential that can be safely imported into skc's store. */
+export interface ImportableCredential {
+    provider: ExternalProvider;
+    origin: CredentialOrigin;
+    /** Redacted, human-readable description of where this came from. */
+    source: string;
+    kind: AuthCredential["type"];
+    identity?: {
+        email?: string;
+        accountId?: string;
+    };
+    /** Epoch-ms expiry for OAuth credentials, when known. */
+    expiresAt?: number;
+    /** Redacted access token / API key — safe to display. */
+    redactedToken: string;
+    /** Opaque credential payload. Never include this in any summary output. */
+    credential: AuthCredential;
+}
+/** A source that was found but could not be imported. */
+export interface SkippedCredential {
+    origin: CredentialOrigin;
+    source: string;
+    reason: string;
+}
+/** Ambient environment-backed auth that is already usable without import. */
+export interface EnvironmentCredentialHint {
+    provider: ExternalProvider;
+    variable: string;
+    redactedValue: string;
+}
+export interface CredentialDiscoveryResult {
+    importable: ImportableCredential[];
+    skipped: SkippedCredential[];
+    environment: EnvironmentCredentialHint[];
+}
+export interface DiscoveryOptions {
+    /** Override the home directory (defaults to `os.homedir()`). */
+    homeDir?: string;
+    /** Override the environment (defaults to `process.env`). */
+    env?: Record<string, string | undefined>;
+    /** Override the platform (defaults to `process.platform`). */
+    platform?: NodeJS.Platform;
+    /**
+     * Reader for the macOS Keychain `Claude Code-credentials` entry. Defaults to
+     * shelling out to `security`; injected in tests. Returns the raw JSON string,
+     * or `null` when no entry exists.
+     */
+    readClaudeKeychain?: () => Promise<string | null>;
+}
+export type CredentialUpserter = (provider: string, credential: AuthCredential) => unknown | Promise<unknown>;
+export interface ImportSummary {
+    imported: ImportableCredential[];
+    failed: Array<{
+        credential: ImportableCredential;
+        error: string;
+    }>;
+}
+/**
+ * Discover Claude Code and Codex CLI credentials across files, the macOS
+ * Keychain, and environment variables. Never throws for individual unreadable or
+ * malformed sources — those land in {@link CredentialDiscoveryResult.skipped}.
+ */
+export declare function discoverExternalCredentials(options?: DiscoveryOptions): Promise<CredentialDiscoveryResult>;
+/** Redacted one-line summary of an importable credential. Never includes secrets. */
+export declare function formatCredentialSummary(credential: ImportableCredential): string;
+/** Redacted summary lines for an entire discovery result. Never includes secrets. */
+export declare function formatDiscoverySummary(result: CredentialDiscoveryResult): string[];
+export declare function isAutoImportOAuthCredential(credential: ImportableCredential): boolean;
+export declare function filterAutoImportOAuthCredentials(credentials: readonly ImportableCredential[]): ImportableCredential[];
+/**
+ * Persist discovered credentials via `upsert`. Each credential is imported
+ * independently; a failure on one is recorded without aborting the rest.
+ */
+export declare function importCredentials(credentials: readonly ImportableCredential[], upsert: CredentialUpserter): Promise<ImportSummary>;

package/dist/types/setup/hermes-setup.d.ts

@@ -0,0 +1,78 @@
+import { COORDINATOR_MCP_PROTOCOL_VERSION, COORDINATOR_MCP_SERVER_NAME } from "../coordinator/contract";
+export type HermesMutationClass = "sessions" | "questions" | "reports";
+export type HermesSetupMode = "render" | "install" | "check" | "smoke";
+export interface HermesSetupFlags {
+    json?: boolean;
+    check?: boolean;
+    smoke?: boolean;
+    install?: boolean;
+    force?: boolean;
+    root?: string[];
+    repo?: string;
+    profile?: string;
+    sessionCommand?: string;
+    noWorktree?: boolean;
+    worktreeName?: string;
+    stateRoot?: string;
+    mutation?: string[];
+    artifactByteCap?: string;
+    serverKey?: string;
+    skcCommand?: string;
+    target?: string;
+    profileDir?: string;
+}
+export interface CoordinatorSetupSpec {
+    schemaVersion: 1;
+    coordinator: "hermes";
+    serverKey: string;
+    serverName: typeof COORDINATOR_MCP_SERVER_NAME;
+    protocolVersion: typeof COORDINATOR_MCP_PROTOCOL_VERSION;
+    skcCommand: string;
+    args: ["mcp-serve", "coordinator"];
+    roots: string[];
+    namespace: {
+        profile?: string;
+        repo?: string;
+    };
+    sessionCommand?: string;
+    sessionCommandSource: "default" | "explicit";
+    worktree: {
+        enabled: boolean;
+        name?: string;
+    };
+    stateRoot?: string;
+    mutationPolicy: {
+        classes: HermesMutationClass[];
+        perCallConsentRequired: true;
+    };
+    artifactByteCap?: number;
+    installTarget?: {
+        kind: "profile-dir" | "config-file";
+        path: string;
+    };
+    operatorTemplateVersion: 1;
+    contractDocVersion: 1;
+}
+export interface HermesSetupResult {
+    ok: boolean;
+    mode: HermesSetupMode;
+    files_written: string[];
+    previews: Array<{
+        path: string;
+        content: string;
+    }>;
+    warnings: string[];
+    smoke: null | {
+        ok: boolean;
+        protocolVersion: string;
+        serverName: string;
+        requiredTools: string[];
+        missingTools: string[];
+    };
+}
+export declare function buildHermesSetupSpec(flags: HermesSetupFlags): CoordinatorSetupSpec;
+export declare function computeHermesSetupSignature(spec: CoordinatorSetupSpec): string;
+export declare function renderHermesServerBlock(spec: CoordinatorSetupSpec): Record<string, unknown>;
+export declare function runHermesSetup(flags: HermesSetupFlags): Promise<HermesSetupResult>;
+export declare function formatHermesSetupResult(result: HermesSetupResult): string;
+export declare function hermesSetupExitCode(error: unknown): number;

package/dist/types/setup/host-plugin-setup.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Host plugin setup for `skc setup claude` and `skc setup codex`.
+ *
+ * Renders install guidance and a fail-closed coordinator MCP config preview for
+ * the canonical generated plugin bundle under `plugins/`. This is intentionally
+ * render-only and fail-closed: the workdir allowlist is scoped to the project
+ * root and no mutation class is enabled until the user opts in.
+ */
+export type HostPluginKind = "claude" | "codex";
+export interface HostPluginSetupFlags {
+    json?: boolean;
+    check?: boolean;
+    root?: string[];
+    repo?: string;
+}
+export interface HostPluginSetupResult {
+    ok: true;
+    host: HostPluginKind;
+    mode: "render";
+    gated: boolean;
+    pluginPath: string;
+    manifestPath: string;
+    marketplacePath: string;
+    installGuidance: string[];
+    coordinatorConfigPreview: {
+        command: string;
+        args: string[];
+        env: Record<string, string>;
+    };
+    mutationPolicy: string;
+    notes: string[];
+    check?: {
+        ok: boolean;
+        checked: string[];
+        missing: string[];
+    };
+}
+export declare function buildHostPluginSetup(host: HostPluginKind, flags?: HostPluginSetupFlags): HostPluginSetupResult;
+export declare function formatHostPluginSetup(result: HostPluginSetupResult): string;

package/dist/types/setup/model-onboarding-guidance.d.ts

@@ -0,0 +1,9 @@
+export declare const MODEL_ONBOARDING_API_PROVIDER_COMMAND = "/provider add --compat <openai|anthropic> --provider <id> --base-url <url> --api-key-env <ENV> --model <model>";
+export declare const MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND = "/provider add --preset <minimax|minimax-cn|glm>";
+export declare const MODEL_ONBOARDING_SETUP_COMMAND = "skc setup provider";
+export declare const MODEL_ONBOARDING_OAUTH_COMMAND = "/provider login [provider-id] or /login [provider-id]";
+export declare function formatModelOnboardingGuidance(): string;
+export declare function formatModelOnboardingInlineHint(): string;
+export declare function formatNoModelOnboardingError(): string;
+export declare function formatNoCredentialOnboardingError(providerId: string): string;
+export declare function formatNoModelsAvailableFallback(): string;

package/dist/types/setup/provider-onboarding.d.ts

@@ -0,0 +1,52 @@
+import { type ModelsConfig } from "../config/models-config-schema";
+export type ProviderCompatibility = "openai" | "anthropic";
+export type ProviderSetupApi = "openai-responses" | "openai-completions" | "anthropic-messages";
+export interface ProviderSetupInput {
+    compatibility?: ProviderCompatibility;
+    preset?: string;
+    providerId?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    apiKeyEnv?: string;
+    models?: string[];
+    modelsPath?: string;
+    force?: boolean;
+}
+export interface ProviderSetupResult {
+    providerId: string;
+    compatibility: ProviderCompatibility;
+    api: ProviderSetupApi;
+    baseUrl: string;
+    modelIds: string[];
+    modelsPath: string;
+    redactedApiKey: string;
+    credentialSource: "literal" | "env";
+    preset?: string;
+    presetName?: string;
+}
+type ProviderConfig = NonNullable<NonNullable<ModelsConfig["providers"]>[string]>;
+type ProviderCompatConfig = NonNullable<ProviderConfig["compat"]>;
+interface ProviderPreset {
+    id: string;
+    aliases: readonly string[];
+    name: string;
+    description: string;
+    compatibility: ProviderCompatibility;
+    api: ProviderSetupApi;
+    providerId: string;
+    baseUrl: string;
+    apiKeyEnv: string;
+    models: readonly string[];
+    compat?: ProviderCompatConfig;
+}
+export declare const PROVIDER_PRESETS: readonly ProviderPreset[];
+export declare function getDefaultModelsPath(): string;
+export declare function normalizeProviderId(providerId: string): string;
+export declare function parseProviderCompatibility(value: string): ProviderCompatibility;
+export declare function findProviderPreset(value: string | undefined): ProviderPreset | undefined;
+export declare function formatProviderPresetList(): string;
+export declare function parseModelList(values: readonly string[]): string[];
+export declare function redactSecret(secret: string): string;
+export declare function addApiCompatibleProvider(input: ProviderSetupInput): Promise<ProviderSetupResult>;
+export declare function formatProviderSetupResult(result: ProviderSetupResult): string;
+export {};

package/dist/types/skc-runtime/cli-write-receipt.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI write/mutation receipt shaping (Workstream B, v4).
+ *
+ * `CliWriteReceipt` is the compact **stdout presentation** returned by a SKC
+ * mutation command. It carries only routing/audit fields a caller needs; it
+ * NEVER echoes the persisted body (full `state` envelope, ultragoal `plan`,
+ * team task body, ralplan `task`, etc.) — echoing those back is a redundant
+ * token leak because the caller already has the content it just wrote.
+ *
+ * This is intentionally a *separate* concept from the persisted
+ * `WorkflowStateReceipt` (the on-disk envelope `receipt` integrity field).
+ * Do NOT use `CliWriteReceipt` as a persistence schema or validate persisted
+ * envelopes against it.
+ */
+export interface CliWriteReceipt {
+    ok: boolean;
+    [field: string]: unknown;
+}
+/**
+ * Serialize a write/mutation receipt to compact stdout JSON.
+ * `undefined` fields are dropped so optional routing fields stay absent
+ * rather than serialized as `null`.
+ */
+export declare function renderCliWriteReceipt(receipt: Record<string, unknown>): string;

package/dist/types/skc-runtime/deep-interview-ambiguity.d.ts

@@ -0,0 +1,39 @@
+import { type DeepInterviewStateEnvelope } from "./deep-interview-state";
+export interface AmbiguityFloorBreakdown {
+    floor: number;
+    disputed_fact_count: number;
+    unscored_active_component_count: number;
+    auto_answer_ratio: number;
+}
+export interface AmbiguityClampResult {
+    effective: number;
+    clamped: boolean;
+}
+/** Compute the deterministic floor from the inner deep-interview `state` object. */
+export declare function computeAmbiguityFloor(inner: unknown): AmbiguityFloorBreakdown;
+/** Clamp an LLM-reported ambiguity to the deterministic floor: `max(reported, floor)`. */
+export declare function clampReportedAmbiguity(reported: number, floor: number): AmbiguityClampResult;
+/**
+ * Mark every established fact recorded in `retractedRound` as disputed. This is the
+ * mechanical contradiction signal for answer retraction: when the user replaces an
+ * already-scored answer (A -> B pivot), the facts that answer established can no
+ * longer be trusted, so they raise the floor until re-confirmed or superseded.
+ * Returns new arrays/objects; never mutates the input.
+ */
+export declare function disputeFactsFromRetractedRound(facts: readonly unknown[], retractedRound: number): {
+    facts: Record<string, unknown>[];
+    disputedIds: string[];
+};
+export interface AppliedAmbiguityFloor {
+    envelope: DeepInterviewStateEnvelope;
+    breakdown: AmbiguityFloorBreakdown;
+    clamped: boolean;
+}
+/**
+ * Enforce the floor invariant on a full deep-interview envelope: recompute the floor
+ * from persisted evidence, clamp `state.current_ambiguity`, and clamp the latest
+ * scored round (preserving the original value as `reported_ambiguity` for audit).
+ * Historical rounds are never rewritten. Idempotent and non-mutating; every writer
+ * (state CLI write/reconcile, recorder) applies this immediately before persisting.
+ */
+export declare function applyAmbiguityFloorToEnvelope(value: unknown): AppliedAmbiguityFloor;

package/dist/types/skc-runtime/deep-interview-recorder.d.ts

@@ -0,0 +1,123 @@
+import { type DeepInterviewEstablishedFact, type DeepInterviewIntentItem, type DeepInterviewIntentSubstitution, type DeepInterviewRoundRecord, type DeepInterviewStateEnvelope, type DeepInterviewTriggerMetadata } from "./deep-interview-state";
+export * from "./deep-interview-ambiguity";
+export * from "./deep-interview-state";
+/**
+ * Runtime-owned deep-interview round recorder (conflict-aware scoring support).
+ *
+ * Ownership boundary (per the approved consensus plan): this module owns durable
+ * round-record semantics — stable identity, append-or-merge, lifecycle, compact
+ * reads, replay detection, and the pure scored-transition validator. Callers such
+ * as the `ask` tool only resolve an answer and invoke these helpers; they never
+ * compute state paths, merge records, or write `.skc` files directly. All writes
+ * go through the sanctioned state-writer (`writeWorkflowEnvelopeAtomic`).
+ */
+export interface DeepInterviewAnswerInput {
+    interviewId?: string;
+    round: number;
+    round_id?: string;
+    questionId?: string;
+    questionText: string;
+    component?: string;
+    dimension?: string;
+    ambiguity?: number;
+    selectedOptions?: string[];
+    customInput?: string;
+    intent_contract?: {
+        items: DeepInterviewIntentItem[];
+        confirmation_options: string[];
+    };
+    intent_review?: {
+        observed_items: DeepInterviewIntentItem[];
+        supporting_substitutions: DeepInterviewIntentSubstitution[];
+        approval_options: string[];
+    };
+}
+export interface DeepInterviewScoringInput {
+    interviewId?: string;
+    round: number;
+    round_id?: string;
+    questionId?: string;
+    scores: Record<string, number>;
+    ambiguity: number;
+    triggers?: DeepInterviewTriggerMetadata[];
+}
+export type AppendOrMergeAction = "created" | "noop" | "replaced";
+export interface AppendOrMergeResult {
+    rounds: DeepInterviewRoundRecord[];
+    action: AppendOrMergeAction;
+    record: DeepInterviewRoundRecord;
+}
+export interface DeepInterviewCompactState {
+    threshold?: number;
+    threshold_source?: string;
+    current_ambiguity?: number;
+    topology_summary?: {
+        active: number;
+        deferred: number;
+        components: string[];
+    };
+    established_facts: DeepInterviewEstablishedFact[];
+    unresolved_triggers: DeepInterviewTriggerMetadata[];
+    recent_scored_rounds: DeepInterviewRoundRecord[];
+    pending_shells: DeepInterviewRoundRecord[];
+}
+export interface TransitionValidationResult {
+    ok: boolean;
+    violations: string[];
+}
+export declare function buildAnswerShell(input: DeepInterviewAnswerInput, now?: string): DeepInterviewRoundRecord;
+/**
+ * Append-or-merge by `round_key`. Exactly one record per key:
+ * - no existing record -> append (`created`);
+ * - identical question_hash + answer_hash -> deterministic no-op (`noop`);
+ * - same key, different hashes -> deterministic replacement of the prior shell
+ *   (`replaced`); the prior answer for that key is superseded and lifecycle resets.
+ */
+export declare function appendOrMergeRound(rounds: readonly DeepInterviewRoundRecord[], shell: DeepInterviewRoundRecord): AppendOrMergeResult;
+/**
+ * Merge scoring output into the existing record for the derived key, transitioning
+ * it to `scored`. Never appends a second record for the same key; if no shell exists
+ * yet (scoring without a prior ask), a scored record is created so data is not lost.
+ */
+export declare function enrichRoundWithScoring(rounds: readonly DeepInterviewRoundRecord[], input: DeepInterviewScoringInput, now?: string): {
+    rounds: DeepInterviewRoundRecord[];
+    record: DeepInterviewRoundRecord;
+};
+/**
+ * Bidirectional invariant: if `next` carries an `active` trigger, the affected
+ * dimension must not improve and overall ambiguity must rise vs the prior scored
+ * round. `disputed`/`unresolved` triggers are exempt but must carry a rationale.
+ */
+export declare function validateDeepInterviewScoredTransition(prior: DeepInterviewRoundRecord | undefined, next: DeepInterviewRoundRecord): TransitionValidationResult;
+/** Back-compat wrapper: normalize a deep-interview envelope to its canonical nested shape. */
+export declare function ensureDeepInterviewStateShape(value: unknown): DeepInterviewStateEnvelope;
+export declare function projectCompactState(value: unknown, options?: {
+    lastN?: number;
+}): DeepInterviewCompactState;
+/** Refresh the best-effort HUD cache from persisted deep-interview state. */
+export declare function syncDeepInterviewRecorderHud(cwd: string, statePath: string, sessionId: string | undefined): Promise<void>;
+/**
+ * Record an `answered` shell for one round (append-or-merge by durable key).
+ *
+ * Retraction dynamics: replacing an already-`scored` answer is a mechanical
+ * contradiction signal (the user pivoted). The facts that round established are
+ * marked disputed, which raises the deterministic ambiguity floor immediately —
+ * without waiting for the LLM scorer to self-report a trigger.
+ */
+export declare function appendOrMergeDeepInterviewRound(cwd: string, statePath: string, input: DeepInterviewAnswerInput, options?: {
+    sessionId?: string;
+}): Promise<{
+    action: AppendOrMergeAction;
+    record: DeepInterviewRoundRecord;
+    disputedFactIds?: string[];
+}>;
+/** Merge scoring output into the same round record, transitioning to `scored`. */
+export declare function enrichDeepInterviewRoundScoring(cwd: string, statePath: string, input: DeepInterviewScoringInput, options?: {
+    sessionId?: string;
+}): Promise<{
+    record: DeepInterviewRoundRecord;
+}>;
+/** Compact projection so callers read a slice instead of the full transcript. */
+export declare function readDeepInterviewStateCompact(statePath: string, options?: {
+    lastN?: number;
+}): Promise<DeepInterviewCompactState>;

package/dist/types/skc-runtime/deep-interview-runtime.d.ts

@@ -0,0 +1,36 @@
+export * from "./deep-interview-recorder";
+/**
+ * Native implementation of `skc deep-interview`.
+ *
+ * The CLI itself does not run the Socratic interview; that lives inside the `/skill:deep-interview`
+ * skill executed by the agent. This handler validates the documented argument-hint surface
+ * (`[--quick|--standard|--deep] <idea>`), seeds `.skc/state/deep-interview-state.json`, and
+ * updates the shared HUD rail via `syncSkillActiveState` so the active interview is visible to
+ * the TUI.
+ */
+export interface DeepInterviewCommandResult {
+    status: number;
+    stdout?: string;
+    stderr?: string;
+}
+export declare function deepInterviewStatePath(cwd: string, sessionId?: string): string;
+export interface ResolvedDeepInterviewSpecWriteArgs {
+    stage: "final";
+    slug: string;
+    spec: string;
+    sessionId: string;
+    json: boolean;
+    deliberate: boolean;
+    handoff?: "ralplan";
+    force: boolean;
+}
+export interface PersistedDeepInterviewSpec {
+    slug: string;
+    path: string;
+    stage: "final";
+    sha256: string;
+    createdAt: string;
+    statePath: string;
+}
+export declare function persistDeepInterviewSpec(cwd: string, resolved: ResolvedDeepInterviewSpecWriteArgs): Promise<PersistedDeepInterviewSpec>;
+export declare function runNativeDeepInterviewCommand(args: string[], cwd?: string): Promise<DeepInterviewCommandResult>;