SDK

Client JS type-safe per il server opencode.

L’SDK JS/TS di opencode fornisce un client type-safe per interagire con il server. Usalo per creare integrazioni e controllare opencode in modo programmatico.

Scopri di piu su come funziona il server. Per esempi, guarda i progetti creati dalla comunita.

Installa

Installa l’SDK da npm:

npm install @opencode-ai/sdk

Crea un client

Crea un’istanza di opencode:

import { createOpencode } from "@opencode-ai/sdk"

const { client } = await createOpencode()

Questo avvia sia un server sia un client

Opzioni

Opzione	Tipo	Descrizione	Predefinito
`hostname`	`string`	Hostname del server	`127.0.0.1`
`port`	`number`	Porta del server	`4096`
`signal`	`AbortSignal`	Segnale di abort per annullare	`undefined`
`timeout`	`number`	Timeout in ms per avvio server	`5000`
`config`	`Config`	Oggetto di configurazione	`{}`

Configurazione

Puoi passare un oggetto di configurazione per personalizzare il comportamento. L’istanza legge comunque opencode.json, ma puoi sovrascrivere o aggiungere configurazione inline:

import { createOpencode } from "@opencode-ai/sdk"

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    model: "anthropic/claude-3-5-sonnet-20241022",
  },
})

console.log(`Server running at ${opencode.server.url}`)

opencode.server.close()

Solo client

Se hai gia un’istanza di opencode in esecuzione, puoi creare un client per collegarti:

import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096",
})

Opzioni

Opzione	Tipo	Descrizione	Predefinito
`baseUrl`	`string`	URL del server	`http://localhost:4096`
`fetch`	`function`	Implementazione fetch custom	`globalThis.fetch`
`parseAs`	`string`	Metodo di parsing della risposta	`auto`
`responseStyle`	`string`	Stile di ritorno: `data` o `fields`	`fields`
`throwOnError`	`boolean`	Lancia errori invece di restituirli	`false`

Tipi

L’SDK include definizioni TypeScript per tutti i tipi API. Importale direttamente:

import type { Session, Message, Part } from "@opencode-ai/sdk"

Tutti i tipi sono generati dalla specifica OpenAPI del server e disponibili nel file dei tipi.

Errori

L’SDK puo lanciare errori che puoi intercettare e gestire:

try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("Failed to get session:", (error as Error).message)
}

Puoi richiedere un output JSON strutturato dal modello specificando un format con uno schema JSON. Il modello usera un tool StructuredOutput per restituire JSON validato che corrisponde al tuo schema.

Uso Base

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          company: { type: "string", description: "Company name" },
          founded: { type: "number", description: "Year founded" },
          products: {
            type: "array",
            items: { type: "string" },
            description: "Main products",
          },
        },
        required: ["company", "founded"],
      },
    },
  },
})

// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

Tipi di Formato Output

Tipo	Descrizione
`text`	Predefinito. Risposta di testo standard (nessun output strutturato)
`json_schema`	Restituisce JSON validato che corrisponde allo schema fornito

Formato Schema JSON

Quando usi type: 'json_schema', fornisci:

Campo	Tipo	Descrizione
`type`	`'json_schema'`	Richiesto. Specifica la modalita schema JSON
`schema`	`object`	Richiesto. Oggetto JSON Schema che definisce la struttura dell’output
`retryCount`	`number`	Opzionale. Numero di tentativi di validazione (default: 2)

Gestione Errori

Se il modello non riesce a produrre un output strutturato valido dopo tutti i tentativi, la risposta includera un StructuredOutputError:

if (result.data.info.error?.name === "StructuredOutputError") {
  console.error("Failed to produce structured output:", result.data.info.error.message)
  console.error("Attempts:", result.data.info.error.retries)
}

Best Practices

Fornisci descrizioni chiare nelle proprieta del tuo schema per aiutare il modello a capire quali dati estrarre
Usa required per specificare quali campi devono essere presenti
Mantieni gli schemi focalizzati - schemi annidati complessi potrebbero essere piu difficili da compilare correttamente per il modello
Imposta un retryCount appropriato - aumenta per schemi complessi, diminuisci per quelli semplici

API

L’SDK espone tutte le API del server tramite un client type-safe.

Globale

Metodo	Descrizione	Risposta
`global.health()`	Controlla stato e versione server	`{ healthy: true, version: string }`

Esempi

const health = await client.global.health()
console.log(health.data.version)

App

Metodo	Descrizione	Risposta
`app.log()`	Scrive una voce di log	`boolean`
`app.agents()`	Elenca tutti gli agenti	`Agent[]`

Esempi

// Write a log entry
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operation completed",
  },
})

// List available agents
const agents = await client.app.agents()

Progetto

Metodo	Descrizione	Risposta
`project.list()`	Elenca i progetti	`Project[]`
`project.current()`	Progetto corrente	`Project`

Esempi

// List all projects
const projects = await client.project.list()

// Get current project
const currentProject = await client.project.current()

Path

Metodo	Descrizione	Risposta
`path.get()`	Percorso corrente	`Path`

Esempi

// Get current path information
const pathInfo = await client.path.get()

Config

Metodo	Descrizione	Risposta
`config.get()`	Ottieni info config	`Config`
`config.providers()`	Elenca provider e modelli default	`{ providers:` `Provider[], default: { [key: string]: string } }`

Esempi

const config = await client.config.get()

const { providers, default: defaults } = await client.config.providers()

Sessioni

Metodo	Descrizione	Note
`session.list()`	Elenca le sessioni	Returns `Session[]`
`session.get({ path })`	Ottieni una sessione	Returns `Session`
`session.children({ path })`	Elenca sessioni figlie	Returns `Session[]`
`session.create({ body })`	Crea una sessione	Returns `Session`
`session.delete({ path })`	Elimina una sessione	Returns `boolean`
`session.update({ path, body })`	Aggiorna proprieta della sessione	Returns `Session`
`session.init({ path, body })`	Analizza app e crea `AGENTS.md`	Returns `boolean`
`session.abort({ path })`	Interrompe una sessione in corso	Returns `boolean`
`session.share({ path })`	Condivide la sessione	Returns `Session`
`session.unshare({ path })`	Rimuove la condivisione	Returns `Session`
`session.summarize({ path, body })`	Riassume la sessione	Returns `boolean`
`session.messages({ path })`	Elenca i messaggi della sessione	Returns `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Ottieni dettagli di un messaggio	Returns `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Invia un prompt	`body.noReply: true` returns UserMessage (solo contesto). Di default ritorna `AssistantMessage` con risposta AI. Supporta `body.outputFormat` per output strutturato
`session.command({ path, body })`	Invia un comando alla sessione	Returns `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Esegue un comando shell	Returns `AssistantMessage`
`session.revert({ path, body })`	Ripristina un messaggio	Returns `Session`
`session.unrevert({ path })`	Ripristina messaggi revertiti	Returns `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Risponde a una richiesta permessi	Returns `boolean`

Esempi

// Create and manage sessions
const session = await client.session.create({
  body: { title: "My session" },
})

const sessions = await client.session.list()

// Send a prompt message
const result = await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-3-5-sonnet-20241022" },
    parts: [{ type: "text", text: "Hello!" }],
  },
})

// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "You are a helpful assistant." }],
  },
})

File

Metodo	Descrizione	Risposta
`find.text({ query })`	Cerca testo nei file	Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Trova file e directory per nome	`string[]` (paths)
`find.symbols({ query })`	Trova simboli nel workspace	`Symbol[]`
`file.read({ query })`	Legge un file	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Stato dei file tracciati	`File[]`

find.files supporta alcuni campi query opzionali:

type: "file" or "directory"
directory: sovrascrive la root del progetto per la ricerca
limit: risultati massimi (1–200)

Esempi

// Search and read files
const textResults = await client.find.text({
  query: { pattern: "function.*opencode" },
})

const files = await client.find.files({
  query: { query: "*.ts", type: "file" },
})

const directories = await client.find.files({
  query: { query: "packages", type: "directory", limit: 20 },
})

const content = await client.file.read({
  query: { path: "src/index.ts" },
})

TUI

Metodo	Descrizione	Risposta
`tui.appendPrompt({ body })`	Aggiunge testo al prompt	`boolean`
`tui.openHelp()`	Apre la finestra help	`boolean`
`tui.openSessions()`	Apre il selettore sessioni	`boolean`
`tui.openThemes()`	Apre il selettore temi	`boolean`
`tui.openModels()`	Apre il selettore modelli	`boolean`
`tui.submitPrompt()`	Invia il prompt corrente	`boolean`
`tui.clearPrompt()`	Pulisce il prompt	`boolean`
`tui.executeCommand({ body })`	Esegue un comando	`boolean`
`tui.showToast({ body })`	Mostra una notifica toast	`boolean`

Esempi

// Control TUI interface
await client.tui.appendPrompt({
  body: { text: "Add this to prompt" },
})

await client.tui.showToast({
  body: { message: "Task completed", variant: "success" },
})

Autenticazione

Metodo	Descrizione	Risposta
`auth.set({ ... })`	Imposta credenziali auth	`boolean`

Esempi

await client.auth.set({
  path: { id: "anthropic" },
  body: { type: "api", key: "your-api-key" },
})

Eventi

Metodo	Descrizione	Risposta
`event.subscribe()`	Stream di server-sent events	Stream di server-sent events

Esempi

// Listen to real-time events
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Event:", event.type, event.properties)
}