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

package/dist/runtime/workflow-v2-human-response.js

@@ -0,0 +1,133 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Human responses on compiled workflow runs.
+ * Maps the operator's answer through `response_mapping`, applies the negative-answer evidence
+ * rule, and routes; a declined required step carries HUMAN_DECLINED.
+ */
+import { normalizeEvidence } from './evidence.js';
+import { redactValue } from './redaction.js';
+import { fieldEvidence, fieldOutput, validateStepFields, } from './workflow-v2-fields.js';
+import { mapHumanAnswer } from './workflow-v2-human.js';
+import { advanceWorkflowCursor, answerRoute, resolveWorkflowRoute, } from './workflow-v2-routing.js';
+import { workflowV2Event } from './workflow-v2-run.js';
+import { WorkflowRunV2Error, } from './workflow-v2-types.js';
+function verifyResponse(dispatch, response) {
+    if (response.step_id !== dispatch.step_id) {
+        throw new WorkflowRunV2Error('PROTOCOL_ERROR', `human_response is for step ${response.step_id} but the run dispatched ${dispatch.step_id}`);
+    }
+    if (dispatch.kind !== 'human') {
+        throw new WorkflowRunV2Error('PROTOCOL_ERROR', `Step ${dispatch.step_id} is a ${dispatch.kind} step; record it with receipt, not human_response`);
+    }
+    if (response.dispatch_digest !== dispatch.dispatch_digest) {
+        throw new WorkflowRunV2Error('PARAMETER_MUTATION', `human_response for step ${dispatch.step_id} echoes another dispatch_digest; answer the question of the current dispatch`, { mismatched: ['dispatch_digest'] });
+    }
+}
+function routeOf(manifest, step, verdict, attempt, passes) {
+    if (verdict === 'CANCELLED')
+        return answerRoute('CANCELLED');
+    const slot = verdict === 'PASS' ? 'pass' : verdict === 'FAIL' ? 'fail' : 'error';
+    const declined = slot === 'fail' && step.human?.required !== false ? 'HUMAN_DECLINED' : undefined;
+    return resolveWorkflowRoute(manifest.definition, step, slot, attempt, declined, passes);
+}
+function humanPayload(step, dispatch, response, input, outcome) {
+    const { mapped, route, nextRun, fields } = outcome;
+    const human = step.human;
+    return {
+        protocol: 'workflow-v2',
+        step_id: step.id,
+        kind: step.kind,
+        attempt: dispatch.attempt,
+        host_tool_name: dispatch.host_tool_name,
+        arguments: dispatch.arguments,
+        side_effect: step.side_effect,
+        dispatch_digest: dispatch.dispatch_digest,
+        request_digest: input.requestDigest,
+        status: 'succeeded',
+        outcome: route.slot === 'pass' ? 'recorded' : route.slot === 'fail' ? 'failed' : 'inconclusive',
+        ...(route.error_code ? { error_code: route.error_code } : {}),
+        predicates: [],
+        route,
+        pending_verdict: nextRun.pending_verdict ?? null,
+        human_answer: {
+            interaction: human?.interaction,
+            transport: dispatch.human?.transport,
+            instruction: dispatch.human?.instruction,
+            ...(mapped.option ? { option: mapped.option } : {}),
+            ...(mapped.freeform ? { freeform: mapped.freeform } : {}),
+            verdict: mapped.verdict,
+            observation: response.observation,
+            evidence: normalizeEvidence(response.evidence, `${step.id}-${dispatch.attempt}`, input.occurredAt),
+        },
+        artifacts: [],
+        ...(fields.length > 0 ? { fields } : {}),
+    };
+}
+/** Apply the operator's answer to the dispatched human step. */
+export function applyHumanResponse(manifest, run, dispatch, step, response, input) {
+    verifyResponse(dispatch, response);
+    const human = step.human;
+    if (!human) {
+        throw new WorkflowRunV2Error('AUTHORING_INVALID', `Step ${step.id} has no human contract`);
+    }
+    const mapped = mapHumanAnswer(human, response);
+    if ('error' in mapped)
+        throw new WorkflowRunV2Error('INPUT_INVALID', mapped.error);
+    if (mapped.verdict === 'FAIL' &&
+        human.interaction !== 'approval' &&
+        response.evidence.length === 0) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', `A negative answer to ${human.interaction} step ${step.id} needs at least one evidence entry describing what was observed`);
+    }
+    const fields = validateStepFields(step, response.fields, mapped.verdict === 'PASS');
+    const route = routeOf(manifest, step, mapped.verdict, dispatch.attempt, run.step_attempts ?? {});
+    const output = {
+        attempt: dispatch.attempt,
+        status: 'succeeded',
+        verdict: mapped.verdict,
+        slot: route.slot,
+        ...(mapped.option ? { option: mapped.option } : {}),
+        ...(mapped.freeform ? { freeform: redactValue(mapped.freeform) } : {}),
+        // The operator's words beside a chosen option (BUG-158), so the run shows why.
+        ...(response.observation.trim()
+            ? { observation: redactValue(response.observation.trim()) }
+            : {}),
+        ...(route.error_code ? { error_code: route.error_code } : {}),
+        ...redactValue(fieldOutput(fields)),
+    };
+    const advanced = advanceWorkflowCursor(manifest.definition, run, step, output, route);
+    const nextRun = {
+        ...advanced,
+        version: run.version + 1,
+        updated_at: input.occurredAt,
+    };
+    const payload = humanPayload(step, dispatch, response, input, {
+        mapped,
+        route,
+        nextRun,
+        fields,
+    });
+    const redacted = redactValue(payload);
+    const declared = fieldEvidence(step.id, fields, {
+        attempt: dispatch.attempt,
+        sequence: run.version,
+        capturedAt: input.occurredAt,
+    });
+    if (declared.entries.length > 0)
+        redacted.evidence = declared.entries;
+    return {
+        run: nextRun,
+        event: workflowV2Event(run, {
+            type: step.id,
+            actor: input.actor,
+            actorName: input.actorName,
+            toState: nextRun.state,
+            payload: redacted,
+            idempotencyKey: input.idempotencyKey,
+            occurredAt: input.occurredAt,
+        }),
+        route,
+        evidenceFiles: declared.files,
+    };
+}
+//# sourceMappingURL=workflow-v2-human-response.js.map

package/dist/runtime/workflow-v2-human-response.js.map

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

package/dist/runtime/workflow-v2-human.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Human steps of compiled workflows: transport rendering and response mapping.
+ * The host renders exactly the returned question; the runtime maps the answer to a verdict.
+ */
+import type { WorkflowExecutionManifest } from '../core/workflow-compiler.js';
+import type { WorkflowHumanStep, WorkflowHumanTransport, WorkflowStep, WorkflowVerdict } from '../schemas/workflow-definition-v2.js';
+export type HumanDispatchContract = Readonly<{
+    /** The step's rendered title (TASK-910); the question's header when present (BUG-160). */
+    title?: string;
+    interaction: WorkflowHumanStep['interaction'];
+    transport: WorkflowHumanTransport;
+    instruction: string;
+    expected_observation?: string;
+    options: readonly string[];
+    allow_freeform: boolean;
+    required: boolean;
+    response_mapping: Readonly<Record<string, WorkflowVerdict>>;
+}>;
+/** The transport the compiler resolved for the step; the authored value is the fallback. */
+export declare function humanTransportOf(manifest: WorkflowExecutionManifest, step: WorkflowStep): WorkflowHumanTransport;
+/**
+ * The human contract of a step, rendered with `render`. The run path renders from the run, a dry
+ * run from the caller's variables and outputs; both resolve the transport the compiler chose.
+ */
+export declare function humanDispatchContract(manifest: WorkflowExecutionManifest, step: WorkflowStep, render: (text: string) => string): HumanDispatchContract | undefined;
+/** Arguments of the host tool that renders the question for the resolved transport. */
+export declare function humanTransportArguments(stepId: string, contract: HumanDispatchContract): Record<string, unknown>;
+export type MappedHumanAnswer = Readonly<{
+    option?: string;
+    freeform?: string;
+    verdict: WorkflowVerdict;
+}>;
+/**
+ * Match the answer against the declared options (case- and whitespace-insensitive) and map it
+ * through `response_mapping`. A freeform answer maps through the `freeform` key, else INCONCLUSIVE.
+ */
+export declare function mapHumanAnswer(human: WorkflowHumanStep, answer: Readonly<{
+    option?: string;
+    freeform?: string;
+}>): MappedHumanAnswer | {
+    error: string;
+};
+//# sourceMappingURL=workflow-v2-human.d.ts.map

package/dist/runtime/workflow-v2-human.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-human.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-human.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,eAAe,EAChB,MAAM,sCAAsC,CAAC;AAE9C,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAC9C,SAAS,EAAE,sBAAsB,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;CAC7D,CAAC,CAAC;AAEH,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,yBAAyB,EACnC,IAAI,EAAE,YAAY,GACjB,sBAAsB,CAExB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,yBAAyB,EACnC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC/B,qBAAqB,GAAG,SAAS,CAgBnC;AAWD,uFAAuF;AACvF,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsDzB;AAMD,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,eAAe,CAAC;CAC1B,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,QAAQ,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GACvD,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA0BvC"}

package/dist/runtime/workflow-v2-human.js

@@ -0,0 +1,132 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Human steps of compiled workflows: transport rendering and response mapping.
+ * The host renders exactly the returned question; the runtime maps the answer to a verdict.
+ */
+/** The transport the compiler resolved for the step; the authored value is the fallback. */
+export function humanTransportOf(manifest, step) {
+    return manifest.human_transports?.[step.id] ?? step.human?.transport ?? 'conversation';
+}
+/**
+ * The human contract of a step, rendered with `render`. The run path renders from the run, a dry
+ * run from the caller's variables and outputs; both resolve the transport the compiler chose.
+ */
+export function humanDispatchContract(manifest, step, render) {
+    if (!step.human)
+        return undefined;
+    const observation = step.expected_observation ?? step.human.expected_observation;
+    return {
+        // No key without a title, so untitled steps keep their dispatch digests.
+        ...(step.title ? { title: render(step.title) } : {}),
+        interaction: step.human.interaction,
+        transport: humanTransportOf(manifest, step),
+        // The step-level texts come first; the human contract's are the fallback (TASK-974).
+        instruction: render(step.instruction ?? step.human.instruction),
+        expected_observation: observation ? render(observation) : undefined,
+        options: step.human.options,
+        allow_freeform: step.human.allow_freeform,
+        required: step.human.required,
+        response_mapping: step.human.response_mapping,
+    };
+}
+/**
+ * AskUserQuestion takes a header chip of at most 12 characters: the title when it fits, else the
+ * step ID, since a cut title reads worse than the ID and the question carries the instruction.
+ */
+function header(stepId, title) {
+    if (title && title.length <= 12)
+        return title;
+    return stepId.length <= 12 ? stepId : stepId.slice(0, 12);
+}
+/** Arguments of the host tool that renders the question for the resolved transport. */
+export function humanTransportArguments(stepId, contract) {
+    switch (contract.transport) {
+        case 'claude_code_ask_user_question':
+            return {
+                questions: [
+                    {
+                        question: contract.instruction,
+                        header: header(stepId, contract.title),
+                        multiSelect: false,
+                        options: contract.options.map((option) => ({
+                            label: option,
+                            description: `Records ${contract.response_mapping[option] ?? 'INCONCLUSIVE'} for step ${stepId}`,
+                        })),
+                    },
+                ],
+            };
+        case 'vscode_askQuestions':
+            return {
+                questions: [
+                    {
+                        header: contract.title ?? stepId,
+                        question: contract.instruction,
+                        options: contract.options.map((option) => ({ label: option })),
+                        allowFreeformInput: contract.allow_freeform,
+                    },
+                ],
+            };
+        case 'vscode_walkthrough_panel':
+            return {
+                step: {
+                    id: stepId,
+                    ...(contract.title ? { title: contract.title } : {}),
+                    interaction: contract.interaction,
+                    instruction: contract.instruction,
+                    expected_observation: contract.expected_observation,
+                    required: contract.required,
+                    options: contract.options.map((option) => ({
+                        label: option,
+                        records: contract.response_mapping[option] ?? 'INCONCLUSIVE',
+                    })),
+                    allow_freeform: contract.allow_freeform,
+                },
+            };
+        case 'conversation':
+            return {
+                message: [
+                    contract.instruction,
+                    '',
+                    ...contract.options.map((option, index) => `${index + 1}. ${option}`),
+                    ...(contract.allow_freeform ? ['', 'Or answer in your own words.'] : []),
+                ].join('\n'),
+                options: [...contract.options],
+            };
+    }
+}
+function normalized(value) {
+    return value.normalize('NFKC').trim().replace(/\s+/g, ' ').toLocaleLowerCase('en-US');
+}
+/**
+ * Match the answer against the declared options (case- and whitespace-insensitive) and map it
+ * through `response_mapping`. A freeform answer maps through the `freeform` key, else INCONCLUSIVE.
+ */
+export function mapHumanAnswer(human, answer) {
+    if (answer.option !== undefined) {
+        const option = human.options.find((candidate) => normalized(candidate) === normalized(answer.option));
+        if (option)
+            return { option, verdict: human.response_mapping[option] ?? 'INCONCLUSIVE' };
+        if (!human.allow_freeform) {
+            return {
+                error: `"${answer.option}" is not one of the options ${JSON.stringify(human.options)}`,
+            };
+        }
+        return {
+            freeform: answer.option,
+            verdict: human.response_mapping.freeform ?? 'INCONCLUSIVE',
+        };
+    }
+    if (answer.freeform !== undefined) {
+        if (!human.allow_freeform) {
+            return { error: `This step does not accept freeform answers; choose one of the options` };
+        }
+        return {
+            freeform: answer.freeform,
+            verdict: human.response_mapping.freeform ?? 'INCONCLUSIVE',
+        };
+    }
+    return { error: 'A human response needs option or freeform' };
+}
+//# sourceMappingURL=workflow-v2-human.js.map

package/dist/runtime/workflow-v2-human.js.map

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

package/dist/runtime/workflow-v2-labels.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Outline labels of the steps of a v2 run (DEC-024). A run numbers its steps 1 to n when it
+ * starts. A step inserted later takes a label derived from the step before it: the next free
+ * sibling (1a → 1b, and 3 → 4 after the last step), otherwise the first free child (1 → 1a,
+ * 1a → 1a1, 1a1 → 1a1a). A label is never reused or shifted, so a number the operator has read
+ * stays valid for the whole run.
+ * @see STORY-465
+ */
+import type { WorkflowStep } from '../schemas/workflow-definition-v2.js';
+/** The labels a run starts with: the authored order, counted from 1. */
+export declare function initialStepLabels(steps: readonly Pick<WorkflowStep, 'id'>[]): Record<string, string>;
+/** The label with its last segment counted on: 1a → 1b, 1a1 → 1a2, 3 → 4. */
+export declare function nextSiblingLabel(label: string): string;
+/** The first label below this one: a letter after a number, a number after a letter. */
+export declare function firstChildLabel(label: string): string;
+/** The label of a step inserted after `previous`, given every label the run ever used. */
+export declare function insertedStepLabel(previous: string | undefined, used: ReadonlySet<string>): string;
+/**
+ * Labels for the steps of a revised definition: known steps keep theirs, new steps are labelled
+ * after the step before them in authored order. Labels of removed steps stay reserved.
+ */
+export declare function revisedStepLabels(steps: readonly Pick<WorkflowStep, 'id'>[], current: Readonly<Record<string, string>>): Record<string, string>;
+//# sourceMappingURL=workflow-v2-labels.d.ts.map

package/dist/runtime/workflow-v2-labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-labels.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-labels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,wEAAwE;AACxE,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,GACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB;AAeD,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,CAWjG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,EAC1C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACxC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAcxB"}

package/dist/runtime/workflow-v2-labels.js

@@ -0,0 +1,75 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Outline labels of the steps of a v2 run (DEC-024). A run numbers its steps 1 to n when it
+ * starts. A step inserted later takes a label derived from the step before it: the next free
+ * sibling (1a → 1b, and 3 → 4 after the last step), otherwise the first free child (1 → 1a,
+ * 1a → 1a1, 1a1 → 1a1a). A label is never reused or shifted, so a number the operator has read
+ * stays valid for the whole run.
+ * @see STORY-465
+ */
+/** The labels a run starts with: the authored order, counted from 1. */
+export function initialStepLabels(steps) {
+    return Object.fromEntries(steps.map((step, index) => [step.id, String(index + 1)]));
+}
+/** Letters a…z, then aa, ab …: the next value of an alphabetic segment. */
+function nextLetters(segment) {
+    const chars = segment.split('');
+    for (let index = chars.length - 1; index >= 0; index -= 1) {
+        if (chars[index] !== 'z') {
+            chars[index] = String.fromCharCode((chars[index] ?? 'a').charCodeAt(0) + 1);
+            return chars.join('');
+        }
+        chars[index] = 'a';
+    }
+    return `a${chars.join('')}`;
+}
+/** The label with its last segment counted on: 1a → 1b, 1a1 → 1a2, 3 → 4. */
+export function nextSiblingLabel(label) {
+    const match = /^(.*?)(\d+|[a-z]+)$/.exec(label);
+    if (!match)
+        return `${label}a`;
+    const [, head = '', last = ''] = match;
+    return /^\d+$/.test(last) ? `${head}${Number(last) + 1}` : `${head}${nextLetters(last)}`;
+}
+/** The first label below this one: a letter after a number, a number after a letter. */
+export function firstChildLabel(label) {
+    return /\d$/.test(label) ? `${label}a` : `${label}1`;
+}
+/** The label of a step inserted after `previous`, given every label the run ever used. */
+export function insertedStepLabel(previous, used) {
+    if (previous === undefined) {
+        let label = '0';
+        while (used.has(label))
+            label = firstChildLabel(label);
+        return label;
+    }
+    const sibling = nextSiblingLabel(previous);
+    if (!used.has(sibling))
+        return sibling;
+    let child = firstChildLabel(previous);
+    while (used.has(child))
+        child = nextSiblingLabel(child);
+    return child;
+}
+/**
+ * Labels for the steps of a revised definition: known steps keep theirs, new steps are labelled
+ * after the step before them in authored order. Labels of removed steps stay reserved.
+ */
+export function revisedStepLabels(steps, current) {
+    const labels = { ...current };
+    const used = new Set(Object.values(labels));
+    let previous;
+    for (const step of steps) {
+        let label = labels[step.id];
+        if (label === undefined) {
+            label = insertedStepLabel(previous, used);
+            labels[step.id] = label;
+            used.add(label);
+        }
+        previous = label;
+    }
+    return labels;
+}
+//# sourceMappingURL=workflow-v2-labels.js.map

package/dist/runtime/workflow-v2-labels.js.map

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

package/dist/runtime/workflow-v2-notes.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Step notes of v2 runs: a problem or a question from one party, an answer or a check from the
+ * other, on one step. A note changes no cursor, no attempt and no verdict, so a step stays
+ * current while its problem is worked out (field-trial finding 9). It is the channel through which
+ * the agent assists an operator who works a guide alone (DOC-133). A problem or question is open
+ * until a note replies to it or the step is recorded.
+ * @see TASK-979 STORY-463
+ */
+import { z } from 'zod';
+import type { ProcessEvent, ProcessRun } from './index.js';
+import { type WorkflowV2RunContext } from './workflow-v2-run.js';
+import { type WorkflowRunEventApplication, type WorkflowRunEventInput } from './workflow-v2-run-events.js';
+export declare const WORKFLOW_NOTE_EVENT = "run.note";
+/** Problems and questions ask for something; answers and checks reply. */
+export declare const WorkflowStepNoteKind: z.ZodEnum<{
+    answer: "answer";
+    check: "check";
+    problem: "problem";
+    question: "question";
+}>;
+export type WorkflowStepNoteKind = z.infer<typeof WorkflowStepNoteKind>;
+export declare const WorkflowStepNote: z.ZodObject<{
+    step_id: z.ZodString;
+    kind: z.ZodEnum<{
+        answer: "answer";
+        check: "check";
+        problem: "problem";
+        question: "question";
+    }>;
+    text: z.ZodString;
+    reply_to: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkflowStepNote = z.infer<typeof WorkflowStepNote>;
+/** The shape a refused note is pointed to: a flat note is the usual mistake (BUG-188). */
+export declare const WORKFLOW_NOTE_SHAPE: string;
+export type WorkflowV2StepNoteView = Readonly<{
+    note_id: string;
+    step_id: string;
+    kind: WorkflowStepNoteKind;
+    text: string;
+    /** Set when the text was longer than the preview; the full text is this evidence file. */
+    evidence_path?: string;
+    actor: ProcessEvent['actor'];
+    actor_name?: string;
+    at: string;
+    reply_to?: string;
+    /** A problem or question nobody has replied to and whose step was not recorded since. */
+    open: boolean;
+}>;
+/** The notes of a run in sequence, each with whether it is still open. */
+export declare function workflowV2StepNotes(events: readonly ProcessEvent[]): WorkflowV2StepNoteView[];
+/** Build the note event; a secret-shaped text is refused, never redacted into the record. */
+export declare function applyStepNote(context: WorkflowV2RunContext, run: ProcessRun, events: readonly ProcessEvent[], note: WorkflowStepNote, input: WorkflowRunEventInput): WorkflowRunEventApplication;
+export declare function noteWorkflowRunV2(context: WorkflowV2RunContext, runId: string, note: WorkflowStepNote, input: WorkflowRunEventInput): Promise<ProcessRun>;
+//# sourceMappingURL=workflow-v2-notes.d.ts.map

package/dist/runtime/workflow-v2-notes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-v2-notes.d.ts","sourceRoot":"","sources":["../../src/runtime/workflow-v2-notes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3D,OAAO,EAAE,KAAK,oBAAoB,EAAmB,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAIL,KAAK,2BAA2B,EAChC,KAAK,qBAAqB,EAC3B,MAAM,6BAA6B,CAAC;AAGrC,eAAO,MAAM,mBAAmB,aAAa,CAAC;AAE9C,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB;;;;;EAAqD,CAAC;AACvF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,eAAO,MAAM,gBAAgB;;;;;;;;;;iBAM3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,0FAA0F;AAC1F,eAAO,MAAM,mBAAmB,QAGgD,CAAC;AAEjF,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,oBAAoB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,IAAI,EAAE,OAAO,CAAC;CACf,CAAC,CAAC;AAaH,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,sBAAsB,EAAE,CA2B7F;AAED,6FAA6F;AAC7F,wBAAgB,aAAa,CAC3B,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,qBAAqB,GAC3B,2BAA2B,CAuD7B;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,UAAU,CAAC,CAIrB"}

package/dist/runtime/workflow-v2-notes.js

@@ -0,0 +1,124 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Step notes of v2 runs: a problem or a question from one party, an answer or a check from the
+ * other, on one step. A note changes no cursor, no attempt and no verdict, so a step stays
+ * current while its problem is worked out (field-trial finding 9). It is the channel through which
+ * the agent assists an operator who works a guide alone (DOC-133). A problem or question is open
+ * until a note replies to it or the step is recorded.
+ * @see TASK-979 STORY-463
+ */
+import { z } from 'zod';
+import { captureEvidence, EVIDENCE_PREVIEW_LIMIT } from './evidence.js';
+import { containsSecretShape, redactValue } from './redaction.js';
+import { workflowV2Event } from './workflow-v2-run.js';
+import { bumpedRun, commitWorkflowRunEvent, otherParty, } from './workflow-v2-run-events.js';
+import { WorkflowRunV2Error } from './workflow-v2-types.js';
+export const WORKFLOW_NOTE_EVENT = 'run.note';
+/** Problems and questions ask for something; answers and checks reply. */
+export const WorkflowStepNoteKind = z.enum(['problem', 'question', 'answer', 'check']);
+export const WorkflowStepNote = z.object({
+    step_id: z.string().min(1).max(100),
+    kind: WorkflowStepNoteKind,
+    text: z.string().trim().min(1).max(100_000),
+    /** The note this one answers; replying resolves it. */
+    reply_to: z.string().min(1).max(40).optional(),
+});
+/** The shape a refused note is pointed to: a flat note is the usual mistake (BUG-188). */
+export const WORKFLOW_NOTE_SHAPE = 'A step note is the note object, note: { step_id, kind: problem | question | answer | check, ' +
+    'text, reply_to (the note_id it answers, optional) }, sent through workflow_run_record with ' +
+    'run_id, actor and actor_name, without expected_version or a step submission.';
+const ASKING = new Set(['problem', 'question']);
+function isNoteEvent(event) {
+    return event.type === WORKFLOW_NOTE_EVENT;
+}
+/** A record of the step itself — not a note, an assignment or a revision about it. */
+function recordsStep(event, stepId) {
+    return !event.type.startsWith('run.') && event.payload.step_id === stepId;
+}
+/** The notes of a run in sequence, each with whether it is still open. */
+export function workflowV2StepNotes(events) {
+    const ordered = [...events].sort((left, right) => left.sequence - right.sequence);
+    return ordered.filter(isNoteEvent).map((event) => {
+        const payload = event.payload;
+        const noteId = String(payload.note_id);
+        const stepId = String(payload.step_id);
+        const kind = WorkflowStepNoteKind.catch('check').parse(payload.kind);
+        const later = ordered.filter((candidate) => candidate.sequence > event.sequence);
+        const answered = later.some((candidate) => isNoteEvent(candidate) && candidate.payload.reply_to === noteId);
+        const recorded = later.some((candidate) => recordsStep(candidate, stepId));
+        return {
+            note_id: noteId,
+            step_id: stepId,
+            kind,
+            text: typeof payload.text === 'string' ? payload.text : '',
+            ...(typeof payload.evidence_path === 'string'
+                ? { evidence_path: payload.evidence_path }
+                : {}),
+            actor: event.actor,
+            ...(event.actor_name ? { actor_name: event.actor_name } : {}),
+            at: event.occurred_at,
+            ...(typeof payload.reply_to === 'string' ? { reply_to: payload.reply_to } : {}),
+            open: ASKING.has(kind) && !answered && !recorded,
+        };
+    });
+}
+/** Build the note event; a secret-shaped text is refused, never redacted into the record. */
+export function applyStepNote(context, run, events, note, input) {
+    const parsed = WorkflowStepNote.safeParse(note);
+    if (!parsed.success) {
+        const error = new WorkflowRunV2Error('INPUT_INVALID', `Invalid note: ${parsed.error.message}`);
+        error.hint = WORKFLOW_NOTE_SHAPE;
+        throw error;
+    }
+    const { step_id: stepId, kind, text, reply_to: replyTo } = parsed.data;
+    if (!context.manifest.definition.steps.some((step) => step.id === stepId)) {
+        throw new WorkflowRunV2Error('PROTOCOL_ERROR', `The guide has no step ${stepId}`);
+    }
+    if (containsSecretShape(text)) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', 'The note looks like it contains a secret; a note is written to the run log, so describe the problem without the credential');
+    }
+    if (replyTo && !events.some((event) => isNoteEvent(event) && event.payload.note_id === replyTo)) {
+        throw new WorkflowRunV2Error('INPUT_INVALID', `reply_to names no note of this run: ${replyTo}`);
+    }
+    const occurredAt = input.occurredAt ?? new Date().toISOString();
+    const noteId = `note-${run.version}`;
+    const { entry, file } = captureEvidence({
+        stepId,
+        attempt: 1,
+        sequence: run.version,
+        type: 'note',
+        suffix: noteId,
+        text,
+        capturedAt: occurredAt,
+    });
+    const payload = redactValue({
+        protocol: 'workflow-v2',
+        submission: 'note',
+        step_id: stepId,
+        note_id: noteId,
+        kind,
+        text: text.length > EVIDENCE_PREVIEW_LIMIT ? `${text.slice(0, EVIDENCE_PREVIEW_LIMIT)}…` : text,
+        ...(entry.path ? { evidence_path: entry.path } : {}),
+        ...(replyTo ? { reply_to: replyTo } : {}),
+    });
+    payload.evidence = [entry];
+    const event = workflowV2Event(run, {
+        type: WORKFLOW_NOTE_EVENT,
+        actor: input.actor,
+        actorName: input.actorName,
+        toState: run.state,
+        payload,
+        occurredAt,
+    });
+    return {
+        run: bumpedRun(run, occurredAt),
+        event: { ...event, notify: otherParty(input.actor) },
+        evidenceFiles: file ? [file] : [],
+    };
+}
+export async function noteWorkflowRunV2(context, runId, note, input) {
+    return commitWorkflowRunEvent(context, runId, (run, events) => applyStepNote(context, run, events, note, input));
+}
+//# sourceMappingURL=workflow-v2-notes.js.map