crewhaus 0.1.8 → 0.2.1

package/dist/init-interactive.d.ts

@@ -0,0 +1,105 @@
+import { type Spec, SpecParseError } from "@crewhaus/spec";
+/**
+ * Item 39 — `crewhaus init --interactive`. Folds the demos harness-designer
+ * pattern (an agent that interviews the user in plain English and emits a
+ * validated crewhaus.yaml) into core. Two design commitments:
+ *
+ *   1. NO dependency on the demos repo. The shape-decision guidance is
+ *      bundled inline here ({@link SHAPE_GUIDANCE} / {@link buildInterviewSystemPrompt}),
+ *      and validation is `parseSpec` called in-process — the single source of
+ *      truth for what compiles.
+ *   2. Every draft the model emits is validated against the LIVE Zod union via
+ *      `parseSpec`, and on a structured error the error text is fed back for a
+ *      retry. So `init --interactive` cannot emit a spec that won't parse.
+ *
+ * Everything here is side-effect-free and unit-testable: the interview loop is
+ * driven by an INJECTED `proposeSpec` callback (the CLI wires the model
+ * adapter behind it), and the credential-free fallback is a pure
+ * {@link buildScriptedSpec} over stdin answers. The CLI wrapper in `index.ts`
+ * owns all I/O.
+ */
+/** The fourteen target shapes, with the one-line "pick me when" guidance the
+ *  interviewer uses. Bundled inline so core never reaches into the demos repo. */
+export declare const SHAPE_GUIDANCE: ReadonlyArray<{
+    target: string;
+    when: string;
+}>;
+/** Shapes the scripted (no-credentials) fallback can emit end-to-end without
+ *  additional required blocks the user would have to hand-author. cli is the
+ *  overwhelmingly common case; workflow + research + eval are the other simple
+ *  single-agent shapes whose minimal spec is fully derivable from a few answers. */
+export declare const SCRIPTED_SHAPES: readonly ["cli", "workflow", "research"];
+export type ScriptedShape = (typeof SCRIPTED_SHAPES)[number];
+export declare function isScriptedShape(s: string): s is ScriptedShape;
+/**
+ * The interviewer's system prompt. Bundles the shape catalog + the hard rules
+ * the emitted YAML must obey (single-line-safe names, the `$UPPER_SNAKE_CASE`
+ * secret convention, no `permissions.mode: bypass`). Kept as a builder so a
+ * test can assert the guidance is present without shipping a golden file.
+ */
+export declare function buildInterviewSystemPrompt(): string;
+/** The tool the interviewer calls to submit a candidate spec. Exported so the
+ *  CLI wires the same schema into the adapter request. */
+export declare const EMIT_SPEC_TOOL: {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: {
+            yaml: {
+                type: "string";
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+/** One turn of the interview: the injected model proposes a spec (the `yaml`
+ *  string it passed to `emit_spec`), given the running feedback log of prior
+ *  validation errors. Returns undefined if the model declined to emit. */
+export type ProposeSpec = (feedback: readonly string[]) => Promise<string | undefined>;
+export type InterviewResult = {
+    readonly yaml: string;
+    readonly spec: Spec;
+    /** How many drafts were tried before one validated (1 = first try). */
+    readonly attempts: number;
+};
+export declare class InterviewError extends SpecParseError {
+}
+/**
+ * Drive the validate-and-retry interview loop. Each attempt asks the injected
+ * `proposeSpec` for a draft, runs it through `parseSpec` (the LIVE union), and
+ * on a `SpecParseError` appends the error to the feedback log for the next
+ * attempt. Succeeds on the first draft that validates; throws
+ * {@link InterviewError} after `maxAttempts` failed drafts (or if the model
+ * declines to emit). Pure given its `proposeSpec` seam — no I/O.
+ */
+export declare function runInterview(opts: {
+    readonly proposeSpec: ProposeSpec;
+    readonly maxAttempts?: number;
+}): Promise<InterviewResult>;
+/** The answers the scripted (no-credentials) questionnaire collects. Every
+ *  field is a plain string/list so the CLI can gather them over stdin and a
+ *  test can drive {@link buildScriptedSpec} directly. */
+export type ScriptedAnswers = {
+    readonly name: string;
+    readonly shape: ScriptedShape;
+    readonly model: string;
+    readonly instructions: string;
+    /** Tool names for cli/research; ignored for workflow. */
+    readonly tools?: readonly string[];
+    /** The research goal (research shape only). */
+    readonly goal?: string;
+};
+/**
+ * Build a minimal, VALIDATED crewhaus.yaml from scripted answers — the
+ * credential-free degrade path. Emits the spec text, runs it through
+ * `parseSpec` (so even the scripted path can't produce an invalid spec), and
+ * returns both. Throws `SpecParseError` if the answers somehow don't validate
+ * (e.g. an unsafe name), which the CLI surfaces so the user can retry the
+ * offending answer.
+ */
+export declare function buildScriptedSpec(answers: ScriptedAnswers): {
+    yaml: string;
+    spec: Spec;
+};

package/dist/init-interactive.js

@@ -0,0 +1,208 @@
+import { SpecParseError, parseSpec } from "@crewhaus/spec";
+/**
+ * Item 39 — `crewhaus init --interactive`. Folds the demos harness-designer
+ * pattern (an agent that interviews the user in plain English and emits a
+ * validated crewhaus.yaml) into core. Two design commitments:
+ *
+ *   1. NO dependency on the demos repo. The shape-decision guidance is
+ *      bundled inline here ({@link SHAPE_GUIDANCE} / {@link buildInterviewSystemPrompt}),
+ *      and validation is `parseSpec` called in-process — the single source of
+ *      truth for what compiles.
+ *   2. Every draft the model emits is validated against the LIVE Zod union via
+ *      `parseSpec`, and on a structured error the error text is fed back for a
+ *      retry. So `init --interactive` cannot emit a spec that won't parse.
+ *
+ * Everything here is side-effect-free and unit-testable: the interview loop is
+ * driven by an INJECTED `proposeSpec` callback (the CLI wires the model
+ * adapter behind it), and the credential-free fallback is a pure
+ * {@link buildScriptedSpec} over stdin answers. The CLI wrapper in `index.ts`
+ * owns all I/O.
+ */
+/** The fourteen target shapes, with the one-line "pick me when" guidance the
+ *  interviewer uses. Bundled inline so core never reaches into the demos repo. */
+export const SHAPE_GUIDANCE = [
+    {
+        target: "cli",
+        when: "a single interactive chat/coding agent run from a terminal (the default)",
+    },
+    { target: "workflow", when: "a fixed sequence of steps, each a prompt, threaded in order" },
+    { target: "channel", when: "a long-running bot that answers Slack/Telegram/Discord messages" },
+    { target: "graph", when: "a stateful DAG of LLM nodes with human-in-the-loop pause points" },
+    { target: "managed", when: "a multi-tenant gateway daemon with per-tenant token budgets" },
+    {
+        target: "pipeline",
+        when: "RAG: index documents into a vector store, then chat with retrieval",
+    },
+    {
+        target: "crew",
+        when: "multiple named roles that hand off to each other (router or match rules)",
+    },
+    { target: "research", when: "decompose a goal into sub-questions and write a cited report" },
+    { target: "batch", when: "a queue worker that runs the agent on each job with idempotency" },
+    { target: "voice", when: "a realtime audio agent (OpenAI realtime / Vapi) over telephony" },
+    { target: "browser", when: "a computer-use agent that drives a real browser" },
+    { target: "eval", when: "run an agent against a dataset and grade it (not a live agent)" },
+    { target: "onchain", when: "an event-driven daemon that reacts to on-chain triggers with txns" },
+    { target: "onchain-game", when: "a perceive-act loop against a game contract" },
+];
+/** Shapes the scripted (no-credentials) fallback can emit end-to-end without
+ *  additional required blocks the user would have to hand-author. cli is the
+ *  overwhelmingly common case; workflow + research + eval are the other simple
+ *  single-agent shapes whose minimal spec is fully derivable from a few answers. */
+export const SCRIPTED_SHAPES = ["cli", "workflow", "research"];
+export function isScriptedShape(s) {
+    return SCRIPTED_SHAPES.includes(s);
+}
+/**
+ * The interviewer's system prompt. Bundles the shape catalog + the hard rules
+ * the emitted YAML must obey (single-line-safe names, the `$UPPER_SNAKE_CASE`
+ * secret convention, no `permissions.mode: bypass`). Kept as a builder so a
+ * test can assert the guidance is present without shipping a golden file.
+ */
+export function buildInterviewSystemPrompt() {
+    const shapes = SHAPE_GUIDANCE.map((s) => `  - ${s.target}: ${s.when}`).join("\n");
+    return [
+        "You are the CrewHaus harness designer. Interview the user in plain English to",
+        "understand what agent they want to build, then emit a single valid crewhaus.yaml",
+        "by calling the `emit_spec` tool with the full YAML as its `yaml` argument.",
+        "",
+        "Pick exactly ONE target shape:",
+        shapes,
+        "",
+        "Hard rules the YAML MUST obey (the validator rejects violations):",
+        '  - `name` and every role/step/node name: letters, digits, spaces, and "_ . - :" only',
+        "    (no newlines, quotes, slashes, or comment/template delimiters).",
+        "  - Secrets (tokens, API keys, channel credentials) MUST be written as a $UPPER_SNAKE_CASE",
+        "    environment reference (e.g. $SLACK_BOT_TOKEN), NEVER a literal secret value.",
+        "  - Do NOT set `permissions.mode: bypass` — it is rejected; use default/plan/auto.",
+        "  - For a cli target: top-level `name`, `target: cli`, and an `agent` block with",
+        "    `model` and `instructions`. Tools go in a top-level `tools:` list of names.",
+        "  - Keep the spec minimal — only the blocks the user actually asked for.",
+        "",
+        "When the validator reports an error on your draft, FIX exactly that error and re-emit",
+        "— do not restart the interview.",
+    ].join("\n");
+}
+/** The tool the interviewer calls to submit a candidate spec. Exported so the
+ *  CLI wires the same schema into the adapter request. */
+export const EMIT_SPEC_TOOL = {
+    name: "emit_spec",
+    description: "Submit the complete crewhaus.yaml as a single YAML string. The validator parses it " +
+        "immediately; if it fails you will be told the exact error and must re-emit a corrected spec.",
+    input_schema: {
+        type: "object",
+        properties: {
+            yaml: { type: "string", description: "The full crewhaus.yaml document." },
+        },
+        required: ["yaml"],
+    },
+};
+export class InterviewError extends SpecParseError {
+}
+/**
+ * Drive the validate-and-retry interview loop. Each attempt asks the injected
+ * `proposeSpec` for a draft, runs it through `parseSpec` (the LIVE union), and
+ * on a `SpecParseError` appends the error to the feedback log for the next
+ * attempt. Succeeds on the first draft that validates; throws
+ * {@link InterviewError} after `maxAttempts` failed drafts (or if the model
+ * declines to emit). Pure given its `proposeSpec` seam — no I/O.
+ */
+export async function runInterview(opts) {
+    const maxAttempts = opts.maxAttempts ?? 4;
+    const feedback = [];
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const yaml = await opts.proposeSpec(feedback);
+        if (yaml === undefined) {
+            throw new InterviewError("the interviewer did not emit a spec (no emit_spec tool call) — try a more concrete description");
+        }
+        try {
+            const spec = parseSpec(yaml);
+            return { yaml, spec, attempts: attempt };
+        }
+        catch (err) {
+            if (err instanceof SpecParseError) {
+                feedback.push(err.message);
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new InterviewError(`interviewer failed to produce a valid spec after ${maxAttempts} attempts. Last errors:\n${feedback
+        .map((f) => `  - ${f}`)
+        .join("\n")}`);
+}
+/** YAML-quote a scalar that might contain special characters. The scripted
+ *  answers are user free-text, so a name/model with a colon or `#` must be
+ *  double-quoted to parse. Instructions use a block scalar (see below). */
+function yamlScalar(value) {
+    // Safe bareword: no YAML-significant leading/embedded chars.
+    if (/^[A-Za-z0-9_][\w .-]*$/.test(value) && !/[:#]/.test(value))
+        return value;
+    return JSON.stringify(value); // JSON string is valid YAML double-quoted scalar.
+}
+/** Render a possibly-multiline instructions string as a literal block scalar. */
+function yamlBlock(key, value, indent) {
+    const lines = value.split("\n");
+    const body = lines.map((l) => `${indent}  ${l}`).join("\n");
+    return `${indent}${key}: |\n${body}`;
+}
+/**
+ * Build a minimal, VALIDATED crewhaus.yaml from scripted answers — the
+ * credential-free degrade path. Emits the spec text, runs it through
+ * `parseSpec` (so even the scripted path can't produce an invalid spec), and
+ * returns both. Throws `SpecParseError` if the answers somehow don't validate
+ * (e.g. an unsafe name), which the CLI surfaces so the user can retry the
+ * offending answer.
+ */
+export function buildScriptedSpec(answers) {
+    let yaml;
+    if (answers.shape === "workflow") {
+        yaml = [
+            `name: ${yamlScalar(answers.name)}`,
+            "target: workflow",
+            `model: ${yamlScalar(answers.model)}`,
+            "steps:",
+            `  - name: ${yamlScalar(answers.name)}-step`,
+            // The step's `instructions:` is nested one list-item deep, so the block
+            // scalar indents at 4 spaces (2 for the list item + 2 for the map key).
+            yamlBlock("instructions", answers.instructions, "    "),
+            "",
+        ].join("\n");
+    }
+    else if (answers.shape === "research") {
+        const toolsBlock = answers.tools && answers.tools.length > 0
+            ? `tools:\n${answers.tools.map((t) => `  - ${yamlScalar(t)}`).join("\n")}\n`
+            : "";
+        yaml = [
+            `name: ${yamlScalar(answers.name)}`,
+            "target: research",
+            "agent:",
+            `  model: ${yamlScalar(answers.model)}`,
+            yamlBlock("instructions", answers.instructions, "  "),
+            `goal: ${yamlScalar(answers.goal ?? answers.instructions)}`,
+            toolsBlock.trimEnd(),
+            "",
+        ]
+            .filter((l) => l !== "")
+            .join("\n");
+    }
+    else {
+        // cli (default)
+        const toolsBlock = answers.tools && answers.tools.length > 0
+            ? `tools:\n${answers.tools.map((t) => `  - ${yamlScalar(t)}`).join("\n")}\n`
+            : "";
+        yaml = [
+            `name: ${yamlScalar(answers.name)}`,
+            "target: cli",
+            "agent:",
+            `  model: ${yamlScalar(answers.model)}`,
+            yamlBlock("instructions", answers.instructions, "  "),
+            toolsBlock.trimEnd(),
+            "",
+        ]
+            .filter((l) => l !== "")
+            .join("\n");
+    }
+    const spec = parseSpec(yaml);
+    return { yaml, spec };
+}

package/dist/intents.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Item 67 — `crewhaus intents`: end-user intent analytics. What are people
+ * actually asking the harness, and how well is it serving them?
+ *
+ * Clusters `user_message` inputs across sessions with the SAME deterministic
+ * greedy-Jaccard token clustering the `faq` / `graders suggest` / coverage
+ * features use (no model call), then ranks each intent cluster by:
+ *
+ *   - FREQUENCY:     total occurrences + distinct sessions.
+ *   - SATISFACTION:  mean normalized rating of the cluster's rated turns.
+ *   - FAILURE RATE:  share of the cluster's turns that hit a struggle signal
+ *                    (error / tool-error / loop / retry — mined by the same
+ *                    `dataset mine` signals), i.e. an UNMET intent.
+ *   - RECENCY:       first vs second half of the session window → a "rising"
+ *                    intent asked much more in the recent half.
+ *
+ * From those it surfaces four views: top intents, rising intents, low-
+ * satisfaction intents (down-rated / high-error), and unmet intents (the agent
+ * couldn't answer — errors/loops/retries). This is the product-analytics feed
+ * for `dataset mine` / `faq distill` / few-shot harvest.
+ *
+ * Everything here is pure + deterministic (the CLI entry file reads sessions +
+ * feedback and PII/secret-redacts the rendered examples via a passed-in
+ * callback). No credential/secret text enters a rendered example un-redacted.
+ */
+import type { FeedbackRecord, LoggedEvent, SessionTurn } from "./feedback";
+/** Thrown on malformed inputs / bad flags. The CLI routes it through `die()`. */
+export declare class IntentsError extends Error {
+    readonly name = "IntentsError";
+}
+/** A per-turn struggle signal, keyed by session#turn — the same set `dataset
+ *  mine` recognizes. Supplied by the CLI (from `mineSession`). */
+export type TurnSignal = {
+    readonly sessionId: string;
+    readonly turnNumber: number;
+};
+/** One user turn tagged with recency (for the rising view) — a SessionTurn plus
+ *  a monotonically increasing global ordinal across the scanned window. */
+export type OrderedTurn = SessionTurn & {
+    /** 0-based position in the chronological scan order (older = smaller). */
+    readonly order: number;
+};
+/** One ranked intent cluster. */
+export type Intent = {
+    /** The representative question (most-frequent-token, then shortest). */
+    readonly representative: string;
+    /** Total user turns in this cluster. */
+    readonly occurrences: number;
+    /** Distinct sessions that asked a question in this cluster. */
+    readonly sessionCount: number;
+    /** Mean normalized rating [0,1] over rated turns; undefined when none rated. */
+    readonly meanRating: number | undefined;
+    /** Number of the cluster's turns that hit a struggle signal. */
+    readonly failedTurns: number;
+    /** failedTurns / occurrences. */
+    readonly failureRate: number;
+    /** Occurrences in the OLDER half of the window. */
+    readonly earlyCount: number;
+    /** Occurrences in the RECENT half of the window. */
+    readonly recentCount: number;
+    /** A few representative example questions (caller redacts before render). */
+    readonly examples: readonly string[];
+};
+export type IntentDigest = {
+    readonly totalTurns: number;
+    readonly totalSessions: number;
+    readonly intents: readonly Intent[];
+    readonly topIntents: readonly Intent[];
+    readonly risingIntents: readonly Intent[];
+    readonly lowSatisfactionIntents: readonly Intent[];
+    readonly unmetIntents: readonly Intent[];
+};
+export type ClusterIntentsOptions = {
+    /** Jaccard overlap at/above which a question joins a cluster seed. Default 0.5. */
+    readonly threshold?: number;
+    /** Rating below which an intent counts as "low satisfaction". Default 0.5. */
+    readonly lowSatisfactionBelow?: number;
+    /** Failure rate at/above which an intent counts as "unmet". Default 0.34. */
+    readonly unmetFailureAtLeast?: number;
+    /** How many top/rising/etc. to surface in each view. Default 5. */
+    readonly topN?: number;
+    /** Max example questions kept per intent. Default 3. */
+    readonly examplesPerIntent?: number;
+};
+/**
+ * Cluster ordered user turns into ranked intents. Deterministic: turns are
+ * clustered greedily by normalized-token Jaccard overlap in `order` sequence;
+ * each cluster's representative is the highest-token-frequency question (ties →
+ * shortest, then lexicographic). The recency split is the median `order`.
+ */
+export declare function clusterIntents(turns: ReadonlyArray<OrderedTurn>, feedback: ReadonlyArray<FeedbackRecord>, failedTurnKeys: ReadonlyArray<TurnSignal>, opts?: ClusterIntentsOptions): IntentDigest;
+/** Build ordered turns from per-session events, oldest session first. The
+ *  caller passes sessions already in chronological order (oldest→newest). */
+export declare function orderedTurnsFromSessions(perSession: ReadonlyArray<{
+    sessionId: string;
+    events: ReadonlyArray<LoggedEvent>;
+}>, deriveTurns: (events: ReadonlyArray<LoggedEvent>) => Array<Omit<SessionTurn, "sessionId">>): OrderedTurn[];
+/** Apply the redactor to every rendered string in the digest. */
+export declare function redactDigest(digest: IntentDigest, redact: (s: string) => string): IntentDigest;
+/** Render the digest as plain text. */
+export declare function renderIntentsText(digest: IntentDigest): string;
+/** Render the digest as pretty JSON. */
+export declare function renderIntentsJson(digest: IntentDigest): string;
+/** Render the digest as a self-contained HTML report. */
+export declare function renderIntentsHtml(digest: IntentDigest): string;