@schilderlabs/pitown-core 0.1.0 → 0.2.1

package/dist/index.d.mts

@@ -2,6 +2,47 @@
 type InterruptCategory = "missing-context" | "spec-gap" | "policy-gap" | "validation-gap" | "tooling-failure" | "external-blocker";
 type FixType = "adr" | "docs" | "policy" | "prompt" | "skill" | "tooling" | "validation";
 type RunMode = "single-pi";
+type AgentStatus = "queued" | "starting" | "running" | "idle" | "blocked" | "completed" | "failed";
+type AgentMailbox = "inbox" | "outbox";
+type TaskStatus = "queued" | "running" | "blocked" | "completed";
+interface AgentSessionRecord {
+  runtime: "pi";
+  persisted: boolean;
+  sessionDir: string | null;
+  sessionId: string | null;
+  sessionPath: string | null;
+  lastAttachedAt: string | null;
+}
+interface AgentStateSnapshot {
+  agentId: string;
+  role: string;
+  status: AgentStatus;
+  taskId: string | null;
+  task: string | null;
+  branch: string | null;
+  updatedAt: string;
+  lastMessage: string | null;
+  waitingOn: string | null;
+  blocked: boolean;
+  runId: string | null;
+  session: AgentSessionRecord;
+}
+interface AgentMessageRecord {
+  box: AgentMailbox;
+  from: string;
+  body: string;
+  createdAt: string;
+}
+interface TaskRecord {
+  taskId: string;
+  title: string;
+  status: TaskStatus;
+  role: string;
+  assignedAgentId: string;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+}
 interface InterruptRecord {
   id: string;
   runId: string;
@@ -47,6 +88,8 @@ interface RunOptions {
   mode?: RunMode;
   planPath?: string | null;
   recommendedPlanDir?: string | null;
+  appendedSystemPrompt?: string | null;
+  extensionPath?: string | null;
   piCommand?: string;
 }
 interface RunManifest {
@@ -75,6 +118,9 @@ interface PiInvocationRecord {
   repoRoot: string;
   planPath: string | null;
   goal: string | null;
+  sessionDir: string | null;
+  sessionId: string | null;
+  sessionPath: string | null;
   startedAt: string;
   endedAt: string;
   exitCode: number;
@@ -100,6 +146,83 @@ interface ControllerRunResult {
   summary: RunSummary;
   piInvocation: PiInvocationRecord;
 }
+type LoopStopReason = "all-tasks-completed" | "all-remaining-tasks-blocked" | "leader-blocked" | "max-iterations-reached" | "max-wall-time-reached" | "pi-exit-nonzero" | "high-interrupt-rate";
+interface LoopOptions {
+  runOptions: RunOptions;
+  maxIterations?: number;
+  maxWallTimeMs?: number;
+  stopOnPiFailure?: boolean;
+  interruptRateThreshold?: number | null;
+  onIterationComplete?: (iteration: LoopIterationResult) => void;
+}
+interface BoardSnapshot {
+  tasks: Array<{
+    taskId: string;
+    status: TaskStatus;
+  }>;
+  agents: Array<{
+    agentId: string;
+    status: AgentStatus;
+    blocked: boolean;
+  }>;
+  allTasksCompleted: boolean;
+  allRemainingTasksBlocked: boolean;
+  leaderBlocked: boolean;
+  hasQueuedOrRunningWork: boolean;
+}
+interface LoopIterationResult {
+  iteration: number;
+  controllerResult: ControllerRunResult;
+  boardSnapshot: BoardSnapshot;
+  metrics: MetricsSnapshot;
+  elapsedMs: number;
+  continueReason: string | null;
+  stopReason: LoopStopReason | null;
+}
+interface LoopRunResult {
+  loopId: string;
+  iterations: LoopIterationResult[];
+  stopReason: LoopStopReason;
+  totalIterations: number;
+  totalElapsedMs: number;
+  finalBoardSnapshot: BoardSnapshot;
+  aggregateMetrics: MetricsSnapshot;
+}
+//#endregion
+//#region src/agents.d.ts
+declare function getAgentsDir(artifactsDir: string): string;
+declare function getAgentDir(artifactsDir: string, agentId: string): string;
+declare function getAgentStatePath(artifactsDir: string, agentId: string): string;
+declare function getAgentSessionPath(artifactsDir: string, agentId: string): string;
+declare function getAgentMailboxPath(artifactsDir: string, agentId: string, box: AgentMailbox): string;
+declare function getAgentSessionsDir(artifactsDir: string, agentId: string): string;
+declare function getSessionIdFromPath(sessionPath: string | null | undefined): string | null;
+declare function createAgentSessionRecord(input?: Partial<Pick<AgentSessionRecord, "sessionDir" | "sessionId" | "sessionPath" | "lastAttachedAt">>): AgentSessionRecord;
+declare function createAgentState(input: {
+  agentId: string;
+  role: string;
+  status: AgentStatus;
+  taskId?: string | null;
+  task?: string | null;
+  branch?: string | null;
+  lastMessage?: string | null;
+  waitingOn?: string | null;
+  blocked?: boolean;
+  runId?: string | null;
+  session?: AgentSessionRecord;
+}): AgentStateSnapshot;
+declare function writeAgentState(artifactsDir: string, state: AgentStateSnapshot): void;
+declare function readAgentState(artifactsDir: string, agentId: string): AgentStateSnapshot | null;
+declare function listAgentStates(artifactsDir: string): AgentStateSnapshot[];
+declare function appendAgentMessage(input: {
+  artifactsDir: string;
+  agentId: string;
+  box: AgentMailbox;
+  from: string;
+  body: string;
+}): AgentMessageRecord;
+declare function readAgentMessages(artifactsDir: string, agentId: string, box: AgentMailbox): AgentMessageRecord[];
+declare function getLatestAgentSession(artifactsDir: string, agentId: string): AgentSessionRecord;
 //#endregion
 //#region src/controller.d.ts
 declare function runController(options: RunOptions): ControllerRunResult;
@@ -127,6 +250,24 @@ declare function acquireRepoLease(runId: string, repoId: string, branch: string)
   release: () => void;
 };
 //#endregion
+//#region src/loop.d.ts
+declare function snapshotBoard(artifactsDir: string): BoardSnapshot;
+declare function evaluateStopCondition(input: {
+  iteration: number;
+  maxIterations: number;
+  elapsedMs: number;
+  maxWallTimeMs: number;
+  piExitCode: number;
+  stopOnPiFailure: boolean;
+  board: BoardSnapshot;
+  metrics: MetricsSnapshot;
+  interruptRateThreshold: number | null;
+}): {
+  stopReason: LoopStopReason | null;
+  continueReason: string | null;
+};
+declare function runLoop(options: LoopOptions): LoopRunResult;
+//#endregion
 //#region src/metrics.d.ts
 declare function computeInterruptRate(interrupts: InterruptRecord[], taskAttempts: TaskAttempt[]): number;
 declare function computeAutonomousCompletionRate(taskAttempts: TaskAttempt[]): number;
@@ -139,6 +280,95 @@ declare function computeMetrics(input: {
   feedbackCycles?: FeedbackCycle[];
 }): MetricsSnapshot;
 //#endregion
+//#region src/orchestration.d.ts
+interface SpawnAgentRunOptions {
+  repoRoot: string;
+  artifactsDir: string;
+  role: string;
+  agentId: string;
+  task: string | null;
+  appendedSystemPrompt?: string | null;
+  extensionPath?: string | null;
+  taskId?: string | null;
+}
+interface SpawnAgentRunResult {
+  piResult: {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+  };
+  latestSession: AgentSessionRecord;
+  completionMessage: string;
+}
+interface DelegateTaskOptions {
+  repoRoot: string;
+  artifactsDir: string;
+  fromAgentId: string;
+  role: string;
+  agentId?: string | null;
+  appendedSystemPrompt?: string | null;
+  extensionPath?: string | null;
+  task: string;
+}
+interface DelegateTaskResult {
+  task: TaskRecord;
+  agentId: string;
+  piResult: {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+  };
+  latestSession: AgentSessionRecord;
+}
+interface ResolvedAgentSession {
+  state: AgentStateSnapshot;
+  session: AgentSessionRecord;
+}
+interface RunAgentTurnOptions {
+  repoRoot: string;
+  artifactsDir: string;
+  agentId: string;
+  message: string;
+  from?: string;
+  runtimeArgs?: string[] | null;
+}
+interface RunAgentTurnResult {
+  piResult: {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+  };
+  latestSession: AgentSessionRecord;
+  completionMessage: string;
+}
+declare function createRolePrompt(input: {
+  role: string;
+  task: string | null;
+  repoRoot: string;
+}): string;
+declare function resolveAgentSession(agentId: string, artifactsDir: string): ResolvedAgentSession;
+declare function queueAgentMessage(input: {
+  artifactsDir: string;
+  agentId: string;
+  from: string;
+  body: string;
+}): void;
+declare function updateAgentStatus(input: {
+  artifactsDir: string;
+  agentId: string;
+  status: "queued" | "running" | "idle" | "blocked" | "completed" | "failed";
+  lastMessage?: string | null;
+  waitingOn?: string | null;
+  blocked?: boolean;
+}): void;
+declare function spawnAgentRun(options: SpawnAgentRunOptions): SpawnAgentRunResult;
+declare function runAgentTurn(options: RunAgentTurnOptions): RunAgentTurnResult;
+declare function delegateTask(options: DelegateTaskOptions): DelegateTaskResult;
+//#endregion
+//#region src/pi.d.ts
+declare function detectPiAuthFailure(stderr: string, stdout: string): boolean;
+declare function createPiAuthHelpMessage(): string;
+//#endregion
 //#region src/repo.d.ts
 declare function isGitRepo(cwd: string): boolean;
 declare function getRepoRoot(cwd: string): string;
@@ -156,7 +386,28 @@ declare function runCommandSync(command: string, args: string[], options?: {
   cwd?: string;
   env?: NodeJS.ProcessEnv;
 }): CommandResult;
+declare function assertCommandAvailable(command: string): void;
+declare function runCommandInteractive(command: string, args: string[], options?: {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+}): number;
 declare function assertSuccess(result: CommandResult, context: string): void;
 //#endregion
-export { CommandResult, ControllerRunResult, CreateInterruptInput, FeedbackCycle, FixType, InterruptCategory, InterruptRecord, MetricsSnapshot, PiInvocationRecord, RunManifest, RunMode, RunOptions, RunSummary, TaskAttempt, acquireRepoLease, appendJsonl, assertSuccess, computeAutonomousCompletionRate, computeContextCoverageScore, computeFeedbackToDemoCycleTime, computeInterruptRate, computeMeanTimeToCorrect, computeMetrics, createInterruptRecord, createRepoSlug, getCurrentBranch, getRepoIdentity, getRepoRoot, isGitRepo, readJsonl, resolveInterrupt, runCommandSync, runController };
+//#region src/tasks.d.ts
+declare function getTasksDir(artifactsDir: string): string;
+declare function getTaskPath(artifactsDir: string, taskId: string): string;
+declare function createTaskRecord(input: {
+  taskId: string;
+  title: string;
+  status: TaskStatus;
+  role: string;
+  assignedAgentId: string;
+  createdBy: string;
+}): TaskRecord;
+declare function writeTaskRecord(artifactsDir: string, task: TaskRecord): void;
+declare function updateTaskRecordStatus(artifactsDir: string, taskId: string, status: TaskStatus): TaskRecord | null;
+declare function readTaskRecord(artifactsDir: string, taskId: string): TaskRecord | null;
+declare function listTaskRecords(artifactsDir: string): TaskRecord[];
+//#endregion
+export { AgentMailbox, AgentMessageRecord, AgentSessionRecord, AgentStateSnapshot, AgentStatus, BoardSnapshot, CommandResult, ControllerRunResult, CreateInterruptInput, DelegateTaskOptions, DelegateTaskResult, FeedbackCycle, FixType, InterruptCategory, InterruptRecord, LoopIterationResult, LoopOptions, LoopRunResult, LoopStopReason, MetricsSnapshot, PiInvocationRecord, ResolvedAgentSession, RunAgentTurnOptions, RunAgentTurnResult, RunManifest, RunMode, RunOptions, RunSummary, SpawnAgentRunOptions, SpawnAgentRunResult, TaskAttempt, TaskRecord, TaskStatus, acquireRepoLease, appendAgentMessage, appendJsonl, assertCommandAvailable, assertSuccess, computeAutonomousCompletionRate, computeContextCoverageScore, computeFeedbackToDemoCycleTime, computeInterruptRate, computeMeanTimeToCorrect, computeMetrics, createAgentSessionRecord, createAgentState, createInterruptRecord, createPiAuthHelpMessage, createRepoSlug, createRolePrompt, createTaskRecord, delegateTask, detectPiAuthFailure, evaluateStopCondition, getAgentDir, getAgentMailboxPath, getAgentSessionPath, getAgentSessionsDir, getAgentStatePath, getAgentsDir, getCurrentBranch, getLatestAgentSession, getRepoIdentity, getRepoRoot, getSessionIdFromPath, getTaskPath, getTasksDir, isGitRepo, listAgentStates, listTaskRecords, queueAgentMessage, readAgentMessages, readAgentState, readJsonl, readTaskRecord, resolveAgentSession, resolveInterrupt, runAgentTurn, runCommandInteractive, runCommandSync, runController, runLoop, snapshotBoard, spawnAgentRun, updateAgentStatus, updateTaskRecordStatus, writeAgentState, writeTaskRecord };
 //# sourceMappingURL=index.d.mts.map