openagents_sdk::labs

ArtifactDownload::next_chunk

pub async fn next_chunk(
    &mut self,
    cancel: &CancellationToken,
) -> Result<Option<Vec<u8>>, Error>

Reads the next part of the file, or None when the whole file has arrived.

ArtifactHandle::metadata

pub fn metadata(&self) -> &Artifact

Returns the file's details, such as its name, size, and checksum.

ArtifactHandle::signed_url

pub fn signed_url(&self) -> Option<&str>

A public signed link, without an account bearer. Refresh metadata after expiry.

ArtifactHandle::expires_seconds

pub fn expires_seconds(&self) -> Option<u32>

Returns how many seconds the signed link stays valid, if it is signed.

Client::agent_lab

pub fn agent_lab<'a>(
    &'a self,
    session: &'a Session,
) -> Result<AgentLabClient<'a>, Error>

Returns the Agent Lab client for session, or an error if the session belongs to another deployment.

Client::agents

pub fn agents<'a>(&'a self, session: &'a Session) -> Result<Agents<'a>, Error>

Returns the agents client for session, or an error if the session belongs to another deployment.

Client::scanned_login

pub async fn scanned_login(
    &self,
    scanned: &ScannedLogin,
) -> Result<ScannedLoginAbout, Error>

Which browser scanned signs in, to show before approving.

Calls GET /v1/web-sign-in/*

Client::approve_scanned_login

pub async fn approve_scanned_login(
    &self,
    signer: &dyn NostrSigner,
    scanned: &ScannedLogin,
) -> Result<ScannedLoginApproved, Error>

Approve scanned with the key behind signer: the browser that showed the code signs in as that key's account (a new key makes it). Sends once.

Client::sign_in_with_key

pub async fn sign_in_with_key(
    &self,
    signer: &dyn NostrSigner,
    app: &str,
    computer: &str,
) -> Result<KeySignIn, Error>

Sign in with the key behind signer: fetch a challenge, sign one request, and receive an app session. A key that already has an account signs in this way; a new key may be asked for a sign-up proof first (Refused { code: Some("proof_required"), .. }, #11994), which [Client::sign_in_with_key_on] sends. Sends once; the caller stores the session as it stores a device sign-in's, and signs in again before it expires.

Client::key_challenge

pub async fn key_challenge(&self) -> Result<String, Error>

A fresh sign-in challenge, for a sign-in that needs a proof over it.

Client::sign_in_with_key_on

pub async fn sign_in_with_key_on(
    &self,
    signer: &dyn NostrSigner,
    challenge: &str,
    app: &str,
    computer: &str,
    proof: serde_json::Map<String, Value>,
) -> Result<KeySignIn, Error>

Sign in over challenge (from [Client::key_challenge]), adding proof to the body: {"pow": solve_pow(challenge, POW_BITS)}, or {"app_attest": {"key_id", "attestation"}} from App Attest over SHA-256(challenge). The body stays under [KEY_BODY_MAX].

Client::link_key

pub async fn link_key(
    &self,
    session: &Session,
    new_key: &dyn NostrSigner,
) -> Result<Vec<LinkedKey>, Error>

Add the key behind new_key to the signed-in account; new_key signs a proof bound to this account. Answers the account's keys. A key that already signs in to another account is refused (Refused { status: 409, code: Some("identity_taken") }).

Calls POST /v1/device/keys

Client::account_keys

pub async fn account_keys(&self, session: &Session) -> Result<Vec<LinkedKey>, Error>

The signed-in account's keys, oldest first.

Calls GET /v1/device/keys

Client::remove_key

pub async fn remove_key(
    &self,
    session: &Session,
    pubkey: &str,
) -> Result<Vec<LinkedKey>, Error>

Remove one of the account's keys (hex or npub). The last key is never removed (Refused { status: 409, code: Some("last_key") }).

Calls DELETE /v1/device/keys/*

Client::authenticate_computer_job

pub async fn authenticate_computer_job(
    &self,
    credential: &str,
) -> Result<Session, Error>

Import a job credential issued by the work service. This credential authorizes only that job's computer operations, not account or chat access.

Client::authenticate_environment_job

pub async fn authenticate_environment_job(
    &self,
    credential: &str,
) -> Result<Session, Error>

Import an Environment attempt's computer credential. The grant excludes account reads and every other attempt's computers and artifacts.

Client::start_login

pub async fn start_login(&self, app: &str, computer: &str) -> Result<Login, Error>

Start an existing OpenAgents device grant. Does not launch a browser.

Calls POST /v1/device/code

Client::poll_login

pub async fn poll_login(&self, login: &mut Login) -> Result<Poll, Error>

Poll no faster than the server permits. An interrupted redemption ends this attempt.

Calls POST /v1/device/token

Client::wait_for_login

pub async fn wait_for_login(
    &self,
    login: &mut Login,
    cancellation: &CancellationToken,
) -> Result<Session, Error>

Wait with explicit cancellation. A dropped/uncertain redemption is never automatically retried.

Client::account

pub async fn account(&self, session: &Session) -> Result<AccountView, Error>

Read the existing account and current workspaces; never trusts saved membership data.

Calls GET /v1/account

Client::authenticate

pub async fn authenticate(&self, credential: &str) -> Result<Session, Error>

Explicitly import an app session or sign-in key. Does not read environment variables.

Calls GET /v1/account

Client::restore

pub async fn restore(&self, record: &CredentialRecord) -> Result<Session, Error>

Revalidate a record loaded by the caller. Failure does not erase caller storage.

Client::delete_account

pub async fn delete_account(
    &self,
    session: &Session,
    forfeit_balance: bool,
) -> Result<(), Error>

Delete the signed-in account and what it keeps (#12002): chats, files, projects, connections, computers, keys, and sessions. The wallet's 12 words stay on the device. Refusals come back as [Error::Refused] with code balance_remaining (paid credit is left: ask, then call again with forfeit_balance), shared_workspace (the person owns a team with other members), or confirm_required. Clear local storage after it succeeds.

Calls DELETE /v1/account

Client::sign_out_record

pub async fn sign_out_record(&self, record: &CredentialRecord) -> Result<(), Error>

Revoke a saved app session without restoring account authority first. This also works when account discovery is unavailable or local expiry has passed. Always clear local credentials and views, even when revocation fails.

Client::sign_out

pub async fn sign_out(&self, session: &Session) -> Result<(), Error>

Revoke this app session. Sign-in keys are only forgotten by the caller, as in the CLI. Clear the caller's local storage and views even if this request fails offline.

Calls POST /v1/device/sign-out

Client::cloud_host

pub async fn cloud_host(
    &self,
    session: &Session,
    cancel: &CancellationToken,
) -> Result<CloudHost, Error>

Our cloud's current state.

Calls GET /v1/cloud-host

Client::start_cloud_host

pub async fn start_cloud_host(
    &self,
    session: &Session,
    cancel: &CancellationToken,
) -> Result<CloudHost, Error>

Start Our cloud, or return the run already going.

Calls POST /v1/cloud-host

Client::stop_cloud_host

pub async fn stop_cloud_host(
    &self,
    session: &Session,
    cancel: &CancellationToken,
) -> Result<CloudHost, Error>

End the engine and stop the computer.

Calls POST /v1/cloud-host/stop

Client::delete_cloud_host

pub async fn delete_cloud_host(
    &self,
    session: &Session,
    cancel: &CancellationToken,
) -> Result<CloudHost, Error>

End the engine and delete the computer.

Calls DELETE /v1/cloud-host

Client::computers

pub fn computers<'a>(&'a self, session: &'a Session) -> Result<Computers<'a>, Error>

Returns a client for the cloud computers on the session's account.

Client::home

pub fn home<'a>(&'a self, session: &'a Session) -> Result<Home<'a>, Error>

Returns the Home client for a session on this deployment.

Client::chat

pub fn chat(&self, session: &Session, id: &str) -> Result<ChatRef, Error>

Bind an explicit saved ID to this account; the service checks access on each read.

Client::history

pub fn history(&self, session: &Session) -> Result<ChatReader, Error>

Starts reading the account's chat list.

Client::history_projects

pub fn history_projects(&self, session: &Session) -> Result<ProjectReader, Error>

Starts reading the account's projects.

Client::shared_history

pub fn shared_history(
    &self,
    session: &Session,
    project: &HistoryProject,
) -> Result<ChatReader, Error>

Starts reading the chats in a shared project. Refuses a project that isn't shared.

Client::transcript

pub fn transcript(
    &self,
    session: &Session,
    chat: &ChatRef,
) -> Result<TranscriptReader, Error>

Starts reading a chat's messages from the first one.

Client::download

pub async fn download(
    &self,
    session: &Session,
    file: &AttachmentRef,
    cancel: &CancellationToken,
) -> Result<Vec<u8>, Error>

Fetch only this deployment's authorized saved bytes. No redirects, files, hosts, or external URLs are followed.

Client::history_index

pub fn history_index(&self, session: &Session) -> Result<HistoryIndex, Error>

Creates an empty history index for the signed-in account.

Client::artifact

pub async fn artifact(
    &self,
    space: &str,
    id: &str,
    cancel: &CancellationToken,
) -> Result<ArtifactHandle, Error>

Looks up a lab file in a space and returns its details and link.

Client::download

pub async fn download(
    &self,
    artifact: &ArtifactHandle,
    range: Option<Range<u64>>,
    cancel: &CancellationToken,
) -> Result<ArtifactDownload, Error>

Starts downloading a lab file, or only a byte range of it.

Client::events

pub fn events(&self, document: &DocumentRef, since: u64) -> Result<Events, Error>

Opens an event stream for a document, starting after the given cursor.

Client::kinds

pub async fn kinds(
    &self,
    space: &str,
    cancel: &CancellationToken,
) -> Result<Vec<KindManifest>, Error>

Lists the lab kinds available in a space.

Calls GET /v1/labs/kinds

Client::tools

pub async fn tools(
    &self,
    space: &str,
    kind: &str,
    cancel: &CancellationToken,
) -> Result<Vec<ToolDecl>, Error>

Lists the tools a lab kind offers in a space.

Calls GET /v1/labs/kinds/{kind}/tools

Client::invoke

pub async fn invoke(
    &self,
    kind: &str,
    name: &str,
    request: &Request<ToolCall>,
    cancel: &CancellationToken,
) -> Result<ToolResult, Error>

Calls a lab kind's tool and returns its result.

Calls POST /v1/labs/kinds/{kind}/tools/{name}

Client::documents

pub async fn documents(
    &self,
    space: &str,
    page: &PageOptions,
    cancel: &CancellationToken,
) -> Result<List<DocumentMeta>, Error>

Returns a page of documents in a space.

Calls GET /v1/labs/documents

Client::create_document

pub async fn create_document(
    &self,
    request: &Request<CreateDocument>,
    cancel: &CancellationToken,
) -> Result<Version, Error>

Creates a document and returns its first version.

Calls POST /v1/labs/documents

Client::document

pub async fn document(
    &self,
    document: &DocumentRef,
    cancel: &CancellationToken,
) -> Result<DocumentMeta, Error>

Returns a document's details.

Calls GET /v1/labs/documents/{id}

Client::delete_document

pub async fn delete_document(
    &self,
    document: &DocumentRef,
    cancel: &CancellationToken,
) -> Result<bool, Error>

Deletes a document and returns whether it was deleted.

Calls DELETE /v1/labs/documents/{id}

Client::versions

pub async fn versions(
    &self,
    document: &DocumentRef,
    page: &PageOptions,
    cancel: &CancellationToken,
) -> Result<List<Version>, Error>

Returns a page of a document's versions.

Calls GET /v1/labs/documents/{id}/versions

Client::version

pub async fn version(
    &self,
    document: &DocumentRef,
    number: u64,
    cancel: &CancellationToken,
) -> Result<Version, Error>

Returns one version of a document by number.

Calls GET /v1/labs/documents/{id}/versions/{n}

Client::edit

pub async fn edit(
    &self,
    document: &DocumentRef,
    request: &Request<EditDocument>,
    cancel: &CancellationToken,
) -> Result<EditResult, Error>

Proposes a new version of a document and reports whether it was created, out of date, or refused.

Calls POST /v1/labs/documents/{id}/versions

Client::card

pub async fn card(
    &self,
    document: &DocumentRef,
    number: u64,
    cancel: &CancellationToken,
) -> Result<Card, Error>

Returns the card for one version of a document.

Calls GET /v1/labs/documents/{id}/versions/{n}/card

Client::create_job

pub async fn create_job(
    &self,
    request: &JobRequest,
    cancel: &CancellationToken,
) -> Result<JobState, Error>

Starts a job, retrying with the same key after network errors or busy responses.

Calls POST /v1/labs/jobs

Client::jobs

pub async fn jobs(
    &self,
    document: &DocumentRef,
    page: &PageOptions,
    cancel: &CancellationToken,
) -> Result<List<JobState>, Error>

Returns a page of a document's jobs.

Calls GET /v1/labs/jobs

Client::job

pub async fn job(
    &self,
    job: &JobRef,
    cancel: &CancellationToken,
) -> Result<JobState, Error>

Returns a job's current state.

Client::cancel_job

pub async fn cancel_job(
    &self,
    job: &JobRef,
    cancel: &CancellationToken,
) -> Result<JobState, Error>

Cancels a job and returns its state.

Client::wait

pub async fn wait(
    &self,
    job: &JobRef,
    options: WaitOptions,
    cancel: &CancellationToken,
) -> Result<JobState, Error>

Checks a job until it finishes or the wait times out.

Client::notes

pub async fn notes(
    &self,
    document: &DocumentRef,
    page: &PageOptions,
    cancel: &CancellationToken,
) -> Result<List<Note>, Error>

Returns a page of a document's notes.

Calls GET /v1/labs/documents/{id}/notes

Client::add_note

pub async fn add_note(
    &self,
    document: &DocumentRef,
    request: &Request<AddNote>,
    cancel: &CancellationToken,
) -> Result<(), Error>

Adds a note to a document version.

Calls POST /v1/labs/documents/{id}/notes

Client::upload

pub async fn upload(
    &self,
    request: &Request<Upload>,
    cancel: &CancellationToken,
) -> Result<Artifact, Error>

Uploads a file to a space and returns its details.

Calls POST /v1/labs/uploads

Client::events_since

pub async fn events_since(
    &self,
    document: &DocumentRef,
    since: u64,
    limit: u16,
    cancel: &CancellationToken,
) -> Result<List<Event>, Error>

Returns up to limit document events after a cursor, without a live stream.

Calls GET /v1/labs/documents/{id}/events

Client::labs

pub fn labs(&self, session: &Session) -> Result<Client, Error>

Returns a Labs client for a session on this deployment.

Client::set_session

pub fn set_session(&self, session: &Session) -> Result<(), Error>

Switches the client to another session and cancels reads in progress.

Client::clear_session

pub fn clear_session(&self)

Signs the client out and cancels reads in progress.

Client::with_retries

pub fn with_retries(mut self, retries: RetryPolicy) -> Result<Self, Error>

Sets the retry policy, refusing values outside the allowed range.

Client::bind

pub fn bind<T>(&self, body: T) -> Result<Request<T>, Error>

Ties a request body to the current account and deployment.

Client::document_ref

pub fn document_ref(&self, space: &str, id: &str) -> Result<DocumentRef, Error>

Checks a space and ID and returns a document reference.

Client::job_ref

pub fn job_ref(&self, space: &str, id: &str) -> Result<JobRef, Error>

Checks a space and ID and returns a job reference.

Client::job_request

pub fn job_request(&self, body: CreateJob) -> Result<JobRequest, Error>

Builds a job request with a new random key.

Client::job_request_with_key

pub fn job_request_with_key(
    &self,
    body: CreateJob,
    key: RequestKey,
) -> Result<JobRequest, Error>

Builds a job request with a key you supply, such as a saved one.

Client::schedules

pub fn schedules<'a>(&'a self, session: &'a Session) -> Result<Schedules<'a>, Error>

Returns a client for the scheduled prompts on the session's account.

Error::payment_required

pub fn payment_required(&self) -> Option<&crate::PaymentRequired>

Returns the payment details when the request needs payment first.

Error::refusal

pub fn refusal(&self) -> Option<&Refusal>

Returns the server's refusal, if the server refused the request.

Error::status

pub fn status(&self) -> Option<u16>

Returns the HTTP status of a refused request.

Error::retry_after

pub fn retry_after(&self) -> Option<Duration>

Returns how long the server asked you to wait before trying again.

Events::cursor

pub fn cursor(&self) -> u64

The last event delivered to the caller, suitable for caller-owned storage.

Events::next

pub async fn next(&mut self, cancel: &CancellationToken) -> Result<Event, Error>

Waits for and returns the next event, reconnecting if the connection drops.

Calls GET /v1/labs/documents/{id}/events

JobRequest::key

pub fn key(&self) -> &RequestKey

Returns the request's key.

JobRequest::body

pub fn body(&self) -> &CreateJob

Returns the job to create.

Request::body

pub fn body(&self) -> &T

Returns the request body.

RequestKey::generate

pub fn generate() -> Result<Self, Error>

Creates a random key.

RequestKey::as_str

pub fn as_str(&self) -> &str

Returns the key as a string.