agentweaver 0.1.16 → 0.1.18

package/docs/example/.plugins/claude-example-plugin/index.js

@@ -0,0 +1,149 @@
+import { AGENTWEAVER_PLUGIN_SDK_VERSION } from "agentweaver/plugin-sdk";
+
+export const CLAUDE_EXAMPLE_PLUGIN_SDK_VERSION = AGENTWEAVER_PLUGIN_SDK_VERSION;
+export const CLAUDE_EXECUTOR_ID = "claude";
+export const CLAUDE_AUTH_STATUS_ERROR = "Claude CLI authentication is required. Run 'claude auth status' and sign in before using the example flow.";
+export const CLAUDE_NORMALIZATION_ERROR =
+  "Claude JSON normalization failed: no supported assistant text was found in result, message.content[*].text, or content[*].text.";
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function resolveSetting(override, env, envKey, defaultValue) {
+  const direct = nonEmptyString(typeof override === "number" ? String(override) : override);
+  if (direct) {
+    return direct;
+  }
+  const fromEnv = nonEmptyString(env?.[envKey]);
+  if (fromEnv) {
+    return fromEnv;
+  }
+  return nonEmptyString(defaultValue);
+}
+
+function resolveStringListSetting(override, env, envKey, defaultValue) {
+  const direct = nonEmptyString(override);
+  const envValue = nonEmptyString(env?.[envKey]);
+  const effective = direct ?? envValue ?? nonEmptyString(defaultValue);
+  if (!effective) {
+    return [];
+  }
+  return effective
+    .split(/[,\s]+/)
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+function extractTextFragments(items) {
+  if (!Array.isArray(items)) {
+    return null;
+  }
+  const fragments = items
+    .map((item) => (item && typeof item === "object" ? item.text : undefined))
+    .filter((text) => typeof text === "string" && text.trim().length > 0);
+  return fragments.length > 0 ? fragments.join("\n") : null;
+}
+
+export function normalizeClaudePayload(payload, effectiveModel = "") {
+  const resultText = nonEmptyString(payload?.result);
+  const messageContentText = extractTextFragments(payload?.message?.content);
+  const contentText = extractTextFragments(payload?.content);
+  const output = resultText ?? messageContentText ?? contentText;
+  if (!output) {
+    throw new Error(CLAUDE_NORMALIZATION_ERROR);
+  }
+  return {
+    output,
+    model: nonEmptyString(payload?.model) ?? effectiveModel,
+    rawResponse: payload,
+  };
+}
+
+export async function verifyClaudeAuth(runtime, env, config) {
+  const command = runtime.resolveCmd(config.defaultCommand, config.commandEnvVar);
+  try {
+    await runtime.runCommand([command, "auth", "status"], {
+      env,
+      label: "claude:auth-status",
+      printFailureOutput: false,
+    });
+  } catch {
+    throw new Error(CLAUDE_AUTH_STATUS_ERROR);
+  }
+  return command;
+}
+
+export const claudeExecutorDefinition = {
+  kind: CLAUDE_EXECUTOR_ID,
+  version: 1,
+  defaultConfig: {
+    commandEnvVar: "CLAUDE_BIN",
+    defaultCommand: "claude",
+    modelEnvVar: "CLAUDE_MODEL",
+    defaultModel: "",
+    maxTurnsEnvVar: "CLAUDE_MAX_TURNS",
+    defaultMaxTurns: "",
+    permissionModeEnvVar: "CLAUDE_PERMISSION_MODE",
+    defaultPermissionMode: "bypassPermissions",
+    allowedToolsEnvVar: "CLAUDE_ALLOWED_TOOLS",
+    defaultAllowedTools: "",
+    disallowedToolsEnvVar: "CLAUDE_DISALLOWED_TOOLS",
+    defaultDisallowedTools: "",
+    addCwdAsAllowedDir: true,
+  },
+  async execute(context, input, config) {
+    const env = input?.env ?? context.env;
+    const command = input?.command ?? context.runtime.resolveCmd(config.defaultCommand, config.commandEnvVar);
+    const effectiveModel = resolveSetting(input?.model, env, config.modelEnvVar, config.defaultModel);
+    const effectiveMaxTurns = resolveSetting(input?.maxTurns, env, config.maxTurnsEnvVar, config.defaultMaxTurns);
+    const permissionMode = resolveSetting(undefined, env, config.permissionModeEnvVar, config.defaultPermissionMode);
+    const allowedTools = resolveStringListSetting(undefined, env, config.allowedToolsEnvVar, config.defaultAllowedTools);
+    const disallowedTools = resolveStringListSetting(undefined, env, config.disallowedToolsEnvVar, config.defaultDisallowedTools);
+    const argv = [
+      command,
+      "-p",
+      String(input?.prompt ?? ""),
+      "--output-format",
+      "json",
+      ...(config.addCwdAsAllowedDir ? ["--add-dir", context.cwd] : []),
+      ...(permissionMode ? ["--permission-mode", permissionMode] : []),
+      ...(allowedTools.length > 0 ? ["--allowedTools", ...allowedTools] : []),
+      ...(disallowedTools.length > 0 ? ["--disallowedTools", ...disallowedTools] : []),
+      ...(effectiveModel ? ["--model", effectiveModel] : []),
+      ...(effectiveMaxTurns ? ["--max-turns", effectiveMaxTurns] : []),
+    ];
+    const stdout = await context.runtime.runCommand(argv, {
+      env,
+      dryRun: context.dryRun,
+      verbose: context.verbose,
+      label: `claude:${effectiveModel || "default"}`,
+      printFailureOutput: true,
+    });
+    let payload;
+    try {
+      payload = JSON.parse(stdout);
+    } catch (error) {
+      throw new Error(`Claude CLI returned invalid JSON: ${error.message}`);
+    }
+    const normalized = normalizeClaudePayload(payload, effectiveModel ?? "");
+    return {
+      output: normalized.output,
+      command,
+      model: normalized.model ?? "",
+      rawResponse: normalized.rawResponse,
+    };
+  },
+};
+
+export const executors = [
+  {
+    id: CLAUDE_EXECUTOR_ID,
+    definition: claudeExecutorDefinition,
+    routing: {
+      kind: "llm",
+      defaultModel: "sonnet",
+      models: ["sonnet", "opus", "haiku"],
+    },
+  },
+];

package/docs/example/.plugins/claude-example-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "claude-example-plugin",
+  "sdk_version": 1,
+  "entrypoint": "index.js",
+  "name": "Claude Example Plugin",
+  "version": "0.1.0",
+  "description": "Project-local Claude CLI reference plugin for AgentWeaver."
+}

package/docs/examples/.flows/claude-example.json

@@ -0,0 +1,50 @@
+{
+  "kind": "claude-example-flow",
+  "version": 1,
+  "description": "Project-local reference flow for the Claude example plugin.",
+  "phases": [
+    {
+      "id": "example",
+      "steps": [
+        {
+          "id": "run_claude_prompt",
+          "node": "llm-prompt",
+          "prompt": {
+            "inlineTemplate": "Use the current workspace. Create the JSON file `.agentweaver/.artifacts/examples/claude-example-proof.json` with exactly this shape: `{ \"status\": \"ok\", \"executor\": \"claude\", \"message\": \"<one short sentence proving the Claude example plugin executed through llm-prompt>\", \"model\": \"<the exact model name you used, or an empty string if unavailable>\" }`. Write valid JSON only to that file. After the file is written, reply with exactly `wrote .agentweaver/.artifacts/examples/claude-example-proof.json`."
+          },
+          "params": {
+            "labelText": {
+              "const": "Run Claude via llm-prompt"
+            },
+            "executor": {
+              "const": "claude"
+            },
+            "requiredArtifacts": {
+              "list": [
+                {
+                  "const": ".agentweaver/.artifacts/examples/claude-example-proof.json"
+                }
+              ]
+            },
+            "missingArtifactsMessage": {
+              "const": "The Claude example flow requires Claude to write the fixed proof artifact."
+            }
+          },
+          "expect": [
+            {
+              "kind": "require-artifacts",
+              "paths": {
+                "list": [
+                  {
+                    "const": ".agentweaver/.artifacts/examples/claude-example-proof.json"
+                  }
+                ]
+              },
+              "message": "The Claude example flow must write the fixed proof artifact."
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/docs/examples/.plugins/claude-example-plugin/index.js

@@ -0,0 +1,149 @@
+import { AGENTWEAVER_PLUGIN_SDK_VERSION } from "agentweaver/plugin-sdk";
+
+export const CLAUDE_EXAMPLE_PLUGIN_SDK_VERSION = AGENTWEAVER_PLUGIN_SDK_VERSION;
+export const CLAUDE_EXECUTOR_ID = "claude";
+export const CLAUDE_AUTH_STATUS_ERROR = "Claude CLI authentication is required. Run 'claude auth status' and sign in before using the example flow.";
+export const CLAUDE_NORMALIZATION_ERROR =
+  "Claude JSON normalization failed: no supported assistant text was found in result, message.content[*].text, or content[*].text.";
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function resolveSetting(override, env, envKey, defaultValue) {
+  const direct = nonEmptyString(typeof override === "number" ? String(override) : override);
+  if (direct) {
+    return direct;
+  }
+  const fromEnv = nonEmptyString(env?.[envKey]);
+  if (fromEnv) {
+    return fromEnv;
+  }
+  return nonEmptyString(defaultValue);
+}
+
+function resolveStringListSetting(override, env, envKey, defaultValue) {
+  const direct = nonEmptyString(override);
+  const envValue = nonEmptyString(env?.[envKey]);
+  const effective = direct ?? envValue ?? nonEmptyString(defaultValue);
+  if (!effective) {
+    return [];
+  }
+  return effective
+    .split(/[,\s]+/)
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+function extractTextFragments(items) {
+  if (!Array.isArray(items)) {
+    return null;
+  }
+  const fragments = items
+    .map((item) => (item && typeof item === "object" ? item.text : undefined))
+    .filter((text) => typeof text === "string" && text.trim().length > 0);
+  return fragments.length > 0 ? fragments.join("\n") : null;
+}
+
+export function normalizeClaudePayload(payload, effectiveModel = "") {
+  const resultText = nonEmptyString(payload?.result);
+  const messageContentText = extractTextFragments(payload?.message?.content);
+  const contentText = extractTextFragments(payload?.content);
+  const output = resultText ?? messageContentText ?? contentText;
+  if (!output) {
+    throw new Error(CLAUDE_NORMALIZATION_ERROR);
+  }
+  return {
+    output,
+    model: nonEmptyString(payload?.model) ?? effectiveModel,
+    rawResponse: payload,
+  };
+}
+
+export async function verifyClaudeAuth(runtime, env, config) {
+  const command = runtime.resolveCmd(config.defaultCommand, config.commandEnvVar);
+  try {
+    await runtime.runCommand([command, "auth", "status"], {
+      env,
+      label: "claude:auth-status",
+      printFailureOutput: false,
+    });
+  } catch {
+    throw new Error(CLAUDE_AUTH_STATUS_ERROR);
+  }
+  return command;
+}
+
+export const claudeExecutorDefinition = {
+  kind: CLAUDE_EXECUTOR_ID,
+  version: 1,
+  defaultConfig: {
+    commandEnvVar: "CLAUDE_BIN",
+    defaultCommand: "claude",
+    modelEnvVar: "CLAUDE_MODEL",
+    defaultModel: "",
+    maxTurnsEnvVar: "CLAUDE_MAX_TURNS",
+    defaultMaxTurns: "",
+    permissionModeEnvVar: "CLAUDE_PERMISSION_MODE",
+    defaultPermissionMode: "bypassPermissions",
+    allowedToolsEnvVar: "CLAUDE_ALLOWED_TOOLS",
+    defaultAllowedTools: "",
+    disallowedToolsEnvVar: "CLAUDE_DISALLOWED_TOOLS",
+    defaultDisallowedTools: "",
+    addCwdAsAllowedDir: true,
+  },
+  async execute(context, input, config) {
+    const env = input?.env ?? context.env;
+    const command = input?.command ?? context.runtime.resolveCmd(config.defaultCommand, config.commandEnvVar);
+    const effectiveModel = resolveSetting(input?.model, env, config.modelEnvVar, config.defaultModel);
+    const effectiveMaxTurns = resolveSetting(input?.maxTurns, env, config.maxTurnsEnvVar, config.defaultMaxTurns);
+    const permissionMode = resolveSetting(undefined, env, config.permissionModeEnvVar, config.defaultPermissionMode);
+    const allowedTools = resolveStringListSetting(undefined, env, config.allowedToolsEnvVar, config.defaultAllowedTools);
+    const disallowedTools = resolveStringListSetting(undefined, env, config.disallowedToolsEnvVar, config.defaultDisallowedTools);
+    const argv = [
+      command,
+      "-p",
+      String(input?.prompt ?? ""),
+      "--output-format",
+      "json",
+      ...(config.addCwdAsAllowedDir ? ["--add-dir", context.cwd] : []),
+      ...(permissionMode ? ["--permission-mode", permissionMode] : []),
+      ...(allowedTools.length > 0 ? ["--allowedTools", ...allowedTools] : []),
+      ...(disallowedTools.length > 0 ? ["--disallowedTools", ...disallowedTools] : []),
+      ...(effectiveModel ? ["--model", effectiveModel] : []),
+      ...(effectiveMaxTurns ? ["--max-turns", effectiveMaxTurns] : []),
+    ];
+    const stdout = await context.runtime.runCommand(argv, {
+      env,
+      dryRun: context.dryRun,
+      verbose: context.verbose,
+      label: `claude:${effectiveModel || "default"}`,
+      printFailureOutput: true,
+    });
+    let payload;
+    try {
+      payload = JSON.parse(stdout);
+    } catch (error) {
+      throw new Error(`Claude CLI returned invalid JSON: ${error.message}`);
+    }
+    const normalized = normalizeClaudePayload(payload, effectiveModel ?? "");
+    return {
+      output: normalized.output,
+      command,
+      model: normalized.model ?? "",
+      rawResponse: normalized.rawResponse,
+    };
+  },
+};
+
+export const executors = [
+  {
+    id: CLAUDE_EXECUTOR_ID,
+    definition: claudeExecutorDefinition,
+    routing: {
+      kind: "llm",
+      defaultModel: "sonnet",
+      models: ["sonnet", "opus", "haiku"],
+    },
+  },
+];

package/docs/examples/.plugins/claude-example-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "claude-example-plugin",
+  "sdk_version": 1,
+  "entrypoint": "index.js",
+  "name": "Claude Example Plugin",
+  "version": "0.1.0",
+  "description": "Project-local Claude CLI reference plugin for AgentWeaver."
+}

package/docs/features.md

@@ -0,0 +1,77 @@
+# Key Features
+
+AgentWeaver is built around harness engineering: the workflow around the coding agent is explicit, versioned, inspectable, and repeatable. This document expands the key features summarized in the README and points to the deeper reference documents.
+
+## Declarative Agent Workflows
+
+AgentWeaver workflows are JSON flow specs. A flow declares phases, steps, prompt bindings, params, conditions, expected artifacts, and post-step actions. Runtime behavior lives in typed nodes and executors instead of ad-hoc command handlers.
+
+This makes workflows reviewable as source code and lets the same model power direct CLI commands, long-running automation, and the interactive TUI.
+
+Reference: [Declarative Workflows](declarative-workflows.md)
+
+## Project Playbook
+
+The project playbook stores repository-local conventions under `.agentweaver/playbook/`. It contains a manifest, stable practices, examples, templates, and baseline project context.
+
+Guided workflows validate the playbook, select compact phase-specific guidance, and pass that guidance into planning, design review, implementation, review, and repair prompts. This helps repeated agent runs inherit the same project knowledge without copying long instructions into every prompt.
+
+Reference: [Project Playbook](playbook.md)
+
+## Artifact-First Execution
+
+AgentWeaver treats artifacts as the contract between stages. LLM-backed stages write structured JSON artifacts first, then derivative markdown for human reading.
+
+This gives each workflow durable intermediate state: normalized task context, planning questions, design, implementation plan, QA plan, review findings, repair reports, project guidance, and other artifacts can be inspected, validated, reused, or used to resume a run.
+
+## Planning and Design Review
+
+Planning is not only a prompt. The planning flow produces structured design, implementation plan, and QA plan artifacts. `design-review` then critiques those planning artifacts before implementation starts.
+
+For planning-heavy work, `auto-common` can run a design-review loop and iterate through `plan-revise` before coding. This makes implementation less dependent on a single speculative prompt.
+
+## Review and Repair Loops
+
+Review stages produce structured findings with severity levels. Repair stages can use those findings to select blockers and critical issues, build targeted fix prompts, apply changes, and run follow-up checks.
+
+Loop flows such as `review-loop`, `run-go-tests-loop`, and `run-go-linter-loop` make repeated review/fix/check cycles explicit and bounded.
+
+## Resumable Automation
+
+Long-running flows persist compact execution state under `.agentweaver/scopes/<scope>/`. AgentWeaver uses that state with artifacts and launch profile checks to support resume, continue, and restart behavior.
+
+This is especially useful for end-to-end flows such as `auto-common`, `auto-golang`, and review/check loops where restarting from scratch would waste context and work.
+
+## Execution Backends
+
+AgentWeaver routes work through executors. Built-in executors cover Codex, OpenCode, Jira fetch, GitLab diff/review fetch, shell/process checks, Git commit, and Telegram notifications.
+
+Executor configuration is separated from flow specs, so workflows can describe what should happen while runtime profiles decide how work is executed.
+
+## Interactive TUI and Direct CLI
+
+The same flow model works in direct CLI commands and in the interactive terminal UI. The TUI surfaces discovered flows, flow descriptions, active state, progress, and summary artifacts.
+
+This lets operators choose between fast command execution and supervised long-running workflows without changing the underlying flow definitions.
+
+## Custom Flows
+
+Built-in flows live under `src/pipeline/flow-specs/`, while custom flow specs can live under `~/.agentweaver/.flows/` or project-local `.agentweaver/.flows/`.
+
+Custom flows are discovered recursively, validated at load time, and can compose built-in, global, or project-local flows through nested `flow-run` steps.
+
+Reference: [Declarative Workflows](declarative-workflows.md)
+
+## Plugin SDK
+
+Local plugins can add public-SDK-compatible nodes and executors. Plugin manifests declare ids, SDK version, runtime entrypoints, and contributed runtime capabilities.
+
+The loader validates plugin manifests, SDK compatibility, executor definitions, node metadata, and version consistency before plugin contributions become available to flows.
+
+Reference: [Plugin SDK](plugin-sdk.md)
+
+## Operational Diagnostics
+
+The `doctor` command checks readiness before a workflow fails mid-run. It covers system requirements, executor configuration, flow readiness, node versions, current working directory context, AgentWeaver home configuration, and environment diagnostics.
+
+Diagnostics are available as human-readable output or JSON for automation.