Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

@defai-digital/ax-code-sdk per TypeScript

SDK TypeScript per integrare il runtime dell’agente di programmazione AX Code nelle tue applicazioni.

Usalo per supervisionare un runtime firmato di AX Code compatibile attraverso confini tipizzati headless o gRPC, consumare eventi in streaming, proiettare lo stato della sessione e testare le integrazioni dell’applicazione. Gli host sorgente che forniscono deliberatamente il pacchetto privato del runtime possono anche usare l’adattatore in-process createAgent().

Installazione

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

Richiede Node.js 26+ (oppure Deno con compatibilità Node). Le versioni più vecchie di Node.js non sono supportate. Gli helper del ciclo di vita headless e gRPC si aspettano un eseguibile firmato ax-code su PATH, oppure un percorso assoluto passato come binary. Le versioni di SDK e runtime sono indipendenti. Controlla il protocollo di capacità del runtime prima di abilitare le funzioni dell’app; un controllo della sola versione dell’SDK non stabilisce la compatibilità del runtime.

Il nome del pacchetto dello workspace @ax-code/sdk è privato di questo monorepo. I consumatori pubblici installano sempre @defai-digital/ax-code-sdk da JSR.

Migrazione dell'API dei rapporti

AX Code 7.24.1 sostituisce il rapporto a grafo DRE con Run Report. Le integrazioni dei rapporti devono usare ax-code run-report e le route HTTP /run-report; il vecchio comando dre-graph e le route /dre-graph sono rimossi. Le operazioni generate dell’SDK sono ora getRunReportSessionSessionId e getRunReportSessionSessionIdFingerprint, al posto delle operazioni getDreGraph corrispondenti.

Aggiorna insieme l’integrazione dei rapporti e il runtime. Le altre superfici di integrazione richiedono ancora i propri controlli di capacità del runtime.

Scegli una superficie di integrazione

Le applicazioni pubbliche devono usare headless o grpc con un runtime firmato di AX Code compatibile. HTTP/OpenAPI resta dietro quegli SDK come ripiego e strato di diagnostica. I sottopercorsi legacy @defai-digital/ax-code-sdk/v2 restano per la compatibilità del runtime; le nuove integrazioni non devono partire da lì.

createAgent() carica il pacchetto sorgente privato ax-code al momento della chiamata. Il runtime non è pubblicato su JSR.

Avvio rapido (headless)

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()
}

Gli host desktop possono passare un percorso assoluto verificato come binary. Vedi example/headless-app.ts per un ciclo di app basato sulla proiezione.

Backend headless

startHeadlessBackend genera ax-code serve su una porta loopback casuale, crea una credenziale monouso, attende /global/health e restituisce un handle. close() invia SIGTERM, poi 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 e applyHeadlessProjectionEvent sono TypeScript puro. Le interfacce delle app devono trattare permission, question, session_diff, todo, session_status e session_error come stato primario. Le risposte autonome sono facoltative; le app supervisionate devono mostrare le richieste di permesso e di domanda in attesa.

La proiezione autonoma mantiene in attesa i permessi isolation_escalation, bash_destructive, ops_approve, webmcp, hook e computer, oltre a qualsiasi richiesta i cui metadati impostano requireInteractive: true. I consumatori devono ottenere una risposta umana esplicita per queste richieste.

gRPC / desktop nativo

Usa @defai-digital/ax-code-sdk/grpc quando un host nativo possiede già il trasporto (preload di 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 structured-clone (preload / Tauri).
• createAxCodeGrpcClientFromNativeBridge() — stesso realm JavaScript, con AbortSignal e iterabili asincroni.
• createAxCodeGrpcClientFromNativeHandlers() — collega i nomi dei metodi a handler tipizzati; requireHandlers fallisce subito sulle lacune.
• startAxCodeGrpcNodeHttp2Server() da @defai-digital/ax-code-sdk/grpc/node — espone lo stesso ponte come endpoint gRPC HTTP/2 locale.
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods() — catalogo canonico dei metodi per elenchi consentiti e nomi proto.

createAxCodeGrpcClientFromHttp() è solo loopback. L’asset proto è packages/sdk/proto/ax_code/v1/headless.proto e viene risolto a runtime con resolveAxCodeGrpcProtoUrl().

Agente in-process (solo host sorgente)

Questo percorso richiede il pacchetto privato del runtime ax-code. Non è il confine pubblico di integrazione delle app.

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’autenticazione viene rilevata automaticamente dalle variabili d’ambiente, iniettata tramite auth: { provider, apiKey }, oppure presa da 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`)
}

Altri esempi: example/programmatic.ts.

Test

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à di versione

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")
}

Controlli delle richieste e instradamento

SDK 2.6 aggiunge controlli facoltativi alle richieste headless. Le chiamate esistenti conservano il proprio comportamento; non viene imposta alcuna scadenza predefinita.

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) espone l’endpoint atomico del seguito in coda. Il suo risultato generation_not_active lascia la riga invariata. L’SDK restituisce ricevute e motivi di rifiuto alla lettera. accepted significa ammesso per un confine di ciclo successivo; applied significa ammesso in modo durevole a quel confine, con il completamento del provider ancora separato. Le ricevute sono locali al processo e limitate, quindi la loro assenza dopo un riavvio non prova che una correzione non sia mai stata applicata.

requestOptions fornisce i predefiniti per tutte le richieste e i comandi di comodità headless, incluse le operazioni di flusso di lavoro e di coda dei compiti. I metodi centrali di sessione e comando e l’instradamento accettano override per chiamata; timeoutMs: 0 disattiva una scadenza predefinita. Le sottoscrizioni usano il proprio signal, e client.client conserva i controlli del client generato. Un HeadlessTransport personalizzato riceve il segnale e deve rilasciare le risorse in attesa quando viene interrotto.

L’annullamento HTTP e IPC ferma l’attesa locale. Una mutazione già inviata può comunque eseguirsi; riconcilia lo stato di sessione e coda prima di agire oltre. Nessuno dei due trasporti ritenta le mutazioni. Le scadenze sollevano TimeoutError; gli annullamenti del chiamante conservano il motivo del segnale. Le risposte HTTP e IPC non riuscite sollevano HeadlessRequestError con status, body, method e path; i frame di errore del protocollo IPC conservano IpcTransportError.

Compatibilità del runtime e aggiornamento da SDK 2.5

La linea di base corrente del contratto generato è il sorgente di AX Code v7.23.0. SDK 2.6 non deduce funzioni non annunciate dalla versione del runtime. Il catalogo di capacità corrente non annuncia l’instradamento separatamente; controlla l’endpoint di lettura prima di offrire l’instradamento e gestisci gli errori di route non supportata. SDK 2.6 conserva i punti di ingresso generati e headless esistenti. I nuovi metadati di errore di risposta e i controlli delle richieste sono additivi; il codice che intercetta Error continua a funzionare.

Le applicazioni che aggiornano pin più vecchi devono prima verificare il runtime firmato, poi testare la negoziazione delle capacità, la proiezione degli eventi, i permessi e le domande in attesa, l’annullamento e l’arresto del backend. I cambiamenti di pin del consumatore appartengono al repository che consuma, dopo la pubblicazione dell’SDK di destinazione. Valida il pacchetto compilato in locale con pnpm --dir packages/sdk/js run test:consumer; questo controlla import pubblici, dichiarazioni e asset proto in una fixture isolata senza il pacchetto sorgente privato del runtime.

Integrazioni tra linguaggi

Questo pacchetto è l’SDK TypeScript/JavaScript di prima parte. Per Python, Go, Java, Rust o altri runtime, genera dal proto gRPC del repository oppure usa il confine CLI/runtime posseduto da quell’integrazione.

Migrazione da @ax-code/sdk 1.4.0

Il sottopercorso ./programmatic riesporta ancora la voce predefinita; trattalo come deprecato.

Licenza

Apache-2.0