@akira-tl/forgerelay 1.1.2 → 1.2.0

package/dist/subagents/profiles.js

@@ -1,7 +1,10 @@
-import { existsSync } from "node:fs";
-import { readdir, readFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
+import * as z from "zod/v4";
 import { parse as parseYaml } from "yaml";
+import { defineConfigDomain } from "../runtime/config/definition/definition.js";
+import { resolveConfigDomain } from "../runtime/config/resolution/resolver.js";
+import { resolveProjectContext } from "../workspaces/state/project-context.js";
+import { projectExecutionRequirement } from "../runtime/security/project-execution-trust.js";
 export const SUBAGENT_PROVIDERS = [
     "codex",
     "claude",
@@ -11,23 +14,125 @@ export const SUBAGENT_PROVIDERS = [
     "copilot",
 ];
 const FRONTMATTER_DELIMITER = "---";
-const PROVIDERS = new Set(SUBAGENT_PROVIDERS);
+const CANONICAL_PRIORITY = 100;
+const LEGACY_PRIORITY = 0;
+const LEGACY_DEPRECATION = {
+    since: "1.2.0",
+    removeIn: "1.4.0",
+    replacement: "subagents/",
+};
+const profileNameSchema = z.string().trim().min(1);
+const providerSchema = z.enum(SUBAGENT_PROVIDERS);
+const optionalNonEmptyString = z.string().trim().min(1).optional();
+const activeProfileFrontmatterSchema = z.object({
+    name: profileNameSchema.optional(),
+    description: z.string().trim().min(1),
+    provider: providerSchema,
+    model: optionalNonEmptyString,
+    thinking: optionalNonEmptyString,
+    disabled: z.literal(false).optional(),
+}).strict();
+const disabledProfileFrontmatterSchema = z.object({
+    name: profileNameSchema.optional(),
+    description: optionalNonEmptyString,
+    provider: providerSchema.optional(),
+    model: optionalNonEmptyString,
+    thinking: optionalNonEmptyString,
+    disabled: z.literal(true),
+}).strict();
+const subagentProfileValueSchema = z.object({
+    description: z.string().trim().min(1),
+    provider: providerSchema,
+    model: optionalNonEmptyString,
+    thinking: optionalNonEmptyString,
+    body: z.string(),
+}).strict();
+const subagentProfileDisabledSchema = z.object({ disabled: z.literal(true) }).strict();
+const subagentProfilesSchema = z.record(profileNameSchema, z.union([subagentProfileValueSchema, subagentProfileDisabledSchema]));
+export const subagentProfilesConfigDefinition = defineConfigDomain({
+    domain: "subagents",
+    title: "ForgeRelay Subagent Profile configuration",
+    description: "Markdown Subagent Profiles resolved by profile name across user, Project, and Project Local scopes.",
+    schemaOutput: "none",
+    fields: {
+        profiles: {
+            schema: subagentProfilesSchema,
+            description: "Subagent Profiles keyed by effective profile name.",
+            required: true,
+            legalScopes: ["project-local", "project", "user"],
+            merge: "keyed",
+            reload: "hot",
+            sensitivity: "sensitive",
+            interpolation: "none",
+            builtIn: { kind: "none" },
+            executionEffect: (value) => isRecord(value) && value.disabled === true ? "none" : "process",
+        },
+    },
+});
+export async function resolveSubagentProfilesConfig(config, workspaceRoot) {
+    const project = await resolveProjectContext(config.configDir, workspaceRoot);
+    return resolveSubagentProfilesConfigSources({
+        configDir: config.configDir,
+        sourceRuntime: config.configRuntime.sources,
+        projectSharedConfigDir: project.sharedConfigDir,
+        projectLocalConfigDir: project.localConfigDir,
+    });
+}
+export function resolveSubagentProfilesConfigSources(input) {
+    const sources = [];
+    const refreshDiagnostics = [];
+    appendProfileDirectory(sources, refreshDiagnostics, input.sourceRuntime, "user", join(input.configDir, "agents"), false);
+    appendProfileDirectory(sources, refreshDiagnostics, input.sourceRuntime, "user", join(input.configDir, "subagents"), true);
+    if (input.projectSharedConfigDir) {
+        appendProfileDirectory(sources, refreshDiagnostics, input.sourceRuntime, "project", join(input.projectSharedConfigDir, "agents"), false);
+        appendProfileDirectory(sources, refreshDiagnostics, input.sourceRuntime, "project", join(input.projectSharedConfigDir, "subagents"), true);
+    }
+    if (input.projectLocalConfigDir) {
+        appendProfileDirectory(sources, refreshDiagnostics, input.sourceRuntime, "project-local", join(input.projectLocalConfigDir, "subagents"), true);
+    }
+    const resolution = resolveConfigDomain({
+        definition: subagentProfilesConfigDefinition,
+        sources,
+    });
+    resolution.diagnostics = mergeDiagnostics(resolution.diagnostics, refreshDiagnostics);
+    return resolution;
+}
 export async function loadSubagentProfiles(config, workspaceRoot) {
     if (!config.subagents)
         return [];
-    const profileDirs = [
-        config.configAgentsDir,
-        join(workspaceRoot, ".forgerelay", "agents"),
-    ];
-    const profilesByName = new Map();
-    for (const directory of profileDirs) {
-        for (const profile of await loadProfilesFromDirectory(directory)) {
-            profilesByName.set(profile.name, profile);
-        }
+    const project = await resolveProjectContext(config.configDir, workspaceRoot);
+    const resolution = resolveSubagentProfilesConfigSources({
+        configDir: config.configDir,
+        sourceRuntime: config.configRuntime.sources,
+        projectSharedConfigDir: project.sharedConfigDir,
+        projectLocalConfigDir: project.localConfigDir,
+    });
+    for (const diagnostic of resolution.diagnostics) {
+        if (diagnostic.severity !== "error" || diagnostic.diagnosticChanged === false)
+            continue;
+        console.warn(`Skipping invalid subagent profile ${diagnostic.source.location ?? diagnostic.source.id}: ${diagnostic.message}`);
     }
-    return Array.from(profilesByName.values())
-        .filter((profile) => !profile.disabled)
-        .sort((a, b) => a.name.localeCompare(b.name));
+    return effectiveSubagentProfileEntries(resolution)
+        .map((entry) => {
+        const executionRequirement = projectExecutionRequirement({
+            projectId: project.id,
+            resolution,
+            entryKey: `profiles.${entry.name}`,
+            display: { kind: "subagent-profile", name: entry.name },
+        });
+        return {
+            name: entry.name,
+            description: entry.value.description,
+            provider: entry.value.provider,
+            ...(entry.value.model ? { model: entry.value.model } : {}),
+            ...(entry.value.thinking ? { thinking: entry.value.thinking } : {}),
+            filePath: entry.filePath,
+            body: entry.value.body,
+            disabled: false,
+            ...(executionRequirement ? { executionRequirement } : {}),
+        };
+    })
+        .sort((left, right) => left.name.localeCompare(right.name));
 }
 export function summarizeSubagentProfile(profile) {
     return {
@@ -46,31 +151,205 @@ export function formatAvailableSubagentProfile(profile) {
         : "";
     return `${profile.name} (${profile.provider}${model}${thinking}${availability})`;
 }
-async function loadProfilesFromDirectory(directory) {
+function effectiveSubagentProfileEntries(resolution) {
+    const values = isRecord(resolution.values.profiles) ? resolution.values.profiles : {};
+    const result = [];
+    for (const [name, value] of Object.entries(values)) {
+        const parsed = subagentProfileValueSchema.safeParse(value);
+        const entry = resolution.entries[`profiles.${name}`];
+        if (!parsed.success || !entry || !entry.effective.source.location) {
+            throw new Error(`Subagent Profile resolver produced an invalid effective entry for ${name}.`);
+        }
+        result.push({
+            name,
+            value: parsed.data,
+            scope: entry.effective.source.scope,
+            filePath: entry.effective.source.location,
+        });
+    }
+    return result;
+}
+function appendProfileDirectory(sources, diagnostics, sourceRuntime, scope, directory, canonical) {
     const resolvedDirectory = resolve(directory);
-    if (!existsSync(resolvedDirectory))
-        return [];
-    const entries = await readdir(resolvedDirectory, { withFileTypes: true });
-    const profiles = [];
-    for (const entry of entries) {
-        if (!entry.isFile())
-            continue;
-        if (!entry.name.endsWith(".md"))
+    const refreshed = sourceRuntime.refreshDirectory({
+        key: `subagents:${canonical ? "canonical" : "legacy"}:${scope}:${resolvedDirectory}`,
+        directory: resolvedDirectory,
+        include: (name) => name.endsWith(".md"),
+        parse: (_name, content, filePath) => parseProfileSourceDocument(canonical, content, filePath),
+        parseIssue: (error) => ({
+            code: "invalid_source",
+            message: "Subagent Profile is invalid.",
+            ...(error instanceof SubagentProfileSourceError && error.keyHint
+                ? { keyHint: error.keyHint }
+                : {}),
+        }),
+        readIssue: { code: "invalid_source", message: "Subagent Profile could not be read." },
+    });
+    if (refreshed.state === "invalid" && refreshed.issue) {
+        diagnostics.push({
+            severity: "error",
+            code: refreshed.issue.code,
+            source: {
+                id: `${canonical ? "canonical" : "legacy"}:${scope}:subagents-directory`,
+                scope,
+                kind: "file",
+                location: resolvedDirectory,
+                priority: canonical ? CANONICAL_PRIORITY : LEGACY_PRIORITY,
+            },
+            message: refreshed.issue.message,
+            diagnosticChanged: refreshed.diagnosticChanged,
+        });
+    }
+    for (const unit of refreshed.units) {
+        const filePath = unit.status.path;
+        if (unit.value !== undefined) {
+            const source = profileSource(scope, filePath, unit.name, canonical, unit.value);
+            sources.push(source);
+            if (unit.status.state === "invalid" && unit.issue) {
+                diagnostics.push({
+                    severity: "error",
+                    code: unit.issue.code,
+                    source: sourceReference(source),
+                    message: unit.issue.message,
+                    usingLastKnownGood: true,
+                    diagnosticChanged: unit.status.diagnosticChanged,
+                });
+            }
             continue;
-        const filePath = join(resolvedDirectory, entry.name);
-        try {
-            profiles.push(await loadProfileFile(filePath));
         }
-        catch (error) {
-            console.warn(`Skipping invalid subagent profile ${filePath}: ${errorMessage(error)}`);
+        if (unit.status.state === "invalid") {
+            sources.push(invalidProfileSource(scope, filePath, profileKeyHintFromIssue(unit.issue) ?? basename(unit.name, ".md"), canonical, unit.issue?.message ?? "Subagent Profile is invalid.", unit.issue?.code));
         }
     }
-    return profiles;
 }
-async function loadProfileFile(filePath) {
-    const content = await readFile(filePath, "utf8");
+function profileSource(scope, filePath, fileName, canonical, profile) {
+    const value = profile.disabled
+        ? { disabled: true }
+        : {
+            description: profile.description,
+            provider: profile.provider,
+            ...(profile.model ? { model: profile.model } : {}),
+            ...(profile.thinking ? { thinking: profile.thinking } : {}),
+            body: profile.body,
+        };
+    return {
+        id: `${canonical ? "canonical" : "legacy"}:${scope}:subagent:${fileName}`,
+        scope,
+        kind: "file",
+        location: filePath,
+        priority: canonical ? CANONICAL_PRIORITY : LEGACY_PRIORITY,
+        normalized: true,
+        ...(canonical ? { shadowsLowerPriorityKeys: [`profiles.${profile.name}`] } : { deprecation: LEGACY_DEPRECATION }),
+        value: { profiles: { [profile.name]: value } },
+    };
+}
+function invalidProfileSource(scope, filePath, key, canonical, message, code = "invalid_source") {
+    return {
+        id: `${canonical ? "canonical" : "legacy"}:${scope}:subagent:${basename(filePath)}`,
+        scope,
+        kind: "file",
+        location: filePath,
+        priority: canonical ? CANONICAL_PRIORITY : LEGACY_PRIORITY,
+        ...(canonical ? { shadowsLowerPriorityKeys: [`profiles.${key}`] } : { deprecation: LEGACY_DEPRECATION }),
+        error: { code, message },
+    };
+}
+class SubagentProfileSourceError extends Error {
+    keyHint;
+    constructor(keyHint) {
+        super("Subagent Profile source is invalid.");
+        this.keyHint = keyHint;
+        this.name = "SubagentProfileSourceError";
+    }
+}
+function parseProfileSourceDocument(canonical, content, filePath) {
+    const keyHint = profileKeyHint(content, filePath);
+    try {
+        return canonical
+            ? canonicalProfileFromDocument(content, filePath)
+            : legacyProfileFromDocument(content, filePath);
+    }
+    catch {
+        throw new SubagentProfileSourceError(keyHint);
+    }
+}
+function canonicalProfileFromDocument(content, filePath) {
+    const parsed = parseFrontmatter(content, filePath);
+    const frontmatter = z.union([
+        disabledProfileFrontmatterSchema,
+        activeProfileFrontmatterSchema,
+    ]).parse(parsed.frontmatter);
+    const name = frontmatter.name ?? basename(filePath, ".md");
+    if (frontmatter.disabled === true) {
+        return {
+            name,
+            description: frontmatter.description ?? "Disabled Subagent Profile.",
+            provider: frontmatter.provider ?? "codex",
+            model: frontmatter.model,
+            thinking: frontmatter.thinking,
+            filePath,
+            body: parsed.body,
+            disabled: true,
+        };
+    }
+    return {
+        name,
+        description: frontmatter.description,
+        provider: frontmatter.provider,
+        model: frontmatter.model,
+        thinking: frontmatter.thinking,
+        filePath,
+        body: parsed.body,
+        disabled: false,
+    };
+}
+function legacyProfileFromDocument(content, filePath) {
     const parsed = parseFrontmatter(content, filePath);
-    return profileFromFrontmatter(parsed.frontmatter, parsed.body, filePath);
+    return legacyProfileFromFrontmatter(parsed.frontmatter, parsed.body, filePath);
+}
+export function canonicalSubagentProfileDocumentFromLegacy(content, filePath) {
+    const profile = legacyProfileFromDocument(content, filePath);
+    const frontmatter = [
+        `name: ${JSON.stringify(profile.name)}`,
+        `description: ${JSON.stringify(profile.description)}`,
+        `provider: ${profile.provider}`,
+        ...(profile.model ? [`model: ${JSON.stringify(profile.model)}`] : []),
+        ...(profile.thinking ? [`thinking: ${JSON.stringify(profile.thinking)}`] : []),
+        ...(profile.disabled ? ["disabled: true"] : []),
+    ];
+    return [FRONTMATTER_DELIMITER, ...frontmatter, FRONTMATTER_DELIMITER, profile.body, ""].join("\n");
+}
+function legacyProfileFromFrontmatter(frontmatter, body, filePath) {
+    const name = readString(frontmatter, "name") ?? basename(filePath, ".md");
+    const description = readString(frontmatter, "description");
+    const provider = readProvider(frontmatter, filePath);
+    if (!description) {
+        throw new Error(`Subagent profile is missing description: ${filePath}`);
+    }
+    return {
+        name,
+        description,
+        provider,
+        model: readString(frontmatter, "model"),
+        thinking: readString(frontmatter, "thinking"),
+        filePath,
+        body,
+        disabled: frontmatter.disabled === true,
+    };
+}
+function profileKeyHint(content, filePath) {
+    try {
+        return readString(parseFrontmatter(content, filePath).frontmatter, "name");
+    }
+    catch {
+        return undefined;
+    }
+}
+function profileKeyHintFromIssue(issue) {
+    if (!issue || !("keyHint" in issue) || typeof issue.keyHint !== "string")
+        return undefined;
+    const trimmed = issue.keyHint.trim();
+    return trimmed || undefined;
 }
 function parseFrontmatter(content, filePath) {
     const normalized = content.replace(/^\uFEFF/, "");
@@ -100,36 +379,18 @@ function parseProfileYaml(source, filePath) {
     }
     return parsed;
 }
-function profileFromFrontmatter(frontmatter, body, filePath) {
-    const name = readString(frontmatter, "name") ?? basename(filePath, ".md");
-    const description = readString(frontmatter, "description");
-    const provider = readProvider(frontmatter, filePath);
-    if (!description) {
-        throw new Error(`Subagent profile is missing description: ${filePath}`);
-    }
-    return {
-        name,
-        description,
-        provider,
-        model: readString(frontmatter, "model"),
-        thinking: readString(frontmatter, "thinking"),
-        filePath,
-        body,
-        disabled: frontmatter.disabled === true,
-    };
-}
 function readProvider(frontmatter, filePath) {
     const provider = readString(frontmatter, "provider");
     if (!provider) {
         throw new Error(`Subagent profile is missing provider: ${filePath}`);
     }
-    if (!PROVIDERS.has(provider)) {
+    if (!isSubagentProvider(provider)) {
         throw new Error(`Subagent profile provider must be codex, claude, opencode, pi, cursor, or copilot: ${filePath}`);
     }
     return provider;
 }
 export function isSubagentProvider(value) {
-    return PROVIDERS.has(value);
+    return SUBAGENT_PROVIDERS.includes(value);
 }
 function readString(frontmatter, key) {
     const value = frontmatter[key];
@@ -138,6 +399,28 @@ function readString(frontmatter, key) {
     const trimmed = value.trim();
     return trimmed || undefined;
 }
+function sourceReference(source) {
+    return {
+        id: source.id,
+        scope: source.scope,
+        kind: source.kind,
+        ...(source.location ? { location: source.location } : {}),
+        priority: source.priority,
+    };
+}
+function mergeDiagnostics(left, right) {
+    const seen = new Set();
+    return [...left, ...right].filter((diagnostic) => {
+        const key = `${diagnostic.source.id}\0${diagnostic.code}\0${diagnostic.message}\0${diagnostic.usingLastKnownGood === true}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/subagents/sessions/execution.js

@@ -1,5 +1,5 @@
 import { HookRunner } from "../../mcp/hooks/hooks.js";
-import { isSubagentProvider, loadSubagentProfiles, } from "../profiles.js";
+import { isSubagentProvider, } from "../profiles.js";
 import { runSubagentProvider } from "../providers/registry.js";
 import { SubagentDeliveryMailbox } from "./delivery-mailbox.js";
 import { createSubagentSessionStore, } from "./store.js";
@@ -13,7 +13,7 @@ export async function executeSubagentRun(config, input, providerRunner = runSuba
         if (record.activeRun?.id !== input.runId) {
             throw new Error(`Subagent Run ${input.runId} is not active for Session ${record.id}.`);
         }
-        const hooks = new HookRunner(config.hooks, config.logging, process.env, undefined, config.commandShellRuntime);
+        const hooks = new HookRunner({}, config.logging, process.env, undefined, config.commandShellRuntime, config.configDir, config.configRuntime.sources);
         const hookInvocation = {
             workspaceId: record.workspaceId,
             workspaceRoot: record.workspaceRoot,
@@ -33,7 +33,7 @@ export async function executeSubagentRun(config, input, providerRunner = runSuba
         try {
             await hooks.run("SubagentStart", hookInvocation);
             input.signal?.throwIfAborted();
-            result = await runSessionProvider(config, record, input.prompt, providerRunner, input.signal);
+            result = await runSessionProvider(record, input.prompt, providerRunner, input.signal);
             input.signal?.throwIfAborted();
         }
         catch (error) {
@@ -109,43 +109,14 @@ export async function executeSubagentSession(config, sessionId, prompt) {
         store.close();
     }
 }
-async function runSessionProvider(config, session, prompt, providerRunner, signal) {
+async function runSessionProvider(session, prompt, providerRunner, signal) {
     if (!isSubagentProvider(session.provider)) {
         throw new Error(`Unknown subagent provider for Session ${session.id}: ${session.provider}`);
     }
-    if (session.providerSessionId) {
-        return providerRunner(session.provider, {
-            prompt,
-            workspace: session.workspaceRoot,
-            providerSessionId: session.providerSessionId,
-            writeMode: "allowed",
-            model: session.model,
-            thinking: session.thinking,
-            signal,
-        });
-    }
-    if (session.profileName === session.provider) {
-        return providerRunner(session.provider, {
-            prompt,
-            workspace: session.workspaceRoot,
-            writeMode: "allowed",
-            model: session.model,
-            thinking: session.thinking,
-            signal,
-        });
-    }
-    const profiles = await loadSubagentProfiles(config, session.workspaceRoot);
-    const profile = profiles.find((candidate) => candidate.name === session.profileName);
-    if (!profile)
-        throw new Error(`Subagent profile not found: ${session.profileName}`);
-    return runSubagentProfile(profile, session, prompt, providerRunner, signal);
-}
-async function runSubagentProfile(profile, session, prompt, providerRunner, signal) {
-    const body = profile.body.trim();
-    const firstPrompt = body ? `${body}\n\nTask:\n${prompt}` : prompt;
     return providerRunner(session.provider, {
-        prompt: firstPrompt,
+        prompt,
         workspace: session.workspaceRoot,
+        ...(session.providerSessionId ? { providerSessionId: session.providerSessionId } : {}),
         writeMode: "allowed",
         model: session.model,
         thinking: session.thinking,

package/dist/subagents/sessions/manager.js

@@ -3,6 +3,7 @@ import { formatAvailableSubagentTargets, resolveSubagentTarget, } from "../cli-t
 import { isSubagentProvider, loadSubagentProfiles, } from "../profiles.js";
 import { assertSubagentProviderAvailable } from "../providers/availability.js";
 import { subagentProviderContinuationSupported } from "../providers/continuation.js";
+import { compatibilityAllowProjectExecutionTrustPolicy, } from "../../runtime/security/project-execution-trust.js";
 import { createSubagentSessionStore, } from "./store.js";
 export class SubagentSessionError extends Error {
     code;
@@ -15,10 +16,12 @@ export class SubagentSessionError extends Error {
 export class SubagentSessionManager {
     config;
     launcher;
+    projectExecutionTrustPolicy;
     store;
-    constructor(config, launcher) {
+    constructor(config, launcher, projectExecutionTrustPolicy = compatibilityAllowProjectExecutionTrustPolicy) {
         this.config = config;
         this.launcher = launcher;
+        this.projectExecutionTrustPolicy = projectExecutionTrustPolicy;
         this.store = createSubagentSessionStore(config);
     }
     list(scope = {}) {
@@ -33,6 +36,9 @@ export class SubagentSessionManager {
         if (!target) {
             throw new Error(`Unknown subagent profile or provider: ${input.target}. Available ${formatAvailableSubagentTargets(profiles)}`);
         }
+        if (target.kind === "profile" && target.profile.executionRequirement) {
+            await this.projectExecutionTrustPolicy.authorize(target.profile.executionRequirement);
+        }
         assertSubagentProviderAvailable(target.provider);
         const runId = newRunId();
         const startedAt = new Date().toISOString();
@@ -56,7 +62,7 @@ export class SubagentSessionManager {
             sessionId: session.id,
             runId,
             ...(input.activityId ? { activityId: input.activityId } : {}),
-            prompt: input.prompt,
+            prompt: subagentLaunchPrompt(target, input.prompt),
         }));
         return {
             session: owned,
@@ -146,6 +152,12 @@ export class SubagentSessionManager {
         return this.store.assignActiveRunOwner(session.id, run.id, owner);
     }
 }
+function subagentLaunchPrompt(target, prompt) {
+    if (target.kind !== "profile")
+        return prompt;
+    const body = target.profile.body.trim();
+    return body ? `${body}\n\nTask:\n${prompt}` : prompt;
+}
 function newRunId() {
     return `run_${randomUUID().replaceAll("-", "").slice(0, 12)}`;
 }