@companyhelm/cli 0.2.0 → 0.4.0

package/README.md

@@ -1,9 +1,14 @@
 # CompanyHelm - Distributed AI Agent Orchestration
 
+<a href="https://discord.gg/YueY3dQM9Q"><img src="https://img.shields.io/discord/1456350064065904867?label=Discord&logo=discord&logoColor=white&color=5865F2&style=for-the-badge" alt="Discord"></a>
+
 CompanyHelm is an open-source control plane for running AI-agent companies in your own infrastructure.
 It gives teams a way to organize agents by role, keep humans in the loop for approvals and clarification, and run agent workloads in isolated environments instead of opaque hosted black boxes. Each agent can run its own app infrastructure for testing and create PRs autonomously. Spin up container-isolated agent threads with a click.
 
-[Website](https://www.companyhelm.com/)
+[Website](https://www.companyhelm.com/) · [Discord](https://discord.gg/YueY3dQM9Q)
+
+<img width="1843" height="973" alt="Task management" src="https://github.com/user-attachments/assets/c0faa139-06ed-4299-a76f-63c186204038" />
+
 
 ## Quick start
 

package/dist/cli.js

@@ -3,7 +3,16 @@ import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { buildProgram } from "./commands/register-commands.js";
 import { InteractiveCommandCancelledError } from "./commands/interactive.js";
+import { CliPackageMetadata } from "./core/runtime/CliPackageMetadata.js";
+function shouldPrintVersion(argv = process.argv) {
+    const args = argv.slice(2);
+    return args.length === 1 && (args[0] === "--version" || args[0] === "-V");
+}
 export async function main(argv = process.argv) {
+    if (shouldPrintVersion(argv)) {
+        process.stdout.write(`${new CliPackageMetadata().version()}\n`);
+        return;
+    }
     const program = buildProgram();
     try {
         await program.parseAsync(argv);
@@ -13,7 +22,9 @@ export async function main(argv = process.argv) {
             process.exitCode = 1;
             return;
         }
-        throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
     }
 }
 function isCliEntrypoint(argv = process.argv) {

package/dist/commands/dependencies.js

@@ -1,6 +1,4 @@
 import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
 import { DeploymentBootstrapper } from "../core/bootstrap/DeploymentBootstrapper.js";
 import { ApiEnvFileWriter } from "../core/config/ApiEnvFileWriter.js";
 import { GithubAppConfigStore } from "../core/config/GithubAppConfigStore.js";
@@ -11,17 +9,21 @@ import { LocalServiceProcessManager } from "../core/local/LocalServiceProcessMan
 import { WebLocalService } from "../core/local/WebLocalService.js";
 import { LogsService } from "../core/logs/LogsService.js";
 import { CommandRunner } from "../core/process/CommandRunner.js";
-import { ProjectPaths } from "../core/runtime/ProjectPaths.js";
 import { RunnerSupervisor } from "../core/runner/RunnerSupervisor.js";
+import { defaultCliRoot } from "../core/runtime/CliRoot.js";
 import { createPasswordHash } from "../core/runtime/Secrets.js";
 import { RuntimePaths } from "../core/runtime/RuntimePaths.js";
 import { RuntimeStateStore } from "../core/runtime/RuntimeStateStore.js";
 import { VersionCatalog } from "../core/runtime/VersionCatalog.js";
 import { StatusService } from "../core/status/StatusService.js";
 import { TerminalRenderer } from "../core/ui/TerminalRenderer.js";
+import { LocalConfigStore } from "../core/runtime/LocalConfigStore.js";
+import { PortAllocator } from "../core/runtime/PortAllocator.js";
+import { runStartupPreflightChecks } from "../preflight/runStartupPreflightChecks.js";
 import { ensureGithubAppConfig } from "./setup-github-app.js";
+import { ensureAgentWorkspaceMode } from "./startup-preferences.js";
 function runtimeRoot() {
-    return process.env.COMPANYHELM_HOME || path.join(os.homedir(), ".companyhelm");
+    return defaultCliRoot();
 }
 export function createDefaultDependencies() {
     const root = runtimeRoot();
@@ -33,9 +35,9 @@ export function createDefaultDependencies() {
     const runnerSupervisor = new RunnerSupervisor(runtimePaths.runnerConfigPath());
     const bootstrapper = new DeploymentBootstrapper();
     const githubAppConfigStore = new GithubAppConfigStore();
-    const apiEnvFileWriter = new ApiEnvFileWriter(process.cwd());
-    const projectPaths = new ProjectPaths(process.cwd());
+    const apiEnvFileWriter = new ApiEnvFileWriter(root);
     const localRepoSourceResolver = new LocalRepoSourceResolver(process.cwd());
+    const localConfigStore = new LocalConfigStore();
     const localServiceProcessManager = new LocalServiceProcessManager();
     const apiLocalService = new ApiLocalService(localServiceProcessManager, commandRunner);
     const webLocalService = new WebLocalService(localServiceProcessManager, commandRunner);
@@ -86,11 +88,21 @@ export function createDefaultDependencies() {
         async up(options = {}) {
             const logLevel = options.logLevel ?? "info";
             const useHostDockerRuntime = options.useHostDockerRuntime ?? false;
-            const githubAppConfig = await ensureGithubAppConfig(githubAppConfigStore, process.stdin, process.stdout);
-            const state = stateStore.initialize();
             process.stdout.write(`${renderer.renderBanner()}\n`);
-            const runnerAlreadyRunning = await isRunnerRunning(commandRunner, runnerSupervisor);
             const desiredSources = localRepoSourceResolver.resolve(options);
+            const currentState = stateStore.load();
+            const allocatedPorts = currentState?.ports ?? new PortAllocator().allocate();
+            await runStartupPreflightChecks({
+                commandRunner,
+                currentState,
+                desiredSources,
+                ports: allocatedPorts,
+                readStatus: () => statusService.read()
+            });
+            const workspaceMode = await ensureAgentWorkspaceMode(localConfigStore, process.stdin, process.stdout);
+            const githubAppConfig = await ensureGithubAppConfig(githubAppConfigStore, process.stdin, process.stdout, { workspaceMode });
+            const state = currentState ?? stateStore.initialize();
+            const runnerAlreadyRunning = await isRunnerRunning(commandRunner, runnerSupervisor);
             const versions = versionCatalog.resolve();
             const passwordRecord = createPasswordHash(state.auth.password);
             const startedLocalServices = [];
@@ -100,7 +112,8 @@ export function createDefaultDependencies() {
             apiEnvFileWriter.write(githubAppConfig);
             bootstrapper.writeSeedSql(root, state, passwordRecord.passwordHash, passwordRecord.passwordSalt);
             bootstrapper.writeApiConfig(root, state, logLevel, {
-                databaseHost: desiredSources.api.source === "local" ? "127.0.0.1" : "postgres"
+                databaseHost: desiredSources.api.source === "local" ? "127.0.0.1" : "postgres",
+                githubAppConfig
             });
             bootstrapper.writeFrontendConfig(root, state);
             await stopLocalServicesFromState(stateStore.load(), localServiceProcessManager);
@@ -141,14 +154,16 @@ export function createDefaultDependencies() {
                     await commandRunner.run(configureSdkCommand.command, configureSdkCommand.args);
                     const startCommand = runnerSupervisor.buildStartArgs({
                         serverUrl: `127.0.0.1:${state.ports.runnerGrpc}`,
-                        agentApiUrl: `127.0.0.1:${state.ports.agentCliGrpc}`,
+                        agentApiUrl: `http://127.0.0.1:${state.ports.apiHttp}/agent/v1`,
                         logPath: runtimePaths.runnerLogPath(),
                         secret: state.runner.secret,
                         logLevel,
-                        useHostDockerRuntime
+                        useHostDockerRuntime,
+                        workspaceMode,
+                        projectRoot: process.cwd()
                     });
                     process.stdout.write(`${renderer.progress("Starting the runner...")}\n`);
-                    await commandRunner.run(startCommand.command, startCommand.args);
+                    await commandRunner.run(startCommand.command, startCommand.args, undefined, startCommand.env);
                     runnerStarted = true;
                 }
                 if (desiredSources.frontend.source === "local") {
@@ -246,7 +261,7 @@ export function createDefaultDependencies() {
                 await stopLocalServicesFromState(state, localServiceProcessManager);
             }
             await dockerStackManager.down({ removeVolumes: true });
-            fs.rmSync(projectPaths.apiEnvPath(), { force: true });
+            fs.rmSync(localConfigStore.configPath(), { force: true });
             fs.rmSync(root, { recursive: true, force: true });
             if (options.removeGithubAppConfig) {
                 githubAppConfigStore.delete();

package/dist/commands/interactive.d.ts

@@ -2,5 +2,6 @@ import type { Readable, Writable } from "node:stream";
 export declare class InteractiveCommandCancelledError extends Error {
     constructor(message: string);
 }
+export declare function hasInteractiveTerminal(input: Readable, output: Writable): boolean;
 export declare function requireInteractiveTerminal(input: Readable, output: Writable, message: string): void;
 export declare function unwrapPromptResult<T>(value: T | symbol, message: string, output: Writable): T;

package/dist/commands/interactive.js

@@ -8,8 +8,11 @@ export class InteractiveCommandCancelledError extends Error {
 function isReadableTty(input) {
     return "isTTY" in input && Boolean(input.isTTY);
 }
+export function hasInteractiveTerminal(input, output) {
+    return isReadableTty(input) && clack.isTTY(output);
+}
 export function requireInteractiveTerminal(input, output, message) {
-    if (!isReadableTty(input) || !clack.isTTY(output)) {
+    if (!hasInteractiveTerminal(input, output)) {
         throw new Error(message);
     }
 }

package/dist/commands/logs.js

@@ -1,4 +1,4 @@
-const AVAILABLE_LOG_SERVICES = ["postgres", "api", "frontend", "runner"];
+import { AVAILABLE_MANAGED_SERVICE_NAMES } from "../core/services/ManagedServiceNames.js";
 export function registerLogsCommand(program, dependencies) {
     program
         .command("logs")
@@ -6,7 +6,7 @@ export function registerLogsCommand(program, dependencies) {
         .argument("[service]")
         .action(async (service) => {
         if (!service) {
-            process.stdout.write(`Available services:\n${AVAILABLE_LOG_SERVICES.map((name) => `- ${name}`).join("\n")}\n`);
+            process.stdout.write(`Available services:\n${AVAILABLE_MANAGED_SERVICE_NAMES.map((name) => `- ${name}`).join("\n")}\n`);
             return;
         }
         await dependencies.logs(service);

package/dist/commands/register-commands.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { createDefaultDependencies } from "./dependencies.js";
+import { CliPackageMetadata } from "../core/runtime/CliPackageMetadata.js";
 import { registerDownCommand } from "./down.js";
 import { registerLogsCommand } from "./logs.js";
 import { registerResetCommand } from "./reset.js";
@@ -8,7 +9,9 @@ import { registerSetImageVersionCommand } from "./set-image-version.js";
 import { registerStatusCommand } from "./status.js";
 import { registerUpCommand } from "./up.js";
 export function buildProgram(dependencies = createDefaultDependencies()) {
-    const program = new Command().name("companyhelm");
+    const program = new Command()
+        .name("companyhelm")
+        .version(new CliPackageMetadata().version());
     registerSetupGithubAppCommand(program);
     registerUpCommand(program, dependencies);
     registerDownCommand(program, dependencies);

package/dist/commands/reset.js

@@ -4,7 +4,7 @@ import { requireInteractiveTerminal, unwrapPromptResult } from "./interactive.js
 export async function confirmReset(input = process.stdin, output = process.stdout) {
     requireInteractiveTerminal(input, output, "reset requires confirmation from a TTY. Re-run with --yes to skip the prompt.");
     const confirmed = await clack.confirm({
-        message: "This will remove CompanyHelm containers, Postgres data, local runtime state, and generated .companyhelm/api/.env. Continue?",
+        message: "This will remove CompanyHelm containers, Postgres data, generated runtime files under ~/.companyhelm/cli/runtime, and the CLI workspace config under ~/.companyhelm/cli/config.yaml. Continue?",
         active: "Yes",
         inactive: "No",
         initialValue: false,

package/dist/commands/set-image-version.js

@@ -1,7 +1,7 @@
 import * as clack from "@clack/prompts";
-import { LocalConfigStore } from "../core/runtime/LocalConfigStore.js";
 import { MANAGED_IMAGE_SERVICES, requireManagedImageService } from "../core/runtime/ManagedImages.js";
 import { PublicImageTagRegistry } from "../core/runtime/PublicImageTagRegistry.js";
+import { RepoConfigStore } from "../core/runtime/RepoConfigStore.js";
 import { requireInteractiveTerminal, unwrapPromptResult } from "./interactive.js";
 function parsePositiveInteger(value) {
     const parsed = Number.parseInt(value, 10);
@@ -59,7 +59,7 @@ export async function runSetImageVersion(options, dependencies = {}) {
     const input = dependencies.input ?? process.stdin;
     const output = dependencies.output ?? process.stdout;
     const registry = dependencies.registry ?? new PublicImageTagRegistry();
-    const configStore = dependencies.configStore ?? new LocalConfigStore();
+    const configStore = dependencies.configStore ?? new RepoConfigStore();
     clack.intro("CompanyHelm image selection", { output });
     const selectedService = options.service
         ? requireManagedImageService(options.service)
@@ -78,7 +78,7 @@ export async function runSetImageVersion(options, dependencies = {}) {
 export function registerSetImageVersionCommand(program) {
     program
         .command("set-image-version")
-        .description("Interactively choose an API or frontend image tag and store it in local config.yaml.")
+        .description("Interactively choose an API or frontend image tag and store it in the project config.")
         .option("-s, --service <service>", "Prefill the service to update (api or frontend)")
         .option("-l, --limit <count>", "How many image tags to show", parsePositiveInteger, 20)
         .action(async (options) => {

package/dist/commands/setup-github-app.d.ts

@@ -2,9 +2,12 @@ import { Writable, type Readable } from "node:stream";
 import type { Command } from "commander";
 import { GithubAppConfigStore } from "../core/config/GithubAppConfigStore.js";
 import { type GithubAppConfig } from "../core/config/GithubAppConfig.js";
+import type { AgentWorkspaceMode } from "../core/runtime/LocalConfigStore.js";
 type BrowserUrlOpener = (url: string) => Promise<void>;
 export declare function readPemFromTerminal(input?: Readable, output?: Writable): Promise<string>;
 export declare function promptGithubAppConfig(input?: Readable, output?: Writable, openBrowser?: BrowserUrlOpener): Promise<GithubAppConfig>;
-export declare function ensureGithubAppConfig(store?: GithubAppConfigStore, input?: Readable, output?: Writable): Promise<GithubAppConfig>;
+export declare function ensureGithubAppConfig(store?: GithubAppConfigStore, input?: Readable, output?: Writable, options?: {
+    workspaceMode?: AgentWorkspaceMode;
+}): Promise<GithubAppConfig | null>;
 export declare function registerSetupGithubAppCommand(program: Command, store?: GithubAppConfigStore): void;
 export {};

package/dist/commands/setup-github-app.js

@@ -3,7 +3,7 @@ import chalk from "chalk";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { Writable } from "node:stream";
-import { unwrapPromptResult, requireInteractiveTerminal, InteractiveCommandCancelledError } from "./interactive.js";
+import { unwrapPromptResult, requireInteractiveTerminal, InteractiveCommandCancelledError, hasInteractiveTerminal } from "./interactive.js";
 import { GithubAppConfigStore } from "../core/config/GithubAppConfigStore.js";
 import { normalizeGithubAppConfig } from "../core/config/GithubAppConfig.js";
 const GITHUB_NEW_APP_URL = "https://github.com/settings/apps/new";
@@ -176,17 +176,39 @@ export async function promptGithubAppConfig(input = process.stdin, output = proc
         appPrivateKeyPem,
     });
 }
-export async function ensureGithubAppConfig(store = new GithubAppConfigStore(), input = process.stdin, output = process.stdout) {
+export async function ensureGithubAppConfig(store = new GithubAppConfigStore(), input = process.stdin, output = process.stdout, options = {}) {
     const existingConfig = store.load();
     if (existingConfig) {
         return existingConfig;
     }
-    requireInteractiveTerminal(input, output, `GitHub App config is not set up. Run \`companyhelm setup-github-app\` or rerun \`companyhelm up\` in a TTY.`);
-    clack.intro("CompanyHelm GitHub App setup", { output });
-    clack.note([
-        "No machine GitHub App config was found.",
-        "CompanyHelm will collect it now and then continue startup.",
-    ].join("\n"), "Setup required", { output });
+    if (!hasInteractiveTerminal(input, output)) {
+        return null;
+    }
+    const workspaceMode = options.workspaceMode ?? "dedicated";
+    clack.intro("CompanyHelm GitHub auth", { output });
+    clack.note(workspaceMode === "dedicated"
+        ? [
+            "No machine GitHub App config was found.",
+            "Dedicated workspaces cannot access files from your host system.",
+            "GitHub auth is recommended so agents can clone and work in your repositories.",
+        ].join("\n")
+        : [
+            "No machine GitHub App config was found.",
+            "GitHub auth is optional in current working directory mode.",
+            "Set it up now if you want agents to access GitHub directly from this deployment.",
+        ].join("\n"), "Optional setup", { output });
+    const shouldSetup = unwrapPromptResult(await clack.confirm({
+        message: "Set up GitHub auth now?",
+        active: "Set it up",
+        inactive: "Skip for now",
+        initialValue: false,
+        input,
+        output,
+    }), "GitHub App setup cancelled.", output);
+    if (!shouldSetup) {
+        clack.outro("Skipping GitHub App setup. Continuing startup without GitHub access.", { output });
+        return null;
+    }
     const config = await promptGithubAppConfig(input, output);
     const spinner = clack.spinner({ output });
     spinner.start("Saving machine GitHub App config");

package/dist/commands/startup-preferences.d.ts

@@ -0,0 +1,3 @@
+import type { Readable, Writable } from "node:stream";
+import { LocalConfigStore, type AgentWorkspaceMode } from "../core/runtime/LocalConfigStore.js";
+export declare function ensureAgentWorkspaceMode(store?: LocalConfigStore, input?: Readable, output?: Writable): Promise<AgentWorkspaceMode>;

package/dist/commands/startup-preferences.js

@@ -0,0 +1,39 @@
+import * as clack from "@clack/prompts";
+import { unwrapPromptResult, hasInteractiveTerminal } from "./interactive.js";
+import { LocalConfigStore } from "../core/runtime/LocalConfigStore.js";
+const DEFAULT_WORKSPACE_MODE = "current-working-directory";
+export async function ensureAgentWorkspaceMode(store = new LocalConfigStore(), input = process.stdin, output = process.stdout) {
+    const existingMode = store.load().agentWorkspaceMode;
+    if (existingMode) {
+        return existingMode;
+    }
+    if (!hasInteractiveTerminal(input, output)) {
+        return DEFAULT_WORKSPACE_MODE;
+    }
+    clack.note([
+        "Choose where agent threads should run.",
+        "Dedicated workspaces keep agents isolated from your host filesystem.",
+        "In dedicated mode agents will not have access to files on your system, so GitHub auth is recommended if you want them to clone your repositories.",
+        "Current working directory mode mounts this checkout directly into agent threads.",
+    ].join("\n"), "Agent workspace", { output });
+    const selectedMode = unwrapPromptResult(await clack.select({
+        message: "Where should agents operate?",
+        options: [
+            {
+                value: "current-working-directory",
+                label: "Current working directory",
+                hint: "recommended: agents work directly in this checkout"
+            },
+            {
+                value: "dedicated",
+                label: "Dedicated workspaces directory",
+                hint: "isolated thread workspaces"
+            }
+        ],
+        initialValue: DEFAULT_WORKSPACE_MODE,
+        input,
+        output
+    }), "Workspace selection cancelled.", output);
+    store.setAgentWorkspaceMode(selectedMode);
+    return selectedMode;
+}

package/dist/core/bootstrap/DeploymentBootstrapper.d.ts

@@ -1,4 +1,5 @@
 import type { LogLevel } from "../../commands/dependencies.js";
+import type { GithubAppConfig } from "../config/GithubAppConfig.js";
 import type { RuntimeState } from "../runtime/RuntimeState.js";
 export declare class DeploymentBootstrapper {
     private readonly renderer;
@@ -7,7 +8,7 @@ export declare class DeploymentBootstrapper {
         databaseHost?: string;
         appPort?: number;
         runnerGrpcPort?: number;
-        agentGrpcPort?: number;
+        githubAppConfig?: GithubAppConfig | null;
     }): string;
     writeFrontendConfig(root: string, state: RuntimeState): string;
     private indentBlock;

package/dist/core/bootstrap/DeploymentBootstrapper.js

@@ -23,8 +23,18 @@ export class DeploymentBootstrapper {
         const outputPath = runtimePaths.apiConfigPath();
         const appPort = options.appPort ?? state.ports.apiHttp;
         const runnerGrpcPort = options.runnerGrpcPort ?? state.ports.runnerGrpc;
-        const agentGrpcPort = options.agentGrpcPort ?? state.ports.agentCliGrpc;
         const databaseHost = options.databaseHost ?? "postgres";
+        const githubConfigLines = options.githubAppConfig
+            ? [
+                '  app_client_id: "${GITHUB_APP_CLIENT_ID}"',
+                '  app_private_key_pem: "${GITHUB_APP_PRIVATE_KEY_PEM}"',
+                '  app_link: "${GITHUB_APP_URL}"'
+            ]
+            : [
+                '  app_client_id: "companyhelm-local-github-disabled"',
+                '  app_private_key_pem: "companyhelm-local-github-disabled"',
+                '  app_link: "https://github.com/apps/companyhelm-local-disabled"'
+            ];
         const yaml = [
             "app:",
             '  host: "0.0.0.0"',
@@ -37,10 +47,17 @@ export class DeploymentBootstrapper {
             "    heartbeat:",
             "      intervalMs: 20000",
             "      jitterMs: 10000",
-            "agent:",
-            "  grpc:",
-            '    host: "0.0.0.0"',
-            `    port: ${agentGrpcPort}`,
+            "  workers:",
+            "    agentHeartbeats:",
+            "      intervalSeconds: 60",
+            "      jitterSeconds: 60",
+            "      batchSize: 10",
+            "      leaseSeconds: 120",
+            "    taskWorker:",
+            "      intervalSeconds: 60",
+            "      jitterSeconds: 60",
+            "      batchSize: 10",
+            "      leaseSeconds: 120",
             "database:",
             '  name: "companyhelm"',
             `  host: "${databaseHost}"`,
@@ -53,9 +70,7 @@ export class DeploymentBootstrapper {
             '      username: "postgres"',
             '      password: "postgres"',
             "github:",
-            '  app_client_id: "${GITHUB_APP_CLIENT_ID}"',
-            '  app_private_key_pem: "${GITHUB_APP_PRIVATE_KEY_PEM}"',
-            '  app_link: "${GITHUB_APP_URL}"',
+            ...githubConfigLines,
             'authProvider: "companyhelm"',
             "auth:",
             "  companyhelm:",

package/dist/core/config/ApiEnvFileWriter.d.ts

@@ -1,6 +1,8 @@
 import type { GithubAppConfig } from "./GithubAppConfig.js";
 export declare class ApiEnvFileWriter {
-    private readonly projectPaths;
-    constructor(projectRoot?: string);
-    write(config: GithubAppConfig): string;
+    private readonly runtimePaths;
+    private readonly templatePath;
+    constructor(root: string);
+    write(config: GithubAppConfig | null): string;
+    private render;
 }

package/dist/core/config/ApiEnvFileWriter.js

@@ -1,5 +1,7 @@
 import fs from "node:fs";
-import { ProjectPaths } from "../runtime/ProjectPaths.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { RuntimePaths } from "../runtime/RuntimePaths.js";
 function escapeEnvValue(value) {
     return String(value || "")
         .replace(/\\/g, "\\\\")
@@ -8,19 +10,24 @@ function escapeEnvValue(value) {
         .replace(/\n/g, "\\n");
 }
 export class ApiEnvFileWriter {
-    projectPaths;
-    constructor(projectRoot = process.cwd()) {
-        this.projectPaths = new ProjectPaths(projectRoot);
+    runtimePaths;
+    templatePath;
+    constructor(root) {
+        this.runtimePaths = new RuntimePaths(root);
+        this.templatePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../templates/api.env.tpl");
     }
     write(config) {
-        fs.mkdirSync(this.projectPaths.apiDirectoryPath(), { recursive: true });
-        const contents = [
-            `GITHUB_APP_URL=${escapeEnvValue(config.appUrl)}`,
-            `GITHUB_APP_CLIENT_ID=${escapeEnvValue(config.appClientId)}`,
-            `GITHUB_APP_PRIVATE_KEY_PEM=${escapeEnvValue(config.appPrivateKeyPem)}`,
-            "",
-        ].join("\n");
-        fs.writeFileSync(this.projectPaths.apiEnvPath(), contents, "utf8");
-        return this.projectPaths.apiEnvPath();
+        fs.mkdirSync(this.runtimePaths.apiDirectoryPath(), { recursive: true });
+        const contents = this.render(config);
+        fs.writeFileSync(this.runtimePaths.apiEnvPath(), contents, "utf8");
+        return this.runtimePaths.apiEnvPath();
+    }
+    render(config) {
+        const template = fs.readFileSync(this.templatePath, "utf8");
+        const rendered = template
+            .replace("{{GITHUB_APP_URL}}", escapeEnvValue(config?.appUrl ?? ""))
+            .replace("{{GITHUB_APP_CLIENT_ID}}", escapeEnvValue(config?.appClientId ?? ""))
+            .replace("{{GITHUB_APP_PRIVATE_KEY_PEM}}", escapeEnvValue(config?.appPrivateKeyPem ?? ""));
+        return rendered.endsWith("\n") ? rendered : `${rendered}\n`;
     }
 }

package/dist/core/config/GithubAppConfigStore.js

@@ -1,18 +1,10 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { parse, stringify } from "yaml";
 import { normalizeGithubAppConfig } from "./GithubAppConfig.js";
+import { defaultCliConfigRoot } from "../runtime/CliRoot.js";
 function defaultConfigRoot() {
-    const explicitRoot = String(process.env.COMPANYHELM_CONFIG_HOME || "").trim();
-    if (explicitRoot) {
-        return path.resolve(explicitRoot);
-    }
-    const xdgRoot = String(process.env.XDG_CONFIG_HOME || "").trim();
-    if (xdgRoot) {
-        return path.resolve(xdgRoot, "companyhelm");
-    }
-    return path.join(os.homedir(), ".config", "companyhelm");
+    return defaultCliConfigRoot();
 }
 export class GithubAppConfigStore {
     configRoot;

package/dist/core/docker/ComposeTemplateRenderer.js

@@ -29,7 +29,6 @@ export class ComposeTemplateRenderer {
             "    ports:",
             `      - "${ports.apiHttpPort}:4000"`,
             `      - "${ports.runnerGrpcPort}:${ports.runnerGrpcPort}"`,
-            `      - "${ports.agentCliGrpcPort}:${ports.agentCliGrpcPort}"`,
             "    volumes:",
             `      - "${paths.apiConfigPath}:/run/companyhelm/config.yaml:ro"`,
             "    networks:",

package/dist/core/docker/DockerStackManager.js

@@ -1,6 +1,5 @@
 import fs from "node:fs";
 import { CommandRunner } from "../process/CommandRunner.js";
-import { ProjectPaths } from "../runtime/ProjectPaths.js";
 import { RuntimePaths } from "../runtime/RuntimePaths.js";
 import { ComposeTemplateRenderer } from "./ComposeTemplateRenderer.js";
 export class DockerStackManager {
@@ -23,7 +22,7 @@ export class DockerStackManager {
             agentCliGrpcPort: state.ports.agentCliGrpc
         }, {
             apiConfigPath: this.runtimePaths.apiConfigPath(),
-            apiEnvPath: new ProjectPaths(process.cwd()).apiEnvPath(),
+            apiEnvPath: this.runtimePaths.apiEnvPath(),
             frontendConfigPath: this.runtimePaths.frontendConfigPath(),
             seedFilePath: this.runtimePaths.seedFilePath()
         }, {

package/dist/core/local/ApiLocalService.d.ts

@@ -8,7 +8,7 @@ export interface ApiLocalServiceStartInput {
     configPath: string;
     graphqlUrl: string;
     logPath: string;
-    githubAppConfig: GithubAppConfig;
+    githubAppConfig: GithubAppConfig | null;
     state: RuntimeState;
     logLevel: LogLevel;
 }

package/dist/core/local/ApiLocalService.js

@@ -24,9 +24,9 @@ export class ApiLocalService {
             logPath: input.logPath,
             env: {
                 APP_ENV: "local",
-                GITHUB_APP_CLIENT_ID: input.githubAppConfig.appClientId,
-                GITHUB_APP_URL: input.githubAppConfig.appUrl,
-                GITHUB_APP_PRIVATE_KEY_PEM: input.githubAppConfig.appPrivateKeyPem,
+                GITHUB_APP_CLIENT_ID: input.githubAppConfig?.appClientId ?? "",
+                GITHUB_APP_URL: input.githubAppConfig?.appUrl ?? "",
+                GITHUB_APP_PRIVATE_KEY_PEM: input.githubAppConfig?.appPrivateKeyPem ?? "",
                 COMPANYHELM_JWT_PRIVATE_KEY_PEM: input.state.auth.jwtPrivateKeyPem,
                 COMPANYHELM_JWT_PUBLIC_KEY_PEM: input.state.auth.jwtPublicKeyPem,
                 COMPANYHELM_LOG_LEVEL: input.logLevel

package/dist/core/logs/LogsService.d.ts

@@ -1,5 +1,6 @@
+import { type ManagedServiceKey } from "../services/ManagedServiceNames.js";
 export declare class LogsService {
     private readonly streamServiceLogs;
-    constructor(streamServiceLogs: (service: "postgres" | "api" | "frontend" | "runner") => Promise<void>);
+    constructor(streamServiceLogs: (service: ManagedServiceKey) => Promise<void>);
     stream(service: string): Promise<void>;
 }

package/dist/core/logs/LogsService.js

@@ -1,13 +1,14 @@
-const MANAGED_SERVICES = new Set(["postgres", "api", "frontend", "runner"]);
+import { AVAILABLE_MANAGED_SERVICE_NAMES, resolveManagedServiceKey } from "../services/ManagedServiceNames.js";
 export class LogsService {
     streamServiceLogs;
     constructor(streamServiceLogs) {
         this.streamServiceLogs = streamServiceLogs;
     }
     async stream(service) {
-        if (!MANAGED_SERVICES.has(service)) {
-            throw new Error(`Unknown service '${service}'. Expected one of: ${Array.from(MANAGED_SERVICES).join(", ")}`);
+        const resolvedService = resolveManagedServiceKey(service);
+        if (!resolvedService) {
+            throw new Error(`Unknown service '${service}'. Expected one of: ${AVAILABLE_MANAGED_SERVICE_NAMES.join(", ")}`);
         }
-        await this.streamServiceLogs(service);
+        await this.streamServiceLogs(resolvedService);
     }
 }

package/dist/core/runner/RunnerSupervisor.d.ts

@@ -1,4 +1,5 @@
 import type { LogLevel } from "../../commands/dependencies.js";
+import type { AgentWorkspaceMode } from "../runtime/LocalConfigStore.js";
 export interface RunnerStartInput {
     serverUrl: string;
     agentApiUrl: string;
@@ -6,10 +7,13 @@ export interface RunnerStartInput {
     secret: string;
     logLevel?: LogLevel;
     useHostDockerRuntime?: boolean;
+    workspaceMode?: AgentWorkspaceMode;
+    projectRoot?: string;
 }
 export interface RunnerStartCommand {
     command: string;
     args: string[];
+    env?: NodeJS.ProcessEnv;
 }
 export declare class RunnerSupervisor {
     private readonly configPath;
@@ -19,5 +23,7 @@ export declare class RunnerSupervisor {
     buildStopArgs(): RunnerStartCommand;
     buildStatusArgs(): RunnerStartCommand;
     private resolveRunnerCliPath;
+    private resolveRunnerCliOverridePath;
+    private resolveRunnerEntrypointPath;
     private resolveHostDockerPath;
 }