@factory/droid-sdk

The Factory TypeScript SDK lets applications run Droid, continue conversations, stream work, control tools, and connect to a running Droid daemon.

Installation

npm install @factory/droid-sdk

The SDK requires Node.js 18 or later.

Entrypoints

By default, Node session APIs start the droid CLI from PATH and read FACTORY_API_KEY. A custom executable, API key, or transport can be supplied through session options.

Quick start

import { run } from '@factory/droid-sdk/node';

const result = await run('Summarize this repository.');

if (!result.success) {
  throw new Error(result.error?.message ?? 'The run did not complete.');
}

console.log(result.text);

Use createSession() for multi-turn Node conversations. Use connectToDaemon() from the root entrypoint to manage sessions through an existing daemon.

Documentation

The TypeScript SDK documentation is the canonical user-facing guide to:

• Node and daemon runtimes
• Runs, sessions, streaming, attachments, and structured output
• Permissions, AskUser, tools, skills, MCP, and hooks
• Session replacement and cleanup behavior
• Browser and daemon integration
• Observability, REST helpers, advanced resources, and the public API

Runnable examples are available under examples/node and examples/browser.

Custom transport migration

• Breaking agent-client change: DroidClientOptions.transport and custom session transports now require DroidClientTransport, which exchanges JsonRpcMessage objects through send and onMessage. No format marker or runtime detection is needed.
• Built-in ProcessTransport owns its stdio JSON codec. Its direct send and onMessage callers must now pass and receive objects rather than strings. In-process implementations exchange snapshots without codecs.
• For an existing custom StringFramedDroidClientTransport, explicitly pass withJsonRpcCodec(stringTransport) to DroidClient or session options. The adapter and both interfaces are exported from @factory/droid-sdk/node. Do not wrap an already typed transport.
• Breaking daemon-client change: replace DaemonClient.onMessage with onTransportMessage and remove JSON.parse from callbacks. Custom DaemonClientTransport.send and message listeners now exchange JsonRpcMessage objects. Put codecs inside transports that cross a serialized boundary. External wire formats are unchanged.

Shared display messages

• filterMessagesForUI no longer copies messages. A message with nothing to hide comes back as the same object, and a stripped message as a projection that later calls return again. Treat the results as read-only: mutating one changes your input or what later calls return. Replace a message instead of editing it.

Open status values (0.11.0)

• RemoteSession['status'], MachineTemplateBuildStatus['status'], and MachineTemplateBuildStatus['failureReason'] now accept values a newer server adds instead of failing the response. An exhaustive switch over one of them needs a branch for an unknown value.
• Those fields of RemoteSessionSchema and MachineTemplateBuildStatusSchema are unions now, not enums: .enum on them is gone, and .options lists the union's member schemas rather than the known values.

Machine template list (0.11.0)

• listMachineTemplates no longer takes limit or cursor. The API returns every template in one response, with pagination.hasMore always false and pagination.nextCursor always null.
• ListMachineTemplatesOptions drops limit and cursor but stays an interface over FactoryApiOptions, so declaration merging into it keeps compiling. An options object literal that passes either field fails typecheck; a variable typed with extra properties compiles, and the helper does not send them.

The canonical SDK guide remains the full API reference.

Browser security

The daemon client currently authenticates with a Factory API key. Browser integration is intended for trusted local tools. Do not ship a Factory API key in a public website, commit it to source control, or put it in a URL.

License

Apache 2.0