pi-chalin 0.1.0

package/src/runtime-state.ts

@@ -0,0 +1,175 @@
+import type { RouteDecision, RunState } from "./schemas.ts";
+
+let lastRun: RunState | undefined;
+const liveStepSessions = new Map<string, LiveStepSessionRef>();
+let routeInvocations: ChalinRouteInvocation[] = [];
+let directCompletion: DirectCompletionState = freshDirectCompletionState();
+
+export type ChalinRouteOutcome = "dry-run" | "ask" | "block" | "failed" | "paused" | "complete";
+
+interface ChalinRouteInvocation {
+  id: number;
+  dryRun: boolean;
+  route?: Pick<RouteDecision, "kind" | "agents" | "risk">;
+  outcome?: ChalinRouteOutcome;
+}
+
+interface DirectCompletionState {
+  prompt: string;
+  mutationObserved: boolean;
+  testMutationObserved: boolean;
+  verificationObserved: boolean;
+  verificationCommand?: string;
+  progressNudgeSent: boolean;
+  readyToVerifyNudgeSent: boolean;
+  failedVerificationNudgeSent: boolean;
+  missingTestNudgeSent: boolean;
+  nudgeSent: boolean;
+}
+
+export interface LiveStepSessionRef {
+  runId: string;
+  stepId: string;
+  agent: string;
+  cwd: string;
+  startedAt: string;
+  getMessages(): readonly unknown[];
+}
+
+export function setLatestRun(run: RunState | undefined): void {
+  lastRun = run;
+}
+
+export function getLatestRun(): RunState | undefined {
+  return lastRun;
+}
+
+export function getActiveRun(): RunState | undefined {
+  return lastRun?.status === "running" ? lastRun : undefined;
+}
+
+export function setLiveStepSession(ref: LiveStepSessionRef): void {
+  liveStepSessions.set(liveStepKey(ref.runId, ref.stepId), ref);
+}
+
+export function getLiveStepSession(runId: string, stepId: string): LiveStepSessionRef | undefined {
+  return liveStepSessions.get(liveStepKey(runId, stepId));
+}
+
+export function clearLiveStepSession(runId: string, stepId: string, ref?: LiveStepSessionRef): void {
+  const key = liveStepKey(runId, stepId);
+  if (ref && liveStepSessions.get(key) !== ref) return;
+  liveStepSessions.delete(key);
+}
+
+export function beginChalinTurn(options: { prompt?: string } = {}): void {
+  routeInvocations = [];
+  directCompletion = freshDirectCompletionState();
+  directCompletion.prompt = options.prompt ?? "";
+}
+
+export function recordDirectToolCompletion(options: { toolName: string; isError?: boolean; command?: string; argsText?: string }): { shouldProgressNudge: boolean; shouldReadyToVerifyNudge: boolean; shouldFailureNudge: boolean; shouldMissingTestNudge: boolean; shouldCompletionNudge: boolean; verificationCommand?: string } {
+  let shouldProgressNudge = false;
+  if (options.toolName === "edit" || options.toolName === "write") {
+    if (options.isError) return { shouldProgressNudge: false, shouldReadyToVerifyNudge: false, shouldFailureNudge: false, shouldMissingTestNudge: false, shouldCompletionNudge: false };
+    directCompletion.mutationObserved = true;
+    if (directCompletion.verificationObserved || directCompletion.verificationCommand || directCompletion.failedVerificationNudgeSent || directCompletion.nudgeSent) {
+      directCompletion.verificationObserved = false;
+      directCompletion.verificationCommand = undefined;
+      directCompletion.readyToVerifyNudgeSent = false;
+      directCompletion.failedVerificationNudgeSent = false;
+      directCompletion.missingTestNudgeSent = false;
+      directCompletion.nudgeSent = false;
+    }
+    if (isTestMutation(options.argsText)) directCompletion.testMutationObserved = true;
+    shouldProgressNudge = !directCompletion.progressNudgeSent;
+    if (shouldProgressNudge) directCompletion.progressNudgeSent = true;
+  }
+  let shouldFailureNudge = false;
+  if (options.toolName === "bash" && directCompletion.mutationObserved && isVerificationCommand(options.command)) {
+    directCompletion.verificationCommand = options.command?.trim();
+    if (options.isError) {
+      shouldFailureNudge = !directCompletion.failedVerificationNudgeSent;
+      if (shouldFailureNudge) directCompletion.failedVerificationNudgeSent = true;
+    } else {
+      directCompletion.verificationObserved = true;
+    }
+  } else if (options.isError) {
+    return { shouldProgressNudge, shouldReadyToVerifyNudge: false, shouldFailureNudge: false, shouldMissingTestNudge: false, shouldCompletionNudge: false, verificationCommand: directCompletion.verificationCommand };
+  }
+  const shouldReadyToVerifyNudge = directCompletion.mutationObserved
+    && !directCompletion.verificationObserved
+    && !directCompletion.readyToVerifyNudgeSent
+    && (!taskRequiresTests(directCompletion.prompt) || directCompletion.testMutationObserved);
+  if (shouldReadyToVerifyNudge) directCompletion.readyToVerifyNudgeSent = true;
+  const shouldMissingTestNudge = directCompletion.mutationObserved
+    && directCompletion.verificationObserved
+    && taskRequiresTests(directCompletion.prompt)
+    && !directCompletion.testMutationObserved
+    && !directCompletion.missingTestNudgeSent;
+  if (shouldMissingTestNudge) directCompletion.missingTestNudgeSent = true;
+  const shouldCompletionNudge = directCompletion.mutationObserved
+    && directCompletion.verificationObserved
+    && !shouldMissingTestNudge
+    && !(taskRequiresTests(directCompletion.prompt) && !directCompletion.testMutationObserved)
+    && !directCompletion.nudgeSent;
+  if (shouldCompletionNudge) directCompletion.nudgeSent = true;
+  return { shouldProgressNudge, shouldReadyToVerifyNudge, shouldFailureNudge, shouldMissingTestNudge, shouldCompletionNudge, verificationCommand: directCompletion.verificationCommand };
+}
+
+export function beginChalinRouteInvocation(options: { dryRun: boolean; route: RouteDecision }): { allowed: boolean; reason?: string; invocationId?: number } {
+  const committed = routeInvocations.find((call) => call.outcome === "complete" || call.outcome === "paused");
+  if (!options.dryRun && committed) {
+    return {
+      allowed: false,
+      reason: "chalin_route already executed for this user prompt. Synthesize the existing result instead of launching another chalin workflow. A second call is allowed only after dryRun, ask, block, or failed outcomes.",
+    };
+  }
+
+  const invocation: ChalinRouteInvocation = {
+    id: routeInvocations.length + 1,
+    dryRun: options.dryRun,
+    route: { kind: options.route.kind, agents: options.route.agents, risk: options.route.risk },
+  };
+  routeInvocations.push(invocation);
+  return { allowed: true, invocationId: invocation.id };
+}
+
+export function finishChalinRouteInvocation(invocationId: number | undefined, outcome: ChalinRouteOutcome): void {
+  if (invocationId === undefined) return;
+  const invocation = routeInvocations.find((call) => call.id === invocationId);
+  if (invocation) invocation.outcome = outcome;
+}
+
+export function getChalinRouteInvocations(): readonly ChalinRouteInvocation[] {
+  return routeInvocations;
+}
+
+export function resetRuntimeState(): void {
+  lastRun = undefined;
+  liveStepSessions.clear();
+  routeInvocations = [];
+  directCompletion = freshDirectCompletionState();
+}
+
+function liveStepKey(runId: string, stepId: string): string {
+  return `${runId}:${stepId}`;
+}
+
+function freshDirectCompletionState(): DirectCompletionState {
+  return { prompt: "", mutationObserved: false, testMutationObserved: false, verificationObserved: false, verificationCommand: undefined, progressNudgeSent: false, readyToVerifyNudgeSent: false, failedVerificationNudgeSent: false, missingTestNudgeSent: false, nudgeSent: false };
+}
+
+function isVerificationCommand(command: string | undefined): boolean {
+  if (!command) return false;
+  return /\b(npm|pnpm|yarn|bun)\s+(test|run\s+(test|typecheck|lint|check)|exec\s+(vitest|jest|tsc|eslint))\b/i.test(command)
+    || /\b(node\s+.*--test|python3?\s+-m\s+unittest(?:\s+discover)?|go\s+test|cargo\s+test|pytest|vitest|jest|tsc\s+--noEmit|eslint)\b/i.test(command);
+}
+
+function taskRequiresTests(prompt: string): boolean {
+  return /\b(test|tests|prueba|pruebas|spec|specs|coverage|cobertura)\b/i.test(prompt);
+}
+
+function isTestMutation(argsText: string | undefined): boolean {
+  return Boolean(argsText && /\b(test|tests|spec|__tests__)\/|\.test\.|\.spec\./i.test(argsText));
+}

package/src/schemas.ts

@@ -0,0 +1,316 @@
+export const AGENT_SCOPES = ["built-in", "project", "user"] as const;
+export type AgentScope = (typeof AGENT_SCOPES)[number];
+
+export const AGENT_CONCERNS = [
+  "recon",
+  "research",
+  "context-building",
+  "planning",
+  "implementation",
+  "review",
+  "conflict-resolution",
+  "decision-consistency",
+  "delegation",
+  "memory-curation",
+] as const;
+export type AgentConcern = (typeof AGENT_CONCERNS)[number];
+
+export const AGENT_CAPABILITIES = [
+  "inspect-files",
+  "search-files",
+  "run-safe-bash",
+  "validate",
+  "edit-files",
+  "write-new-files",
+  "external-context",
+  "memory-read",
+  "memory-write",
+  "coordinate",
+] as const;
+export type AgentCapability = (typeof AGENT_CAPABILITIES)[number];
+
+export const AGENT_THINKING_LEVELS = ["inherit", "off", "minimal", "low", "medium", "high", "xhigh"] as const;
+export type AgentThinkingLevel = (typeof AGENT_THINKING_LEVELS)[number];
+
+export type AgentMemoryWritePolicy = "never" | "candidate" | "approved";
+
+export interface AgentMemoryPolicy {
+  read: boolean;
+  write: AgentMemoryWritePolicy;
+  categories: string[];
+}
+
+export interface AgentDefinition {
+  name: string;
+  scope: AgentScope;
+  concern: AgentConcern;
+  capabilities: AgentCapability[];
+  description: string;
+  model: "inherit" | string;
+  thinking?: AgentThinkingLevel;
+  tools: string[];
+  memory: AgentMemoryPolicy;
+  systemPrompt: string;
+  sourcePath?: string;
+  diagnostics: string[];
+}
+
+export interface AgentCatalogDiagnostics {
+  warnings: string[];
+  errors: string[];
+}
+
+export type RouteKind =
+  | "bypass"
+  | "single-agent"
+  | "multi-agent-chain"
+  | "multi-agent-parallel"
+  | "multi-agent-dag"
+  | "memory-only"
+  | "ask-user";
+
+export type RouteRisk = "low" | "medium" | "high" | "critical";
+export type RouteAmbiguity = "low" | "medium" | "high";
+
+export interface AgentStep {
+  id?: string;
+  agent: string;
+  task: string;
+  budget?: ToolBudgetProfile;
+}
+
+export interface AgentStage {
+  id: string;
+  tasks: AgentStep[];
+}
+
+export type ToolBudgetProfile = "tight" | "normal" | "deep" | "extended";
+
+export type RoutePlan =
+  | { kind: "single"; agent: string; task: string; budget?: ToolBudgetProfile }
+  | { kind: "chain"; steps: AgentStep[] }
+  | { kind: "parallel"; tasks: AgentStep[] }
+  | { kind: "dag"; stages: AgentStage[] };
+
+export interface RouteDecision {
+  kind: RouteKind;
+  agents: string[];
+  risk: RouteRisk;
+  ambiguity: RouteAmbiguity;
+  needsMemory: boolean;
+  needsArtifacts: boolean;
+  reason: string;
+  plan?: RoutePlan;
+}
+
+export type ApprovalAction = "allow" | "ask" | "block";
+
+export interface ApprovalDecision {
+  action: ApprovalAction;
+  reason: string;
+}
+
+export type RunStatus = "pending" | "running" | "complete" | "failed" | "paused" | "budget-capped" | "stale-repaired";
+
+export interface MemoryCandidate {
+  id: string;
+  category: string;
+  content: string;
+  sourceAgent: string;
+  confidence: number;
+  evidence?: string;
+  scope: "project" | "user";
+  createdAt: string;
+  topicKey?: string;
+}
+
+export type MemoryRecordStatus = "active" | "pending" | "rejected" | "superseded" | "stale" | "quarantined";
+
+export interface MemoryRecord extends MemoryCandidate {
+  status: MemoryRecordStatus;
+  reviewedAt?: string;
+  importance: number;
+  trigger: string;
+  lastSeenAt: string;
+  duplicateCount: number;
+  revisionCount: number;
+  updatedAt?: string;
+  lastUsedAt?: string;
+  useCount?: number;
+  utilityScore?: number;
+  tokenCostEstimate?: number;
+  supersedesId?: string;
+  supersededBy?: string;
+}
+
+export type MemoryAuditEventType =
+  | "create"
+  | "duplicate"
+  | "revise"
+  | "approve"
+  | "reject"
+  | "delete"
+  | "retrieve"
+  | "quarantine"
+  | "stale";
+
+export interface MemoryAuditEvent {
+  id: string;
+  recordId: string;
+  type: MemoryAuditEventType;
+  actor: string;
+  at: string;
+  summary: string;
+  previousContent?: string;
+  nextContent?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentOutput {
+  agent: string;
+  text: string;
+  handoff?: string;
+  memoryCandidates: MemoryCandidate[];
+  raw: string;
+  warnings: string[];
+}
+
+export interface TokenUsageCost {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  total: number;
+}
+
+export interface TokenUsageSummary {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: TokenUsageCost;
+}
+
+export interface RunStepMetrics {
+  durationMs: number;
+  usage: TokenUsageSummary;
+  toolCalls: number;
+  maxToolCalls?: number;
+  toolCallsByName: Record<string, number>;
+  policyViolations?: string[];
+  budgetStopCount?: number;
+  duplicateReadCount?: number;
+  crossStepDuplicateReadCount?: number;
+  crossStepDuplicateReads?: string[];
+  filesRead?: string[];
+  readBytes?: number;
+  outputChars?: number;
+  outputTruncatedCount?: number;
+  filesTouched?: string[];
+  retriesByTool?: Record<string, number>;
+  utility?: {
+    findingsPerTool: number;
+    filesReadPerFinding: number;
+    duplicateReads: number;
+    toolCallsBeforeFirstSignal: number;
+    verificationDone: boolean;
+    memoryCandidatesQuality: number;
+  };
+}
+
+export type ModelResolutionSource = "session-override" | "agent" | "tier" | "inherit";
+export type ModelResolutionStatus = "selected" | "invalid" | "unavailable" | "unauthenticated" | "fallback";
+
+export interface ModelResolutionAttempt {
+  source: ModelResolutionSource;
+  ref?: string;
+  status: ModelResolutionStatus;
+  model?: string;
+  reason?: string;
+}
+
+export interface ModelResolutionLog {
+  selected: string;
+  tier: "fast" | "balanced" | "strong";
+  attempts: ModelResolutionAttempt[];
+}
+
+export interface RunStepState {
+  id: string;
+  agent: string;
+  task: string;
+  status: RunStatus;
+  budget?: ToolBudgetProfile;
+  maxToolCalls?: number;
+  startedAt?: string;
+  endedAt?: string;
+  model?: string;
+  thinkingLevel?: AgentThinkingLevel;
+  output?: AgentOutput;
+  error?: string;
+  currentTool?: string;
+  modelResolution?: ModelResolutionLog;
+  metrics?: RunStepMetrics;
+}
+
+export interface RunState {
+  id: string;
+  route: RouteDecision;
+  status: RunStatus;
+  startedAt: string;
+  endedAt?: string;
+  steps: RunStepState[];
+  logsPath?: string;
+  warnings: string[];
+  budgetPreflight?: {
+    taskKind: string;
+    expectedStages: number;
+    expectedTools: number;
+    risk: RouteRisk;
+    budgetProfile: ToolBudgetProfile;
+    resumeStrategy: string;
+    requiresArtifacts: boolean;
+    recommendation: string;
+  };
+  metrics?: {
+    durationMs: number;
+    usage: TokenUsageSummary;
+    toolCalls: number;
+    toolCallsByName: Record<string, number>;
+    policyViolations?: string[];
+    budgetStopCount?: number;
+    duplicateReadCount?: number;
+    crossStepDuplicateReadCount?: number;
+    crossStepDuplicateReads?: string[];
+    filesRead?: string[];
+  };
+}
+
+export interface ChalinRuntimeState {
+  autoRoutingEnabled: boolean;
+  pendingApprovals: number;
+  activeRuns: number;
+  pendingMemoryCandidates: number;
+  lastRun?: RunState;
+}
+
+export function isAgentScope(value: string): value is AgentScope {
+  return (AGENT_SCOPES as readonly string[]).includes(value);
+}
+
+export function isAgentConcern(value: string): value is AgentConcern {
+  return (AGENT_CONCERNS as readonly string[]).includes(value);
+}
+
+export function isAgentCapability(value: string): value is AgentCapability {
+  return (AGENT_CAPABILITIES as readonly string[]).includes(value);
+}
+
+export function isAgentThinkingLevel(value: string): value is AgentThinkingLevel {
+  return (AGENT_THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+export function riskRank(risk: RouteRisk): number {
+  return { low: 0, medium: 1, high: 2, critical: 3 }[risk];
+}