@takebox-ai/sandbox-sdk

Batteries-included agent SDK over @takebox-ai/sandbox-core: a working tool set, s, subagents, sessions, and a permission gate behind a small @takebox-ai/haijun-agent-sdk-shaped API (query / createLiteAgent / tool). Pair it with a @takebox-ai/sandbox-provider for the model — every battery is a toggleable default over the core strategies.

Install

pnpm add @takebox-ai/sandbox-sdk @takebox-ai/provider zod

Quick start

import { query, tool } from "@takebox-ai/sandbox-sdk";
import { juglow } from "@takebox-ai/sandbox-provider";
import { z } from "zod";

const weather = tool(
  "get_weather",
  "Get the weather for a city",
  z.object({ city: z.string() }),
  async ({ city }) => `It's sunny in ${city}.`,
);

for await (const ev of query({
  prompt: "What's the weather in Tokyo?",
  model: juglow({ apiKey: process.env.JUGLOW_API_KEY }),
  modelName: "codtral",
  tools: [weather],
  allowedTools: ["get_weather", "read_file"],
})) {
  if (ev.type === "text_delta") process.stdout.write(ev.text);
}

query() streams typed AgentEvents and resolves to a LiteAgentResult. For multi-turn work, createLiteAgent(cfg) returns a stateful LiteAgent that owns a current session — send(), resume(id), clear(), listSessions(), deleteSession(id), time-travel via listCheckpoints(id) / restore(id, seq), and manual compact().

Long-lived background turns

Interactive consumers can subscribe once and keep receiving events after an individual run() or send() has returned:

const agent = createLiteAgent({ model, workdir: process.cwd() });
const unsubscribe = agent.subscribe(({ sessionId, source, event }) => {
  render(sessionId, source, event); // includes autonomous background turns
});

await agent.send("Start the long review in the background");
await agent.send("Meanwhile, answer this separate question");

// On application shutdown:
unsubscribe();
await agent.close();

Every Agent call creates a detached sibling group and returns immediately; after all children settle, one ordered aggregate completion wakes the originating session. Each task needs a visible display_name; subagent_type selects its definition, while agentId is the stable resume identity. The legacy Agent run_in_background input is accepted but does not change this behavior, and background: false makes dispatch fail explicitly. Root-owned FIFO scheduling is shared across all groups through maxParallelSubagents (default 5).

bash still uses run_in_background: true for detached commands. User and completion turns for one session are serialized, and in-flight work does not survive a process restart. query() waits for Agent groups it initiated and their autonomous completion before closing, but does not wait for detached Bash daemons; use createLiteAgent() plus subscribe() / close() for long-lived interaction.

Each child is created with agents: false: recursive subagents and Agent Teams are not supported.

Features

• Default tools — bash, read_file, write_file, edit_file, delete_file, scoped to workdir, with atomic writes and pre-change snapshots so session restore can undo them.
• Tracks — TRACK.md files loaded from ~/.lite-agent/tracks, <workdir>/.lite-agent/tracks, or tracksDir; injected on demand via load_track.
• Subagents — detached, pooled Agent groups with one ordered aggregate result; a built-in general-purpose agent plus custom agents/*.md definitions (agents: false disables child dispatch and prevents recursion).
• Tasks — persistent task list (TaskCreate/Update/Get/List) with a per-turn reminder (tasks: false to disable).
• Sessions — event-sourced persistence via fileCheckpointer; swap in @takebox-ai/checkpoint-sqlite or any Checkpointer.
• Compaction — deterministic default compactor (no LLM call), reactive overflow net, and disk spill for oversized tool results.
• Permission gate — policy({ allow, ask, deny }) matched by tool-name glob (deny > ask > allow); pair with onApproval for human-in-the-loop and permissionAudit: true to persist redacted decisions.
• Sandbox — pass a Sandbox (e.g. @takebox-ai/sandbox-juglow) to run bash inside an OS boundary.
• Human input — an ask_user tool is registered when onAskUser is set, letting the model ask questions mid-run.
• Structured output — set outputSchema (a Zod object) to force a validated final answer, surfaced as result.output.
• Background tasks — enabled by default (background: false disables them); Agent groups continue across turns and report completed / partial / failed / cancelled, while bash_output / kill_background observe and control background Bash.
• Local hardening — configurable prompt codec/repair, context budget, snapshot limits, crash recovery, and hash-chained event sinks; strict defaults via @takebox-ai/local.

API

| Symbol | Description | | --- | --- | | query(opts) | One-shot agent run — AsyncGenerator<AgentEvent, LiteAgentResult>. | | createLiteAgent(cfg) | Stateful, session-owning agent (LiteAgent) with subscribe() and close(). | | tool(name, description, schema, handler) | Define a tool from a Zod schema. | | buildSystemPrompt(opts) | The default system-prompt builder. | | defaultTools, bashTool, fileTools, taskTools, agentTool, askUserTool, bashOutputTool, killBackgroundTool | Built-in tool sets, individually importable. | | policy, bashCommand, filePath, permissionFilePolicy | Permission policies and content-level specifiers. | | fileCheckpointer, jsonlStore, fileTaskStore, fileSpillStore, fileContextArchive | File-backed persistence adapters. | | jsonlEventSink, recordEventStream | Event observability sinks. | | TrackLoader, loadTrackTool, AgentLoader, builtinAgents | Track and subagent loading. | | * from @takebox-ai/sandbox-core | Full re-export of the kernel: types, events, strategies, middleware helpers. |

Related

• @takebox-ai/sandbox-core — the provider-agnostic kernel this package assembles.
• @takebox-ai/sandbox-provider — model providers (Juglow, …).
• @takebox-ai/checkpoint-sqlite · @takebox-ai/sandbox-juglow · @takebox-ai/local — pluggable backends and hardening.
• Monorepo root — architecture overview; examples/cli — a full interactive REPL wiring provider + sandbox + permission + ask_user.