@sayknow-cli/coding-agent 0.4.1 → 0.4.3

package/dist/types/config/settings.d.ts

@@ -0,0 +1,189 @@
+import { procmgr } from "@sayknow-cli/utils";
+import type { ModelRole } from "../config/model-registry";
+import { type NotificationSettingsReader, type NotificationSettingsSnapshot } from "../sdk/bus/config";
+import { AgentStorage } from "../session/agent-storage";
+import { type EditMode } from "../utils/edit-mode";
+import { type CasReceipt } from "./atomic-yaml-patch";
+import { type ModelSelectorValue } from "./model-selector-value";
+import { type BashInterceptorRule, type GroupPrefix, type GroupTypeMap, type SettingPath, type SettingsSchemaReport, type SettingValue } from "./settings-schema";
+export type * from "./settings-schema";
+export * from "./settings-schema";
+/** Raw settings object as stored in YAML */
+export interface RawSettings {
+    [key: string]: unknown;
+}
+export type SettingsAtomicPatch = {
+    path: SettingPath;
+    op: "set";
+    value: unknown;
+} | {
+    path: SettingPath;
+    op: "unset";
+};
+export type SettingsAtomicReceipt = CasReceipt;
+export interface SettingsOptions {
+    /** Current working directory for project settings discovery */
+    cwd?: string;
+    /** Agent directory for config.yml storage */
+    agentDir?: string;
+    /** Don't persist to disk (for tests) */
+    inMemory?: boolean;
+    /** Initial overrides */
+    overrides?: Partial<Record<SettingPath, unknown>>;
+}
+/** Additional layer setup for {@link Settings.isolated}. */
+export interface IsolatedSettingsOptions {
+    /** Initial runtime overrides. Notification paths are rejected. */
+    overrides?: Partial<Record<SettingPath, unknown>>;
+}
+/** Raised when an ephemeral override attempts to change global-only notification settings. */
+export declare class NotificationSettingsOverrideError extends Error {
+    readonly path: SettingPath;
+    constructor(path: SettingPath);
+}
+export declare class Settings implements NotificationSettingsReader {
+    #private;
+    private constructor();
+    /**
+     * Initialize the global singleton.
+     * Call once at startup before accessing `settings`.
+     */
+    static init(options?: SettingsOptions): Promise<Settings>;
+    /**
+     * Load settings for an explicit workspace without changing the global singleton.
+     * Managed-session policy resolution must be bound to the workspace being opened.
+     */
+    static loadForScope(options: {
+        cwd: string;
+        agentDir?: string;
+    }): Promise<Settings>;
+    /**
+     * Create an isolated instance for testing with explicit user/global settings.
+     * Does not affect the global singleton.
+     */
+    static isolated(globalSettings?: Partial<Record<SettingPath, unknown>>, options?: IsolatedSettingsOptions): Settings;
+    /**
+     * Get the global singleton.
+     * Throws if not initialized.
+     */
+    static get instance(): Settings;
+    /**
+     * Get a setting value (sync).
+     * Returns the merged value from global + project + overrides, or the default.
+     */
+    get<P extends SettingPath>(path: P): SettingValue<P>;
+    /**
+     * Get a setting value from the user/global config only.
+     *
+     * Use for machine-local command hooks and other settings that must not be
+     * activated by project-scoped config files.
+     */
+    getGlobal<P extends SettingPath>(path: P): SettingValue<P> | undefined;
+    /**
+     * Read the remote-notification settings from the user/global layer only.
+     * Schema defaults are applied per path; project settings and runtime overrides
+     * are deliberately excluded from this trust boundary.
+     */
+    getNotificationSettingsSnapshot(): NotificationSettingsSnapshot;
+    /** Check whether a setting is present in loaded settings/overrides rather than coming from schema defaults. */
+    has(path: SettingPath): boolean;
+    /** Diagnostics from schema reconciliation during the most recent load. */
+    getSchemaReport(): SettingsSchemaReport;
+    /**
+     * Set a setting value (sync).
+     * Updates global settings and reserves its background persistence slot before
+     * returning, so later durable batches cannot overtake this mutation.
+     */
+    set<P extends SettingPath>(path: P, value: SettingValue<P> | undefined): void;
+    /**
+     * Delete a global setting (sync), rather than serializing an ambiguous YAML
+     * `undefined` value. Defaults/project settings become visible immediately.
+     */
+    unset<P extends SettingPath>(path: P): void;
+    /**
+     * Persist a tagged batch as one atomic YAML replacement. Unlike ordinary
+     * {@link set}, canonical state and hooks change only after the rename succeeds.
+     */
+    commitAtomicBatch(patches: readonly SettingsAtomicPatch[]): Promise<CasReceipt>;
+    /** Build a durable batch from the current on-disk YAML under the shared queue and file lock. */
+    commitAtomicBatchWithCurrent(buildPatches: (current: Readonly<RawSettings>) => Promise<readonly SettingsAtomicPatch[]> | readonly SettingsAtomicPatch[]): Promise<CasReceipt>;
+    /**
+     * Apply runtime overrides (not persisted).
+     */
+    override<P extends SettingPath>(path: P, value: SettingValue<P>): void;
+    /**
+     * Clear a runtime override.
+     */
+    clearOverride(path: SettingPath): void;
+    /** Flush a reserved debounced save without allowing it to be overtaken. */
+    flush(): Promise<void>;
+    /** Like {@link flush}, but reports a durable save failure to the caller. */
+    flushOrThrow(): Promise<void>;
+    cloneForCwd(cwd: string): Promise<Settings>;
+    getStorage(): AgentStorage | null;
+    getCwd(): string;
+    getAgentDir(): string;
+    getPlansDirectory(): string;
+    /**
+     * Get shell configuration based on settings.
+     */
+    getShellConfig(): procmgr.ShellConfig;
+    /**
+     * Get all settings in a group with full type safety.
+     */
+    getGroup<G extends GroupPrefix>(prefix: G): GroupTypeMap[G];
+    /**
+     * Get the edit variant for a specific model.
+     * Returns "patch", "replace", "hashline", "vim", "apply_patch", or null (use global default).
+     */
+    getEditVariantForModel(model: string | undefined): EditMode | null;
+    /**
+     * Get bash interceptor rules (typed accessor for complex array config).
+     */
+    getBashInterceptorRules(): BashInterceptorRule[];
+    /**
+     * Set a model role (helper for modelRoles record).
+     */
+    setModelRole(role: ModelRole | string, modelId: ModelSelectorValue): void;
+    setGlobalModelRole(role: ModelRole | string, modelId: ModelSelectorValue | undefined): void;
+    setGlobalModelRoleAndFlush(role: ModelRole | string, modelId: ModelSelectorValue | undefined): Promise<CasReceipt>;
+    restoreGlobalDefaultModelRoleIfCurrent(commit: CasReceipt): Promise<boolean>;
+    /**
+     * Set an agent model override while keeping any live runtime override aligned.
+     *
+     * Runtime model profiles override `task.agentModelOverrides` for the current
+     * session. A user-selected role assignment must win immediately in that same
+     * session, but only the explicit agent change should be persisted.
+     */
+    setAgentModelOverride(agentName: string, modelId: ModelSelectorValue): void;
+    /**
+     * Get a model role (helper for modelRoles record).
+     */
+    getModelRole(role: ModelRole | string): ModelSelectorValue | undefined;
+    /**
+     * Get all model roles (helper for modelRoles record).
+     */
+    getModelRoles(): Readonly<Record<string, ModelSelectorValue>>;
+    overrideModelRoles(roles: Readonly<Record<string, ModelSelectorValue>>): void;
+    /**
+     * Set disabled providers (for compatibility with discovery system).
+     */
+    setDisabledProviders(ids: string[]): void;
+}
+/**
+ * Subscribe to append-only mode setting changes.
+ * Returns an unsubscribe function. Multiple sessions (main + subagents)
+ * can register independently without overwriting each other.
+ */
+export declare function onAppendOnlyModeChanged(cb: (value: string) => void): () => void;
+export declare function isSettingsInitialized(): boolean;
+/**
+ * Reset the global singleton for testing.
+ * @internal
+ */
+export declare function resetSettingsForTest(): void;
+/**
+ * The global settings singleton.
+ * Must call `Settings.init()` before using.
+ */
+export declare const settings: Settings;

package/dist/types/config/skill-settings-defaults.d.ts

@@ -0,0 +1,14 @@
+export interface SkillDiscoverySettings {
+    enabled?: boolean;
+    enableSkillCommands?: boolean;
+    enableCodexUser?: boolean;
+    enableClaudeUser?: boolean;
+    enableClaudeProject?: boolean;
+    enablePiUser?: boolean;
+    enablePiProject?: boolean;
+    customDirectories?: string[];
+    ignoredSkills?: string[];
+    includeSkills?: string[];
+}
+export declare const DEFAULT_SKILL_DISCOVERY_SETTINGS: SkillDiscoverySettings;
+export declare const DEFAULT_DISABLED_EXTENSIONS: string[];

package/dist/types/config/telegram-autostart.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Auto-start the Telegram Remote gateway when `telegram.enabled` is on.
+ *
+ * Called once during skc startup (interactive / persistent modes only — not
+ * `-p` print or auto-print). Spawns the gateway as a detached background
+ * process, tracks its PID so repeated skc invocations don't double-spawn,
+ * and redirects output to a log file under the config root.
+ */
+/**
+ * If `telegram.enabled` is true and the gateway is not already running, spawn
+ * it in the background. Never throws — failures are logged as warnings so the
+ * main skc session is unaffected.
+ */
+export declare function maybeAutostartTelegramRemote(): Promise<void>;

package/dist/types/config/telegram-env-bridge.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bridge between skc settings (`telegram.*`) and the
+ * `@sayknow-cli/telegram-remote` gateway's environment-driven config
+ * (`loadConfigFromEnv` in packages/telegram-remote/src/config.ts).
+ *
+ * The gateway is a standalone process (`skc-telegram-remote`) that reads all
+ * configuration from `SKC_TELEGRAM_REMOTE_*` env vars. This module converts the
+ * typed settings group into those env vars so skc can spawn the gateway with a
+ * consistent, settings-page-driven configuration.
+ */
+import type { TelegramSettings } from "./settings-schema";
+/** Convert telegram settings into the env-var map the gateway expects. */
+export declare function telegramSettingsToEnv(s: TelegramSettings): Record<string, string>;
+/**
+ * Validate telegram settings before spawning the gateway.
+ * Returns a list of human-readable error strings (empty when valid).
+ */
+export declare function validateTelegramSettings(s: TelegramSettings): string[];

package/dist/types/config.d.ts

@@ -0,0 +1,66 @@
+export * from "./config/config-file";
+/**
+ * Get the base directory for resolving optional package assets (docs, examples).
+ * Walk up from import.meta.dir until we find package.json, or fall back to cwd.
+ */
+export declare function getPackageDir(): string;
+/** Get path to CHANGELOG.md (optional, may not exist in binary) */
+export declare function getChangelogPath(): string;
+export interface ConfigDirEntry {
+    path: string;
+    source: string;
+    level: "user" | "project";
+}
+export interface GetConfigDirsOptions {
+    /** Include user-level directories (~/.skc/agent/...). Default: true */
+    user?: boolean;
+    /** Include project-level directories (.skc/...). Default: true */
+    project?: boolean;
+    /** Current working directory for project paths. Default: getProjectDir() */
+    cwd?: string;
+    /** Only return directories that exist. Default: false */
+    existingOnly?: boolean;
+}
+/**
+ * Get all config directories for a subpath, ordered by priority (highest first).
+ *
+ * @param subpath - Subpath within config dirs (e.g., "commands", "hooks", "agents")
+ * @param options - Options for filtering
+ * @returns Array of directory entries, highest priority first
+ *
+ * @example
+ * // Get all command directories
+ * getConfigDirs("commands")
+ * // → [{ path: "~/.skc/agent/commands", source: ".skc", level: "user" }, ...]
+ *
+ * @example
+ * // Get only existing project skill directories
+ * getConfigDirs("skills", { user: false, existingOnly: true })
+ */
+export declare function getConfigDirs(subpath: string, options?: GetConfigDirsOptions): ConfigDirEntry[];
+/**
+ * Get all config directory paths for a subpath (convenience wrapper).
+ * Returns just the paths, highest priority first.
+ */
+export declare function getConfigDirPaths(subpath: string, options?: GetConfigDirsOptions): string[];
+export interface ConfigFileResult<T> {
+    path: string;
+    source: string;
+    level: "user" | "project";
+    content: T;
+}
+/**
+ * Find the first existing config file (for non-JSON files like SYSTEM.md).
+ * Returns just the path, or undefined if not found.
+ */
+export declare function findConfigFile(subpath: string, options?: GetConfigDirsOptions): string | undefined;
+/**
+ * Find the first existing config file with metadata.
+ */
+export declare function findConfigFileWithMeta(subpath: string, options?: GetConfigDirsOptions): Omit<ConfigFileResult<never>, "content"> | undefined;
+/**
+ * Find all nearest config directories by walking up from cwd.
+ * Returns one entry per config base (.skc, .Anthropic model) - the nearest one found.
+ * Results are in priority order (highest first).
+ */
+export declare function findAllNearestProjectConfigDirs(subpath: string, cwd?: string): ConfigDirEntry[];

package/dist/types/coordinator/contract.d.ts

@@ -0,0 +1,4 @@
+export declare const COORDINATOR_MCP_PROTOCOL_VERSION = "2024-11-05";
+export declare const COORDINATOR_MCP_SERVER_NAME = "skc-coordinator-mcp";
+export declare const COORDINATOR_MCP_TOOL_NAMES: readonly ["skc_coordinator_list_sessions", "skc_coordinator_read_status", "skc_coordinator_read_tail", "skc_coordinator_list_questions", "skc_coordinator_list_artifacts", "skc_coordinator_read_artifact", "skc_coordinator_read_coordination_status", "skc_coordinator_watch_events", "skc_coordinator_register_session", "skc_coordinator_start_session", "skc_coordinator_stop_session", "skc_coordinator_send_prompt", "skc_coordinator_submit_question_answer", "skc_coordinator_read_turn", "skc_coordinator_await_turn", "skc_coordinator_report_status", "skc_delegate_plan", "skc_delegate_execute", "skc_delegate_team"];
+export type CoordinatorToolName = (typeof COORDINATOR_MCP_TOOL_NAMES)[number];

package/dist/types/coordinator-mcp/model-preset.d.ts

@@ -0,0 +1,46 @@
+export interface CoordinatorModelProfile {
+    name: string;
+}
+/**
+ * Loads the merged built-in + custom model-profile names from `models.yml`
+ * without loading the session-host model registry. The child still owns
+ * profile activation; this validates the selection before session creation.
+ */
+export type CoordinatorModelProfileLoader = () => Map<string, CoordinatorModelProfile> | Promise<Map<string, CoordinatorModelProfile>>;
+/**
+ * Thrown by the default loader when `models.yml` exists but is invalid or
+ * unreadable. This lets the resolver fail closed with a distinct, stable reason
+ * instead of silently collapsing a broken registry to the built-ins-only set
+ * (which would misreport a caller's valid custom profile as unknown).
+ */
+export declare class CoordinatorModelProfileRegistryError extends Error {
+    constructor(cause?: unknown);
+}
+export declare const loadCoordinatorModelProfiles: CoordinatorModelProfileLoader;
+export type CoordinatorMpresetResolution = {
+    ok: true;
+    mpreset: string | null;
+} | {
+    ok: false;
+    reason: "unknown_model_profile";
+    mpreset: string;
+    available_profiles: string[];
+} | {
+    ok: false;
+    reason: "model_profile_registry_error";
+    mpreset: string;
+    available_profiles: string[];
+};
+/**
+ * Resolve a coordinator `mpreset` argument against the merged profile registry.
+ *
+ * Only an absent (`undefined`/`null`) value is a no-op (`mpreset: null`); an
+ * explicit empty/whitespace string is a caller error and is rejected rather
+ * than silently launching at the default tier. Legacy aliases are canonicalized
+ * exactly like the CLI (e.g. `codex-standard` -> `codex-medium`) so coordinator
+ * selection stays in parity with `skc --mpreset <profile>`; the resolved value
+ * is the canonical profile name. Unknown names are rejected with the
+ * available-profile listing and never reach a spawned child command, and a
+ * broken registry fails closed with `model_profile_registry_error`.
+ */
+export declare function resolveCoordinatorMpreset(raw: unknown, loadProfiles: CoordinatorModelProfileLoader): Promise<CoordinatorMpresetResolution>;

package/dist/types/coordinator-mcp/policy.d.ts

@@ -0,0 +1,32 @@
+import * as fs from "node:fs/promises";
+export type CoordinatorMutationClass = "sessions" | "questions" | "reports";
+export interface CoordinatorNamespace {
+    profile: string | null;
+    repo: string | null;
+    identity: string;
+}
+export declare function coordinatorNamespaceIdentity(env?: NodeJS.ProcessEnv): string;
+export interface CoordinatorMcpConfig {
+    allowedRoots: string[];
+    mutationClasses: Set<CoordinatorMutationClass>;
+    artifactByteCap: number;
+    namespace: CoordinatorNamespace;
+    stateRoot: string;
+    sessionCommand: string | null;
+    sessionIdleTtlMs: number;
+    sessionSweepIntervalMs: number;
+    forceStopEnabled: boolean;
+}
+export interface CoordinatorMutationRequest {
+    allow_mutation?: boolean;
+}
+export declare function buildCoordinatorMcpConfig(env?: NodeJS.ProcessEnv): CoordinatorMcpConfig;
+export declare function assertCoordinatorWorkdir(config: CoordinatorMcpConfig, cwd: unknown): Promise<string>;
+export declare function assertCoordinatorArtifactPath(config: CoordinatorMcpConfig, artifactPath: unknown): Promise<{
+    path: string;
+    byteCap: number;
+}>;
+export declare function requireCoordinatorMutation(config: CoordinatorMcpConfig, mutationClass: CoordinatorMutationClass, request: CoordinatorMutationRequest): void;
+export declare function coordinatorNamespacePath(config: CoordinatorMcpConfig): string;
+/** Opens and authorizes an artifact by the opened handle identity, not a racy pathname. */
+export declare function safeOpenCoordinatorArtifact(config: CoordinatorMcpConfig, artifactPath: unknown): Promise<fs.FileHandle>;

package/dist/types/coordinator-mcp/question-gate-codec.d.ts

@@ -0,0 +1,129 @@
+import type { WorkflowGate } from "../modes/shared/agent-wire/workflow-gate-types";
+export type PublicReason = "unsupported_gate" | "query_unavailable" | "pagination_malformed" | "row_unrepresentable" | "missing_runtime_turn" | "invalid_runtime_turn" | "invalid_gate_row" | "wrong_session" | "ownership_unavailable" | "ownership_conflict" | "gate_provenance_changed" | "turn_terminal" | "endpoint_changed" | "terminal_race" | "terminal_uncertain" | "session_closing" | "session_unavailable" | "reported_failure" | "validation_rejected";
+export type CoordinatorQuestionStatusV1 = "pending" | "answered" | "stale" | "uncertain";
+export interface CoordinatorQuestionOptionPublicV1 {
+    id: string;
+    label: string;
+    recommended: boolean;
+}
+export interface CoordinatorQuestionPublicV1 extends Record<string, unknown> {
+    schema_version: 1;
+    question_id: string;
+    session_id: string;
+    turn_id: string;
+    status: CoordinatorQuestionStatusV1;
+    stage: string;
+    kind: string;
+    prompt: string;
+    multi: boolean;
+    allow_empty: boolean;
+    options: CoordinatorQuestionOptionPublicV1[];
+    other_allowed: boolean;
+    clarification_allowed: boolean;
+    created_at: string;
+    updated_at: string;
+    answered_at: string | null;
+    reason: PublicReason | null;
+    answer_binding?: string;
+}
+export interface CoordinatorQuestionDiagnosticPublicV1 {
+    schema_version: 1;
+    session_id: string;
+    turn_id: string | null;
+    gate_id: string | null;
+    reason: PublicReason;
+    observed_at: string;
+}
+export interface CoordinatorQuestionReconciliationPublicV1 {
+    attempted: boolean;
+    complete: boolean;
+    revision: string | null;
+    observed_at: string;
+    reason: PublicReason | null;
+}
+export interface ListQuestionsSuccessV1 extends Record<string, unknown> {
+    ok: true;
+    schema_version: 1;
+    questions: CoordinatorQuestionPublicV1[];
+    diagnostics: CoordinatorQuestionDiagnosticPublicV1[];
+    reconciliation: CoordinatorQuestionReconciliationPublicV1;
+}
+export type CoordinatorAskAnswerV1 = {
+    selected: string[];
+    other?: false;
+} | {
+    selected: string[];
+    other: true;
+    custom: string;
+} | {
+    action: "clarify";
+    question: string;
+};
+export interface SubmitQuestionAnswerInputV1 {
+    session_id: string;
+    turn_id: string;
+    question_id: string;
+    answer_binding: string;
+    answer: CoordinatorAskAnswerV1;
+    idempotency_key: string;
+    allow_mutation: true;
+}
+export type SubmitQuestionAnswerSuccessV1 = {
+    ok: true;
+    schema_version: 1;
+    session_id: string;
+    turn_id: string;
+    question_id: string;
+    operation: "workflow.gate_answer";
+    status: "accepted";
+    replayed: boolean;
+    resolved_at: string;
+};
+export type SubmitQuestionAnswerValidationRejectedV1 = {
+    ok: false;
+    schema_version: 1;
+    session_id: string;
+    turn_id: string;
+    question_id: string;
+    error: {
+        code: "validation_rejected";
+        message: string;
+    };
+    question_status: "pending";
+};
+export type SubmitQuestionAnswerFailureV1 = {
+    ok: false;
+    error: {
+        code: "not_found" | "resource_gone" | "ownership_mismatch" | "terminal_uncertain" | "idempotency_conflict";
+        message: string;
+    };
+};
+export interface PrivateAskGateCodecV1 {
+    schema_version: 1;
+    labels: string[];
+    recommended_index: number | null;
+    multi: boolean;
+    allow_empty: boolean;
+    other_allowed: true;
+    clarification_allowed: true;
+}
+export declare function decodeAskGateV1(gate: WorkflowGate): PrivateAskGateCodecV1 | null;
+export declare function projectAskGateQuestion(input: {
+    question_id: string;
+    session_id: string;
+    turn_id: string;
+    status: CoordinatorQuestionStatusV1;
+    stage: string;
+    kind: string;
+    prompt: string;
+    codec: PrivateAskGateCodecV1;
+    created_at: string;
+    updated_at: string;
+    answered_at: string | null;
+    reason: PublicReason | null;
+    answer_binding?: string;
+}): CoordinatorQuestionPublicV1;
+export declare function validateCoordinatorAskAnswer(codec: PrivateAskGateCodecV1, answer: unknown): CoordinatorAskAnswerV1 | null;
+export declare function translateCoordinatorAskAnswer(codec: PrivateAskGateCodecV1, answer: CoordinatorAskAnswerV1): unknown;
+export declare function createAnswerBinding(): string;
+export declare function answerBindingMatches(binding: string, expected: string): boolean;