@gaia-ai/core 0.6.0 → 0.6.2

package/README.md

@@ -1,5 +1,5 @@
 # @gaia-ai/core
 
-GAIA global contract: plugin API, built-in remotes/workspaces/auth, shared primitives.
+GAIA surface-agnostic kernel: host contract, split-config helpers, addon preset/discovery machinery, shared primitives.
 
-Part of the GAIA conductor. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all plugins. Source: https://git.key-tec.de/keytec/gaia (conductor/).
+Part of the GAIA CLI. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all addons. Source: https://git.key-tec.de/keytec/gaia (gaia-cli/).

package/dist/src/cli/config-source.d.ts

@@ -0,0 +1,47 @@
+/** Skip a `//`-line comment; return the index of the terminating newline (or EOF). */
+export declare function skipLineComment(src: string, i: number): number;
+/** Skip a block comment; return the index just past it. */
+export declare function skipBlockComment(src: string, i: number): number;
+/** Skip a string/template literal (honouring `\` escapes and `${ … }`
+ *  interpolations in backtick strings); return the index just past the close. */
+export declare function skipString(src: string, i: number): number;
+/** Given the index of an opening `{`/`[`/`(`, return the index of its matching
+ *  close, skipping nested delimiters, strings and comments. -1 if unbalanced. */
+export declare function matchDelimiter(src: string, openIdx: number): number;
+/** Skip whitespace + comments starting at `i` (bounded by `limit`). */
+export declare function skipTrivia(src: string, i: number, limit: number): number;
+/** Read a property key (bare identifier or quoted string) at `i`. */
+export declare function readKey(src: string, i: number): {
+    name?: string;
+    end: number;
+};
+/** From `from`, scan to just past the next top-level `,` (or to `limit` when the
+ *  value runs to the object close), skipping nested delimiters/strings/comments. */
+export declare function scanToTopLevelComma(src: string, from: number, limit: number): number;
+/** One top-level property of a config's default-export object literal. */
+export interface PropEntry {
+    key: string | undefined;
+    /** Start of the entry INCLUDING its leading trivia (comments/whitespace). */
+    start: number;
+    /** End of the entry (just past its trailing comma, or the object close). */
+    end: number;
+}
+/** Locate the `export default { … }` object; return the body span (exclusive of
+ *  the braces) or undefined when the default export is not an object literal. */
+export declare function findDefaultExportObject(src: string): {
+    bodyStart: number;
+    bodyEnd: number;
+} | undefined;
+/** Enumerate the top-level properties of the object body [bodyStart, bodyEnd). */
+export declare function scanTopLevelProperties(src: string, bodyStart: number, bodyEnd: number): PropEntry[];
+/**
+ * Does this config SOURCE declare `key` as a real top-level property of its
+ * `export default { … }` object?
+ *
+ * Deliberately stricter than a `/site\s*:/` regex, which would also fire on the
+ * word in a comment, in a string, or on a NESTED `site:` inside some slot's
+ * `with: { … }`. `false` when the default export is not an object literal at all
+ * (a `defineConfig(…)` call, a re-export shim) — such a file cannot be read as a
+ * connection source by inspection, and guessing is worse than falling through.
+ */
+export declare function declaresTopLevelKey(src: string, key: string): boolean;

package/dist/src/cli/config-source.js

@@ -0,0 +1,197 @@
+// GAIA-230: the balanced-delimiter, comment-aware SOURCE scanner for a config
+// module's `export default { … }` object — hoisted here from the conductor's
+// `config.ts` (where GAIA-218 AC-7's `stripLegacyConnectionFromConfigSource`
+// introduced it) so both users share one source of truth for "which top-level
+// properties does this config source declare?":
+//
+//   - `@gaia-ai/core` — `findGaiaConfig` gates the LEGACY `conductor.config.js`
+//     connection read on CONTENT: a config declaring no `site` is not a
+//     connection source (root cause 2). Core is layer 0 with zero `@gaia-ai/*`
+//     edges, so it cannot import the conductor's copy — hence the hoist.
+//   - `@gaia-ai/conductor` — the strip pass re-uses these primitives.
+//
+// Everything here is a PURE TEXT read. Nothing executes the config module: a
+// config may import a secret-bearing machine context and have side effects, and
+// both callers (a sync path resolver, an idempotent `--dry-run` migration) must
+// stay safe to run on an untrusted tree.
+const CLOSER = { '{': '}', '[': ']', '(': ')' };
+/** Skip a `//`-line comment; return the index of the terminating newline (or EOF). */
+export function skipLineComment(src, i) {
+    const nl = src.indexOf('\n', i);
+    return nl === -1 ? src.length : nl;
+}
+/** Skip a block comment; return the index just past it. */
+export function skipBlockComment(src, i) {
+    const end = src.indexOf('*/', i + 2);
+    return end === -1 ? src.length : end + 2;
+}
+/** Skip a string/template literal (honouring `\` escapes and `${ … }`
+ *  interpolations in backtick strings); return the index just past the close. */
+export function skipString(src, i) {
+    const quote = src[i];
+    i++;
+    while (i < src.length) {
+        const c = src[i];
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if (quote === '`' && c === '$' && src[i + 1] === '{') {
+            i = matchDelimiter(src, i + 1) + 1;
+            continue;
+        }
+        if (c === quote)
+            return i + 1;
+        i++;
+    }
+    return i;
+}
+/** Given the index of an opening `{`/`[`/`(`, return the index of its matching
+ *  close, skipping nested delimiters, strings and comments. -1 if unbalanced. */
+export function matchDelimiter(src, openIdx) {
+    const stack = [CLOSER[src[openIdx]]];
+    let i = openIdx + 1;
+    while (i < src.length && stack.length > 0) {
+        const c = src[i];
+        if (c === '/' && src[i + 1] === '/') {
+            i = skipLineComment(src, i);
+            continue;
+        }
+        if (c === '/' && src[i + 1] === '*') {
+            i = skipBlockComment(src, i);
+            continue;
+        }
+        if (c === "'" || c === '"' || c === '`') {
+            i = skipString(src, i);
+            continue;
+        }
+        if (c === '{' || c === '[' || c === '(') {
+            stack.push(CLOSER[c]);
+            i++;
+            continue;
+        }
+        if (c === '}' || c === ']' || c === ')') {
+            if (c === stack[stack.length - 1])
+                stack.pop();
+            i++;
+            continue;
+        }
+        i++;
+    }
+    return stack.length === 0 ? i - 1 : -1;
+}
+/** Skip whitespace + comments starting at `i` (bounded by `limit`). */
+export function skipTrivia(src, i, limit) {
+    while (i < limit) {
+        const c = src[i];
+        if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+            i++;
+            continue;
+        }
+        if (c === '/' && src[i + 1] === '/') {
+            i = skipLineComment(src, i);
+            continue;
+        }
+        if (c === '/' && src[i + 1] === '*') {
+            i = skipBlockComment(src, i);
+            continue;
+        }
+        break;
+    }
+    return i;
+}
+/** Read a property key (bare identifier or quoted string) at `i`. */
+export function readKey(src, i) {
+    const c = src[i];
+    if (c === "'" || c === '"') {
+        const end = skipString(src, i);
+        return { name: src.slice(i + 1, end - 1), end };
+    }
+    const m = /^[A-Za-z0-9_$]+/.exec(src.slice(i));
+    if (m)
+        return { name: m[0], end: i + m[0].length };
+    return { end: i };
+}
+/** From `from`, scan to just past the next top-level `,` (or to `limit` when the
+ *  value runs to the object close), skipping nested delimiters/strings/comments. */
+export function scanToTopLevelComma(src, from, limit) {
+    let i = from;
+    while (i < limit) {
+        const c = src[i];
+        if (c === '/' && src[i + 1] === '/') {
+            i = skipLineComment(src, i);
+            continue;
+        }
+        if (c === '/' && src[i + 1] === '*') {
+            i = skipBlockComment(src, i);
+            continue;
+        }
+        if (c === "'" || c === '"' || c === '`') {
+            i = skipString(src, i);
+            continue;
+        }
+        if (c === '{' || c === '[' || c === '(') {
+            i = matchDelimiter(src, i) + 1;
+            continue;
+        }
+        if (c === ',')
+            return i + 1;
+        i++;
+    }
+    return limit;
+}
+/** Locate the `export default { … }` object; return the body span (exclusive of
+ *  the braces) or undefined when the default export is not an object literal. */
+export function findDefaultExportObject(src) {
+    const m = /export\s+default\s*/.exec(src);
+    if (!m)
+        return undefined;
+    const braceIdx = m.index + m[0].length;
+    if (src[braceIdx] !== '{')
+        return undefined;
+    const end = matchDelimiter(src, braceIdx);
+    if (end === -1)
+        return undefined;
+    return { bodyStart: braceIdx + 1, bodyEnd: end };
+}
+/** Enumerate the top-level properties of the object body [bodyStart, bodyEnd). */
+export function scanTopLevelProperties(src, bodyStart, bodyEnd) {
+    const entries = [];
+    let i = bodyStart;
+    while (i < bodyEnd) {
+        const entryStart = i;
+        const keyPos = skipTrivia(src, i, bodyEnd);
+        if (keyPos >= bodyEnd)
+            break;
+        const key = readKey(src, keyPos);
+        let j = skipTrivia(src, key.end, bodyEnd);
+        if (src[j] !== ':') {
+            // Not a `key: value` property (spread/computed/shorthand) — keep it.
+            const term = scanToTopLevelComma(src, keyPos, bodyEnd);
+            entries.push({ key: undefined, start: entryStart, end: term });
+            i = term;
+            continue;
+        }
+        j++;
+        const term = scanToTopLevelComma(src, j, bodyEnd);
+        entries.push({ key: key.name, start: entryStart, end: term });
+        i = term;
+    }
+    return entries;
+}
+/**
+ * Does this config SOURCE declare `key` as a real top-level property of its
+ * `export default { … }` object?
+ *
+ * Deliberately stricter than a `/site\s*:/` regex, which would also fire on the
+ * word in a comment, in a string, or on a NESTED `site:` inside some slot's
+ * `with: { … }`. `false` when the default export is not an object literal at all
+ * (a `defineConfig(…)` call, a re-export shim) — such a file cannot be read as a
+ * connection source by inspection, and guessing is worse than falling through.
+ */
+export function declaresTopLevelKey(src, key) {
+    const obj = findDefaultExportObject(src);
+    if (!obj)
+        return false;
+    return scanTopLevelProperties(src, obj.bodyStart, obj.bodyEnd).some((e) => e.key === key);
+}

package/dist/src/cli/gaia-dir.d.ts

@@ -1,3 +1,9 @@
+/**
+ * The user-global `~/.gaia` dir. Core owns where the split-config files live,
+ * so a consumer that must recognise the home dir (e.g. to exclude it from a
+ * project walk-up, GAIA-219 AC-9) asks for it rather than joining it itself.
+ */
+export declare function homeGaiaDir(home?: string): string;
 /**
  * Walk from `cwd` root-ward (git/eslint style) to the nearest ancestor whose
  * `.gaia/` dir holds at least one conductor config; return that `.gaia/` dir, or
@@ -17,6 +23,12 @@ export declare function findGaiaDir(cwd: string): string | undefined;
  * 3. No `.gaia/` config anywhere up the tree → an actionable `gaia init` error.
  */
 export declare function resolveConfigPath(override?: string, cwd?: string, conductorName?: string): string;
+/**
+ * Which leg of the connection precedence produced the resolved path. Purely
+ * diagnostic (GAIA-219 D4): it lets a consumer report project-vs-home without
+ * re-deriving the rule, which would be a second precedence implementation.
+ */
+export type GaiaConfigSource = 'explicit' | 'project' | 'home' | 'fallback';
 /** A resolved connection-config file: its path, whether it is the shipped
  *  machine-context fallback, and whether it is a legacy `conductor.config.js`. */
 export interface GaiaConfigResolution {
@@ -25,23 +37,56 @@ export interface GaiaConfigResolution {
     fallback: boolean;
     /** true when the resolved file is a legacy `conductor.config.js` connection. */
     legacy: boolean;
+    /** Which leg produced `path` (GAIA-219 D4). */
+    source: GaiaConfigSource;
 }
 /**
  * Walk root-ward for the nearest `.gaia/` connection config: prefer
  * `gaia.config.js`; fall back to a legacy `conductor.config.js` in the same dir
- * (back-compat). Returns `undefined` when neither is found up the tree.
+ * **only when it really declares a connection** (a top-level `site` — GAIA-230).
+ * An engine-only `conductor.config.js` is skipped, and the walk continues, so the
+ * home `~/.gaia/gaia.config.js` every repo inherits is genuinely reachable.
+ * Returns `undefined` when no connection source is found up the tree.
  */
 export declare function findGaiaConfig(cwd: string): {
     path: string;
     legacy: boolean;
 } | undefined;
+/**
+ * Walk root-ward for the nearest `.gaia/` dir that marks a **project** — one
+ * holding any gaia config at all, a `gaia.config.js` or at least one conductor
+ * config. Returns that `.gaia/` dir, or `undefined` up to the filesystem root.
+ *
+ * Deliberately a different question from `findGaiaConfig` (GAIA-219 AC-9):
+ * "which project am I standing in" is not "where does my connection come from".
+ * Since GAIA-230 the connection walk-up skips an engine-only
+ * `conductor.config.js`, and GAIA-218 makes exactly that the canonical repo
+ * shape — so keying project detection on the connection would stop recognising
+ * the most common project as a project. It is content-agnostic for the same
+ * reason `findGaiaDir` is: a `.gaia/` dir is the marker.
+ *
+ * It is a superset of `findGaiaDir`, which requires a *conductor* config
+ * because it resolves the engine config; a repo carrying only a project
+ * connection override is a project here and not there.
+ */
+export declare function findProjectGaiaDir(cwd: string): string | undefined;
 /**
  * Resolve the CONNECTION (`gaia.config.js`) config path. Precedence (AC-4):
  * 1. `explicit` (`--config` / `$GAIA_CONFIG` / `$DROPSH_CONFIG`) wins verbatim.
- * 2. Project `./.gaia/gaia.config.js` found by walk-up (legacy
- *    `conductor.config.js` accepted as a connection source).
+ * 2. Project `./.gaia/gaia.config.js` found by walk-up (a legacy
+ *    `conductor.config.js` accepted as a connection source only when it declares
+ *    a top-level `site` — GAIA-230).
  * 3. Home `~/.gaia/gaia.config.js` when present.
  * 4. The shipped fallback (`homeFallbackGaiaConfigPath`, reads the machine context).
+ *
+ * `source` (GAIA-219 D4) names the leg that won. One correction applies **to
+ * the project leg only**: the walk-up in step 2 climbs to the filesystem root,
+ * so from any cwd under `$HOME` it reaches `~/.gaia/gaia.config.js` and would
+ * return it as `project`. That is the same file step 3 would return, so
+ * resolution is unaffected — but the label would be a lie, hence step 2
+ * re-labels the home candidate `home`. An **explicit** path that happens to
+ * name the home config still reports `explicit`: there the user did choose it
+ * by name, and which leg won is exactly what the report is for.
  */
 export declare function resolveGaiaConfigPath(opts?: {
     cwd?: string;

package/dist/src/cli/gaia-dir.js

@@ -1,6 +1,7 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { declaresTopLevelKey } from './config-source.js';
 import { homeFallbackGaiaConfigPath } from './paths.js';
 // GAIA-201: the pure `.gaia/` walk-up, hoisted from the conductor's `config.ts`.
 // Two config kinds now live under `.gaia/`:
@@ -11,6 +12,16 @@ import { homeFallbackGaiaConfigPath } from './paths.js';
 //              `conductor.config.js` still carrying `site`/`plugins` is accepted
 //              as a connection source (back-compat) when no `gaia.config.js` is
 //              found, so an un-migrated repo keeps working.
+//
+// GAIA-230 (root cause 2): that back-compat read is gated on CONTENT, not on file
+// existence. `gaia upgrade` step 0 (GAIA-218 AC-7) deliberately STRIPS
+// `site`/`plugins` from every engine config, and step 1 defaults the project
+// connection override to skip — because the global `~/.gaia/gaia.config.js` is the
+// default connection every repo inherits. An existence-only read let the
+// engine-only file it leaves behind keep precedence 2 and shadow that inherited
+// default, so `loadGaiaConfig` died on `requires site.base_url`. A
+// `conductor.config.js` declaring no top-level `site` is therefore NOT a
+// connection source and falls through to the home config.
 /** A repo's config files live in this dir, one conductor config per conductor. */
 const GAIA_DIR = '.gaia';
 /** The default conductor's file name; its stem is `conductor`. */
@@ -40,6 +51,14 @@ function configStems(gaiaDir) {
 function fileForStem(stem) {
     return stem === 'conductor' ? DEFAULT_CONFIG : `${stem}${VARIANT_SUFFIX}`;
 }
+/**
+ * The user-global `~/.gaia` dir. Core owns where the split-config files live,
+ * so a consumer that must recognise the home dir (e.g. to exclude it from a
+ * project walk-up, GAIA-219 AC-9) asks for it rather than joining it itself.
+ */
+export function homeGaiaDir(home = homedir()) {
+    return join(home, GAIA_DIR);
+}
 /**
  * Walk from `cwd` root-ward (git/eslint style) to the nearest ancestor whose
  * `.gaia/` dir holds at least one conductor config; return that `.gaia/` dir, or
@@ -98,10 +117,28 @@ export function resolveConfigPath(override, cwd = process.cwd(), conductorName)
     throw new Error(`${stems.length} conductors in ${gaiaDir} (${stems.join(', ')}); ` +
         'select one with --conductor <name> or $GAIA_CONDUCTOR');
 }
+/**
+ * GAIA-230: is this `conductor.config.js` a legacy CONNECTION source, i.e. does
+ * its source still declare a top-level `site`? A pure source read — a config may
+ * import a secret-bearing machine context, and this resolver is sync and must
+ * never execute the module. An unreadable file, or one whose default export is
+ * not an object literal, is not a connection source.
+ */
+function declaresConnection(path) {
+    try {
+        return declaresTopLevelKey(readFileSync(path, 'utf8'), 'site');
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Walk root-ward for the nearest `.gaia/` connection config: prefer
  * `gaia.config.js`; fall back to a legacy `conductor.config.js` in the same dir
- * (back-compat). Returns `undefined` when neither is found up the tree.
+ * **only when it really declares a connection** (a top-level `site` — GAIA-230).
+ * An engine-only `conductor.config.js` is skipped, and the walk continues, so the
+ * home `~/.gaia/gaia.config.js` every repo inherits is genuinely reachable.
+ * Returns `undefined` when no connection source is found up the tree.
  */
 export function findGaiaConfig(cwd) {
     let dir = resolve(cwd);
@@ -112,8 +149,41 @@ export function findGaiaConfig(cwd) {
             if (existsSync(gaiaCfg))
                 return { path: gaiaCfg, legacy: false };
             const legacy = join(gaiaDir, DEFAULT_CONFIG);
-            if (existsSync(legacy))
+            if (existsSync(legacy) && declaresConnection(legacy)) {
                 return { path: legacy, legacy: true };
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Walk root-ward for the nearest `.gaia/` dir that marks a **project** — one
+ * holding any gaia config at all, a `gaia.config.js` or at least one conductor
+ * config. Returns that `.gaia/` dir, or `undefined` up to the filesystem root.
+ *
+ * Deliberately a different question from `findGaiaConfig` (GAIA-219 AC-9):
+ * "which project am I standing in" is not "where does my connection come from".
+ * Since GAIA-230 the connection walk-up skips an engine-only
+ * `conductor.config.js`, and GAIA-218 makes exactly that the canonical repo
+ * shape — so keying project detection on the connection would stop recognising
+ * the most common project as a project. It is content-agnostic for the same
+ * reason `findGaiaDir` is: a `.gaia/` dir is the marker.
+ *
+ * It is a superset of `findGaiaDir`, which requires a *conductor* config
+ * because it resolves the engine config; a repo carrying only a project
+ * connection override is a project here and not there.
+ */
+export function findProjectGaiaDir(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const gaiaDir = join(dir, GAIA_DIR);
+        if (existsSync(gaiaDir) &&
+            (existsSync(join(gaiaDir, GAIA_CONFIG)) ||
+                configStems(gaiaDir).length > 0)) {
+            return gaiaDir;
         }
         const parent = dirname(dir);
         if (parent === dir)
@@ -124,29 +194,49 @@ export function findGaiaConfig(cwd) {
 /**
  * Resolve the CONNECTION (`gaia.config.js`) config path. Precedence (AC-4):
  * 1. `explicit` (`--config` / `$GAIA_CONFIG` / `$DROPSH_CONFIG`) wins verbatim.
- * 2. Project `./.gaia/gaia.config.js` found by walk-up (legacy
- *    `conductor.config.js` accepted as a connection source).
+ * 2. Project `./.gaia/gaia.config.js` found by walk-up (a legacy
+ *    `conductor.config.js` accepted as a connection source only when it declares
+ *    a top-level `site` — GAIA-230).
  * 3. Home `~/.gaia/gaia.config.js` when present.
  * 4. The shipped fallback (`homeFallbackGaiaConfigPath`, reads the machine context).
+ *
+ * `source` (GAIA-219 D4) names the leg that won. One correction applies **to
+ * the project leg only**: the walk-up in step 2 climbs to the filesystem root,
+ * so from any cwd under `$HOME` it reaches `~/.gaia/gaia.config.js` and would
+ * return it as `project`. That is the same file step 3 would return, so
+ * resolution is unaffected — but the label would be a lie, hence step 2
+ * re-labels the home candidate `home`. An **explicit** path that happens to
+ * name the home config still reports `explicit`: there the user did choose it
+ * by name, and which leg won is exactly what the report is for.
  */
 export function resolveGaiaConfigPath(opts = {}) {
+    const homeCfg = join(homeGaiaDir(opts.home), GAIA_CONFIG);
     const explicit = opts.explicit;
     if (explicit !== undefined && explicit.trim() !== '') {
-        return { path: explicit, fallback: false, legacy: false };
+        return {
+            path: explicit,
+            fallback: false,
+            legacy: false,
+            source: 'explicit',
+        };
     }
     const cwd = opts.cwd ?? process.cwd();
     const project = findGaiaConfig(cwd);
     if (project !== undefined) {
-        return { path: project.path, fallback: false, legacy: project.legacy };
+        return {
+            path: project.path,
+            fallback: false,
+            legacy: project.legacy,
+            source: project.path === homeCfg ? 'home' : 'project',
+        };
     }
-    const home = opts.home ?? homedir();
-    const homeCfg = join(home, GAIA_DIR, GAIA_CONFIG);
     if (existsSync(homeCfg)) {
-        return { path: homeCfg, fallback: false, legacy: false };
+        return { path: homeCfg, fallback: false, legacy: false, source: 'home' };
     }
     return {
         path: opts.shippedFallback ?? homeFallbackGaiaConfigPath(),
         fallback: true,
         legacy: false,
+        source: 'fallback',
     };
 }

package/dist/src/cli/load-gaia-config.d.ts

@@ -1,5 +1,6 @@
 import type { DropSHPlugin } from 'dropsh/plugin';
 import type { GaiaCommandHost } from './commands.js';
+import { type GaiaConfigSource } from './gaia-dir.js';
 /** The resolved control-plane connection: site + constructed auth plugins. */
 export interface GaiaConnectionConfig {
     site: {
@@ -11,6 +12,10 @@ export interface GaiaConnectionConfig {
     config_path: string;
     /** true when this is the shipped machine-context fallback. */
     fallback: boolean;
+    /** Which leg of the precedence produced `config_path` (GAIA-219 D4). */
+    source: GaiaConfigSource;
+    /** true when the loaded file is a legacy `conductor.config.js` connection. */
+    legacy: boolean;
 }
 /**
  * Load the connection config for `gaia ui` / `gaia dropsh` / conductor-auth.

package/dist/src/cli/load-gaia-config.js

@@ -80,7 +80,14 @@ export async function loadGaiaConfig(host, opts = {}) {
     const site = isRecord(raw.site) ? raw.site : {};
     const baseUrl = typeof site.base_url === 'string' ? site.base_url : '';
     if (baseUrl.trim() === '') {
-        throw new Error(`gaia connection config requires site.base_url (${configPath})`);
+        // GAIA-218 (AC-9): a legible failure that names the resolved connection path
+        // and the file that was expected to supply `site.base_url`, so a mis-resolved
+        // or empty connection is diagnosable — never a downstream plugin error (auth
+        // no longer lives in the engine config, so no plugin resolution runs here).
+        const expected = resolution.fallback
+            ? 'the shipped machine-context fallback resolved no base_url — run `gaia conductor init` or create ~/.gaia/gaia.config.js'
+            : 'expected a gaia.config.js (project ./.gaia/gaia.config.js or home ~/.gaia/gaia.config.js) declaring site.base_url';
+        throw new Error(`gaia connection config requires site.base_url — resolved ${configPath}; ${expected}`);
     }
     const jsonapiPrefix = typeof site.jsonapi_prefix === 'string' && site.jsonapi_prefix.trim() !== ''
         ? site.jsonapi_prefix
@@ -106,5 +113,7 @@ export async function loadGaiaConfig(host, opts = {}) {
         plugins,
         config_path: configPath,
         fallback: resolution.fallback,
+        source: resolution.source,
+        legacy: resolution.legacy,
     };
 }

package/dist/src/core/exec.d.ts

@@ -28,7 +28,7 @@ export declare class CommandRunner {
 /**
  * Replace the module-level singleton runner used by {@link exec}.
  *
- * Note: out-of-package plugins (e.g. `@gaia-ai/plugin-herdr`) import `exec` via
+ * Note: out-of-package plugins (e.g. `@gaia-ai/addon-herdr`) import `exec` via
  * the `@gaia-ai/gaia/plugin` barrel, which resolves to the built `dist/`
  * copy of this module. This means `setDefaultCommandRunner` only shares the
  * runner with those plugins when the conductor itself runs from `dist`

package/dist/src/core/exec.js

@@ -64,7 +64,7 @@ let defaultRunner = new CommandRunner(noopLogger);
 /**
  * Replace the module-level singleton runner used by {@link exec}.
  *
- * Note: out-of-package plugins (e.g. `@gaia-ai/plugin-herdr`) import `exec` via
+ * Note: out-of-package plugins (e.g. `@gaia-ai/addon-herdr`) import `exec` via
  * the `@gaia-ai/gaia/plugin` barrel, which resolves to the built `dist/`
  * copy of this module. This means `setDefaultCommandRunner` only shares the
  * runner with those plugins when the conductor itself runs from `dist`

package/dist/src/index.d.ts

@@ -1,6 +1,7 @@
 export type { GaiaCommandHost, GaiaCommandPlugin } from './cli/commands.js';
-export type { GaiaConfigResolution } from './cli/gaia-dir.js';
-export { findGaiaConfig, findGaiaDir, resolveConfigPath, resolveGaiaConfigPath, } from './cli/gaia-dir.js';
+export { declaresTopLevelKey, findDefaultExportObject, matchDelimiter, type PropEntry, readKey, scanTopLevelProperties, scanToTopLevelComma, skipBlockComment, skipLineComment, skipString, skipTrivia, } from './cli/config-source.js';
+export type { GaiaConfigResolution, GaiaConfigSource, } from './cli/gaia-dir.js';
+export { findGaiaConfig, findGaiaDir, findProjectGaiaDir, homeGaiaDir, resolveConfigPath, resolveGaiaConfigPath, } from './cli/gaia-dir.js';
 export { type GaiaConnectionConfig, loadGaiaConfig, } from './cli/load-gaia-config.js';
 export { legacyMachineContextPath, type MachineContext, machineContextPath, readMachineContext, resolveMachineContextPath, } from './cli/machine-context.js';
 export { corePackageRoot, homeFallbackGaiaConfigPath, } from './cli/paths.js';
@@ -11,14 +12,6 @@ export { CommandRunner, ExecError, exec, setDefaultCommandRunner, } from './core
 export { type ConductorLogger, createLogger } from './core/logger.js';
 export { shellQuote } from './core/shell.js';
 export { DEFAULT_SLUG_MAX_LENGTH, slugify } from './core/slug.js';
-export { type AgentFootprint, emptyAgentFootprint, type GaiaAgent, } from './plugins/agent/agent.js';
 export { discoverAddons, type ResolvedConductorSlots, resolveConductorSlots, } from './plugins/discover-addons.js';
-export type * from './plugins/executor/executor.js';
-export type { AgentCandidate, AgentPlugin, ExecutorDeps, ExecutorPlugin, RemotePlugin, ResolvedAgent, WorkspacePlugin, } from './plugins/plugins.js';
-export { selectAgent, selectAgents } from './plugins/plugins.js';
-export { type AddonEntry, type CommandDescriptor, type DiscoveredContributions, emptyContributions, type GaiaPreset, type GaiaSurface, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './plugins/preset.js';
-export type * from './plugins/remote/remote.js';
-export { loadInstructions } from './plugins/workspace/instructions.js';
-export type { EnsuredWorkspace, GaiaWorkspace, } from './plugins/workspace/workspace.js';
-export type * from './types.js';
+export { type AddonEntry, type CommandDescriptor, type DiscoveredContributions, emptyContributions, type GaiaPreset, type GaiaSurface, type OpaqueAccumulator, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './plugins/preset.js';
 export { type ExpandedLoad, expandLoad, type InputDecl, parseStepValues, readSkillWhen, type SkillContract, type SkillWhen, StepContractError, type StepValues, type Triple, validateLoad, type WhenValue, WORKFLOW_STEPS, type WorkflowStep, } from './workflow/step-contract.js';

package/dist/src/index.js

@@ -1,4 +1,9 @@
-export { findGaiaConfig, findGaiaDir, resolveConfigPath, resolveGaiaConfigPath, } from './cli/gaia-dir.js';
+// GAIA-230: the comment-aware config-SOURCE scanner. Owned by the kernel so the
+// content-gated legacy connection read (`findGaiaConfig`) and the conductor's
+// GAIA-218 strip pass share one answer to "which top-level properties does this
+// config source declare?" — core is layer 0 and cannot import the conductor's copy.
+export { declaresTopLevelKey, findDefaultExportObject, matchDelimiter, readKey, scanTopLevelProperties, scanToTopLevelComma, skipBlockComment, skipLineComment, skipString, skipTrivia, } from './cli/config-source.js';
+export { findGaiaConfig, findGaiaDir, findProjectGaiaDir, homeGaiaDir, resolveConfigPath, resolveGaiaConfigPath, } from './cli/gaia-dir.js';
 export { loadGaiaConfig, } from './cli/load-gaia-config.js';
 export { legacyMachineContextPath, machineContextPath, readMachineContext, resolveMachineContextPath, } from './cli/machine-context.js';
 export { corePackageRoot, homeFallbackGaiaConfigPath, } from './cli/paths.js';
@@ -9,14 +14,20 @@ export { CommandRunner, ExecError, exec, setDefaultCommandRunner, } from './core
 export { createLogger } from './core/logger.js';
 export { shellQuote } from './core/shell.js';
 export { DEFAULT_SLUG_MAX_LENGTH, slugify } from './core/slug.js';
-export { emptyAgentFootprint, } from './plugins/agent/agent.js';
 // GAIA-215: the Storybook-style preset contract + the shared addon discovery.
+// GAIA-224 (Finding 6): SURFACE-AGNOSTIC only. The conductor-surface interfaces
+// (`GaiaRemote`/`GaiaExecutor`/`GaiaWorkspace`/`GaiaAgent`, the four `*Plugin`
+// interfaces, `ExecutorDeps`, `AgentCandidate`/`ResolvedAgent`, the `select*`
+// selectors), the config contract (`ConductorSettings`/`ConductorFileConfig`/
+// `ConductorEngineConfig`) and every built-in IMPLEMENTATION have moved out of
+// this kernel — the contract to `@gaia-ai/conductor` (subpath
+// `@gaia-ai/conductor/contract`), the impls to their own addons
+// (`@gaia-ai/addon-remote-drupal`, `@gaia-ai/addon-workspace-git`,
+// `@gaia-ai/addon-auth-basic`, `@gaia-ai/addon-fake`). `loadInstructions` moved to
+// `@gaia-ai/addon-workspace-git`. Core ships NO plugin implementations.
 export { discoverAddons, resolveConductorSlots, } from './plugins/discover-addons.js';
-export { selectAgent, selectAgents } from './plugins/plugins.js';
 export { emptyContributions, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './plugins/preset.js';
 // GAIA-194 AC-2: the agent-host contract (`AgentLaunchHost` / `HostedAgent` /
-// `supportsAgentHost`) moved OUT of core — it is the TUI renderer's own plugin
-// seam (`@gaia-ai/plugin-gaia-ui`), and herdr types its impl locally. Core is
-// the conductor engine contract only.
-export { loadInstructions } from './plugins/workspace/instructions.js';
+// `supportsAgentHost`) is likewise NOT here — it is the TUI renderer's own plugin
+// seam (`@gaia-ai/addon-gaia-ui`), and herdr types its impl locally.
 export { expandLoad, parseStepValues, readSkillWhen, StepContractError, validateLoad, WORKFLOW_STEPS, } from './workflow/step-contract.js';