Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал

Пакет @defai-digital/ax-code-sdk

SDK на TypeScript для встраивания среды выполнения агента написания кода AX Code в ваши приложения.

Используйте его, чтобы наблюдать за совместимой подписанной средой выполнения AX Code через типизированные границы headless или gRPC, потреблять потоковые события, проецировать состояние сеанса и проверять интеграции приложения. Узлы исходного кода, которые намеренно предоставляют закрытый пакет среды выполнения, могут также использовать внутрипроцессный адаптер createAgent().

Установка

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

Нужен Node.js 26+ (или Deno с совместимостью Node). Более старые версии Node.js не поддерживаются. Помощники жизненного цикла headless и gRPC ожидают подписанный исполняемый файл ax-code в PATH либо абсолютный путь, переданный как binary. Версии SDK и среды выполнения независимы. Прежде чем включать функции приложения, проверьте протокол возможностей среды выполнения. Одной проверки версии SDK для совместимости среды недостаточно.

Имя пакета рабочей области @ax-code/sdk закрыто для этого монорепозитория. Публичные потребители всегда устанавливают @defai-digital/ax-code-sdk из JSR.

Миграция API отчётов

AX Code 7.24.1 заменяет отчёт графа DRE на Run Report. Интеграции отчётов должны использовать ax-code run-report и маршруты HTTP /run-report. Старая команда dre-graph и маршруты /dre-graph удалены. Сгенерированные операции SDK теперь getRunReportSessionSessionId и getRunReportSessionSessionIdFingerprint и заменяют соответствующие операции getDreGraph.

Обновляйте интеграцию отчётов и среду выполнения вместе. Другие поверхности интеграции по-прежнему требуют собственных проверок возможностей среды выполнения.

Выбор поверхности интеграции

Публичным приложениям следует использовать headless или grpc с совместимой подписанной средой выполнения AX Code. HTTP/OpenAPI остаётся за этими SDK как запасной слой и слой диагностики. Устаревшие подпути @defai-digital/ax-code-sdk/v2 сохраняются ради совместимости среды выполнения. Новым интеграциям не следует с них начинать.

createAgent() загружает закрытый исходный пакет ax-code в момент вызова. Среда выполнения в JSR не публикуется.

Быстрый старт (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()
}

Настольные узлы могут передать проверенный абсолютный путь как binary. См. example/headless-app.ts для цикла приложения на проекции.

Сервер headless

startHeadlessBackend порождает ax-code serve на случайном порту loopback, создаёт одноразовые учётные данные, ждёт /global/health и возвращает дескриптор. close() отправляет SIGTERM, затем 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 и applyHeadlessProjectionEvent — чистый TypeScript. Интерфейсам приложений следует считать первичным состоянием permission, question, session_diff, todo, session_status и session_error. Автономные ответы включаются явно. Наблюдаемые приложения должны отрисовывать ожидающие запросы прав и вопросов.

Автономная проекция оставляет ожидающими права isolation_escalation, bash_destructive, ops_approve, webmcp, hook и computer, а также любой запрос, чьи метаданные задают requireInteractive: true. Потребители должны получить явный человеческий ответ на эти запросы.

gRPC и собственное настольное приложение

Используйте @defai-digital/ax-code-sdk/grpc, когда собственный узел уже владеет транспортом (preload 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() — та же область JavaScript, с AbortSignal и асинхронными итерируемыми.
• createAxCodeGrpcClientFromNativeHandlers() — привязывает имена методов к типизированным обработчикам. requireHandlers сразу завершается ошибкой при пропусках.
• startAxCodeGrpcNodeHttp2Server() из @defai-digital/ax-code-sdk/grpc/node — открывает тот же мост как локальную конечную точку gRPC на HTTP/2.
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods() — канонический каталог методов для списков разрешений и имён proto.

createAxCodeGrpcClientFromHttp() работает только на loopback. Ресурс proto — packages/sdk/proto/ax_code/v1/headless.proto и разрешается во время выполнения через resolveAxCodeGrpcProtoUrl().

Агент в процессе (только узлы исходного кода)

Этот путь требует закрытого пакета среды выполнения ax-code. Это не публичная граница интеграции приложений.

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

Аутентификация определяется автоматически из переменных окружения, внедряется через auth: { provider, apiKey } или берётся из 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`)
}

Другие примеры: example/programmatic.ts.

Тестирование

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

Совместимость версий

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

Управление запросами и направление

SDK 2.6 добавляет необязательные средства управления к запросам headless. Существующие вызовы сохраняют поведение. Срок по умолчанию не навязывается.

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) открывает атомарную конечную точку поставленного в очередь продолжения. Результат generation_not_active оставляет строку неизменной. SDK возвращает квитанции и причины отказа дословно. accepted означает допуск к более поздней границе цикла. applied означает устойчивый допуск на этой границе, а завершение у провайдера по-прежнему отдельно. Квитанции локальны для процесса и ограничены, поэтому их отсутствие после перезапуска не доказывает, что исправление никогда не применялось.

requestOptions задаёт значения по умолчанию для всех удобных запросов и команд headless, включая операции рабочего процесса и очереди задач. Основные методы сеанса и команд и направление принимают переопределения на вызов. timeoutMs: 0 отключает срок по умолчанию. Подписки используют собственный signal, а client.client сохраняет средства управления сгенерированного клиента. Пользовательский HeadlessTransport получает сигнал и должен освободить ожидающие ресурсы при прерывании.

Отмена HTTP и IPC останавливает локальное ожидание. Уже отправленное изменение всё ещё может выполниться. Сверьте состояние сеанса и очереди, прежде чем действовать дальше. Ни один транспорт не повторяет изменения. Сроки возбуждают TimeoutError. Прерывания вызывающего сохраняют причину сигнала. Неуспешные ответы HTTP и IPC возбуждают HeadlessRequestError с status, body, method и path. Кадры протокольной ошибки IPC сохраняют IpcTransportError.

Совместимость среды выполнения и обновление с SDK 2.5

Текущая базовая линия сгенерированного контракта — исходный код AX Code v7.23.0. SDK 2.6 не выводит необъявленные функции из версии среды выполнения. Текущий каталог возможностей не объявляет направление отдельно. Проверьте конечную точку чтения, прежде чем предлагать направление, и обрабатывайте ошибки неподдерживаемого маршрута. SDK 2.6 сохраняет существующие точки входа сгенерированного клиента и headless. Новые метаданные ошибок ответа и средства управления запросами аддитивны. Код, перехватывающий Error, продолжает работать.

Приложениям, обновляющим более старые закрепления, следует сначала проверить подписанную среду выполнения, затем проверить согласование возможностей, проекцию событий, ожидающие права и вопросы, отмену и остановку сервера. Смена закрепления потребителя принадлежит репозиторию потребителя после публикации целевого SDK. Проверьте собранный пакет локально через pnpm --dir packages/sdk/js run test:consumer. Это проверяет публичные импорты, объявления и ресурсы proto в изолированной оснастке без закрытого исходного пакета среды выполнения.

Интеграции на других языках

Этот пакет — собственный SDK на TypeScript и JavaScript. Для Python, Go, Java, Rust или других сред выполнения генерируйте код из proto gRPC репозитория либо используйте границу CLI и среды выполнения, которой владеет эта интеграция.

Миграция с @ax-code/sdk 1.4.0

Подпуть ./programmatic по-прежнему реэкспортирует вход по умолчанию. Считайте его устаревшим.

Лицензия

Apache-2.0