SDK

Cliente de tipo seguro en JS para servidor de dropstone.

El SDK de JS/TS de Dropstone proporciona un cliente de tipo seguro para interactuar con un agente de Dropstone local. Inicia dropstone serve como un subproceso y te proporciona un cliente HTTP tipado apuntando a él.

¿Necesitas acceso a API sin interfaz en CI?:

Para uso puramente programático (tuberías de CI, automatización, serverless), prefiere la API HTTP con una DROPSTONE_API_KEY. El SDK en esta página está diseñado para incrustar el agente interactivo en un proceso de Node donde el binario de CLI está instalado junto a él.

Consulta la página Server para saber cómo funciona la API HTTP subyacente.

Instalar

Instala el SDK desde npm:

npm install @blankline/dropstone-sdk

Crear cliente

Crea una instancia de dropstone:

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

const { client } = await createDropstone()

Esto inicia tanto un servidor como un cliente

Opciones

Opción	Tipo	Descripción	Predeterminado
`hostname`	`string`	Nombre de host del servidor	`127.0.0.1`
`port`	`number`	Puerto del servidor	`4096`
`signal`	`AbortSignal`	Señal de cancelación	`undefined`
`timeout`	`number`	Tiempo de espera en ms	`5000`
`config`	`Config`	Objeto de configuración	`{}`

Config

Puedes pasar un objeto de configuración para personalizar el comportamiento. La instancia sigue recogiendo tu dropstone.json, pero puedes anular o agregar configuración en línea:

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 cliente

Si ya tienes una instancia de dropstone en ejecución, puedes crear una instancia de cliente para conectarte a ella:

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

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

Opciones

Opción	Tipo	Descripción	Predeterminado
`baseUrl`	`string`	URL del servidor	`http://localhost:4096`
`fetch`	`function`	Implementación de fetch personal	`globalThis.fetch`
`parseAs`	`string`	Método de análisis de respuesta	`auto`
`responseStyle`	`string`	Estilo de retorno: `data` o `fields`	`fields`
`throwOnError`	`boolean`	Lanzar errores en lugar de retornar	`false`

Tipos

El SDK incluye definiciones de TypeScript para todos los tipos de API. Impórtalos directamente:

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

Todos los tipos se generan a partir de la especificación OpenAPI del servidor, por lo que los nombres que ves en TypeScript se asignan uno a uno a las formas de solicitud y respuesta del servidor.

Errores

El SDK puede lanzar errores que puedes capturar y manejar:

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

Salida Estructurada

Puedes solicitar salida JSON estructurada del modelo especificando un format con un esquema JSON. El modelo utilizará una herramienta StructuredOutput para devolver JSON validado que coincida con tu esquema.

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 Salida

Tipo	Descripción
`text`	Predeterminado. Respuesta de texto estándar (sin salida estructurada)
`json_schema`	Devuelve JSON validado que coincide con el esquema proporcionado

Formato de Esquema JSON

Cuando uses type: 'json_schema', proporciona:

Campo	Tipo	Descripción
`type`	`'json_schema'`	Requerido. Especifica el modo de esquema JSON
`schema`	`object`	Requerido. Objeto de esquema JSON que define la estructura de salida
`retryCount`	`number`	Opcional. Número de reintentos de validación (predeterminado: 2)

Manejo de Errores

Si el modelo no produce salida estructurada válida después de todos los reintentos, la respuesta incluirá 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)
}

Mejores Prácticas

Proporciona descripciones claras en las propiedades de tu esquema para ayudar al modelo a entender qué datos extraer
Usa required para especificar qué campos deben estar presentes
Mantén esquemas enfocados - los esquemas anidados complejos pueden ser más difíciles de llenar correctamente para el modelo
Establece retryCount apropiado - aumenta para esquemas complejos, disminuye para esquemas simples

APIs

El SDK expone todas las APIs del servidor a través de un cliente de tipo seguro.

Global

Método	Descripción	Respuesta
`global.health()`	Verificar salud y versión del servidor	`{ healthy: true, version: string }`

Ejemplos

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

App

Método	Descripción	Respuesta
`app.log()`	Escribir una entrada de registro	`boolean`
`app.agents()`	Listar todos los agentes disponibles	`Agent[]`

Ejemplos

// 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	Descripción	Respuesta
`project.list()`	Listar todos los proyectos	`Project[]`
`project.current()`	Obtener proyecto actual	`Project`

Ejemplos

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

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

Path

Método	Descripción	Respuesta
`path.get()`	Obtener ruta actual	`Path`

Ejemplos

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

Config

Método	Descripción	Respuesta
`config.get()`	Obtener información de configuración	`Config`

Ejemplos

const config = await client.config.get()

Sessions

Método	Descripción	Notas
`session.list()`	Listar sesiones	Devuelve `Session[]`
`session.get({ path })`	Obtener sesión	Devuelve `Session`
`session.children({ path })`	Listar sesiones secundarias	Devuelve `Session[]`
`session.create({ body })`	Crear sesión	Devuelve `Session`
`session.delete({ path })`	Eliminar sesión	Devuelve `boolean`
`session.update({ path, body })`	Actualizar propiedades de sesión	Devuelve `Session`
`session.init({ path, body })`	Analizar aplicación y crear `AGENTS.md`	Devuelve `boolean`
`session.abort({ path })`	Abortar una sesión en ejecución	Devuelve `boolean`
`session.summarize({ path, body })`	Resumir sesión	Devuelve `boolean`
`session.messages({ path })`	Listar mensajes en una sesión	Devuelve `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Obtener detalles del mensaje	Devuelve `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Enviar mensaje de solicitud	`body.noReply: true` devuelve UserMessage (solo contexto). Predeterminado devuelve `AssistantMessage` con respuesta de IA. Admite `body.outputFormat` para salida estructurada
`session.command({ path, body })`	Enviar comando a sesión	Devuelve `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Ejecutar un comando de shell	Devuelve `AssistantMessage`
`session.revert({ path, body })`	Revertir un mensaje	Devuelve `Session`
`session.unrevert({ path })`	Restaurar mensajes revertidos	Devuelve `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Responder a una solicitud de permiso	Devuelve `boolean`

Ejemplos

// 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	Descripción	Respuesta
`find.text({ query })`	Buscar texto en archivos	Array de objetos de coincidencia con `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Encontrar archivos y directorios por nombre	`string[]` (rutas)
`find.symbols({ query })`	Encontrar símbolos del espacio de trabajo	`Symbol[]`
`file.read({ query })`	Leer un archivo	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Obtener estado de archivos rastreados	`File[]`

find.files admite algunos campos de consulta opcionales:

type: "file" o "directory"
directory: anular la raíz del proyecto para la búsqueda
limit: máximo de resultados (1–200)

Ejemplos

// 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	Descripción	Respuesta
`auth.set({ ... })`	Establecer credenciales de autenticación	`boolean`

Ejemplos

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

Events

Método	Descripción	Respuesta
`event.subscribe()`	Flujo de eventos enviados por servidor	Flujo de eventos enviados por servidor

Ejemplos

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

Crear cliente

Opciones

Config

Solo cliente

Opciones

Tipos

Errores

Salida Estructurada

Uso Básico

Tipos de Formato de Salida

Formato de Esquema JSON

Manejo de Errores

Mejores Prácticas

APIs

Global

Ejemplos

App

Ejemplos

Project

Ejemplos

Path

Ejemplos

Config

Ejemplos

Sessions

Ejemplos

Files

Ejemplos

Auth

Ejemplos

Events

Ejemplos

En esta página