Dust AI Agent Platform Documentation

The Sparkle library is organized into several functional categories in the Storybook sidebar:

• Foundations: Design tokens (colors, typography, shadows, motion).
• Assets: Brand assets (logos, icon sets, avatar sets).
• Actions: Triggers like Button, SplitButton, IconButton, and SliderToggle.
• Forms & Inputs: Controls like Input, TextArea, Checkbox, RadioGroup, and Dropdown.
• Data Display: Presentational components like Avatar, Icon, Card, Chip, Counter, DataTable, and Tree.
• Feedback & Status: Spinners, loading states, and notifications.
• Navigation: Breadcrumbs, Tabs, Toolbars, and navigation lists.
• Overlays: Dialogs, Sheets, Popovers, and Tooltips.
• Layout: Scaffolding and spacing like Page, Container, ScrollArea, and Separator.
• Lists: List and item components.
• Product: App-specific UI for Conversation (messages, citations, code blocks) and Agent surfaces.
• Effects & Motion: Animated and decorative effects.
• Lab: Experimental, unstable components.

When migrating from io-ts to zod, use the following pattern mappings for schema definitions, type extraction, and validation.

Schema Definition

io-ts

const Schema = t.type({
  name: t.string,
  age: t.number,
  email: t.union([t.string, t.undefined]),
});

zod

const Schema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().optional(),
});

Type Extraction

io-ts

type MyType = t.TypeOf<typeof Schema>;

zod

type MyType = z.infer<typeof Schema>;

Validation

io-ts

const result = Schema.decode(data);
if (isLeft(result)) {
  const errors = reporter.formatValidationErrors(result.left);
  return Err(errors);
}
return Ok(result.right);

zod

const result = Schema.safeParse(data);
if (!result.success) {
  return Err(result.error.errors.map((e) => e.message));
}
return Ok(result.data);

// io-ts
const Schema = t.type({
  name: t.string,
  age: t.number,
  email: t.union([t.string, t.undefined]),
});

// zod
const Schema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().optional(),
});

API handlers in front-api/routes/ should remain thin. They are responsible for:

• Authentication/Authorization
• HTTP method dispatch
• Request validation (using zod)
• Calling the business layer (lib/api/*)
• Mapping business results to HTTP responses

Business Logic Location: Non-trivial logic (sequential DB operations, conditional branching on state, coordination across resources) must live in lib/api/* or within a Resource.

Crucial Rule: Business logic must not return HTTP-specific error envelopes like APIErrorWithStatusCode. It should return domain results (e.g., Result<T, DomainError>). The handler is the only layer that should map domain errors to HTTP status codes.

// BAD — business layer encoding HTTP status codes
export async function getThing(
  auth: Authenticator,
  id: string
): Promise<Result<Thing, APIErrorWithStatusCode>> {
  if (!found) {
    return new Err({
      status_code: 404,
      api_error: { type: "thing_not_found", message: "Not found." },
    });
  }
}

// GOOD — domain error, handler maps to HTTP
export class ThingError extends Error {
  constructor(readonly type: "not_found" | "unauthorized") {
    super(type);
  }
}

export async function getThing(
  auth: Authenticator,
  id: string
): Promise<Result<Thing, ThingError>> {
  if (!found) {
    return new Err(new ThingError("not_found"));
  }
}

// Handler does the mapping:
const result = await getThing(auth, id);
if (result.isErr()) {
  switch (result.error.type) {
    case "not_found": return apiError(req, res, { status_code: 404, ... });
    case "unauthorized": return apiError(req, res, { status_code: 403, ... });
  }
}

The Steering feature (gated by the enable_steering feature flag) allows users to redirect an agent's work by sending a new message while an agent is still running.

When steering is enabled, postUserMessage follows a 'pending' path if the message contains user mentions and the currently running agent, but does not address a different agent.

Constraints for Steering:

• A message can contain at most one agent mention.
• You cannot address a different agent than the one currently running.
• API callers bypass the pending path and always follow the normal path.

Workflow:

1. A UserMessage is created with visibility: "pending".
2. A UserMessageNewEvent (pending) is published.
3. gracefullyStopAgentLoop() is called with reason: "steering".
4. Once the current loop stops (with status "gracefully_stopped" or "succeeded"), the pending message is promoted to visibility: "visible", and a new AgentMessage is created to handle the new instruction.

The Sandbox Secret Swap is a security architecture designed to prevent secret exfiltration from sandbox environments. Instead of injecting real secrets into the agent process environment in plaintext, the system injects deterministic, opaque placeholders.

How it works:

1. Placeholder Injection: The agent process environment contains a random nonce (placeholder) instead of the real secret.
2. Just-in-Time Substitution: When an HTTPS request leaves the sandbox, the dsbx (sandbox) component performs a Man-in-the-Middle (MITM) on the egress path. It substitutes the placeholder with the real secret value just before the bytes hit the upstream server.
3. Destination Gating: Substitution only occurs if the destination domain is explicitly listed in the secret's allowedDomains. If a placeholder is detected going to a domain not in its allowedDomains, dsbx drops the connection.

Key Security Invariant: The real secret value is never forwarded to a destination outside the matching secret's allowedDomains.