@companyhelm/cli 0.0.2

package/dist/state/service/host.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHostInfo = getHostInfo;
+const node_os_1 = require("node:os");
+const node_fs_1 = require("node:fs");
+const path_js_1 = require("../utils/path.js");
+function getHostInfo(codexAuthPath) {
+    const info = (0, node_os_1.userInfo)();
+    return {
+        uid: info.uid,
+        gid: info.gid,
+        home: (0, node_os_1.homedir)(),
+        codexAuthExists: (0, node_fs_1.existsSync)((0, path_js_1.expandHome)(codexAuthPath)),
+    };
+}

package/dist/state/service/runtime_shell.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildNvmCodexBootstrapScript = buildNvmCodexBootstrapScript;
+exports.buildCodexAppServerCommand = buildCodexAppServerCommand;
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+const CODEX_APP_SERVER_STDIN_LISTEN_FLAG = "--listen stdio://";
+const CODEX_YOLO_FLAG = "--dangerously-bypass-approvals-and-sandbox";
+function buildNvmCodexBootstrapScript(homeDirectory) {
+    const lines = [
+        "set -euo pipefail",
+    ];
+    if (homeDirectory) {
+        lines.push(`export HOME=${shellQuote(homeDirectory)}`);
+    }
+    lines.push('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 [ -z "${NVM_DIR:-}" ] || [ ! -s "$NVM_DIR/nvm.sh" ]; then', '  echo "nvm is not configured: unable to locate nvm.sh." >&2', "  exit 1", "fi", '. "$NVM_DIR/nvm.sh"', 'nvm use --silent default >/dev/null 2>&1 || true', 'if ! command -v codex >/dev/null 2>&1; then', '  echo "codex command is not available after sourcing nvm." >&2', "  exit 1", "fi");
+    return lines.join("\n");
+}
+function buildCodexAppServerCommand(homeDirectory) {
+    const bootstrap = buildNvmCodexBootstrapScript(homeDirectory);
+    return `${bootstrap}\ncodex ${CODEX_YOLO_FLAG} app-server ${CODEX_APP_SERVER_STDIN_LISTEN_FLAG}`;
+}

package/dist/state/service/sdk/refresh_models.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshSdkModels = refreshSdkModels;
+const drizzle_orm_1 = require("drizzle-orm");
+const config_js_1 = require("../../config.js");
+const db_js_1 = require("../../state/db.js");
+const schema_js_1 = require("../../state/schema.js");
+const app_server_js_1 = require("../app_server.js");
+const app_server_container_js_1 = require("../docker/app_server_container.js");
+async function fetchCodexModelsFromAppServer(clientName, logger) {
+    const transport = new app_server_container_js_1.AppServerContainerService();
+    const appServer = new app_server_js_1.AppServerService(transport, clientName, logger);
+    await appServer.start();
+    const models = [];
+    let nextCursor = null;
+    try {
+        while (true) {
+            const result = await appServer.listModels(nextCursor, 100);
+            models.push(...result.data);
+            if (!result.nextCursor) {
+                break;
+            }
+            nextCursor = result.nextCursor;
+        }
+    }
+    finally {
+        await appServer.stop();
+    }
+    return models;
+}
+async function refreshCodexModels(cfg, logger) {
+    const models = await fetchCodexModelsFromAppServer(cfg.codex.app_server_client_name, logger);
+    const { db, client } = await (0, db_js_1.initDb)(cfg.state_db_path);
+    try {
+        await db.delete(schema_js_1.llmModels).where((0, drizzle_orm_1.eq)(schema_js_1.llmModels.sdkName, "codex"));
+        if (models.length > 0) {
+            await db.insert(schema_js_1.llmModels).values(models.map((model) => ({
+                name: model.model,
+                sdkName: "codex",
+                reasoningLevels: model.supportedReasoningEfforts.map((effort) => effort.reasoningEffort),
+            })));
+        }
+    }
+    finally {
+        client.close();
+    }
+    return models.length;
+}
+async function refreshSdkModels(options) {
+    const cfg = config_js_1.config.parse({});
+    const { db, client } = await (0, db_js_1.initDb)(cfg.state_db_path);
+    let selectedSdks = [];
+    try {
+        if (options?.sdk) {
+            const configured = await db.select().from(schema_js_1.agentSdks).where((0, drizzle_orm_1.eq)(schema_js_1.agentSdks.name, options.sdk)).get();
+            if (!configured) {
+                throw new Error(`SDK '${options.sdk}' is not configured.`);
+            }
+            selectedSdks = [configured];
+        }
+        else {
+            selectedSdks = await db.select().from(schema_js_1.agentSdks).all();
+        }
+    }
+    finally {
+        client.close();
+    }
+    if (selectedSdks.length === 0) {
+        throw new Error("No SDKs are configured.");
+    }
+    const results = [];
+    for (const sdk of selectedSdks) {
+        if (!sdk.authentication || sdk.authentication === "unauthenticated") {
+            throw new Error(`SDK '${sdk.name}' is missing authentication.`);
+        }
+        if (sdk.name !== "codex") {
+            throw new Error(`SDK '${sdk.name}' is not supported by model refresh yet.`);
+        }
+        const modelCount = await refreshCodexModels(cfg, options?.logger);
+        results.push({ sdk: sdk.name, modelCount });
+    }
+    return results;
+}

package/dist/state/service/thread_lifecycle.js

@@ -0,0 +1,327 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThreadContainerService = void 0;
+exports.buildThreadContainerNames = buildThreadContainerNames;
+exports.resolveThreadsRootDirectory = resolveThreadsRootDirectory;
+exports.resolveThreadDirectory = resolveThreadDirectory;
+exports.buildSharedThreadMounts = buildSharedThreadMounts;
+exports.buildDindContainerOptions = buildDindContainerOptions;
+exports.buildRuntimeContainerOptions = buildRuntimeContainerOptions;
+const dockerode_1 = __importDefault(require("dockerode"));
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const path_js_1 = require("../utils/path.js");
+const runtime_shell_js_1 = require("./runtime_shell.js");
+const CONTAINER_START_TIMEOUT_MS = 30000;
+const CONTAINER_START_POLL_MS = 500;
+function resolveContainerPath(path, containerHome) {
+    if (path === "~") {
+        return containerHome;
+    }
+    if (path.startsWith("~/")) {
+        return `${containerHome}${path.slice(1)}`;
+    }
+    return path;
+}
+function buildThreadContainerNames(threadId) {
+    return {
+        dind: `companyhelm-dind-thread-${threadId}`,
+        runtime: `companyhelm-runtime-thread-${threadId}`,
+    };
+}
+function resolveThreadsRootDirectory(configDirectory, threadsDirectory) {
+    const expandedThreadsDirectory = (0, path_js_1.expandHome)(threadsDirectory);
+    if ((0, node_path_1.isAbsolute)(expandedThreadsDirectory)) {
+        return expandedThreadsDirectory;
+    }
+    return (0, node_path_1.join)((0, path_js_1.expandHome)(configDirectory), expandedThreadsDirectory);
+}
+function resolveThreadDirectory(configDirectory, threadsDirectory, agentId, threadId) {
+    return (0, node_path_1.join)(resolveThreadsRootDirectory(configDirectory, threadsDirectory), `agent-${agentId}`, `thread-${threadId}`);
+}
+function buildSharedThreadMounts(options) {
+    const mounts = [
+        {
+            Type: "bind",
+            Source: options.threadDirectory,
+            Target: "/workspace",
+        },
+    ];
+    if (options.codexAuthMode === "dedicated") {
+        mounts.push({
+            Type: "bind",
+            Source: (0, node_path_1.join)((0, path_js_1.expandHome)(options.configDirectory), options.codexAuthFilePath),
+            Target: resolveContainerPath(options.codexAuthPath, options.containerHomeDirectory),
+        });
+        return mounts;
+    }
+    const hostAuthPath = (0, path_js_1.expandHome)(options.codexAuthPath);
+    mounts.push({
+        Type: "bind",
+        Source: hostAuthPath,
+        Target: hostAuthPath,
+    });
+    return mounts;
+}
+function buildCommonContainerEnv(user) {
+    return [
+        `HOME=${user.agentHomeDirectory}`,
+        `USER=${user.agentUser}`,
+    ];
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function buildRuntimeIdentityProvisionScript(user) {
+    return [
+        "set -euo pipefail",
+        `AGENT_USER=${shellQuote(user.agentUser)}`,
+        `AGENT_HOME=${shellQuote(user.agentHomeDirectory)}`,
+        `AGENT_UID=${shellQuote(String(user.uid))}`,
+        `AGENT_GID=${shellQuote(String(user.gid))}`,
+        "",
+        'install -d -m 0755 -o "$AGENT_UID" -g "$AGENT_GID" "$AGENT_HOME"',
+        "",
+        '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",
+        "",
+        'install -d -m 0755 -o "$AGENT_UID" -g "$AGENT_GID" "$AGENT_HOME/.codex"',
+        'if [ -e "$AGENT_HOME/.codex/auth.json" ]; then',
+        '  chown "$AGENT_UID:$AGENT_GID" "$AGENT_HOME/.codex/auth.json" || true',
+        "fi",
+        'chown -R "$AGENT_UID:$AGENT_GID" "$AGENT_HOME" || true',
+    ].join("\n");
+}
+function buildRuntimeToolingValidationScript(user) {
+    return (0, runtime_shell_js_1.buildNvmCodexBootstrapScript)(user.agentHomeDirectory);
+}
+function buildDindContainerOptions(options) {
+    return {
+        name: options.names.dind,
+        Image: options.dindImage,
+        WorkingDir: "/workspace",
+        Env: [
+            "DOCKER_TLS_CERTDIR=",
+        ],
+        HostConfig: {
+            Privileged: true,
+            Mounts: options.mounts,
+        },
+    };
+}
+function buildRuntimeContainerOptions(options) {
+    return {
+        name: options.names.runtime,
+        Image: options.runtimeImage,
+        User: `${options.user.uid}:${options.user.gid}`,
+        WorkingDir: "/workspace",
+        Env: [
+            ...buildCommonContainerEnv(options.user),
+            "DOCKER_HOST=tcp://localhost:2375",
+        ],
+        Cmd: ["sleep", "infinity"],
+        HostConfig: {
+            NetworkMode: `container:${options.names.dind}`,
+            Mounts: options.mounts,
+        },
+    };
+}
+function isContainerNotFound(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    const statusCode = "statusCode" in error ? error.statusCode : undefined;
+    if (statusCode === 404) {
+        return true;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return /No such container/i.test(message);
+}
+function isContainerAlreadyStarted(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    const statusCode = "statusCode" in error ? error.statusCode : undefined;
+    if (statusCode === 304) {
+        return true;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return /already started/i.test(message);
+}
+function isContainerNotRunning(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    const statusCode = "statusCode" in error ? error.statusCode : undefined;
+    if (statusCode === 304) {
+        return true;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return /is not running/i.test(message);
+}
+function isImageNotFound(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    const statusCode = "statusCode" in error ? error.statusCode : undefined;
+    if (statusCode === 404) {
+        return true;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return /No such image/i.test(message);
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+class ThreadContainerService {
+    constructor(docker, runCommand = node_child_process_1.spawnSync) {
+        this.docker = docker ?? new dockerode_1.default();
+        this.runCommand = runCommand;
+    }
+    runDockerExecScript(args, contextMessage) {
+        const result = this.runCommand("docker", args, {
+            encoding: "utf8",
+        });
+        if (result.status === 0 && !result.error) {
+            return;
+        }
+        const detail = [result.error?.message, result.stderr, result.stdout]
+            .filter((value) => typeof value === "string" && value.trim().length > 0)
+            .map((value) => value.trim())
+            .join(" | ");
+        const status = result.status === null ? "unknown" : String(result.status);
+        throw new Error(`${contextMessage} (exit ${status})${detail ? `: ${detail}` : "."}`);
+    }
+    async pullImage(image) {
+        await new Promise((resolve, reject) => {
+            this.docker.pull(image, (error, stream) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                if (!stream) {
+                    reject(new Error(`Docker returned an empty stream while pulling image '${image}'.`));
+                    return;
+                }
+                const modem = this.docker.modem;
+                if (!modem?.followProgress) {
+                    resolve();
+                    return;
+                }
+                modem.followProgress(stream, (pullError) => {
+                    if (pullError) {
+                        reject(pullError);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        });
+    }
+    async ensureImageAvailable(image) {
+        try {
+            await this.docker.getImage(image).inspect();
+            return;
+        }
+        catch (error) {
+            if (!isImageNotFound(error)) {
+                throw error;
+            }
+        }
+        await this.pullImage(image);
+    }
+    async createThreadContainers(options) {
+        await this.ensureImageAvailable(options.dindImage);
+        if (options.runtimeImage !== options.dindImage) {
+            await this.ensureImageAvailable(options.runtimeImage);
+        }
+        await this.docker.createContainer(buildDindContainerOptions(options));
+        try {
+            await this.docker.createContainer(buildRuntimeContainerOptions(options));
+        }
+        catch (error) {
+            await this.forceRemoveContainer(options.names.dind);
+            throw new Error(toErrorMessage(error));
+        }
+    }
+    async startContainer(name) {
+        const container = this.docker.getContainer(name);
+        try {
+            await container.start();
+        }
+        catch (error) {
+            if (isContainerAlreadyStarted(error)) {
+                return;
+            }
+            throw error;
+        }
+    }
+    async waitForContainerRunning(name, timeoutMs = CONTAINER_START_TIMEOUT_MS) {
+        const container = this.docker.getContainer(name);
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const details = await container.inspect();
+            const state = details.State;
+            if (state?.Running) {
+                return;
+            }
+            if (state?.Status === "exited" || state?.Status === "dead") {
+                throw new Error(`Container '${name}' is not running (status=${state.Status}, exitCode=${state.ExitCode ?? "unknown"}).`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, CONTAINER_START_POLL_MS));
+        }
+        throw new Error(`Container '${name}' did not reach running state within ${timeoutMs}ms.`);
+    }
+    async ensureContainerRunning(name, timeoutMs = CONTAINER_START_TIMEOUT_MS) {
+        await this.startContainer(name);
+        await this.waitForContainerRunning(name, timeoutMs);
+    }
+    async ensureRuntimeContainerIdentity(name, user) {
+        const script = buildRuntimeIdentityProvisionScript(user);
+        this.runDockerExecScript(["exec", "-u", "0", name, "bash", "-lc", script], `Failed to provision runtime user '${user.agentUser}' in container '${name}'`);
+    }
+    async ensureRuntimeContainerTooling(name, user) {
+        const script = buildRuntimeToolingValidationScript(user);
+        this.runDockerExecScript(["exec", "-u", user.agentUser, name, "bash", "-lc", script], `Failed to validate nvm/codex in runtime container '${name}'`);
+    }
+    async stopContainer(name) {
+        try {
+            await this.docker.getContainer(name).stop({ t: 10 });
+        }
+        catch (error) {
+            if (isContainerNotFound(error) || isContainerNotRunning(error)) {
+                return;
+            }
+            throw error;
+        }
+    }
+    async forceRemoveContainer(name) {
+        try {
+            await this.docker.getContainer(name).remove({ force: true });
+        }
+        catch (error) {
+            if (isContainerNotFound(error)) {
+                return;
+            }
+            throw error;
+        }
+    }
+}
+exports.ThreadContainerService = ThreadContainerService;

package/dist/state/service/thread_runtime.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureThreadRuntimeReady = ensureThreadRuntimeReady;
+const thread_lifecycle_js_1 = require("./thread_lifecycle.js");
+async function ensureThreadRuntimeReady(options) {
+    const containerService = options.containerService ?? new thread_lifecycle_js_1.ThreadContainerService();
+    await containerService.ensureContainerRunning(options.dindContainer);
+    await containerService.ensureContainerRunning(options.runtimeContainer);
+    await containerService.ensureRuntimeContainerIdentity(options.runtimeContainer, options.user);
+    await containerService.ensureRuntimeContainerTooling(options.runtimeContainer, options.user);
+}

package/dist/state/service/thread_turn_state.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadThreadMessageExecutionState = loadThreadMessageExecutionState;
+exports.updateThreadTurnState = updateThreadTurnState;
+const drizzle_orm_1 = require("drizzle-orm");
+const db_js_1 = require("../state/db.js");
+const schema_js_1 = require("../state/schema.js");
+async function loadThreadMessageExecutionState(stateDbPath, agentId, threadId) {
+    const { db, client } = await (0, db_js_1.initDb)(stateDbPath);
+    try {
+        return await db
+            .select({
+            id: schema_js_1.threads.id,
+            agentId: schema_js_1.threads.agentId,
+            sdkThreadId: schema_js_1.threads.sdkThreadId,
+            model: schema_js_1.threads.model,
+            reasoningLevel: schema_js_1.threads.reasoningLevel,
+            currentSdkTurnId: schema_js_1.threads.currentSdkTurnId,
+            isCurrentTurnRunning: schema_js_1.threads.isCurrentTurnRunning,
+            runtimeContainer: schema_js_1.threads.runtimeContainer,
+            dindContainer: schema_js_1.threads.dindContainer,
+            homeDirectory: schema_js_1.threads.homeDirectory,
+            uid: schema_js_1.threads.uid,
+            gid: schema_js_1.threads.gid,
+        })
+            .from(schema_js_1.threads)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_js_1.threads.id, threadId), (0, drizzle_orm_1.eq)(schema_js_1.threads.agentId, agentId)))
+            .get();
+    }
+    finally {
+        client.close();
+    }
+}
+async function updateThreadTurnState(stateDbPath, agentId, threadId, update) {
+    const { db, client } = await (0, db_js_1.initDb)(stateDbPath);
+    try {
+        await db
+            .update(schema_js_1.threads)
+            .set(update)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_js_1.threads.id, threadId), (0, drizzle_orm_1.eq)(schema_js_1.threads.agentId, agentId)));
+    }
+    finally {
+        client.close();
+    }
+}

package/dist/state/service/workspace_agents.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENTS_MD_CLI_TOOLS_SECTION = exports.AGENTS_MD_WORKSPACE_SECTION = void 0;
+exports.renderRuntimeAgentsMd = renderRuntimeAgentsMd;
+exports.ensureWorkspaceAgentsMd = ensureWorkspaceAgentsMd;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.AGENTS_MD_WORKSPACE_SECTION = `## Workspace Structure
+
+- \`/workspace\` is a thread-specific bind mount from the host.
+- Host path layout: \`<config_directory>/<workspaces_directory>/agent-<agent-id>/thread-<thread-id>\`.
+- This workspace is not initialized as a Git repository by default.
+- Clone a repository into \`/workspace\` or run \`git init\` manually when version history is required.
+`;
+exports.AGENTS_MD_CLI_TOOLS_SECTION = `## Available CLI Tools
+
+- There are currently no additional CompanyHelm helper CLI tools installed in this runtime.
+`;
+const AGENTS_MD_GITHUB_SECTION_MARKER = "## GitHub Installations";
+const RUNTIME_AGENTS_TEMPLATE_PATH = "templates/runtime_agents.md.j2";
+const DEFAULT_HOME_DIRECTORY = "/home/agent";
+function buildGithubInstallationsSection(installations) {
+    const lines = [AGENTS_MD_GITHUB_SECTION_MARKER, ""];
+    if (installations.length === 0) {
+        lines.push("- No linked GitHub installations were provided for this thread.");
+        return lines.join("\n");
+    }
+    for (const installation of installations) {
+        lines.push(`### Installation ${installation.installationId}`);
+        lines.push(`- Access token: \`${installation.accessToken}\``);
+        lines.push(`- Access token expires (unix ms): \`${installation.accessTokenExpiresUnixTimeMs}\``);
+        if (installation.repositories.length === 0) {
+            lines.push("- Repositories: none reported.");
+        }
+        else {
+            lines.push("- Repositories:");
+            for (const repository of installation.repositories) {
+                lines.push(`  - \`${repository}\``);
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}
+function renderJinjaTemplate(template, context) {
+    return template.replace(/{{\s*([a-zA-Z0-9_]+)\s*}}/g, (_match, key) => {
+        const value = context[key];
+        if (value === undefined) {
+            throw new Error(`Missing template value for key '${key}'`);
+        }
+        return value;
+    });
+}
+function resolveTemplatePath() {
+    const distRelativePath = (0, node_path_1.join)(__dirname, "..", RUNTIME_AGENTS_TEMPLATE_PATH);
+    if ((0, node_fs_1.existsSync)(distRelativePath)) {
+        return distRelativePath;
+    }
+    const sourceRelativePath = (0, node_path_1.join)(__dirname, "..", "..", "src", RUNTIME_AGENTS_TEMPLATE_PATH);
+    if ((0, node_fs_1.existsSync)(sourceRelativePath)) {
+        return sourceRelativePath;
+    }
+    throw new Error(`Runtime AGENTS template was not found at ${distRelativePath} or ${sourceRelativePath}`);
+}
+function renderRuntimeAgentsMd(homeDirectory = DEFAULT_HOME_DIRECTORY, githubInstallations = []) {
+    const githubInstallationsSection = buildGithubInstallationsSection(githubInstallations);
+    const defaultTemplate = `# Agent Instructions
+
+${exports.AGENTS_MD_WORKSPACE_SECTION}
+${githubInstallationsSection}
+
+${exports.AGENTS_MD_CLI_TOOLS_SECTION}`;
+    try {
+        const template = (0, node_fs_1.readFileSync)(resolveTemplatePath(), "utf8");
+        return renderJinjaTemplate(template, {
+            home_directory: homeDirectory,
+            github_installations_section: githubInstallationsSection,
+        }).trim() + "\n";
+    }
+    catch {
+        return defaultTemplate.trim() + "\n";
+    }
+}
+function ensureWorkspaceAgentsMd(workspaceDirectory, homeDirectory = DEFAULT_HOME_DIRECTORY, githubInstallations = []) {
+    (0, node_fs_1.mkdirSync)(workspaceDirectory, { recursive: true });
+    const agentsPath = (0, node_path_1.join)(workspaceDirectory, "AGENTS.md");
+    const githubInstallationsSection = buildGithubInstallationsSection(githubInstallations);
+    const sections = [
+        { marker: "## Workspace Structure", content: exports.AGENTS_MD_WORKSPACE_SECTION },
+        { marker: AGENTS_MD_GITHUB_SECTION_MARKER, content: githubInstallationsSection },
+        { marker: "## Available CLI Tools", content: exports.AGENTS_MD_CLI_TOOLS_SECTION },
+    ];
+    let existing = "";
+    try {
+        existing = (0, node_fs_1.readFileSync)(agentsPath, "utf8");
+    }
+    catch {
+        existing = "";
+    }
+    const pendingSections = sections
+        .filter((section) => !existing.includes(section.marker))
+        .map((section) => section.content);
+    if (pendingSections.length === 0) {
+        return;
+    }
+    const updated = existing.trim()
+        ? `${existing.trimEnd()}\n\n${pendingSections.join("\n\n")}`
+        : renderRuntimeAgentsMd(homeDirectory, githubInstallations);
+    try {
+        (0, node_fs_1.writeFileSync)(agentsPath, updated, "utf8");
+    }
+    catch {
+        // Best-effort workspace instruction file.
+    }
+}