pi-chalin 0.1.0

package/src/interview.ts

@@ -0,0 +1,202 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ArtifactStore, InterviewDecisionInput } from "./artifacts.ts";
+
+export interface InterviewChoiceInput {
+  label: string;
+  value?: string;
+  recommended?: boolean;
+}
+
+export interface InterviewQuestionInput {
+  id?: string;
+  question: string;
+  choices: InterviewChoiceInput[];
+  allowCustom?: boolean;
+}
+
+export interface InterviewRequestInput {
+  featureId?: string;
+  task: string;
+  reason: string;
+  questions: InterviewQuestionInput[];
+  batchSize?: number;
+}
+
+export interface InterviewAnswer {
+  questionId: string;
+  question: string;
+  answer: string;
+  choiceLabel?: string;
+  custom: boolean;
+  recommended: boolean;
+}
+
+export interface InterviewResult {
+  featureId: string;
+  task: string;
+  reason: string;
+  status: "answered" | "cancelled" | "non-interactive";
+  answers: InterviewAnswer[];
+  artifactCheckpoint?: string;
+}
+
+const CUSTOM_OPTION = "Custom answer…";
+const SKIP_OPTION = "Skip / not sure";
+
+export async function runChalinInterview(
+  ctx: ExtensionContext,
+  store: ArtifactStore,
+  input: InterviewRequestInput,
+): Promise<InterviewResult> {
+  const featureId = safeFeatureId(input.featureId || input.task || input.reason || "interview");
+  const questions = normalizeQuestions(input.questions, input.batchSize ?? 5);
+  await store.initFeature({ featureId, goal: input.task, chain: ["interview"], currentStep: "Clarify request" });
+
+  if (questions.length === 0) {
+    const result: InterviewResult = { featureId, task: input.task, reason: input.reason, status: "cancelled", answers: [] };
+    await persistInterview(store, result);
+    return result;
+  }
+
+  if (!ctx.hasUI) {
+    const result: InterviewResult = { featureId, task: input.task, reason: input.reason, status: "non-interactive", answers: [] };
+    await persistInterview(store, result);
+    ctx.ui.notify(formatInterviewRequest(input.task, input.reason, questions), "warning");
+    return result;
+  }
+
+  const answers: InterviewAnswer[] = [];
+  for (let index = 0; index < questions.length; index += 1) {
+    const question = questions[index]!;
+    const selected = await ctx.ui.select(formatQuestionTitle(index + 1, questions.length, question.question), questionOptions(question));
+    if (!selected) break;
+    if (selected === SKIP_OPTION) {
+      answers.push({ questionId: question.id ?? `q${index + 1}`, question: question.question, answer: "Not sure", choiceLabel: selected, custom: false, recommended: false });
+      continue;
+    }
+    if (selected === CUSTOM_OPTION) {
+      const custom = await ctx.ui.input(compact(question.question, 72), "Type your answer...");
+      if (!custom?.trim()) continue;
+      answers.push({ questionId: question.id ?? `q${index + 1}`, question: question.question, answer: custom.trim(), custom: true, recommended: false });
+      continue;
+    }
+    const choice = question.choices.find((candidate) => formatChoice(candidate, recommendedChoice(question)) === selected);
+    const answer = choice?.value?.trim() || choice?.label.trim() || selected.replace(/\s*\(RECOMMENDED\)$/, "").trim();
+    answers.push({
+      questionId: question.id ?? `q${index + 1}`,
+      question: question.question,
+      answer,
+      choiceLabel: choice?.label,
+      custom: false,
+      recommended: Boolean(choice?.recommended),
+    });
+  }
+
+  const result: InterviewResult = {
+    featureId,
+    task: input.task,
+    reason: input.reason,
+    status: answers.length === questions.length ? "answered" : "cancelled",
+    answers,
+  };
+  const checkpoint = await persistInterview(store, result);
+  result.artifactCheckpoint = checkpoint.id;
+  return result;
+}
+
+export function formatInterviewResult(result: InterviewResult): string {
+  const lines = [
+    `pi-chalin interview · ${result.status}`,
+    `artifact: ${result.featureId}`,
+    `reason: ${compact(result.reason, 140)}`,
+    result.answers.length ? "answers:" : "answers: none",
+    ...result.answers.map((answer, index) => `${index + 1}. ${compact(answer.question, 90)} → ${compact(answer.answer, 120)}${answer.custom ? " (custom)" : answer.recommended ? " (recommended)" : ""}`),
+    result.status === "answered" ? "next: continue planning or call chalin_route with these answers as context." : "next: ask the user directly before running subagents.",
+  ];
+  return lines.join("\n");
+}
+
+function normalizeQuestions(raw: InterviewQuestionInput[], batchSize: number): InterviewQuestionInput[] {
+  const max = Math.max(1, Math.min(5, Math.floor(batchSize || 5)));
+  return raw
+    .filter((question) => question.question.trim().length > 0)
+    .slice(0, max)
+    .map((question, index) => ({
+      id: question.id?.trim() || `q${index + 1}`,
+      question: compact(question.question, 160),
+      allowCustom: question.allowCustom !== false,
+      choices: normalizeChoices(question.choices),
+    }));
+}
+
+function normalizeChoices(choices: InterviewChoiceInput[]): InterviewChoiceInput[] {
+  const normalized = choices
+    .filter((choice) => choice.label.trim().length > 0)
+    .slice(0, 5)
+    .map((choice) => ({ ...choice, label: compact(choice.label, 72), value: choice.value ? compact(choice.value, 180) : undefined }));
+  if (normalized.some((choice) => choice.recommended)) return normalized;
+  return normalized.map((choice, index) => ({ ...choice, recommended: index === 0 }));
+}
+
+function questionOptions(question: InterviewQuestionInput): string[] {
+  const recommended = recommendedChoice(question);
+  return [
+    ...question.choices.map((choice) => formatChoice(choice, recommended)),
+    ...(question.allowCustom === false ? [] : [CUSTOM_OPTION]),
+    SKIP_OPTION,
+  ];
+}
+
+function recommendedChoice(question: InterviewQuestionInput): InterviewChoiceInput | undefined {
+  return question.choices.find((choice) => choice.recommended) ?? question.choices[0];
+}
+
+function formatChoice(choice: InterviewChoiceInput, recommended: InterviewChoiceInput | undefined): string {
+  const isRecommended = choice === recommended || choice.recommended;
+  return `${choice.label}${isRecommended ? " (RECOMMENDED)" : ""}`;
+}
+
+function formatQuestionTitle(current: number, total: number, question: string): string {
+  return `pi-chalin interview ${current}/${total} · ${compact(question, 70)}`;
+}
+
+function formatInterviewRequest(task: string, reason: string, questions: InterviewQuestionInput[]): string {
+  return [
+    "pi-chalin interview required",
+    `task: ${compact(task, 140)}`,
+    `reason: ${compact(reason, 140)}`,
+    ...questions.map((question, index) => `${index + 1}. ${question.question}\n   ${question.choices.map((choice) => `- ${choice.label}${choice.recommended ? " (recommended)" : ""}`).join("\n   ")}`),
+  ].join("\n");
+}
+
+async function persistInterview(store: ArtifactStore, result: InterviewResult) {
+  const decision: InterviewDecisionInput = {
+    task: result.task,
+    reason: result.reason,
+    answers: result.answers.map((answer) => ({
+      questionId: answer.questionId,
+      question: answer.question,
+      answer: answer.answer,
+      custom: answer.custom,
+      recommended: answer.recommended,
+    })),
+    status: result.status,
+  };
+  await store.appendInterviewDecision(result.featureId, decision);
+  return store.appendCheckpoint(result.featureId, {
+    agent: "interview",
+    title: result.status === "answered" ? "Interview answers captured" : "Interview needs user input",
+    summary: result.answers.length ? result.answers.map((answer) => `${answer.question}: ${answer.answer}`).join("; ") : `No answers captured. ${result.reason}`,
+    status: result.status === "answered" ? "active" : "paused",
+    stage: "interview",
+  });
+}
+
+function safeFeatureId(value: string): string {
+  return compact(value, 80).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "interview";
+}
+
+function compact(text: string, max: number): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return normalized.length <= max ? normalized : `${normalized.slice(0, max - 1)}…`;
+}

package/src/kernel.ts

@@ -0,0 +1,254 @@
+import { AgentCatalog } from "./agents.ts";
+import { ArtifactStore } from "./artifacts.ts";
+import { approvalDecision, type ChalinConfig } from "./config.ts";
+import { MemoryStore } from "./memory.ts";
+import { MockWorkerRunner, SdkWorkerRunner, type WorkerRunner, type WorkerRunnerContext } from "./runner.ts";
+import type { AgentDefinition, AgentStage, AgentStep, AgentThinkingLevel, ApprovalDecision, MemoryRecord, RouteDecision, RoutePlan, RunState } from "./schemas.ts";
+
+export interface ChalinKernelOptions {
+  cwd?: string;
+  config?: ChalinConfig;
+  catalog?: AgentCatalog;
+  memory?: MemoryStore;
+  artifacts?: ArtifactStore;
+  runner?: WorkerRunner;
+  sdkRunner?: WorkerRunner;
+  modelOverrides?: Record<string, string>;
+  thinkingOverrides?: Record<string, AgentThinkingLevel>;
+}
+
+export interface ChalinHandleResult {
+  route: RouteDecision;
+  approval: ApprovalDecision;
+  run?: RunState;
+  memories: MemoryRecord[];
+  diagnostics: string[];
+}
+
+export class ChalinKernel {
+  private readonly cwd: string;
+  private readonly config: ChalinConfig;
+  private readonly catalog: AgentCatalog;
+  private readonly memory: MemoryStore;
+  private readonly artifacts: ArtifactStore;
+  private readonly runner: WorkerRunner;
+  private readonly sdkRunner: WorkerRunner;
+  private readonly modelOverrides: Record<string, string>;
+  private readonly thinkingOverrides: Record<string, AgentThinkingLevel>;
+
+  constructor(options?: ChalinKernelOptions) {
+    this.cwd = options?.cwd ?? process.cwd();
+    this.config = options?.config ?? {
+      enabled: true,
+      autonomy: "balanced",
+      safety: { approvalRiskThreshold: "medium", recursionGuard: true, singleWriterGuard: true, mutationExpectationGuard: true, blockCritical: true },
+      agents: { modelOverrides: {}, thinkingOverrides: {}, modelPersistenceDefaults: { "built-in": "user", user: "user", project: "project" } },
+    };
+    this.catalog = options?.catalog ?? AgentCatalog.load({ cwd: this.cwd });
+    this.memory = options?.memory ?? new MemoryStore({ cwd: this.cwd });
+    this.artifacts = options?.artifacts ?? new ArtifactStore({ cwd: this.cwd });
+    this.runner = options?.runner ?? new MockWorkerRunner();
+    this.sdkRunner = options?.sdkRunner ?? new SdkWorkerRunner();
+    this.modelOverrides = options?.modelOverrides ?? this.config.agents.modelOverrides;
+    this.thinkingOverrides = options?.thinkingOverrides ?? this.config.agents.thinkingOverrides;
+  }
+
+  /**
+   * pi-chalin is LLM-routed: the primary Pi agent decides whether to call the
+   * chalin_route tool and provides the topology/steps. This method remains as a
+   * safe legacy preview path, but it intentionally does not infer workflows from
+   * hard-coded prompt keywords.
+   */
+  classify(prompt: string): RouteDecision {
+    const text = prompt.trim();
+    if (!text) return askUser("Prompt is empty.");
+    return {
+      kind: "bypass",
+      agents: [],
+      risk: "low",
+      ambiguity: "low",
+      needsMemory: false,
+      needsArtifacts: false,
+      reason: "pi-chalin uses LLM-first routing: the primary Pi agent decides when to call chalin_route and which agents/topology to use.",
+    };
+  }
+
+  classifyPlaceholder(prompt: string): RouteDecision {
+    return this.classify(prompt);
+  }
+
+  async handlePrompt(prompt: string, context: Omit<WorkerRunnerContext, "agents" | "modelOverrides"> = { cwd: this.cwd }): Promise<ChalinHandleResult> {
+    return this.handleRoute(this.classify(prompt), prompt, context);
+  }
+
+  async handleRoute(route: RouteDecision, prompt: string, context: Omit<WorkerRunnerContext, "agents" | "modelOverrides"> = { cwd: this.cwd }, approvalOverride?: ApprovalDecision): Promise<ChalinHandleResult> {
+    const approval = approvalOverride ?? approvalDecision(this.config, route);
+    const diagnostics = [...this.catalog.diagnostics.warnings, ...this.catalog.diagnostics.errors];
+    const memories = route.needsMemory ? (await this.memory.retrieve({ query: prompt, sourceAgent: "primary-pi", limit: 5, tokenBudget: 900 })).results.map((result) => result.record) : [];
+    if (approval.action !== "allow" || !route.plan) return { route, approval, memories, diagnostics };
+
+    const agents = this.resolvePlanAgents(route);
+    const missing = route.agents.filter((ref) => !agents.has(ref));
+    if (missing.length > 0) {
+      return {
+        route,
+        approval: { action: "block", reason: `Unknown pi-chalin agent(s): ${missing.join(", ")}.` },
+        memories,
+        diagnostics: [...diagnostics, `Unknown pi-chalin agent(s): ${missing.join(", ")}.`],
+      };
+    }
+
+    const runner = context.extensionContext ? this.sdkRunner : this.runner;
+    const run = await runner.run(route, { ...context, cwd: this.cwd, agents, modelOverrides: this.modelOverrides, thinkingOverrides: this.thinkingOverrides });
+    const candidates = run.steps.flatMap((step) => step.output?.memoryCandidates ?? []);
+    if (candidates.length > 0) {
+      if (context.extensionContext) {
+        this.persistMemoriesAfterToolResult(candidates, run.id, context.extensionContext.hasUI);
+      } else {
+        await this.memory.submitCandidates(candidates);
+      }
+    }
+    if (route.needsArtifacts || run.steps.length > 1) await this.artifacts.recordRun(run);
+    return { route, approval, run, memories, diagnostics };
+  }
+
+  async resumeRun(run: RunState, context: Omit<WorkerRunnerContext, "agents" | "modelOverrides" | "thinkingOverrides"> = { cwd: this.cwd }): Promise<ChalinHandleResult> {
+    const approval = approvalDecision(this.config, run.route);
+    const diagnostics = [...this.catalog.diagnostics.warnings, ...this.catalog.diagnostics.errors];
+    if (approval.action !== "allow" || !run.route.plan) return { route: run.route, approval, memories: [], diagnostics, run };
+    const agents = this.resolvePlanAgents(run.route);
+    const runner = context.extensionContext ? this.sdkRunner : this.runner;
+    const resumed = runner.resume
+      ? await runner.resume(run, { ...context, cwd: this.cwd, agents, modelOverrides: this.modelOverrides, thinkingOverrides: this.thinkingOverrides })
+      : await runner.run(run.route, { ...context, cwd: this.cwd, agents, modelOverrides: this.modelOverrides, thinkingOverrides: this.thinkingOverrides });
+    const candidates = resumed.steps.flatMap((step) => step.output?.memoryCandidates ?? []);
+    if (candidates.length > 0) {
+      if (context.extensionContext) this.persistMemoriesAfterToolResult(candidates, resumed.id, context.extensionContext.hasUI);
+      else await this.memory.submitCandidates(candidates);
+    }
+    await this.artifacts.recordRun(resumed);
+    return { route: resumed.route, approval, run: resumed, memories: [], diagnostics };
+  }
+
+  async approvalFor(route: RouteDecision): Promise<ApprovalDecision> {
+    return approvalDecision(this.config, route);
+  }
+
+  resolvePlanAgents(route: RouteDecision): Map<string, AgentDefinition> {
+    const result = new Map<string, AgentDefinition>();
+    for (const ref of route.agents) {
+      const resolved = this.catalog.resolve(ref);
+      if (resolved.agent) result.set(resolved.agent.name, resolved.agent);
+    }
+    const conflictResolver = this.catalog.resolve("conflict-resolver").agent;
+    if (conflictResolver) result.set(conflictResolver.name, conflictResolver);
+    return result;
+  }
+
+  private persistMemoriesAfterToolResult(candidates: NonNullable<RunState["steps"][number]["output"]>["memoryCandidates"], runId: string, hasUI: boolean): void {
+    const configuredDelay = Number(process.env.PI_CHALIN_MEMORY_PERSIST_DELAY_MS);
+    const delayMs = Number.isFinite(configuredDelay) && configuredDelay >= 0 ? configuredDelay : hasUI ? 0 : 30_000;
+    const timer = setTimeout(() => {
+      void this.memory.submitCandidates(candidates).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`pi-chalin memory persistence failed after run ${runId}: ${message}`);
+      });
+    }, delayMs);
+    timer.unref?.();
+  }
+}
+
+function askUser(reason: string): RouteDecision {
+  return { kind: "ask-user", agents: [], risk: "low", ambiguity: "high", needsMemory: false, needsArtifacts: false, reason };
+}
+
+export function routeFromPlan(input: {
+  topology: "single" | "chain" | "parallel" | "dag" | "memory-only";
+  steps?: AgentStep[];
+  stages?: Array<{ id?: string; name?: string; tasks: AgentStep[] }>;
+  risk?: RouteDecision["risk"];
+  needsMemory?: boolean;
+  needsArtifacts?: boolean;
+  reason?: string;
+}): RouteDecision {
+  const steps = sanitizeSteps(input.steps ?? []);
+  if (input.topology === "memory-only") {
+    return {
+      kind: "memory-only",
+      agents: [],
+      risk: input.risk ?? "low",
+      ambiguity: "low",
+      needsMemory: true,
+      needsArtifacts: false,
+      reason: input.reason?.trim() || "Primary Pi agent requested pi-chalin memory lookup.",
+    };
+  }
+  if (input.topology === "dag") {
+    const stages = sanitizeStages(input.stages ?? []);
+    if (stages.length === 0) return askUser("chalin_route dag topology requires at least one stage with agent tasks.");
+    const agents = stages.flatMap((stage) => stage.tasks.map((step) => step.agent));
+    const allSteps = stages.flatMap((stage) => stage.tasks);
+    return {
+      kind: "multi-agent-dag",
+      agents,
+      risk: input.risk ?? riskFromPlan(allSteps),
+      ambiguity: "low",
+      needsMemory: Boolean(input.needsMemory),
+      needsArtifacts: input.needsArtifacts ?? allSteps.some((step) => ["scout", "planner", "worker", "reviewer", "context-builder"].includes(step.agent)),
+      reason: input.reason?.trim() || "Primary Pi agent selected a staged DAG workflow dynamically.",
+      plan: { kind: "dag", stages },
+    };
+  }
+  if (steps.length === 0) return askUser("chalin_route requires at least one agent step unless topology is memory-only.");
+
+  const agents = steps.map((step) => step.agent);
+  const plan = planFromTopology(input.topology, steps);
+  return {
+    kind: kindFromTopology(input.topology, steps.length),
+    agents,
+    risk: input.risk ?? riskFromPlan(steps),
+    ambiguity: "low",
+    needsMemory: Boolean(input.needsMemory),
+    needsArtifacts: input.needsArtifacts ?? steps.some((step) => ["scout", "planner", "worker", "reviewer", "context-builder"].includes(step.agent)),
+    reason: input.reason?.trim() || "Primary Pi agent selected this chalin workflow dynamically.",
+    plan,
+  };
+}
+
+function sanitizeSteps(steps: AgentStep[]): AgentStep[] {
+  return steps
+    .map((step) => ({ id: step.id?.trim(), agent: step.agent.trim(), task: step.task.trim(), budget: sanitizeBudget(step.budget) }))
+    .filter((step) => step.agent.length > 0 && step.task.length > 0)
+    .slice(0, 6);
+}
+
+function sanitizeStages(stages: Array<{ id?: string; name?: string; tasks: AgentStep[] }>): AgentStage[] {
+  return stages
+    .map((stage, index) => ({
+      id: (stage.id ?? stage.name ?? `stage-${index + 1}`).trim() || `stage-${index + 1}`,
+      tasks: sanitizeSteps(stage.tasks).slice(0, 10),
+    }))
+    .filter((stage) => stage.tasks.length > 0)
+    .slice(0, 8);
+}
+
+function kindFromTopology(topology: "single" | "chain" | "parallel", stepCount: number): RouteDecision["kind"] {
+  if (topology === "parallel") return "multi-agent-parallel";
+  if (topology === "chain" || stepCount > 1) return "multi-agent-chain";
+  return "single-agent";
+}
+
+function planFromTopology(topology: "single" | "chain" | "parallel", steps: AgentStep[]): RoutePlan {
+  if (topology === "parallel") return { kind: "parallel", tasks: steps };
+  if (topology === "chain" || steps.length > 1) return { kind: "chain", steps };
+  return { kind: "single", agent: steps[0]!.agent, task: steps[0]!.task, budget: steps[0]!.budget };
+}
+
+function sanitizeBudget(value: AgentStep["budget"]): AgentStep["budget"] | undefined {
+  return value === "tight" || value === "normal" || value === "deep" || value === "extended" ? value : undefined;
+}
+
+function riskFromPlan(steps: Array<{ agent: string }>): RouteDecision["risk"] {
+  if (steps.some((step) => step.agent === "worker")) return "medium";
+  return "low";
+}