stateknot 0.1.0-alpha.1

Durable agent orchestration for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

// Copyright 2026 StateKnot contributors
// SPDX-License-Identifier: Apache-2.0

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use stateknot_core::{AgentRequest, AgentSubmissionKey, CapabilityIdentity, EventId};
use stateknot_runtime::AgentRunSnapshot;
use std::fmt;

/// Closed submission envelope. Tenant, caller, Run IDs and initial state are host-owned.
/// Persist the key and complete logical request before the first HTTP attempt.
#[derive(Clone, Deserialize, JsonSchema, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AgentHttpSubmission {
    /// Opaque tenant-scoped idempotency key, not an authentication credential.
    pub submission_key: AgentSubmissionKey,
    /// Exact installed Agent capability identity and version.
    pub agent: CapabilityIdentity,
    /// Input schema, bounded input and requested (only narrowing) budget limits.
    pub request: AgentRequest,
}

impl fmt::Debug for AgentHttpSubmission {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("AgentHttpSubmission")
            .field("agent", &self.agent)
            .finish_non_exhaustive()
    }
}

/// Closed body-based lookup; opaque submission keys never enter a URL.
#[derive(Clone, Deserialize, JsonSchema, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AgentHttpLookup {
    /// Previously retained submission identity.
    pub submission_key: AgentSubmissionKey,
}

impl fmt::Debug for AgentHttpLookup {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("AgentHttpLookup { .. }")
    }
}

/// Public v1 response; a snapshot is an observation, not an execution acknowledgement.
/// A later replay can contain a newer lifecycle revision. Terminal data appears
/// only when the durable runtime has confirmed it.
#[derive(Clone, Debug, Deserialize, JsonSchema, Serialize)]
#[serde(deny_unknown_fields)]
pub struct AgentHttpRunResponse {
    /// Fresh correlation identity; not the durable submission/cancellation key.
    pub request_id: EventId,
    /// Existing integrity-verified public snapshot, never raw journal/DB state.
    pub snapshot: AgentRunSnapshot,
}