Starweaver

Starweaver is a Rust agent SDK for building local-first AI agents, CLIs, and service runtimes. It gives you a typed agent loop, provider-neutral model protocol, function tools, structured output, durable session primitives, first-party environment tools, and a CLI product surface in one workspace.

The current release line is preparing for the first public release, 0.0.1. The development version in this repository intentionally uses the pre-release version 0.0.1-dev.0; the release commit promotes it to 0.0.1.

Why Starweaver

Rust-native agent construction with AgentBuilder, AgentApp, and AgentSession.
Provider-neutral model messages, settings, profiles, streaming parts, and request audit hooks.
Typed function tools from Serde and schemars, plus toolsets, metadata, retries, approval, and deferred records.
Structured output through JSON Schema, typed parsing, output functions, and validation retry.
Runtime extension hooks for prompt preparation, request shaping, tool policy, output validation, usage, and trace recording.
Durable execution foundations: context export/restore, checkpoints, session records, replay streams, and SQLite storage adapters.
First-party SDK bundles for filesystem, shell, skills, task tracking, host search/scrape/media adapters, MCP, and subagents.
A CLI launcher with profile-based local runs, install/update flow, display messages, local storage, and release artifacts.

Install

After the first release is published:

curl -fsSL https://raw.githubusercontent.com/Wh1isper/starweaver/main/scripts/install.sh | sh

Install a pinned release:

STARWEAVER_VERSION=v0.0.1 \
  curl -fsSL https://raw.githubusercontent.com/Wh1isper/starweaver/main/scripts/install.sh | sh

Run from a checkout before the first release:

make cli -- -p "hello" --output text
make sw -- version

SDK Quickstart

use std::sync::Arc;

use starweaver_agent::{AgentBuilder, TestModel};

# async fn example() -> Result<(), starweaver_agent::AgentError> {
let agent = AgentBuilder::new(Arc::new(TestModel::with_text("Paris")))
    .instruction("Answer concisely.")
    .build();

let result = agent.run("What is the capital of France?").await?;
assert_eq!(result.output, "Paris");
# Ok(())
# }

Add typed tools:

use std::sync::Arc;

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use starweaver_agent::{typed_tool, AgentBuilder, TestModel, ToolContext, ToolResult};

#[derive(Clone, Debug, Deserialize, JsonSchema, Serialize)]
struct LookupArgs {
    /// City to look up.
    city: String,
}

# async fn example() -> Result<(), starweaver_agent::AgentError> {
let lookup = typed_tool::<LookupArgs, _, _>(
    "lookup_weather",
    Some("Look up weather for a city".to_string()),
    |_ctx: ToolContext, args: LookupArgs| async move {
        Ok(ToolResult::new(serde_json::json!({
            "city": args.city,
            "forecast": "clear"
        })))
    },
);

let agent = AgentBuilder::new(Arc::new(TestModel::with_text("clear")))
    .tool(Arc::new(lookup))
    .build();

let result = agent.run("What is the weather in Paris?").await?;
assert_eq!(result.output, "clear");
# Ok(())
# }

Documentation

Published docs: https://starweaver.wh1isper.top

Start here:

Architecture and product decisions live in spec/. User-facing guides live in docs/.

Workspace

Starweaver is organized as focused crates:

starweaver-agent: public SDK facade, app/session helpers, bundles, subagents, profiles, and filters.
starweaver-runtime: deterministic agent loop, graph state, tools, output, retries, capabilities, streams, traces, and checkpoints.
starweaver-model: provider-neutral model protocol, settings, profiles, transports, wrappers, OAuth-backed adapters, and replay tests.
starweaver-tools: function tools, toolsets, metadata, lifecycle, MCP foundations, approval, and deferred execution.
starweaver-context: AgentContext, typed dependencies, state, event/message buses, notes, usage, and resumable state.
starweaver-environment: local and virtual filesystem/shell providers, policies, resources, and environment snapshots.
starweaver-session, starweaver-stream, starweaver-storage: durable session, replay, display stream, and SQLite storage contracts.
starweaver-cli: local CLI product surface, launcher dispatch, profiles, TUI, storage, install, and update workflows.

Validation

make fmt-check
make check
make test
make docs-check
make docs-build

Full local gate:

make ci

Release

Prepare the first public release:

gh workflow run prepare-release.yml -f version=0.0.1

The workflow pushes release/v0.0.1 for review. After that release commit reaches main, publish v0.0.1 as a GitHub Release; the published Release event builds CLI archives, uploads checksums, and publishes crates through the Release environment.

Acknowledgements

Starweaver's design is informed by prior agent SDK work, including Pydantic AI and the Yet Another Agents / ya-mono ecosystem. Starweaver's implementation, public symbols, crate boundaries, documentation, and release workflow use Starweaver-native names and contracts.

License

BSD-3-Clause

starweaver-usage 0.0.1