agentweaver 0.1.16 → 0.1.17

package/dist/runtime/execution-routing.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { TaskRunnerError } from "../errors.js";
-import { ALLOWED_MODELS_BY_EXECUTOR, DEFAULT_LAUNCH_PROFILE, defaultModelForExecutor, isAllowedModelForExecutor, resolveLaunchProfile, } from "../pipeline/launch-profile-config.js";
+import { allowedModelsForExecutor, DEFAULT_LAUNCH_PROFILE, defaultModelForExecutor, isAllowedModelForExecutor, resolveLaunchProfile, } from "../pipeline/launch-profile-config.js";
 import { BUILT_IN_EXECUTION_PRESET_IDS, EXECUTION_ROUTING_GROUPS, } from "../pipeline/execution-routing-config.js";
 export const BUILT_IN_EXECUTION_PRESETS = {
     balanced: {
@@ -62,12 +62,14 @@ function stableRoutingPayload(routing) {
 export function executionRoutingFingerprint(routing) {
     return createHash("sha256").update(stableRoutingPayload({ ...routing, fingerprint: "" })).digest("hex");
 }
-export function validateExecutionRoute(executor, model) {
-    const allowedModels = ALLOWED_MODELS_BY_EXECUTOR[executor];
-    if (!allowedModels) {
+export function validateExecutionRoute(executor, model, executors) {
+    if (!executors && !isAllowedModelForExecutor(executor, model)) {
         throw new TaskRunnerError(`Unsupported llm executor '${executor}'.`);
     }
-    if (!allowedModels.includes(model)) {
+    if (executors && !executors.getRouting(executor)) {
+        throw new TaskRunnerError(`Unsupported llm executor '${executor}'.`);
+    }
+    if (!isAllowedModelForExecutor(executor, model, executors)) {
         throw new TaskRunnerError(`Model '${model}' is not allowed for executor '${executor}'.`);
     }
 }
@@ -77,25 +79,25 @@ export function toExecutionRouteSelection(route) {
         model: route.model,
     };
 }
-export function resolveExecutionRoute(selection, fallback) {
+export function resolveExecutionRoute(selection, fallback, executors) {
     const launchProfile = resolveLaunchProfile({
         executor: selection.executor,
         model: selection.model,
-    }, fallback);
-    validateExecutionRoute(launchProfile.executor, launchProfile.model);
+    }, fallback, executors);
+    validateExecutionRoute(launchProfile.executor, launchProfile.model, executors);
     return launchProfile;
 }
 export function resolveExecutionRouting(options) {
     const fallbackDefaultRoute = options.fallbackDefaultRoute ?? DEFAULT_LAUNCH_PROFILE;
     const preset = options.presetId ? BUILT_IN_EXECUTION_PRESETS[options.presetId] : null;
     const defaultRouteSelection = options.defaultRoute ?? preset?.defaultRoute ?? toExecutionRouteSelection(fallbackDefaultRoute);
-    const defaultRoute = resolveExecutionRoute(defaultRouteSelection, fallbackDefaultRoute);
+    const defaultRoute = resolveExecutionRoute(defaultRouteSelection, fallbackDefaultRoute, options.executors);
     const groups = Object.fromEntries(EXECUTION_ROUTING_GROUPS.map((group) => {
         const override = options.currentRunOverrides?.[group]
             ?? options.presetOverrides?.[group]
             ?? preset?.groupOverrides?.[group]
             ?? { executor: "default", model: "default" };
-        return [group, resolveExecutionRoute(override, defaultRoute)];
+        return [group, resolveExecutionRoute(override, defaultRoute, options.executors)];
     }));
     const fingerprint = executionRoutingFingerprint({
         defaultRoute,
@@ -143,18 +145,18 @@ export function executorsForRoutingGroups(routing, groups) {
     }
     return requiredExecutors;
 }
-export function normalizeEditableExecutionRouting(routes) {
+export function normalizeEditableExecutionRouting(routes, executors) {
     const normalizedRoutes = {};
     const validationErrors = [];
     for (const group of EXECUTION_ROUTING_GROUPS) {
         const route = routes[group];
-        if (isAllowedModelForExecutor(route.executor, route.model)) {
+        if (isAllowedModelForExecutor(route.executor, route.model, executors)) {
             normalizedRoutes[group] = { ...route };
             continue;
         }
         normalizedRoutes[group] = {
             executor: route.executor,
-            model: defaultModelForExecutor(route.executor),
+            model: defaultModelForExecutor(route.executor, executors),
         };
         validationErrors.push(`${routingGroupLabel(group)} model '${route.model}' is not allowed for executor '${route.executor}'. Select a ${route.executor} model.`);
     }
@@ -184,10 +186,14 @@ export function defaultExecutionRouting() {
         },
     });
 }
-export function resolveStoredExecutionRoutingSnapshot(routing) {
-    validateExecutionRoute(routing.defaultRoute.executor, routing.defaultRoute.model);
+export function resolveStoredExecutionRoutingSnapshot(routing, executors) {
+    if (executors) {
+        validateExecutionRoute(routing.defaultRoute.executor, routing.defaultRoute.model, executors);
+    }
     for (const group of EXECUTION_ROUTING_GROUPS) {
-        validateExecutionRoute(routing.groups[group].executor, routing.groups[group].model);
+        if (executors) {
+            validateExecutionRoute(routing.groups[group].executor, routing.groups[group].model, executors);
+        }
     }
     const fingerprint = executionRoutingFingerprint({
         defaultRoute: routing.defaultRoute,
@@ -218,9 +224,9 @@ export function singleLaunchProfileExecutionRouting(launchProfile) {
         currentRunOverrides: Object.fromEntries(EXECUTION_ROUTING_GROUPS.map((group) => [group, toExecutionRouteSelection(launchProfile)])),
     });
 }
-export function modelOptionsForExecutor(executor) {
-    const defaultModel = defaultModelForExecutor(executor);
-    return ALLOWED_MODELS_BY_EXECUTOR[executor].map((model) => ({
+export function modelOptionsForExecutor(executor, executors) {
+    const defaultModel = defaultModelForExecutor(executor, executors);
+    return allowedModelsForExecutor(executor, executors).map((model) => ({
         value: model,
         label: model === defaultModel ? `${model} [default]` : model,
     }));

package/dist/runtime/interactive-execution-routing.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { flowRoutingGroups, flowRoutingKey } from "../pipeline/flow-catalog.js";
 import { loadNamedDeclarativeFlow } from "../pipeline/declarative-flows.js";
+import { createPipelineRegistryContext } from "../pipeline/plugin-loader.js";
 import { EXECUTION_ROUTING_GROUPS, } from "../pipeline/execution-routing-config.js";
 import { DEFAULT_LAUNCH_PROFILE, defaultModelForExecutor, isAllowedModelForExecutor, } from "../pipeline/launch-profile-config.js";
 import { FlowInterruptedError, TaskRunnerError } from "../errors.js";
@@ -58,15 +59,9 @@ function executionPresetSelectionForm(flowEntry, flowDefaultAvailable, lastUsedA
         ],
     };
 }
-function executorFieldOptions() {
-    return [
-        { value: "codex", label: "codex" },
-        { value: "opencode", label: "opencode" },
-    ];
-}
-function selectedExecutorFromValues(values, fieldId, fallbackExecutor) {
-    const candidate = values[fieldId];
-    return candidate === "codex" || candidate === "opencode" ? candidate : fallbackExecutor;
+function selectedExecutorFromValues(values, fieldId, fallbackExecutor, registryContext) {
+    const candidate = typeof values[fieldId] === "string" ? values[fieldId] : "";
+    return registryContext.executors.getRouting(candidate)?.kind === "llm" ? candidate : fallbackExecutor;
 }
 function routingEditorDraftFromRouting(routing) {
     return {
@@ -83,7 +78,11 @@ function routingEditorDraftFromRouting(routing) {
         ])),
     };
 }
-function advancedRoutingEditorForm(activeGroups, draft, validationMessage) {
+function advancedRoutingEditorForm(activeGroups, draft, registryContext, validationMessage) {
+    const executorOptions = registryContext.executors.llmExecutors().map((entry) => ({
+        value: entry.id,
+        label: entry.id,
+    }));
     const fields = [
         {
             id: "default_route_executor",
@@ -91,7 +90,7 @@ function advancedRoutingEditorForm(activeGroups, draft, validationMessage) {
             label: "Default route executor",
             required: true,
             default: draft.defaultRoute.executor,
-            options: executorFieldOptions(),
+            options: executorOptions,
         },
         {
             id: "default_route_model",
@@ -100,8 +99,8 @@ function advancedRoutingEditorForm(activeGroups, draft, validationMessage) {
             help: "Available models follow the selected default executor.",
             required: true,
             default: draft.defaultRoute.model,
-            options: modelOptionsForExecutor(draft.defaultRoute.executor),
-            optionsFromValues: (values) => modelOptionsForExecutor(selectedExecutorFromValues(values, "default_route_executor", draft.defaultRoute.executor)),
+            options: modelOptionsForExecutor(draft.defaultRoute.executor, registryContext.executors),
+            optionsFromValues: (values) => modelOptionsForExecutor(selectedExecutorFromValues(values, "default_route_executor", draft.defaultRoute.executor, registryContext), registryContext.executors),
         },
         ...activeGroups.flatMap((group) => {
             const route = draft.groups[group];
@@ -112,7 +111,7 @@ function advancedRoutingEditorForm(activeGroups, draft, validationMessage) {
                     label: `${routingGroupLabel(group)} executor`,
                     required: true,
                     default: route.executor,
-                    options: executorFieldOptions(),
+                    options: executorOptions,
                 },
                 {
                     id: `${group}_model`,
@@ -121,8 +120,8 @@ function advancedRoutingEditorForm(activeGroups, draft, validationMessage) {
                     help: `Available models follow the selected ${routingGroupLabel(group)} executor.`,
                     required: true,
                     default: route.model,
-                    options: modelOptionsForExecutor(route.executor),
-                    optionsFromValues: (values) => modelOptionsForExecutor(selectedExecutorFromValues(values, `${group}_executor`, route.executor)),
+                    options: modelOptionsForExecutor(route.executor, registryContext.executors),
+                    optionsFromValues: (values) => modelOptionsForExecutor(selectedExecutorFromValues(values, `${group}_executor`, route.executor, registryContext), registryContext.executors),
                 },
             ];
         }),
@@ -202,8 +201,8 @@ function presetNameForm() {
         ],
     };
 }
-function normalizeEditableRoute(label, route) {
-    if (isAllowedModelForExecutor(route.executor, route.model)) {
+function normalizeEditableRoute(label, route, executors) {
+    if (isAllowedModelForExecutor(route.executor, route.model, executors)) {
         return {
             route: { ...route },
             validationErrors: [],
@@ -212,20 +211,20 @@ function normalizeEditableRoute(label, route) {
     return {
         route: {
             executor: route.executor,
-            model: defaultModelForExecutor(route.executor),
+            model: defaultModelForExecutor(route.executor, executors),
         },
         validationErrors: [
             `${label} model '${route.model}' is not allowed for executor '${route.executor}'. Select a ${route.executor} model.`,
         ],
     };
 }
-function normalizeEditableRoutingDraft(draft) {
-    const defaultRoute = normalizeEditableRoute("Default route", draft.defaultRoute);
+function normalizeEditableRoutingDraft(draft, executors) {
+    const defaultRoute = normalizeEditableRoute("Default route", draft.defaultRoute, executors);
     const groups = {};
     const currentRunOverrides = {};
     const validationErrors = [...defaultRoute.validationErrors];
     for (const group of EXECUTION_ROUTING_GROUPS) {
-        const normalizedRoute = normalizeEditableRoute(routingGroupLabel(group), draft.groups[group]);
+        const normalizedRoute = normalizeEditableRoute(routingGroupLabel(group), draft.groups[group], executors);
         groups[group] = normalizedRoute.route;
         if (normalizedRoute.route.executor !== defaultRoute.route.executor
             || normalizedRoute.route.model !== defaultRoute.route.model) {
@@ -274,40 +273,47 @@ function formatAsciiTable(headers, rows, maxWidths) {
     const separator = `|-${widths.map((width) => "-".repeat(width)).join("-|-")}-|`;
     return [formatRow(headers), separator, ...rows.map((row) => formatRow(row))];
 }
-function collectEffectiveRoutedStepRows(flow, cwd, routing, prefixSegments = [], ancestry = []) {
+function collectEffectiveRoutedStepRows(flow, cwd, routing, registryContext, prefixSegments = [], ancestry = []) {
     if (ancestry.includes(flow.absolutePath)) {
-        return [];
+        return Promise.resolve([]);
     }
     const nextAncestry = [...ancestry, flow.absolutePath];
     const rows = [];
-    for (const phase of flow.phases) {
-        for (const step of phase.steps) {
-            const stepRef = `${phase.id}.${step.id}`;
-            if (step.routingGroup) {
-                const route = routing.groups[step.routingGroup];
-                rows.push({
-                    step: [...prefixSegments, stepRef].join(" > "),
-                    group: routingGroupLabel(step.routingGroup),
-                    executor: route.executor,
-                    model: route.model,
+    const run = async () => {
+        for (const phase of flow.phases) {
+            for (const step of phase.steps) {
+                const stepRef = `${phase.id}.${step.id}`;
+                if (step.routingGroup) {
+                    const route = routing.groups[step.routingGroup];
+                    rows.push({
+                        step: [...prefixSegments, stepRef].join(" > "),
+                        group: routingGroupLabel(step.routingGroup),
+                        executor: route.executor,
+                        model: route.model,
+                    });
+                }
+                if (step.node !== "flow-run") {
+                    continue;
+                }
+                const nestedFlowName = step.params?.fileName;
+                if (!nestedFlowName || !("const" in nestedFlowName) || typeof nestedFlowName.const !== "string") {
+                    continue;
+                }
+                const nestedFlow = await loadNamedDeclarativeFlow(nestedFlowName.const, cwd, {
+                    ...(registryContext ? { registryContext } : {}),
                 });
+                const nestedFlowLabel = path.basename(nestedFlow.fileName, path.extname(nestedFlow.fileName));
+                rows.push(...await collectEffectiveRoutedStepRows(nestedFlow, cwd, routing, registryContext, [...prefixSegments, stepRef, nestedFlowLabel], nextAncestry));
             }
-            if (step.node !== "flow-run") {
-                continue;
-            }
-            const nestedFlowName = step.params?.fileName;
-            if (!nestedFlowName || !("const" in nestedFlowName) || typeof nestedFlowName.const !== "string") {
-                continue;
-            }
-            const nestedFlow = loadNamedDeclarativeFlow(nestedFlowName.const, cwd);
-            const nestedFlowLabel = path.basename(nestedFlow.fileName, path.extname(nestedFlow.fileName));
-            rows.push(...collectEffectiveRoutedStepRows(nestedFlow, cwd, routing, [...prefixSegments, stepRef, nestedFlowLabel], nextAncestry));
         }
-    }
-    return rows;
+        return rows;
+    };
+    return run();
 }
-export function describeEffectiveRoutingPreview(flowEntry, routing, cwd) {
-    const previewGroups = flowRoutingGroups(flowEntry, cwd);
+export async function describeEffectiveRoutingPreview(flowEntry, routing, cwd, registryContext) {
+    const previewGroups = await flowRoutingGroups(flowEntry, cwd, {
+        ...(registryContext ? { registryContext } : {}),
+    });
     const summaryRows = [
         ["Default", routing.defaultRoute.executor, routing.defaultRoute.model],
         ...previewGroups.map((group) => [
@@ -320,7 +326,7 @@ export function describeEffectiveRoutingPreview(flowEntry, routing, cwd) {
         "Effective routes:",
         ...formatAsciiTable(["Scope", "Executor", "Model"], summaryRows, [18, 12, 36]),
     ];
-    const routedSteps = collapseRepeatedEffectiveRoutedStepRows(collectEffectiveRoutedStepRows(flowEntry.flow, cwd, routing));
+    const routedSteps = collapseRepeatedEffectiveRoutedStepRows(await collectEffectiveRoutedStepRows(flowEntry.flow, cwd, routing, registryContext));
     if (routedSteps.length === 0) {
         return lines.join("\n");
     }
@@ -332,7 +338,8 @@ export function describeEffectiveRoutingPreview(flowEntry, routing, cwd) {
     ].join("\n");
 }
 export async function requestInteractiveExecutionRouting(flowEntry, requestUserInput) {
-    const previewGroups = flowRoutingGroups(flowEntry, process.cwd());
+    const registryContext = await createPipelineRegistryContext(process.cwd());
+    const previewGroups = await flowRoutingGroups(flowEntry, process.cwd(), { registryContext });
     const flowKey = flowRoutingKey(flowEntry);
     const namedPresets = getNamedExecutionPresets();
     const flowDefault = getFlowDefaultExecutionRouting(flowKey);
@@ -346,14 +353,14 @@ export async function requestInteractiveExecutionRouting(flowEntry, requestUserI
             throw new TaskRunnerError("Flow default routing is unavailable.");
         }
         selectedPreset = { kind: "flow-default", label: "Flow default" };
-        routing = resolveStoredExecutionRoutingSnapshot(flowDefault.routing);
+        routing = resolveStoredExecutionRoutingSnapshot(flowDefault.routing, registryContext.executors);
     }
     else if (selectedPresetValue === "last-used") {
         if (!lastUsed) {
             throw new TaskRunnerError("Last-used routing is unavailable.");
         }
         selectedPreset = { kind: "last-used", label: "Last used" };
-        routing = resolveStoredExecutionRoutingSnapshot(lastUsed.routing);
+        routing = resolveStoredExecutionRoutingSnapshot(lastUsed.routing, registryContext.executors);
     }
     else if (selectedPresetValue.startsWith("named:")) {
         const presetName = selectedPresetValue.slice("named:".length);
@@ -362,7 +369,7 @@ export async function requestInteractiveExecutionRouting(flowEntry, requestUserI
             throw new TaskRunnerError(`Named preset '${presetName}' is unavailable.`);
         }
         selectedPreset = { kind: "named", presetId: presetName, label: `Named preset: ${presetName}` };
-        routing = resolveStoredExecutionRoutingSnapshot(namedPreset.routing);
+        routing = resolveStoredExecutionRoutingSnapshot(namedPreset.routing, registryContext.executors);
     }
     else if (selectedPresetValue.startsWith("built-in:")) {
         const presetId = selectedPresetValue.slice("built-in:".length);
@@ -371,11 +378,12 @@ export async function requestInteractiveExecutionRouting(flowEntry, requestUserI
             throw new TaskRunnerError(`Unknown execution preset '${presetId}'.`);
         }
         selectedPreset = { kind: "built-in", presetId, label: preset.label };
-        routing = resolveExecutionRouting({ presetId });
+        routing = resolveExecutionRouting({ presetId, executors: registryContext.executors });
     }
     else {
         selectedPreset = { kind: "custom", label: "Custom" };
         routing = resolveExecutionRouting({
+            executors: registryContext.executors,
             defaultRoute: {
                 executor: DEFAULT_LAUNCH_PROFILE.executor,
                 model: DEFAULT_LAUNCH_PROFILE.model,
@@ -385,7 +393,7 @@ export async function requestInteractiveExecutionRouting(flowEntry, requestUserI
     let editorDraft = routingEditorDraftFromRouting(routing);
     let editorValidationMessage;
     for (;;) {
-        const previewText = `Preset: ${selectedPreset.label}\n${describeEffectiveRoutingPreview(flowEntry, routing, process.cwd())}`;
+        const previewText = `Preset: ${selectedPreset.label}\n${await describeEffectiveRoutingPreview(flowEntry, routing, process.cwd(), registryContext)}`;
         const actionResult = await requestUserInput(routingActionForm(previewText));
         const action = String(actionResult.values.action ?? "start");
         if (action === "cancel") {
@@ -395,7 +403,7 @@ export async function requestInteractiveExecutionRouting(flowEntry, requestUserI
             saveLastUsedExecutionRouting(flowKey, routing, selectedPreset);
             return { routing, selectedPreset };
         }
-        const routingFormResult = await requestUserInput(advancedRoutingEditorForm(previewGroups, editorDraft, editorValidationMessage));
+        const routingFormResult = await requestUserInput(advancedRoutingEditorForm(previewGroups, editorDraft, registryContext, editorValidationMessage));
         const requestedDefaultRoute = {
             executor: String(routingFormResult.values.default_route_executor ?? editorDraft.defaultRoute.executor),
             model: String(routingFormResult.values.default_route_model ?? editorDraft.defaultRoute.model),
@@ -418,7 +426,7 @@ export async function requestInteractiveExecutionRouting(flowEntry, requestUserI
                 ];
             })),
         };
-        const normalizedDraft = normalizeEditableRoutingDraft(requestedDraft);
+        const normalizedDraft = normalizeEditableRoutingDraft(requestedDraft, registryContext.executors);
         editorDraft = normalizedDraft.draft;
         if (normalizedDraft.validationErrors.length > 0) {
             editorValidationMessage = normalizedDraft.validationErrors.join("\n");
@@ -426,6 +434,7 @@ export async function requestInteractiveExecutionRouting(flowEntry, requestUserI
         }
         try {
             routing = resolveExecutionRouting({
+                executors: registryContext.executors,
                 defaultRoute: {
                     executor: normalizedDraft.draft.defaultRoute.executor,
                     model: normalizedDraft.draft.defaultRoute.model,

package/docs/example/.flows/examples/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/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."
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}