agentweaver 0.1.16 → 0.1.17

package/README.md

@@ -34,13 +34,21 @@ In practice, this means you can treat an agent workflow like an engineered syste
 
 ## Core Concepts
 
-- `flow spec`: declarative JSON under `src/pipeline/flow-specs/` or project-local `.agentweaver/.flows/`
+- `flow spec`: declarative JSON under `src/pipeline/flow-specs/`, global `~/.agentweaver/.flows/`, or project-local `.agentweaver/.flows/`
 - `node`: reusable runtime unit from `src/pipeline/nodes/`
 - `executor`: integration layer for Jira, Codex, OpenCode, GitLab, shell/process execution, Telegram notifications, and related actions
 - `scope`: isolated workspace key for artifacts and flow state; usually based on Jira task, otherwise derived from git context
 - `artifact`: file produced or consumed by flows, used as the stable contract between stages
 - `flow state`: compact persisted execution metadata used for resume/restart in long-running flows such as `auto-golang`
 
+## Семантика Запуска
+
+- `resume` возобновляет только реально прерванный запуск и использует сохранённое состояние исполнения без пересборки уже выполненных шагов
+- `continue` предназначен для завершённых итерационных циклов и запускает следующую итерацию от последних валидных артефактов без удаления исторических артефактов
+- `restart` считается новым запуском: текущая активная попытка архивируется в `.agentweaver/scopes/<scope>/.artifacts/restart-archives/attempt-XXXX`, после чего создаётся новая активная попытка
+- Для неоднозначных запусков оператор должен явно выбрать действие: в интерактивном режиме через подтверждение, в неинтерактивном режиме через `--resume`, `--continue` или `--restart`
+- Контракт распространяется на `auto-common`, `auto-simple`, `auto-golang`, `instant-task`, `review-loop`, `run-go-linter-loop` и `run-go-tests-loop`
+
 ## Declarative Workflow Model
 
 The center of the system is the declarative flow spec:
@@ -118,6 +126,34 @@ node dist/index.js --help
 
 Global install after publishing:
 
+## Plugin SDK
+
+AgentWeaver supports local plugins and custom declarative flows from both global and project-local `.agentweaver` directories.
+
+Plugin authors must use only the public SDK subpath: `agentweaver/plugin-sdk`.
+The package root `agentweaver`, internal paths such as `agentweaver/dist/*` and `agentweaver/src/*`, and repository-relative source imports are not part of the supported SDK contract.
+
+Supported plugin manifest locations are:
+
+- `~/.agentweaver/.plugins/<plugin-id>/plugin.json`
+- `.agentweaver/.plugins/<plugin-id>/plugin.json`
+
+The plugin directory name and manifest `id` must match exactly.
+
+Use the dedicated guide at [docs/plugin-sdk.md](docs/plugin-sdk.md) for:
+
+- the executor versus node architecture
+- manifest and entrypoint rules
+- optional routing metadata for plugin LLM executors
+- runtime context APIs available to plugin code
+- global and project-local flow wiring under `~/.agentweaver/.flows/` and `.agentweaver/.flows/`
+- compatibility, testing, troubleshooting, and a complete end-to-end walkthrough
+
+Repository reference examples live under `docs/examples/`, for example:
+
+- `docs/examples/.plugins/claude-example-plugin/`
+- `docs/examples/.flows/claude-example.json`
+
 ```bash
 npm install -g agentweaver
 agentweaver --help
@@ -183,7 +219,7 @@ OPENCODE_MODEL=minimax-coding-plan/MiniMax-M2.7
 
 The full-screen TUI is not a cosmetic wrapper. It is the operator console for the harness:
 
-- browse built-in and project-local workflows
+- browse built-in, global, and project-local workflows
 - launch flows in the current scope
 - inspect progress by phase and step
 - follow activity, prompts, summaries, and statuses
@@ -332,27 +368,31 @@ Current layout:
 Flow discovery behavior:
 
 - built-in flows are loaded from `src/pipeline/flow-specs/`
-- project-local flows are loaded from `.agentweaver/.flows/`
-- both built-in and project-local flow specs are validated at load time
-- duplicate flow ids fail fast
-- project-local flows are shown separately in the UI
+- global custom flows are loaded from `~/.agentweaver/.flows/`
+- project-local custom flows are loaded from `.agentweaver/.flows/`
+- all discovered flow specs are validated at load time
+- duplicate flow ids fail fast across built-in, global, and project-local sources
+- custom flows are shown separately in the UI as global and project-local groups
 
-## Project-Local Flows
+## Custom Flows
 
-You can add project-specific flow specs under:
+You can add custom flow specs under either:
 
 ```bash
+~/.agentweaver/.flows/**/*.json
 .agentweaver/.flows/**/*.json
 ```
 
-Project-local flows:
+Custom flows:
 
 - are discovered recursively
 - get their flow id from the relative path without `.json`
 - share the same validator and runtime as built-in flows
 - cannot conflict with an existing built-in or other discovered flow id
 
-Nested `flow-run` steps can reference built-in or project-local specs by file name, as long as the name resolves unambiguously.
+Use the global directory for reusable personal flows and plugins across repositories, and the project-local directory for repo-specific wiring.
+
+Nested `flow-run` steps can reference built-in, global, or project-local specs by file name, as long as the name resolves unambiguously.
 
 ## Development
 

package/dist/artifacts.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { TaskRunnerError } from "./errors.js";
@@ -214,8 +214,78 @@ export function gitlabDiffReviewInputJsonFile(taskKey) {
 export function flowStateFile(scopeKey, flowId) {
     return scopeArtifactsFile(scopeKey, `.agentweaver-flow-state-${encodeURIComponent(flowId)}.json`);
 }
-export function planArtifacts(taskKey) {
-    return [designFile(taskKey), designJsonFile(taskKey), planFile(taskKey), planJsonFile(taskKey), qaFile(taskKey), qaJsonFile(taskKey)];
+export function restartArchivesDir(scopeKey) {
+    return scopeArtifactsFile(scopeKey, "restart-archives");
+}
+function nextRestartArchiveName(scopeKey) {
+    const archiveRoot = restartArchivesDir(scopeKey);
+    if (!existsSync(archiveRoot)) {
+        return "attempt-0001";
+    }
+    const attemptNumbers = readdirSync(archiveRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => /^attempt-(\d{4})$/.exec(entry.name)?.[1] ?? null)
+        .filter((value) => value !== null)
+        .map((value) => Number.parseInt(value, 10));
+    const nextNumber = (attemptNumbers.length === 0 ? 0 : Math.max(...attemptNumbers)) + 1;
+    return `attempt-${String(nextNumber).padStart(4, "0")}`;
+}
+export function archiveActiveAttempt(scopeKey) {
+    const workspaceDir = scopeWorkspaceDir(scopeKey);
+    if (!existsSync(workspaceDir)) {
+        return null;
+    }
+    const workspaceEntries = readdirSync(workspaceDir, { withFileTypes: true })
+        .filter((entry) => entry.name !== ".artifacts");
+    const artifactEntries = readdirSync(scopeArtifactsDir(scopeKey), { withFileTypes: true })
+        .filter((entry) => entry.name !== "restart-archives");
+    if (workspaceEntries.length === 0 && artifactEntries.length === 0) {
+        return null;
+    }
+    const archiveRoot = restartArchivesDir(scopeKey);
+    mkdirSync(archiveRoot, { recursive: true });
+    const archiveDir = path.join(archiveRoot, nextRestartArchiveName(scopeKey));
+    const workspaceArchiveDir = path.join(archiveDir, "workspace");
+    const artifactsArchiveDir = path.join(archiveDir, "artifacts");
+    mkdirSync(workspaceArchiveDir, { recursive: true });
+    mkdirSync(artifactsArchiveDir, { recursive: true });
+    try {
+        for (const entry of workspaceEntries) {
+            cpSync(path.join(workspaceDir, entry.name), path.join(workspaceArchiveDir, entry.name), {
+                recursive: true,
+                errorOnExist: true,
+                force: false,
+            });
+        }
+        for (const entry of artifactEntries) {
+            cpSync(path.join(scopeArtifactsDir(scopeKey), entry.name), path.join(artifactsArchiveDir, entry.name), {
+                recursive: true,
+                errorOnExist: true,
+                force: false,
+            });
+        }
+    }
+    catch (error) {
+        rmSync(archiveDir, { recursive: true, force: true });
+        throw new TaskRunnerError(`Failed to archive active attempt for restart: ${error.message}`);
+    }
+    for (const entry of workspaceEntries) {
+        rmSync(path.join(workspaceDir, entry.name), { recursive: true, force: true });
+    }
+    for (const entry of artifactEntries) {
+        rmSync(path.join(scopeArtifactsDir(scopeKey), entry.name), { recursive: true, force: true });
+    }
+    return archiveDir;
+}
+export function planArtifacts(taskKey, iteration) {
+    return [
+        designFile(taskKey, iteration),
+        designJsonFile(taskKey, iteration),
+        planFile(taskKey, iteration),
+        planJsonFile(taskKey, iteration),
+        qaFile(taskKey, iteration),
+        qaJsonFile(taskKey, iteration),
+    ];
 }
 export function bugAnalyzeArtifacts(taskKey) {
     return [

package/dist/doctor/checks/executors.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { DoctorStatus } from "../types.js";
 import { CATEGORY } from "./category.js";
-import { ALLOWED_MODELS_BY_EXECUTOR } from "../../pipeline/launch-profile-config.js";
+import { allowedModelsForExecutor } from "../../pipeline/launch-profile-config.js";
 import { findCmdPath, isExecutable } from "../../runtime/command-resolution.js";
 function getEnvVarName(executorId) {
     return executorId === "codex" ? "CODEX_BIN" : "OPENCODE_BIN";
@@ -72,7 +72,7 @@ function checkExecutor(executorId) {
     if (versionOutput === null) {
         return createResult(executorId, DoctorStatus.Fail, `${executorId} --version check failed`, `${executorId} --version did not produce expected output`, `path: ${resolution.path}, source: ${resolution.source}`, resolution, null);
     }
-    const allowedModels = ALLOWED_MODELS_BY_EXECUTOR[executorId];
+    const allowedModels = allowedModelsForExecutor(executorId);
     const modelWarnings = [];
     for (const model of allowedModels) {
         const modelResult = spawnSync(resolution.path, ["--model", model, "--version"], { encoding: "utf8", stdio: "pipe" });

package/dist/flow-state.js

@@ -4,7 +4,25 @@ import { ensureScopeWorkspaceDir, flowStateFile } from "./artifacts.js";
 import { TaskRunnerError } from "./errors.js";
 import { isFlowRunResumeEnvelope } from "./pipeline/flow-run-resume.js";
 import { resolveStoredExecutionRoutingSnapshot, singleLaunchProfileExecutionRouting } from "./runtime/execution-routing.js";
-const FLOW_STATE_SCHEMA_VERSION = 2;
+const FLOW_STATE_SCHEMA_VERSION = 3;
+const CONTINUABLE_FLOW_KINDS = new Set([
+    "design-review-loop-flow",
+    "review-loop-flow",
+    "review-project-loop-flow",
+    "run-go-linter-loop-flow",
+    "run-go-tests-loop-flow",
+]);
+const CONTINUABLE_PARENT_FLOW_IDS = new Set([
+    "auto-common",
+    "auto-simple",
+    "auto-golang",
+    "instant-task",
+]);
+const CONTINUABLE_DIRECT_FLOW_IDS = new Set([
+    "review-loop",
+    "run-go-linter-loop",
+    "run-go-tests-loop",
+]);
 function nowIso8601() {
     return new Date().toISOString();
 }
@@ -45,6 +63,7 @@ export function createFlowRunState(scopeKey, flowId, executionState, jiraRef, la
     ensurePublicationRunId(executionState);
     const effectiveExecutionRouting = executionRouting ?? (launchProfile ? singleLaunchProfileExecutionRouting(launchProfile) : undefined);
     const effectiveLaunchProfile = launchProfile ?? effectiveExecutionRouting?.defaultRoute;
+    const continuation = inferContinuationMetadata(flowId, executionState);
     return {
         schemaVersion: FLOW_STATE_SCHEMA_VERSION,
         flowId,
@@ -56,6 +75,7 @@ export function createFlowRunState(scopeKey, flowId, executionState, jiraRef, la
         ...(effectiveLaunchProfile ? { launchProfile: effectiveLaunchProfile } : {}),
         ...(effectiveExecutionRouting ? { executionRouting: effectiveExecutionRouting, routingFingerprint: effectiveExecutionRouting.fingerprint } : {}),
         ...(selectedRoutingPreset ? { selectedRoutingPreset } : {}),
+        continuation,
         executionState: stripExecutionStatePayload(executionState),
     };
 }
@@ -66,6 +86,43 @@ function upgradeFlowRunStateV1(state) {
         schemaVersion: FLOW_STATE_SCHEMA_VERSION,
         ...(executionRouting ? { executionRouting, routingFingerprint: executionRouting.fingerprint } : {}),
         ...(executionRouting ? { selectedRoutingPreset: { kind: "custom", label: "Legacy launch profile" } } : {}),
+        continuation: {
+            continueEligible: false,
+        },
+    };
+}
+function upgradeFlowRunStateV2(state) {
+    return {
+        ...state,
+        schemaVersion: FLOW_STATE_SCHEMA_VERSION,
+        continuation: {
+            continueEligible: false,
+        },
+    };
+}
+function parseTerminationLocation(terminationReason) {
+    if (typeof terminationReason !== "string") {
+        return {};
+    }
+    const match = /^Stopped by ([^:]+):(.+)$/.exec(terminationReason.trim());
+    if (!match) {
+        return {};
+    }
+    const stopPhaseId = match[1];
+    const stopStepId = match[2];
+    return {
+        ...(stopPhaseId ? { stopPhaseId } : {}),
+        ...(stopStepId ? { stopStepId } : {}),
+    };
+}
+function inferContinuationMetadata(flowId, executionState) {
+    const stopLocation = parseTerminationLocation(executionState.terminationReason);
+    const continueEligible = CONTINUABLE_FLOW_KINDS.has(executionState.flowKind)
+        || (CONTINUABLE_PARENT_FLOW_IDS.has(flowId) && Boolean(stopLocation.stopPhaseId && stopLocation.stopStepId));
+    return {
+        continueEligible,
+        ...(stopLocation.stopPhaseId ? { stopPhaseId: stopLocation.stopPhaseId } : {}),
+        ...(stopLocation.stopStepId ? { stopStepId: stopLocation.stopStepId } : {}),
     };
 }
 function normalizeFlowRunState(raw, flowId, filePath) {
@@ -77,6 +134,9 @@ function normalizeFlowRunState(raw, flowId, filePath) {
     if (schemaVersion === 1) {
         state = upgradeFlowRunStateV1(raw);
     }
+    else if (schemaVersion === 2) {
+        state = upgradeFlowRunStateV2(raw);
+    }
     else if (schemaVersion === FLOW_STATE_SCHEMA_VERSION) {
         state = raw;
     }
@@ -97,6 +157,11 @@ function normalizeFlowRunState(raw, flowId, filePath) {
         state.executionRouting = executionRouting;
         state.routingFingerprint = executionRouting.fingerprint;
     }
+    const inferredContinuation = inferContinuationMetadata(state.flowId, state.executionState);
+    state.continuation = {
+        ...inferredContinuation,
+        continueEligible: inferredContinuation.continueEligible && state.continuation?.continueEligible !== false,
+    };
     return state;
 }
 export function loadFlowRunState(scopeKey, flowId) {
@@ -125,6 +190,7 @@ export function saveFlowRunState(state) {
         state.executionRouting = singleLaunchProfileExecutionRouting(state.launchProfile);
         state.routingFingerprint = state.executionRouting.fingerprint;
     }
+    state.continuation = inferContinuationMetadata(state.flowId, state.executionState);
     ensureScopeWorkspaceDir(state.scopeKey);
     writeFileSync(flowStateFile(state.scopeKey, state.flowId), `${JSON.stringify({
         ...state,
@@ -154,6 +220,53 @@ export function hasResumableFlowState(state) {
     }
     return state.executionState.phases.some((phase) => phase.steps.some((step) => step.status === "done" || step.status === "running"));
 }
+function hasContinuableFlowState(state) {
+    if (!state) {
+        return false;
+    }
+    if (!state.executionState.terminated && state.status !== "completed") {
+        return false;
+    }
+    return state.continuation?.continueEligible === true;
+}
+export function classifyFlowLaunchAvailability(state) {
+    if (!state) {
+        return {
+            hasExistingState: false,
+            requiresExplicitChoice: false,
+            resume: { available: false, reason: "No saved state found." },
+            continue: { available: false, reason: "No saved state found." },
+            restart: { available: true, reason: "Start a fresh attempt." },
+        };
+    }
+    const resumeAvailable = hasResumableFlowState(state);
+    const continueAvailable = hasContinuableFlowState(state);
+    const availability = {
+        hasExistingState: true,
+        requiresExplicitChoice: resumeAvailable || continueAvailable,
+        resume: resumeAvailable
+            ? { available: true, reason: "Continue the interrupted execution state." }
+            : {
+                available: false,
+                reason: state.executionState.terminated || state.status === "completed"
+                    ? "The saved run already terminated and cannot be resumed."
+                    : "The saved state is not resumable.",
+            },
+        continue: continueAvailable
+            ? { available: true, reason: "Start the next iteration from the latest active artifacts." }
+            : {
+                available: false,
+                reason: state.schemaVersion < FLOW_STATE_SCHEMA_VERSION
+                    ? "Legacy flow state lacks safe continuation metadata."
+                    : "The saved run does not expose a continuable loop boundary.",
+            },
+        restart: {
+            available: true,
+            reason: "Archive the active attempt and start a fresh run.",
+        },
+    };
+    return availability;
+}
 function normalizeStepState(step) {
     if (step.status !== "running") {
         return step;
@@ -237,3 +350,27 @@ export function prepareFlowStateForResume(state) {
     delete state.executionState.terminationReason;
     return state;
 }
+export function prepareFlowStateForContinue(state, orderedPhases) {
+    state.status = "pending";
+    state.lastError = null;
+    state.currentStep = null;
+    const flowKind = state.executionState.flowKind;
+    if (CONTINUABLE_FLOW_KINDS.has(flowKind) || CONTINUABLE_DIRECT_FLOW_IDS.has(state.flowId)) {
+        state.executionState = {
+            ...state.executionState,
+            publicationRunId: randomUUID(),
+            terminated: false,
+            phases: orderedPhases.map(createPendingPhaseState),
+        };
+        delete state.executionState.terminationReason;
+        delete state.executionState.terminationOutcome;
+        return state;
+    }
+    const targetPhaseId = state.continuation?.stopPhaseId ?? parseTerminationLocation(state.executionState.terminationReason).stopPhaseId;
+    if (!targetPhaseId) {
+        throw new TaskRunnerError("Continue is impossible because the stop phase could not be determined safely. Use restart.");
+    }
+    rewindFlowRunStateToPhase(state, orderedPhases, targetPhaseId);
+    state.executionState.publicationRunId = randomUUID();
+    return state;
+}