@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/core/workflow-compiler-host-rules.js

@@ -0,0 +1,266 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Host rules of the authoring-time workflow compiler.
+ * Bindings must name a tool of the selected host profile, human steps must use a transport that
+ * profile renders, script steps carry a command, and destructive steps should depend on approval.
+ */
+import { containsSecretShape } from '../runtime/redaction.js';
+import { findHostTool, HUMAN_TRANSPORT_LIMITS, OPERATOR_HOST_TOOL, } from './workflow-host-profiles.js';
+const APPROVAL_SIDE_EFFECTS = new Set([
+    'local-destructive',
+    'remote-mutating',
+    'credentialed',
+    'irreversible',
+]);
+function checkArgumentKeys(step, schema, report) {
+    const keys = Object.keys(step.arguments_template);
+    const missing = schema.required.filter((key) => !keys.includes(key));
+    const allowed = new Set(Object.keys(schema.properties));
+    const unknown = schema.additionalProperties ? [] : keys.filter((key) => !allowed.has(key));
+    if (missing.length > 0 || unknown.length > 0) {
+        report({
+            level: 'error',
+            code: 'AUTHORING_INVALID',
+            step_id: step.id,
+            path: 'arguments_template',
+            message: `Step ${step.id} arguments for ${step.binding?.host_tool_name} ${[
+                missing.length > 0 ? `miss ${missing.join(', ')}` : '',
+                unknown.length > 0
+                    ? `name unknown ${unknown.join(', ')} (allowed: ${[...allowed].join(', ')})`
+                    : '',
+            ]
+                .filter(Boolean)
+                .join(' and ')}`,
+        });
+    }
+}
+/** Every binding names a tool the profile declares for the step's kind. */
+export function checkBindingsAgainstProfile(definition, resolved, report) {
+    const { profile } = resolved;
+    for (const step of definition.steps) {
+        if (!step.binding)
+            continue;
+        // An absent host_profile means this profile, so the binding is checked here rather than skipped.
+        if (step.binding.host_profile !== undefined && step.binding.host_profile !== profile.name)
+            continue;
+        const tool = findHostTool(profile, step.binding.host_tool_name);
+        const kind = step.kind;
+        if (!tool?.kinds.includes(kind)) {
+            const offered = profile.tools
+                .filter((candidate) => candidate.kinds.includes(kind))
+                .map((candidate) => candidate.host_tool_name);
+            report({
+                level: 'error',
+                code: 'BINDING_UNAVAILABLE',
+                step_id: step.id,
+                path: 'binding.host_tool_name',
+                message: `Step ${step.id} binds ${step.binding.host_tool_name}, which host profile ${profile.name} (${resolved.source}) does not declare for ${step.kind} steps; declared: ${offered.join(', ') || 'none'}`,
+            });
+            continue;
+        }
+        if (tool.argument_schema)
+            checkArgumentKeys(step, tool.argument_schema, report);
+    }
+}
+/**
+ * Resolve the transport of every human step for the profile. The authored transport must be the
+ * profile's or `conversation`; `on_unavailable: declared-fallback` falls back to `conversation`.
+ */
+export function resolveHumanTransports(definition, resolved, report) {
+    const transports = {};
+    for (const step of definition.steps) {
+        const human = step.human;
+        if (!human)
+            continue;
+        const profileTransport = resolved?.profile.human_transport;
+        let transport = human.transport ?? profileTransport ?? 'conversation';
+        if (profileTransport && transport !== profileTransport && transport !== 'conversation') {
+            if (human.on_unavailable === 'declared-fallback') {
+                transport = 'conversation';
+            }
+            else {
+                report({
+                    level: 'error',
+                    code: 'HOST_PROFILE_MISMATCH',
+                    step_id: step.id,
+                    path: 'human.transport',
+                    message: `Step ${step.id} uses transport ${human.transport}, but host profile ${resolved?.profile.name} renders human steps with ${profileTransport}; use ${profileTransport} or conversation, omit transport, or set on_unavailable: declared-fallback`,
+                });
+            }
+        }
+        const limits = HUMAN_TRANSPORT_LIMITS[transport];
+        if (human.options.length < limits.min || human.options.length > limits.max) {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path: 'human.options',
+                message: `Step ${step.id} offers ${human.options.length} options; transport ${transport} takes ${limits.min} to ${limits.max}`,
+            });
+        }
+        transports[step.id] = transport;
+    }
+    return transports;
+}
+export function checkScriptSteps(definition, report) {
+    for (const step of definition.steps) {
+        const isShell = step.kind === 'script' || (step.kind === 'cleanup' && step.script);
+        if (isShell && typeof step.arguments_template.command !== 'string') {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path: 'arguments_template.command',
+                message: `Script step ${step.id} needs arguments_template.command as a string`,
+            });
+        }
+        if (step.script && step.kind !== 'script' && step.kind !== 'cleanup') {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path: 'script',
+                message: `Step ${step.id} is ${step.kind}; a script contract belongs to script or cleanup steps`,
+            });
+        }
+    }
+}
+/** Warn when a destructive, mutating, credentialed, or irreversible step has no approval dependency. */
+export function checkApprovalDependencies(definition, report) {
+    const byId = new Map(definition.steps.map((step) => [step.id, step]));
+    for (const step of definition.steps) {
+        if (step.kind === 'cleanup' || !APPROVAL_SIDE_EFFECTS.has(step.side_effect))
+            continue;
+        const approved = step.depends_on.some((dependency) => byId.get(dependency)?.human?.interaction === 'approval');
+        if (!approved) {
+            report({
+                level: 'warning',
+                code: 'APPROVAL_MISSING',
+                step_id: step.id,
+                path: 'depends_on',
+                message: `Step ${step.id} is ${step.side_effect} but depends on no approval step; a run refuses to dispatch it (POLICY_DENIED) until such a dependency answers PASS`,
+            });
+        }
+    }
+}
+function literalSecretPaths(value, path) {
+    if (typeof value === 'string') {
+        const literal = value.replace(/\$\{[^}]*\}/g, '');
+        return containsSecretShape(literal) ? [path] : [];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((entry, index) => literalSecretPaths(entry, `${path}.${index}`));
+    }
+    if (value && typeof value === 'object') {
+        return Object.entries(value).flatMap(([key, nested]) => literalSecretPaths(nested, `${path}.${key}`));
+    }
+    return [];
+}
+/** Predicate kinds that can only be judged from a structured tool result. */
+const OUTPUT_ONLY_PREDICATE_KINDS = new Set([
+    'schema-valid',
+    'json-path-equals',
+    'playwright-assertion',
+]);
+/**
+ * Output fields only a tool receipt carries. An observation reports `status`, the observation text,
+ * an error text and artifacts — it has no exit code and no parsed JSON, so a predicate pointed at
+ * one of these has nothing to read and would evaluate the same way whatever the executor reported.
+ */
+const RECEIPT_ONLY_OUTPUT_FIELDS = new Set([
+    'exit_code',
+    'json',
+    'stdout',
+    'stderr',
+    'response',
+]);
+/** Path segments of a subject selector, so `outputs.check.exit_code` yields its last segment. */
+function pathSegments(value) {
+    return value.split(/[^A-Za-z0-9_]+/).filter((segment) => segment.length > 0);
+}
+/**
+ * The receipt-only field a predicate reads, if any. Looked for in the `target` selector and inside
+ * every `${…}` template in its parameters, which is the other way a parameter reaches an output.
+ */
+function receiptOnlyReference(parameters) {
+    const target = parameters.target;
+    if (typeof target === 'string') {
+        const hit = pathSegments(target).find((segment) => RECEIPT_ONLY_OUTPUT_FIELDS.has(segment));
+        if (hit)
+            return hit;
+    }
+    const templates = [];
+    const collect = (value) => {
+        if (typeof value === 'string') {
+            for (const match of value.matchAll(/\$\{([^}]*)\}/g))
+                templates.push(match[1] ?? '');
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                collect(entry);
+            return;
+        }
+        if (value && typeof value === 'object')
+            for (const entry of Object.values(value))
+                collect(entry);
+    };
+    collect(parameters);
+    for (const template of templates) {
+        const hit = pathSegments(template).find((segment) => RECEIPT_ONLY_OUTPUT_FIELDS.has(segment));
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/**
+ * A step the executor discharges by reporting what they observed has no structured tool output, so
+ * a predicate that can only read such output is refused while the guide is written rather than
+ * failing halfway through a run. Two ways a predicate gives itself away: its kind can only judge a
+ * structured result, or it points at a field only a receipt carries. The kind alone is not enough —
+ * `number-compare` is harmless until it targets `outputs.<step>.exit_code`.
+ */
+export function checkExecutorPredicates(definition, report) {
+    const byId = new Map(definition.predicates.map((predicate) => [predicate.id, predicate]));
+    for (const step of definition.steps) {
+        if (step.binding?.host_tool_name !== OPERATOR_HOST_TOOL)
+            continue;
+        for (const id of step.expected_results) {
+            const predicate = byId.get(id);
+            if (!predicate)
+                continue;
+            const reason = OUTPUT_ONLY_PREDICATE_KINDS.has(predicate.kind)
+                ? `of kind ${predicate.kind} can only judge a structured tool result`
+                : (() => {
+                    const field = receiptOnlyReference(predicate.parameters);
+                    return field ? `reads ${field}, which only a tool receipt carries` : undefined;
+                })();
+            if (!reason)
+                continue;
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path: 'expected_results',
+                message: `Step ${step.id} is carried out by the executor and reported as an observation, so predicate ${id} ${reason}; judge the reported observation instead, or bind a real host tool`,
+            });
+        }
+    }
+}
+/** A secret written into a template is an authoring error; pass it as a secret-reference variable. */
+export function checkSecretLiterals(definition, report) {
+    for (const step of definition.steps) {
+        for (const path of literalSecretPaths(step.arguments_template, 'arguments_template')) {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path,
+                message: `Step ${step.id} has a secret-shaped literal at ${path}; declare a secret-reference variable and reference it as \${variables.<name>}`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=workflow-compiler-host-rules.js.map

package/dist/core/workflow-compiler-host-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-host-rules.js","sourceRoot":"","sources":["../../src/core/workflow-compiler-host-rules.ts"],"names":[],"mappings":"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"}

package/dist/core/workflow-compiler-loop-rules.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Authoring rule for route loops (TASK-1024). A route back to the step itself or to an earlier
+ * step repeats that stretch of the guide, and only the target's `max_passes` ends the loop in
+ * FAIL; without it the loop runs until the operator stops the run, so the compiler warns.
+ * @see TASK-1024
+ */
+import type { WorkflowDefinitionV2 as WorkflowDefinition } from '../schemas/workflow-definition-v2.js';
+import type { DiagnosticSink } from './workflow-compiler-rules.js';
+export declare function checkLoopBounds(definition: WorkflowDefinition, report: DiagnosticSink): void;
+//# sourceMappingURL=workflow-compiler-loop-rules.d.ts.map

package/dist/core/workflow-compiler-loop-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-loop-rules.d.ts","sourceRoot":"","sources":["../../src/core/workflow-compiler-loop-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,oBAAoB,IAAI,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AACvG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAInE,wBAAgB,eAAe,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAiB5F"}

package/dist/core/workflow-compiler-loop-rules.js

@@ -0,0 +1,31 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Authoring rule for route loops (TASK-1024). A route back to the step itself or to an earlier
+ * step repeats that stretch of the guide, and only the target's `max_passes` ends the loop in
+ * FAIL; without it the loop runs until the operator stops the run, so the compiler warns.
+ * @see TASK-1024
+ */
+const SLOTS = ['pass', 'fail', 'error'];
+export function checkLoopBounds(definition, report) {
+    const positions = new Map(definition.steps.map((step, position) => [step.id, position]));
+    for (const [position, step] of definition.steps.entries()) {
+        for (const slot of SLOTS) {
+            const targetId = step.on[slot];
+            const target = positions.get(targetId);
+            if (target === undefined || target > position)
+                continue;
+            if (definition.steps[target]?.max_passes !== undefined)
+                continue;
+            report({
+                level: 'warning',
+                code: 'UNBOUNDED_LOOP',
+                step_id: step.id,
+                path: `on.${slot}`,
+                message: `Step ${step.id} routes ${slot} back to step ${targetId}, which has no max_passes; give ${targetId} max_passes so the loop ends in FAIL instead of running until the operator stops it`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=workflow-compiler-loop-rules.js.map

package/dist/core/workflow-compiler-loop-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-loop-rules.js","sourceRoot":"","sources":["../../src/core/workflow-compiler-loop-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAEjD,MAAM,UAAU,eAAe,CAAC,UAA8B,EAAE,MAAsB;IACpF,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACzF,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC1D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YAC/B,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACvC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,QAAQ;gBAAE,SAAS;YACxD,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,UAAU,KAAK,SAAS;gBAAE,SAAS;YACjE,MAAM,CAAC;gBACL,KAAK,EAAE,SAAS;gBAChB,IAAI,EAAE,gBAAgB;gBACtB,OAAO,EAAE,IAAI,CAAC,EAAE;gBAChB,IAAI,EAAE,MAAM,IAAI,EAAE;gBAClB,OAAO,EAAE,QAAQ,IAAI,CAAC,EAAE,WAAW,IAAI,iBAAiB,QAAQ,mCAAmC,QAAQ,qFAAqF;aACjM,CAAC,CAAC;QACL,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/core/workflow-compiler-optional-rules.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Authoring rules for optional steps. A host may skip an optional step (BUG-144), so the
+ * compiler refuses what a skip would break at run time: a cleanup is owed and never optional,
+ * and no other step may read the outputs of a step that might not have run. An optional
+ * approval is allowed but warned about, because skipping it denies every step that needs it.
+ * @see BUG-144
+ */
+import type { WorkflowDefinitionV2 as WorkflowDefinition } from '../schemas/workflow-definition-v2.js';
+import type { DiagnosticSink } from './workflow-compiler-rules.js';
+export declare function checkOptionalSteps(definition: WorkflowDefinition, report: DiagnosticSink): void;
+//# sourceMappingURL=workflow-compiler-optional-rules.d.ts.map

package/dist/core/workflow-compiler-optional-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-optional-rules.d.ts","sourceRoot":"","sources":["../../src/core/workflow-compiler-optional-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,oBAAoB,IAAI,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AACvG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAiCnE,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CA+B/F"}

package/dist/core/workflow-compiler-optional-rules.js

@@ -0,0 +1,76 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Authoring rules for optional steps. A host may skip an optional step (BUG-144), so the
+ * compiler refuses what a skip would break at run time: a cleanup is owed and never optional,
+ * and no other step may read the outputs of a step that might not have run. An optional
+ * approval is allowed but warned about, because skipping it denies every step that needs it.
+ * @see BUG-144
+ */
+const OUTPUT_TEMPLATE = /\$\{outputs\.([a-z][a-z0-9_-]*)[.}]/g;
+const OUTPUT_TARGET = /^outputs\.([a-z][a-z0-9_-]*)(?:\.|$)/;
+/** Every string anywhere inside a value, depth first. */
+function stringsOf(value, into = []) {
+    if (typeof value === 'string')
+        into.push(value);
+    else if (Array.isArray(value))
+        for (const entry of value)
+            stringsOf(entry, into);
+    else if (value && typeof value === 'object') {
+        for (const entry of Object.values(value))
+            stringsOf(entry, into);
+    }
+    return into;
+}
+/** The IDs of the steps whose outputs the step reads: its templates and its predicates' targets. */
+function outputsReadBy(definition, step) {
+    const read = new Set();
+    for (const text of stringsOf(step)) {
+        for (const match of text.matchAll(OUTPUT_TEMPLATE))
+            read.add(match[1]);
+    }
+    const predicates = new Map(definition.predicates.map((predicate) => [predicate.id, predicate]));
+    for (const id of step.expected_results) {
+        const target = predicates.get(id)?.parameters.target;
+        const match = typeof target === 'string' ? OUTPUT_TARGET.exec(target) : null;
+        if (match)
+            read.add(match[1]);
+    }
+    read.delete(step.id);
+    return read;
+}
+export function checkOptionalSteps(definition, report) {
+    const optional = new Set(definition.steps.filter((step) => step.optional).map((s) => s.id));
+    for (const step of definition.steps) {
+        if (step.optional && step.kind === 'cleanup') {
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path: 'optional',
+                message: `Cleanup step ${step.id} cannot be optional; a cleanup the run owes is never skipped`,
+            });
+        }
+        if (step.optional && step.human?.interaction === 'approval') {
+            report({
+                level: 'warning',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path: 'optional',
+                message: `Approval step ${step.id} is optional; skipping it denies every step that needs its approval`,
+            });
+        }
+        for (const read of outputsReadBy(definition, step)) {
+            if (!optional.has(read))
+                continue;
+            report({
+                level: 'error',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                message: `Optional step ${read} is read by ${step.id}; a skipped step leaves no outputs to read`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=workflow-compiler-optional-rules.js.map

package/dist/core/workflow-compiler-optional-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-optional-rules.js","sourceRoot":"","sources":["../../src/core/workflow-compiler-optional-rules.ts"],"names":[],"mappings":"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"}

package/dist/core/workflow-compiler-party-rules.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Party rules of the authoring-time workflow compiler (STORY-503). A step's `who` decides its
+ * party in every run mode (BUG-207). The guide view lets the operator carry out a step bound to
+ * an agent tool only by running its command in a local terminal, so `who: operator` on a step it
+ * cannot run leaves the operator a step they cannot record. That is a warning, as is a `who`
+ * without effect: on a predicate step, which the runtime judges, and `agent` on a question,
+ * which the operator answers.
+ *
+ * One step, one party (BUG-206): a step whose title or instruction has the other party act mixes
+ * two parties' work, which belongs in two steps. The check is a word heuristic and only warns:
+ * the other party named as the subject of a verb ("Claude builds", "the operator opens", "der
+ * Operator baut"), addressed ("Claude: …"), or handed the work ("ask the operator to", "let
+ * Claude"). Naming them as a recipient ("report it to Claude", "tell the operator"), in a purpose
+ * clause ("so that Claude …") or in a condition ("only when Claude names …") is no mix.
+ */
+import type { WorkflowDefinitionV2 as WorkflowDefinition } from '../schemas/workflow-definition-v2.js';
+import type { DiagnosticSink } from './workflow-compiler-rules.js';
+export declare function checkStepParties(definition: WorkflowDefinition, report: DiagnosticSink): void;
+//# sourceMappingURL=workflow-compiler-party-rules.d.ts.map

package/dist/core/workflow-compiler-party-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-party-rules.d.ts","sourceRoot":"","sources":["../../src/core/workflow-compiler-party-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,oBAAoB,IAAI,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAEvG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAkHnE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAqB7F"}

package/dist/core/workflow-compiler-party-rules.js

@@ -0,0 +1,146 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Party rules of the authoring-time workflow compiler (STORY-503). A step's `who` decides its
+ * party in every run mode (BUG-207). The guide view lets the operator carry out a step bound to
+ * an agent tool only by running its command in a local terminal, so `who: operator` on a step it
+ * cannot run leaves the operator a step they cannot record. That is a warning, as is a `who`
+ * without effect: on a predicate step, which the runtime judges, and `agent` on a question,
+ * which the operator answers.
+ *
+ * One step, one party (BUG-206): a step whose title or instruction has the other party act mixes
+ * two parties' work, which belongs in two steps. The check is a word heuristic and only warns:
+ * the other party named as the subject of a verb ("Claude builds", "the operator opens", "der
+ * Operator baut"), addressed ("Claude: …"), or handed the work ("ask the operator to", "let
+ * Claude"). Naming them as a recipient ("report it to Claude", "tell the operator"), in a purpose
+ * clause ("so that Claude …") or in a condition ("only when Claude names …") is no mix.
+ */
+import { defaultAssignee, workflowStepChannel } from '../runtime/workflow-v2-parties.js';
+import { OPERATOR_HOST_TOOL, TERMINAL_HOST_TOOLS } from './workflow-host-profiles.js';
+/**
+ * How a step's text names each party. "The agent" and "the user" are left out, because a guide
+ * uses them for the product's own agents and accounts too.
+ */
+const PARTY_NAMES = {
+    agent: /\b(?:Claude|Copilot|the AI|the assistant|die KI)\b/giu,
+    operator: /\b(?:the operator|the product owner|der Operator|die Operatorin|der Bediener)\b/giu,
+};
+/** Words before the name that make the party a recipient or the subject of a purpose clause. */
+const NOT_ACTING_AFTER = new Set([
+    ...['to', 'tell', 'inform', 'notify', 'show', 'send', 'give', 'ask', 'for', 'from', 'with'],
+    ...['by', 'about', 'that', 'so', 'when', 'if', 'once', 'after', 'before', 'until', 'unless'],
+    ...['while', 'whether', 'an', 'für', 'von', 'mit', 'zu', 'dass', 'damit', 'sodass', 'wenn'],
+    ...['falls', 'sobald', 'nachdem', 'bevor', 'bis', 'während', 'ob', 'frag', 'frage', 'sag'],
+    ...['sage', 'zeig', 'zeige', 'melde', 'schick', 'schicke', 'gib', 'informiere'],
+]);
+/** Words before the name that hand it the work: these always, `ask` and `get` before "to". */
+const DELEGATING = new Set(['let', 'have', 'lass', 'lassen']);
+const DELEGATING_TO = new Set(['ask', 'get']);
+/** Words after the name that make it the actor although they end in neither s nor t. */
+const ACTING_WORDS = new Set(['will', 'must', 'should', 'shall', 'then', 'now', 'first']);
+/** Words of four letters or more after the name that end in s or t but describe instead of act. */
+const DESCRIBING_WORDS = new Set([
+    ...['this', 'thus', 'that', 'just', 'about', 'built', 'sent', 'left', 'next', 'last', 'most'],
+    ...['sees', 'gets', 'knows', 'needs', 'wants', 'waits', 'plus', 'less', 'across', 'against'],
+    ...['almost', 'chat', 'sessions', 'settings', 'nicht', 'nichts', 'sieht', 'erhält', 'bekommt'],
+    ...['wartet', 'braucht', 'erneut', 'bereits', 'etwas', 'jetzt', 'selbst', 'seit', 'dort'],
+    ...['erst', 'sonst', 'meist'],
+]);
+/** Why the guide view cannot run the step's command for the operator, if it cannot. */
+function unrunnableReason(step, remote) {
+    if (step.section !== undefined && remote.has(step.section)) {
+        return `its section ${step.section} is remote, so the guide view only copies the command`;
+    }
+    const tool = step.binding?.host_tool_name;
+    if (!tool || !TERMINAL_HOST_TOOLS.has(tool)) {
+        return `the guide view runs only ${[...TERMINAL_HOST_TOOLS].join(', ')} commands, and the step binds ${tool ?? 'no tool'}`;
+    }
+    if (typeof step.arguments_template.command !== 'string') {
+        return 'it has no arguments_template.command the guide view could run';
+    }
+    return undefined;
+}
+/** The warning a step's `who` earns, if any. */
+function partyWarning(step, remote) {
+    if (step.kind === 'predicate') {
+        return `Step ${step.id} is a predicate step, which the runtime judges; who has no effect`;
+    }
+    if (step.kind === 'human') {
+        return step.who === 'agent'
+            ? `Step ${step.id} is a question, which the operator answers; who: agent has no effect`
+            : undefined;
+    }
+    if (step.who !== 'operator' || step.binding?.host_tool_name === OPERATOR_HOST_TOOL) {
+        return undefined;
+    }
+    const reason = unrunnableReason(step, remote);
+    return reason
+        ? `Step ${step.id} names who: operator, but ${reason}; bind it to the operator tool (host_tool_name "${OPERATOR_HOST_TOOL}") so the operator reports what they saw, or leave it to the agent`
+        : undefined;
+}
+/** The words where the text first has the party act, if it does. */
+function actingExcerpt(text, party) {
+    for (const match of text.matchAll(PARTY_NAMES[party])) {
+        const end = match.index + match[0].length;
+        const before = /(\p{L}+)[\s,]*$/u.exec(text.slice(0, match.index));
+        const after = /^(?:\s+(\p{L}+)|\s*:)/u.exec(text.slice(end));
+        const prior = before?.[1]?.toLowerCase() ?? '';
+        const next = after?.[1]?.toLowerCase();
+        const handed = DELEGATING.has(prior) || (DELEGATING_TO.has(prior) && next === 'to');
+        const acting = after !== null &&
+            !NOT_ACTING_AFTER.has(prior) &&
+            (next === undefined ||
+                ACTING_WORDS.has(next) ||
+                (next.length >= 4 && /[st]$/u.test(next) && !DESCRIBING_WORDS.has(next)));
+        if (handed || acting) {
+            const from = handed && before ? before.index : match.index;
+            return text.slice(from, end + (after?.[0].length ?? 0)).trim();
+        }
+    }
+    return undefined;
+}
+/** One step, one party: a warning on the first directive text that has the other party act. */
+function mixedPartyWarning(step) {
+    if (step.kind === 'predicate')
+        return undefined;
+    const party = defaultAssignee('together', workflowStepChannel(step), step.who);
+    const other = party === 'operator' ? 'agent' : 'operator';
+    const texts = [
+        ['title', step.title],
+        ['instruction', step.instruction],
+        ['human.instruction', step.human?.instruction],
+    ];
+    for (const [path, text] of texts) {
+        const excerpt = text ? actingExcerpt(text, other) : undefined;
+        if (excerpt) {
+            return {
+                path,
+                message: `A together run gives step ${step.id} to the ${party}, but its ${path} has the ${other} act ("${excerpt}"); split it into one step per party in the order they act, each with its own who`,
+            };
+        }
+    }
+    return undefined;
+}
+export function checkStepParties(definition, report) {
+    const remote = new Set((definition.sections ?? []).filter((section) => section.remote).map((section) => section.id));
+    for (const step of definition.steps) {
+        const mixed = mixedPartyWarning(step);
+        if (mixed) {
+            report({ level: 'warning', code: 'AUTHORING_INVALID', step_id: step.id, ...mixed });
+        }
+        if (step.who === undefined)
+            continue;
+        const message = partyWarning(step, remote);
+        if (message) {
+            report({
+                level: 'warning',
+                code: 'AUTHORING_INVALID',
+                step_id: step.id,
+                path: 'who',
+                message,
+            });
+        }
+    }
+}
+//# sourceMappingURL=workflow-compiler-party-rules.js.map

package/dist/core/workflow-compiler-party-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-compiler-party-rules.js","sourceRoot":"","sources":["../../src/core/workflow-compiler-party-rules.ts"],"names":[],"mappings":"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"}