@meowlynxsea/koi 0.1.0

package/src/agent/tool-orchestration.ts

@@ -0,0 +1,55 @@
+/**
+ * Tool Orchestration — 工具调度器
+ *
+ * Manages execution ordering: read-only tools run concurrently,
+ * write tools are serialized via an internal mutex.
+ *
+ * All Koi custom tools register with executionMode: "parallel" to avoid
+ * Pi's all-sequential fallback, then write tools self-coordinate here.
+ */
+
+import { isReadOnlyTool } from "../tools/types.js";
+
+/** 写入工具互斥锁 — Promise 链实现串行队列 */
+export class WriteToolMutex {
+  private queue: Promise<void> = Promise.resolve();
+
+  async acquire(): Promise<() => void> {
+    let release: (() => void) | undefined;
+    const promise = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const previous = this.queue;
+    this.queue = this.queue.then(() => promise);
+    await previous;
+    return release!;
+  }
+}
+
+export const globalWriteMutex = new WriteToolMutex();
+
+/** 分类工具调用为只读 / 写入两组 */
+export function classifyToolCalls<T extends { name: string }>(
+  calls: T[]
+): { readonly: T[]; write: T[] } {
+  const readonly: T[] = [];
+  const write: T[] = [];
+  for (const call of calls) {
+    if (isReadOnlyTool(call.name)) {
+      readonly.push(call);
+    } else {
+      write.push(call);
+    }
+  }
+  return { readonly, write };
+}
+
+/** 在 execute() 内部包装写入工具，确保串行 */
+export async function withWriteLock<T>(fn: () => Promise<T>): Promise<T> {
+  const release = await globalWriteMutex.acquire();
+  try {
+    return await fn();
+  } finally {
+    release();
+  }
+}

package/src/agent/tools.ts

@@ -0,0 +1,8 @@
+/**
+ * Custom Tool Registry
+ *
+ * Pi coding tools are loaded automatically via createAgentSession.
+ * Custom koi-specific tools can be registered here in the future.
+ */
+
+export {};

package/src/cli/args.ts

@@ -0,0 +1,6 @@
+/**
+ * CLI Argument Parser
+ *
+ * Uses commander (or custom parser) to define flags, options,
+ * and sub-commands for the koi binary.
+ */

package/src/cli/commands.ts

@@ -0,0 +1,5 @@
+/**
+ * CLI Commands Registry
+ *
+ * Defines all sub-commands (e.g. `koi chat`, `koi config`, `koi export`).
+ */

package/src/commands/skills/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Skills Command Entry Point
+ *
+ * Registers the /skills command for the command palette.
+ */
+
+import type { Command } from "../../types/commands.js";
+
+const skillsCommand: Command = {
+  id: "skills",
+  name: "Skills",
+  description: "List and manage available skills",
+  keywords: ["skill", "skills", "commands", "slash"],
+  action: async (context) => {
+    // This will be handled by the app's command panel
+    if (context.onOpenSkillsModal) {
+      context.onOpenSkillsModal();
+    }
+    return { success: true };
+  },
+};
+
+export default skillsCommand;

package/src/config/models.ts

@@ -0,0 +1,6 @@
+/**
+ * Model Registry
+ *
+ * Wraps Pi's ModelRegistry with custom model aliases, fallback chains,
+ * and provider-specific authentication.
+ */

package/src/config/settings.ts

@@ -0,0 +1,392 @@
+/**
+ * Settings / Configuration Manager
+ *
+ * Persists user preferences and bridges to Pi infrastructure:
+ * - Koi settings: session title, current model reference, provider configs
+ * - Pi AuthStorage: credential storage for agent session
+ * - Pi ModelRegistry: model discovery and API key resolution
+ * - Pi SettingsManager: compaction, retry, and runtime settings
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import {
+  getProviders,
+  getModels,
+  completeSimple,
+  type KnownProvider,
+  type Model,
+  type Api,
+} from "@mariozechner/pi-ai";
+import { getErrorMessage } from "../tools/types.js";
+import { getOAuthProvider } from "@mariozechner/pi-ai/oauth";
+import {
+  AuthStorage,
+  ModelRegistry,
+  SettingsManager,
+} from "@mariozechner/pi-coding-agent";
+
+export interface ModelRef {
+  provider: string;
+  modelId: string;
+}
+
+export type AuthMethod = "apikey" | "oauth";
+
+export interface ProviderConfig {
+  provider: string;
+  authMethod: AuthMethod;
+  credential: string; // api key or oauth token
+}
+
+interface SettingsFile {
+  version: number;
+  sessionTitle: string;
+  providers: Record<string, ProviderConfig>;
+  currentModel: ModelRef | null;
+  auxiliaryModel?: ModelRef | null;
+}
+
+const CONFIG_DIR = path.join(os.homedir(), ".config", "koi");
+const SETTINGS_PATH = path.join(CONFIG_DIR, "settings.json");
+const PI_AGENT_DIR = path.join(CONFIG_DIR, "pi");
+
+let sessionTitle = "New Session";
+let providerConfigs = new Map<string, ProviderConfig>();
+let currentModel: ModelRef | null = null;
+let auxiliaryModel: ModelRef | null = null;
+
+// Pi infrastructure (lazy-initialized)
+let piAuthStorage: AuthStorage | null = null;
+let piModelRegistry: ModelRegistry | null = null;
+let piSettingsManager: SettingsManager | null = null;
+
+function ensureConfigDir(): void {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+  if (!fs.existsSync(PI_AGENT_DIR)) {
+    fs.mkdirSync(PI_AGENT_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+function initPiInfrastructure(): void {
+  if (piAuthStorage && piModelRegistry && piSettingsManager) return;
+  ensureConfigDir();
+  piAuthStorage = AuthStorage.create(path.join(PI_AGENT_DIR, "auth.json"));
+  piModelRegistry = ModelRegistry.create(
+    piAuthStorage,
+    path.join(PI_AGENT_DIR, "models.json")
+  );
+  piSettingsManager = SettingsManager.create(process.cwd(), PI_AGENT_DIR);
+}
+
+function syncCredentialsToPi(): void {
+  if (!piAuthStorage) return;
+  for (const [provider, config] of providerConfigs) {
+    if (config.authMethod === "apikey") {
+      piAuthStorage.set(provider, { type: "api_key", key: config.credential });
+    } else if (config.authMethod === "oauth") {
+      // OAuth tokens from koi settings lack refresh token; store as api_key
+      // so ModelRegistry can resolve them without OAuth refresh flow.
+      piAuthStorage.set(provider, { type: "api_key", key: config.credential });
+    }
+  }
+}
+
+/* ───────── Pi infrastructure accessors ───────── */
+
+export function getPiAuthStorage(): AuthStorage {
+  initPiInfrastructure();
+  return piAuthStorage!;
+}
+
+export function getPiModelRegistry(): ModelRegistry {
+  initPiInfrastructure();
+  piModelRegistry!.refresh();
+  return piModelRegistry!;
+}
+
+export function getPiSettingsManager(): SettingsManager {
+  initPiInfrastructure();
+  return piSettingsManager!;
+}
+
+/* ───────── Pi model resolution ───────── */
+
+export function getCurrentPiModel(): Model<Api> | undefined {
+  const ref = getCurrentModel();
+  if (!ref) return undefined;
+  return getPiModelRegistry().find(ref.provider, ref.modelId);
+}
+
+export function getAvailablePiModels(): Model<Api>[] {
+  return getPiModelRegistry().getAvailable();
+}
+
+export function resolvePiModel(ref: ModelRef): Model<Api> | undefined {
+  return getPiModelRegistry().find(ref.provider, ref.modelId);
+}
+
+/* ───────── Pi SettingsManager proxies ───────── */
+
+export function getCompactionSettings() {
+  return getPiSettingsManager().getCompactionSettings();
+}
+
+export function setCompactionEnabled(enabled: boolean) {
+  getPiSettingsManager().setCompactionEnabled(enabled);
+}
+
+export function getRetrySettings() {
+  return getPiSettingsManager().getRetrySettings();
+}
+
+export function setRetryEnabled(enabled: boolean) {
+  getPiSettingsManager().setRetryEnabled(enabled);
+}
+
+/* ───────── Koi settings I/O ───────── */
+
+export function saveSettings(): void {
+  try {
+    ensureConfigDir();
+    const data: SettingsFile = {
+      version: 1,
+      sessionTitle,
+      providers: Object.fromEntries(providerConfigs),
+      currentModel,
+      auxiliaryModel,
+    };
+    const json = JSON.stringify(data, null, 2);
+    fs.writeFileSync(SETTINGS_PATH, json + "\n", { mode: 0o600 });
+    fs.chmodSync(SETTINGS_PATH, 0o600);
+  } catch {
+    // Silently ignore write errors so the TUI never crashes on save.
+  }
+}
+
+export function loadSettings(): void {
+  initPiInfrastructure();
+
+  try {
+    if (!fs.existsSync(SETTINGS_PATH)) {
+      return;
+    }
+    const raw = fs.readFileSync(SETTINGS_PATH, "utf-8");
+    const data = JSON.parse(raw) as SettingsFile;
+
+    if (data.sessionTitle) {
+      sessionTitle = data.sessionTitle;
+    }
+    if (data.providers) {
+      providerConfigs = new Map(Object.entries(data.providers));
+    }
+    if (data.currentModel) {
+      currentModel = data.currentModel;
+    }
+    if (data.auxiliaryModel) {
+      auxiliaryModel = data.auxiliaryModel;
+    }
+    syncCredentialsToPi();
+  } catch {
+    // If the file is missing, corrupt, or unreadable, start fresh.
+  }
+}
+
+/* ───────── Session title ───────── */
+
+export function getSessionTitle(): string {
+  return sessionTitle;
+}
+
+export function setSessionTitle(title: string): void {
+  sessionTitle = title;
+  saveSettings();
+}
+
+/* ───────── Provider configuration ───────── */
+
+export function configureProvider(config: ProviderConfig): void {
+  providerConfigs.set(config.provider, config);
+  saveSettings();
+  // Sync to Pi AuthStorage so agent sessions can resolve API keys
+  if (config.authMethod === "apikey") {
+    getPiAuthStorage().set(config.provider, {
+      type: "api_key",
+      key: config.credential,
+    });
+  } else {
+    getPiAuthStorage().set(config.provider, {
+      type: "api_key",
+      key: config.credential,
+    });
+  }
+}
+
+export function removeProvider(provider: string): void {
+  providerConfigs.delete(provider);
+  saveSettings();
+  getPiAuthStorage().remove(provider);
+}
+
+export function isProviderConfigured(provider: string): boolean {
+  return providerConfigs.has(provider);
+}
+
+export function getProviderConfig(
+  provider: string
+): ProviderConfig | undefined {
+  return providerConfigs.get(provider);
+}
+
+export function getConfiguredProviders(): string[] {
+  return Array.from(providerConfigs.keys());
+}
+
+/* ───────── Current model (koi reference) ───────── */
+
+export function getCurrentModel(): ModelRef | null {
+  return currentModel;
+}
+
+export function setCurrentModel(ref: ModelRef | null): void {
+  currentModel = ref;
+  saveSettings();
+}
+
+export function getAuxiliaryModel(): ModelRef | null {
+  return auxiliaryModel;
+}
+
+export function setAuxiliaryModel(ref: ModelRef | null): void {
+  auxiliaryModel = ref;
+  saveSettings();
+}
+
+/* ───────── Model discovery (via pi-ai, for modals) ───────── */
+
+export function getAllProviders(): string[] {
+  return getProviders();
+}
+
+export function getProviderModels(provider: string): Model<Api>[] {
+  return getModels(provider as KnownProvider);
+}
+
+/* ───────── Credential validation ───────── */
+
+export async function validateProviderCredential(
+  provider: string,
+  credential: string
+): Promise<{ valid: boolean; error?: string }> {
+  try {
+    const models = getModels(provider as KnownProvider);
+    if (!models || models.length === 0) {
+      return { valid: false, error: "No models available for this provider" };
+    }
+
+    let model: Model<Api> = models[0]!;
+    let apiKey = credential;
+
+    const oauthProvider = getOAuthProvider(provider);
+    if (oauthProvider) {
+      const fakeCreds = {
+        access: credential,
+        refresh: credential,
+        expires: Date.now() + 86400000,
+      };
+      apiKey = oauthProvider.getApiKey(fakeCreds);
+      if (oauthProvider.modifyModels) {
+        const modified = oauthProvider.modifyModels(models, fakeCreds);
+        if (modified.length > 0) {
+          model = modified[0]!;
+        }
+      }
+    }
+
+    const message = await completeSimple(
+      model,
+      {
+        messages: [{ role: "user", content: "Hi", timestamp: Date.now() }],
+      },
+      {
+        apiKey,
+        maxTokens: 1,
+        maxRetries: 0,
+        timeoutMs: 15000,
+      }
+    );
+
+    if (message.stopReason === "error" || message.stopReason === "aborted") {
+      return {
+        valid: false,
+        error: message.errorMessage || "API request failed",
+      };
+    }
+
+    return { valid: true };
+  } catch (err: unknown) {
+    return { valid: false, error: getErrorMessage(err) };
+  }
+}
+
+/* ───────── Auxiliary model call ───────── */
+
+/**
+ * Call the auxiliary model with a system prompt and user messages.
+ * Returns the model's text response or null if the model is not configured or call fails.
+ */
+export async function callAuxiliaryModel(
+  systemPrompt: string,
+  userMessages: Array<{ role: "user"; content: string; timestamp: number }>
+): Promise<string | null> {
+  const ref = getAuxiliaryModel();
+  if (!ref) {
+    return null;
+  }
+
+  const model = resolvePiModel(ref);
+  if (!model) {
+    return null;
+  }
+
+  const registry = getPiModelRegistry();
+  const auth = await registry.getApiKeyAndHeaders(model);
+  if (!auth.ok) {
+    return null;
+  }
+
+  try {
+    const result = await completeSimple(
+      model,
+      {
+        systemPrompt,
+        messages: userMessages,
+      },
+      {
+        apiKey: auth.apiKey,
+        headers: auth.headers,
+        maxTokens: 1024,
+        maxRetries: 1,
+        timeoutMs: 30000,
+      }
+    );
+
+    fs.appendFileSync("/tmp/koi-debug.log", `[callAuxiliaryModel] result.stopReason: ${result.stopReason}, content: ${JSON.stringify(result.content)}\n`);
+
+    if (result.stopReason === "error" || result.stopReason === "aborted") {
+      return null;
+    }
+
+    const text = result.content
+      .filter((block): block is { type: "text"; text: string } => block.type === "text")
+      .map((block) => block.text)
+      .join("");
+    fs.appendFileSync("/tmp/koi-debug.log", `[callAuxiliaryModel] joined text: "${text}"\n`);
+    return text;
+  } catch {
+    return null;
+  }
+}

package/src/main.tsx

@@ -0,0 +1,64 @@
+/**
+ * Koi - Main Entry Point
+ *
+ * Bootstraps the OpenTUI React application.
+ */
+
+import { createCliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { DialogProvider } from "@opentui-ui/dialog/react";
+import { App } from "./tui/app.js";
+import { loadSettings } from "./config/settings.js";
+
+export async function main(): Promise<void> {
+  loadSettings();
+  const renderer = await createCliRenderer({ exitOnCtrlC: false });
+  createRoot(renderer).render(
+    <DialogProvider>
+      <App
+        onExit={() => {
+          renderer.destroy();
+          process.exit(0);
+        }}
+      />
+    </DialogProvider>
+  );
+
+  // Ensure terminal state is restored on unexpected exits
+  const cleanup = () => {
+    try {
+      renderer.destroy();
+    } catch {
+      // ignore cleanup errors during shutdown
+    }
+  };
+  process.on("exit", cleanup);
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("uncaughtException", (err) => {
+    cleanup();
+    console.error(err);
+    process.exit(1);
+  });
+  process.on("unhandledRejection", (reason) => {
+    cleanup();
+    console.error("Unhandled rejection:", reason);
+    process.exit(1);
+  });
+
+  // Keep process alive until exit
+  await new Promise(() => {});
+}
+
+if (import.meta.main) {
+  main().catch((err: unknown) => {
+    console.error(err);
+    process.exit(1);
+  });
+}