SDK

Cliente JS type-safe para servidor dropstone.

O SDK JS/TS do Dropstone fornece um cliente type-safe para interagir com um agente Dropstone local. Ele inicia dropstone serve como um subprocess e oferece um cliente HTTP tipado apontando para ele.

Precisa de acesso à API headless em CI?:

Para uso puramente programático (pipelines de CI, automação, serverless), prefira a HTTP API com uma DROPSTONE_API_KEY. O SDK nesta página é destinado para incorporar o agente interativo em um processo Node onde o binário da CLI está instalado junto.

Veja a página Server para entender como a API HTTP subjacente funciona.

Instalar

Instale o SDK do npm:

npm install @blankline/dropstone-sdk

Criar cliente

Crie uma instância do dropstone:

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

const { client } = await createDropstone()

Isso inicia tanto um servidor quanto um cliente

Opções

Opção	Tipo	Descrição	Padrão
`hostname`	`string`	Hostname do servidor	`127.0.0.1`
`port`	`number`	Porta do servidor	`4096`
`signal`	`AbortSignal`	Sinal de aborto para cancelamento	`undefined`
`timeout`	`number`	Timeout em ms para iniciar servidor	`5000`
`config`	`Config`	Objeto de configuração	`{}`

Config

Você pode passar um objeto de configuração para personalizar o comportamento. A instância ainda pega seu dropstone.json, mas você pode sobrescrever ou adicionar configuração 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()

Apenas cliente

Se você já tem uma instância do dropstone em execução, você pode criar uma instância de cliente para se conectar a ela:

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

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

Opções

Opção	Tipo	Descrição	Padrão
`baseUrl`	`string`	URL do servidor	`http://localhost:4096`
`fetch`	`function`	Implementação fetch customizada	`globalThis.fetch`
`parseAs`	`string`	Método de parsing de resposta	`auto`
`responseStyle`	`string`	Estilo de retorno: `data` ou `fields`	`fields`
`throwOnError`	`boolean`	Lançar erros em vez de retornar	`false`

Tipos

O SDK inclui definições TypeScript para todos os tipos de API. Importe-os diretamente:

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

Todos os tipos são gerados a partir da especificação OpenAPI do servidor, então os nomes que você vê em TypeScript mapeiam um-para-um para as formas de servidor de requisição e resposta.

Erros

O SDK pode lançar erros que você pode capturar e tratar:

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

Saída Estruturada

Você pode solicitar saída JSON estruturada do modelo especificando um format com um schema JSON. O modelo usará uma ferramenta StructuredOutput para retornar JSON validado correspondendo ao seu schema.

Uso Básico

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

// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Dropstone", founded: 2024, products: ["Dropstone CLI"] }

Tipos de Formato de Saída

Tipo	Descrição
`text`	Padrão. Resposta de texto padrão (sem saída estruturada)
`json_schema`	Retorna JSON validado correspondendo ao schema fornecido

Formato JSON Schema

Ao usar type: 'json_schema', forneça:

Campo	Tipo	Descrição
`type`	`'json_schema'`	Obrigatório. Especifica modo de schema JSON
`schema`	`object`	Obrigatório. Objeto JSON Schema definindo a estrutura de saída
`retryCount`	`number`	Opcional. Número de tentativas de validação (padrão: 2)

Tratamento de Erros

Se o modelo falhar em produzir saída estruturada válida após todas as tentativas, a resposta incluirá um 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)
}

Melhores Práticas

Forneça descrições claras nas propriedades do seu schema para ajudar o modelo a entender quais dados extrair
Use required para especificar quais campos devem estar presentes
Mantenha schemas focados - schemas aninhados complexos podem ser mais difíceis para o modelo preencher corretamente
Defina retryCount apropriado - aumente para schemas complexos, diminua para simples

APIs

O SDK expõe todas as APIs do servidor através de um cliente type-safe.

Global

Método	Descrição	Resposta
`global.health()`	Verificar saúde e versão do servidor	`{ healthy: true, version: string }`

Exemplos

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

App

Método	Descrição	Resposta
`app.log()`	Escrever uma entrada de log	`boolean`
`app.agents()`	Listar todos os agentes disponíveis	`Agent[]`

Exemplos

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

Project

Método	Descrição	Resposta
`project.list()`	Listar todos os projetos	`Project[]`
`project.current()`	Obter projeto atual	`Project`

Exemplos

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

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

Path

Método	Descrição	Resposta
`path.get()`	Obter caminho atual	`Path`

Exemplos

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

Config

Método	Descrição	Resposta
`config.get()`	Obter informações de config	`Config`

Exemplos

const config = await client.config.get()

Sessions

Método	Descrição	Notas
`session.list()`	Listar sessões	Retorna `Session[]`
`session.get({ path })`	Obter sessão	Retorna `Session`
`session.children({ path })`	Listar sessões filhas	Retorna `Session[]`
`session.create({ body })`	Criar sessão	Retorna `Session`
`session.delete({ path })`	Deletar sessão	Retorna `boolean`
`session.update({ path, body })`	Atualizar propriedades da sessão	Retorna `Session`
`session.init({ path, body })`	Analisar app e criar `AGENTS.md`	Retorna `boolean`
`session.abort({ path })`	Abortar uma sessão em execução	Retorna `boolean`
`session.summarize({ path, body })`	Resumir sessão	Retorna `boolean`
`session.messages({ path })`	Listar mensagens em uma sessão	Retorna `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Obter detalhes da mensagem	Retorna `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Enviar mensagem de prompt	`body.noReply: true` retorna UserMessage (apenas contexto). Padrão retorna `AssistantMessage` com resposta de IA. Suporta `body.outputFormat` para saída estruturada
`session.command({ path, body })`	Enviar comando para sessão	Retorna `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Executar um comando shell	Retorna `AssistantMessage`
`session.revert({ path, body })`	Reverter uma mensagem	Retorna `Session`
`session.unrevert({ path })`	Restaurar mensagens revertidas	Retorna `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Responder a uma solicitação de permissão	Retorna `boolean`

Exemplos

// 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: "dropstone", modelID: "dropstone-pro" },
    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." }],
  },
})

Files

Método	Descrição	Resposta
`find.text({ query })`	Pesquisar texto em arquivos	Array de objetos de correspondência com `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Encontrar arquivos e diretórios por nome	`string[]` (caminhos)
`find.symbols({ query })`	Encontrar símbolos do workspace	`Symbol[]`
`file.read({ query })`	Ler um arquivo	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Obter status para arquivos rastreados	`File[]`

find.files suporta alguns campos de query opcionais:

type: "file" ou "directory"
directory: sobrescrever a raiz do projeto para a busca
limit: máximo de resultados (1–200)

Exemplos

// Search and read files
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

Método	Descrição	Resposta
`auth.set({ ... })`	Definir credenciais de autenticação	`boolean`

Exemplos

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

Events

Método	Descrição	Resposta
`event.subscribe()`	Fluxo de eventos enviados pelo servidor	Fluxo de eventos enviados pelo servidor

Exemplos

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

Server Mode

HTTP API

SDK

Instalar

Criar cliente

Opções

Config

Apenas cliente

Opções

Tipos

Erros

Saída Estruturada

Uso Básico

Tipos de Formato de Saída

Formato JSON Schema

Tratamento de Erros

Melhores Práticas

APIs

Global

Exemplos

App

Exemplos

Project

Exemplos

Path

Exemplos

Config

Exemplos

Sessions

Exemplos

Files

Exemplos

Auth

Exemplos

Events

Exemplos

Nesta página