@polpo-ai/core 0.2.5 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenPolpo Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/assessment-orchestrator.d.ts

@@ -0,0 +1,124 @@
+/**
+ * AssessmentOrchestrator — handles the full assessment pipeline:
+ * result collection → question detection → assessment → auto-correction → judge → fix/retry/fail.
+ *
+ * Pure core version — ZERO Node.js imports.
+ * All runtime-specific behavior is injected via OrchestratorContext ports
+ * and the optional AssessmentPorts interface.
+ */
+import type { OrchestratorContext } from "./orchestrator-context.js";
+import type { Task, TaskResult, ModelConfig } from "./types.js";
+/**
+ * Optional ports for runtime-specific operations that cannot go through
+ * OrchestratorContext (to avoid modifying the shared interface).
+ *
+ * Shell layer creates these from Node.js APIs (node:fs, node:path);
+ * cloud/test environments can provide stubs or omit them.
+ */
+export interface AssessmentPorts {
+    /** Check if a file path exists (sync). Maps to node:fs existsSync. */
+    fileExists?: (path: string) => boolean;
+    /** Read directory entries with type info (sync). Maps to node:fs readdirSync. */
+    readDir?: (dir: string) => Array<{
+        name: string;
+        isFile: boolean;
+        isDirectory: boolean;
+    }>;
+    /** Join path segments. Maps to node:path join. */
+    joinPath?: (...parts: string[]) => string;
+    /** Extract file name from path. Maps to node:path basename. */
+    baseName?: (path: string) => string;
+    /**
+     * Generate an answer to an agent's question.
+     * Shell layer implements this using shared memory + sibling tasks + LLM.
+     * When not provided, question auto-answering is skipped (falls through to assessment).
+     */
+    generateAnswer?: (task: Task, question: string, model?: string | ModelConfig) => Promise<string>;
+    /** LLM-based question classifier. Overrides core classifyAsQuestion when provided. */
+    classifyAsQuestion?: (stdout: string, model?: string | ModelConfig) => Promise<{
+        isQuestion: boolean;
+        question: string;
+    }>;
+}
+/**
+ * Handles the full assessment pipeline: result collection → question detection →
+ * assessment → auto-correction → judge → fix/retry/fail.
+ */
+export declare class AssessmentOrchestrator {
+    private ctx;
+    private ports;
+    constructor(ctx: OrchestratorContext, ports?: AssessmentPorts);
+    /**
+     * Build a rich ReviewContext from all available data sources:
+     * - RunStore activity (files, tool counts)
+     * - TaskResult (stdout, stderr, exit code, duration)
+     * - JSONL transcript log (execution timeline)
+     * - Task outcomes
+     */
+    private buildReviewContext;
+    /**
+     * Attempt to transition a task to "done", but first run the before:task:complete
+     * hook so approval gates (and any other hooks) can block it.
+     * Returns true if the task transitioned to done, false if a hook blocked it.
+     */
+    private transitionToDone;
+    /** Resolve effective confidence: explicit field, or default by type. */
+    private getConfidence;
+    /** Check if any failed checks correspond to estimated expectations. */
+    private hasEstimatedFailures;
+    handleResult(taskId: string, result: TaskResult): Promise<void>;
+    /**
+     * LLM-classify a potential question, then either resolve+rerun or proceed to assessment.
+     */
+    private handlePossibleQuestion;
+    /**
+     * Auto-answer an agent's question and re-run the task (no retry burn).
+     */
+    private resolveAndRerun;
+    /**
+     * Inline answer generation using ctx.memoryStore + ctx.registry + ctx.queryLLM.
+     * Equivalent to the shell's generateAnswer() but without Node.js dependencies.
+     */
+    private generateAnswerInline;
+    /**
+     * Run assessment with retry when all LLM reviewers fail.
+     * Retries up to maxAssessmentRetries times before returning the failed result.
+     */
+    private runAssessmentWithRetry;
+    /**
+     * Standard assessment flow: run expectations/metrics, then mark done/failed/fix/retry.
+     */
+    private proceedToAssessment;
+    /**
+     * Core assessment flow — extracted to allow hook interception in proceedToAssessment.
+     */
+    private runAssessmentFlow;
+    /**
+     * Auto-correct expectations when assessment fails due to wrong paths.
+     * If the only failures are file_exists checks with incorrect paths, search
+     * for the actual files using agent activity + filesystem, update expectations,
+     * and re-assess. Returns true if auto-correction succeeded (task is done).
+     */
+    private tryAutoCorrectExpectations;
+    /** Search for a file by name in common project locations.
+     *  Searches agentWorkDir first (where the agent actually created files),
+     *  then falls back to workDir (the project root) when they differ. */
+    private findFileByName;
+    /**
+     * LLM judge: analyze failed estimated expectations vs agent output and decide
+     * whether they are wrong (correct them) or the agent's work is wrong (fix phase).
+     * Only operates on estimated expectations — firm ones are never touched.
+     * Returns true if expectations were corrected and re-assessment passed.
+     */
+    private judgeExpectations;
+    /** Recursive directory search (bounded depth). Uses injected file system ports. */
+    private searchDir;
+    /**
+     * Fix phase: when execution succeeded but review failed, try a targeted fix
+     * without burning a full retry. After maxFixAttempts, fall back to full retry.
+     */
+    private fixOrRetry;
+    /** @internal — exposed for test access via Orchestrator facade */
+    retryOrFail(taskId: string, _task: Task, result: TaskResult): Promise<void>;
+}
+//# sourceMappingURL=assessment-orchestrator.d.ts.map

package/dist/assessment-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assessment-orchestrator.d.ts","sourceRoot":"","sources":["../src/assessment-orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAoD,WAAW,EAAE,MAAM,YAAY,CAAC;AAUlH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,iFAAiF;IACjF,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC1F,kDAAkD;IAClD,QAAQ,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;IAC1C,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACjG,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,KAAK,OAAO,CAAC;QAAE,UAAU,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3H;AAED;;;GAGG;AACH,qBAAa,sBAAsB;IAGrB,OAAO,CAAC,GAAG;IAFvB,OAAO,CAAC,KAAK,CAAkB;gBAEX,GAAG,EAAE,mBAAmB,EAAE,KAAK,CAAC,EAAE,eAAe;IAIrE;;;;;;OAMG;YACW,kBAAkB;IAmChC;;;;OAIG;YACW,gBAAgB;IA2B9B,wEAAwE;IACxE,OAAO,CAAC,aAAa;IAKrB,uEAAuE;IACvE,OAAO,CAAC,oBAAoB;IAKtB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCrE;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;OAEG;IACH,OAAO,CAAC,eAAe;IAmCvB;;;OAGG;YACW,oBAAoB;IAkDlC;;;OAGG;YACW,sBAAsB;IA8BpC;;OAEG;YACW,mBAAmB;IAgCjC;;OAEG;YACW,iBAAiB;IAsF/B;;;;;OAKG;YACW,0BAA0B;IA+GxC;;0EAEsE;IACtE,OAAO,CAAC,cAAc;IAoBtB;;;;;OAKG;YACW,iBAAiB;IAmG/B,mFAAmF;IACnF,OAAO,CAAC,SAAS;IAoBjB;;;OAGG;YACW,UAAU;IAsDxB,kEAAkE;IAC5D,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAuGlF"}