Foundry primitives

The libraries Marbles combines into one local automation runtime.

Marbles bundles the libraries below. Import @foundry.sh/marbles to write an automation; follow a package link when you need its underlying contract or implementation.

How a run uses the primitives

A launch enters Workflows as a tree of steps. Marbles gives each step a context through which it can open sessions, use files, execute commands, and publish results. That context connects the libraries below to the run’s replay, cancellation, output, and cleanup.

Library	Responsibility in Marbles
Workflows	Executes steps and workflows, records results, applies retry policies, and supports waiting.
Agents	Keeps conversations, skills, and tool authorization for `agent` and `agents.session`.
Models	Resolves the agent’s `provider` and `model`.
Workspaces	Provides file operations, observation, and Git worktrees.
Sandbox	Runs isolated environments and their file, command, and process operations.
Artifacts	Keeps named outputs, content versions, stored bytes, and Feed entries.
Core	Defines shared storage and pagination contracts.
Lib	Supplies configuration, authorization, paths, digests, and local file coordination.

What Marbles adds

Marbles supplies module discovery, the catalog, CLI defaults, the dashboard, trigger loops, local state, and the bindings between resources and steps.

For example, Workflows supplies the retry and suspension machinery. Marbles records the agent sessions and artifact versions opened by a step, and persists parked runs for later adoption. Agents keeps the conversation; Artifacts keeps the report. Together they support a workflow that waits for approval without repeating its completed review.

The package APIs can support host choices the CLI does not expose. Read Marbles’ durability guarantees and remote limits when deciding what a CLI deployment can do. A library’s recovery API does not by itself enable automatic recovery of an interrupted Marbles run.

When to go deeper

Use these docs to author and operate automations. Follow a package link when you need to understand a resource’s underlying contract, investigate its implementation, or reuse a primitive in another product.

For an embedded Marbles host, the engine reference shows how to provide the package instances and persistent stores. Use its bundled @foundry.sh/marbles/lib exports for those instances so they match the engine’s copy of the classes.

Package entry points

Import	Intended use
`@foundry.sh/marbles`	Author automations: builders, resource factories, triggers, helpers, and their types.
`@foundry.sh/marbles/prebuilt`	Register a ready-made step with your chosen options.
`@foundry.sh/marbles/lib`	Embed an engine in another application with explicit dependencies.

With this foundation, Software Factory puts the pieces together in a complete local workflow. Use the API reference when you need exact options and types.