@ours.network/fleet 1.1.0-nightly.1 → 1.1.0-nightly.2

package/dist/config.js

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { basename, dirname, extname, join, resolve, sep } from 'node:path';
 import { agentDir, defaultConfigPath, fleetDDir, home } from './paths.js';
 import { parseFleetDocument, } from './config-yaml.js';
 import { harnessRuntimeDir, resolveIsolation, validateIsolationConfig, } from './isolation/policy.js';
@@ -10,6 +10,7 @@ import { resolveLoops } from './loops/config.js';
 import { validateRoomsConfig, validateTasksConfig, validateRoomTemplatesConfig, } from './rooms-tasks/config.js';
 import { CAPABILITIES, CAP_MONITOR_INTERRUPT_AFTER_TOOL } from './capabilities.js';
 import { runningLabel } from './provenance.js';
+import { parseDuration } from './duration.js';
 /** Conservative built-in policy; `worklog: false` is the explicit opt-out. */
 export const DEFAULT_WORKLOG_POLICY = Object.freeze({
     max_kb: 1024,
@@ -126,12 +127,276 @@ export function isolationContextFor(role) {
         harnessSharedPaths: split?.shared,
     };
 }
-export const ROLE_NAME_RE = /^[A-Za-z0-9_-]+$/;
+export const ROLE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 const ROLE_KEYS = [
     'harness', 'session', 'session_options', 'permissions', 'identity', 'cwd', 'coordinator', 'mission', 'persona', 'bio',
-    'briefing_file', 'model', 'model_chain', 'max_tokens', 'autocompact_pct', 'env', 'oversee', 'harness_options',
+    'briefing_file', 'model', 'effort', 'model_chain', 'max_tokens', 'autocompact_pct', 'env', 'oversee', 'harness_options',
     'isolation', 'monitor', 'owner_channel', 'worklog', 'auth_proxy',
 ];
+const ROLE_PRESET_KEYS = ['mission', 'persona', 'bio', 'briefing_file'];
+const BRAIN_PRESET_KEYS = [
+    'harness', 'session', 'session_options', 'model', 'model_chain', 'max_tokens',
+    'autocompact_pct', 'harness_options', 'effort',
+];
+const AGENT_KEYS = [
+    'role', 'brain', 'permissions', 'identity', 'cwd', 'coordinator', 'env', 'oversee',
+    'isolation', 'monitor', 'owner_channel', 'worklog', 'auth_proxy',
+];
+const V2_API_VERSION = 'ours.network/fleet/v2';
+const utf8Bytes = (value) => Buffer.byteLength(value, 'utf8');
+function schemaError(file, pointer, summary) {
+    throw new ConfigError(`${file}: E_SCHEMA ${pointer}: ${summary}`);
+}
+function validateRoleValue(value, file, pointer) {
+    const limits = {
+        mission: { bytes: 16 * 1024, nonblank: true },
+        persona: { bytes: 16 * 1024 },
+        bio: { bytes: 4 * 1024 },
+    };
+    for (const [key, rule] of Object.entries(limits)) {
+        const current = value[key];
+        if (current === undefined)
+            continue;
+        if (typeof current !== 'string')
+            schemaError(file, `${pointer}/${key}`, 'must be a string');
+        if (rule.nonblank && !current.trim())
+            schemaError(file, `${pointer}/${key}`, 'must be non-blank');
+        if (utf8Bytes(current) > rule.bytes)
+            schemaError(file, `${pointer}/${key}`, `must be at most ${rule.bytes} UTF-8 bytes`);
+    }
+    if (value.briefing_file !== undefined
+        && (typeof value.briefing_file !== 'string' || !value.briefing_file.trim()))
+        schemaError(file, `${pointer}/briefing_file`, 'must be a non-blank relative path');
+}
+function validateBrainValue(value, file, pointer) {
+    if (typeof value.harness !== 'string' || !value.harness.trim())
+        schemaError(file, `${pointer}/harness`, 'is required and must be a registered non-blank harness ID');
+    if (value.model !== undefined && value.model !== null
+        && (typeof value.model !== 'string' || !value.model.trim()))
+        schemaError(file, `${pointer}/model`, 'must be a non-blank string or null');
+    for (const key of ['harness_options', 'session_options']) {
+        if (value[key] !== undefined && !isPlainObject(value[key]))
+            schemaError(file, `${pointer}/${key}`, 'must be a mapping');
+    }
+}
+function validateAgentScalars(value, file, id) {
+    for (const key of ['identity', 'cwd']) {
+        const current = value[key];
+        if (current !== undefined && (typeof current !== 'string' || !current.trim()))
+            schemaError(file, `/agents/${id}/${key}`, 'must be a non-blank string');
+    }
+    if (value.coordinator !== undefined
+        && (typeof value.coordinator !== 'string' || !ROLE_NAME_RE.test(value.coordinator)))
+        schemaError(file, `/agents/${id}/coordinator`, 'must be a valid Agent ID');
+    if (value.oversee !== undefined) {
+        if (!Array.isArray(value.oversee))
+            schemaError(file, `/agents/${id}/oversee`, 'must be an array');
+        const seen = new Set();
+        value.oversee.forEach((entry, index) => {
+            const pointer = `/agents/${id}/oversee/${index}`;
+            if (!isPlainObject(entry))
+                schemaError(file, pointer, 'must be a mapping');
+            const keys = Object.keys(entry);
+            const bad = keys.filter(key => key !== 'agent' && key !== 'interval');
+            if (bad.length || keys.length !== 2 || !keys.includes('agent') || !keys.includes('interval'))
+                schemaError(file, pointer, 'must contain exactly agent and interval');
+            if (typeof entry.agent !== 'string' || !ROLE_NAME_RE.test(entry.agent))
+                schemaError(file, `${pointer}/agent`, 'must be a valid Agent ID');
+            if (typeof entry.interval !== 'string')
+                schemaError(file, `${pointer}/interval`, 'must be a valid duration');
+            try {
+                parseDuration(entry.interval, { name: 'oversee interval' });
+            }
+            catch {
+                schemaError(file, `${pointer}/interval`, 'must be a valid duration such as 5m');
+            }
+            if (seen.has(entry.agent))
+                schemaError(file, `${pointer}/agent`, 'must be unique');
+            seen.add(entry.agent);
+        });
+    }
+}
+function assertTrustedPath(path, expected) {
+    const st = lstatSync(path);
+    if (st.isSymbolicLink())
+        throw new ConfigError(`E_SYMLINK: trusted configuration path is a symlink: ${path}`);
+    if (expected === 'file' ? !st.isFile() : !st.isDirectory())
+        throw new ConfigError(`E_FILE_TRUST: expected ${expected}: ${path}`);
+    const uid = process.getuid?.();
+    if (uid !== undefined && st.uid !== uid)
+        throw new ConfigError(`E_FILE_TRUST: ${path} is owned by uid ${st.uid}; required uid ${uid}`);
+    if ((st.mode & 0o022) !== 0)
+        throw new ConfigError(`E_FILE_TRUST: ${path} is group/world writable (mode ${(st.mode & 0o777).toString(8)})`);
+}
+function assertBareKeys(value, allowed, label) {
+    if (!isPlainObject(value))
+        throw new ConfigError(`${label}: E_SCHEMA: must be a mapping`);
+    const bad = Object.keys(value).filter(key => !allowed.includes(key));
+    if (bad.length)
+        throw new ConfigError(`${label}: E_UNKNOWN_KEY: unknown key(s) ${bad.join(', ')}; allowed: ${allowed.join(', ')}`);
+    return value;
+}
+export function splitRootFor(base) {
+    const extension = extname(base).toLowerCase();
+    return extension === '.yaml' || extension === '.yml' ? base.slice(0, -extension.length) : `${base}.d`;
+}
+function readKindDirectory(root, kind, required, yamlMode, diagnostics, files) {
+    if (!existsSync(root)) {
+        if (required)
+            throw new ConfigError(`E_ROOT_MISSING: required ${kind} root not found: ${root}`);
+        return new Map();
+    }
+    assertTrustedPath(root, 'directory');
+    const result = new Map();
+    const names = readdirSync(root).filter(name => ['.yaml', '.yml'].includes(extname(name).toLowerCase())).sort();
+    for (const name of names) {
+        const file = join(root, name);
+        assertTrustedPath(file, 'file');
+        const id = basename(name, extname(name));
+        if (!ROLE_NAME_RE.test(id))
+            throw new ConfigError(`${file}: invalid ${kind} id '${id}' (allowed: [A-Za-z0-9_-])`);
+        const previous = result.get(id);
+        if (previous)
+            throw new ConfigError(`E_DUPLICATE_ID: ${kind} '${id}' defined by both ${previous.file} and ${file}`);
+        const parsed = parseFleetDocument(file, readFileSync(file, 'utf8'), yamlMode);
+        diagnostics.push(...parsed.diagnostics);
+        files.push(file);
+        result.set(id, { file, value: parsed.value });
+    }
+    return result;
+}
+function selection(raw, kind, agentFile, presets, allowed) {
+    if (!isPlainObject(raw))
+        schemaError(agentFile, `/${kind}`, 'must be { ref } or { inline }');
+    const keys = Object.keys(raw);
+    if (keys.length !== 1 || (keys[0] !== 'ref' && keys[0] !== 'inline'))
+        throw new ConfigError(`${agentFile}: E_UNION /${kind}: must contain exactly one of ref or inline`);
+    if ('ref' in raw) {
+        if (typeof raw.ref !== 'string' || !ROLE_NAME_RE.test(raw.ref))
+            schemaError(agentFile, `/${kind}/ref`, 'must be a valid case-sensitive ID');
+        const preset = presets.get(raw.ref);
+        if (!preset)
+            throw new ConfigError(`${agentFile}: E_REF_MISSING: ${kind} '${raw.ref}' not found`);
+        return {
+            value: assertBareKeys(preset.value, allowed, `${preset.file}: ${kind} '${raw.ref}'`),
+            file: preset.file,
+            pointer: `/${kind}s/${raw.ref}`,
+        };
+    }
+    return {
+        value: assertBareKeys(raw.inline, allowed, `${agentFile}: agent.${kind}.inline`),
+        file: agentFile,
+        pointer: `/${kind}/inline`,
+    };
+}
+function deepSubStrict(value, vars, file, pointer) {
+    if (typeof value === 'string') {
+        return value.replace(/\$\{(\w+)\}/g, (_match, key) => {
+            if (!(key in vars))
+                schemaError(file, pointer, `unknown variable \${${key}}`);
+            return String(vars[key]);
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((item, index) => deepSubStrict(item, vars, file, `${pointer}/${index}`));
+    if (isPlainObject(value))
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+            key, deepSubStrict(child, vars, file, `${pointer}/${key}`),
+        ]));
+    return value;
+}
+function composeSplitRoles(base, baseDoc, yamlMode, diagnostics, files) {
+    if (baseDoc.api_version !== V2_API_VERSION)
+        throw new ConfigError(`${base}: legacy fleet configuration is unsupported; run 'ours-fleet doctor' and rewrite it as ${V2_API_VERSION}`);
+    if ('roles' in baseDoc)
+        throw new ConfigError(`${base}: legacy top-level roles: is unsupported; define bare Agent files under ${splitRootFor(base)}/agents/`);
+    const root = splitRootFor(base);
+    if (!existsSync(root))
+        throw new ConfigError(`E_ROOT_MISSING: required configuration root not found: ${root}`);
+    assertTrustedPath(root, 'directory');
+    const brains = readKindDirectory(join(root, 'brains'), 'brain', false, yamlMode, diagnostics, files);
+    const roles = readKindDirectory(join(root, 'roles'), 'role', false, yamlMode, diagnostics, files);
+    const agents = readKindDirectory(join(root, 'agents'), 'agent', true, yamlMode, diagnostics, files);
+    const vars = (baseDoc.vars ?? {});
+    const documents = [];
+    for (const [id, agent] of agents) {
+        const a = assertBareKeys(agent.value, AGENT_KEYS, `${agent.file}: agent '${id}'`);
+        if (!('role' in a) || !('brain' in a))
+            throw new ConfigError(`${agent.file}: agent '${id}' requires role and brain`);
+        const role = selection(a.role, 'role', agent.file, roles, ROLE_PRESET_KEYS);
+        const brain = selection(a.brain, 'brain', agent.file, brains, BRAIN_PRESET_KEYS);
+        const operational = deepSubStrict(Object.fromEntries(Object.entries(a).filter(([key]) => key !== 'role' && key !== 'brain')), vars, agent.file, `/agents/${id}`);
+        validateAgentScalars(operational, agent.file, id);
+        const brainValue = deepSubStrict({ ...brain.value }, vars, brain.file, brain.pointer);
+        validateBrainValue(brainValue, brain.file, brain.pointer);
+        const effort = brainValue.effort;
+        delete brainValue.effort;
+        const harness = brainValue.harness;
+        {
+            let adapter;
+            try {
+                adapter = getAdapter(harness);
+            }
+            catch {
+                schemaError(brain.file, `${brain.pointer}/harness`, `unregistered harness '${harness}'`);
+            }
+            let resolved;
+            try {
+                resolved = adapter.agentSession.resolveBrain({
+                    model: brainValue.model,
+                    effort: effort,
+                    harnessOptions: brainValue.harness_options,
+                });
+            }
+            catch (error) {
+                schemaError(brain.file, `${brain.pointer}/effort`, error.message);
+            }
+            brainValue.model = resolved.model;
+            brainValue.harness_options = resolved.harnessOptions;
+            brainValue.effort = effort;
+        }
+        const roleValue = deepSubStrict({ ...role.value }, vars, role.file, role.pointer);
+        validateRoleValue(roleValue, role.file, role.pointer);
+        if (typeof roleValue.briefing_file === 'string') {
+            const containmentRoot = realpathSync(dirname(role.file));
+            const briefing = resolve(dirname(role.file), roleValue.briefing_file);
+            if (briefing !== containmentRoot && !briefing.startsWith(`${containmentRoot}${sep}`))
+                throw new ConfigError(`${role.file}: E_PATH_ESCAPE: briefing_file escapes its ${role.file === agent.file ? 'Agent' : 'Role'} root`);
+            assertTrustedPath(briefing, 'file');
+            const real = realpathSync(briefing);
+            if (real !== containmentRoot && !real.startsWith(`${containmentRoot}${sep}`))
+                throw new ConfigError(`${role.file}: E_PATH_ESCAPE: briefing_file realpath escapes its root`);
+            roleValue.briefing_file = real;
+        }
+        const provenance = {};
+        const record = (values, source, kind, via) => {
+            for (const [key, raw] of Object.entries(values))
+                provenance[key] = {
+                    sourceFile: source.file, sourcePointer: `${source.pointer}/${key}`,
+                    sourceKind: kind, sourceId: via?.id ?? id, origin: 'explicit',
+                    ...(via ? { viaReference: via } : {}),
+                    transforms: [
+                        ...(JSON.stringify(raw).includes('${')
+                            ? [{ kind: 'substitution', detail: 'manifest variable substitution' }] : []),
+                        ...(['model', 'harness_options', 'effort'].includes(key)
+                            ? [{ kind: 'adapter-normalization', detail: 'AgentSession Brain resolution' }] : []),
+                    ],
+                };
+        };
+        record(a, { file: agent.file, pointer: `/agents/${id}` }, 'Agent');
+        record(role.value, { file: role.file, pointer: role.pointer }, 'Role', 'ref' in a.role
+            ? { sourcePointer: `/agents/${id}/role/ref`, kind: 'Role', id: String(a.role.ref) }
+            : undefined);
+        record(brain.value, { file: brain.file, pointer: brain.pointer }, 'Brain', 'ref' in a.brain
+            ? { sourcePointer: `/agents/${id}/brain/ref`, kind: 'Brain', id: String(a.brain.ref) }
+            : undefined);
+        delete provenance.role;
+        delete provenance.brain;
+        documents.push({ file: agent.file,
+            doc: { roles: { [id]: { ...brainValue, ...roleValue, ...operational } } }, provenance });
+    }
+    return documents;
+}
 function deepSub(v, vars) {
     if (typeof v === 'string')
         return v.replace(/\$\{(\w+)\}/g, (m, k) => (k in vars ? String(vars[k]) : m));
@@ -141,43 +406,37 @@ function deepSub(v, vars) {
         return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, deepSub(x, vars)]));
     return v;
 }
-/** Load ~/fleet.yaml (or an explicit path) merged with ~/fleet.d/*.yaml drop-ins. */
+/** Load a v2 manifest and bare Agent/Role/Brain documents from its stem directory. */
 export function loadConfig(configPath, options = {}) {
     const base = configPath ?? defaultConfigPath();
     const files = [];
     const diagnostics = [];
-    const docs = [];
+    let docs = [];
+    let manifestDoc = {};
     if (existsSync(base)) {
+        assertTrustedPath(base, 'file');
         const parsed = parseFleetDocument(base, readFileSync(base, 'utf8'), options.yamlMode);
-        docs.push({ file: base, doc: parsed.value });
+        manifestDoc = parsed.value;
         diagnostics.push(...parsed.diagnostics);
         files.push(base);
     }
     else if (configPath) {
         throw new ConfigError(`config not found: ${base}`);
     }
-    const dd = fleetDDir();
-    if (existsSync(dd)) {
-        for (const f of readdirSync(dd).filter(f => f.endsWith('.yaml') || f.endsWith('.yml')).sort()) {
-            const p = join(dd, f);
-            const parsed = parseFleetDocument(p, readFileSync(p, 'utf8'), options.yamlMode);
-            const doc = parsed.value;
-            diagnostics.push(...parsed.diagnostics);
-            const FLEET_D_ALLOWED = ['roles', 'rooms', 'room_templates', 'tasks'];
-            const extra = Object.keys(doc).filter(k => !FLEET_D_ALLOWED.includes(k));
-            if (extra.length)
-                throw new ConfigError(`${p}: fleet.d files may only define ${FLEET_D_ALLOWED.join(', ')}: (found: ${extra.join(', ')})`);
-            docs.push({ file: p, doc });
-            files.push(p);
-        }
+    else {
+        throw new ConfigError(`config not found: ${base}`);
     }
-    const baseDoc = docs.length && docs[0].file === base ? docs[0].doc : {};
+    const dd = fleetDDir();
+    if (existsSync(dd) && readdirSync(dd).some(f => f.endsWith('.yaml') || f.endsWith('.yml')))
+        throw new ConfigError(`${dd}: legacy fleet.d configuration is unsupported; run 'ours-fleet doctor' and move agents to ${splitRootFor(base)}/agents/`);
+    docs = [{ file: base, doc: manifestDoc }, ...composeSplitRoles(base, manifestDoc, options.yamlMode ?? 'compat', diagnostics, files)];
+    const baseDoc = manifestDoc;
     const vars = (baseDoc.vars ?? {});
     const defaults = (baseDoc.defaults ?? {});
     const startStaggerMs = resolveStartStaggerMs(baseDoc.start_stagger_ms, base);
     const seen = new Map();
     const roles = [];
-    for (const { file, doc } of docs) {
+    for (const { file, doc, provenance } of docs) {
         for (const [name, raw] of Object.entries((doc.roles ?? {}))) {
             if (!ROLE_NAME_RE.test(name))
                 throw new ConfigError(`${file}: invalid role name '${name}' (allowed: [A-Za-z0-9_-])`);
@@ -234,6 +493,21 @@ export function loadConfig(configPath, options = {}) {
             const modelChain = resolveModelChain(model, r.model_chain ?? (inheritsModelDefaults
                 ? defaults.model_chain
                 : undefined), file, name);
+            const fieldProvenance = { ...(provenance ?? {}) };
+            const defaulted = (key, explicit, builtIn = false) => {
+                if (fieldProvenance[key])
+                    return;
+                fieldProvenance[key] = {
+                    sourceFile: builtIn ? '(built-in)' : base,
+                    sourcePointer: builtIn ? `/${key}` : `/defaults/${key}`,
+                    sourceKind: builtIn ? 'built-in' : 'Manifest',
+                    origin: builtIn ? 'built-in' : explicit ? 'explicit' : 'typed-default',
+                    transforms: [{ kind: 'validation-default', detail: builtIn ? 'built-in default' : 'manifest operational default' }],
+                };
+            };
+            defaulted('identity', r.identity !== undefined, r.identity === undefined);
+            defaulted('permissions', defaults.permissions !== undefined, defaults.permissions === undefined);
+            defaulted('monitor', defaults.monitor !== undefined, defaults.monitor === undefined);
             roles.push({
                 ...r,
                 name,
@@ -252,6 +526,7 @@ export function loadConfig(configPath, options = {}) {
                 monitor,
                 owner_channel: ownerChannel,
                 worklog,
+                provenance: fieldProvenance,
                 auth_proxy: authProxy,
                 env: Object.keys(env).length ? env : undefined,
                 loops: [],
@@ -307,6 +582,15 @@ export function loadConfig(configPath, options = {}) {
         roles, vars, defaults, files, startStaggerMs, diagnostics, watchdogs,
         loops: resolvedLoops.loops,
         rooms, roomTemplates, tasks, ownerInviteFingerprint,
+        configMode: 'split-v2',
+        sourceDocuments: files.map(path => {
+            if (path === base)
+                return { kind: 'Manifest', path };
+            const parent = basename(dirname(path));
+            const kind = parent === 'agents' ? 'Agent'
+                : parent === 'roles' ? 'Role' : 'Brain';
+            return { kind, id: basename(path, extname(path)), path };
+        }),
     };
     if (ownerInvite !== undefined) {
         Object.defineProperty(result, 'ownerInvite', {

package/dist/creation.d.ts

@@ -153,7 +153,7 @@ export interface DaemonIdentityProvisionerOptions {
 export declare function daemonIdentityProvisioner(env?: NodeJS.ProcessEnv, attachClient?: (options: AttachOursClientOptions) => Promise<IdentityInventoryClient>, options?: DaemonIdentityProvisionerOptions): IdentityProvisioner;
 /** Inventory-only variant for session-owned temporary identity lifecycles. */
 export declare function daemonIdentityInventoryProvisioner(env?: NodeJS.ProcessEnv, attachClient?: (options: AttachOursClientOptions) => Promise<IdentityInventoryClient>): IdentityProvisioner;
-/** Atomically write a role's fleet.d file, journalling it for rollback. */
+/** Atomically write a bare Agent file, journalling it for rollback. */
 export declare function writeRoleFile(tx: CreationTransaction, file: string, contents: string): void;
 /** Where a setting's effective value came from. */
 export type ProvenanceSource = 'cli' | 'fleet-default' | 'caller-role' | 'built-in';

package/dist/creation.js

@@ -300,12 +300,12 @@ export function daemonIdentityInventoryProvisioner(env = process.env, attachClie
         acceptTemporaryExisting: true,
     });
 }
-/** Atomically write a role's fleet.d file, journalling it for rollback. */
+/** Atomically write a bare Agent file, journalling it for rollback. */
 export function writeRoleFile(tx, file, contents) {
     const existed = existsSync(file);
     replaceFileAtomically(file, contents, 0o644);
     tx.record({
-        stage: `fleet.d file ${file}`,
+        stage: `Agent file ${file}`,
         // Only remove what THIS transaction created; never delete a file the
         // operator already had.
         undo: () => { if (!existed)