@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/claude-code/build/src/cli/kit.js

@@ -6,7 +6,8 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
 import { assertPathContained, assertPathsDisjoint, atomicWriteJson, copyDirAtomic, ensureSafeDirectory, isoNow, readJson, walkFiles } from "../lib/fs.js";
-import { assertKitRepository, deriveKitTargets, parseKitDependencies } from "../flow-kit/validate.js";
+import { assertKitRepository, deriveKitTargets, parseKitDependencies, validateKitRepositoryDiagnostics } from "../flow-kit/validate.js";
+import { provisionKit, ProvisionConflictError } from "../flow-kit/provision.js";
 import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
 import { defaultCodexHome } from "../lib/local-artifact-root.js";
 import { root } from "../tools/common.js";
@@ -35,6 +36,18 @@ function resolveCatalogKitSource(source) {
         return null;
     return path.resolve(path.dirname(repoCatalogPath), "..", rel);
 }
+function resolveProvisionKitSource(source, dest) {
+    const localPath = path.resolve(source);
+    if (fs.existsSync(localPath))
+        return localPath;
+    const installed = loadRegistry(dest).kits.find((entry) => entry.id === source);
+    if (installed) {
+        const installedSource = installedPath(dest, source);
+        if (fs.existsSync(installedSource))
+            return installedSource;
+    }
+    return resolveCatalogKitSource(source);
+}
 function loadRegistry(dest) {
     const file = registryPath(dest);
     if (!fs.existsSync(file))
@@ -64,6 +77,17 @@ function warnUninstalledDependencies(manifest, manifestPath, dest) {
         }
     }
 }
+/**
+ * Print non-blocking kit-validation warnings (e.g. an agent-spawning trigger surface
+ * declared without complete guard config — context/contracts/trigger-guards.md).
+ * Shared by BOTH install source forms (local path and git clone) so the standing
+ * warning contract cannot silently diverge between them. Same non-blocking
+ * `warning:` convention as warnUninstalledDependencies above.
+ */
+async function printKitValidationWarnings(kitDir) {
+    for (const warning of (await validateKitRepositoryDiagnostics(kitDir)).warnings)
+        console.log(`warning: ${warning}`);
+}
 function contentHash(root) {
     const hash = crypto.createHash("sha256");
     for (const file of walkFiles(root)) {
@@ -122,6 +146,7 @@ async function installLocalSource(source, argv) {
     let manifest;
     try {
         manifest = await assertKitRepository(source);
+        await printKitValidationWarnings(source);
     }
     catch (error) {
         console.log("Flow Kit repository validation failed:");
@@ -211,6 +236,7 @@ async function installGitSource(rawUrl, argv) {
         let manifest;
         try {
             manifest = await assertKitRepository(tmpBase);
+            await printKitValidationWarnings(tmpBase);
         }
         catch (error) {
             console.log("Flow Kit repository validation failed:");
@@ -321,6 +347,69 @@ function activate(argv) {
     console.log(JSON.stringify(result, null, 2));
     return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }
+async function validate(argv) {
+    const args = parseArgs(argv);
+    const kitDir = path.resolve(args.positionals[0] ?? ".");
+    const diagnostics = await validateKitRepositoryDiagnostics(kitDir);
+    for (const warning of diagnostics.warnings)
+        console.log(`warning: ${warning}`);
+    if (diagnostics.errors.length) {
+        console.log("Flow Kit repository validation failed:");
+        for (const error of diagnostics.errors)
+            console.log(` - ${error}`);
+        return 1;
+    }
+    console.log(`Flow Kit repository validation passed: ${kitDir}`);
+    return 0;
+}
+async function provision(argv) {
+    const args = parseArgs(argv);
+    const source = args.positionals[0];
+    if (!source) {
+        console.error("provision: missing <kit-id-or-path> argument");
+        console.error("usage: flow-agents kit provision <kit-id-or-path> [--target <dir>] [--force] [--dry-run]");
+        return 2;
+    }
+    const dest = resolveDest(args.flags);
+    const kitDir = resolveProvisionKitSource(source, dest);
+    if (!kitDir) {
+        console.error(`provision: kit '${source}' was not found as a local path, installed kit, or catalog kit`);
+        return 1;
+    }
+    const target = path.resolve(flagString(args.flags, "target", process.cwd()) ?? process.cwd());
+    try {
+        const result = await provisionKit(kitDir, target, {
+            force: flagBool(args.flags, "force"),
+            dryRun: flagBool(args.flags, "dry-run"),
+        });
+        for (const file of result.files)
+            console.log(`${result.dry_run ? "would provision" : "provisioned"}: ${file.source} -> ${file.destination}`);
+        if (result.dry_run)
+            console.log(`dry-run: ${result.files.length} file(s) declared by kit '${result.kit_id}'; no files written`);
+        else if (result.files.length === 0)
+            console.log(`kit '${result.kit_id}' declares no provisions`);
+        else
+            console.log(`provisioned ${result.files.length} file(s) from kit '${result.kit_id}' into ${target}`);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof ProvisionConflictError) {
+            console.error(`provision: ${error.message}; rerun with --force to overwrite`);
+            for (const conflict of error.conflicts)
+                console.error(`conflict: ${conflict.target} (${conflict.destination})`);
+            return 1;
+        }
+        const diagnostics = error.diagnostics;
+        if (diagnostics?.length) {
+            console.error("Flow Kit repository validation failed:");
+            for (const diagnostic of diagnostics)
+                console.error(` - ${diagnostic}`);
+        }
+        else
+            console.error(`provision: ${error.message}`);
+        return 1;
+    }
+}
 /**
  * inspect <kit-dir> [--json]
  *
@@ -375,9 +464,13 @@ export async function main(argv = process.argv.slice(2)) {
         return status(rest);
     if (command === "activate")
         return activate(rest);
+    if (command === "validate")
+        return await validate(rest);
+    if (command === "provision")
+        return await provision(rest);
     if (command === "inspect")
         return await inspect(rest);
-    console.error("usage: flow-agents kit <install|activate|inspect|list|status> ...");
+    console.error("usage: flow-agents kit <install|activate|validate|provision|inspect|list|status> ...");
     return 2;
 }
 // Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.

package/dist/claude-code/build/src/cli/narrative-render.d.ts

@@ -0,0 +1,95 @@
+import { type GroundedExecutionNarrative, type WrittenGroundedNarrative } from "../narrative/envelope.js";
+import { type EntailmentIdentity, type EntailmentProvenance } from "../narrative/grounding-validator.js";
+import { type Statement } from "../narrative/statements.js";
+export declare const PROSE_PROMPT_VERSION: "narrative-prose-renderer/v1";
+export declare const PROSE_ECONOMICS_FILE = "prose-economics.jsonl";
+export interface ProseGeneratorSentence {
+    text: string;
+    statement_refs: string[];
+}
+export interface ProseGeneratorUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+export interface GeneratedProse {
+    sentences: ProseGeneratorSentence[];
+    usage: ProseGeneratorUsage;
+}
+export interface ProseSourceView {
+    source_ref: string;
+    stream: string;
+    content: string;
+}
+export interface ProseGeneratorInput {
+    /** Frozen runtime-projection statements only (turns[].statements + document_statements). */
+    statements: Statement[];
+    /** Policy-filtered frozen snapshot views for every source_ref cited by `statements`. */
+    sourceViews: ProseSourceView[];
+}
+export interface ProseGenerator {
+    identity: EntailmentIdentity;
+    generate(input: ProseGeneratorInput): Promise<GeneratedProse>;
+}
+export declare const stubGenerator: ProseGenerator;
+export interface ProviderOptIn {
+    tenant: string;
+    data_residency: string;
+    payload_policy: string;
+}
+export interface ProviderConfig {
+    endpoint?: string;
+    optIn?: ProviderOptIn;
+}
+export declare function providerAllowed(config: ProviderConfig, endpoint: string): boolean;
+export declare class ProviderNotAllowedError extends Error {
+    readonly endpoint: string;
+    readonly name = "ProviderNotAllowedError";
+    constructor(endpoint: string);
+}
+export interface ModelGeneratorConfig extends ProviderConfig {
+    model: string;
+    provider: string;
+    timeoutMs?: number;
+}
+/** Local-first default real path (D5): an operator-configured local model server. */
+export declare function localModelGenerator(config: ModelGeneratorConfig): ProseGenerator;
+/** Hosted path (D5/R6/AC8): inert without EXPLICIT opt-in; never dials without it. */
+export declare function hostedModelGenerator(config: ModelGeneratorConfig): ProseGenerator;
+export declare class GeneratorTimeoutError extends Error {
+    readonly name = "GeneratorTimeoutError";
+}
+export type ProseRenderOutcome = "accepted" | "generator_error" | "generator_timeout" | "validator_error" | "validator_reject";
+export type ProseEconomicsRecord = EntailmentProvenance & {
+    attempted_at: string;
+    outcome: ProseRenderOutcome;
+    detail?: string;
+};
+export interface RenderProseOptions {
+    compiledAt: string;
+    outDir: string;
+    generator: ProseGenerator;
+    timeoutMs?: number;
+}
+export interface RenderProseResult {
+    envelope: GroundedExecutionNarrative;
+    written: WrittenGroundedNarrative;
+    outcome: "prose_published" | "deterministic_only";
+    reason?: string;
+    prose?: {
+        path: string;
+        sha256: string;
+    };
+    provenance: ProseEconomicsRecord;
+}
+/**
+ * Fail-closed orchestrator (D4/LB1). The #613/#623 compose -> schema-validate ->
+ * grounding-validate prefix is unchanged and still throws before ANY write on a
+ * malformed/ungrounded envelope (nothing to attempt generation over). Once that
+ * substrate is valid, the deterministic #613 output is ALWAYS written first (R4's
+ * guarantee), then generation is attempted under a bounded timeout. ANY
+ * generator error/timeout/validator error/reject leaves ZERO prose artifacts and
+ * records economics for the attempt; only an accepted, re-validated, prose-augmented
+ * statement set is published alongside the deterministic narrative.
+ */
+export declare function renderProse(narrativeDir: string, opts: RenderProseOptions): Promise<RenderProseResult>;
+export declare function main(argv?: string[]): Promise<number>;