Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

SDK @defai-digital/ax-code-sdk

SDK TypeScript pour intégrer le runtime d’agent de codage AX Code dans vos propres applications.

Utilisez-le pour superviser un runtime AX Code signé compatible à travers des frontières typées sans interface ou gRPC, consommer des événements en flux, projeter l’état de session et tester des intégrations d’application. Les hôtes source qui fournissent à dessein le paquet de runtime privé peuvent aussi utiliser l’adaptateur dans le processus createAgent().

Installation

pnpm add jsr:@defai-digital/ax-code-sdk@2.6.7

deno add jsr:@defai-digital/ax-code-sdk@2.6.7

npx jsr add @defai-digital/ax-code-sdk@2.6.7

Exige Node.js 26+ (ou Deno avec la compatibilité Node). Les versions plus anciennes de Node.js ne sont pas prises en charge. Les assistants de cycle de vie sans interface et gRPC attendent un exécutable signé ax-code sur PATH, ou un chemin absolu passé comme binary. Les versions du SDK et du runtime sont indépendantes. Vérifiez le protocole de capacité du runtime avant d’activer des fonctionnalités d’application ; un contrôle de version du SDK seul n’établit pas la compatibilité du runtime.

Le nom de paquet de l’espace de travail @ax-code/sdk est privé à ce monodépôt. Les consommateurs publics installent toujours @defai-digital/ax-code-sdk depuis JSR.

Migration de l'API de rapport

AX Code 7.24.1 remplace le rapport de graphe DRE par le rapport d’exécution. Les intégrations de rapport doivent utiliser ax-code run-report et les routes HTTP /run-report ; l’ancienne commande dre-graph et les routes /dre-graph sont retirées. Les opérations du SDK généré sont désormais getRunReportSessionSessionId et getRunReportSessionSessionIdFingerprint, remplaçant les opérations getDreGraph correspondantes.

Mettez à niveau ensemble l’intégration de rapport et le runtime. Les autres surfaces d’intégration exigent encore leurs propres contrôles de capacité du runtime.

Choisir une surface d'intégration

Les applications publiques doivent utiliser headless ou grpc avec un runtime AX Code signé compatible. HTTP/OpenAPI reste derrière ces SDK comme repli et couche de diagnostic. Les sous-chemins hérités @defai-digital/ax-code-sdk/v2 restent pour la compatibilité du runtime ; les nouvelles intégrations ne doivent pas commencer là.

createAgent() charge le paquet source privé ax-code au moment de l’appel. Le runtime n’est pas publié sur JSR.

Démarrage rapide (sans interface)

import { createHeadlessClient, startHeadlessBackend } from "@defai-digital/ax-code-sdk/headless"

const directory = process.cwd()
const backend = await startHeadlessBackend({ directory })
try {
  const client = createHeadlessClient({
    baseUrl: backend.url,
    directory,
    headers: backend.headers,
  })
  const session = await client.createSession({ title: "SDK example" })
  await client.sendPrompt(session.id, {
    parts: [{ type: "text", text: "Summarize this project." }],
  })
} finally {
  await backend.close()
}

Les hôtes de bureau peuvent passer un chemin absolu vérifié comme binary. Voir example/headless-app.ts pour une boucle d’application fondée sur la projection.

Moteur sans interface

startHeadlessBackend lance ax-code serve sur un port de boucle locale aléatoire, génère un identifiant à usage unique, attend /global/health et renvoie une poignée. close() envoie SIGTERM, puis SIGKILL.

import {
  startHeadlessBackend,
  createHeadlessClient,
  createHeadlessProjectionState,
  applyHeadlessProjectionEvent,
} from "@defai-digital/ax-code-sdk/headless"

const backend = await startHeadlessBackend({ directory: "/path/to/workspace" })
try {
  const client = createHeadlessClient({ baseUrl: backend.url, headers: backend.headers })
  const state = createHeadlessProjectionState()
  const session = await client.createSession({ title: "My session" })

  await client.sendPrompt(session.id, { parts: [{ type: "text", text: "Review this project" }] })
  for await (const event of client.subscribe()) {
    applyHeadlessProjectionEvent(state, event)
    if (state.session_status[session.id]?.type === "idle") break
  }
} finally {
  await backend.close()
}

createHeadlessProjectionState et applyHeadlessProjectionEvent sont du TypeScript pur. Les interfaces d’application doivent traiter permission, question, session_diff, todo, session_status et session_error comme état principal. Les réponses autonomes sont une activation explicite ; les applications supervisées doivent afficher les demandes de permission et de question en attente.

La projection autonome garde en attente les permissions isolation_escalation, bash_destructive, ops_approve, webmcp, hook et computer, ainsi que toute requête dont les métadonnées définissent requireInteractive: true. Les consommateurs doivent obtenir une réponse humaine explicite pour ces demandes.

Bureau gRPC / natif

Utilisez @defai-digital/ax-code-sdk/grpc lorsqu’un hôte natif possède déjà le transport (préchargement Electron, Tauri, Rust, HTTP/2).

import {
  createAxCodeGrpcClientFromNativeIpc,
  resolveAxCodeGrpcProtoUrl,
  startAxCodeGrpcHeadlessBackend,
} from "@defai-digital/ax-code-sdk/grpc"

const backend = await startAxCodeGrpcHeadlessBackend({ directory: "/path/to/workspace" })
try {
  const client = backend.client
  await client.bootstrap.load({
    include: { sessions: true, providers: true, path: true, vcs: true },
  })
  const session = (await client.createSession({ title: "Desktop session" })) as { id: string }
  await client.sendPrompt(session.id, { parts: [{ type: "text", text: "Review this project" }] })
  const protoUrl = resolveAxCodeGrpcProtoUrl()
} finally {
  await backend.close()
}

• createAxCodeGrpcClientFromNativeIpc() — IPC par clone structuré (préchargement / Tauri).
• createAxCodeGrpcClientFromNativeBridge() — même domaine JavaScript, avec AbortSignal et des itérables asynchrones.
• createAxCodeGrpcClientFromNativeHandlers() — lier des noms de méthodes à des gestionnaires typés ; requireHandlers échoue vite en cas de lacunes.
• startAxCodeGrpcNodeHttp2Server() depuis @defai-digital/ax-code-sdk/grpc/node — exposer le même pont comme point de terminaison gRPC HTTP/2 local.
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods() — catalogue canonique de méthodes pour les listes d’autorisation et les noms proto.

createAxCodeGrpcClientFromHttp() est limité à la boucle locale. La ressource proto est packages/sdk/proto/ax_code/v1/headless.proto et se résout à l’exécution avec resolveAxCodeGrpcProtoUrl().

Agent dans le processus (hôtes source seulement)

Ce chemin exige le paquet de runtime privé ax-code. Ce n’est pas la frontière publique d’intégration d’application.

import { createAgent, tool } from "@defai-digital/ax-code-sdk"
import { z } from "zod"

const deploy = tool({
  name: "deploy_staging",
  description: "Deploy the current branch to staging",
  parameters: z.object({
    service: z.enum(["api", "web", "worker"]),
    skipTests: z.boolean().default(false),
  }),
  execute: async ({ service }) => ({ url: `https://staging.example.com/${service}` }),
})

const agent = await createAgent({ directory: "/repo", tools: [deploy] })

const result = await agent.run("Fix the login bug")
for await (const event of agent.stream("Explain this codebase")) {
  if (event.type === "text") process.stdout.write(event.text)
}
const session = await agent.session()
await session.run("Read src/auth/index.ts")
await agent.dispose()

L’authentification est détectée automatiquement depuis les variables d’environnement, injectée via auth: { provider, apiKey }, ou prise depuis ax-code providers login.

import { ProviderError, ToolError, TimeoutError } from "@defai-digital/ax-code-sdk"

try {
  await agent.run("Deploy to prod")
} catch (e) {
  if (e instanceof ProviderError && e.isRetryable) console.log("Rate limited, retry later")
  else if (e instanceof ToolError) console.log(`Tool "${e.tool}" failed: ${e.message}`)
  else if (e instanceof TimeoutError) console.log(`Timed out after ${e.timeout}ms`)
}

D’autres exemples : example/programmatic.ts.

Tests

import { createMockAgent, assertToolSuccess } from "@defai-digital/ax-code-sdk/testing"

test("CI bot scans for CVEs", async () => {
  const agent = createMockAgent({
    replies: ["Found 2 CVEs. Opening PR to bump versions."],
    toolCalls: [{ tool: "grep", input: { pattern: "CVE-" }, output: "CVE-2025-1234" }],
  })
  const result = await agent.run("scan for CVEs")
  expect(result.text).toContain("2 CVEs")
  assertToolSuccess(result, "grep")
})

Compatibilité de version

import { SDK_VERSION, isSDKVersionCompatible } from "@defai-digital/ax-code-sdk"

console.log(SDK_VERSION)
if (!isSDKVersionCompatible("^2.0.0")) {
  throw new Error("Incompatible SDK version")
}

Contrôles de requête et orientation

Le SDK 2.6 ajoute des contrôles facultatifs aux requêtes sans interface. Les appels existants conservent leur comportement ; aucune échéance par défaut n’est imposée.

import { createHeadlessClient, HeadlessRequestError } from "@defai-digital/ax-code-sdk/headless"

const client = createHeadlessClient({
  baseUrl: backend.url,
  headers: backend.headers,
  directory,
  requestOptions: { timeoutMs: 30_000 },
})
const compatibility = await client.checkCompatibility({ requiredFeatures: ["sessions", "asyncPrompt"] })
if (!compatibility.compatible) throw new Error(compatibility.issues.join("; "))

const controller = new AbortController()
const state = await client.steering(sessionID, { signal: controller.signal, timeoutMs: 5_000 })
if (state.generation) {
  try {
    const receipt = await client.steer(
      sessionID,
      {
        expectedGeneration: state.generation,
        clientID, // Keep this id with the correction so uncertain outcomes can be reconciled.
        text: "Use the existing session contract.",
      },
      { signal: controller.signal },
    )
    console.log(receipt.status)
  } catch (error) {
    if (error instanceof HeadlessRequestError && error.status === 409) {
      console.log("Correction conflicts with a prior request; reconcile the steering state.")
    } else {
      throw error
    }
  }
}

client.taskQueue.steer(taskID) expose le point de terminaison atomique de suivi en file. Son résultat generation_not_active laisse la ligne inchangée. Le SDK renvoie les reçus et les raisons de rejet tels quels. accepted signifie admis pour une frontière de boucle ultérieure ; applied signifie admis de façon durable à cette frontière, l’achèvement du fournisseur restant distinct. Les reçus sont locaux au processus et bornés, donc leur absence après un redémarrage ne prouve pas qu’une correction n’a jamais été appliquée.

requestOptions fournit des défauts pour toutes les requêtes et commandes de commodité sans interface, y compris les opérations de flux de travail et de file de tâches. Les méthodes centrales de session et de commande, ainsi que l’orientation, acceptent des forçages par appel ; timeoutMs: 0 désactive une échéance par défaut. Les abonnements utilisent leur propre signal, et client.client conserve les contrôles du client généré. Un HeadlessTransport personnalisé reçoit le signal et doit libérer ses ressources en attente lorsqu’il s’abandonne.

L’annulation HTTP et IPC arrête l’attente locale. Une mutation déjà répartie peut encore s’exécuter ; réconciliez l’état de session et de file avant d’agir davantage. Aucun des deux transports ne réessaie les mutations. Les échéances lèvent TimeoutError ; les abandons de l’appelant préservent la raison du signal. Les réponses HTTP et IPC qui ne sont pas un succès lèvent HeadlessRequestError avec status, body, method et path ; les trames d’erreur de protocole IPC conservent IpcTransportError.

Compatibilité du runtime et mise à niveau depuis le SDK 2.5

La ligne de base du contrat généré actuel est la source AX Code v7.23.0. Le SDK 2.6 n’infère pas des fonctionnalités non annoncées à partir de la version du runtime. Le catalogue de capacités actuel n’annonce pas l’orientation séparément ; vérifiez le point de terminaison de lecture avant de proposer l’orientation, et gérez les erreurs de route non prise en charge. Le SDK 2.6 préserve les points d’entrée générés et sans interface existants. Les nouvelles métadonnées d’erreur de réponse et les contrôles de requête sont additifs ; le code qui capture Error continue de fonctionner.

Les applications qui mettent à niveau des épingles plus anciennes doivent d’abord vérifier leur runtime signé, puis tester la négociation de capacité, la projection d’événements, les permissions et questions en attente, l’annulation et l’arrêt du moteur. Les changements d’épingle du consommateur appartiennent au dépôt consommateur après la publication du SDK cible. Validez le paquet compilé localement avec pnpm --dir packages/sdk/js run test:consumer ; cela contrôle les imports publics, les déclarations et les ressources proto dans un jeu d’essai isolé, sans le paquet source du runtime privé.

Intégrations entre langages

Ce paquet est le SDK TypeScript/JavaScript de première partie. Pour Python, Go, Java, Rust ou d’autres runtimes, générez depuis le proto gRPC du dépôt ou utilisez la frontière CLI/runtime possédée par cette intégration.

Migration depuis @ax-code/sdk 1.4.0

Le sous-chemin ./programmatic réexporte encore l’entrée par défaut ; traitez-le comme déprécié.

Licence

Apache-2.0