@khorsheed/dsh-local-agent-kimi 0.1.0-rc.6

package/lib/types/provision.js

@@ -0,0 +1,363 @@
+/**
+ * Kimi Code scoped-home provisioning: a working `config.toml` (provider and
+ * model definitions) is required for the ACP server to authenticate. The
+ * scoped home is provisioned once — from the user's own config, redacted —
+ * so the scoped setup mirrors the user's models while carrying no secrets.
+ * Sign-out removes the credentials and OAuth cache so a later login can
+ * authorize a different account. The agent preset the delegation tool row
+ * needs is bootstrapped into the user preset root on first boot, so
+ * installing the bundle needs no manual copy step.
+ * @module @khorsheed/dsh-local-agent-kimi/provision
+ */
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const REAL_CONFIG = join(homedir(), '.kimi-code', 'config.toml');
+/** Credentials directory inside the scoped home; its presence marks auth. */
+const CREDENTIALS_DIR = 'credentials';
+/** OAuth token cache directory inside the scoped home. */
+const OAUTH_DIR = 'oauth';
+/**
+ * The managed provider's endpoint, written into a fresh scoped config and the
+ * baseline the eval snapshot compares against: a scoped config still pointing
+ * here routes through kimi's own service, i.e. no custom endpoint is in force.
+ */
+export const KIMI_MANAGED_BASE_URL = 'https://api.kimi.com/coding/v1';
+/**
+ * The reasoning effort a fresh scoped config gets when the plugin config does
+ * not override it — the value the pre-config-item provisioning hardcoded, so
+ * the default is behavior-preserving.
+ */
+export const DEFAULT_THINKING_EFFORT = 'high';
+/** Minimal managed config for a fresh home with no user config to mirror. */
+function minimalConfig(model, thinkingEffort) {
+    return `default_model = "${model}"
+
+[thinking]
+enabled = true
+effort = "${thinkingEffort}"
+
+[providers."managed:kimi-code"]
+base_url = "${KIMI_MANAGED_BASE_URL}"
+type = "kimi"
+api_key = ""
+
+[providers."managed:kimi-code".oauth]
+storage = "file"
+key = "oauth/kimi-code"
+
+[models."${model}"]
+provider = "managed:kimi-code"
+model = "${model.split('/').pop()}"
+max_context_size = 1048576
+capabilities = [ "thinking", "always_thinking", "image_in", "video_in", "tool_use" ]
+display_name = "${model}"
+support_efforts = [ "low", "high", "max" ]
+default_effort = "${thinkingEffort}"
+`;
+}
+/**
+ * Redact every api_key value so the scoped copy carries no secrets. The
+ * kimi-managed provider keeps an empty api_key (its auth routes through
+ * oauth), which is exactly what an empty value means here.
+ * @param config - the user's config text.
+ * @returns the same config with all api_key values blanked.
+ */
+export function redactApiKeys(config) {
+    return config.replace(/api_key\s*=\s*"[^"]*"/gu, 'api_key = ""');
+}
+/**
+ * Provision `<homeDir>/config.toml` unless one already exists. A present
+ * config is respected untouched (a person may have edited it); otherwise the
+ * user's own real config is copied redacted so the scoped home mirrors the
+ * user's models; with no real config, a minimal kimi-managed config is
+ * written. `thinkingEffort` feeds the minimal config's `[thinking] effort`
+ * (and the model's `default_effort`) — it applies at provision time only,
+ * never retroactively to an existing config.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @param model - the kimi-managed model id for a fresh minimal config.
+ * @param thinkingEffort - the reasoning effort a fresh minimal config pins.
+ * @returns true when a config was written, false when one already existed.
+ */
+export async function provisionKimiConfig(homeDir, model, thinkingEffort) {
+    try {
+        await readFile(join(homeDir, 'config.toml'));
+        return false;
+    }
+    catch (error) {
+        // No config yet: fall through to provisioning.
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    let config = minimalConfig(model, thinkingEffort);
+    try {
+        config = redactApiKeys(await readFile(REAL_CONFIG, 'utf8'));
+    }
+    catch (error) {
+        // No user config to mirror; the minimal managed config stands.
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    // `wx` refuses to overwrite a config that appeared since the read check.
+    await writeFile(join(homeDir, 'config.toml'), config, { flag: 'wx' });
+    return true;
+}
+/** The managed-service provider section provisioned into the scoped config. */
+const MANAGED_PROVIDER_SECTION = 'providers."managed:kimi-code"';
+/**
+ * Read the scoped config's effective LLM endpoint: the
+ * `[providers."managed:kimi-code"].base_url` key, if present. A missing or
+ * malformed config yields undefined (the CLI falls back to its default
+ * endpoint). Used only for diagnostics — the config itself is authoritative,
+ * and a user-edited value is respected untouched.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns the configured base URL, or undefined when absent/unreadable.
+ */
+export async function readKimiBaseUrl(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, 'config.toml'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    // Section-aware line scan: key order inside the provider table is the
+    // writer's choice, so base_url must be found wherever it sits in the
+    // section — a diagnostic that silently reports the default would mislead.
+    let section = '';
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trim();
+        const header = /^\[+([^\]]+)\]+$/.exec(line);
+        if (header !== null) {
+            section = header[1];
+            continue;
+        }
+        if (section === MANAGED_PROVIDER_SECTION) {
+            const match = /^base_url\s*=\s*"([^"]*)"$/.exec(line);
+            if (match !== null)
+                return match[1];
+        }
+    }
+    return undefined;
+}
+/**
+ * Read the scoped config's configured default model: the top-level
+ * `default_model` key — the selection a plain `kimi -p` round runs with. A
+ * missing or malformed config, or no key, yields undefined — the honest
+ * "unknown", never a guessed default. Read-only: the config is authoritative
+ * and a user-edited value is reported as-is.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns the configured model identifier, or undefined when none is set.
+ */
+export async function readKimiDefaultModel(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, 'config.toml'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    // default_model is a top-level key, so it only counts before the first
+    // table header — the same rule the other readers apply.
+    let section = '';
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trim();
+        const header = /^\[+([^\]]+)\]+$/.exec(line);
+        if (header !== null) {
+            section = header[1];
+            continue;
+        }
+        if (section !== '')
+            continue;
+        const key = /^(\w+)\s*=\s*"([^"]*)"$/.exec(line);
+        if (key !== null && key[1] === 'default_model')
+            return key[2];
+    }
+    return undefined;
+}
+/**
+ * List the model identifiers the scoped config DEFINES: every
+ * `[models."…"]` table key (bare `[models.x]` keys included). This is the
+ * pickable vocabulary a model surface can offer without hardcoding a catalog —
+ * the same table `-m` resolves against. A missing or malformed config yields
+ * an empty list. Read-only: the config is authoritative.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns the defined model identifiers, in file order, deduplicated.
+ */
+export async function listKimiConfigModels(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, 'config.toml'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const models = [];
+    for (const rawLine of text.split('\n')) {
+        const header = /^\[+([^\]]+)\]+$/.exec(rawLine.trim());
+        if (header === null)
+            continue;
+        const table = /^models\.(?:"([^"]+)"|([\w-]+))$/.exec(header[1]);
+        const name = table?.[1] ?? table?.[2];
+        if (name !== undefined && name !== '' && !models.includes(name))
+            models.push(name);
+    }
+    return models;
+}
+/**
+ * Rewrite the scoped config's top-level `default_model` to `model`, so the
+ * NEXT process started under this home runs that model. This is the resident
+ * path's only lever: `kimi acp` takes no model flag (verified against kimi
+ * 0.39.1), while `kimi -p` takes `-m` — so the one-shot rounds pass the flag
+ * and the live driver writes the file before spawning its runtime.
+ *
+ * The write is surgical: the first top-level `default_model` assignment is
+ * replaced in place and everything else — model tables, providers, thinking
+ * effort, comments, key order — is left byte-identical. A config with no
+ * top-level `default_model` gains one as its first line; an absent or
+ * unreadable config is left alone (provisioning owns creation, and inventing
+ * a config here would hide a broken home).
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @param model - the model identifier to pin as the default.
+ * @returns true when the file now names `model`, false when there was no
+ *   config to write into.
+ */
+export async function writeKimiDefaultModel(homeDir, model) {
+    const path = join(homeDir, 'config.toml');
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    // TOML basic strings take backslash escapes; a model id with a quote or a
+    // backslash would otherwise produce a config kimi cannot parse.
+    const assignment = `default_model = "${model.replace(/\\/gu, '\\\\').replace(/"/gu, '\\"')}"`;
+    const lines = text.split('\n');
+    let section = '';
+    for (const [index, rawLine] of lines.entries()) {
+        const line = rawLine.trim();
+        const header = /^\[+([^\]]+)\]+$/.exec(line);
+        if (header !== null) {
+            section = header[1];
+            continue;
+        }
+        // Top-level only, exactly as readKimiDefaultModel scans for it.
+        if (section !== '')
+            continue;
+        const key = /^(\w+)\s*=/.exec(line);
+        if (key === null || key[1] !== 'default_model')
+            continue;
+        if (line === assignment)
+            return true;
+        lines[index] = assignment;
+        await writeFile(path, lines.join('\n'), 'utf8');
+        return true;
+    }
+    await writeFile(path, `${assignment}\n${text}`, 'utf8');
+    return true;
+}
+/**
+ * Read the scoped config's effective reasoning effort: the `[thinking] effort`
+ * key, falling back to a `[models."…"]` section's `default_effort` when the
+ * thinking table carries none (the CLI resolves effort the same way). A
+ * missing or malformed config, or no effort key anywhere, yields undefined —
+ * the honest "unknown", never a guessed default. Read-only: the config is
+ * authoritative, a user-edited value is reported as-is.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns the effective effort, or undefined when it cannot be determined.
+ */
+export async function readKimiReasoningEffort(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, 'config.toml'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    // Section-aware line scan (same shape as readKimiBaseUrl): effort must be
+    // found wherever it sits in its section, and only the thinking table's own
+    // effort counts before any model default does.
+    let section = '';
+    let thinkingEffort;
+    let modelDefaultEffort;
+    for (const rawLine of text.split('\n')) {
+        const line = rawLine.trim();
+        const header = /^\[+([^\]]+)\]+$/.exec(line);
+        if (header !== null) {
+            section = header[1];
+            continue;
+        }
+        const key = /^(\w+)\s*=\s*"([^"]*)"$/.exec(line);
+        if (key === null)
+            continue;
+        if (section === 'thinking' && key[1] === 'effort' && thinkingEffort === undefined)
+            thinkingEffort = key[2];
+        if (section.startsWith('models.') && key[1] === 'default_effort' && modelDefaultEffort === undefined) {
+            modelDefaultEffort = key[2];
+        }
+    }
+    return thinkingEffort ?? modelDefaultEffort;
+}
+/**
+ * Whether the scoped config's permission rules auto-approve the subagent's
+ * tool use: the `Bash(*)` allow rule the provisioning gate
+ * ({@link ensureKimiPermissions}) keys on, detected with the exact same
+ * substring so the snapshot and the provisioning can never disagree about
+ * the same file.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns whether the auto-approve rule is present.
+ */
+export async function readKimiAutoApprove(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, 'config.toml'), 'utf8');
+    }
+    catch {
+        return false;
+    }
+    return text.includes('pattern = "Bash(*)');
+}
+/** Permission rule block letting the kimi subagent run shell commands. */
+const KIMI_PERMISSION_BLOCK = `
+[[permission.rules]]
+decision = "allow"
+pattern = "Bash(*)"
+reason = "let the kimi subagent run shell commands"
+`;
+/**
+ * Ensure the scoped config allows the subagent's tool use. The one-shot
+ * `kimi -p` child uses the config's permission rules, so without a rule it
+ * answers without executing tools. Idempotent; an existing rule is respected.
+ * @param homeDir - the `kimi` harness's scoped home.
+ */
+export async function ensureKimiPermissions(homeDir) {
+    const file = join(homeDir, 'config.toml');
+    let content;
+    try {
+        content = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        // No config yet; provisioning will write one with the rules when it runs.
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (content.includes('pattern = "Bash(*)'))
+        return;
+    await writeFile(file, `${content.trimEnd()}\n${KIMI_PERMISSION_BLOCK}`);
+}
+/**
+ * Sign out of the scoped account: remove the credentials and OAuth token
+ * cache, so `/<name> status` reports not authenticated and the next login
+ * authorizes a fresh account. The kimi CLI has no `logout` command, so the
+ * scoped files are the logout path.
+ * @param homeDir - the `kimi` harness's scoped home.
+ */
+export async function kimiLogout(homeDir) {
+    await Promise.all([
+        rm(join(homeDir, CREDENTIALS_DIR), { recursive: true, force: true }),
+        rm(join(homeDir, OAUTH_DIR), { recursive: true, force: true }),
+    ]);
+}

package/lib/types/records.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Kimi Code session records adapter: reads the scoped home's
+ * `session_index.jsonl`, kimi's own append-only index.
+ * @module @khorsheed/dsh-local-agent-kimi/records
+ */
+import type { LocalAgentSessionRecord } from '@khorsheed/dsh-local-agent';
+/**
+ * Whether the scoped home holds usable login credentials, guarded by the
+ * credential sentinel: a VALID credential file (both tokens non-empty) reads
+ * true and refreshes the backup; an empty shell (the kimi CLI's failure-path
+ * wipe) restores the backup when one exists and reads false otherwise. The
+ * pre-sentinel "directory non-empty" check could not tell the empty shell
+ * from a real credential at all.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns true when usable credentials are present (after any restore).
+ */
+export declare function kimiAuthenticated(homeDir: string): Promise<boolean>;
+/**
+ * The newest credential file's modification stamp (epoch ms), undefined when
+ * no credential exists. A completed device-code login rewrites the
+ * credentials directory, so the stamp distinguishes a fresh login from a
+ * leftover (possibly expired) credential.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns the newest credential mtime, or undefined when none exists.
+ */
+export declare function kimiCredentialStamp(homeDir: string): Promise<number | undefined>;
+/**
+ * Read the scoped home's session index. The index is kimi's own
+ * newline-delimited JSONL; a torn tail line (the file is append-only) is
+ * skipped rather than failing the whole list.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns the parsed records in file order, empty when no index exists yet.
+ */
+export declare function listKimiSessions(homeDir: string): Promise<readonly LocalAgentSessionRecord[]>;
+//# sourceMappingURL=records.d.ts.map

package/lib/types/records.js

@@ -0,0 +1,85 @@
+/**
+ * Kimi Code session records adapter: reads the scoped home's
+ * `session_index.jsonl`, kimi's own append-only index.
+ * @module @khorsheed/dsh-local-agent-kimi/records
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { guardKimiCredential } from './credential-guard.js';
+/** Credentials live under this directory inside the scoped home. */
+const CREDENTIALS_DIR = 'credentials';
+/**
+ * Whether the scoped home holds usable login credentials, guarded by the
+ * credential sentinel: a VALID credential file (both tokens non-empty) reads
+ * true and refreshes the backup; an empty shell (the kimi CLI's failure-path
+ * wipe) restores the backup when one exists and reads false otherwise. The
+ * pre-sentinel "directory non-empty" check could not tell the empty shell
+ * from a real credential at all.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns true when usable credentials are present (after any restore).
+ */
+export async function kimiAuthenticated(homeDir) {
+    return guardKimiCredential(homeDir);
+}
+/**
+ * The newest credential file's modification stamp (epoch ms), undefined when
+ * no credential exists. A completed device-code login rewrites the
+ * credentials directory, so the stamp distinguishes a fresh login from a
+ * leftover (possibly expired) credential.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns the newest credential mtime, or undefined when none exists.
+ */
+export async function kimiCredentialStamp(homeDir) {
+    try {
+        const entries = await readdir(join(homeDir, CREDENTIALS_DIR));
+        let newest;
+        for (const entry of entries) {
+            const { mtimeMs } = await stat(join(homeDir, CREDENTIALS_DIR, entry));
+            if (newest === undefined || mtimeMs > newest)
+                newest = mtimeMs;
+        }
+        return newest;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the scoped home's session index. The index is kimi's own
+ * newline-delimited JSONL; a torn tail line (the file is append-only) is
+ * skipped rather than failing the whole list.
+ * @param homeDir - the `kimi` harness's scoped home.
+ * @returns the parsed records in file order, empty when no index exists yet.
+ */
+export async function listKimiSessions(homeDir) {
+    const indexPath = join(homeDir, 'session_index.jsonl');
+    let text;
+    try {
+        text = await readFile(indexPath, 'utf8');
+    }
+    catch (error) {
+        // No index yet: the scoped home has never run a session. Nothing to list.
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const records = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            records.push({
+                id: parsed.sessionId,
+                workDir: parsed.workDir,
+                ...parsed.title !== undefined && typeof parsed.title === 'string' && { title: parsed.title },
+                ...parsed.createdAt !== undefined && typeof parsed.createdAt === 'string' && { startedAt: Date.parse(parsed.createdAt) },
+            });
+        }
+        catch {
+            // A torn tail line from an in-flight append; skip it and keep the rest.
+        }
+    }
+    return records;
+}

package/lib/types/session-configuration.d.ts

@@ -0,0 +1,5 @@
+import type { LocalAgentResolvedConfiguration } from '@khorsheed/dsh-local-agent/types';
+import { type KimiNativeConfiguration } from './model-catalog.ts';
+/** Confirm model first: its returned options determine which efforts are valid. */
+export declare function configureKimiSession(sessionId: string, initial: KimiNativeConfiguration | undefined, desired: LocalAgentResolvedConfiguration, request: (method: string, params: Record<string, unknown>) => Promise<unknown>): Promise<KimiNativeConfiguration | undefined>;
+//# sourceMappingURL=session-configuration.d.ts.map

package/lib/types/session-configuration.js

@@ -0,0 +1,26 @@
+import { kimiNativeConfiguration } from './model-catalog.js';
+/** Confirm model first: its returned options determine which efforts are valid. */
+export async function configureKimiSession(sessionId, initial, desired, request) {
+    let current = initial;
+    if (desired.model !== undefined && current?.currentModel !== desired.model) {
+        if (current?.modelConfigId === undefined)
+            throw new Error('This Kimi ACP session exposes no verified model selection control');
+        if (!current.directory.entries.some(entry => entry.value === desired.model))
+            throw new Error('The running Kimi session does not advertise this model');
+        current = kimiNativeConfiguration(await request('session/set_config_option', { sessionId, configId: current.modelConfigId, value: desired.model }));
+        if (current?.currentModel !== desired.model)
+            throw new Error('Kimi did not confirm the requested model');
+    }
+    if (desired.effort !== undefined && current?.currentEffort !== desired.effort) {
+        const currentModel = current?.currentModel;
+        const entry = current?.directory.entries.find(entry => entry.value === currentModel);
+        if (current?.effortConfigId === undefined || !entry?.reasoning?.options.some(option => option.value === desired.effort)) {
+            throw new Error('The running Kimi session does not advertise this model/effort combination');
+        }
+        current = kimiNativeConfiguration(await request('session/set_config_option', { sessionId, configId: current.effortConfigId, value: desired.effort }));
+        if (current?.currentEffort !== desired.effort || (desired.model !== undefined && current.currentModel !== desired.model)) {
+            throw new Error('Kimi did not confirm the requested model/effort configuration');
+        }
+    }
+    return current;
+}