SDK & Plugins

DimCode's embeddable runtime is published as @archships/dim-agent-sdk. The current release tracked by these docs is @archships/[email protected].

Install

npm install @archships/[email protected]

Plugin authors should also install the public plugin contract package:

npm install @archships/[email protected] @archships/[email protected]

Minimal Agent

import {
  createAgent,
  createModel,
  createOpenAIAdapter,
} from '@archships/dim-agent-sdk'

const model = createModel(
  createOpenAIAdapter({
    apiKey: process.env.OPENAI_API_KEY,
    baseUrl: 'https://api.openai.com/v1',
    defaultModel: 'gpt-4o-mini',
  }),
)

const agent = createAgent({
  model,
  cwd: process.cwd(),
  hostDataDir: '.dim/host-data',
})

const session = await agent.createSession({
  systemPrompt: 'You are a coding agent. Use tools when needed.',
})

const itemId = session.send('Inspect this repo and propose the next change.')

for await (const event of session.receive()) {
  if (event.itemId !== itemId) continue
  if (event.type === 'text_delta') process.stdout.write(event.delta)
  if (event.type === 'done') console.log(event.message.content)
}

Queue-first Sessions

Sessions use a queue-first flow:

• session.send(input) queues one user item and returns its itemId.
• session.sendBatch(items) queues multiple user items.
• session.steer(input) adds steering context for the next queued item.
• session.receive() drains queued work and streams events.
• session.getQueueStatus(), cancelQueuedItem(), and clearQueue() expose host queue control.

Useful stream events include text_delta, thinking_delta, tool_call_start, tool_call_args_delta, tool_call_end, tool_call, plugin_event, tool_result, usage_recorded, turn_usage, done, and error.

Provider Adapters

The SDK exports createModel() plus built-in adapters:

• createOpenAIAdapter() and createOpenAIResponsesAdapter()
• createAnthropicAdapter()
• createGeminiAdapter()
• createZenMuxAdapter()
• createAihubmixAdapter() and createAihubmixResponsesAdapter()
• createMoonshotAIAdapter()
• createDeepSeekAdapter()
• createXaiAdapter() and createXaiResponsesAdapter()

Adapter-level provider debug logs can be enabled with debug.logFilePath; secret-bearing fields are redacted by default.

Builtin Tools

createAgent() registers four local coding tools by default:

Tool	Purpose	Notes
read	Read file context	UTF-8 text returns line-numbered windows and revisions; raster images become synthetic user file context when the active model accepts image input
write	Write UTF-8 text	Creates or overwrites files
edit	Replace text	Uses revision guards and supports replaceAll
exec	Run commands	Uses flat argv-style input, foreground/background runs, process polling, and explicit termination

exec input uses a string-array command:

{
  command: ['pnpm', 'test'],
  cwd: process.cwd(),
  yieldTimeMs: 1000,
  timeoutMs: 30000,
}

Persistence and Usage

Use FileStateStore or InMemoryStateStore for session persistence:

import { FileStateStore, createAgent } from '@archships/dim-agent-sdk'

const agent = createAgent({
  model,
  stateStore: new FileStateStore({ directory: '.dim/snapshots' }),
})

FileStateStore writes <sessionId>.json for the main snapshot and <sessionId>.usage.json for the usage ledger. Usage can be read through session.getUsageSummary(), session.getTurnUsage(itemId), and session.listRequestUsages().

Compaction

The SDK exports compaction helpers such as DEFAULT_COMPACTION_SAFETY_RATIO, buildCompactionBudget(), calculateThresholdTokens(), and isContextWindowExceededError(). Automatic history summarization is delivered by the official @archships/dim-plugin-auto-compact package.

Official Plugins

Package	Version	Status
@archships/dim-plugin-auto-compact	0.0.19	Supported auto compaction
@archships/dim-plugin-devtools	0.0.3	Supported local inspector
@archships/dim-plugin-grep-glob	0.0.9	Supported grep / glob tools
@archships/dim-plugin-mcp-client	0.0.9	Supported MCP client
@archships/dim-plugin-skills	0.0.13	Supported file-backed skills
@archships/dim-plugin-plan-mode	0.0.13	Supported planning guardrail
@archships/dim-plugin-research-mode	0.0.4	Experimental research guardrail
@archships/dim-plugin-memory	0.0.3	Stub
@archships/dim-plugin-web	0.0.3	Stub
@archships/dim-plugin-scheduler	0.0.3	Stub

Devtools

import { createDevtoolsPlugin } from '@archships/dim-plugin-devtools'

const agent = createAgent({
  model,
  cwd: process.cwd(),
  hostDataDir: '.dim/host-data',
  plugins: [createDevtoolsPlugin({ autoOpenBrowser: false })],
})

const session = await agent.createSession()
const devtools = session.getPlugin('devtools')

console.log(await devtools?.getInspectorUrl())

The devtools plugin uses hostDataDir for runtime journals and provider request history.

GoatChain Migration

For hosts migrating from GoatChain-style runtimes, map the core pieces directly:

GoatChain concern	Dim SDK path
Agent/session lifecycle	createAgent(), createSession(), restoreSession()
Queue execution	send(), sendBatch(), steer(), receive()
Model adapters	createModel(createOpenAIAdapter(...)) and other built-in adapters
Local coding tools	Built-in read, write, edit, exec
Plugins/middleware	Official plugins plus @archships/dim-plugin-api hooks
Persistence	FileStateStore, InMemoryStateStore, split usage ledger
Subagents	SubagentOrchestrator, in-process executors, process executors

Use the SDK for agent runtime concerns, official plugins for common extensions, and the host application for UI, auth, tenancy, and deployment policy.