@kontourai/flow-agents 3.2.0 → 3.4.0

package/build/src/cli.js

@@ -3,6 +3,7 @@ import { basename } from "node:path";
 import { main as effectiveBacklogSettings } from "./cli/effective-backlog-settings.js";
 import { main as effectiveAssignmentProviderSettings } from "./cli/effective-assignment-provider-settings.js";
 import { main as assignmentProvider } from "./cli/assignment-provider.js";
+import { main as builderRun } from "./cli/builder-run.js";
 import { main as consoleLearningProjection } from "./cli/console-learning-projection.js";
 import { main as kit } from "./cli/kit.js";
 import { main as fixtureRetirementAudit } from "./cli/fixture-retirement-audit.js";
@@ -20,10 +21,12 @@ import { main as validateSource } from "./tools/validate-source-tree.js";
 import { main as validatePackage } from "./tools/validate-package.js";
 import { main as validateHookInfluence } from "./cli/validate-hook-influence.js";
 import { main as runtimeAdapter } from "./cli/runtime-adapter.js";
+import { main as skillDriftCheck } from "./cli/skill-drift-check.js";
 import { main as utteranceCheck } from "./cli/utterance-check.js";
 import { main as verify } from "./cli/verify.js";
 const availableCommands = new Map([
     ["build-bundles", () => buildBundles()],
+    ["builder-run", builderRun],
     ["console-learning-projection", consoleLearningProjection],
     ["context-map", contextMap],
     ["assignment-provider", assignmentProvider],
@@ -36,6 +39,7 @@ const availableCommands = new Map([
     ["publish-change", publishChange],
     ["pull-work-provider", pullWorkProvider],
     ["runtime-adapter", runtimeAdapter],
+    ["skill-drift-check", skillDriftCheck],
     ["utterance-check", utteranceCheck],
     ["telemetry-doctor", telemetryDoctor],
     ["usage-feedback", usageFeedback],
@@ -59,6 +63,7 @@ const aliases = new Map([
     ["flow-agents-publish-change", "publish-change"],
     ["flow-agents-pull-work-provider", "pull-work-provider"],
     ["flow-agents-runtime-adapter", "runtime-adapter"],
+    ["flow-agents-skill-drift-check", "skill-drift-check"],
     ["flow-agents-telemetry-doctor", "telemetry-doctor"],
     ["flow-agents-usage-feedback", "usage-feedback"],
     ["flow-agents-veritas-governance", "veritas-governance"],

package/build/src/flow-kit/validate.d.ts

@@ -2,6 +2,33 @@ export interface KitDependencyEntry {
     kit_id: string;
     reason?: string;
 }
+export interface KitWorkflowTriggerEntry {
+    id: string;
+    when: string;
+    target_flow_id?: string;
+    default_skill?: string;
+    conditional_skills?: {
+        when: string;
+        skill: string;
+    }[];
+    required_sequence?: string[];
+    post_verify_targets?: string[];
+}
+export interface KitHookInfluenceExpectationEntry {
+    id: string;
+    description: string;
+    tier: string;
+    hook?: string;
+    event?: string;
+    must_include_guidance: string[];
+    must_include_actions: string[];
+}
+export interface KitFlowStepActionEntry {
+    flow_id: string;
+    step_id: string;
+    skills: string[];
+    operations: string[];
+}
 /**
  * Parse and shape-validate a kit manifest's `dependencies` field (Flow Agents
  * extension-layer metadata; see docs/adr/0019-kit-dependency-ownership.md).
@@ -21,6 +48,18 @@ export declare function parseKitDependencies(manifest: Record<string, unknown>,
     entries: KitDependencyEntry[];
     errors: string[];
 };
+export declare function parseKitWorkflowTriggers(manifest: Record<string, unknown>, manifestPath: string): {
+    entries: KitWorkflowTriggerEntry[];
+    errors: string[];
+};
+export declare function parseKitHookInfluenceExpectations(manifest: Record<string, unknown>, manifestPath: string): {
+    entries: KitHookInfluenceExpectationEntry[];
+    errors: string[];
+};
+export declare function parseKitFlowStepActions(manifest: Record<string, unknown>, manifestPath: string): {
+    entries: KitFlowStepActionEntry[];
+    errors: string[];
+};
 export type KitTargetConsumer = "flow" | "flow-agents" | string;
 export interface KitConformanceLevel {
     /** K0: valid core Flow Kit container with at least one flow (gates evaluable agentlessly). */
@@ -32,39 +71,20 @@ export interface KitConformanceLevel {
 }
 /**
  * Kit trust level — WHO vouches for a kit, orthogonal to the K-level capability axis.
- *
- * - "first-party": the kit is authored and published by Kontour (kontourai); its id is in the
- *   FIRST_PARTY_KIT_IDS allowlist maintained in this repository. These kits are built, tested,
- *   and distributed with the flow-agents package.
- * - "verified": reserved for a future third-party verification process (e.g. self-certification
- *   via the conformance kit + cryptographic attestation / Veritas claims). Not yet implemented.
- * - "unverified": default for all kits not in the first-party allowlist. This says nothing about
- *   the kit's quality — it only means Kontour has not vouched for it.
- *
- * The v2 path for "verified": cryptographic signing / attestation against the conformance kit
- * and Veritas claims substrate is the natural next step and is intentionally deferred.
- */
-export type KitTrustLevel = "first-party" | "verified" | "unverified";
-/**
- * Allowlist of kit IDs that Kontour authors, tests, and ships with the flow-agents package.
- *
- * Criteria for inclusion:
- *   1. The kit directory lives under kits/ in the kontourai/flow-agents repository.
- *   2. The kit is published by @kontourai (npm package @kontourai/flow-agents).
- *   3. Kontour owns and maintains the kit's content and release lifecycle.
- *
- * To add a new first-party kit: add its id here AND ensure it lives under kits/ in this repo.
- * Third-party forks or community kits published elsewhere are NOT first-party, even if they
- * share a similar id — first-party is tied to provenance in this specific repository.
+ * Runtime steering and capability decisions do not branch on official/built-in provenance.
  */
-export declare const FIRST_PARTY_KIT_IDS: ReadonlySet<string>;
+export type KitTrustLevel = "verified" | "unverified";
+export type KitSourceKind = "builtin" | "local" | "unknown";
+export interface KitTrustOptions {
+    source_kind?: KitSourceKind;
+    kitDir?: string;
+    sourceRoot?: string;
+}
 /**
  * Derive the trust level for a kit id.
- *
- * v1 determination: allowlist check against FIRST_PARTY_KIT_IDS.
- * "verified" is reserved for future third-party verification (not yet granted to any kit).
+ * "verified" is reserved for future third-party verification.
  */
-export declare function deriveKitTrust(kitId: string): KitTrustLevel;
+export declare function deriveKitTrust(kitId: string, manifest?: Record<string, unknown>, options?: KitTrustOptions): KitTrustLevel;
 export interface KitTargetsResult {
     kit_id: string;
     kit_name: string;
@@ -75,7 +95,7 @@ export interface KitTargetsResult {
     third_party_extensions: string[];
     /**
      * Trust level: who vouches for this kit. Orthogonal to the K-level capability axis.
-     * "first-party" = Kontour-published; "verified" = reserved (future); "unverified" = default.
+     * "verified" = reserved (future); "unverified" = default.
      */
     trust: KitTrustLevel;
 }
@@ -91,14 +111,14 @@ export interface KitTargetsResult {
  *  - targets.flow-agents: present when K1 (agent extension assets activate in >=1 harness).
  *  - third-party: any top-level keys that are not core fields and not Flow Agents extension classes.
  *
- * Trust derivation (from kontourai/flow-agents#79):
- *  - "first-party": kit id is in FIRST_PARTY_KIT_IDS (Kontour-authored kits in this repo).
- *  - "unverified": all other kits (default; "verified" is reserved for a future process).
+ * Trust derivation:
+ *  - "unverified": all current kits (default; "verified" is reserved for a future process).
+ *    kit.json `first_party` is catalog metadata and is not trusted for runtime privilege.
  *
  * @param manifest  The kit.json manifest object.
  * @param kitDir    Kit directory for flow file-existence checks. Defaults to "" (structural-only).
  *                  Pass the real kit directory from `inspect` to get authoritative K0 validation.
  */
-export declare function deriveKitTargets(manifest: Record<string, unknown>, kitDir?: string): Promise<KitTargetsResult>;
+export declare function deriveKitTargets(manifest: Record<string, unknown>, kitDir?: string, sourceRoot?: string): Promise<KitTargetsResult>;
 export declare function validateKitRepository(kitDir: string): Promise<string[]>;
 export declare function assertKitRepository(kitDir: string): Promise<Record<string, unknown>>;

package/build/src/flow-kit/validate.js

@@ -10,8 +10,11 @@ const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals",
 // Flow Agents-recognized metadata fields that are neither core container fields nor
 // agent-extension asset classes. Recognized here so they are never misreported as
 // unknown third-party extension namespaces. `dependencies` declares cross-kit skill
-// dependencies (extension-layer ownership; see docs/adr/0019-kit-dependency-ownership.md).
-const KNOWN_METADATA_FIELDS = new Set(["dependencies"]);
+// dependencies (extension-layer ownership; see docs/adr/0019-kit-dependency-ownership.md),
+// workflow_triggers / hook_influence_expectations declare kit-owned runtime influence,
+// and first_party is legacy catalog/marketplace metadata. It does not grant runtime
+// capability or steering privilege.
+const KNOWN_METADATA_FIELDS = new Set(["dependencies", "workflow_triggers", "hook_influence_expectations", "flow_step_actions", "first_party"]);
 /**
  * Parse and shape-validate a kit manifest's `dependencies` field (Flow Agents
  * extension-layer metadata; see docs/adr/0019-kit-dependency-ownership.md).
@@ -67,28 +70,224 @@ export function parseKitDependencies(manifest, manifestPath) {
     });
     return { entries, errors };
 }
-/**
- * Allowlist of kit IDs that Kontour authors, tests, and ships with the flow-agents package.
- *
- * Criteria for inclusion:
- *   1. The kit directory lives under kits/ in the kontourai/flow-agents repository.
- *   2. The kit is published by @kontourai (npm package @kontourai/flow-agents).
- *   3. Kontour owns and maintains the kit's content and release lifecycle.
- *
- * To add a new first-party kit: add its id here AND ensure it lives under kits/ in this repo.
- * Third-party forks or community kits published elsewhere are NOT first-party, even if they
- * share a similar id — first-party is tied to provenance in this specific repository.
- */
-export const FIRST_PARTY_KIT_IDS = new Set(["builder", "knowledge"]);
+function nonEmptyStringList(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string" && item.trim().length > 0);
+}
+const WORKFLOW_TRIGGER_IDENTIFIER_RE = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+function workflowTriggerIdentifier(value) {
+    return typeof value === "string" && WORKFLOW_TRIGGER_IDENTIFIER_RE.test(value);
+}
+function optionalWorkflowTriggerIdentifier(value) {
+    return value === undefined || workflowTriggerIdentifier(value);
+}
+function optionalWorkflowTriggerIdentifierList(value) {
+    return value === undefined || (Array.isArray(value) && value.length > 0 && value.every(workflowTriggerIdentifier));
+}
+function optionalConditionalSkills(value) {
+    return value === undefined ||
+        (Array.isArray(value) && value.every((item) => typeof item === "object" && item !== null &&
+            workflowTriggerIdentifier(item.when) &&
+            workflowTriggerIdentifier(item.skill)));
+}
+export function parseKitWorkflowTriggers(manifest, manifestPath) {
+    const entries = [];
+    const errors = [];
+    const raw = manifest.workflow_triggers;
+    if (raw === undefined)
+        return { entries, errors };
+    if (!Array.isArray(raw)) {
+        errors.push(`${manifestPath}: .workflow_triggers must be a list`);
+        return { entries, errors };
+    }
+    const seen = new Set();
+    raw.forEach((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            errors.push(`${manifestPath}: workflow_triggers[${index}] must be an object`);
+            return;
+        }
+        const record = entry;
+        const id = record.id;
+        const when = record.when;
+        if (!workflowTriggerIdentifier(id)) {
+            errors.push(`${manifestPath}: workflow_triggers[${index}].id must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$`);
+            return;
+        }
+        if (seen.has(id))
+            errors.push(`${manifestPath}: workflow_triggers[${index}].id duplicates '${id}'`);
+        seen.add(id);
+        if (!workflowTriggerIdentifier(when)) {
+            errors.push(`${manifestPath}: workflow_triggers[${index}].when must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$`);
+            return;
+        }
+        if (record.hint !== undefined) {
+            errors.push(`${manifestPath}: workflow_triggers[${index}].hint is retired; use structured steering fields`);
+            return;
+        }
+        if (record.display_name !== undefined) {
+            errors.push(`${manifestPath}: workflow_triggers[${index}].display_name is not supported in workflow_triggers; use catalog/listing metadata for human-readable names`);
+            return;
+        }
+        if (!optionalWorkflowTriggerIdentifier(record.target_flow_id)) {
+            errors.push(`${manifestPath}: workflow_triggers[${index}].target_flow_id must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+            return;
+        }
+        if (!optionalWorkflowTriggerIdentifier(record.default_skill)) {
+            errors.push(`${manifestPath}: workflow_triggers[${index}].default_skill must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+            return;
+        }
+        if (!optionalConditionalSkills(record.conditional_skills)) {
+            errors.push(`${manifestPath}: workflow_triggers[${index}].conditional_skills must be a list of { when, skill } identifiers matching ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+            return;
+        }
+        if (!optionalWorkflowTriggerIdentifierList(record.required_sequence)) {
+            errors.push(`${manifestPath}: workflow_triggers[${index}].required_sequence must be a non-empty identifier list matching ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+            return;
+        }
+        if (!optionalWorkflowTriggerIdentifierList(record.post_verify_targets)) {
+            errors.push(`${manifestPath}: workflow_triggers[${index}].post_verify_targets must be a non-empty identifier list matching ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+            return;
+        }
+        entries.push({
+            id,
+            when,
+            ...(typeof record.target_flow_id === "string" ? { target_flow_id: record.target_flow_id } : {}),
+            ...(typeof record.default_skill === "string" ? { default_skill: record.default_skill } : {}),
+            ...(Array.isArray(record.conditional_skills) ? { conditional_skills: record.conditional_skills } : {}),
+            ...(Array.isArray(record.required_sequence) ? { required_sequence: record.required_sequence } : {}),
+            ...(Array.isArray(record.post_verify_targets) ? { post_verify_targets: record.post_verify_targets } : {}),
+        });
+    });
+    return { entries, errors };
+}
+export function parseKitHookInfluenceExpectations(manifest, manifestPath) {
+    const entries = [];
+    const errors = [];
+    const raw = manifest.hook_influence_expectations;
+    if (raw === undefined)
+        return { entries, errors };
+    if (!Array.isArray(raw)) {
+        errors.push(`${manifestPath}: .hook_influence_expectations must be a list`);
+        return { entries, errors };
+    }
+    const seen = new Set();
+    raw.forEach((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            errors.push(`${manifestPath}: hook_influence_expectations[${index}] must be an object`);
+            return;
+        }
+        const record = entry;
+        const id = record.id;
+        const description = record.description;
+        const tier = record.tier;
+        if (typeof id !== "string" || !id.trim()) {
+            errors.push(`${manifestPath}: hook_influence_expectations[${index}].id must be a non-empty string`);
+            return;
+        }
+        if (seen.has(id))
+            errors.push(`${manifestPath}: hook_influence_expectations[${index}].id duplicates '${id}'`);
+        seen.add(id);
+        if (typeof description !== "string" || !description.trim()) {
+            errors.push(`${manifestPath}: hook_influence_expectations[${index}].description must be a non-empty string`);
+            return;
+        }
+        if (typeof tier !== "string" || !tier.trim()) {
+            errors.push(`${manifestPath}: hook_influence_expectations[${index}].tier must be a non-empty string`);
+            return;
+        }
+        if (record.hook !== undefined && (typeof record.hook !== "string" || !record.hook.trim())) {
+            errors.push(`${manifestPath}: hook_influence_expectations[${index}].hook must be a non-empty string when present`);
+            return;
+        }
+        if (record.event !== undefined && (typeof record.event !== "string" || !record.event.trim())) {
+            errors.push(`${manifestPath}: hook_influence_expectations[${index}].event must be a non-empty string when present`);
+            return;
+        }
+        if (!nonEmptyStringList(record.must_include_guidance)) {
+            errors.push(`${manifestPath}: hook_influence_expectations[${index}].must_include_guidance must be a non-empty string list`);
+            return;
+        }
+        if (!nonEmptyStringList(record.must_include_actions)) {
+            errors.push(`${manifestPath}: hook_influence_expectations[${index}].must_include_actions must be a non-empty string list`);
+            return;
+        }
+        entries.push({
+            id,
+            description,
+            tier,
+            ...(typeof record.hook === "string" ? { hook: record.hook } : {}),
+            ...(typeof record.event === "string" ? { event: record.event } : {}),
+            must_include_guidance: record.must_include_guidance,
+            must_include_actions: record.must_include_actions,
+        });
+    });
+    return { entries, errors };
+}
+export function parseKitFlowStepActions(manifest, manifestPath) {
+    const entries = [];
+    const errors = [];
+    const raw = manifest.flow_step_actions;
+    if (raw === undefined)
+        return { entries, errors };
+    if (!Array.isArray(raw)) {
+        errors.push(`${manifestPath}: .flow_step_actions must be a list`);
+        return { entries, errors };
+    }
+    const seen = new Set();
+    raw.forEach((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            errors.push(`${manifestPath}: flow_step_actions[${index}] must be an object`);
+            return;
+        }
+        const record = entry;
+        if (!workflowTriggerIdentifier(record.flow_id)) {
+            errors.push(`${manifestPath}: flow_step_actions[${index}].flow_id must be a Flow identifier`);
+            return;
+        }
+        if (!workflowTriggerIdentifier(record.step_id)) {
+            errors.push(`${manifestPath}: flow_step_actions[${index}].step_id must be a step identifier`);
+            return;
+        }
+        const skills = record.skills;
+        const operations = record.operations ?? [];
+        if (!Array.isArray(skills) || !skills.every(workflowTriggerIdentifier)) {
+            errors.push(`${manifestPath}: flow_step_actions[${index}].skills must be an identifier list`);
+            return;
+        }
+        if (new Set(skills).size !== skills.length) {
+            errors.push(`${manifestPath}: flow_step_actions[${index}].skills must not contain duplicates`);
+            return;
+        }
+        if (!Array.isArray(operations) || !operations.every(workflowTriggerIdentifier)) {
+            errors.push(`${manifestPath}: flow_step_actions[${index}].operations must be an identifier list when present`);
+            return;
+        }
+        if (new Set(operations).size !== operations.length) {
+            errors.push(`${manifestPath}: flow_step_actions[${index}].operations must not contain duplicates`);
+            return;
+        }
+        const key = `${record.flow_id}/${record.step_id}`;
+        if (seen.has(key)) {
+            errors.push(`${manifestPath}: flow_step_actions[${index}] duplicates '${key}'`);
+            return;
+        }
+        seen.add(key);
+        entries.push({
+            flow_id: record.flow_id,
+            step_id: record.step_id,
+            skills: skills,
+            operations: operations,
+        });
+    });
+    return { entries, errors };
+}
 /**
  * Derive the trust level for a kit id.
- *
- * v1 determination: allowlist check against FIRST_PARTY_KIT_IDS.
- * "verified" is reserved for future third-party verification (not yet granted to any kit).
+ * "verified" is reserved for future third-party verification.
  */
-export function deriveKitTrust(kitId) {
-    if (FIRST_PARTY_KIT_IDS.has(kitId))
-        return "first-party";
+export function deriveKitTrust(kitId, manifest, options = {}) {
+    void kitId;
+    void manifest;
+    void options;
     return "unverified";
 }
 let _validateKitContainerCache = null;
@@ -144,15 +343,15 @@ async function delegateCoreContainerValidation(kitDir, manifest) {
  *  - targets.flow-agents: present when K1 (agent extension assets activate in >=1 harness).
  *  - third-party: any top-level keys that are not core fields and not Flow Agents extension classes.
  *
- * Trust derivation (from kontourai/flow-agents#79):
- *  - "first-party": kit id is in FIRST_PARTY_KIT_IDS (Kontour-authored kits in this repo).
- *  - "unverified": all other kits (default; "verified" is reserved for a future process).
+ * Trust derivation:
+ *  - "unverified": all current kits (default; "verified" is reserved for a future process).
+ *    kit.json `first_party` is catalog metadata and is not trusted for runtime privilege.
  *
  * @param manifest  The kit.json manifest object.
  * @param kitDir    Kit directory for flow file-existence checks. Defaults to "" (structural-only).
  *                  Pass the real kit directory from `inspect` to get authoritative K0 validation.
  */
-export async function deriveKitTargets(manifest, kitDir = "") {
+export async function deriveKitTargets(manifest, kitDir = "", sourceRoot = process.cwd()) {
     const kitId = typeof manifest.id === "string" ? manifest.id : "<unknown>";
     const kitName = typeof manifest.name === "string" ? manifest.name : "<unknown>";
     // Delegate core container validation to @kontourai/flow.
@@ -176,7 +375,7 @@ export async function deriveKitTargets(manifest, kitDir = "") {
     for (const ns of thirdPartyExtensions)
         targets.push(ns);
     // Derive trust level orthogonally to the K-level capability axis.
-    const trust = deriveKitTrust(kitId);
+    const trust = deriveKitTrust(kitId, manifest, { kitDir, sourceRoot });
     return {
         kit_id: kitId,
         kit_name: kitName,
@@ -253,6 +452,18 @@ export async function validateKitRepository(kitDir) {
     const depResult = parseKitDependencies(manifest, manifestPath);
     for (const err of depResult.errors)
         errors.push(err);
+    const workflowTriggerResult = parseKitWorkflowTriggers(manifest, manifestPath);
+    for (const err of workflowTriggerResult.errors)
+        errors.push(err);
+    const hookExpectationResult = parseKitHookInfluenceExpectations(manifest, manifestPath);
+    for (const err of hookExpectationResult.errors)
+        errors.push(err);
+    const flowStepActionResult = parseKitFlowStepActions(manifest, manifestPath);
+    for (const err of flowStepActionResult.errors)
+        errors.push(err);
+    if (manifest.first_party !== undefined && typeof manifest.first_party !== "boolean") {
+        errors.push(`${manifestPath}: .first_party must be a boolean when present`);
+    }
     return errors;
 }
 export async function assertKitRepository(kitDir) {

package/build/src/index.d.ts

@@ -1,3 +1,5 @@
+export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
+export type { BuilderBuildRunResult, BuilderBuildRunIdentityMismatch, BuilderBuildTrustBundleEvidenceInput, EvaluateBuilderBuildRunInput, LoadBuilderBuildRunInput, StartBuilderBuildRunInput, } from "./builder-flow-run-adapter.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";
 export { validateTrustBundle, normalizeCheck, normalizeFinding, normalizeLearning, normalizeEvidenceRefs, validateEvidenceRef, validateLearningCorrection, loadJson, writeJson, appendJsonl, sidecarBase, writeState, statuses, phases, checkKinds, checkStatuses, verdicts, } from "./cli/workflow-sidecar.js";
 /** Read a sidecar JSON file from a workflow artifact directory; returns `{}` if absent. */

package/build/src/index.js

@@ -15,6 +15,7 @@
  */
 import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
+export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";
 export { 
 // Trust-bundle (Hachure) validation — the same validator the writer uses.

package/build/src/lib/console-connect-options.d.ts

@@ -0,0 +1,97 @@
+export type TelemetrySink = "local-files" | "local-kontour-console" | "kontour-hosted-console" | "user-hosted-console" | "kontour-cloud" | "hosted-kontour-console";
+export type ConsoleConnectChoice = "hosted" | "local" | "self-hosted" | "skip";
+/**
+ * Case-insensitive match on the four accepted choice spellings. Blank or
+ * unrecognized input falls back to `fallback` (the caller decides the
+ * default, typically "hosted").
+ */
+export declare function normalizeConsoleConnectChoice(answer: string, fallback: ConsoleConnectChoice): ConsoleConnectChoice;
+/** Pure lookup table: choice -> the exact `telemetrySinks` array to install with. */
+export declare function mapConsoleConnectChoiceToSinks(choice: ConsoleConnectChoice): TelemetrySink[];
+/** Only "self-hosted" requires an inline URL prompt. */
+export declare function needsConsoleUrlPrompt(choice: ConsoleConnectChoice): boolean;
+/**
+ * Mirrors `needsConsoleCredentials`'s existing semantics one-for-one
+ * (choice-based instead of sinks-based): every choice except "skip" wants
+ * token/tenant prompts.
+ */
+export declare function needsConsoleCredentialPrompts(choice: ConsoleConnectChoice): boolean;
+/**
+ * The one hard-fail guard this PR adds: self-hosted Console with a blank URL
+ * is a downstream `die` in `install-console-config.sh` (the `user-hosted-console`
+ * branch requires `--console-url`/`--console-endpoint`). Falls back to
+ * `local-files` with a one-line warning instead of letting that crash happen.
+ *
+ * Only handles the blank case — a non-blank-but-malformed URL (e.g. a typo)
+ * is NOT this guard's job; callers separately run `isValidConsoleUrl` for
+ * that format-only warn-and-continue case.
+ */
+export declare function resolveSelfHostedUrlOrFallback(url: string): {
+    sinks: TelemetrySink[];
+    url: string;
+    fallbackWarning?: string;
+};
+export type ConsoleConnectIo = {
+    ask: (prompt: string) => Promise<string>;
+    askHidden: (prompt: string) => Promise<string>;
+};
+export type ConsoleConnectDefaults = {
+    hostedUrl: string;
+    localUrl: string;
+};
+export type ConsoleConnectResult = {
+    telemetrySinks: TelemetrySink[];
+    consoleUrl?: string;
+    consoleTokenValue?: string;
+    consoleTenant?: string;
+    warnings: string[];
+};
+/**
+ * Full interactive orchestration used by `interactiveOptions()`: prompts the
+ * four-way "Connect to Kontour Console?" choice (default Hosted, showing the
+ * real `console-presets.sh`-resolved hosted URL), applies the self-hosted
+ * blank-URL guard, prompts hidden token + tenant when a console connection is
+ * wanted, runs PR1's pure validators (validate-and-warn, not
+ * validate-and-block), and returns any format warnings in `warnings` for the
+ * caller to print -- rather than printing directly, so this stays testable
+ * via return-value assertions, not console-spy assertions.
+ */
+export declare function runConsoleConnectWizard(io: ConsoleConnectIo, defaults: ConsoleConnectDefaults): Promise<ConsoleConnectResult>;
+export type ConsoleStatus = "connected-verified" | "connected-unverified" | "local-only";
+type DoctorConsoleShape = {
+    sink: "local-only" | "console";
+    reachability: {
+        checked: boolean;
+        ok: boolean | null;
+        error?: string;
+        statusCode?: number;
+    };
+};
+export declare function describeConsoleStatus(doctor: {
+    console: DoctorConsoleShape;
+}): {
+    status: ConsoleStatus;
+    detail?: string;
+};
+export type PostInstallSummaryInput = {
+    runtime: string;
+    runtimeAutoDetected: boolean;
+    dest: string;
+    telemetrySinks: string[];
+    consoleStatus: {
+        status: ConsoleStatus;
+        detail?: string;
+    };
+    tokenConfigured: boolean;
+    tenantConfigured: boolean;
+    nextSteps: string[];
+};
+/**
+ * Pure string[]-builder for the post-install summary block: one array entry
+ * per line, so callers `console.log` each entry and tests assert on array
+ * contents rather than scraping stdout. Never receives or emits the raw
+ * console token value -- only the `tokenConfigured`/`tenantConfigured`
+ * booleans are shown.
+ */
+export declare function buildPostInstallSummaryLines(input: PostInstallSummaryInput): string[];
+export {};