SDK do Dropstone

O SDK JS/TS do Dropstone fornece um cliente com tipagem segura para interagir com o runtime do agente Dropstone. Ele inicia o dropstone serve como um subprocesso e fornece um cliente HTTP tipado apontando para ele. Como ele executa o mesmo agente local que a CLI usa, cada sessão do SDK herda a memória da sua conta — ensine uma vez na CLI, no chat ou no SDK e todas as superfícies já saberão (veja Memória (Continuity)).

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

Instalação

Instale o SDK a partir do npm:

npm install @blankline/dropstone-sdk

Cliente headless de API

Para pipelines de CI, automação e serverless, você não precisa da CLI. Use o cliente headless, que fala diretamente com a API HTTP do Dropstone usando uma chave de API:

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

// Lê DROPSTONE_API_KEY do ambiente automaticamente.
const dropstone = createDropstoneApi()

const resp = await dropstone.chat.completions.create({
  model: "dropstone-fast", // ou "dropstone-pro" / "dropstone-heavy"
  messages: [{ role: "user", content: "Escreva um haicai sobre depuração." }],
})

console.log(resp.choices[0].message.content)
console.log("Custo: $" + resp.usage?.cost) // valor cobrado, em USD

Obter uma chave de API

1. Entre em dropstone.io/dashboard.
2. Abra Configurações → API em dropstone.io/dashboard/settings e crie uma chave — ela se parece com dsk_live_<43 caracteres>.
3. Defina-a como uma variável de ambiente (ou passe apiKey para createDropstoneApi):

export DROPSTONE_API_KEY=dsk_live_...

O streaming funciona da mesma forma, e o cliente é compatível com OpenAI — você pode apontar o SDK da OpenAI para a URL base do Dropstone:

const stream = await dropstone.chat.completions.create({
  model: "dropstone-fast",
  stream: true,
  messages: [{ role: "user", content: "Conte até 5." }],
})

for await (const chunk of stream) {
  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "")
}

Veja a página da API HTTP para a referência completa.

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. Cada método do SDK retorna { data, request, response }, então acesse o payload via .data.

Opções

Configuração

Você pode passar um objeto de configuração para personalizar o comportamento. A instância ainda capta o seu dropstone.json, mas você pode substituir 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(`Servidor rodando em ${dropstone.server.url}`)

dropstone.server.close()

Memória (Continuity)

O Dropstone mantém uma memória persistente por conta. Chamamos isso de Continuity — uma memória entre superfícies compartilhada pela CLI, chat, VS Code e SDK. Ensine uma vez em qualquer lugar e todas as superfícies já saberão.

As sessões que você executa pelo SDK usam a mesma memória de conta da CLI. O que você ensina à CLI já é conhecido pelas sessões do SDK, e o que uma sessão do SDK registra fica disponível de volta na CLI e no chat. A cada turno, o agente recupera automaticamente a memória relevante antes de responder, para não reaprender o que já sabe.

O agente do SDK também pode ler e escrever memória diretamente, com as mesmas ferramentas da CLI:

Exemplo

Declare uma preferência a partir do código e ela será registrada da mesma forma que seria na CLI — visível na CLI e no chat depois:

const { client } = await createDropstone()

const session = await client.session.create({ body: { title: "Ensinar memória" } })

await client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Lembre-se disso como uma regra permanente: use sempre bun, não npm." }],
  },
})

Continuity vs AGENTS.md

O AGENTS.md é um arquivo de projeto que você envia para o Git para convenções de equipe — estável, com escopo no repositório e compartilhado com qualquer pessoa que o clone. Continuity é a sua memória privada de conta: o que você ensina na CLI, no chat ou no SDK acompanha sua conta entre superfícies e projetos. Eles resolvem problemas diferentes e funcionam melhor juntos — regras de projeto no AGENTS.md, memória pessoal entre superfícies no Continuity. Veja Regras e Memória.

O que é lembrado

A memória armazena apenas as regras e os fatos que você ensina explicitamente — preferências, convenções e correções que valem a pena carregar entre sessões. Ela é distinta do contexto efêmero de uma única sessão, que não é mantido após o término da sessão.

Veja a página Memória para saber como o Dropstone decide o que manter.

Somente cliente

Se você já tem uma instância do dropstone em execução, 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

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ê no TypeScript correspondem um a um às formas de solicitação e resposta do servidor.

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("Falha ao obter a sessão:", (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 que corresponde ao seu schema.

Uso básico

const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Pesquise o Dropstone e forneça informações da empresa" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          company: { type: "string", description: "Nome da empresa" },
          founded: { type: "number", description: "Ano de fundação" },
          products: {
            type: "array",
            items: { type: "string" },
            description: "Principais produtos",
          },
        },
        required: ["company", "founded"],
      },
    },
  },
})

// Acesse a saída estruturada
console.log(result.data.info.structured_output)
// { company: "Dropstone", founded: 2024, products: ["Dropstone CLI"] }

Tipos de formato de saída

Formato do schema JSON

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

Tratamento de erros

Se o modelo falhar ao 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("Falha ao produzir saída estruturada:", result.data.info.error.message)
  console.error("Tentativas:", result.data.info.error.retries)
}

Melhores práticas

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

APIs

O SDK expõe todas as APIs do servidor por meio de um cliente com tipagem segura.

Global

Exemplos

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

App

Exemplos

// Escrever uma entrada de log
await client.app.log({
  body: {
    service: "my-app",
    level: "info",
    message: "Operação concluída",
  },
})

// Listar agentes disponíveis
const agents = await client.app.agents()

Projeto

Exemplos

// Listar todos os projetos
const projects = await client.project.list()

// Obter o projeto atual
const currentProject = await client.project.current()

Caminho

Exemplos

// Obter informações do caminho atual
const pathInfo = await client.path.get()

Configuração

Exemplos

const config = await client.config.get()

Sessões

Exemplos

// Criar e gerenciar sessões
const session = await client.session.create({
  body: { title: "Minha sessão" },
})

const sessions = await client.session.list()

// Enviar uma mensagem de prompt
const result = await client.session.prompt({
  path: { id: session.data.id },
  body: {
    model: { providerID: "dropstone", modelID: "dropstone-pro" },
    parts: [{ type: "text", text: "Olá!" }],
  },
})

// Injetar contexto sem acionar resposta da IA (útil para plugins)
await client.session.prompt({
  path: { id: session.data.id },
  body: {
    noReply: true,
    parts: [{ type: "text", text: "Você é um assistente útil." }],
  },
})

Arquivos

find.files suporta alguns campos de consulta opcionais:

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

Exemplos

// Buscar e ler arquivos
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" },
})

Autenticação

Exemplos

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

Eventos

Exemplos

// Ouvir eventos em tempo real
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Evento:", event.type, event.properties)
}

API v2

O SDK inclui uma superfície v1 estável (usada nos exemplos acima) e uma superfície v2 que espelha o contrato mais recente do Effect HttpApi. Prefira v2 para novas integrações:

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

const { client, server } = await createDropstone()
// v2 expõe uma hierarquia de recursos mais rica: workspace, worktree, file, find, etc.
const files = await client.file.list({ path: "src" })

A superfície v1 é mantida para compatibilidade com versões anteriores. Novos endpoints só são adicionados na v2.