agent-relay-server 0.122.0 → 0.123.0

package/runner/src/profile-projection.ts

@@ -0,0 +1,324 @@
+import type { AgentProfile, AgentProfileProjectionEntry, AgentProfileProjectionReport, SpawnProvider } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
+import type { AssembledLaunch } from "./launch-assembly";
+
+// #557 — the projection report DESCRIBES an AssembledLaunch, the same object the adapters
+// turn into launch args. It is no longer a separate re-derivation from the profile, so the
+// report and the real launch share one source of truth and cannot drift: change the
+// assembler and both the args AND this report change together. Every entry below reads a
+// field the assembler actually computed (relay gates, provisioned sets, instruction
+// disposition, vanilla mechanism, config home) — only the not-yet-enforced category modes
+// (mcp/hooks) and the purely-declarative env/permissions read straight off the profile.
+
+interface AgentProfileProjectionInput {
+  assembled: AssembledLaunch;
+  generatedAt?: number;
+}
+
+export function agentProfileProjectionReport(input: AgentProfileProjectionInput): AgentProfileProjectionReport {
+  const { assembled } = input;
+  const { provider } = assembled;
+  const profile = assembled.profile;
+  const generatedAt = input.generatedAt ?? Date.now();
+  const entries: AgentProfileProjectionEntry[] = [];
+  const add = (entry: AgentProfileProjectionEntry) => entries.push(entry);
+
+  add(relayContextEntry(assembled));
+  add(relaySkillsEntry(assembled));
+  add(relayPluginsEntry(assembled));
+  add(relayStatusLineEntry(assembled));
+  add(repoInstructionsEntry(assembled));
+  add(globalInstructionsEntry(assembled));
+  add(mcpEntry(assembled));
+  add(hooksEntry(assembled));
+  add(provisioningSkillsEntry(assembled));
+  add(provisioningPluginsEntry(assembled));
+  add(provisioningHooksEntry(assembled));
+  add(hostSkillsEntry(assembled));
+  add(hostPluginsEntry(assembled));
+  add(provisioningMcpEntry(assembled));
+  for (const entry of provisioningSkippedEntries(assembled)) add(entry);
+  add(projectMcpEntry(assembled));
+  add(projectSkillsEntry(assembled));
+  add(projectSettingsEntry(assembled));
+  add(sharedMcpEntry(assembled));
+  if (profile) add(filesystemEntry(profile));
+  add(configHomeEntry(assembled));
+  if (assembled.vanilla) add(vanillaLaunchEntry(provider));
+  if (profile) add(envEntry(profile));
+
+  const warnings = entries
+    .filter((entry) => entry.result === "partial" || entry.result === "unsupported")
+    .map((entry) => `${entry.capability}: ${entry.detail}`);
+  const unsupported = entries
+    .filter((entry) => entry.result === "unsupported")
+    .map((entry) => entry.capability);
+
+  return {
+    profileName: profile?.name ?? "default",
+    provider,
+    base: assembled.base,
+    generatedAt,
+    entries,
+    warnings,
+    unsupported,
+  };
+}
+
+function relayContextEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  return a.relayContext
+    ? applied("relay.context", "enabled", "Relay context is injected before Relay-delivered provider turns.")
+    : applied("relay.context", "disabled", "Relay context injection is disabled by the profile.");
+}
+
+function relaySkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (!hasPluginSurface) {
+    return a.relaySkills
+      ? applied("relay.skills", "enabled", `Bundled Agent Relay ${label} skills are passed through the provider's skill delivery mechanism.`)
+      : applied("relay.skills", "disabled", `Bundled Agent Relay ${label} skills are omitted.`);
+  }
+  return a.relaySkills
+    ? applied("relay.skills", "enabled", `Agent Relay ${label} skills are available through the bundled Relay plugin.`)
+    : applied("relay.skills", "disabled", a.relayPlugin
+      ? `${label} does not expose an independent Relay skill switch; disabling skills requires disabling the Relay plugin.`
+      : `Bundled Agent Relay ${label} plugin dirs are omitted, so Relay plugin-provided skills are unavailable.`);
+}
+
+function relayPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (hasPluginSurface) {
+    return a.relayPlugin
+      ? applied("relay.plugins", "enabled", `Bundled Agent Relay ${label} plugin dir is passed to ${label}.`)
+      : applied("relay.plugins", "disabled", `Bundled Agent Relay ${label} plugin dirs are omitted.`);
+  }
+  return notApplicable("relay.plugins", a.relaySkills ? "enabled" : "disabled", `${label} Relay integration uses skills/app-server delivery, not a Relay plugin dir.`);
+}
+
+function relayStatusLineEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  if (a.statusLine) {
+    return applied("relay.statusLine", "enabled", "Agent Relay status-line context probe settings are injected when caller settings allow it.");
+  }
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (hasPluginSurface) {
+    return applied("relay.statusLine", "disabled", "Agent Relay status-line settings are omitted.");
+  }
+  return notApplicable("relay.statusLine", "disabled", `${label} reports context through provider-native events instead of a Relay status-line setting.`);
+}
+
+function repoInstructionsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const disposition = a.instructions.repo;
+  if (disposition === "allow") return applied("instructions.repo", "allow", "Repo-local provider instructions are left available.");
+  if (disposition === "suppressed") {
+    const label = getManifest(a.provider)?.label ?? a.provider;
+    return applied("instructions.repo", "ignore", `Repo project instructions are suppressed: ${label} launches with the vanilla base mechanism (provider-specific suppression of repo instructions).`);
+  }
+  return unsupported("instructions.repo", "ignore", "Repo instruction suppression requires the vanilla base; isolated/minimal do not enforce it at launch yet.");
+}
+
+// #552/#554/#555/#556 — the vanilla base's launch-time host suppression, naming the exact
+// provider mechanism the assembler emitted (Claude --setting-sources "user"; Codex
+// project_doc_max_bytes=0). OS-level admin/managed policy is beyond any client flag and is
+// called out so it isn't mistaken for a leak.
+const VANILLA_MECHANISM: Record<string, { requested: string; detail: string }> = {
+  claude: {
+    requested: "--setting-sources user",
+    detail: "Claude launches the isolated config home under --setting-sources \"user\": host CLAUDE.md (repo + global), host skills/plugins/hooks, and host MCP (.mcp.json / ~/.claude.json) are all excluded; relay-provisioned assets in the home load. Auth, model, and built-in tools work normally. OS-level admin-managed policy still applies.",
+  },
+  codex: {
+    requested: "project_doc_max_bytes=0",
+    detail: "Codex launches with an isolated CODEX_HOME (no host config.toml MCP/hooks) and project_doc_max_bytes=0 (no AGENTS.md project doc, repo or global).",
+  },
+};
+
+function vanillaLaunchEntry(provider: SpawnProvider): AgentProfileProjectionEntry {
+  const label = getManifest(provider)?.label ?? provider;
+  const mechanism = VANILLA_MECHANISM[provider];
+  return applied(
+    "provider.vanilla",
+    mechanism?.requested ?? "active",
+    mechanism?.detail ?? `${label} launches with the vanilla base: an isolated provider config home and provider-specific repo instruction suppression. Auth, model, and built-in tools work normally.`,
+  );
+}
+
+function provisioningSkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const count = a.skills.length;
+  if (!count) return notApplicable("provisioning.skills", "none", "No relay-provisioned skills materialized for this launch.");
+  const names = ` (${a.skills.map((s) => s.name).join(", ")})`;
+  const label = getManifest(a.provider)?.label ?? a.provider;
+  return applied("provisioning.skills", `${count}`, `Relay-provisioned skills materialized for ${label} from the isolated provider config home${names}.`);
+}
+
+function provisioningPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const manifest = getManifest(a.provider);
+  const label = manifest?.label ?? a.provider;
+  const hasPluginSurface = Boolean(manifest?.provisioning?.bundledPlugin);
+  if (!hasPluginSurface) {
+    const declared = (a.profile?.plugins ?? []).filter((p) => p.enabled).length;
+    return notApplicable("provisioning.plugins", `${declared}`, `${label} has no plugin surface; provisioned plugins apply to plugin-capable providers only.`);
+  }
+  const count = a.plugins.length;
+  if (!count) return notApplicable("provisioning.plugins", "none", "No relay-provisioned plugins materialized for this launch.");
+  const names = ` (${a.plugins.map((p) => p.name).join(", ")})`;
+  return applied("provisioning.plugins", `${count}`, `Relay-provisioned plugins passed to ${label} via the plugin dir mechanism${names}.`);
+}
+
+function provisioningHooksEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  // #1096 review — the anti-lie invariant: hooks that RESOLVED but did NOT reach the launch
+  // (baseline safety guard included) are reported LOUDLY as a warning, never "applied" and never
+  // a benign "not-applicable". `hooksSuppressed` is set only when there were hooks to deliver.
+  if (a.hooksSuppressed?.names.length) {
+    return partial(
+      "provisioning.hooks",
+      "suppressed",
+      `Relay-provisioned hooks were NOT applied (${a.hooksSuppressed.names.join(", ")}): ${a.hooksSuppressed.reason}. A baseline safety guard is absent for this launch.`,
+    );
+  }
+  const count = a.hooks.length;
+  if (!count) return notApplicable("provisioning.hooks", "none", "No relay-provisioned hooks materialized for this launch.");
+  const names = ` (${a.hooks.map((h) => h.name).join(", ")})`;
+  const label = getManifest(a.provider)?.label ?? a.provider;
+  return applied("provisioning.hooks", `${count}`, `Relay-provisioned hooks materialized for ${label} from the managed provider config home${names}.`);
+}
+
+function hostSkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.hostAssets?.skills);
+  if (!optedIn) return notApplicable("hostAssets.skills", "off", "Host/global skill inheritance is off for this resolved profile.");
+  const label = getManifest(a.provider)?.label ?? a.provider;
+  if (!getManifest(a.provider)?.provisioning?.bundledPlugin) {
+    return notApplicable("hostAssets.skills", "unsupported", `${label} does not expose host skill-dir projection through Agent Relay.`);
+  }
+  if (!a.hostSkills.length) return applied("hostAssets.skills", "none", "Host/global skill inheritance is on, but no valid host skill dirs were found.");
+  const names = a.hostSkills.map((s) => s.name).join(", ");
+  return applied("hostAssets.skills", `${a.hostSkills.length}`, `Host/global skills materialized into Relay's managed ${label} config home (${names}).`);
+}
+
+function hostPluginsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.hostAssets?.plugins);
+  if (!optedIn) return notApplicable("hostAssets.plugins", "off", "Host/global plugin inheritance is off for this resolved profile.");
+  const label = getManifest(a.provider)?.label ?? a.provider;
+  if (!getManifest(a.provider)?.provisioning?.bundledPlugin) {
+    return notApplicable("hostAssets.plugins", "unsupported", `${label} has no plugin-dir surface for host plugin inheritance.`);
+  }
+  if (!a.hostPluginDirs.length) return applied("hostAssets.plugins", "none", "Host/global plugin inheritance is on, but no host plugin dirs are configured.");
+  return applied("hostAssets.plugins", `${a.hostPluginDirs.length}`, `Host/global plugin dirs passed to ${label} (${a.hostPluginDirs.join(", ")}).`);
+}
+
+function provisioningMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const names = a.mcp.servers;
+  if (!names.length) return notApplicable("provisioning.mcp", "none", "No relay-provisioned MCP servers materialized for this launch.");
+  const count = `${names.length} server${names.length === 1 ? "" : "s"}`;
+  const providerLabel = getManifest(a.provider)?.label ?? a.provider;
+  return applied("provisioning.mcp", count, `Relay-provisioned MCP servers injected for ${providerLabel} (${names.join(", ")})${a.mcp.strict ? "; strict mode guarantees only declared servers load" : ""}.`);
+}
+
+function provisioningSkippedEntries(a: AssembledLaunch): AgentProfileProjectionEntry[] {
+  return (a.profile?.provisioning?.skipped ?? []).map((item) => partial(
+    `provisioning.${item.kind}.${item.ref}`,
+    item.reason,
+    item.detail,
+  ));
+}
+
+// #667 — project `.mcp.json` projection provenance. `not-applicable` when the profile/spawn
+// didn't opt in (the default); `applied` lists the spawn-cwd servers relay injected through
+// the controlled --mcp-config / -c path (sourced from the project, not ambient host MCP).
+function projectMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.projectMcp);
+  const names = a.mcp.projectServers;
+  if (!optedIn) return notApplicable("projectMcp", "off", "Project .mcp.json projection is off (opt in via the projectMcp profile/spawn option).");
+  if (!names.length) return applied("projectMcp", "none", "Project .mcp.json projection is on, but the spawn cwd declared no injectable MCP servers.");
+  const count = `${names.length} server${names.length === 1 ? "" : "s"}`;
+  return applied("projectMcp", count, `Project .mcp.json servers injected for this launch (${names.join(", ")})${a.mcp.strict ? "; survives strict MCP mode" : ""}.`);
+}
+
+function projectSkillsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.projectSkills);
+  if (!optedIn) return notApplicable("projectSkills", "off", "Project .claude/skills projection is off (opt in via the projectSkills profile/spawn option).");
+  if (!getManifest(a.provider)?.provisioning?.bundledPlugin) return notApplicable("projectSkills", "unsupported", "Project skills projection applies to plugin-capable providers only.");
+  if (!a.projectSkills.length) return applied("projectSkills", "none", "Project .claude/skills projection is on, but the spawn cwd declared no valid skill dirs.");
+  const names = a.projectSkills.map((s) => s.name).join(", ");
+  return applied("projectSkills", `${a.projectSkills.length}`, `Project .claude skills materialized into Relay's managed Claude config home (${names}); host/global skills are excluded.`);
+}
+
+function projectSettingsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.projectSettings);
+  if (!optedIn) return notApplicable("projectSettings", "off", "Project .claude/settings.json projection is off (opt in via the projectSettings profile/spawn option).");
+  if (!getManifest(a.provider)?.provisioning?.bundledPlugin) return notApplicable("projectSettings", "unsupported", "Project settings projection applies to plugin-capable providers only.");
+  const ignored = a.projectSettings.ignoredKeys.length ? `; ignored security keys: ${a.projectSettings.ignoredKeys.join(", ")}` : "";
+  return applied("projectSettings", a.projectSettings.keys.length ? `${a.projectSettings.keys.length} keys` : "none", `Project .claude/settings.json was sanitized and injected through --settings; Relay approvalMode/permission gates remain authoritative${ignored}.`);
+}
+
+// #672/#689 — shared host-listener MCP provenance. `applied` reports the per-agent `callmux
+// bridge` route. `not-applicable` means the resolved profile kept shared MCP off (for example a
+// zero-host profile, explicit false, or global kill-switch normalization before launch).
+function sharedMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const optedIn = Boolean(a.profile?.sharedMcp);
+  const listener = a.mcp.sharedListener;
+  if (!optedIn || !listener) return notApplicable("sharedMcp", "off", "Shared host-listener MCP is off for this resolved profile; non-identity MCP is injected per-agent.");
+  return applied("sharedMcp", "on", `Non-identity MCP (e.g. tokenlean, github) routed through the shared callmux listener (${listener.url}) via a per-agent 'callmux bridge --cwd "$WORKTREE"'; session survives a listener restart, session-cwd isolated. Relay endpoint stays per-agent.`);
+}
+
+function globalInstructionsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const disposition = a.instructions.global;
+  if (disposition === "allow") return applied("instructions.global", "allow", "Host/global provider instructions are left available.");
+  if (disposition === "isolated") return applied("instructions.global", "ignore", `${a.provider} uses an isolated provider config home, so host/global provider instructions are not loaded.`);
+  return unsupported("instructions.global", "ignore", `${a.provider} global instruction isolation requires an isolated provider config home.`);
+}
+
+function mcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const mode = a.profile?.mcp.mode ?? "host";
+  if (mode === "host") return applied("mcp", "host", "Host provider MCP configuration is left available.");
+  if (mode === "none" && a.base !== "host") {
+    return applied("mcp", "none", `${a.provider} uses an isolated provider config home without host MCP configuration.`);
+  }
+  return unsupported("mcp", mode, `${a.provider} MCP category projection is not enforced yet.`);
+}
+
+function hooksEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const mode = a.profile?.hooks.mode ?? "host";
+  if (mode === "host") return applied("hooks", "host", "Host provider hooks are left available.");
+  if (mode === "none" && a.base !== "host") {
+    return applied("hooks", "none", `${a.provider} uses an isolated provider config home without host hook configuration.`);
+  }
+  return unsupported("hooks", mode, `${a.provider} hook category projection is not enforced yet.`);
+}
+
+function filesystemEntry(profile: AgentProfile): AgentProfileProjectionEntry {
+  if (profile.permissions.filesystem === "host") return applied("permissions.filesystem", "host", "No profile-level filesystem boundary requested.");
+  return partial("permissions.filesystem", profile.permissions.filesystem, "Relay constrains spawn cwd through the orchestrator; provider-level filesystem sandbox projection is not complete yet.");
+}
+
+function configHomeEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  if (!a.configHome) return applied("provider.configHome", "host", "Provider uses the host's normal configuration home.");
+  return applied("provider.configHome", a.base, `${a.provider} is launched with an Agent Relay managed provider config home and linked host auth where available.`);
+}
+
+function envEntry(profile: AgentProfile): AgentProfileProjectionEntry {
+  const count = Object.keys(profile.env).length;
+  return count
+    ? applied("env", `${count} vars`, "Profile environment variables are passed through the orchestrator runner environment.")
+    : applied("env", "none", "No profile environment variables requested.");
+}
+
+function applied(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "applied", detail };
+}
+
+function partial(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "partial", detail };
+}
+
+function unsupported(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "unsupported", detail };
+}
+
+function notApplicable(capability: string, requested: string, detail: string): AgentProfileProjectionEntry {
+  return { capability, requested, result: "not-applicable", detail };
+}

package/runner/src/providers.ts

@@ -0,0 +1,20 @@
+import type { SpawnProvider } from "agent-relay-sdk";
+import type { ProviderAdapter } from "./adapter";
+import { ClaudeAdapter } from "./adapters/claude";
+import { CodexAdapter } from "./adapters/codex";
+
+interface RunnerProviderRegistration {
+  provider: SpawnProvider;
+  createAdapter: () => ProviderAdapter;
+}
+
+const RUNNER_PROVIDERS: Record<string, RunnerProviderRegistration> = {
+  claude: { provider: "claude", createAdapter: () => new ClaudeAdapter() },
+  codex: { provider: "codex", createAdapter: () => new CodexAdapter() },
+};
+
+export function createProviderAdapter(provider: SpawnProvider): ProviderAdapter {
+  const registration = RUNNER_PROVIDERS[provider];
+  if (!registration) throw new Error(`unsupported provider adapter: ${provider}`);
+  return registration.createAdapter();
+}