SDK

Client type-safe JS per il server dropstone.

L'SDK JS/TS di Dropstone fornisce un client type-safe per interagire con un agente Dropstone locale. Avvia dropstone serve come sottoprocesso e ti fornisce un client HTTP tipizzato che punta ad esso.

Hai bisogno di accesso API headless in CI?:

Per un uso puramente programmatico (pipeline CI, automazione, serverless), preferisci l'HTTP API con una DROPSTONE_API_KEY. L'SDK in questa pagina è destinato all'integrazione dell'agente interattivo in un processo Node dove il binario CLI è installato insieme.

Vedi la pagina Server per come funziona l'API HTTP sottostante.

Installa

Installa l'SDK da npm:

npm install @blankline/dropstone-sdk

Crea client

Crea un'istanza di dropstone:

import { createDropstone } from "@blankline/dropstone-sdk"

const { client } = await createDropstone()

Questo avvia sia un server che 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 interruzione	`undefined`
`timeout`	`number`	Timeout in ms per l'avvio server	`5000`
`config`	`Config`	Oggetto di configurazione	`{}`

Config

Puoi passare un oggetto di configurazione per personalizzare il comportamento. L'istanza raccoglie comunque il tuo dropstone.json, ma puoi sovrascrivere o aggiungere configurazione inline:

import { createDropstone } from "@blankline/dropstone-sdk"

const dropstone = await createDropstone({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    model: "dropstone/dropstone-pro",
  },
})

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

dropstone.server.close()

Solo client

Se hai già un'istanza di dropstone in esecuzione, puoi creare un'istanza client per connetterti ad essa:

import { createDropstoneClient } from "@blankline/dropstone-sdk"

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

Opzioni

Opzione	Tipo	Descrizione	Predefinito
`baseUrl`	`string`	URL del server	`http://localhost:4096`
`fetch`	`function`	Implementazione fetch personalizzata	`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 di API. Importali direttamente:

import type { Session, Message, Part } from "@blankline/dropstone-sdk"

Tutti i tipi sono generati dalla specifica OpenAPI del server, quindi i nomi che vedi in TypeScript corrispondono uno-a-uno alle forme di richiesta e risposta del server.

Errori

L'SDK può lanciare errori che puoi catturare e gestire:

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

Output Strutturato

Puoi richiedere output JSON strutturato dal modello specificando un format con uno schema JSON. Il modello utilizzerà uno strumento StructuredOutput per restituire JSON validato che corrisponda al tuo schema.

Utilizzo di Base

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Research Dropstone 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"],
      },
    },
  },
})

// Accedi all'output strutturato
console.log(result.data.info.structured_output)
// { company: "Dropstone", founded: 2024, products: ["Dropstone CLI"] }

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 JSON Schema

Quando usi type: 'json_schema', fornisci:

Campo	Tipo	Descrizione
`type`	`'json_schema'`	Obbligatorio. Specifica la modalità JSON schema
`schema`	`object`	Obbligatorio. Oggetto JSON Schema che definisce la struttura dell'output
`retryCount`	`number`	Opzionale. Numero di tentativi di validazione (predefinito: 2)

Gestione degli Errori

Se il modello non riesce a produrre output strutturato valido dopo tutti i tentativi, la risposta includerà 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 proprietà dello 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 più 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 attraverso un client type-safe.

Global

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

Esempi

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

App

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

Esempi

// Scrivi una voce di log
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operation completed",
  },
})

// Elenca gli agenti disponibili
const agents = await client.app.agents()

Project

Metodo	Descrizione	Risposta
`project.list()`	Elenca tutti i progetti	`Project[]`
`project.current()`	Ottieni il progetto corrente	`Project`

Esempi

// Elenca tutti i progetti
const projects = await client.project.list()

// Ottieni il progetto corrente
const currentProject = await client.project.current()

Path

Metodo	Descrizione	Risposta
`path.get()`	Ottieni il percorso corrente	`Path`

Esempi

// Ottieni le informazioni del percorso corrente
const pathInfo = await client.path.get()

Config

Metodo	Descrizione	Risposta
`config.get()`	Ottieni le informazioni di configurazione	`Config`

Esempi

const config = await client.config.get()

Sessions

Metodo	Descrizione	Note
`session.list()`	Elenca le sessioni	Restituisce `Session[]`
`session.get({ path })`	Ottieni la sessione	Restituisce `Session`
`session.children({ path })`	Elenca le sessioni figlie	Restituisce `Session[]`
`session.create({ body })`	Crea una sessione	Restituisce `Session`
`session.delete({ path })`	Elimina una sessione	Restituisce `boolean`
`session.update({ path, body })`	Aggiorna le proprietà della sessione	Restituisce `Session`
`session.init({ path, body })`	Analizza l'app e crea `AGENTS.md`	Restituisce `boolean`
`session.abort({ path })`	Interrompi una sessione in esecuzione	Restituisce `boolean`
`session.summarize({ path, body })`	Riassumi la sessione	Restituisce `boolean`
`session.messages({ path })`	Elenca i messaggi in una sessione	Restituisce `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Ottieni i dettagli del messaggio	Restituisce `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Invia un messaggio di prompt	`body.noReply: true` restituisce UserMessage (solo contesto). Predefinito restituisce `AssistantMessage` con risposta AI. Supporta `body.outputFormat` per output strutturato
`session.command({ path, body })`	Invia un comando alla sessione	Restituisce `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Esegui un comando shell	Restituisce `AssistantMessage`
`session.revert({ path, body })`	Ripristina un messaggio	Restituisce `Session`
`session.unrevert({ path })`	Ripristina i messaggi ripristinati	Restituisce `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Rispondi a una richiesta di permesso	Restituisce `boolean`

Esempi

// Crea e gestisci le sessioni
const session = await client.session.create({
  body: { title: "My session" },
})

const sessions = await client.session.list()

// Invia un messaggio di prompt
const result = await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "dropstone", modelID: "dropstone-pro" },
    parts: [{ type: "text", text: "Hello!" }],
  },
})

// Inietta contesto senza attivare la risposta AI (utile per i plugin)
await client.session.prompt({
  path: { id: session.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "You are a helpful assistant." }],
  },
})

Files

Metodo	Descrizione	Risposta
`find.text({ query })`	Cerca testo nei file	Array di oggetti di corrispondenza con `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Trova file e directory per nome	`string[]` (percorsi)
`find.symbols({ query })`	Trova simboli dell'area di lavoro	`Symbol[]`
`file.read({ query })`	Leggi un file	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Ottieni lo stato dei file tracciati	`File[]`

find.files supporta alcuni campi di query opzionali:

type: "file" o "directory"
directory: sovrascrivi la radice del progetto per la ricerca
limit: risultati massimi (1–200)

Esempi

// Cerca e leggi i file
const textResults = await client.find.text({
  query: { pattern: "function.*dropstone" },
})

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

Auth

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

Esempi

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

Events

Metodo	Descrizione	Risposta
`event.subscribe()`	Flusso di eventi inviati dal server	Flusso di eventi inviati dal server

Esempi

// Ascolta gli eventi in tempo reale
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Event:", event.type, event.properties)
}

Server Mode

HTTP API

SDK

Installa

Crea client

Opzioni

Config

Solo client

Opzioni

Tipi

Errori

Output Strutturato

Utilizzo di Base

Tipi di Formato Output

Formato JSON Schema

Gestione degli Errori

Best Practices

API

Global

Esempi

App

Esempi

Project

Esempi

Path

Esempi

Config

Esempi

Sessions

Esempi

Files

Esempi

Auth

Esempi

Events

Esempi

In questa pagina