@companyhelm/cli 0.0.2 → 0.0.5

package/dist/commands/startup.js

@@ -53,97 +53,184 @@ function banner() {
     console.log(figlet_1.default.textSync("CompanyHelm", { font: "Small" }));
     console.log();
 }
-async function refreshCodexModelsInStartup() {
-    const spinner = p.spinner();
+function isErrnoException(error) {
+    return error instanceof Error && "code" in error;
+}
+function buildDockerMissingError() {
+    return new Error("Docker is not installed or not available on PATH. Install Docker and retry.");
+}
+const defaultStartupDependencies = {
+    getHostInfoFn: host_js_1.getHostInfo,
+    initDbFn: db_js_1.initDb,
+    promptApi: p,
+    refreshSdkModelsFn: refresh_models_js_1.refreshSdkModels,
+    spawnCommand: node_child_process_1.spawn,
+    spawnSyncCommand: node_child_process_1.spawnSync,
+};
+function ensureDockerAvailable(spawnSyncCommand) {
+    const result = spawnSyncCommand("docker", ["--version"], { stdio: "ignore" });
+    if (isErrnoException(result.error) && result.error.code === "ENOENT") {
+        throw buildDockerMissingError();
+    }
+}
+function restoreInteractiveTerminalState() {
+    try {
+        if (process.stdin.isTTY && typeof process.stdin.setRawMode === "function") {
+            process.stdin.setRawMode(false);
+        }
+    }
+    catch {
+        // Best-effort prompt cleanup.
+    }
+    try {
+        if (process.stdout.isTTY) {
+            process.stdout.write("\u001B[?25h");
+        }
+    }
+    catch {
+        // Best-effort prompt cleanup.
+    }
+}
+function exitStartup(code) {
+    restoreInteractiveTerminalState();
+    process.exit(code);
+}
+async function refreshCodexModelsInStartup(deps) {
+    ensureDockerAvailable(deps.spawnSyncCommand);
+    const spinner = deps.promptApi.spinner();
     const seenStatusMessages = new Set();
     spinner.start("Preparing Codex runtime image and refreshing model catalog via app-server");
-    const results = await (0, refresh_models_js_1.refreshSdkModels)({
+    const results = await deps.refreshSdkModelsFn({
         sdk: "codex",
         imageStatusReporter: (message) => {
             if (seenStatusMessages.has(message)) {
                 return;
             }
             seenStatusMessages.add(message);
-            p.log.info(message);
+            deps.promptApi.log.info(message);
         },
     });
     const count = results[0]?.modelCount ?? 0;
     spinner.stop(`Codex model catalog refreshed (${count} models).`);
 }
-async function dedicatedAuth(cfg, db) {
+async function dedicatedAuth(cfg, db, deps) {
+    ensureDockerAvailable(deps.spawnSyncCommand);
     const port = cfg.codex.codex_auth_port;
     const socatPort = port + 1;
     const containerName = `companyhelm-codex-auth-${Date.now()}`;
-    p.log.info("Starting Codex login inside a container...");
-    p.log.info("A browser URL will appear -- open it to complete authentication.");
+    deps.promptApi.log.info("Starting Codex login inside a container...");
+    deps.promptApi.log.info("A browser URL will appear -- open it to complete authentication.");
     const configDir = (0, path_js_1.expandHome)(cfg.config_directory);
     if (!(0, node_fs_1.existsSync)(configDir)) {
         (0, node_fs_1.mkdirSync)(configDir, { recursive: true });
     }
     const destPath = (0, node_path_1.join)(configDir, cfg.codex.codex_auth_file_path);
-    const child = (0, node_child_process_1.spawn)("docker", [
-        "run",
-        "-it",
-        "--name",
-        containerName,
-        "-p",
-        `${port}:${socatPort}`,
-        "--entrypoint",
-        "bash",
-        cfg.runtime_image,
-        "-c",
-        `source "$NVM_DIR/nvm.sh"; socat TCP-LISTEN:${socatPort},fork,bind=0.0.0.0,reuseaddr TCP:127.0.0.1:${port} 2>/dev/null & codex`,
-    ], { stdio: "inherit" });
     let authCopied = false;
     await new Promise((resolve, reject) => {
-        const poll = setInterval(() => {
-            const check = (0, node_child_process_1.spawnSync)("docker", ["exec", containerName, "sh", "-c", `test -f ${cfg.codex.codex_auth_path}`], {
+        let settled = false;
+        let poll;
+        const rejectOnce = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (poll) {
+                clearInterval(poll);
+            }
+            deps.spawnSyncCommand("docker", ["rm", "-f", containerName], { stdio: "ignore" });
+            reject(error);
+        };
+        const resolveOnce = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (poll) {
+                clearInterval(poll);
+            }
+            resolve();
+        };
+        const child = deps.spawnCommand("docker", [
+            "run",
+            "-it",
+            "--name",
+            containerName,
+            "-p",
+            `${port}:${socatPort}`,
+            "--entrypoint",
+            "bash",
+            cfg.runtime_image,
+            "-c",
+            `source "$NVM_DIR/nvm.sh"; socat TCP-LISTEN:${socatPort},fork,bind=0.0.0.0,reuseaddr TCP:127.0.0.1:${port} 2>/dev/null & codex`,
+        ], { stdio: "inherit" });
+        child.on("error", (error) => {
+            if (isErrnoException(error) && error.code === "ENOENT") {
+                rejectOnce(buildDockerMissingError());
+                return;
+            }
+            rejectOnce(new Error(`Failed to start Codex login container: ${error.message}`));
+        });
+        poll = setInterval(() => {
+            if (settled) {
+                return;
+            }
+            const check = deps.spawnSyncCommand("docker", ["exec", containerName, "sh", "-c", `test -f ${cfg.codex.codex_auth_path}`], {
                 stdio: "ignore",
             });
             if (check.status === 0) {
-                clearInterval(poll);
-                const resolveResult = (0, node_child_process_1.spawnSync)("docker", ["exec", containerName, "sh", "-c", `echo ${cfg.codex.codex_auth_path}`], {
+                const resolveResult = deps.spawnSyncCommand("docker", ["exec", containerName, "sh", "-c", `echo ${cfg.codex.codex_auth_path}`], {
                     encoding: "utf-8",
                 });
                 const containerAuthAbsPath = resolveResult.stdout.trim();
-                const cpResult = (0, node_child_process_1.spawnSync)("docker", ["cp", `${containerName}:${containerAuthAbsPath}`, destPath], {
+                const cpResult = deps.spawnSyncCommand("docker", ["cp", `${containerName}:${containerAuthAbsPath}`, destPath], {
                     stdio: "ignore",
                 });
                 if (cpResult.status !== 0) {
-                    (0, node_child_process_1.spawnSync)("docker", ["rm", "-f", containerName], { stdio: "ignore" });
-                    reject(new Error("Failed to extract auth file from container."));
+                    rejectOnce(new Error("Failed to extract auth file from container."));
                     return;
                 }
                 authCopied = true;
-                (0, node_child_process_1.spawnSync)("docker", ["rm", "-f", containerName], { stdio: "ignore" });
-                resolve();
+                deps.spawnSyncCommand("docker", ["rm", "-f", containerName], { stdio: "ignore" });
+                resolveOnce();
             }
         }, 1000);
         child.on("exit", () => {
-            clearInterval(poll);
             if (!authCopied) {
-                (0, node_child_process_1.spawnSync)("docker", ["rm", "-f", containerName], { stdio: "ignore" });
-                reject(new Error("Codex login failed or was cancelled."));
+                rejectOnce(new Error("Codex login failed or was cancelled."));
             }
         });
     });
     await db.insert(schema_js_1.agentSdks).values({ name: "codex", authentication: "dedicated" });
-    p.log.success(`Codex auth saved to ${destPath}`);
+    deps.promptApi.log.success(`Codex auth saved to ${destPath}`);
 }
-async function startup() {
+async function selectStartupAuthMode(options, deps) {
+    if (options.length === 1) {
+        return options[0].value;
+    }
+    const authMode = await deps.promptApi.select({
+        message: "How would you like to authenticate Codex?",
+        options,
+    });
+    if (deps.promptApi.isCancel(authMode)) {
+        deps.promptApi.cancel("Setup cancelled.");
+        exitStartup(0);
+    }
+    return authMode;
+}
+async function startup(cfg = config_js_1.config.parse({}), overrides = {}) {
+    const deps = { ...defaultStartupDependencies, ...overrides };
     banner();
-    const cfg = config_js_1.config.parse({});
-    const s = p.spinner();
+    const s = deps.promptApi.spinner();
     s.start("Initializing state database");
-    const { db } = await (0, db_js_1.initDb)(cfg.state_db_path);
+    const { db } = await deps.initDbFn(cfg.state_db_path);
     s.stop("State database ready.");
     const sdks = await db.select().from(schema_js_1.agentSdks).all();
     if (sdks.length > 0) {
-        p.log.success(`Agent SDK configured: ${sdks.map((sdk) => sdk.name).join(", ")}`);
+        deps.promptApi.log.success(`Agent SDK configured: ${sdks.map((sdk) => sdk.name).join(", ")}`);
         return;
     }
-    p.intro("No agent SDK configured. Let's set up Codex authentication.");
-    const hostInfo = (0, host_js_1.getHostInfo)(cfg.codex.codex_auth_path);
+    deps.promptApi.intro("No agent SDK configured. Let's set up Codex authentication.");
+    const hostInfo = deps.getHostInfoFn(cfg.codex.codex_auth_path);
     const options = [
         {
             value: "dedicated",
@@ -158,28 +245,24 @@ async function startup() {
             hint: `reuse existing credentials from ${cfg.codex.codex_auth_path}`,
         });
     }
-    const authMode = await p.select({
-        message: "How would you like to authenticate Codex?",
-        options,
-    });
-    if (p.isCancel(authMode)) {
-        p.cancel("Setup cancelled.");
-        process.exit(0);
-    }
     try {
+        const authMode = await selectStartupAuthMode(options, deps);
         if (authMode === "host") {
             await db.insert(schema_js_1.agentSdks).values({ name: "codex", authentication: "host" });
-            await refreshCodexModelsInStartup();
-            p.outro("Codex SDK configured with host authentication.");
+            await refreshCodexModelsInStartup(deps);
+            deps.promptApi.outro("Codex SDK configured with host authentication.");
             return;
         }
-        await dedicatedAuth(cfg, db);
-        await refreshCodexModelsInStartup();
-        p.outro("Codex login successful!");
+        await dedicatedAuth(cfg, db, deps);
+        await refreshCodexModelsInStartup(deps);
+        deps.promptApi.outro("Codex login successful!");
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Codex setup failed.";
-        p.cancel(message);
-        process.exit(1);
+        deps.promptApi.cancel(message);
+        exitStartup(1);
+    }
+    finally {
+        restoreInteractiveTerminalState();
     }
 }

package/dist/commands/status.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStatusCommand = registerStatusCommand;
+const node_path_1 = require("node:path");
+const config_js_1 = require("../config.js");
+const daemon_state_js_1 = require("../state/daemon_state.js");
+const daemon_js_1 = require("../utils/daemon.js");
+const process_js_1 = require("../utils/process.js");
+function registerStatusCommand(program) {
+    program
+        .command("status")
+        .description("Show whether the local CompanyHelm daemon is running.")
+        .option("--state-db-path <path>", "State database path override (defaults to ~/.local/share/companyhelm/state.db).")
+        .action(async (options) => {
+        const cfg = config_js_1.config.parse({
+            state_db_path: options.stateDbPath,
+        });
+        const state = await (0, daemon_state_js_1.readCurrentDaemonState)(cfg.state_db_path);
+        const running = state?.pid != null && (0, process_js_1.isProcessRunning)(state.pid);
+        const logPath = state?.logPath ?? (0, daemon_js_1.resolveDaemonLogPath)(cfg.state_db_path);
+        const logDirectory = state?.logPath ? (0, node_path_1.dirname)(state.logPath) : (0, daemon_js_1.resolveDaemonLogDirectory)(cfg.state_db_path);
+        console.log(`Daemon: ${running ? "running" : "not running"}`);
+        if (state?.pid != null) {
+            console.log(`PID: ${running ? state.pid : `${state.pid} (stale)`}`);
+        }
+        else {
+            console.log("PID: none");
+        }
+        console.log(`Log directory: ${logDirectory}`);
+        console.log(`Log file: ${logPath}`);
+    });
+}

package/dist/service/app_server.js

@@ -104,6 +104,9 @@ class AppServerService {
     async startThread(params) {
         return this.request("thread/start", params, 15000);
     }
+    async startThreadWithResponse(params, requestId) {
+        return this.requestWithResponse("thread/start", params, 15000, requestId);
+    }
     async resumeThread(params) {
         return this.request("thread/resume", params, 15000);
     }
@@ -160,6 +163,9 @@ class AppServerService {
             if (message.method === "error" &&
                 message.params.threadId === threadId &&
                 message.params.turnId === turnId) {
+                if (message.params.willRetry) {
+                    continue;
+                }
                 throw new Error(message.params.error.message);
             }
             if (message.method === "turn/completed" &&
@@ -206,14 +212,22 @@ class AppServerService {
         }
     }
     async request(method, params, timeoutMs) {
-        const requestId = this.nextRequestId++;
+        const response = await this.requestWithResponse(method, params, timeoutMs);
+        return response.result;
+    }
+    async requestWithResponse(method, params, timeoutMs, requestId) {
+        const resolvedRequestId = requestId ?? this.nextRequestId++;
         const request = {
             method,
-            id: requestId,
+            id: resolvedRequestId,
             params,
         };
         await this.sendMessage(request);
-        return this.waitForResponseResult(requestId, timeoutMs);
+        const response = await this.waitForResponseMessage(resolvedRequestId, timeoutMs);
+        return {
+            id: response.id,
+            result: response.result,
+        };
     }
     async sendMessage(message) {
         const payload = JSON.stringify(message);
@@ -369,7 +383,7 @@ class AppServerService {
             pendingRequest.reject(new Error(`app-server returned an error for request ${String(message.id)}: ${formatUnknownError(message.error)}`));
             return;
         }
-        pendingRequest.resolve(message.result);
+        pendingRequest.resolve(message);
     }
     rejectAllPendingRequests(error) {
         for (const [requestId, pendingRequest] of this.pendingRequests.entries()) {
@@ -378,14 +392,14 @@ class AppServerService {
             pendingRequest.reject(new Error(`request ${String(requestId)} failed: ${error.message}`));
         }
     }
-    async waitForResponseResult(requestId, timeoutMs) {
+    async waitForResponseMessage(requestId, timeoutMs) {
         const immediateResponse = this.pendingResponses.get(requestId);
         if (immediateResponse) {
             this.pendingResponses.delete(requestId);
             if (immediateResponse.error !== undefined) {
                 throw new Error(`app-server returned an error for request ${String(requestId)}: ${formatUnknownError(immediateResponse.error)}`);
             }
-            return immediateResponse.result;
+            return immediateResponse;
         }
         return new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
@@ -394,8 +408,8 @@ class AppServerService {
             }, timeoutMs);
             const pendingRequest = {
                 timeout,
-                resolve: (result) => {
-                    resolve(result);
+                resolve: (message) => {
+                    resolve(message);
                 },
                 reject: (error) => {
                     reject(error);
@@ -413,7 +427,7 @@ class AppServerService {
                 reject(new Error(`app-server returned an error for request ${String(requestId)}: ${formatUnknownError(bufferedResponse.error)}`));
                 return;
             }
-            resolve(bufferedResponse.result);
+            resolve(bufferedResponse);
         });
     }
     formatDebugContext() {

package/dist/service/docker/app_server_container.js

@@ -151,7 +151,7 @@ class AppServerContainerService {
                 throw error;
             }
         }
-        this.reportImageStatus(`Docker image '${image}' not found locally. Downloading now.`);
+        this.reportImageStatus(`Docker image '${image}' not found locally. Pulling remotely.`);
         await this.pullImage(image);
         this.reportImageStatus(`Docker image '${image}' is ready.`);
     }
@@ -210,6 +210,7 @@ class AppServerContainerService {
             "-lc",
             bootstrapScript,
         ];
+        this.reportImageStatus(`Launching Docker container from image '${cfg.runtime_image}'.`);
         const child = (0, node_child_process_1.spawn)("docker", args, {
             stdio: ["pipe", "pipe", "pipe"],
         });
@@ -230,6 +231,7 @@ class AppServerContainerService {
         });
         this.child = child;
         this.running = true;
+        this.reportImageStatus(`Waiting for app-server to initialize in Docker container '${this.containerName}'.`);
     }
     async stop() {
         this.running = false;

package/dist/service/thread_lifecycle.js

@@ -527,7 +527,7 @@ class ThreadContainerService {
                 throw error;
             }
         }
-        imageStatusReporter?.(`Docker image '${image}' not found locally. Downloading now.`);
+        imageStatusReporter?.(`Docker image '${image}' not found locally. Pulling remotely.`);
         await this.pullImage(image, imageStatusReporter);
         imageStatusReporter?.(`Docker image '${image}' is ready.`);
     }
@@ -539,6 +539,7 @@ class ThreadContainerService {
             }
             await this.ensureImageAvailable(options.runtimeImage, options.imageStatusReporter);
             try {
+                options.imageStatusReporter?.(`Creating Docker container '${options.names.runtime}' from image '${options.runtimeImage}'.`);
                 await this.docker.createContainer(buildRuntimeContainerOptions(options));
             }
             catch (error) {
@@ -552,8 +553,10 @@ class ThreadContainerService {
         if (options.runtimeImage !== options.dindImage) {
             await this.ensureImageAvailable(options.runtimeImage, options.imageStatusReporter);
         }
+        options.imageStatusReporter?.(`Creating Docker container '${options.names.dind}' from image '${options.dindImage}'.`);
         await this.docker.createContainer(buildDindContainerOptions(options));
         try {
+            options.imageStatusReporter?.(`Creating Docker container '${options.names.runtime}' from image '${options.runtimeImage}'.`);
             await this.docker.createContainer(buildRuntimeContainerOptions(options));
         }
         catch (error) {

package/dist/state/daemon_state.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNNER_DAEMON_STATE_ID = void 0;
+exports.readCurrentDaemonState = readCurrentDaemonState;
+exports.claimCurrentDaemonState = claimCurrentDaemonState;
+exports.clearCurrentDaemonState = clearCurrentDaemonState;
+const drizzle_orm_1 = require("drizzle-orm");
+const db_js_1 = require("./db.js");
+const schema_js_1 = require("./schema.js");
+const process_js_1 = require("../utils/process.js");
+exports.RUNNER_DAEMON_STATE_ID = "runner";
+async function readCurrentDaemonState(stateDbPath) {
+    const { db, client } = await (0, db_js_1.initDb)(stateDbPath);
+    try {
+        const existing = await db.select().from(schema_js_1.daemonState).where((0, drizzle_orm_1.eq)(schema_js_1.daemonState.id, exports.RUNNER_DAEMON_STATE_ID)).all();
+        const row = existing[0];
+        if (!row) {
+            return null;
+        }
+        return {
+            id: row.id,
+            pid: row.pid ?? null,
+            logPath: row.logPath ?? null,
+            startedAt: row.startedAt,
+            updatedAt: row.updatedAt,
+        };
+    }
+    finally {
+        client.close();
+    }
+}
+async function claimCurrentDaemonState(stateDbPath, pid, logPath) {
+    const now = new Date().toISOString();
+    const { client } = await (0, db_js_1.initDb)(stateDbPath);
+    try {
+        await client.execute("BEGIN IMMEDIATE");
+        try {
+            const existing = await client.execute({
+                sql: "SELECT pid FROM daemon_state WHERE id = ?",
+                args: [exports.RUNNER_DAEMON_STATE_ID],
+            });
+            const row = existing.rows[0];
+            const currentPid = typeof row?.pid === "number" ? row.pid : row?.pid == null ? null : Number(row.pid);
+            if (currentPid && currentPid !== pid && (0, process_js_1.isProcessRunning)(currentPid)) {
+                throw new Error(`Another companyhelm daemon is already running with pid ${currentPid}.`);
+            }
+            await client.execute({
+                sql: "INSERT INTO daemon_state (id, pid, log_path, started_at, updated_at) VALUES (?, ?, ?, ?, ?) " +
+                    "ON CONFLICT(id) DO UPDATE SET pid = excluded.pid, log_path = excluded.log_path, started_at = excluded.started_at, updated_at = excluded.updated_at",
+                args: [exports.RUNNER_DAEMON_STATE_ID, pid, logPath, now, now],
+            });
+            await client.execute("COMMIT");
+        }
+        catch (error) {
+            await client.execute("ROLLBACK");
+            throw error;
+        }
+    }
+    finally {
+        client.close();
+    }
+}
+async function clearCurrentDaemonState(stateDbPath, pid) {
+    const now = new Date().toISOString();
+    const { db, client } = await (0, db_js_1.initDb)(stateDbPath);
+    try {
+        const existing = await db.select().from(schema_js_1.daemonState).where((0, drizzle_orm_1.eq)(schema_js_1.daemonState.id, exports.RUNNER_DAEMON_STATE_ID)).all();
+        const current = existing[0];
+        if (!current || current.pid !== pid) {
+            return;
+        }
+        await db
+            .update(schema_js_1.daemonState)
+            .set({
+            pid: null,
+            updatedAt: now,
+        })
+            .where((0, drizzle_orm_1.eq)(schema_js_1.daemonState.id, exports.RUNNER_DAEMON_STATE_ID));
+    }
+    finally {
+        client.close();
+    }
+}

package/dist/state/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.threadUserMessageRequestStore = exports.threads = exports.llmModels = exports.agentSdks = void 0;
+exports.daemonState = exports.threadUserMessageRequestStore = exports.threads = exports.llmModels = exports.agentSdks = void 0;
 const sqlite_core_1 = require("drizzle-orm/sqlite-core");
 // ── agent_sdks ──────────────────────────────────────────────────────────────
 exports.agentSdks = (0, sqlite_core_1.sqliteTable)("agent_sdks", {
@@ -49,3 +49,11 @@ exports.threadUserMessageRequestStore = (0, sqlite_core_1.sqliteTable)("thread_u
     requestId: (0, sqlite_core_1.text)("request_id").notNull(),
     sdkItemId: (0, sqlite_core_1.text)("sdk_item_id"),
 });
+// -- daemon_state ------------------------------------------------------------
+exports.daemonState = (0, sqlite_core_1.sqliteTable)("daemon_state", {
+    id: (0, sqlite_core_1.text)("id").primaryKey(),
+    pid: (0, sqlite_core_1.integer)("pid"),
+    logPath: (0, sqlite_core_1.text)("log_path"),
+    startedAt: (0, sqlite_core_1.text)("started_at").notNull(),
+    updatedAt: (0, sqlite_core_1.text)("updated_at").notNull(),
+});

package/dist/templates/app_server_bootstrap.sh.j2

@@ -0,0 +1,46 @@
+set -euo pipefail
+
+AGENT_USER={{ agent_user }}
+AGENT_HOME={{ agent_home }}
+AGENT_UID={{ agent_uid }}
+AGENT_GID={{ agent_gid }}
+CODEX_AUTH_PATH={{ codex_auth_path }}
+APP_SERVER_COMMAND={{ app_server_command }}
+
+AGENT_GROUP="$AGENT_USER"
+if getent group "$AGENT_GID" >/dev/null 2>&1; then
+  AGENT_GROUP="$(getent group "$AGENT_GID" | cut -d: -f1)"
+elif getent group "$AGENT_USER" >/dev/null 2>&1; then
+  groupmod -g "$AGENT_GID" "$AGENT_USER"
+  AGENT_GROUP="$AGENT_USER"
+else
+  groupadd -g "$AGENT_GID" "$AGENT_USER"
+  AGENT_GROUP="$AGENT_USER"
+fi
+
+if id -u "$AGENT_USER" >/dev/null 2>&1; then
+  usermod -u "$AGENT_UID" -g "$AGENT_GROUP" -d "$AGENT_HOME" "$AGENT_USER" || true
+else
+  useradd -m -d "$AGENT_HOME" -u "$AGENT_UID" -g "$AGENT_GROUP" -s /bin/bash "$AGENT_USER"
+fi
+
+SUDOERS_FILE="/etc/sudoers.d/90-companyhelm-agent"
+if command -v sudo >/dev/null 2>&1; then
+  install -d -m 0750 /etc/sudoers.d
+  printf '%s\n' "$AGENT_USER ALL=(ALL) NOPASSWD:ALL" > "$SUDOERS_FILE"
+  chmod 0440 "$SUDOERS_FILE"
+  if command -v visudo >/dev/null 2>&1; then
+    visudo -cf "$SUDOERS_FILE" >/dev/null
+  fi
+fi
+
+mkdir -p "$AGENT_HOME"
+chown "$AGENT_UID:$AGENT_GID" "$AGENT_HOME" || true
+
+if [ -n "${CODEX_AUTH_PATH:-}" ]; then
+  mkdir -p "$(dirname "$CODEX_AUTH_PATH")"
+  chown -R "$AGENT_UID:$AGENT_GID" "$(dirname "$CODEX_AUTH_PATH")" || true
+fi
+
+export HOME="$AGENT_HOME"
+exec sudo -n -E -H -u "$AGENT_USER" bash -lc "$APP_SERVER_COMMAND"

package/dist/templates/runtime_agents.md.j2

@@ -0,0 +1,50 @@
+# Agent Instructions
+
+## Workspace Structure
+
+- You are running in a thread-specific container and workspace
+- This workspace is not initialized as a Git repository by default. Repositories should live in a subdirectory of the workspace.
+
+## Docker
+
+Docker is available, the docker host runs in a separate container. The network is shared with container.
+- only the `/workspace` is shared with the docker host
+- `{{home_directory}}/.codex/auth.json` is also shared with the docker host
+- Nested DinD is not supported in this environment because the outer runtime already uses rootless DinD.
+- If you need to use Docker in Docker you can mount the docker socket in the container and use this environment DinD to run containers within containers.
+
+## GitHub Installations
+
+- Synced GitHub installation credentials are written to `/workspace/.companyhelm/installations.json`.
+- Use `list-installations` to inspect installation IDs, repository scopes, tokens, and expiration timestamps.
+- Use `gh-use-installation <installation-id>` to configure `gh` authentication for a specific installation.
+
+```bash
+# Inspect synced installation credentials
+list-installations
+
+# Configure gh to use installation 112331765
+gh-use-installation 112331765
+
+# Verify gh is authenticated for github.com
+gh auth status --hostname github.com
+```
+
+## Available CLI Tools
+
+- `list-installations`: list synced GitHub installations with repositories, access tokens, and expirations.
+- `gh-use-installation <installation-id>`: configure `gh` authentication for a selected GitHub installation token.
+- `aws`: AWS CLI is pre-installed and available in `PATH`.
+- For scripted PR creation/updates, always use `gh pr create --body-file <path>` and `gh pr edit --body-file <path>` instead of inline `--body` to avoid shell interpolation of markdown backticks.
+- DO NOT INSTALL PLAYWRIGHT IN THE RUNTIME IMAGE. Playwright CLI is already installed and available for browser automation tasks with Chromium pre-installed: `playwright open --browser=chromium ...`
+
+## CompanyHelm Agent CLI
+
+- `companyhelm-agent` is pre-installed in the runtime image.
+- Thread bootstrap writes `{{home_directory}}/.config/companyhelm-agent-cli/config.json` with:
+  - `agent_api_url`: localhost targets are rewritten to `host.docker.internal` (for example `http://host.docker.internal:<port>`) for Docker-to-host access.
+  - `token`: sourced from the thread secret.
+- Example commands:
+  - `companyhelm-agent task get --task-id <id>`
+  - `companyhelm-agent task dependencies --task-id <id>`
+  - `companyhelm-agent task update-status --task-id <id> --status <draft|pending|in_progress|completed>`

package/dist/templates/runtime_bashrc.j2

@@ -0,0 +1,19 @@
+# CompanyHelm runtime shell initialization.
+# This file is generated by companyhelm-cli when a thread runtime starts.
+
+if [ -z "${NVM_DIR:-}" ] || [ ! -s "$NVM_DIR/nvm.sh" ]; then
+  for candidate in "/usr/local/nvm" "$HOME/.nvm" "/opt/nvm" "/root/.nvm"; do
+    if [ -s "$candidate/nvm.sh" ]; then
+      export NVM_DIR="$candidate"
+      break
+    fi
+  done
+fi
+
+if [ -n "${NVM_DIR:-}" ] && [ -s "$NVM_DIR/nvm.sh" ]; then
+  . "$NVM_DIR/nvm.sh"
+  nvm use --silent default >/dev/null 2>&1 || true
+  if [ -s "$NVM_DIR/bash_completion" ]; then
+    . "$NVM_DIR/bash_completion"
+  fi
+fi