@opentag/runner 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @opentag/runner
+
+Executor contracts and built-in runner adapters for OpenTag.
+
+Use this package when building a local daemon, hosted runner, or custom executor that consumes OpenTag runs.
+
+## Install
+
+```bash
+pnpm add @opentag/runner
+```
+
+## Exports
+
+- `ExecutorAdapter`: interface every executor implements.
+- `createEchoExecutor`: smoke-test executor that echoes the normalized command.
+- `createCodexExecutor`: executor that runs `codex exec` in a mapped local checkout.
+- Git helpers such as `createRunBranch`, `changedFiles`, and `branchNameForRun`.
+- Command helpers such as `nodeCommandRunner` and `assertCommandSucceeded`.
+
+## Example
+
+```ts
+import type { ExecutorAdapter } from "@opentag/runner";
+
+export const executor: ExecutorAdapter = {
+  id: "my-agent",
+  displayName: "My Agent",
+  async canRun() {
+    return { ready: true };
+  },
+  async run(input, sink) {
+    await sink.emit({
+      type: "executor.started",
+      message: `Running ${input.command.rawText}`,
+      at: new Date().toISOString()
+    });
+
+    return {
+      conclusion: "success",
+      summary: "Handled by my-agent"
+    };
+  },
+  async cancel() {
+    return;
+  }
+};
+```
+
+## Safety Notes
+
+`createCodexExecutor` refuses to run when the target checkout has uncommitted changes. It creates an isolated `opentag/<runId>` branch before running Codex.
+
+## Stability
+
+`ExecutorAdapter` is public API. Add optional fields rather than changing required method signatures.

package/dist/codex.d.ts

@@ -0,0 +1,9 @@
+import { type CommandRunner } from "./command.js";
+import type { ExecutorAdapter } from "./executor.js";
+export type CodexExecutorOptions = {
+    runner?: CommandRunner;
+    codexCommand?: string;
+    model?: string;
+};
+export declare function createCodexExecutor(options?: CodexExecutorOptions): ExecutorAdapter;
+//# sourceMappingURL=codex.d.ts.map

package/dist/codex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../src/codex.ts"],"names":[],"mappings":"AACA,OAAO,EAA6C,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA0BF,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,eAAe,CA2FvF"}

package/dist/command.d.ts

@@ -0,0 +1,14 @@
+export type CommandResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type CommandRunner = {
+    run(command: string, args: string[], options?: {
+        cwd?: string;
+        input?: string;
+    }): Promise<CommandResult>;
+};
+export declare const nodeCommandRunner: CommandRunner;
+export declare function assertCommandSucceeded(result: CommandResult, label: string): Promise<void>;
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC1G,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,aA2B/B,CAAC;AAEF,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhG"}

package/dist/echo.d.ts

@@ -0,0 +1,3 @@
+import type { ExecutorAdapter } from "./executor.js";
+export declare function createEchoExecutor(): ExecutorAdapter;
+//# sourceMappingURL=echo.d.ts.map

package/dist/echo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"echo.d.ts","sourceRoot":"","sources":["../src/echo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAMrD,wBAAgB,kBAAkB,IAAI,eAAe,CAkCpD"}

package/dist/executor.d.ts

@@ -0,0 +1,27 @@
+import type { ContextPointer, OpenTagCommand, OpenTagRunResult } from "@opentag/core";
+export type ExecutorEvent = {
+    type: "executor.started" | "executor.progress" | "executor.completed" | "executor.failed";
+    message: string;
+    at: string;
+};
+export type ExecutorEventSink = {
+    emit(event: ExecutorEvent): Promise<void>;
+};
+export type ExecutorRunInput = {
+    runId: string;
+    workspacePath: string;
+    command: OpenTagCommand;
+    context: ContextPointer[];
+};
+export type ExecutorReadiness = {
+    ready: boolean;
+    reason?: string;
+};
+export type ExecutorAdapter = {
+    id: string;
+    displayName: string;
+    canRun(input: ExecutorRunInput): Promise<ExecutorReadiness>;
+    run(input: ExecutorRunInput, sink: ExecutorEventSink): Promise<OpenTagRunResult>;
+    cancel(runId: string): Promise<void>;
+};
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,kBAAkB,GAAG,mBAAmB,GAAG,oBAAoB,GAAG,iBAAiB,CAAC;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC5D,GAAG,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACjF,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC,CAAC"}

package/dist/git.d.ts

@@ -0,0 +1,29 @@
+import type { CommandRunner } from "./command.js";
+export type GitStatusEntry = {
+    status: string;
+    path: string;
+};
+export declare function branchNameForRun(runId: string): string;
+export declare function parseStatusEntries(statusOutput: string): GitStatusEntry[];
+export declare function isInternalArtifactPath(path: string): boolean;
+export declare function parseChangedFiles(statusOutput: string): string[];
+export declare function createRunBranch(input: {
+    runner: CommandRunner;
+    workspacePath: string;
+    branchName: string;
+}): Promise<void>;
+export declare function changedFiles(input: {
+    runner: CommandRunner;
+    workspacePath: string;
+}): Promise<string[]>;
+export declare function cleanupInternalArtifacts(input: {
+    runner: CommandRunner;
+    workspacePath: string;
+}): Promise<string[]>;
+export declare function pushBranch(input: {
+    runner: CommandRunner;
+    workspacePath: string;
+    remote: string;
+    branchName: string;
+}): Promise<void>;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAIF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,EAAE,CAUzE;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAIhE;AAED,wBAAsB,eAAe,CAAC,KAAK,EAAE;IAC3C,MAAM,EAAE,aAAa,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhB;AAED,wBAAsB,YAAY,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAI7G;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBzH;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE;IACtC,MAAM,EAAE,aAAa,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhB"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./codex.js";
+export * from "./command.js";
+export * from "./echo.js";
+export * from "./executor.js";
+export * from "./git.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,241 @@
+// src/command.ts
+import { spawn } from "child_process";
+var nodeCommandRunner = {
+  run(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(command, args, {
+        cwd: options.cwd,
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+      const stdout = [];
+      const stderr = [];
+      child.stdout.on("data", (chunk) => stdout.push(chunk));
+      child.stderr.on("data", (chunk) => stderr.push(chunk));
+      child.on("error", reject);
+      child.on("close", (exitCode) => {
+        resolve({
+          exitCode: exitCode ?? 1,
+          stdout: Buffer.concat(stdout).toString("utf8"),
+          stderr: Buffer.concat(stderr).toString("utf8")
+        });
+      });
+      if (options.input) {
+        child.stdin.write(options.input);
+      }
+      child.stdin.end();
+    });
+  }
+};
+async function assertCommandSucceeded(result, label) {
+  if (result.exitCode !== 0) {
+    throw new Error(`${label} failed with exit code ${result.exitCode}: ${result.stderr || result.stdout}`);
+  }
+}
+
+// src/git.ts
+var INTERNAL_ARTIFACT_ROOTS = [".omx", ".codex", ".claude"];
+function branchNameForRun(runId) {
+  const safeRunId = runId.replace(/[^a-zA-Z0-9._-]/g, "-");
+  return `opentag/${safeRunId}`;
+}
+function parseStatusEntries(statusOutput) {
+  return statusOutput.split("\n").map((line) => line.replace(/\r$/, "")).filter(Boolean).map((line) => ({
+    status: line.slice(0, 2),
+    path: line.slice(3).trim()
+  })).filter((entry) => entry.path.length > 0);
+}
+function isInternalArtifactPath(path) {
+  return INTERNAL_ARTIFACT_ROOTS.some((root) => path === root || path.startsWith(`${root}/`));
+}
+function parseChangedFiles(statusOutput) {
+  return parseStatusEntries(statusOutput).map((entry) => entry.path).filter((path) => !isInternalArtifactPath(path));
+}
+async function createRunBranch(input) {
+  const result = await input.runner.run("git", ["checkout", "-B", input.branchName], { cwd: input.workspacePath });
+  await assertCommandSucceeded(result, "create run branch");
+}
+async function changedFiles(input) {
+  const result = await input.runner.run("git", ["status", "--porcelain"], { cwd: input.workspacePath });
+  await assertCommandSucceeded(result, "read changed files");
+  return parseChangedFiles(result.stdout);
+}
+async function cleanupInternalArtifacts(input) {
+  const statusResult = await input.runner.run("git", ["status", "--porcelain"], { cwd: input.workspacePath });
+  await assertCommandSucceeded(statusResult, "scan internal artifacts");
+  const untrackedRoots = Array.from(
+    new Set(
+      parseStatusEntries(statusResult.stdout).filter((entry) => entry.status === "??" && isInternalArtifactPath(entry.path)).map((entry) => entry.path.split("/", 1)[0] ?? entry.path)
+    )
+  );
+  if (untrackedRoots.length === 0) return [];
+  const cleanResult = await input.runner.run("git", ["clean", "-fd", "--", ...untrackedRoots], {
+    cwd: input.workspacePath
+  });
+  await assertCommandSucceeded(cleanResult, "clean internal artifacts");
+  return untrackedRoots;
+}
+async function pushBranch(input) {
+  const result = await input.runner.run("git", ["push", "-u", input.remote, input.branchName], { cwd: input.workspacePath });
+  await assertCommandSucceeded(result, "push run branch");
+}
+
+// src/codex.ts
+function contextLines(context) {
+  if (!context.length) return "No additional context pointers were provided.";
+  return context.map((pointer) => `- ${pointer.kind}: ${pointer.uri}`).join("\n");
+}
+function buildPrompt(input) {
+  return [
+    "You are executing an OpenTag run in a local checkout.",
+    `Run ID: ${input.runId}`,
+    "",
+    "User request:",
+    input.rawText,
+    "",
+    "Context pointers:",
+    contextLines(input.context),
+    "",
+    "Work autonomously but keep the change narrow. Run relevant verification if you modify files. End with a concise summary."
+  ].join("\n");
+}
+function createCodexExecutor(options = {}) {
+  const runner = options.runner ?? nodeCommandRunner;
+  const codexCommand = options.codexCommand ?? "codex";
+  return {
+    id: "codex",
+    displayName: "Codex Executor",
+    async canRun(input) {
+      const codexVersion = await runner.run(codexCommand, ["--version"], { cwd: input.workspacePath });
+      if (codexVersion.exitCode !== 0) {
+        return { ready: false, reason: `Codex CLI is not available: ${codexVersion.stderr || codexVersion.stdout}` };
+      }
+      const gitStatus = await runner.run("git", ["status", "--porcelain"], { cwd: input.workspacePath });
+      if (gitStatus.exitCode !== 0) {
+        return { ready: false, reason: `Workspace is not a git checkout: ${gitStatus.stderr || gitStatus.stdout}` };
+      }
+      if (gitStatus.stdout.trim().length > 0) {
+        return { ready: false, reason: "Workspace has uncommitted changes; refusing to run Codex executor." };
+      }
+      return { ready: true };
+    },
+    async run(input, sink) {
+      const branchName = branchNameForRun(input.runId);
+      await sink.emit({
+        type: "executor.started",
+        message: `Creating isolated branch ${branchName}`,
+        at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      await createRunBranch({ runner, workspacePath: input.workspacePath, branchName });
+      await sink.emit({
+        type: "executor.progress",
+        message: "Starting codex exec",
+        at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      const args = [
+        "exec",
+        "--cd",
+        input.workspacePath,
+        "--full-auto",
+        "--ephemeral",
+        ...options.model ? ["--model", options.model] : [],
+        "-"
+      ];
+      const codexResult = await runner.run(codexCommand, args, {
+        cwd: input.workspacePath,
+        input: buildPrompt({
+          runId: input.runId,
+          rawText: input.command.rawText,
+          context: input.context
+        })
+      });
+      await assertCommandSucceeded(codexResult, "codex exec");
+      const cleanedArtifacts = await cleanupInternalArtifacts({ runner, workspacePath: input.workspacePath });
+      if (cleanedArtifacts.length > 0) {
+        await sink.emit({
+          type: "executor.progress",
+          message: `Cleaned internal artifacts: ${cleanedArtifacts.join(", ")}`,
+          at: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      const files = await changedFiles({ runner, workspacePath: input.workspacePath });
+      await sink.emit({
+        type: "executor.completed",
+        message: `Codex executor completed with ${files.length} changed file(s)`,
+        at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      const output = codexResult.stdout.trim() || codexResult.stderr.trim() || "Codex completed without textual output.";
+      return {
+        conclusion: "success",
+        summary: output.slice(-4e3),
+        changedFiles: files,
+        artifacts: [{ title: "Run branch", uri: branchName }],
+        verification: [
+          {
+            command: "codex exec",
+            outcome: "passed",
+            excerpt: output.slice(-1e3)
+          }
+        ],
+        nextAction: files.length > 0 ? "Review the local branch and create a pull request." : "No file changes were detected."
+      };
+    },
+    async cancel() {
+      return;
+    }
+  };
+}
+
+// src/echo.ts
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function createEchoExecutor() {
+  return {
+    id: "echo",
+    displayName: "Echo Executor",
+    async canRun() {
+      return { ready: true };
+    },
+    async run(input, sink) {
+      await sink.emit({
+        type: "executor.started",
+        message: `Echo executor started for ${input.runId}`,
+        at: nowIso()
+      });
+      await sink.emit({
+        type: "executor.completed",
+        message: `Echo executor completed for ${input.runId}`,
+        at: nowIso()
+      });
+      return {
+        conclusion: "success",
+        summary: `Echoed OpenTag command: ${input.command.rawText}`,
+        verification: [
+          {
+            command: "echo",
+            outcome: "passed",
+            excerpt: input.command.rawText
+          }
+        ]
+      };
+    },
+    async cancel() {
+      return;
+    }
+  };
+}
+export {
+  assertCommandSucceeded,
+  branchNameForRun,
+  changedFiles,
+  cleanupInternalArtifacts,
+  createCodexExecutor,
+  createEchoExecutor,
+  createRunBranch,
+  isInternalArtifactPath,
+  nodeCommandRunner,
+  parseChangedFiles,
+  parseStatusEntries,
+  pushBranch
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/command.ts","../src/git.ts","../src/codex.ts","../src/echo.ts"],"sourcesContent":["import { spawn } from \"node:child_process\";\n\nexport type CommandResult = {\n  exitCode: number;\n  stdout: string;\n  stderr: string;\n};\n\nexport type CommandRunner = {\n  run(command: string, args: string[], options?: { cwd?: string; input?: string }): Promise<CommandResult>;\n};\n\nexport const nodeCommandRunner: CommandRunner = {\n  run(command, args, options = {}) {\n    return new Promise((resolve, reject) => {\n      const child = spawn(command, args, {\n        cwd: options.cwd,\n        stdio: [\"pipe\", \"pipe\", \"pipe\"]\n      });\n      const stdout: Buffer[] = [];\n      const stderr: Buffer[] = [];\n\n      child.stdout.on(\"data\", (chunk: Buffer) => stdout.push(chunk));\n      child.stderr.on(\"data\", (chunk: Buffer) => stderr.push(chunk));\n      child.on(\"error\", reject);\n      child.on(\"close\", (exitCode) => {\n        resolve({\n          exitCode: exitCode ?? 1,\n          stdout: Buffer.concat(stdout).toString(\"utf8\"),\n          stderr: Buffer.concat(stderr).toString(\"utf8\")\n        });\n      });\n\n      if (options.input) {\n        child.stdin.write(options.input);\n      }\n      child.stdin.end();\n    });\n  }\n};\n\nexport async function assertCommandSucceeded(result: CommandResult, label: string): Promise<void> {\n  if (result.exitCode !== 0) {\n    throw new Error(`${label} failed with exit code ${result.exitCode}: ${result.stderr || result.stdout}`);\n  }\n}\n","import type { CommandRunner } from \"./command.js\";\nimport { assertCommandSucceeded } from \"./command.js\";\n\nexport type GitStatusEntry = {\n  status: string;\n  path: string;\n};\n\nconst INTERNAL_ARTIFACT_ROOTS = [\".omx\", \".codex\", \".claude\"];\n\nexport function branchNameForRun(runId: string): string {\n  const safeRunId = runId.replace(/[^a-zA-Z0-9._-]/g, \"-\");\n  return `opentag/${safeRunId}`;\n}\n\nexport function parseStatusEntries(statusOutput: string): GitStatusEntry[] {\n  return statusOutput\n    .split(\"\\n\")\n    .map((line) => line.replace(/\\r$/, \"\"))\n    .filter(Boolean)\n    .map((line) => ({\n      status: line.slice(0, 2),\n      path: line.slice(3).trim()\n    }))\n    .filter((entry) => entry.path.length > 0);\n}\n\nexport function isInternalArtifactPath(path: string): boolean {\n  return INTERNAL_ARTIFACT_ROOTS.some((root) => path === root || path.startsWith(`${root}/`));\n}\n\nexport function parseChangedFiles(statusOutput: string): string[] {\n  return parseStatusEntries(statusOutput)\n    .map((entry) => entry.path)\n    .filter((path) => !isInternalArtifactPath(path));\n}\n\nexport async function createRunBranch(input: {\n  runner: CommandRunner;\n  workspacePath: string;\n  branchName: string;\n}): Promise<void> {\n  const result = await input.runner.run(\"git\", [\"checkout\", \"-B\", input.branchName], { cwd: input.workspacePath });\n  await assertCommandSucceeded(result, \"create run branch\");\n}\n\nexport async function changedFiles(input: { runner: CommandRunner; workspacePath: string }): Promise<string[]> {\n  const result = await input.runner.run(\"git\", [\"status\", \"--porcelain\"], { cwd: input.workspacePath });\n  await assertCommandSucceeded(result, \"read changed files\");\n  return parseChangedFiles(result.stdout);\n}\n\nexport async function cleanupInternalArtifacts(input: { runner: CommandRunner; workspacePath: string }): Promise<string[]> {\n  const statusResult = await input.runner.run(\"git\", [\"status\", \"--porcelain\"], { cwd: input.workspacePath });\n  await assertCommandSucceeded(statusResult, \"scan internal artifacts\");\n  const untrackedRoots = Array.from(\n    new Set(\n      parseStatusEntries(statusResult.stdout)\n        .filter((entry) => entry.status === \"??\" && isInternalArtifactPath(entry.path))\n        .map((entry) => entry.path.split(\"/\", 1)[0] ?? entry.path)\n    )\n  );\n  if (untrackedRoots.length === 0) return [];\n\n  const cleanResult = await input.runner.run(\"git\", [\"clean\", \"-fd\", \"--\", ...untrackedRoots], {\n    cwd: input.workspacePath\n  });\n  await assertCommandSucceeded(cleanResult, \"clean internal artifacts\");\n  return untrackedRoots;\n}\n\nexport async function pushBranch(input: {\n  runner: CommandRunner;\n  workspacePath: string;\n  remote: string;\n  branchName: string;\n}): Promise<void> {\n  const result = await input.runner.run(\"git\", [\"push\", \"-u\", input.remote, input.branchName], { cwd: input.workspacePath });\n  await assertCommandSucceeded(result, \"push run branch\");\n}\n","import type { ContextPointer } from \"@opentag/core\";\nimport { assertCommandSucceeded, nodeCommandRunner, type CommandRunner } from \"./command.js\";\nimport type { ExecutorAdapter } from \"./executor.js\";\nimport { branchNameForRun, changedFiles, cleanupInternalArtifacts, createRunBranch } from \"./git.js\";\n\nexport type CodexExecutorOptions = {\n  runner?: CommandRunner;\n  codexCommand?: string;\n  model?: string;\n};\n\nfunction contextLines(context: ContextPointer[]): string {\n  if (!context.length) return \"No additional context pointers were provided.\";\n  return context.map((pointer) => `- ${pointer.kind}: ${pointer.uri}`).join(\"\\n\");\n}\n\nfunction buildPrompt(input: {\n  runId: string;\n  rawText: string;\n  context: ContextPointer[];\n}): string {\n  return [\n    \"You are executing an OpenTag run in a local checkout.\",\n    `Run ID: ${input.runId}`,\n    \"\",\n    \"User request:\",\n    input.rawText,\n    \"\",\n    \"Context pointers:\",\n    contextLines(input.context),\n    \"\",\n    \"Work autonomously but keep the change narrow. Run relevant verification if you modify files. End with a concise summary.\"\n  ].join(\"\\n\");\n}\n\nexport function createCodexExecutor(options: CodexExecutorOptions = {}): ExecutorAdapter {\n  const runner = options.runner ?? nodeCommandRunner;\n  const codexCommand = options.codexCommand ?? \"codex\";\n\n  return {\n    id: \"codex\",\n    displayName: \"Codex Executor\",\n    async canRun(input) {\n      const codexVersion = await runner.run(codexCommand, [\"--version\"], { cwd: input.workspacePath });\n      if (codexVersion.exitCode !== 0) {\n        return { ready: false, reason: `Codex CLI is not available: ${codexVersion.stderr || codexVersion.stdout}` };\n      }\n      const gitStatus = await runner.run(\"git\", [\"status\", \"--porcelain\"], { cwd: input.workspacePath });\n      if (gitStatus.exitCode !== 0) {\n        return { ready: false, reason: `Workspace is not a git checkout: ${gitStatus.stderr || gitStatus.stdout}` };\n      }\n      if (gitStatus.stdout.trim().length > 0) {\n        return { ready: false, reason: \"Workspace has uncommitted changes; refusing to run Codex executor.\" };\n      }\n      return { ready: true };\n    },\n    async run(input, sink) {\n      const branchName = branchNameForRun(input.runId);\n      await sink.emit({\n        type: \"executor.started\",\n        message: `Creating isolated branch ${branchName}`,\n        at: new Date().toISOString()\n      });\n      await createRunBranch({ runner, workspacePath: input.workspacePath, branchName });\n\n      await sink.emit({\n        type: \"executor.progress\",\n        message: \"Starting codex exec\",\n        at: new Date().toISOString()\n      });\n\n      const args = [\n        \"exec\",\n        \"--cd\",\n        input.workspacePath,\n        \"--full-auto\",\n        \"--ephemeral\",\n        ...(options.model ? [\"--model\", options.model] : []),\n        \"-\"\n      ];\n      const codexResult = await runner.run(codexCommand, args, {\n        cwd: input.workspacePath,\n        input: buildPrompt({\n          runId: input.runId,\n          rawText: input.command.rawText,\n          context: input.context\n        })\n      });\n      await assertCommandSucceeded(codexResult, \"codex exec\");\n\n      const cleanedArtifacts = await cleanupInternalArtifacts({ runner, workspacePath: input.workspacePath });\n      if (cleanedArtifacts.length > 0) {\n        await sink.emit({\n          type: \"executor.progress\",\n          message: `Cleaned internal artifacts: ${cleanedArtifacts.join(\", \")}`,\n          at: new Date().toISOString()\n        });\n      }\n\n      const files = await changedFiles({ runner, workspacePath: input.workspacePath });\n      await sink.emit({\n        type: \"executor.completed\",\n        message: `Codex executor completed with ${files.length} changed file(s)`,\n        at: new Date().toISOString()\n      });\n\n      const output = codexResult.stdout.trim() || codexResult.stderr.trim() || \"Codex completed without textual output.\";\n      return {\n        conclusion: \"success\",\n        summary: output.slice(-4000),\n        changedFiles: files,\n        artifacts: [{ title: \"Run branch\", uri: branchName }],\n        verification: [\n          {\n            command: \"codex exec\",\n            outcome: \"passed\",\n            excerpt: output.slice(-1000)\n          }\n        ],\n        nextAction: files.length > 0 ? \"Review the local branch and create a pull request.\" : \"No file changes were detected.\"\n      };\n    },\n    async cancel() {\n      return;\n    }\n  };\n}\n","import type { ExecutorAdapter } from \"./executor.js\";\n\nfunction nowIso(): string {\n  return new Date().toISOString();\n}\n\nexport function createEchoExecutor(): ExecutorAdapter {\n  return {\n    id: \"echo\",\n    displayName: \"Echo Executor\",\n    async canRun() {\n      return { ready: true };\n    },\n    async run(input, sink) {\n      await sink.emit({\n        type: \"executor.started\",\n        message: `Echo executor started for ${input.runId}`,\n        at: nowIso()\n      });\n      await sink.emit({\n        type: \"executor.completed\",\n        message: `Echo executor completed for ${input.runId}`,\n        at: nowIso()\n      });\n      return {\n        conclusion: \"success\",\n        summary: `Echoed OpenTag command: ${input.command.rawText}`,\n        verification: [\n          {\n            command: \"echo\",\n            outcome: \"passed\",\n            excerpt: input.command.rawText\n          }\n        ]\n      };\n    },\n    async cancel() {\n      return;\n    }\n  };\n}\n"],"mappings":";AAAA,SAAS,aAAa;AAYf,IAAM,oBAAmC;AAAA,EAC9C,IAAI,SAAS,MAAM,UAAU,CAAC,GAAG;AAC/B,WAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,YAAM,QAAQ,MAAM,SAAS,MAAM;AAAA,QACjC,KAAK,QAAQ;AAAA,QACb,OAAO,CAAC,QAAQ,QAAQ,MAAM;AAAA,MAChC,CAAC;AACD,YAAM,SAAmB,CAAC;AAC1B,YAAM,SAAmB,CAAC;AAE1B,YAAM,OAAO,GAAG,QAAQ,CAAC,UAAkB,OAAO,KAAK,KAAK,CAAC;AAC7D,YAAM,OAAO,GAAG,QAAQ,CAAC,UAAkB,OAAO,KAAK,KAAK,CAAC;AAC7D,YAAM,GAAG,SAAS,MAAM;AACxB,YAAM,GAAG,SAAS,CAAC,aAAa;AAC9B,gBAAQ;AAAA,UACN,UAAU,YAAY;AAAA,UACtB,QAAQ,OAAO,OAAO,MAAM,EAAE,SAAS,MAAM;AAAA,UAC7C,QAAQ,OAAO,OAAO,MAAM,EAAE,SAAS,MAAM;AAAA,QAC/C,CAAC;AAAA,MACH,CAAC;AAED,UAAI,QAAQ,OAAO;AACjB,cAAM,MAAM,MAAM,QAAQ,KAAK;AAAA,MACjC;AACA,YAAM,MAAM,IAAI;AAAA,IAClB,CAAC;AAAA,EACH;AACF;AAEA,eAAsB,uBAAuB,QAAuB,OAA8B;AAChG,MAAI,OAAO,aAAa,GAAG;AACzB,UAAM,IAAI,MAAM,GAAG,KAAK,0BAA0B,OAAO,QAAQ,KAAK,OAAO,UAAU,OAAO,MAAM,EAAE;AAAA,EACxG;AACF;;;ACrCA,IAAM,0BAA0B,CAAC,QAAQ,UAAU,SAAS;AAErD,SAAS,iBAAiB,OAAuB;AACtD,QAAM,YAAY,MAAM,QAAQ,oBAAoB,GAAG;AACvD,SAAO,WAAW,SAAS;AAC7B;AAEO,SAAS,mBAAmB,cAAwC;AACzE,SAAO,aACJ,MAAM,IAAI,EACV,IAAI,CAAC,SAAS,KAAK,QAAQ,OAAO,EAAE,CAAC,EACrC,OAAO,OAAO,EACd,IAAI,CAAC,UAAU;AAAA,IACd,QAAQ,KAAK,MAAM,GAAG,CAAC;AAAA,IACvB,MAAM,KAAK,MAAM,CAAC,EAAE,KAAK;AAAA,EAC3B,EAAE,EACD,OAAO,CAAC,UAAU,MAAM,KAAK,SAAS,CAAC;AAC5C;AAEO,SAAS,uBAAuB,MAAuB;AAC5D,SAAO,wBAAwB,KAAK,CAAC,SAAS,SAAS,QAAQ,KAAK,WAAW,GAAG,IAAI,GAAG,CAAC;AAC5F;AAEO,SAAS,kBAAkB,cAAgC;AAChE,SAAO,mBAAmB,YAAY,EACnC,IAAI,CAAC,UAAU,MAAM,IAAI,EACzB,OAAO,CAAC,SAAS,CAAC,uBAAuB,IAAI,CAAC;AACnD;AAEA,eAAsB,gBAAgB,OAIpB;AAChB,QAAM,SAAS,MAAM,MAAM,OAAO,IAAI,OAAO,CAAC,YAAY,MAAM,MAAM,UAAU,GAAG,EAAE,KAAK,MAAM,cAAc,CAAC;AAC/G,QAAM,uBAAuB,QAAQ,mBAAmB;AAC1D;AAEA,eAAsB,aAAa,OAA4E;AAC7G,QAAM,SAAS,MAAM,MAAM,OAAO,IAAI,OAAO,CAAC,UAAU,aAAa,GAAG,EAAE,KAAK,MAAM,cAAc,CAAC;AACpG,QAAM,uBAAuB,QAAQ,oBAAoB;AACzD,SAAO,kBAAkB,OAAO,MAAM;AACxC;AAEA,eAAsB,yBAAyB,OAA4E;AACzH,QAAM,eAAe,MAAM,MAAM,OAAO,IAAI,OAAO,CAAC,UAAU,aAAa,GAAG,EAAE,KAAK,MAAM,cAAc,CAAC;AAC1G,QAAM,uBAAuB,cAAc,yBAAyB;AACpE,QAAM,iBAAiB,MAAM;AAAA,IAC3B,IAAI;AAAA,MACF,mBAAmB,aAAa,MAAM,EACnC,OAAO,CAAC,UAAU,MAAM,WAAW,QAAQ,uBAAuB,MAAM,IAAI,CAAC,EAC7E,IAAI,CAAC,UAAU,MAAM,KAAK,MAAM,KAAK,CAAC,EAAE,CAAC,KAAK,MAAM,IAAI;AAAA,IAC7D;AAAA,EACF;AACA,MAAI,eAAe,WAAW,EAAG,QAAO,CAAC;AAEzC,QAAM,cAAc,MAAM,MAAM,OAAO,IAAI,OAAO,CAAC,SAAS,OAAO,MAAM,GAAG,cAAc,GAAG;AAAA,IAC3F,KAAK,MAAM;AAAA,EACb,CAAC;AACD,QAAM,uBAAuB,aAAa,0BAA0B;AACpE,SAAO;AACT;AAEA,eAAsB,WAAW,OAKf;AAChB,QAAM,SAAS,MAAM,MAAM,OAAO,IAAI,OAAO,CAAC,QAAQ,MAAM,MAAM,QAAQ,MAAM,UAAU,GAAG,EAAE,KAAK,MAAM,cAAc,CAAC;AACzH,QAAM,uBAAuB,QAAQ,iBAAiB;AACxD;;;ACpEA,SAAS,aAAa,SAAmC;AACvD,MAAI,CAAC,QAAQ,OAAQ,QAAO;AAC5B,SAAO,QAAQ,IAAI,CAAC,YAAY,KAAK,QAAQ,IAAI,KAAK,QAAQ,GAAG,EAAE,EAAE,KAAK,IAAI;AAChF;AAEA,SAAS,YAAY,OAIV;AACT,SAAO;AAAA,IACL;AAAA,IACA,WAAW,MAAM,KAAK;AAAA,IACtB;AAAA,IACA;AAAA,IACA,MAAM;AAAA,IACN;AAAA,IACA;AAAA,IACA,aAAa,MAAM,OAAO;AAAA,IAC1B;AAAA,IACA;AAAA,EACF,EAAE,KAAK,IAAI;AACb;AAEO,SAAS,oBAAoB,UAAgC,CAAC,GAAoB;AACvF,QAAM,SAAS,QAAQ,UAAU;AACjC,QAAM,eAAe,QAAQ,gBAAgB;AAE7C,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,aAAa;AAAA,IACb,MAAM,OAAO,OAAO;AAClB,YAAM,eAAe,MAAM,OAAO,IAAI,cAAc,CAAC,WAAW,GAAG,EAAE,KAAK,MAAM,cAAc,CAAC;AAC/F,UAAI,aAAa,aAAa,GAAG;AAC/B,eAAO,EAAE,OAAO,OAAO,QAAQ,+BAA+B,aAAa,UAAU,aAAa,MAAM,GAAG;AAAA,MAC7G;AACA,YAAM,YAAY,MAAM,OAAO,IAAI,OAAO,CAAC,UAAU,aAAa,GAAG,EAAE,KAAK,MAAM,cAAc,CAAC;AACjG,UAAI,UAAU,aAAa,GAAG;AAC5B,eAAO,EAAE,OAAO,OAAO,QAAQ,oCAAoC,UAAU,UAAU,UAAU,MAAM,GAAG;AAAA,MAC5G;AACA,UAAI,UAAU,OAAO,KAAK,EAAE,SAAS,GAAG;AACtC,eAAO,EAAE,OAAO,OAAO,QAAQ,qEAAqE;AAAA,MACtG;AACA,aAAO,EAAE,OAAO,KAAK;AAAA,IACvB;AAAA,IACA,MAAM,IAAI,OAAO,MAAM;AACrB,YAAM,aAAa,iBAAiB,MAAM,KAAK;AAC/C,YAAM,KAAK,KAAK;AAAA,QACd,MAAM;AAAA,QACN,SAAS,4BAA4B,UAAU;AAAA,QAC/C,KAAI,oBAAI,KAAK,GAAE,YAAY;AAAA,MAC7B,CAAC;AACD,YAAM,gBAAgB,EAAE,QAAQ,eAAe,MAAM,eAAe,WAAW,CAAC;AAEhF,YAAM,KAAK,KAAK;AAAA,QACd,MAAM;AAAA,QACN,SAAS;AAAA,QACT,KAAI,oBAAI,KAAK,GAAE,YAAY;AAAA,MAC7B,CAAC;AAED,YAAM,OAAO;AAAA,QACX;AAAA,QACA;AAAA,QACA,MAAM;AAAA,QACN;AAAA,QACA;AAAA,QACA,GAAI,QAAQ,QAAQ,CAAC,WAAW,QAAQ,KAAK,IAAI,CAAC;AAAA,QAClD;AAAA,MACF;AACA,YAAM,cAAc,MAAM,OAAO,IAAI,cAAc,MAAM;AAAA,QACvD,KAAK,MAAM;AAAA,QACX,OAAO,YAAY;AAAA,UACjB,OAAO,MAAM;AAAA,UACb,SAAS,MAAM,QAAQ;AAAA,UACvB,SAAS,MAAM;AAAA,QACjB,CAAC;AAAA,MACH,CAAC;AACD,YAAM,uBAAuB,aAAa,YAAY;AAEtD,YAAM,mBAAmB,MAAM,yBAAyB,EAAE,QAAQ,eAAe,MAAM,cAAc,CAAC;AACtG,UAAI,iBAAiB,SAAS,GAAG;AAC/B,cAAM,KAAK,KAAK;AAAA,UACd,MAAM;AAAA,UACN,SAAS,+BAA+B,iBAAiB,KAAK,IAAI,CAAC;AAAA,UACnE,KAAI,oBAAI,KAAK,GAAE,YAAY;AAAA,QAC7B,CAAC;AAAA,MACH;AAEA,YAAM,QAAQ,MAAM,aAAa,EAAE,QAAQ,eAAe,MAAM,cAAc,CAAC;AAC/E,YAAM,KAAK,KAAK;AAAA,QACd,MAAM;AAAA,QACN,SAAS,iCAAiC,MAAM,MAAM;AAAA,QACtD,KAAI,oBAAI,KAAK,GAAE,YAAY;AAAA,MAC7B,CAAC;AAED,YAAM,SAAS,YAAY,OAAO,KAAK,KAAK,YAAY,OAAO,KAAK,KAAK;AACzE,aAAO;AAAA,QACL,YAAY;AAAA,QACZ,SAAS,OAAO,MAAM,IAAK;AAAA,QAC3B,cAAc;AAAA,QACd,WAAW,CAAC,EAAE,OAAO,cAAc,KAAK,WAAW,CAAC;AAAA,QACpD,cAAc;AAAA,UACZ;AAAA,YACE,SAAS;AAAA,YACT,SAAS;AAAA,YACT,SAAS,OAAO,MAAM,IAAK;AAAA,UAC7B;AAAA,QACF;AAAA,QACA,YAAY,MAAM,SAAS,IAAI,uDAAuD;AAAA,MACxF;AAAA,IACF;AAAA,IACA,MAAM,SAAS;AACb;AAAA,IACF;AAAA,EACF;AACF;;;AC5HA,SAAS,SAAiB;AACxB,UAAO,oBAAI,KAAK,GAAE,YAAY;AAChC;AAEO,SAAS,qBAAsC;AACpD,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,aAAa;AAAA,IACb,MAAM,SAAS;AACb,aAAO,EAAE,OAAO,KAAK;AAAA,IACvB;AAAA,IACA,MAAM,IAAI,OAAO,MAAM;AACrB,YAAM,KAAK,KAAK;AAAA,QACd,MAAM;AAAA,QACN,SAAS,6BAA6B,MAAM,KAAK;AAAA,QACjD,IAAI,OAAO;AAAA,MACb,CAAC;AACD,YAAM,KAAK,KAAK;AAAA,QACd,MAAM;AAAA,QACN,SAAS,+BAA+B,MAAM,KAAK;AAAA,QACnD,IAAI,OAAO;AAAA,MACb,CAAC;AACD,aAAO;AAAA,QACL,YAAY;AAAA,QACZ,SAAS,2BAA2B,MAAM,QAAQ,OAAO;AAAA,QACzD,cAAc;AAAA,UACZ;AAAA,YACE,SAAS;AAAA,YACT,SAAS;AAAA,YACT,SAAS,MAAM,QAAQ;AAAA,UACzB;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,IACA,MAAM,SAAS;AACb;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@opentag/runner",
+  "version": "0.1.0",
+  "description": "Executor contracts and built-in runner adapters for OpenTag.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "opentag",
+    "runner",
+    "executor",
+    "codex",
+    "agents"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@opentag/core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsup && tsc -b tsconfig.json --emitDeclarationOnly --force",
+    "lint": "tsc --noEmit"
+  }
+}