specrails-core 5.2.3 → 5.3.0

package/dist/installer/commands/v5-migration.d.ts

@@ -0,0 +1,32 @@
+export interface V5MigrationInput {
+    /** Absolute artifact root (in-repo repoRoot, or the relocated $HOME workspace). */
+    artifactRoot: string;
+    /** Provider directory name (`.claude` / `.codex` / `.gemini`). */
+    providerDir: string;
+}
+/**
+ * Removes artefacts a pre-v5 install left behind so the fresh v5 template set
+ * places into a clean tree. Strictly subtractive and reserved-path-safe:
+ *
+ *   - Removed agent files (`.claude/agents/sr-*.md`, `.gemini/agents/sr-*.md`)
+ *   - Removed command files (`<providerDir>/commands/specrails/*.md`) and their
+ *     codex skill dirs (`.codex/skills/<cmd>/`)
+ *   - The generated top-level skills for removed commands (`.claude/skills/<id>/`)
+ *   - Obsolete staging subtrees under `.specrails/setup-templates/`
+ *     (`personas/`, `skills/enrich/`, and the removed command/agent templates)
+ *   - VPC persona output dirs (`<providerDir>/agents/personas/`)
+ *
+ * `custom-*.md` agents and `.specrails/profiles/**` are protected by
+ * {@link isReservedPath}; files the installer never owned are not enumerated
+ * here, so they are untouched. When at least one path is removed a migration
+ * summary is printed so the user sees exactly what changed.
+ */
+export declare function migratePreV5Install(input: V5MigrationInput): void;
+/**
+ * Test helper: enumerate removed agent/command ids so specs can assert the
+ * migration set stays in lock-step with the deleted templates.
+ */
+export declare const V5_REMOVED: {
+    readonly agents: readonly ["sr-product-manager", "sr-product-analyst", "sr-test-writer", "sr-doc-sync", "sr-merge-resolver", "sr-frontend-developer", "sr-backend-developer", "sr-frontend-reviewer", "sr-backend-reviewer", "sr-security-reviewer", "sr-performance-reviewer"];
+    readonly commands: readonly ["enrich", "reconfig", "vpc-drift", "auto-propose-backlog-specs", "get-backlog-specs", "merge-resolve", "test"];
+};

package/dist/installer/phases/framework-lifecycle.d.ts

@@ -0,0 +1,53 @@
+import { type Provider } from './provider-detect.js';
+/**
+ * Stable provider order for the global framework store. `framework/current` is
+ * shared by every relocated workspace, so a version transition must carry
+ * forward every provider that can still have live links through that pointer.
+ */
+export declare const FRAMEWORK_PROVIDERS: readonly Provider[];
+export interface ResolveRequiredFrameworkProvidersInput {
+    frameworkDir: string;
+    /** Providers requested by the lifecycle operation that is about to swap. */
+    requested?: readonly Provider[];
+    /** Registry home. Defaults to SPECRAILS_REGISTRY_HOME / the normal home. */
+    registryHome?: string;
+}
+export interface MaterializeFrameworkVersionInput extends ResolveRequiredFrameworkProvidersInput {
+    scriptDir: string;
+    version: string;
+}
+/**
+ * Discover providers represented by a framework version.
+ *
+ * A provider is included when either its subtree or its stamp exists. For the
+ * current version this is deliberately conservative: an interrupted/legacy
+ * materialization without a stamp may still have live workspace symlinks, so
+ * the next version must carry that provider forward rather than dropping it.
+ */
+export declare function discoverFrameworkProviders(frameworkDir: string, version: string): Provider[];
+/**
+ * Compute the provider set that MUST exist in a destination version before the
+ * process may move the global `current` pointer:
+ *
+ *  1. providers requested by this operation;
+ *  2. every supported provider recorded by any project in registry.json;
+ *  3. every provider represented by the version currently serving workspaces.
+ *
+ * Taking the global registry union (not just the active project) is essential:
+ * `framework/current` is global, while provider inventories are per project.
+ */
+export declare function resolveRequiredFrameworkProviders(input: ResolveRequiredFrameworkProvidersInput): Provider[];
+/**
+ * Fail closed when a destination version is missing or only partially
+ * materialized. A valid provider requires BOTH its provider subtree and the
+ * final stamp written after scaffold completion, with matching version/provider
+ * fields. The caller may supply an empty requirement only for a first install;
+ * in that case at least one complete provider must be discoverable in target.
+ */
+export declare function assertFrameworkVersionComplete(frameworkDir: string, version: string, requiredProviders: readonly Provider[]): Provider[];
+/**
+ * Materialize a complete destination version and expose it with ONE atomic
+ * pointer swap. No call in the provider loop can move `current`; if any provider
+ * fails, existing workspaces continue resolving through the previous version.
+ */
+export declare function materializeFrameworkVersion(input: MaterializeFrameworkVersionInput): Provider[];

package/dist/installer/phases/install-config.d.ts

@@ -0,0 +1,64 @@
+import { InstallerError } from '../util/errors.js';
+/**
+ * Provider identifier. Kept in lock-step with `provider-detect.ts` `Provider`.
+ */
+export type Provider = 'claude' | 'codex' | 'gemini' | 'kimi';
+/** Cost / capability preset for the model picker. */
+export type ModelPreset = 'balanced' | 'budget' | 'max';
+/** Provider-native model selection retained verbatim in install-config.yaml. */
+export interface InstallModelConfig {
+    preset: ModelPreset;
+    defaults: {
+        model: string;
+    };
+    overrides: Record<string, string>;
+}
+/**
+ * Shape of the `.specrails/install-config.yaml` file — the single
+ * source of truth the TUI writes and the installer reads. Fields map
+ * 1:1 onto the grep-based parser in the retired install.sh.
+ */
+export interface InstallConfig {
+    version: 1;
+    provider: Provider;
+    agents: {
+        selected: string[];
+        excluded?: string[];
+        /** Legacy pre-models-section location, accepted for backward compatibility. */
+        preset?: ModelPreset;
+    };
+    models?: InstallModelConfig;
+}
+/**
+ * Resolve a preset into provider-native identifiers. Kimi currently exposes no
+ * Core-defined cost/capability tier mapping, so every named preset resolves to
+ * its explicit `k3` default. User-supplied exact identifiers are handled later
+ * and are never interpreted as Claude aliases.
+ */
+export declare function resolveProviderModelConfig(provider: Provider, preset?: ModelPreset): InstallModelConfig;
+export declare class InvalidConfigError extends InstallerError {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+export declare const CONFIG_RELATIVE_PATH = ".specrails/install-config.yaml";
+/**
+ * Resolves the install-config path: explicit argument > repo-root default.
+ */
+export declare function resolveConfigPath(repoRoot: string, explicit?: string): string;
+/**
+ * Reads and parses the install-config. Returns `null` if the file is
+ * not present — caller decides whether that's an error or a fallback.
+ */
+export declare function loadInstallConfig(configPath: string): InstallConfig | null;
+/**
+ * Validates an already-parsed YAML document. Collects every error
+ * before throwing so the user sees them all at once (matches the
+ * bash installer's `_config_errors` accumulator behaviour).
+ */
+export declare function validateInstallConfig(raw: unknown): InstallConfig;
+/**
+ * Serialises an {@link InstallConfig} back to YAML and writes it with
+ * LF line endings. Used by `npx specrails-core update --reset-config`
+ * paths (not wired yet) and by tests.
+ */
+export declare function writeInstallConfig(configPath: string, config: InstallConfig): void;

package/dist/installer/phases/manifest.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shape of the `.specrails/specrails-manifest.json` file the installer
+ * writes at install time. Consumers (specrails-desktop's compat check,
+ * the `doctor` command, update.sh) parse it to detect template drift.
+ */
+export interface SpecrailsManifest {
+    version: string;
+    installed_at: string;
+    /** Provider inventory is emitted only by provider-aware lifecycle callers. */
+    providers?: string[];
+    primary_provider?: string;
+    artifacts: Record<string, string>;
+}
+/**
+ * Computes a stable sha256 digest for a file, returned as `sha256:<hex>`.
+ */
+export declare function sha256Of(filePath: string): string;
+export interface BuildManifestInput {
+    /** Absolute path to the specrails-core source package directory. */
+    scriptDir: string;
+    /** Absolute path to the user's repo root where the manifest is written. */
+    repoRoot: string;
+    /** Version string from the specrails-core VERSION file. */
+    version: string;
+    /** Override "installed_at" — exposed for deterministic testing. */
+    installedAt?: string;
+    /** Provider(s) materialized by this lifecycle pass. Existing entries are unioned. */
+    providers?: string[];
+    primaryProvider?: string;
+}
+/**
+ * Walks `templates/**` plus the bundled doctor command file and
+ * produces a stable-sorted manifest.
+ *
+ * Stable-sort rule: artifact keys are sorted ascending by POSIX path.
+ */
+export declare function buildManifest(input: BuildManifestInput): SpecrailsManifest;
+/**
+ * Writes the manifest JSON and the companion version file under
+ * `.specrails/` in the user repo. Both files use LF terminators.
+ */
+export declare function writeManifestFiles(repoRoot: string, manifest: SpecrailsManifest): {
+    manifestPath: string;
+    versionPath: string;
+};

package/dist/installer/phases/prereqs.d.ts

@@ -0,0 +1,51 @@
+import { type Provider, type ProviderAvailability } from './provider-detect.js';
+/**
+ * OpenSpec 1.4.1, which the installer invokes during the default init/update
+ * flow, requires Node >=20.19.0. Keep this floor independent from Kimi's npm
+ * package requirement: SpecRails launches an externally installed Kimi CLI and
+ * does not require the Kimi npm distribution.
+ */
+export declare const MIN_NODE_VERSION = "20.19.0";
+export declare function isSupportedNodeVersion(version: string): boolean;
+/**
+ * Phase 1 prerequisite bundle. Mirrors install.sh's Phase 1 flow but
+ * with explicit options rather than a grab-bag of globals.
+ *
+ * Returns the resolved inputs later phases need — primarily the
+ * selected provider and the detected CLI availability.
+ */
+export interface PrereqOptions {
+    /** Absolute path to the target repository root. */
+    repoRoot: string;
+    /** --yes / -y equivalent — auto-init git, skip interactive prompts. */
+    autoYes: boolean;
+    /** Explicit --provider flag (if passed). */
+    explicitProvider?: Provider;
+    /** SPECRAILS_SKIP_PREREQS=1 equivalent — relax hard failures for CI. */
+    skipPrereqs: boolean;
+}
+export interface PrereqResult {
+    availability: ProviderAvailability;
+    provider: Provider;
+    /**
+     * OSS heuristics. Three signals must align for `isOss` to be true:
+     * a public GitHub repo (via `gh repo view`), at least one CI workflow
+     * file under `.github/workflows/`, and a `CONTRIBUTING.md` at the
+     * repo root or under `.github/`. Surfaced for downstream tooling that
+     * wants to tailor behaviour to open-source projects.
+     */
+    ossSignals: OssSignals;
+}
+export interface OssSignals {
+    hasGh: boolean;
+    publicRepo: boolean;
+    hasCi: boolean;
+    hasContributing: boolean;
+    isOss: boolean;
+}
+/**
+ * Orchestrates every prerequisite check that must pass before the
+ * installer proceeds to Phase 3 (scaffolding). Emits ok/warn/info
+ * lines matching the retired bash output.
+ */
+export declare function checkPrerequisites(options: PrereqOptions): Promise<PrereqResult>;

package/dist/installer/phases/provider-detect.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Provider detection + authentication checks. These mirror the Phase
+ * 1.2 / 1.3 branches of the retired install.sh.
+ */
+export type Provider = 'claude' | 'codex' | 'gemini' | 'kimi';
+/** Oldest TypeScript Kimi Code CLI release covered by this integration. */
+export declare const MIN_KIMI_VERSION = "0.27.0";
+export interface ProviderAvailability {
+    claude: boolean;
+    codex: boolean;
+    /** Optional so callers/tests predating Gemini still typecheck; absent = false. */
+    gemini?: boolean;
+    /** Optional so callers/tests predating Kimi still typecheck; absent = false. */
+    kimi?: boolean;
+}
+export interface ProviderDerivedPaths {
+    /** Root directory inside the user's repo: `.claude` / `.codex` / `.gemini` / `.kimi-code`. */
+    providerDir: string;
+    /** Instructions file relative to the artifact root. */
+    instructionsFile: string;
+}
+/**
+ * Detects which AI CLIs are on PATH. Runs `where` on Windows and
+ * `which` on POSIX via the cross-platform commandExists helper.
+ */
+export declare function detectAvailability(): Promise<ProviderAvailability>;
+/**
+ * Returns the Claude CLI version string (stdout of `claude --version`)
+ * or 'unknown' if the CLI cannot be invoked.
+ */
+export declare function claudeVersion(): Promise<string>;
+/** Returns the raw Kimi Code CLI version or `unknown` when it cannot be probed. */
+export declare function kimiVersion(): Promise<string>;
+/** Extracts a semver-like triple from version output such as `kimi-code 0.27.0`. */
+export declare function parseCliVersion(raw: string): string | null;
+/** True when `raw` identifies a Kimi CLI at or above {@link MIN_KIMI_VERSION}. */
+export declare function isSupportedKimiVersion(raw: string): boolean;
+/**
+ * Resolves which provider the installer should use. Priority:
+ *   1. Explicit `--provider claude` flag (already passed through args).
+ *   2. Config file (read upstream in install-config.ts).
+ *   3. Whichever CLI is installed.
+ *
+ * The caller may bypass prereq failures with `skipPrereqs: true`
+ * (env `SPECRAILS_SKIP_PREREQS=1`).
+ */
+export declare function resolveProvider(availability: ProviderAvailability, options?: {
+    explicit?: Provider;
+    skipPrereqs?: boolean;
+}): Promise<Provider>;
+/**
+ * Directory / filename conventions the provider dictates.
+ *   - Claude Code:  .claude/ + CLAUDE.md
+ *   - Codex:        .codex/  + AGENTS.md
+ *   - Gemini CLI:   .gemini/ + GEMINI.md
+ *   - Kimi Code:    .kimi-code/ + AGENTS.md
+ */
+export declare function derivedPaths(provider: Provider): ProviderDerivedPaths;
+/**
+ * Asserts that Claude Code is authenticated. Matches the three-path
+ * check from install.sh: `claude config list` → ANTHROPIC_API_KEY env →
+ * ~/.claude.json OAuth.
+ */
+export declare function assertClaudeAuthenticated(options?: {
+    skipPrereqs?: boolean;
+}): Promise<void>;
+export type KimiAuthenticationStatus = 'authenticated' | 'unauthenticated' | 'unknown';
+/**
+ * Bounded, non-billing Kimi authentication probe.
+ *
+ * Kimi 0.27 has no CLI command that proves managed OAuth readiness without
+ * starting a model request. We therefore recognise non-secret evidence (the
+ * managed credential file or a process-scoped model key), and honour explicit
+ * login failures emitted by `kimi doctor`. A successful `kimi doctor` only
+ * validates configuration, so it deliberately yields `unknown`.
+ */
+export declare function probeKimiAuthentication(options?: {
+    kimiCodeHome?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<KimiAuthenticationStatus>;
+/**
+ * Rejects only a conclusive login failure. `unknown` is allowed because setup
+ * must not spend quota merely to prove authentication.
+ */
+export declare function assertKimiAuthenticated(options?: {
+    skipPrereqs?: boolean;
+    kimiCodeHome?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<KimiAuthenticationStatus>;

package/dist/installer/phases/scaffold.d.ts

@@ -0,0 +1,211 @@
+import type { Provider } from './provider-detect.js';
+/**
+ * The three baseline agents — the COMPLETE set of agents the installer
+ * ships. The implement pipeline depends on all three. Any additional agent
+ * comes from a user-authored profile (`custom-*`), never the installer.
+ *
+ * Mirrors the `allOf` baseline in schemas/profile.v1.json — update
+ * both files together if this set ever changes.
+ */
+export declare const CORE_AGENTS: Set<string>;
+/**
+ * Rewrite every literal `Skill("opsx:<id>"[, …])` call in a Claude-authored agent
+ * body into the Gemini `activate_skill(name="…")` form. Positional skill input
+ * (e.g. `"<specName>"`) is dropped because `activate_skill` takes only `name` and
+ * the surrounding persona prose already carries the context. Unknown ids are left
+ * untouched (better a visible stale ref than a silent `name="undefined"`). This
+ * runs ONLY on the gemini render path; Claude/Codex keep the `Skill(...)` form.
+ */
+export declare function translateOpsxSkillCallsForGemini(body: string): string;
+/**
+ * Port shared Claude-authored prose to Kimi's directory-skill contract.
+ *
+ * Kimi's TUI/ACP clients intercept `/skill:*`, but a materialized workflow is
+ * already running inside a Session and must activate nested workflows through
+ * Kimi's built-in `Skill` tool (`{ skill, args }`). Emitting slash text here
+ * would silently become ordinary model text under `kimi -p`. Interactive slash
+ * examples therefore belong only in AGENTS/docs, never generated skill bodies.
+ * This is render-only; canonical Claude/Codex/Gemini templates stay unchanged.
+ */
+export declare function translateClaudeTextForKimi(body: string): string;
+export declare function geminiAgentLimitMetadata(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Phase 2 + Phase 3 of the retired install.sh:
+ *   - Detect prior installation state (.claude/.codex/openspec already present).
+ *   - Create the directory skeleton.
+ *   - Copy templates into `.specrails/setup-templates/` (the internal
+ *     staging dir that placement copies from and `update` diffs against).
+ *   - Ensure `.gitignore` excludes the runtime artefacts.
+ *
+ * Placement (`placeArtefacts`) then copies the staged templates directly into
+ * the user's live `.claude/agents/` and `.claude/commands/specrails/` dirs so
+ * the installer finishes in one pass — no follow-up wizard required.
+ */
+export interface ScaffoldInput {
+    /** Absolute path to the specrails-core package (installed via npx). */
+    scriptDir: string;
+    /**
+     * Absolute path to the relocated artifact root — where every Specrails-managed
+     * artifact (.specrails/.claude/.codex/.gemini/.kimi-code and instruction/settings files)
+     * is written. Under relocate-always this is the `$HOME` workspace, NOT the repo.
+     */
+    artifactRoot: string;
+    /**
+     * Absolute path to the user's repo root — the ONLY thing that stays in-repo is
+     * `openspec/**` (installed by init.ts) and git/worktree ops. Used solely by
+     * `detectExistingSetup`'s openspec probe and the gitignore no-op guard.
+     */
+    codeRoot: string;
+    /** Resolved provider from prereqs. */
+    provider: Provider;
+    /** Derived directory name (`.claude` or `.codex`). */
+    providerDir: string;
+    /** Optional explicit allow-list used by config-driven installs. */
+    selectedAgents?: string[];
+    /**
+     * When false, the static-placement helpers do NOT create the per-workspace
+     * mutable seeds (agent-memory dirs, gemini headless acknowledgments). Used by
+     * `installFramework` so the SHARED framework copy stays purely provider-static
+     * — the project layer is seeded separately by `assembleProjectWorkspace`.
+     * Defaults to true (legacy in-place behaviour for `scaffoldInstallation`).
+     */
+    seedProjectDirs?: boolean;
+    /**
+     * When true, place EVERY agent template (the full superset) regardless of
+     * `selectedAgents`. Used by `installFramework` so
+     * the SHARED framework store is a superset that ANY project's selection can
+     * link from — per-project agent filtering then happens at the workspace LINK
+     * step (`linkAgentFiles`), not at materialization. Defaults to false (legacy
+     * selection-honouring placement for in-place `scaffoldInstallation`).
+     */
+    materializeAllAgents?: boolean;
+}
+export interface ScaffoldResult {
+    existingSetup: boolean;
+    createdDirs: string[];
+    copiedFiles: number;
+}
+/**
+ * Returns true iff any of the provider directories already contains
+ * content. The desktop-app-driven path skips the "merge existing?" prompt and
+ * assumes `--yes`; the CLI dispatcher (bin/specrails-core.cjs) should
+ * have prompted before entering this phase.
+ */
+export declare function detectExistingSetup(input: Pick<ScaffoldInput, 'artifactRoot' | 'codeRoot' | 'providerDir'>): boolean;
+/**
+ * Entry point. Creates directories, copies templates, updates
+ * .gitignore. Returns a summary for logging / tests.
+ */
+export declare function scaffoldInstallation(input: ScaffoldInput): ScaffoldResult;
+export interface InstallFrameworkInput {
+    /** Absolute path to the specrails-core package (templates/ + commands/). */
+    scriptDir: string;
+    /** Root of the versioned framework store, e.g. `<home>/.specrails/framework`. */
+    frameworkDir: string;
+    /** Provider whose static subtree is being materialized. */
+    provider: Provider;
+    /** Derived provider dir (`.claude`/`.codex`/`.gemini`/`.kimi-code`). */
+    providerDir: string;
+    /** Framework version (the `<version>/` segment). */
+    version: string;
+    /** Optional explicit agent allow-list (kept for parity with scaffold). */
+    selectedAgents?: string[];
+}
+export interface InstallFrameworkResult {
+    /** `<frameworkDir>/<version>/<providerDir>` — root of the static subtree. */
+    providerFrameworkDir: string;
+    /** `<frameworkDir>/<version>` — the version root (also holds setup-templates/). */
+    versionDir: string;
+    /** True when a fresh materialization happened; false when the idempotent skip fired. */
+    materialized: boolean;
+}
+/** Path to the per-version, per-provider materialization marker (manifest hash). */
+export declare function frameworkStampPath(versionDir: string, providerDir: string): string;
+/**
+ * Validate one provider in a materialized version without needing the source
+ * package. Used by the final swap gate: the stamp identity and current output
+ * hash must still agree immediately before `current` moves.
+ */
+export declare function frameworkMaterializationProblem(versionDir: string, version: string, provider: Provider, providerDir: string): string | null;
+/**
+ * Materialize the provider-INVARIANT framework subtree ONCE into
+ * `<frameworkDir>/<version>/<providerDir>/` (+ `<version>/setup-templates/`).
+ * Idempotent: when the providerDir already exists with a matching stamp it is a
+ * no-op (the second workspace assemble re-uses the same copy). Writes NO
+ * per-workspace state (no agent-memory, no acks, no project-named instruction
+ * files) — those are seeded by `assembleProjectWorkspace`.
+ */
+export declare function installFramework(input: InstallFrameworkInput): InstallFrameworkResult;
+/**
+ * Atomically point `<frameworkDir>/current` at `<version>` so every workspace's
+ * provider links resolve through `current/...` and an update is a single swap.
+ */
+export declare function ensureCurrentSymlink(frameworkDir: string, version: string): void;
+export interface AssembleProjectWorkspaceInput {
+    /** The per-project workspace artifact root (= resolveArtifacts artifactRoot). */
+    workspace: string;
+    /** Root of the versioned framework store (the parent of `current/`). */
+    frameworkDir: string;
+    /** Provider whose subtrees are linked into the workspace. */
+    provider: Provider;
+    /** Derived provider dir (`.claude`/`.codex`/`.gemini`/`.kimi-code`). */
+    providerDir: string;
+    /** Framework version (used for the manifest record). */
+    version: string;
+    /** The user's real repo (drives PROJECT_NAME + gemini ack keying). */
+    codeRoot: string;
+    /** specrails-core package dir (for the manifest hash sources). */
+    scriptDir: string;
+    /**
+     * Optional agent allow-list. Drives BOTH which framework agents are LINKED
+     * into the workspace (`linkAgentFiles`) AND which agent-memory dirs are seeded.
+     * Undefined = the CORE trio only (the lean default). The SHARED framework store
+     * is always the full superset; this is where per-project filtering happens.
+     */
+    selectedAgents?: string[];
+    /**
+     * When true, the static provider subtrees (`agents`/`commands`/`skills`/`rules`)
+     * and the settings file are COPIED as real files from the framework store into
+     * the workspace instead of SYMLINKED. Used by the in-repo standalone install
+     * (`init`/`update` with `artifactRoot === codeRoot`) so the repo gets real,
+     * committable files — a symlink into `$HOME/.specrails/framework` would be
+     * invisible to a standalone user's `claude`/`codex`/`gemini`/`kimi` running in the
+     * repo. The PROJECT layer (agent-memory, manifest, instruction files) is real
+     * either way. Defaults to false (relocated workspaces symlink — the desktop /
+     * `--relocate` path).
+     */
+    copyStatics?: boolean;
+}
+export interface AssembleProjectWorkspaceResult {
+    /** Per-linked-subtree mechanism, for diagnostics (copy-fallback loses O(1) swap). */
+    links: Record<string, 'symlink' | 'junction' | 'copy'>;
+    /** Agent ids whose memory dirs were seeded as real writable dirs. */
+    seededMemoryAgents: string[];
+}
+/**
+ * Assemble a project workspace with NO network and NO re-materialization: (a)
+ * SYMLINK the static providerDir subtrees from `<frameworkDir>/current/
+ * <providerDir>/` into `<workspace>/<providerDir>/`, then (b) seed the PROJECT
+ * layer as real writable files (agent-memory dirs, the manifest, project-named
+ * instruction/settings files, gemini headless acks re-hashed against the LINKED
+ * files). `agent-memory/` is NEVER linked.
+ */
+export declare function assembleProjectWorkspace(input: AssembleProjectWorkspaceInput): AssembleProjectWorkspaceResult;
+/**
+ * Pre-acknowledge the generated gemini subagents so they load in HEADLESS
+ * (`gemini -p`) runs. gemini 0.46+ DISCOVERS `.gemini/agents/*.md` but only
+ * ENABLES a project's custom agents after the interactive "New Agents Discovered
+ * → Acknowledge and Enable" prompt — which never fires headless, so
+ * `invoke_agent sr-architect` returns "Subagent not found" and the implement
+ * orchestrator silently falls back to a generic agent (the specialised personas
+ * never run, the pipeline degrades). The acknowledgment is a user-global file
+ * `~/.gemini/acknowledgments/agents.json` shaped
+ * `{ [projectRoot]: { [agentName]: <sha256-hex of the agent .md file> } }`
+ * (hash algorithm verified empirically against gemini 0.47 = sha256 of the full
+ * file). Writing it at install time makes the freshly-generated agents trusted
+ * with no prompt, for both `gemini` CLI and the desktop's headless spawns. The
+ * file is MERGED — other projects' and other agents' entries are preserved.
+ * Best-effort: any failure is swallowed by the caller (agents still work once
+ * acknowledged interactively).
+ */
+export declare function writeGeminiAgentAcknowledgments(repoRoot: string, agentIds: string[], agentsBaseDir?: string): void;

package/dist/installer/runtime/kimi.d.ts

@@ -0,0 +1,84 @@
+export type KimiThinkingEffort = 'low' | 'high' | 'max';
+export interface KimiInvocationInput {
+    /** Raw profile model id. Official short aliases are normalized at launch. */
+    model: string;
+    /** Plain prompt. Required when `skill` is omitted. */
+    prompt?: string;
+    /** Safe direct-child skill directory id. Uses the managed runner when set. */
+    skill?: string;
+    /** Raw skill argument string expanded with Kimi's native placeholder rules. */
+    skillArguments?: string;
+    /** A session id emitted by a prior `session.resume_hint` event. */
+    sessionId?: string;
+    thinkingEffort?: KimiThinkingEffort;
+    /** Additional source/worktree roots exposed to this independent process. */
+    additionalDirs?: string[];
+    /** Absolute paths only. Kimi prompt mode has no attachment argv flag. */
+    attachmentPaths?: string[];
+    /** Override for callers whose workspace exposes the managed runner elsewhere. */
+    skillRunnerPath?: string;
+}
+export interface KimiInvocation {
+    bin: 'kimi' | 'node';
+    args: string[];
+    /** Process-environment overlay; no credentials are added or persisted. */
+    env: Record<string, string | undefined>;
+    prompt: string;
+    /** Text piped to the managed runner; never placed in subprocess argv. */
+    stdinText?: string;
+}
+export declare const KIMI_SKILL_RUNNER_PATH = ".kimi-code/specrails/run-skill.mjs";
+/**
+ * Profiles retain raw provider ids. At the CLI boundary only the three managed
+ * Kimi aliases gain their documented `kimi-code/` namespace; custom model ids
+ * and already-qualified aliases remain byte-identical.
+ */
+export declare function normalizeKimiCliModel(model: string): string;
+/**
+ * Canonical daemon-free Kimi invocation consumed by Desktop and scripts.
+ * Plain prompts cross stdin into Core's managed Node helper so they never
+ * appear in the host-to-helper argv. The helper must pass the exact user turn
+ * through Kimi 0.27's only non-interactive API, `-p <prompt>`: native Kimi
+ * binaries therefore expose it in their own process argv, while supported npm
+ * Windows shims receive it through the exact stdin bootstrap. Skills also
+ * pre-render direct-child SKILL.md because prompt mode treats `/skill:...` as
+ * literal user text.
+ */
+export declare function buildKimiInvocation(input: KimiInvocationInput): KimiInvocation;
+export type KimiStreamEvent = {
+    kind: 'empty';
+} | {
+    kind: 'invalid';
+    raw: string;
+} | {
+    kind: 'assistant';
+    content: string;
+    raw: Record<string, unknown>;
+} | {
+    kind: 'tool';
+    raw: Record<string, unknown>;
+} | {
+    kind: 'resume_hint';
+    sessionId: string;
+    raw: Record<string, unknown>;
+} | {
+    kind: 'meta';
+    raw: Record<string, unknown>;
+} | {
+    kind: 'unknown';
+    raw: Record<string, unknown>;
+};
+/**
+ * Tolerant JSONL parser for Kimi 0.27. Unknown and malformed lines are surfaced
+ * to the caller rather than terminating the run. Kimi emits no structured USD
+ * cost, so this parser intentionally exposes no fabricated cost field.
+ */
+export declare function parseKimiStreamLine(line: string): KimiStreamEvent;
+/**
+ * Returns a resumable id only when Kimi exited successfully and its final
+ * non-empty JSONL record is a canonical `session.resume_hint`. Kimi may emit a
+ * hint before assigning a non-zero process exit status (for example an
+ * incomplete headless goal), so callers must supply the observed child exit
+ * code rather than treating the record alone as proof of success.
+ */
+export declare function extractKimiSessionHint(lines: Iterable<string>, exitCode: number | null): string | null;