@ema.co/machina 0.1.0

package/dist/mcp/handlers/curate/adapter.js

@@ -0,0 +1,10 @@
+import { findRepoRoot } from "../../state.js";
+import { dispatchCurate } from "./index.js";
+/**
+ * Curate — memorialize / dedup / supersede / advise over the corpus. Adapter: resolve
+ * context (repo root), delegate to the atom-kernel-backed dispatcher. Thin.
+ */
+export async function handleCurate(args) {
+    const ctx = { repoRoot: findRepoRoot(process.cwd()) };
+    return dispatchCurate(args, ctx);
+}

package/dist/mcp/handlers/curate/index.js

@@ -0,0 +1,104 @@
+import { submitChanges, validate, ValidationError } from "../../atom/index.js";
+import { clarificationNeeded, error, success } from "../../responses.js";
+import { corpusStore, deriveDescription, readYield } from "../corpus.js";
+/** Build an AtomInput from a yield slug or explicit fields. */
+function atomInputFromArgs(repoRoot, args) {
+    const audience = typeof args.audience === "string" ? args.audience : undefined;
+    const supersedes = typeof args.supersedes === "string" ? args.supersedes : undefined;
+    const slug = typeof args.slug === "string" ? args.slug : undefined;
+    if (slug) {
+        const content = readYield(repoRoot, slug);
+        if (content === null)
+            return { err: `Yield not found for slug: ${slug}` };
+        return {
+            input: {
+                name: slug,
+                description: deriveDescription(content, slug),
+                body: content,
+                produced_by: "curate",
+                ...(audience ? { audience } : {}),
+                ...(supersedes ? { supersedes } : {}),
+            },
+        };
+    }
+    const name = args.name;
+    const description = args.description;
+    const body = args.body;
+    if (!name || !description || !body) {
+        return { err: "Provide either a `slug` (of a .harvest yield) or explicit name + description + body." };
+    }
+    return {
+        input: {
+            name, description, body, produced_by: "curate",
+            ...(audience ? { audience } : {}),
+            ...(supersedes ? { supersedes } : {}),
+        },
+    };
+}
+export async function dispatchCurate(args, ctx) {
+    const method = args.method;
+    const storage = corpusStore(ctx.repoRoot);
+    switch (method) {
+        case "advise": {
+            // Pre-flight the lib's validation WITHOUT writing — surface the contract to the agent.
+            const { input, err } = atomInputFromArgs(ctx.repoRoot, args);
+            if (err || !input)
+                return error(err ?? "invalid input", { _tip: 'curate(method="advise", slug="…").' });
+            const v = validate({ op: "publish", atom: input });
+            if (v.valid) {
+                return success({ advice: "valid", name: input.name }, {
+                    _next_step: `curate(method="publish", slug="${args.slug ?? input.name}") to memorialize it.`,
+                });
+            }
+            return {
+                status: "analysis",
+                summary: "Yield fails atom-kernel validation — fix before publishing.",
+                issues: v.errors,
+                next_steps: ["Fix the listed issues, then re-run curate(advise)."],
+                _warning: "Validation is enforced by the atom kernel; publish would be rejected.",
+            };
+        }
+        case "publish":
+        case "supersede": {
+            const { input, err } = atomInputFromArgs(ctx.repoRoot, args);
+            if (err || !input) {
+                return error(err ?? "invalid input", {
+                    _tip: 'curate(method="publish", slug="…"), or pass name/description/body. supersede also needs `supersedes`.',
+                });
+            }
+            if (method === "supersede" && !input.supersedes) {
+                return error("supersede requires `supersedes` (the atom id being superseded).", {
+                    _tip: 'curate(method="supersede", slug="…", supersedes="atom:…").',
+                });
+            }
+            try {
+                const res = await submitChanges({ op: "publish", atom: input }, { storage });
+                return success({ id: res.id, curate_status: res.status, name: input.name, audience: res.atom?.audience }, {
+                    _next_step: 'retrieve(method="search", query="…") — the atom is now in the local corpus.',
+                    _tip: res.status === "deduplicated"
+                        ? "Identical content already memorialized — content-addressed dedup (no-op)."
+                        : "Memorialized to the local corpus (swap StorageBackend for GCS org-wide).",
+                });
+            }
+            catch (e) {
+                if (e instanceof ValidationError) {
+                    return {
+                        status: "analysis",
+                        summary: "Validation failed (enforced by the atom kernel).",
+                        issues: e.errors,
+                        next_steps: ["Fix the issues, then re-run curate."],
+                    };
+                }
+                return error(e instanceof Error ? e.message : String(e));
+            }
+        }
+        case "status":
+            return success({ wired: true }, { _tip: "curate → atom-kernel submitChanges (local corpus StorageBackend)." });
+        case undefined:
+            return clarificationNeeded("Which operation?", ["publish", "supersede", "advise", "status"], {
+                _tip: 'e.g. curate(method="publish", slug="my-slug").',
+            });
+        default:
+            return error(`Unknown method: ${method}`, { _tip: "curate supports: publish, supersede, advise, status." });
+    }
+}

package/dist/mcp/handlers/retrieve/adapter.js

@@ -0,0 +1,12 @@
+import { findRepoRoot } from "../../state.js";
+import { dispatchRetrieve } from "./index.js";
+/**
+ * Retrieve — search/rank the corpus. Adapter: resolve context (repo root), delegate.
+ * LOCAL .harvest retrieval (via the owned atom kernel) works offline, with or
+ * without DE; org-wide search COMPOSES with the ema toolkit's knowledge() — not a
+ * rebuilt DE client (the scar tissue the harvest set out to avoid).
+ */
+export async function handleRetrieve(args) {
+    const ctx = { repoRoot: findRepoRoot(process.cwd()) };
+    return dispatchRetrieve(args, ctx);
+}

package/dist/mcp/handlers/retrieve/index.js

@@ -0,0 +1,63 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { buildAtom, search, StoreScanRetrieval } from "../../atom/index.js";
+import { clarificationNeeded, error, list } from "../../responses.js";
+import { HARVEST, corpusStore, deriveDescription, readYield } from "../corpus.js";
+/** Load curated atoms + raw yields into a DE-free retrieval index (content-addressed dedup). */
+async function loadCorpus(repoRoot) {
+    const retrieval = new StoreScanRetrieval();
+    const ids = new Set();
+    // 1) curated atoms (curate output; GcsStorageBackend in org-wide mode)
+    for (const atom of await corpusStore(repoRoot).list()) {
+        await retrieval.index(atom);
+        ids.add(atom.id);
+    }
+    // 2) raw .harvest yields as atoms (always-available local corpus)
+    const root = join(repoRoot, HARVEST);
+    if (existsSync(root)) {
+        for (const d of readdirSync(root, { withFileTypes: true })) {
+            if (!d.isDirectory() || d.name.startsWith("."))
+                continue;
+            const content = readYield(repoRoot, d.name);
+            if (content === null)
+                continue;
+            const atom = buildAtom({
+                name: d.name,
+                description: deriveDescription(content, d.name),
+                body: content,
+                audience: "internal",
+                produced_by: "harvest",
+            });
+            await retrieval.index(atom);
+            ids.add(atom.id);
+        }
+    }
+    return { retrieval, count: ids.size };
+}
+export async function dispatchRetrieve(args, ctx) {
+    const method = args.method ?? "search";
+    if (method !== "search") {
+        return error(`Unknown method: ${method}`, { _tip: "retrieve supports: search." });
+    }
+    const query = args.query;
+    if (!query || query.trim() === "") {
+        return clarificationNeeded("What should I search the corpus for?", [], {
+            _tip: 'retrieve(method="search", query="…").',
+        });
+    }
+    const limit = typeof args.limit === "number" ? args.limit : 10;
+    const audience = Array.isArray(args.audience) ? args.audience : ["public", "internal"];
+    const { retrieval, count } = await loadCorpus(ctx.repoRoot);
+    const hits = await search(query, { audience, limit }, { retrieval });
+    const results = hits.map((h) => ({ slug: h.name, score: Number(h.score.toFixed(3)), description: h.description }));
+    const top = results[0];
+    return {
+        ...list("results", results, {
+            _next_step: top
+                ? `yield(method="get", slug="${top.slug}") to read the top hit.`
+                : "No local hits — broaden the query, or compose with the ema toolkit's knowledge() for org-wide search.",
+            _tip: `Searched ${count} local atoms (curated + .harvest yields; audience: ${audience.join(", ")}). Org-wide composes with ema-toolkit knowledge() (DE).`,
+        }),
+        composes_with: ["ema-toolkit:knowledge()"],
+    };
+}

package/dist/mcp/handlers/yield/adapter.js

@@ -0,0 +1,7 @@
+import { findRepoRoot } from "../../state.js";
+import { dispatchYield } from "./index.js";
+/** Adapter: resolve context (repo root). Thin. */
+export async function handleYield(args) {
+    const ctx = { repoRoot: findRepoRoot(process.cwd()) };
+    return dispatchYield(args, ctx);
+}

package/dist/mcp/handlers/yield/formatters.js

@@ -0,0 +1,11 @@
+import { analysis, success } from "../../responses.js";
+/** Validation result — RETURNED, never thrown, so the agent's guidance loop stays steerable. */
+export function formatValidate(ok, path, detail) {
+    if (ok) {
+        return success({ valid: true, path, validator_output: detail }, { _tip: "Yield conforms to the contract." });
+    }
+    return analysis(`Yield failed validation: ${path}`, [{ severity: "critical", message: detail }], ["Fix the reported issues", 'Re-run yield(method="validate", slug="…")'], {
+        _warning: "The yield does NOT conform to the contract — treat it as not accepted.",
+        _fix: detail,
+    });
+}

package/dist/mcp/handlers/yield/index.js

@@ -0,0 +1,98 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { clarificationNeeded, error, list, singleItem, success } from "../../responses.js";
+import { VALIDATOR_REL } from "../../state.js";
+import { formatValidate } from "./formatters.js";
+const HARVEST = ".harvest";
+const ASSET_REL = "skills/harvest/assets/harvest-yield.example.md";
+function yieldPath(repoRoot, slug) {
+    return join(repoRoot, HARVEST, slug, "harvest-yield.md");
+}
+/** Dispatch by explicit `method`. The agent runs the harvest PROCEDURE; this tool
+ * manages the yield ARTIFACTS it produces (deterministic execution). */
+export async function dispatchYield(args, ctx) {
+    const method = args.method;
+    const { repoRoot } = ctx;
+    const slug = args.slug;
+    switch (method) {
+        case "validate": {
+            const path = args.path ?? (slug ? yieldPath(repoRoot, slug) : undefined);
+            if (!path)
+                return error("validate needs a slug or path", { _tip: 'yield(method="validate", slug="my-slug").' });
+            if (!existsSync(path))
+                return error(`Yield not found: ${path}`, { _tip: 'Check the slug, or yield(method="list").' });
+            // ── Blocking validator gate: shell to the CANONICAL validator (single source of
+            // truth). No "PASS" without validator output; the contract is not re-encoded here.
+            try {
+                const out = execFileSync("python3", [join(repoRoot, VALIDATOR_REL), path], { encoding: "utf8" });
+                return formatValidate(true, path, out.trim());
+            }
+            catch (e) {
+                const err = e;
+                const detail = ((err.stdout ?? "") + (err.stderr ?? "")).trim() || err.message || String(e);
+                return formatValidate(false, path, detail);
+            }
+        }
+        case "list": {
+            const root = join(repoRoot, HARVEST);
+            if (!existsSync(root))
+                return error(`.harvest/ not found under ${repoRoot}`, { _tip: "Run from the eMachina repo root." });
+            const slugs = readdirSync(root, { withFileTypes: true })
+                .filter((d) => d.isDirectory() && existsSync(yieldPath(repoRoot, d.name)))
+                .map((d) => d.name);
+            return list("slugs", slugs, { _next_step: 'yield(method="get", slug="…") to read one.' });
+        }
+        case "get": {
+            if (!slug)
+                return error("get needs a slug", { _tip: 'yield(method="get", slug="my-slug").' });
+            const path = yieldPath(repoRoot, slug);
+            if (!existsSync(path))
+                return error(`Yield not found for slug: ${slug}`, { _tip: 'yield(method="list") to see available slugs.' });
+            return singleItem("yield", { slug, path, content: readFileSync(path, "utf8") });
+        }
+        case "scaffold": {
+            if (!slug)
+                return error("scaffold needs a slug", { _tip: 'yield(method="scaffold", slug="my-new-slug").' });
+            const path = yieldPath(repoRoot, slug);
+            if (existsSync(path))
+                return error(`Yield already exists for slug: ${slug}`, { _tip: "Pick a new slug, or get the existing one." });
+            let content;
+            try {
+                content = scaffoldFromAsset(repoRoot, slug);
+            }
+            catch (e) {
+                return error(e instanceof Error ? e.message : String(e), {
+                    _tip: "Run from the eMachina repo root so the canonical skeleton is reachable.",
+                });
+            }
+            mkdirSync(join(repoRoot, HARVEST, slug), { recursive: true });
+            writeFileSync(path, content);
+            return success({ slug, path }, {
+                _next_step: `Fill the placeholders (Ask/Why/Goals/Findings/Sources), then yield(method="validate", slug="${slug}").`,
+                _warning: "Scaffold copies the canonical skeleton — the agent authors the content (the MCP never invents findings).",
+            });
+        }
+        case undefined:
+            return clarificationNeeded("Which operation?", ["validate", "list", "get", "scaffold"], {
+                _tip: 'e.g. yield(method="list").',
+            });
+        default:
+            return error(`Unknown method: ${method}`, { _tip: "yield supports: validate, list, get, scaffold." });
+    }
+}
+/**
+ * Build a new yield from the CANONICAL skeleton asset — don't re-encode the contract.
+ * Substitute the derived `name` (= slug) and drop the asset's illustrative (future-dated)
+ * `updated` line (optional per the validator; the write hook / author stamps the real clock).
+ * No hardcoded fallback: if the asset is missing we error rather than drift.
+ */
+function scaffoldFromAsset(repoRoot, slug) {
+    const assetPath = join(repoRoot, ASSET_REL);
+    if (!existsSync(assetPath)) {
+        throw new Error(`Canonical yield skeleton not found at ${ASSET_REL} — cannot scaffold without it (no hardcoded fallback, to avoid contract drift).`);
+    }
+    return readFileSync(assetPath, "utf8")
+        .replace(/^name:.*$/m, `name: ${slug}`)
+        .replace(/^[ \t]*updated:.*\r?\n/m, "");
+}

package/dist/mcp/middleware.js

@@ -0,0 +1,14 @@
+import { getState } from "./state.js";
+export function enrichWithState(result, _ctx) {
+    try {
+        const state = getState();
+        // ??= — never clobber a hint the handler already set (e.g. config's own list).
+        if (state.requiredNextSteps.length > 0) {
+            result._required_next_steps ??= state.requiredNextSteps;
+        }
+    }
+    catch {
+        // Best-effort guidance. Swallow — never break dispatch.
+    }
+    return result;
+}

package/dist/mcp/responses.js

@@ -0,0 +1,41 @@
+/**
+ * Response standards — fixed categories + advisory hints.
+ *
+ * The MCP returns DATA in these shapes; the agent orchestrates. Two hard rules
+ * from the ema-mcp-toolkit disciplines (see .harvest/mcp-build-principles):
+ *   1. Errors are RETURNED, never thrown — throwing breaks the agent's guidance loop.
+ *   2. `_`-prefixed hints steer the agent through multi-step flows and are NEVER
+ *      part of the primary result data.
+ */
+export function success(data = {}, hints = {}) {
+    return { status: "success", ...data, ...hints };
+}
+/** Returned, not thrown. */
+export function error(message, hints = {}) {
+    return { status: "error", error: message, ...hints };
+}
+export function clarificationNeeded(message, options, hints = {}) {
+    return { status: "clarification_needed", message, options, ...hints };
+}
+export function analysis(summary, issues, next_steps, hints = {}) {
+    return { status: "analysis", summary, issues, next_steps, ...hints };
+}
+export function list(key, items, hints = {}) {
+    return { status: "list", count: items.length, [key]: items, ...hints };
+}
+export function singleItem(key, item, hints = {}) {
+    return { status: "single_item", [key]: item, ...hints };
+}
+/**
+ * A capability that isn't wired yet — honest, categorized, state-aware.
+ * Used for capabilities declared but not yet wired.
+ */
+export function pending(capability, reason, hints = {}) {
+    return {
+        status: "pending",
+        capability,
+        reason,
+        _warning: `${capability} is not wired yet: ${reason}`,
+        ...hints,
+    };
+}