Developer Docs
Quickstart
Browse documentation
AlphaCodex 0.143Public npm alpha

Argos developer documentation

SDK

Use the server-side SDK for explicit integration. The Codex CLI already wraps these primitives for the supported alpha path.

Execution SDK

The current SDK is ESM-only, server-side only, and requires Node.js 18.18 or newer.

bash
npm install @argosbyaurevon/sdk@beta
typescript
import { createArgosClient } from "@argosbyaurevon/sdk";

const argos = createArgosClient({
  apiBaseUrl: process.env.ARGOS_APP_URL!,
  apiKey: process.env.ARGOS_API_KEY!,
});

Run and checkpoint

This low-level example uses current exported methods and types. Production execution must still preserve its exact operation identity and reconcile any ambiguous external outcome before retrying.

controlled-operation.ts
import { randomUUID } from "node:crypto";
import { createArgosClient } from "@argosbyaurevon/sdk";

const argos = createArgosClient({
  apiBaseUrl: process.env.ARGOS_APP_URL!,
  apiKey: process.env.ARGOS_API_KEY!,
});

const run = await argos.startRun({
  externalRunId: randomUUID(),
  userGoal: "Update password reset rate limiting.",
});

const checkpoint = await argos.beforeAction({
  agentId: process.env.ARGOS_AGENT_ID!,
  workflowId: process.env.ARGOS_WORKFLOW_ID!,
  externalActionId: randomUUID(),
  tool: "apply_patch",
  action: "update_file",
  targetType: "repository_file",
  targetId: "src/auth/password-reset/handler.ts",
  engineeringContext: {
    path: "src/auth/password-reset/handler.ts",
    requestedOutcome: "Add password reset rate limiting.",
    taskScope: {
      expectedPaths: ["src/auth/password-reset/**"],
      reviewPaths: ["src/shared/**"],
      protectedPaths: ["src/auth/session/**"],
    },
  },
  runContext: {
    runId: run.runId,
    externalStepId: randomUUID(),
    expectedRunVersion: run.runVersion,
  },
});

if (checkpoint.decision === "approval_required") {
  // Give approvalRequestId to a separately authenticated reviewer process.
  console.log(checkpoint.approvalRequestId);
} else if (checkpoint.decision === "block") {
  console.log("Mutation blocked before execution.");
} else if (checkpoint.decision === "allow" && checkpoint.executionRun) {
  // Execute the intended operation, then report its real outcome.
  await argos.recordResult(checkpoint.actionId, {
    finalOutcome: "executed",
    resultSummary: { summary: "Expected file update completed." },
    runContext: {
      runId: checkpoint.executionRun.runId,
      stepId: checkpoint.executionRun.stepId,
      expectedRunVersion: checkpoint.executionRun.runVersion,
      expectedStepVersion: checkpoint.executionRun.stepVersion,
    },
  });
}

console.log(argos.taskUrl(run.runId));
console.log(argos.evidenceUrl(checkpoint.evidencePacketId));

The higher-level controlledAction helper remains available for explicitly instrumented callbacks. The supported Codex CLI uses the packaged adapter and does not require customer code to reproduce this low-level flow.

Human reviewer client

createArgosReviewerClient accepts an existing short-lived Supabase human access token. The server resolves the user and rechecks organization membership for every read and decision.

review.ts
import { createArgosReviewerClient } from "@argosbyaurevon/sdk";

const reviewer = createArgosReviewerClient({
  apiBaseUrl: process.env.ARGOS_APP_URL!,
  accessToken: humanSession.access_token,
});

const { intervention } = await reviewer.getIntervention(interventionId);

await reviewer.decide({
  interventionId: intervention.id,
  decision: "approved", // Or "denied".
});