starweaver-usage 0.0.1

# 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:

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

Install a pinned release:

```bash
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:

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

## SDK Quickstart

```rust
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:

```rust
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:

- [Quickstart](docs/quickstart.md)
- [Agent SDK](docs/agent-sdk.md)
- [Agents](docs/agent.md)
- [Models](docs/models.md)
- [Tools](docs/tools.md)
- [Structured Output](docs/output.md)
- [CLI](docs/cli.md)
- [Testing](docs/testing.md)
- [Release](docs/release.md)

Architecture and product decisions live in [spec/](spec/). User-facing guides live in [docs/](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

```bash
make fmt-check
make check
make test
make docs-check
make docs-build
```

Full local gate:

```bash
make ci
```

## Release

Prepare the first public release:

```bash
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