@agentrix/agentrix-run 0.2.0

package/bin/agentrix-run.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/index.mjs');

package/dist/index.cjs

@@ -0,0 +1,656 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var shared = require('@agentrix/shared');
+
+const DEFAULT_RESPONSE_MODE = "stream";
+const DEFAULT_WAIT_TIMEOUT_SECONDS = 1800;
+function usage() {
+  return [
+    "Usage: agentrix-run --agent <agent> --prompt <prompt> [options]",
+    "",
+    "Options:",
+    "  --title <text>",
+    "  --repo <json>",
+    "  --output-schema <json>",
+    "  --ref <ref>",
+    "  --sha <sha>",
+    "  --base-ref <ref>",
+    "  --head-ref <ref>",
+    "  --pr-number <number>",
+    "  --issue-number <number>",
+    "  --response-mode <stream|async>",
+    "  --timeout <seconds>",
+    "  --capability-profile <name>",
+    "  --runner-id <cloud-id|machine-id>",
+    "  --result-file <path>",
+    "  --base-url <url>",
+    "  --api-key <api-key>",
+    "  --metadata <key=value>",
+    "  --help"
+  ].join("\n");
+}
+function requireValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return value;
+}
+function parseRepo(value) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new Error(`Invalid --repo JSON: ${error instanceof Error ? error.message : "unknown error"}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("--repo must be a JSON object");
+  }
+  return parsed;
+}
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function formatSchemaPath(path) {
+  return path.length > 0 ? path.join(".") : "$";
+}
+function normalizeStrictStructuredOutputSchemaNode(value, path, warnings) {
+  if (Array.isArray(value)) {
+    return value.map(
+      (item, index) => normalizeStrictStructuredOutputSchemaNode(item, [...path, String(index)], warnings)
+    );
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const node = {};
+  for (const [key, child] of Object.entries(value)) {
+    node[key] = normalizeStrictStructuredOutputSchemaNode(child, [...path, key], warnings);
+  }
+  const hasProperties = isPlainObject(node.properties);
+  const typeValue = node.type;
+  const isObjectSchema = typeValue === "object" || Array.isArray(typeValue) && typeValue.includes("object") || hasProperties;
+  if (isObjectSchema) {
+    if (node.additionalProperties !== false) {
+      node.additionalProperties = false;
+      warnings.push(`${formatSchemaPath(path)}: set additionalProperties=false`);
+    }
+    if (hasProperties) {
+      const properties = node.properties;
+      const propertyNames = Object.keys(properties);
+      const requiredValue = node.required;
+      if (requiredValue !== void 0 && !Array.isArray(requiredValue)) {
+        throw new Error(`${formatSchemaPath(path)}.required must be an array of property names`);
+      }
+      if (Array.isArray(requiredValue)) {
+        const unknownNames = requiredValue.filter(
+          (item) => typeof item !== "string" || !propertyNames.includes(item)
+        );
+        if (unknownNames.length > 0) {
+          throw new Error(
+            `${formatSchemaPath(path)}.required contains unknown properties: ${unknownNames.map(String).join(", ")}`
+          );
+        }
+      }
+      const normalizedRequired = [...propertyNames];
+      const currentRequired = Array.isArray(requiredValue) ? requiredValue : [];
+      const isSameRequired = currentRequired.length === normalizedRequired.length && currentRequired.every((item, index) => item === normalizedRequired[index]);
+      if (!isSameRequired) {
+        node.required = normalizedRequired;
+        warnings.push(`${formatSchemaPath(path)}: normalized required to all properties`);
+      }
+    }
+  }
+  return node;
+}
+function normalizeStrictStructuredOutputSchema(schema) {
+  const warnings = [];
+  const normalized = normalizeStrictStructuredOutputSchemaNode(schema, [], warnings);
+  if (!isPlainObject(normalized)) {
+    throw new Error("--output-schema must normalize to a JSON object");
+  }
+  return {
+    schema: normalized,
+    warnings
+  };
+}
+function printOutputSchemaWarnings(warnings) {
+  if (warnings.length === 0) {
+    return;
+  }
+  for (const warning of warnings) {
+    process.stderr.write(`[agentrix-run] normalized output schema: ${warning}
+`);
+  }
+}
+function parseOutputSchema(value) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new Error(`Invalid --output-schema JSON: ${error instanceof Error ? error.message : "unknown error"}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("--output-schema must be a JSON object");
+  }
+  const normalized = normalizeStrictStructuredOutputSchema(parsed);
+  printOutputSchemaWarnings(normalized.warnings);
+  return normalized.schema;
+}
+function parseMetadataEntry(value) {
+  const separatorIndex = value.indexOf("=");
+  if (separatorIndex <= 0) {
+    throw new Error(`Invalid --metadata value: ${value}`);
+  }
+  const key = value.slice(0, separatorIndex).trim();
+  const metadataValue = value.slice(separatorIndex + 1).trim();
+  if (!key) {
+    throw new Error(`Invalid --metadata key: ${value}`);
+  }
+  return [key, metadataValue];
+}
+function parseInteger(value, flag) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${flag} must be a positive integer`);
+  }
+  return parsed;
+}
+function parseArgs(argv) {
+  const options = {
+    agent: "",
+    prompt: "",
+    responseMode: DEFAULT_RESPONSE_MODE,
+    metadata: {}
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case "--help":
+        console.log(usage());
+        process.exit(0);
+      case "--agent":
+        options.agent = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--title":
+        options.title = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--prompt":
+        options.prompt = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--repo":
+        options.repo = parseRepo(requireValue(argv, index, arg));
+        index += 1;
+        break;
+      case "--output-schema":
+        options.outputSchema = parseOutputSchema(requireValue(argv, index, arg));
+        index += 1;
+        break;
+      case "--ref":
+        options.ref = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--sha":
+        options.sha = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--base-ref":
+        options.baseRef = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--head-ref":
+        options.headRef = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--pr-number":
+        options.prNumber = parseInteger(requireValue(argv, index, arg), arg);
+        index += 1;
+        break;
+      case "--issue-number":
+        options.issueNumber = parseInteger(requireValue(argv, index, arg), arg);
+        index += 1;
+        break;
+      case "--response-mode": {
+        const value = requireValue(argv, index, arg);
+        if (value !== "stream" && value !== "async") {
+          throw new Error(`Unsupported --response-mode: ${value}`);
+        }
+        options.responseMode = value;
+        index += 1;
+        break;
+      }
+      case "--timeout":
+        options.timeoutSeconds = parseInteger(requireValue(argv, index, arg), arg);
+        index += 1;
+        break;
+      case "--capability-profile":
+        options.capabilityProfile = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--runner-id":
+        options.runnerId = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--result-file":
+        options.resultFile = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--base-url":
+        options.baseUrl = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--api-key":
+        options.apiKey = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--metadata": {
+        const [key, value] = parseMetadataEntry(requireValue(argv, index, arg));
+        options.metadata[key] = value;
+        index += 1;
+        break;
+      }
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  if (!options.agent.trim()) {
+    throw new Error("--agent is required");
+  }
+  if (!options.prompt.trim()) {
+    throw new Error("--prompt is required");
+  }
+  return options;
+}
+function normalizeRef(value) {
+  if (!value) {
+    return void 0;
+  }
+  return value.replace(/^refs\/heads\//, "");
+}
+function safeReadJsonFile(path) {
+  if (!path) {
+    return void 0;
+  }
+  try {
+    const content = node_fs.readFileSync(path, "utf8");
+    const parsed = JSON.parse(content);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    return void 0;
+  }
+  return void 0;
+}
+function splitRepositoryPath(value) {
+  if (!value) {
+    return {};
+  }
+  const parts = value.split("/").filter(Boolean);
+  if (parts.length < 2) {
+    return {};
+  }
+  return {
+    owner: parts.slice(0, -1).join("/"),
+    name: parts[parts.length - 1]
+  };
+}
+function optionalPositiveInt(value) {
+  if (!value) {
+    return void 0;
+  }
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
+}
+function getNestedNumber(value, ...keys) {
+  let current = value;
+  for (const key of keys) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      return void 0;
+    }
+    current = current[key];
+  }
+  return typeof current === "number" ? current : void 0;
+}
+function getNestedString(value, ...keys) {
+  let current = value;
+  for (const key of keys) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      return void 0;
+    }
+    current = current[key];
+  }
+  return typeof current === "string" ? current : void 0;
+}
+function detectGithub() {
+  if (process.env.GITHUB_ACTIONS !== "true") {
+    return null;
+  }
+  const payload = safeReadJsonFile(process.env.GITHUB_EVENT_PATH);
+  const repository = splitRepositoryPath(process.env.GITHUB_REPOSITORY);
+  const runUrl = process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}` : void 0;
+  return {
+    repo: {
+      gitServerId: process.env.AGENTRIX_GIT_SERVER_ID || "github",
+      owner: repository.owner,
+      name: repository.name
+    },
+    git: {
+      ref: normalizeRef(process.env.GITHUB_REF),
+      sha: process.env.GITHUB_SHA,
+      baseRef: process.env.GITHUB_BASE_REF || getNestedString(payload, "pull_request", "base", "ref"),
+      headRef: process.env.GITHUB_HEAD_REF || getNestedString(payload, "pull_request", "head", "ref"),
+      prNumber: getNestedNumber(payload, "pull_request", "number"),
+      issueNumber: getNestedNumber(payload, "issue", "number")
+    },
+    context: {
+      ciProvider: "github_actions",
+      eventName: process.env.GITHUB_EVENT_NAME,
+      eventAction: getNestedString(payload, "action"),
+      runUrl,
+      payload
+    }
+  };
+}
+function detectGitlab() {
+  if (process.env.GITLAB_CI !== "true") {
+    return null;
+  }
+  const repository = splitRepositoryPath(process.env.CI_PROJECT_PATH);
+  return {
+    repo: {
+      gitServerId: process.env.AGENTRIX_GIT_SERVER_ID || "gitlab",
+      owner: repository.owner,
+      name: repository.name
+    },
+    git: {
+      ref: process.env.CI_COMMIT_REF_NAME,
+      sha: process.env.CI_COMMIT_SHA,
+      baseRef: process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME,
+      headRef: process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME,
+      prNumber: optionalPositiveInt(process.env.CI_MERGE_REQUEST_IID),
+      issueNumber: optionalPositiveInt(process.env.AGENTRIX_ISSUE_NUMBER)
+    },
+    context: {
+      ciProvider: "gitlab_ci",
+      eventName: process.env.AGENTRIX_EVENT_NAME || process.env.CI_PIPELINE_SOURCE,
+      eventAction: process.env.AGENTRIX_EVENT_ACTION,
+      jobUrl: process.env.CI_JOB_URL,
+      runUrl: process.env.CI_PIPELINE_URL
+    }
+  };
+}
+function detectCiContext() {
+  return detectGithub() ?? detectGitlab() ?? {};
+}
+function mergeRepo(explicitRepo, detectedRepo) {
+  if (!explicitRepo && !detectedRepo) {
+    return void 0;
+  }
+  return {
+    ...detectedRepo ?? {},
+    ...explicitRepo ?? {}
+  };
+}
+function buildRequest(options, detected) {
+  const repo = mergeRepo(options.repo, detected.repo);
+  const request = {
+    agent: options.agent,
+    title: options.title,
+    prompt: options.prompt,
+    outputSchema: options.outputSchema,
+    repo: {
+      gitServerId: repo?.gitServerId,
+      serverRepoId: repo?.serverRepoId,
+      owner: repo?.owner,
+      name: repo?.name
+    },
+    git: {
+      ref: options.ref ?? detected.git?.ref,
+      sha: options.sha ?? detected.git?.sha,
+      baseRef: options.baseRef ?? detected.git?.baseRef,
+      headRef: options.headRef ?? detected.git?.headRef,
+      prNumber: options.prNumber ?? detected.git?.prNumber,
+      issueNumber: options.issueNumber ?? detected.git?.issueNumber
+    },
+    execution: {
+      capabilityProfile: options.capabilityProfile,
+      runnerId: options.runnerId
+    },
+    context: detected.context?.ciProvider ? {
+      ciProvider: detected.context.ciProvider,
+      eventName: process.env.AGENTRIX_EVENT_NAME || detected.context.eventName,
+      eventAction: process.env.AGENTRIX_EVENT_ACTION || detected.context.eventAction,
+      jobUrl: process.env.AGENTRIX_JOB_URL || detected.context.jobUrl,
+      runUrl: process.env.AGENTRIX_RUN_URL || detected.context.runUrl,
+      payload: detected.context.payload
+    } : void 0,
+    metadata: Object.keys(options.metadata).length > 0 ? options.metadata : void 0
+  };
+  return shared.CreateCiRunRequestSchema.parse(request);
+}
+function resolveBaseUrl(options) {
+  const value = options.baseUrl || process.env.AGENTRIX_BASE_URL;
+  if (!value) {
+    throw new Error("Missing --base-url and AGENTRIX_BASE_URL");
+  }
+  return value.replace(/\/+$/, "");
+}
+function resolveApiKey(options) {
+  const value = options.apiKey || process.env.AGENTRIX_API_KEY;
+  if (!value) {
+    throw new Error("Missing --api-key and AGENTRIX_API_KEY");
+  }
+  return value;
+}
+async function requestJson(method, url, apiKey, body) {
+  const response = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    },
+    body: body === void 0 ? void 0 : JSON.stringify(body)
+  });
+  const text = await response.text();
+  const parsed = text ? JSON.parse(text) : void 0;
+  if (!response.ok) {
+    const message = parsed && typeof parsed === "object" && !Array.isArray(parsed) && typeof parsed.message === "string" ? parsed.message : `HTTP ${response.status}`;
+    throw new Error(message);
+  }
+  return parsed;
+}
+async function createRun(baseUrl, apiKey, request) {
+  const response = await requestJson("POST", `${baseUrl}/v1/ci/runs`, apiKey, request);
+  return shared.CreateCiRunResponseSchema.parse(response);
+}
+function exitCodeForStatus(status) {
+  return status === "completed" ? 0 : 1;
+}
+function printStandardFields(payload) {
+  console.log(`run_id=${payload.runId}`);
+  console.log(`status=${payload.status}`);
+  console.log(`detail_url=${payload.detailUrl}`);
+  if (payload.result) {
+    console.log(`result=${payload.result}`);
+  }
+}
+function ensureWaitDeadline(options) {
+  const timeoutSeconds = options.timeoutSeconds ?? DEFAULT_WAIT_TIMEOUT_SECONDS;
+  return Date.now() + timeoutSeconds * 1e3;
+}
+function writeJsonLine(value) {
+  process.stdout.write(`${JSON.stringify(value)}
+`);
+}
+function writeStreamEvent(type, data) {
+  const record = {
+    type,
+    data
+  };
+  writeJsonLine(record);
+}
+function buildFinalResultRecord(status) {
+  return {
+    runId: status.runId,
+    status: status.status,
+    result: status.result,
+    structuredOutput: status.structuredOutput,
+    detailUrl: status.detailUrl
+  };
+}
+function writeResultFile(path, status) {
+  if (!path) {
+    return;
+  }
+  node_fs.writeFileSync(path, `${JSON.stringify(buildFinalResultRecord(status), null, 2)}
+`, "utf8");
+}
+function writeAsyncResultFile(path, run) {
+  if (!path) {
+    return;
+  }
+  const record = {
+    runId: run.runId,
+    status: run.status,
+    result: "",
+    detailUrl: run.detailUrl
+  };
+  node_fs.writeFileSync(path, `${JSON.stringify(record, null, 2)}
+`, "utf8");
+}
+function parseSseBlock(block) {
+  const normalized = block.replace(/\r/g, "");
+  const lines = normalized.split("\n");
+  let event = "message";
+  const dataLines = [];
+  for (const line of lines) {
+    if (!line) {
+      continue;
+    }
+    if (line.startsWith(":")) {
+      continue;
+    }
+    if (line.startsWith("event:")) {
+      event = line.slice("event:".length).trim();
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice("data:".length).trimStart());
+    }
+  }
+  if (dataLines.length === 0) {
+    return null;
+  }
+  const dataText = dataLines.join("\n");
+  return {
+    event,
+    data: JSON.parse(dataText)
+  };
+}
+async function createRunStream(baseUrl, apiKey, request, deadline) {
+  const timeoutMs = Math.max(deadline - Date.now(), 1);
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`${baseUrl}/v1/ci/runs`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "text/event-stream"
+      },
+      body: JSON.stringify(request),
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      const parsed = text ? JSON.parse(text) : void 0;
+      const message = parsed && typeof parsed === "object" && !Array.isArray(parsed) && typeof parsed.message === "string" ? parsed.message : `HTTP ${response.status}`;
+      throw new Error(message);
+    }
+    if (!response.body) {
+      throw new Error("Missing SSE response body");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (; ; ) {
+      const { value, done } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      buffer = buffer.replace(/\r\n/g, "\n");
+      while (true) {
+        const delimiterIndex = buffer.indexOf("\n\n");
+        if (delimiterIndex === -1) {
+          break;
+        }
+        const block = buffer.slice(0, delimiterIndex);
+        buffer = buffer.slice(delimiterIndex + 2);
+        const parsed = parseSseBlock(block);
+        if (!parsed) {
+          continue;
+        }
+        if (parsed.event === "run.created" || parsed.event === "task.event") {
+          writeStreamEvent(parsed.event, parsed.data);
+          continue;
+        }
+        if (parsed.event === "run.completed" || parsed.event === "run.failed" || parsed.event === "run.canceled" || parsed.event === "run.timeout") {
+          const finalStatus = shared.CiRunStatusResponseSchema.parse(parsed.data);
+          writeStreamEvent(parsed.event, finalStatus);
+          return finalStatus;
+        }
+        if (parsed.event === "run.error") {
+          writeStreamEvent(parsed.event, parsed.data);
+          const error = parsed.data;
+          throw new Error(typeof error.message === "string" ? error.message : "CI run stream failed");
+        }
+      }
+    }
+    buffer += decoder.decode();
+    buffer = buffer.replace(/\r\n/g, "\n");
+    throw new Error("CI run stream ended before terminal event");
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error("Timed out waiting for CI run terminal status");
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}
+async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  const detected = detectCiContext();
+  const baseUrl = resolveBaseUrl(options);
+  const apiKey = resolveApiKey(options);
+  const request = buildRequest(options, detected);
+  if (options.responseMode === "async") {
+    const run = await createRun(baseUrl, apiKey, request);
+    writeAsyncResultFile(options.resultFile, run);
+    printStandardFields({
+      runId: run.runId,
+      status: run.status,
+      detailUrl: run.detailUrl
+    });
+    return 0;
+  }
+  const deadline = ensureWaitDeadline(options);
+  const finalStatus = await createRunStream(baseUrl, apiKey, request, deadline);
+  writeResultFile(options.resultFile, finalStatus);
+  return exitCodeForStatus(finalStatus.status);
+}
+
+main().then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/index.mjs

@@ -0,0 +1,654 @@
+import { writeFileSync, readFileSync } from 'node:fs';
+import { CreateCiRunRequestSchema, CiRunStatusResponseSchema, CreateCiRunResponseSchema } from '@agentrix/shared';
+
+const DEFAULT_RESPONSE_MODE = "stream";
+const DEFAULT_WAIT_TIMEOUT_SECONDS = 1800;
+function usage() {
+  return [
+    "Usage: agentrix-run --agent <agent> --prompt <prompt> [options]",
+    "",
+    "Options:",
+    "  --title <text>",
+    "  --repo <json>",
+    "  --output-schema <json>",
+    "  --ref <ref>",
+    "  --sha <sha>",
+    "  --base-ref <ref>",
+    "  --head-ref <ref>",
+    "  --pr-number <number>",
+    "  --issue-number <number>",
+    "  --response-mode <stream|async>",
+    "  --timeout <seconds>",
+    "  --capability-profile <name>",
+    "  --runner-id <cloud-id|machine-id>",
+    "  --result-file <path>",
+    "  --base-url <url>",
+    "  --api-key <api-key>",
+    "  --metadata <key=value>",
+    "  --help"
+  ].join("\n");
+}
+function requireValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return value;
+}
+function parseRepo(value) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new Error(`Invalid --repo JSON: ${error instanceof Error ? error.message : "unknown error"}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("--repo must be a JSON object");
+  }
+  return parsed;
+}
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function formatSchemaPath(path) {
+  return path.length > 0 ? path.join(".") : "$";
+}
+function normalizeStrictStructuredOutputSchemaNode(value, path, warnings) {
+  if (Array.isArray(value)) {
+    return value.map(
+      (item, index) => normalizeStrictStructuredOutputSchemaNode(item, [...path, String(index)], warnings)
+    );
+  }
+  if (!isPlainObject(value)) {
+    return value;
+  }
+  const node = {};
+  for (const [key, child] of Object.entries(value)) {
+    node[key] = normalizeStrictStructuredOutputSchemaNode(child, [...path, key], warnings);
+  }
+  const hasProperties = isPlainObject(node.properties);
+  const typeValue = node.type;
+  const isObjectSchema = typeValue === "object" || Array.isArray(typeValue) && typeValue.includes("object") || hasProperties;
+  if (isObjectSchema) {
+    if (node.additionalProperties !== false) {
+      node.additionalProperties = false;
+      warnings.push(`${formatSchemaPath(path)}: set additionalProperties=false`);
+    }
+    if (hasProperties) {
+      const properties = node.properties;
+      const propertyNames = Object.keys(properties);
+      const requiredValue = node.required;
+      if (requiredValue !== void 0 && !Array.isArray(requiredValue)) {
+        throw new Error(`${formatSchemaPath(path)}.required must be an array of property names`);
+      }
+      if (Array.isArray(requiredValue)) {
+        const unknownNames = requiredValue.filter(
+          (item) => typeof item !== "string" || !propertyNames.includes(item)
+        );
+        if (unknownNames.length > 0) {
+          throw new Error(
+            `${formatSchemaPath(path)}.required contains unknown properties: ${unknownNames.map(String).join(", ")}`
+          );
+        }
+      }
+      const normalizedRequired = [...propertyNames];
+      const currentRequired = Array.isArray(requiredValue) ? requiredValue : [];
+      const isSameRequired = currentRequired.length === normalizedRequired.length && currentRequired.every((item, index) => item === normalizedRequired[index]);
+      if (!isSameRequired) {
+        node.required = normalizedRequired;
+        warnings.push(`${formatSchemaPath(path)}: normalized required to all properties`);
+      }
+    }
+  }
+  return node;
+}
+function normalizeStrictStructuredOutputSchema(schema) {
+  const warnings = [];
+  const normalized = normalizeStrictStructuredOutputSchemaNode(schema, [], warnings);
+  if (!isPlainObject(normalized)) {
+    throw new Error("--output-schema must normalize to a JSON object");
+  }
+  return {
+    schema: normalized,
+    warnings
+  };
+}
+function printOutputSchemaWarnings(warnings) {
+  if (warnings.length === 0) {
+    return;
+  }
+  for (const warning of warnings) {
+    process.stderr.write(`[agentrix-run] normalized output schema: ${warning}
+`);
+  }
+}
+function parseOutputSchema(value) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new Error(`Invalid --output-schema JSON: ${error instanceof Error ? error.message : "unknown error"}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("--output-schema must be a JSON object");
+  }
+  const normalized = normalizeStrictStructuredOutputSchema(parsed);
+  printOutputSchemaWarnings(normalized.warnings);
+  return normalized.schema;
+}
+function parseMetadataEntry(value) {
+  const separatorIndex = value.indexOf("=");
+  if (separatorIndex <= 0) {
+    throw new Error(`Invalid --metadata value: ${value}`);
+  }
+  const key = value.slice(0, separatorIndex).trim();
+  const metadataValue = value.slice(separatorIndex + 1).trim();
+  if (!key) {
+    throw new Error(`Invalid --metadata key: ${value}`);
+  }
+  return [key, metadataValue];
+}
+function parseInteger(value, flag) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${flag} must be a positive integer`);
+  }
+  return parsed;
+}
+function parseArgs(argv) {
+  const options = {
+    agent: "",
+    prompt: "",
+    responseMode: DEFAULT_RESPONSE_MODE,
+    metadata: {}
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case "--help":
+        console.log(usage());
+        process.exit(0);
+      case "--agent":
+        options.agent = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--title":
+        options.title = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--prompt":
+        options.prompt = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--repo":
+        options.repo = parseRepo(requireValue(argv, index, arg));
+        index += 1;
+        break;
+      case "--output-schema":
+        options.outputSchema = parseOutputSchema(requireValue(argv, index, arg));
+        index += 1;
+        break;
+      case "--ref":
+        options.ref = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--sha":
+        options.sha = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--base-ref":
+        options.baseRef = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--head-ref":
+        options.headRef = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--pr-number":
+        options.prNumber = parseInteger(requireValue(argv, index, arg), arg);
+        index += 1;
+        break;
+      case "--issue-number":
+        options.issueNumber = parseInteger(requireValue(argv, index, arg), arg);
+        index += 1;
+        break;
+      case "--response-mode": {
+        const value = requireValue(argv, index, arg);
+        if (value !== "stream" && value !== "async") {
+          throw new Error(`Unsupported --response-mode: ${value}`);
+        }
+        options.responseMode = value;
+        index += 1;
+        break;
+      }
+      case "--timeout":
+        options.timeoutSeconds = parseInteger(requireValue(argv, index, arg), arg);
+        index += 1;
+        break;
+      case "--capability-profile":
+        options.capabilityProfile = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--runner-id":
+        options.runnerId = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--result-file":
+        options.resultFile = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--base-url":
+        options.baseUrl = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--api-key":
+        options.apiKey = requireValue(argv, index, arg);
+        index += 1;
+        break;
+      case "--metadata": {
+        const [key, value] = parseMetadataEntry(requireValue(argv, index, arg));
+        options.metadata[key] = value;
+        index += 1;
+        break;
+      }
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  if (!options.agent.trim()) {
+    throw new Error("--agent is required");
+  }
+  if (!options.prompt.trim()) {
+    throw new Error("--prompt is required");
+  }
+  return options;
+}
+function normalizeRef(value) {
+  if (!value) {
+    return void 0;
+  }
+  return value.replace(/^refs\/heads\//, "");
+}
+function safeReadJsonFile(path) {
+  if (!path) {
+    return void 0;
+  }
+  try {
+    const content = readFileSync(path, "utf8");
+    const parsed = JSON.parse(content);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    return void 0;
+  }
+  return void 0;
+}
+function splitRepositoryPath(value) {
+  if (!value) {
+    return {};
+  }
+  const parts = value.split("/").filter(Boolean);
+  if (parts.length < 2) {
+    return {};
+  }
+  return {
+    owner: parts.slice(0, -1).join("/"),
+    name: parts[parts.length - 1]
+  };
+}
+function optionalPositiveInt(value) {
+  if (!value) {
+    return void 0;
+  }
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
+}
+function getNestedNumber(value, ...keys) {
+  let current = value;
+  for (const key of keys) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      return void 0;
+    }
+    current = current[key];
+  }
+  return typeof current === "number" ? current : void 0;
+}
+function getNestedString(value, ...keys) {
+  let current = value;
+  for (const key of keys) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      return void 0;
+    }
+    current = current[key];
+  }
+  return typeof current === "string" ? current : void 0;
+}
+function detectGithub() {
+  if (process.env.GITHUB_ACTIONS !== "true") {
+    return null;
+  }
+  const payload = safeReadJsonFile(process.env.GITHUB_EVENT_PATH);
+  const repository = splitRepositoryPath(process.env.GITHUB_REPOSITORY);
+  const runUrl = process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}` : void 0;
+  return {
+    repo: {
+      gitServerId: process.env.AGENTRIX_GIT_SERVER_ID || "github",
+      owner: repository.owner,
+      name: repository.name
+    },
+    git: {
+      ref: normalizeRef(process.env.GITHUB_REF),
+      sha: process.env.GITHUB_SHA,
+      baseRef: process.env.GITHUB_BASE_REF || getNestedString(payload, "pull_request", "base", "ref"),
+      headRef: process.env.GITHUB_HEAD_REF || getNestedString(payload, "pull_request", "head", "ref"),
+      prNumber: getNestedNumber(payload, "pull_request", "number"),
+      issueNumber: getNestedNumber(payload, "issue", "number")
+    },
+    context: {
+      ciProvider: "github_actions",
+      eventName: process.env.GITHUB_EVENT_NAME,
+      eventAction: getNestedString(payload, "action"),
+      runUrl,
+      payload
+    }
+  };
+}
+function detectGitlab() {
+  if (process.env.GITLAB_CI !== "true") {
+    return null;
+  }
+  const repository = splitRepositoryPath(process.env.CI_PROJECT_PATH);
+  return {
+    repo: {
+      gitServerId: process.env.AGENTRIX_GIT_SERVER_ID || "gitlab",
+      owner: repository.owner,
+      name: repository.name
+    },
+    git: {
+      ref: process.env.CI_COMMIT_REF_NAME,
+      sha: process.env.CI_COMMIT_SHA,
+      baseRef: process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME,
+      headRef: process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME,
+      prNumber: optionalPositiveInt(process.env.CI_MERGE_REQUEST_IID),
+      issueNumber: optionalPositiveInt(process.env.AGENTRIX_ISSUE_NUMBER)
+    },
+    context: {
+      ciProvider: "gitlab_ci",
+      eventName: process.env.AGENTRIX_EVENT_NAME || process.env.CI_PIPELINE_SOURCE,
+      eventAction: process.env.AGENTRIX_EVENT_ACTION,
+      jobUrl: process.env.CI_JOB_URL,
+      runUrl: process.env.CI_PIPELINE_URL
+    }
+  };
+}
+function detectCiContext() {
+  return detectGithub() ?? detectGitlab() ?? {};
+}
+function mergeRepo(explicitRepo, detectedRepo) {
+  if (!explicitRepo && !detectedRepo) {
+    return void 0;
+  }
+  return {
+    ...detectedRepo ?? {},
+    ...explicitRepo ?? {}
+  };
+}
+function buildRequest(options, detected) {
+  const repo = mergeRepo(options.repo, detected.repo);
+  const request = {
+    agent: options.agent,
+    title: options.title,
+    prompt: options.prompt,
+    outputSchema: options.outputSchema,
+    repo: {
+      gitServerId: repo?.gitServerId,
+      serverRepoId: repo?.serverRepoId,
+      owner: repo?.owner,
+      name: repo?.name
+    },
+    git: {
+      ref: options.ref ?? detected.git?.ref,
+      sha: options.sha ?? detected.git?.sha,
+      baseRef: options.baseRef ?? detected.git?.baseRef,
+      headRef: options.headRef ?? detected.git?.headRef,
+      prNumber: options.prNumber ?? detected.git?.prNumber,
+      issueNumber: options.issueNumber ?? detected.git?.issueNumber
+    },
+    execution: {
+      capabilityProfile: options.capabilityProfile,
+      runnerId: options.runnerId
+    },
+    context: detected.context?.ciProvider ? {
+      ciProvider: detected.context.ciProvider,
+      eventName: process.env.AGENTRIX_EVENT_NAME || detected.context.eventName,
+      eventAction: process.env.AGENTRIX_EVENT_ACTION || detected.context.eventAction,
+      jobUrl: process.env.AGENTRIX_JOB_URL || detected.context.jobUrl,
+      runUrl: process.env.AGENTRIX_RUN_URL || detected.context.runUrl,
+      payload: detected.context.payload
+    } : void 0,
+    metadata: Object.keys(options.metadata).length > 0 ? options.metadata : void 0
+  };
+  return CreateCiRunRequestSchema.parse(request);
+}
+function resolveBaseUrl(options) {
+  const value = options.baseUrl || process.env.AGENTRIX_BASE_URL;
+  if (!value) {
+    throw new Error("Missing --base-url and AGENTRIX_BASE_URL");
+  }
+  return value.replace(/\/+$/, "");
+}
+function resolveApiKey(options) {
+  const value = options.apiKey || process.env.AGENTRIX_API_KEY;
+  if (!value) {
+    throw new Error("Missing --api-key and AGENTRIX_API_KEY");
+  }
+  return value;
+}
+async function requestJson(method, url, apiKey, body) {
+  const response = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    },
+    body: body === void 0 ? void 0 : JSON.stringify(body)
+  });
+  const text = await response.text();
+  const parsed = text ? JSON.parse(text) : void 0;
+  if (!response.ok) {
+    const message = parsed && typeof parsed === "object" && !Array.isArray(parsed) && typeof parsed.message === "string" ? parsed.message : `HTTP ${response.status}`;
+    throw new Error(message);
+  }
+  return parsed;
+}
+async function createRun(baseUrl, apiKey, request) {
+  const response = await requestJson("POST", `${baseUrl}/v1/ci/runs`, apiKey, request);
+  return CreateCiRunResponseSchema.parse(response);
+}
+function exitCodeForStatus(status) {
+  return status === "completed" ? 0 : 1;
+}
+function printStandardFields(payload) {
+  console.log(`run_id=${payload.runId}`);
+  console.log(`status=${payload.status}`);
+  console.log(`detail_url=${payload.detailUrl}`);
+  if (payload.result) {
+    console.log(`result=${payload.result}`);
+  }
+}
+function ensureWaitDeadline(options) {
+  const timeoutSeconds = options.timeoutSeconds ?? DEFAULT_WAIT_TIMEOUT_SECONDS;
+  return Date.now() + timeoutSeconds * 1e3;
+}
+function writeJsonLine(value) {
+  process.stdout.write(`${JSON.stringify(value)}
+`);
+}
+function writeStreamEvent(type, data) {
+  const record = {
+    type,
+    data
+  };
+  writeJsonLine(record);
+}
+function buildFinalResultRecord(status) {
+  return {
+    runId: status.runId,
+    status: status.status,
+    result: status.result,
+    structuredOutput: status.structuredOutput,
+    detailUrl: status.detailUrl
+  };
+}
+function writeResultFile(path, status) {
+  if (!path) {
+    return;
+  }
+  writeFileSync(path, `${JSON.stringify(buildFinalResultRecord(status), null, 2)}
+`, "utf8");
+}
+function writeAsyncResultFile(path, run) {
+  if (!path) {
+    return;
+  }
+  const record = {
+    runId: run.runId,
+    status: run.status,
+    result: "",
+    detailUrl: run.detailUrl
+  };
+  writeFileSync(path, `${JSON.stringify(record, null, 2)}
+`, "utf8");
+}
+function parseSseBlock(block) {
+  const normalized = block.replace(/\r/g, "");
+  const lines = normalized.split("\n");
+  let event = "message";
+  const dataLines = [];
+  for (const line of lines) {
+    if (!line) {
+      continue;
+    }
+    if (line.startsWith(":")) {
+      continue;
+    }
+    if (line.startsWith("event:")) {
+      event = line.slice("event:".length).trim();
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      dataLines.push(line.slice("data:".length).trimStart());
+    }
+  }
+  if (dataLines.length === 0) {
+    return null;
+  }
+  const dataText = dataLines.join("\n");
+  return {
+    event,
+    data: JSON.parse(dataText)
+  };
+}
+async function createRunStream(baseUrl, apiKey, request, deadline) {
+  const timeoutMs = Math.max(deadline - Date.now(), 1);
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`${baseUrl}/v1/ci/runs`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "text/event-stream"
+      },
+      body: JSON.stringify(request),
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      const parsed = text ? JSON.parse(text) : void 0;
+      const message = parsed && typeof parsed === "object" && !Array.isArray(parsed) && typeof parsed.message === "string" ? parsed.message : `HTTP ${response.status}`;
+      throw new Error(message);
+    }
+    if (!response.body) {
+      throw new Error("Missing SSE response body");
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (; ; ) {
+      const { value, done } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      buffer = buffer.replace(/\r\n/g, "\n");
+      while (true) {
+        const delimiterIndex = buffer.indexOf("\n\n");
+        if (delimiterIndex === -1) {
+          break;
+        }
+        const block = buffer.slice(0, delimiterIndex);
+        buffer = buffer.slice(delimiterIndex + 2);
+        const parsed = parseSseBlock(block);
+        if (!parsed) {
+          continue;
+        }
+        if (parsed.event === "run.created" || parsed.event === "task.event") {
+          writeStreamEvent(parsed.event, parsed.data);
+          continue;
+        }
+        if (parsed.event === "run.completed" || parsed.event === "run.failed" || parsed.event === "run.canceled" || parsed.event === "run.timeout") {
+          const finalStatus = CiRunStatusResponseSchema.parse(parsed.data);
+          writeStreamEvent(parsed.event, finalStatus);
+          return finalStatus;
+        }
+        if (parsed.event === "run.error") {
+          writeStreamEvent(parsed.event, parsed.data);
+          const error = parsed.data;
+          throw new Error(typeof error.message === "string" ? error.message : "CI run stream failed");
+        }
+      }
+    }
+    buffer += decoder.decode();
+    buffer = buffer.replace(/\r\n/g, "\n");
+    throw new Error("CI run stream ended before terminal event");
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error("Timed out waiting for CI run terminal status");
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}
+async function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  const detected = detectCiContext();
+  const baseUrl = resolveBaseUrl(options);
+  const apiKey = resolveApiKey(options);
+  const request = buildRequest(options, detected);
+  if (options.responseMode === "async") {
+    const run = await createRun(baseUrl, apiKey, request);
+    writeAsyncResultFile(options.resultFile, run);
+    printStandardFields({
+      runId: run.runId,
+      status: run.status,
+      detailUrl: run.detailUrl
+    });
+    return 0;
+  }
+  const deadline = ensureWaitDeadline(options);
+  const finalStatus = await createRunStream(baseUrl, apiKey, request, deadline);
+  writeResultFile(options.resultFile, finalStatus);
+  return exitCodeForStatus(finalStatus.status);
+}
+
+main().then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@agentrix/agentrix-run",
+  "version": "0.2.0",
+  "description": "Native CI submit-and-observe wrapper for Agentrix",
+  "type": "module",
+  "bin": {
+    "agentrix-run": "./bin/agentrix-run.mjs"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "package.json"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "shx rm -rf dist && tsc --noEmit && pkgroll",
+    "prepublishOnly": "yarn build"
+  },
+  "dependencies": {
+    "@agentrix/shared": "^2.12.0"
+  },
+  "devDependencies": {
+    "@types/node": ">=20",
+    "pkgroll": "^2.14.2",
+    "shx": "^0.3.3",
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "packageManager": "yarn@1.22.22"
+}