Files
openworker/docs/harness/SDK-STORAGE.md

9.0 KiB

Rust SDK with selectable storage

The Rust SDK runs the same agent and team logic with SQLite or PostgreSQL, either embedded in the application or in a managed private-stdio child. The database is an explicit configuration choice, not a prerequisite for using Teams. No REST server is needed for this integration.

Import and configure

The development crate is openworker-sdk in harness/harness-sdk. Import it using a pinned Git revision of the private repository or a local path dependency; it is not yet a published crates.io release. Partners need repository access. For example, replace the revision placeholder with the handoff's full commit:

[dependencies]
openworker-sdk = { git = "ssh://git@github.com/andrewyng/openworker.git", rev = "PINNED_COMMIT" }
tokio = { version = "1", features = ["full"] }
serde_json = "1"

Use HostConfig for storage selection and one or more trusted coworker profiles. The older RuntimeConfig single-coworker/local constructors remain compatible. Both configurations use the same HarnessClient application methods.

use openworker_sdk::*;

let config = HostConfig {
    state_dir,                  // Stable absolute private controller directory.
    runner: runner_binary,      // Absolute compatible OpenWorker helper binary.
    storage: Storage::Postgres {
        connection_env: "MY_APP_DATABASE_URL".into(),
        schema: "ow_my_product".into(),
        ca_file: Some(postgres_ca),
        loopback_plaintext: false,
    },
    coworkers: vec![
        CoworkerConfig {
            bundle: lead_bundle,
            model: "gpt-6-sol".into(),
            provider: ModelProvider::Openai,
            servers: None, tool_policy: None, runtime_policy: None,
        },
        CoworkerConfig {
            bundle: worker_bundle,
            model: "claude-sonnet-5-5".into(),
            provider: ModelProvider::Anthropic,
            servers: None, tool_policy: None, runtime_policy: None,
        },
    ],
    sandbox: Sandbox::Openshell,
    scripted: false,
    agents: vec![],             // Using the hand-written coworkers above.
    telemetry: None,
};

// Operator setup before starting a new/upgraded PostgreSQL installation.
// Run deliberately, not as an unreviewed side effect of every request.
config.storage.migrate()?;

let client = HarnessClient::embedded(
    config, my_native_tool_registry, ClientOptions::default()
).await?;

For SQLite, change only storage to Storage::Sqlite; its database is under state_dir. This chooses where new state lives—it does not migrate existing sessions between databases.

To use a child process instead, pass the same HostConfig to:

let client = HarnessClient::managed_stdio(HostProcessConfig {
    program: partner_harness_binary,
    host: config,
    restart: RestartPolicy::default(),
}, ClientOptions::default()).await?;

Build the default MCP-capable child with cargo build --locked -p openworker-sdk --bin openworker-harness. For native partner tools, link them into a partner child using this entry point:

fn main() {
    let mut tools = openworker_sdk::ToolRegistry::default();
    my_tools::register(&mut tools).expect("register tools");
    openworker_sdk::cli::main_with_registry(tools);
}

That entry point supports the SDK host protocol plus existing helper commands. Existing binaries using only openworker_runtime::cli retain their old interface; they do not silently acquire the new multi-coworker host launcher. Embedded native tools come from the supplied registry; Rust implementations are never transferred over stdio. Keep the runner/partner binary and tool implementation versions pinned.

Credentials and application operations

The PostgreSQL connection string is read from the explicitly named environment variable, never from the serialized launch configuration or executable arguments. The managed SDK forwards only that declared database variable plus the normal OS/runtime allowlist. Do not log process environments. Model credentials use the existing private connection/set protocol, separately for each coworker:

client.request("connection/set", serde_json::json!({
    "coworker": "team-worker", "id": "anthropic", "label": "Worker provider",
    "provider": "anthropic", "api_key": key_from_private_input,
    "persistence": "memory"
})).await?;

The host removes the routing field before calling the normal credential handler. Keys never enter the session or team database. Memory keys must be resupplied after a child restart; this does not automatically retry an interrupted turn. Automatic deliveries stay queued while model credentials are unavailable. Host snapshots expose session.model_credentials_ready; this is not a live provider health check. Resupplying a key permits still-unstarted deliveries to proceed. Coworker defaults and explicit session overrides retain their existing precedence.

create_session, start_turn, subscribe, attach, approve, answer, cancel_turn, history, plans, skills, tool controls and model connections use the same SDK interface for both adapters. Each session routes to its pinned coworker. Use coworker/list to inspect the registered profiles. Workspace and permission configuration remain per session; choosing PostgreSQL does not grant sandbox, filesystem, network or credential access.

Team methods are create_team(TeamCreate), team_snapshot(id), team_command(id, TeamCommand) and team_events(id, after). TeamMember and TeamRole are exported by the SDK. The work-item/message command bodies are the same as the team protocol. Start fresh role-pinned member sessions, create the team, then submit the task to its lead. The host consumes durable deliveries and terminal notifications; the application need not schedule individual worker turns. Member session progress is pushed through subscribe; board events use the separate cursor-based team_events API. Persist those cursors and reconcile after reconnect rather than treating notifications as exactly-once delivery.

Ownership and storage responsibilities

This SDK host is a single execution supervisor with up to 16 coworker profiles and the existing four active-turn slots per profile. PostgreSQL requires a multithread Tokio runtime. Both databases provide the same team semantics. SQLite holds an exclusive state-directory lock. PostgreSQL uses a dedicated SDK schema, a connection-level host lock, session epochs and lease renewal. A second host is rejected; after connection/process loss the next host fences the prior epochs and recovers without replaying uncertain effects. The local controller directory remains required with PostgreSQL for private connection metadata and runtime/tool state. Do not share it between live hosts.

Use a fresh PostgreSQL schema for SDK-managed execution. It cannot silently adopt an existing distributed-server schema, and distributed workers reject SDK-owned schemas. Multi-node execution remains the existing separately configured server worker-pool deployment; database choice alone does not enable it. This distinction concerns who owns execution, not whether an agent can use Teams.

Common validation, work transitions, dependency dispatch and completion decisions live in runtime/src/team_service.rs. Adapters implement transactions, receipts, event storage, ownership and queue operations. PostgreSQL's HTTP authorization and multi-node controls remain in its server adapter; SQLite is not represented as a network-accessible multi-tenant service. The SDK is a trusted backend API, not an authentication boundary for untrusted callers.

Current parity covers native sessions/teams and the agent features above. Remote environment provisioning, HTTP authorization administration, artifact-service APIs and distributed operational metrics remain server-host APIs, not new SDK methods. This checkpoint does not introduce missing general guardrail hooks or memory tools.

Verification and example

harness/harness-sdk/examples/storage_host.rs is a compilable consumer. It loads a JSON HostConfig, initializes the selected host and shuts down without a model call. Run from harness/:

cargo run --locked -p openworker-sdk --example storage_host -- embedded /absolute/host.json --migrate
cargo run --locked -p openworker-sdk --example storage_host -- stdio /absolute/host.json

The storage/process acceptance matrix is in harness-sdk/tests/storage_teams.rs. It uses synthetic models and real native tools, databases and subprocesses. A lead assigns work, a worker waits at approval, restart retains that approval, one tool effect occurs, comments persist and the lead accepts the result. Managed modes kill the owned child to exercise automatic recovery; both stores reject competing hosts. The same domain assertions run against SQLite and PostgreSQL. Separate SQLite tests inject transaction failure and reject an unsupported future team schema.

Linux qualification and exact regression results are recorded in the work ledger. This is a source SDK checkpoint, not a new Windows, OpenShell/AWS deployment, signed binary release or stable published API promise.