@gaia-ai/core 0.5.4 → 0.6.0

package/dist/src/workflow/step-contract.d.ts

@@ -0,0 +1,119 @@
+/** The workflow states an agent works — the legal `step` values. */
+export declare const WORKFLOW_STEPS: readonly ["qualification", "spec", "diagnose", "coding", "review", "pre_deployment", "post_deployment", "verifying", "summary"];
+export type WorkflowStep = (typeof WORKFLOW_STEPS)[number];
+/** Typed defect raised on the first contract violation. */
+export declare class StepContractError extends Error {
+    constructor(message: string);
+}
+/**
+ * A normalized `when` clause value: a concrete list of allowed values, the
+ * wildcard `'*'` (matches anything), or `undefined` (key omitted — also any).
+ */
+export type WhenValue = string[] | '*' | undefined;
+/** A skill's `when` triple. Any of the three keys may be omitted (= any). */
+export interface SkillWhen {
+    work_type: WhenValue;
+    workflow: WhenValue;
+    step: WhenValue;
+}
+/** One declared input: a value key with a short description and an optional default. */
+export interface InputDecl {
+    /** The value key the skill reads (e.g. `test.command`). */
+    key: string;
+    /** A short human description of what the value is. */
+    description?: string;
+    /** The default used when `WORKFLOW.md` supplies no override for this key. */
+    default?: string;
+}
+/** The parsed contract of a single skill's frontmatter. */
+export interface SkillContract {
+    /** Skill name from frontmatter. */
+    name: string;
+    /**
+     * The `when` triple, or `undefined` when the skill declares no `when` — a
+     * helper/capability skill that owns no step and routes nothing.
+     */
+    when?: SkillWhen;
+    /** The inputs the skill declares (each: key + description + optional default). */
+    inputs: InputDecl[];
+    /**
+     * A **bundle** skill carries its own `## Loaded skills` section in its markdown
+     * **body** — the same list a `WORKFLOW.md` carries. `loads` holds those member
+     * names in declared order. Nothing in the frontmatter marks a bundle; the
+     * section is the marker. Present only on bundles.
+     */
+    loads?: string[];
+    /**
+     * A bundle's member values: the inline `key: value` overrides written under a
+     * member's bullet in the bundle body, keyed by member skill name. Present only
+     * on bundles.
+     */
+    values?: StepValues;
+}
+/**
+ * A concrete `(work_type, workflow, step)` the project can produce. `work_type`
+ * is `null` for a non-work-typed step (qualification, spec, deployment,
+ * verification), a `work:*` label (without the prefix) otherwise.
+ */
+export interface Triple {
+    work_type: string | null;
+    workflow: string;
+    step: WorkflowStep;
+}
+/** Per-skill values, keyed by skill `name` (the `@gaia/` prefix stripped). */
+export type StepValues = Record<string, Record<string, string>>;
+/**
+ * Read the per-skill value **overrides** from a `WORKFLOW.md`'s `## Loaded skills`
+ * section. A project overrides a skill default **inline under that skill's bullet**
+ * (indented `key: value` YAML, block scalars allowed), not in one global block.
+ * Returns a map keyed by skill `name` (the `@gaia/` prefix stripped); a skill with no
+ * overrides maps to `{}` (it runs on its declared defaults).
+ */
+export declare function parseStepValues(workflowMd: string): StepValues;
+/**
+ * Parse a skill's frontmatter into its `SkillContract` — the `when` triple (when
+ * present) and the declared `inputs`. Malformed frontmatter raises `StepContractError`.
+ */
+export declare function readSkillWhen(skillMd: string): SkillContract;
+/** What a load expands to: the flat leaf skills plus the values that reached them. */
+export interface ExpandedLoad {
+    /** The leaf skills (step-owners + helpers), deduplicated, in first-seen order. */
+    skills: SkillContract[];
+    /** The effective per-skill values, keyed by skill name. */
+    values: StepValues;
+}
+/**
+ * Read a `WORKFLOW.md` and expand what it loads into the flat, deduplicated list of
+ * **leaf** skills (step-owners + helpers) the project effectively runs, together with
+ * the values that reach each leaf. One call is the whole load step: parse, expand,
+ * resolve — hand the result straight to `validateLoad`.
+ *
+ * A **bundle** — a skill whose markdown body carries its own `## Loaded skills`
+ * section, so its contract carries `loads` — is recursed into, in its declared
+ * member order; a step-owner or helper is emitted as itself. Leaves are
+ * deduplicated **by name, first occurrence wins**, so the result is deterministic
+ * and idempotent — listing the same bundle twice, or a bundle plus one of its
+ * members as an explicit bullet, yields each leaf exactly once in first-seen order.
+ *
+ * **Value precedence**, narrowest wins: the project's own inline override in
+ * `WORKFLOW.md` beats a bundle's inline value for that member, which beats the
+ * skill's declared `default` (resolved later, in `validateLoad`). Between nested
+ * bundles the outermost wins, matching first-occurrence dedup.
+ *
+ * A root or member name absent from `byName`, or a cycle in the bundle graph,
+ * raises a typed `StepContractError`. Bundles may nest (cycle-safe); gaia ships one
+ * flat level. This never dispatches or routes.
+ */
+export declare function expandLoad(workflowMd: string, byName: Map<string, SkillContract>): ExpandedLoad;
+/**
+ * Validate a loaded set of skills against the project's triple set and per-skill values.
+ *
+ * For every `(work_type, workflow, step)` the project can produce, **exactly one**
+ * loaded skill's `when` must match — a triple with no match (gap) or two matches
+ * (collision) is a configuration error. Every `input` a matched skill declares must
+ * resolve to a value: the `values` map (as resolved by `expandLoad`) or the input's
+ * own declared `default`.
+ *
+ * Reports the first defect as a typed `StepContractError`. Never dispatches or routes.
+ */
+export declare function validateLoad(skills: SkillContract[], values: StepValues, projectTriples: Triple[]): void;

package/dist/src/workflow/step-contract.js

@@ -0,0 +1,430 @@
+/**
+ * GAIA-204 — workflow step contract (pure library).
+ *
+ * "Everything is a skill; `WORKFLOW.md` is a pure loader." Each step-owning skill
+ * self-declares one `when:` over three variables — `work_type`, `workflow`, `step` —
+ * and owns that step's whole flow in prose. Each skill declares its `inputs` (a short
+ * description + a default per value); a project overrides a value inline under the
+ * skill's bullet in `WORKFLOW.md`'s `## Loaded skills` list. Effective value =
+ * override ?? default.
+ *
+ * A **bundle** skill carries a `## Loaded skills` section in its own body and thereby
+ * loads further skills — the same section, the same bullet syntax, the same parser as
+ * `WORKFLOW.md`. Nothing in the frontmatter marks it; the section is the marker.
+ *
+ * This module is the mechanical enforcement of that model. It PARSES, EXPANDS along
+ * a fixed value precedence, and VALIDATES — it never dispatches or routes.
+ * Its only consumers are the contract test suite and `@gaia/upgrade-project` /
+ * `@gaia/initialize-project` load-time validation.
+ */
+import { parse as parseYaml } from 'yaml';
+/** The workflow states an agent works — the legal `step` values. */
+export const WORKFLOW_STEPS = [
+    'qualification',
+    'spec',
+    'diagnose',
+    'coding',
+    'review',
+    'pre_deployment',
+    'post_deployment',
+    'verifying',
+    'summary',
+];
+/** Typed defect raised on the first contract violation. */
+export class StepContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'StepContractError';
+    }
+}
+const LOADED_SKILLS_HEADING = /^##\s+Loaded skills\s*$/;
+const BULLET = /^\s*-\s+@gaia\/([a-z0-9-]+)\s*$/;
+/**
+ * Locate the `## Loaded skills` section in a markdown document: the `[start, end)`
+ * line range of its body, or `null` when the document carries no such section.
+ *
+ * The section is the **only** marker of a loader — `WORKFLOW.md` carries one, and so
+ * does a **bundle** skill whose body loads further skills. Nothing else distinguishes
+ * the two.
+ */
+function loadedSkillsRange(lines) {
+    const start = lines.findIndex((l) => LOADED_SKILLS_HEADING.test(l));
+    if (start === -1)
+        return null;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^##\s+/.test(lines[i] ?? '')) {
+            end = i;
+            break;
+        }
+    }
+    return [start, end];
+}
+/**
+ * Read the per-skill value **overrides** from a `WORKFLOW.md`'s `## Loaded skills`
+ * section. A project overrides a skill default **inline under that skill's bullet**
+ * (indented `key: value` YAML, block scalars allowed), not in one global block.
+ * Returns a map keyed by skill `name` (the `@gaia/` prefix stripped); a skill with no
+ * overrides maps to `{}` (it runs on its declared defaults).
+ */
+export function parseStepValues(workflowMd) {
+    return parseLoadedSection(workflowMd).values;
+}
+/**
+ * Scan a `## Loaded skills` section once and return both what it lists and what it
+ * sets. Order and values come from the same pass, so they can never disagree — the
+ * reason there is no separate name-only parser.
+ *
+ * Works on any document carrying the section: a project's `WORKFLOW.md` and a
+ * **bundle** skill's markdown body are read by the exact same call.
+ */
+function parseLoadedSection(workflowMd) {
+    const lines = workflowMd.split('\n');
+    const range = loadedSkillsRange(lines);
+    if (range === null) {
+        throw new StepContractError('WORKFLOW.md has no `## Loaded skills` section; a pure loader must carry one.');
+    }
+    const [start, end] = range;
+    const names = [];
+    const values = {};
+    let current = null;
+    let childIndent = null;
+    let buffer = [];
+    const flush = () => {
+        if (current === null)
+            return;
+        const yamlText = buffer.join('\n').trim();
+        if (yamlText === '') {
+            values[current] = {};
+        }
+        else {
+            let parsed;
+            try {
+                parsed = parseYaml(yamlText);
+            }
+            catch (cause) {
+                throw new StepContractError(`inline values for \`${current}\` are not valid YAML: ${cause.message}`);
+            }
+            if (parsed == null ||
+                typeof parsed !== 'object' ||
+                Array.isArray(parsed)) {
+                throw new StepContractError(`inline values for \`${current}\` must be a map of value keys to values.`);
+            }
+            const inner = {};
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v !== 'string') {
+                    throw new StepContractError(`inline value \`${current}.${k}\` must be a string.`);
+                }
+                inner[k] = v;
+            }
+            values[current] = inner;
+        }
+        buffer = [];
+        childIndent = null;
+    };
+    for (const raw of lines.slice(start + 1, end)) {
+        const bullet = BULLET.exec(raw);
+        if (bullet) {
+            flush();
+            current = bullet[1] ?? null;
+            if (current !== null)
+                names.push(current);
+            continue;
+        }
+        if (current === null)
+            continue; // prose before the first bullet
+        if (raw.trim() === '') {
+            buffer.push('');
+            continue;
+        }
+        const indent = raw.length - raw.trimStart().length;
+        if (indent === 0) {
+            // dedented prose after the list ends the current skill's values
+            flush();
+            current = null;
+            continue;
+        }
+        if (childIndent === null)
+            childIndent = indent;
+        buffer.push(raw.slice(Math.min(childIndent, indent)));
+    }
+    flush();
+    return { names, values };
+}
+/** Split leading YAML frontmatter (`---` … `---`) from a skill markdown body. */
+function readFrontmatter(skillMd) {
+    const match = /^---\n([\s\S]*?)\n---\s*(?:\n|$)/.exec(skillMd);
+    if (!match) {
+        throw new StepContractError('skill markdown has no YAML frontmatter.');
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(match[1] ?? '');
+    }
+    catch (cause) {
+        throw new StepContractError(`skill frontmatter is not valid YAML: ${cause.message}`);
+    }
+    if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new StepContractError('skill frontmatter must be a YAML map.');
+    }
+    return parsed;
+}
+/** Normalize a raw `when` value (string / list / `*` / omitted) to a `WhenValue`. */
+function normalizeWhenValue(raw, key) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (raw === '*')
+        return '*';
+    if (typeof raw === 'string')
+        return [raw];
+    if (Array.isArray(raw)) {
+        if (raw.some((v) => typeof v !== 'string')) {
+            throw new StepContractError(`\`when.${key}\` list must contain only strings.`);
+        }
+        if (raw.length === 0) {
+            throw new StepContractError(`\`when.${key}\` list must not be empty.`);
+        }
+        return raw;
+    }
+    throw new StepContractError(`\`when.${key}\` must be a string, a list of strings, \`*\`, or omitted.`);
+}
+/**
+ * Parse a skill's frontmatter into its `SkillContract` — the `when` triple (when
+ * present) and the declared `inputs`. Malformed frontmatter raises `StepContractError`.
+ */
+export function readSkillWhen(skillMd) {
+    const fm = readFrontmatter(skillMd);
+    const name = fm.name;
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new StepContractError('skill frontmatter must declare a string `name`.');
+    }
+    let when;
+    if (fm.when !== undefined) {
+        if (fm.when === null ||
+            typeof fm.when !== 'object' ||
+            Array.isArray(fm.when)) {
+            throw new StepContractError(`\`${name}\`: \`when\` must be a map.`);
+        }
+        const raw = fm.when;
+        const allowed = new Set(['work_type', 'workflow', 'step']);
+        for (const k of Object.keys(raw)) {
+            if (!allowed.has(k)) {
+                throw new StepContractError(`\`${name}\`: \`when.${k}\` is not a recognized key (work_type, workflow, step).`);
+            }
+        }
+        const step = normalizeWhenValue(raw.step, 'step');
+        if (Array.isArray(step)) {
+            for (const s of step) {
+                if (!WORKFLOW_STEPS.includes(s)) {
+                    throw new StepContractError(`\`${name}\`: \`when.step\` value \`${s}\` is not a known workflow step.`);
+                }
+            }
+        }
+        when = {
+            work_type: normalizeWhenValue(raw.work_type, 'work_type'),
+            workflow: normalizeWhenValue(raw.workflow, 'workflow'),
+            step,
+        };
+    }
+    const isBundle = loadedSkillsRange(skillMd.split('\n')) !== null;
+    if (isBundle) {
+        if (when !== undefined) {
+            throw new StepContractError(`\`${name}\`: a bundle loads skills in its body and owns no step — it must declare no \`when\`.`);
+        }
+        if (fm.inputs !== undefined) {
+            throw new StepContractError(`\`${name}\`: a bundle declares no \`inputs\` — it carries values for its members, it takes none itself.`);
+        }
+    }
+    const inputs = readInputs(fm.inputs, name);
+    const contract = { name, inputs };
+    if (when !== undefined)
+        contract.when = when;
+    if (isBundle) {
+        const section = parseLoadedSection(skillMd);
+        if (section.names.length === 0) {
+            throw new StepContractError(`\`${name}\`: the \`## Loaded skills\` section lists no skill.`);
+        }
+        contract.loads = section.names;
+        contract.values = section.values;
+    }
+    return contract;
+}
+/**
+ * Parse the `inputs` declaration. Each input is a value key with a short
+ * `description` and an optional `default` (used when `WORKFLOW.md` supplies no
+ * override). The map form is canonical:
+ *
+ * ```yaml
+ * inputs:
+ *   test.command:
+ *     description: shell command that runs the e2e suite
+ *     default: ddev gaia-test-e2e
+ * ```
+ *
+ * A bare string value is shorthand for `{ description: <string> }`, and a plain
+ * list of keys (`inputs: [a, b]`) is accepted for description-less inputs.
+ */
+function readInputs(raw, name) {
+    if (raw === undefined)
+        return [];
+    if (Array.isArray(raw)) {
+        return raw.map((k) => {
+            if (typeof k !== 'string') {
+                throw new StepContractError(`\`${name}\`: \`inputs\` list items must be strings.`);
+            }
+            return { key: k };
+        });
+    }
+    if (raw === null || typeof raw !== 'object') {
+        throw new StepContractError(`\`${name}\`: \`inputs\` must be a map of key → { description, default } (or a list of keys).`);
+    }
+    const decls = [];
+    for (const [key, spec] of Object.entries(raw)) {
+        if (typeof spec === 'string') {
+            decls.push({ key, description: spec });
+            continue;
+        }
+        if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+            throw new StepContractError(`\`${name}\`: input \`${key}\` must be a string or a { description, default } map.`);
+        }
+        const s = spec;
+        if (s.description !== undefined && typeof s.description !== 'string') {
+            throw new StepContractError(`\`${name}\`: input \`${key}\`.description must be a string.`);
+        }
+        if (s.default !== undefined && typeof s.default !== 'string') {
+            throw new StepContractError(`\`${name}\`: input \`${key}\`.default must be a string.`);
+        }
+        const decl = { key };
+        if (typeof s.description === 'string')
+            decl.description = s.description;
+        if (typeof s.default === 'string')
+            decl.default = s.default;
+        decls.push(decl);
+    }
+    return decls;
+}
+/** Does a normalized `when` value match a triple component? */
+function componentMatches(whenVal, tripleVal) {
+    if (whenVal === undefined || whenVal === '*')
+        return true;
+    if (tripleVal === null)
+        return false;
+    return whenVal.includes(tripleVal);
+}
+/** Does a skill's `when` triple match a concrete project triple? */
+function matchesTriple(when, triple) {
+    return (componentMatches(when.work_type, triple.work_type) &&
+        componentMatches(when.workflow, triple.workflow) &&
+        componentMatches(when.step, triple.step));
+}
+function tripleLabel(triple) {
+    return `(${triple.work_type ?? '—'}, ${triple.workflow}, ${triple.step})`;
+}
+/**
+ * Read a `WORKFLOW.md` and expand what it loads into the flat, deduplicated list of
+ * **leaf** skills (step-owners + helpers) the project effectively runs, together with
+ * the values that reach each leaf. One call is the whole load step: parse, expand,
+ * resolve — hand the result straight to `validateLoad`.
+ *
+ * A **bundle** — a skill whose markdown body carries its own `## Loaded skills`
+ * section, so its contract carries `loads` — is recursed into, in its declared
+ * member order; a step-owner or helper is emitted as itself. Leaves are
+ * deduplicated **by name, first occurrence wins**, so the result is deterministic
+ * and idempotent — listing the same bundle twice, or a bundle plus one of its
+ * members as an explicit bullet, yields each leaf exactly once in first-seen order.
+ *
+ * **Value precedence**, narrowest wins: the project's own inline override in
+ * `WORKFLOW.md` beats a bundle's inline value for that member, which beats the
+ * skill's declared `default` (resolved later, in `validateLoad`). Between nested
+ * bundles the outermost wins, matching first-occurrence dedup.
+ *
+ * A root or member name absent from `byName`, or a cycle in the bundle graph,
+ * raises a typed `StepContractError`. Bundles may nest (cycle-safe); gaia ships one
+ * flat level. This never dispatches or routes.
+ */
+export function expandLoad(workflowMd, byName) {
+    const { names: rootNames, values: workflowValues } = parseLoadedSection(workflowMd);
+    const skills = [];
+    const emitted = new Set();
+    const values = {};
+    /** Record values for `name` without overwriting a narrower source already set. */
+    const contribute = (name, from) => {
+        values[name] ??= {};
+        const target = values[name];
+        for (const [k, v] of Object.entries(from)) {
+            if (!(k in target))
+                target[k] = v;
+        }
+    };
+    const walk = (name, stack) => {
+        const skill = byName.get(name);
+        if (skill === undefined) {
+            const via = stack.length > 0
+                ? `bundle \`${stack[stack.length - 1]}\` loads unknown skill \`${name}\``
+                : `loaded skill \`${name}\` not found`;
+            throw new StepContractError(`${via}.`);
+        }
+        if (skill.loads !== undefined) {
+            if (stack.includes(name)) {
+                throw new StepContractError(`cyclic skill bundle: ${[...stack, name].join(' → ')}.`);
+            }
+            if (Object.keys(workflowValues[name] ?? {}).length > 0) {
+                throw new StepContractError(`bundle \`${name}\` takes no inline values of its own — write the value under the member skill's own bullet.`);
+            }
+            // The bundle's own inline values reach its members, but never beat an
+            // override the project wrote in WORKFLOW.md (contributed first, below).
+            for (const [member, memberValues] of Object.entries(skill.values ?? {})) {
+                contribute(member, memberValues);
+            }
+            for (const member of skill.loads)
+                walk(member, [...stack, name]);
+            return;
+        }
+        if (emitted.has(name))
+            return;
+        emitted.add(name);
+        skills.push(skill);
+    };
+    // WORKFLOW.md's own overrides are contributed first, so they win every tie.
+    for (const [name, own] of Object.entries(workflowValues))
+        contribute(name, own);
+    for (const name of rootNames)
+        walk(name, []);
+    return { skills, values };
+}
+/**
+ * Validate a loaded set of skills against the project's triple set and per-skill values.
+ *
+ * For every `(work_type, workflow, step)` the project can produce, **exactly one**
+ * loaded skill's `when` must match — a triple with no match (gap) or two matches
+ * (collision) is a configuration error. Every `input` a matched skill declares must
+ * resolve to a value: the `values` map (as resolved by `expandLoad`) or the input's
+ * own declared `default`.
+ *
+ * Reports the first defect as a typed `StepContractError`. Never dispatches or routes.
+ */
+export function validateLoad(skills, values, projectTriples) {
+    const owners = skills.filter((s) => s.when !== undefined);
+    for (const triple of projectTriples) {
+        const matched = owners.filter((s) => matchesTriple(s.when, triple));
+        if (matched.length === 0) {
+            throw new StepContractError(`no skill matches triple ${tripleLabel(triple)} — coverage gap.`);
+        }
+        if (matched.length > 1) {
+            throw new StepContractError(`${matched.length} skills match triple ${tripleLabel(triple)} — collision: ${matched
+                .map((s) => s.name)
+                .join(', ')}.`);
+        }
+        const owner = matched[0];
+        if (owner.inputs.length === 0)
+            continue;
+        const overrides = values[owner.name];
+        for (const input of owner.inputs) {
+            const effective = overrides?.[input.key] ?? input.default;
+            if (effective === undefined) {
+                const desc = input.description ? ` (${input.description})` : '';
+                throw new StepContractError(`skill \`${owner.name}\` input \`${input.key}\`${desc} has no value: WORKFLOW.md sets no override and the skill declares no default (needed for triple ${tripleLabel(triple)}).`);
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/core",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "GAIA global contract: plugin API, built-in remotes/workspaces/auth, shared primitives.",
   "type": "module",
   "license": "MIT",
@@ -10,10 +10,13 @@
   "exports": {
     ".": "./dist/src/index.js",
     "./plugins": "./dist/src/plugins-index.js",
+    "./builtins": "./dist/src/plugins/builtins-preset.js",
+    "./conductor-registry": "./dist/src/conductor-registry/index.js",
     "./package.json": "./package.json"
   },
   "files": [
     "dist/src",
+    "gaia.config.js",
     "README.md",
     "LICENSE"
   ],
@@ -23,11 +26,14 @@
   "repository": {
     "type": "git",
     "url": "git+https://git.key-tec.de/keytec/gaia.git",
-    "directory": "conductor/packages/core"
+    "directory": "conductor/core"
   },
   "dependencies": {
-    "dropsh": "^0.5.7",
+    "@dropsh/plugin-oauth2": "^0.5.7",
+    "commander": "^12.1.0",
+    "dropsh": "^0.5.8",
     "pino": "^9.6.0",
-    "pino-pretty": "^13.0.0"
+    "pino-pretty": "^13.0.0",
+    "yaml": "^2.7.0"
   }
 }