6.22. SDK Extensions Reference¶

Version: 0.5.0 | Last updated: 2026-02-11

SDK extensions provide developer-convenience features that go beyond the normative protocol specification. These are NOT part of the core protocol; conformant SDKs are NOT REQUIRED to implement them. See spec_extensions.md for the canonical extension catalog.

6.22.1. Secret Management¶

SDKs: Python, JS/TS, Rust

Pluggable secret storage backends for managing API keys, tokens, and credentials used by agents. Local-only concern not specified in the protocol.

Backend Interface¶

All SDKs implement the same SecretsBackend interface:

Backends¶

Types¶

• Scope: Global (None/null) or named scope for secret isolation.
• SecretKey: Dotted-format string (e.g., openai.api_key). Validated on construction.
• SecretValue: String value, maximum 8 KB.
• SecretSource (enum): CLI, ENV, SCOPED, GLOBAL — indicates provenance.

Resolution Order¶

The Resolver resolves secrets with the following precedence:

1. Explicit value (passed programmatically)
2. Environment variable (e.g., SW4RM_SECRET_OPENAI_API_KEY)
3. Scoped secret (from backend)
4. Global secret (from backend)

Factory¶

select_backend(mode?) auto-selects the best backend:

• auto (default): Prefers keyring if available, falls back to file.
• file: Force JSON file backend.
• keyring: Force OS keyring backend.

Override via environment variable: SW4RM_SECRETS_BACKEND.

from sw4rm.secrets import Secrets, Scope, SecretKey, SecretValue

secrets = Secrets()  # auto-selects backend
secrets.set(Scope("myproject"), SecretKey("openai.api_key"), SecretValue("sk-..."))
value = secrets.get(Scope("myproject"), SecretKey("openai.api_key"))

use sw4rm_sdk::secrets::{Secrets, Scope, SecretKey, SecretValue};

let secrets = Secrets::new(None)?;  // auto-selects backend
secrets.set(&Scope::new("myproject"), &SecretKey::new("openai.api_key"), &SecretValue::new("sk-...")?)?;
let value = secrets.get(&Scope::new("myproject"), &SecretKey::new("openai.api_key"))?;

import { Secrets, Scope, SecretKey, SecretValue } from '@sw4rm/js-sdk';

const secrets = await Secrets.create();  // auto-selects backend
await secrets.set(new Scope('myproject'), new SecretKey('openai.api_key'), new SecretValue('sk-...'));
const value = await secrets.get(new Scope('myproject'), new SecretKey('openai.api_key'));

6.22.2. Negotiation Room Store¶

SDKs: Python, JS/TS, Rust

Local persistent storage for negotiation room state. The spec defines the negotiation protocol (§17.5) but does not prescribe local state management. See Negotiation Room Client for usage.

Store Interface¶

Implementations¶

6.22.3. Negotiation Coordinator¶

SDK: Python only

Policy-based decision coordination for multi-agent negotiation. Provides automated scoring, threshold-based auto-approval, and coordinator-role orchestration on top of the spec's Negotiation Room pattern (§17.5).

Key Methods¶

from sw4rm.negotiation_coordinator import NegotiationCoordinator

coordinator = NegotiationCoordinator()
outcome = coordinator.apply_policy(aggregated_scores, policy)
reason = coordinator.generate_decision_reason(outcome, aggregated_scores, votes, policy)

6.22.4. Shared Context Manager¶

SDK: Python only

Optimistic-locking shared context store for concurrent agent access. Not part of the protocol; agents communicate shared state via messages per spec. See Shared Context Manager Client for the full API reference.

Key Features¶

• Optimistic locking: update() requires expected_version; raises ValueError on conflict.
• Explicit locking: lock(context_id, agent_id) blocks updates from other agents.
• Version tracking: Versions auto-increment on each update.

6.22.5. Feature Flags¶

SDK: Python only

Runtime feature flag system for SDK behavior toggles. Allows enabling/disabling experimental features without code changes.

Built-in Flags¶

Resolution Order¶

1. Programmatic overrides (set_flag())
2. Environment variables (SW4RM_FEATURE_*, e.g., SW4RM_FEATURE_ENABLE_WORKFLOW=true)
3. Config dictionary (passed at construction)
4. Default value

from sw4rm.feature_flags import get_feature_flags

flags = get_feature_flags()
if flags.is_enabled("ENABLE_WORKFLOW"):
    # workflow-specific logic
    pass

flags.set_flag("ENABLE_AUDIT", True)

6.22.6. Content Types¶

SDK: Python only

Vendor-specific MIME type constants (application/vnd.sw4rm.*) extending the spec-required application/json and application/protobuf support. See Content Types for the protocol-level reference.

Vendor Content Types¶

Content Type Registry¶

The ContentTypeRegistry provides registration, schema validation, and parsing:

from sw4rm.content_types import get_default_registry, register_standard_types

registry = get_default_registry()
register_standard_types(registry)

# Register custom type
registry.register("application/vnd.myapp.data+json", schema={"type": "object"})
valid = registry.validate("application/vnd.myapp.data+json", payload)

6.22.7. Preemption Manager¶

SDK: Rust only

Cooperative agent preemption with cancellation tokens and safe-point checking. The spec defines preemption semantics (RUNNING → SUSPENDED, §8) but does not prescribe the cooperative implementation pattern.

Key API¶

use sw4rm_sdk::runtime::PreemptionManager;

let pm = PreemptionManager::new();
let pm_clone = pm.clone(); // share with spawned task

// In agent processing loop:
loop {
    if pm.is_preemption_requested() {
        println!("Preempted: {:?}", pm.preemption_reason());
        break;
    }
    // Safe point — do work
    {
        let _guard = pm.non_preemptible(); // critical section
        // non-preemptible work here
    }
}

6.22.8. CONTROL Message Content Types¶

SDK: JS/TS only

Custom content-type constants and codecs for CONTROL messages. The spec defines the CONTROL MessageType but does not enumerate content-type subtypes.

Constants¶

Interfaces¶

SchedulerCommandV1: { stage: 'prompt' | 'plan' | 'run', input?: unknown }

AgentReportV1: { agent_id?, stage?, success?, files?: AgentReportFileV1[], logs?, error? }

import { encodeSchedulerCommandV1, decodeAgentReportV1 } from '@sw4rm/js-sdk/internal/control';

const payload = encodeSchedulerCommandV1({ stage: 'run', input: { task: 'analyze' } });
const report = decodeAgentReportV1(receivedPayload);

6.22.9. Colony / Agent Spawning¶

SDK: Python only

Agent thread spawning infrastructure (colony/ module). Provides lifecycle management for dynamically spawned agents. Application-level concern not specified in the protocol.

Spawn Modes¶

Agent Lifecycle¶

SPAWNING → STARTING → READY → BUSY → TERMINATING → TERMINATED

Error states: UNHEALTHY, FAILED

Key API¶

from sw4rm.colony.spawner import ThreadSpawner, SpawnerConfig

spawner = ThreadSpawner(max_agents=50)
config = SpawnerConfig(
    agent_role="critic",
    agent_type="code_reviewer",
    capabilities=["code_review", "security_audit"],
)
handle = spawner.spawn_agent(config)
spawner.wait_ready(handle.agent_id, timeout_s=10.0)

6.22.10. LLM Integration¶

SDK: Python only

Claude SDK adapter (llm/ module) for integrating language model inference into agent decision-making. Protocol-agnostic; the spec does not prescribe inference engine integration.

Client Interface¶

Implementations¶

Factory¶

from sw4rm.llm import create_llm_client

# Auto-selects based on LLM_CLIENT_TYPE env var (default: "claude_sdk")
client = create_llm_client(model="sonnet")
response = await client.query("Analyze this code for security issues")
print(response.content, response.model, response.usage)

Error Hierarchy¶

LLMError → LLMAuthenticationError | LLMRateLimitError | LLMTimeoutError | LLMContextLengthError

6.22.11. Envelope-Level Message Tracking¶

SDK: Python (extended), Rust (basic)

The Python ActivityBuffer tracks individual envelopes beyond the spec-mandated task-level entries (§10). This provides finer-grained observability.

Extended ActivityRecord Fields¶

The buffer indexes by idempotency_token for deduplication support per §11.2.

6.22.12. Extended Envelope Fields¶

SDKs: Python (implemented), JS/TS and Rust (added for parity)

These envelope fields extend the proto-defined Envelope message. They are carried as SDK-level metadata until the proto is updated.

use sw4rm_sdk::envelope::EnvelopeBuilder;

let envelope = EnvelopeBuilder::new(/* ... */)
    .with_effective_policy_id("policy-abc".to_string())
    .with_audit_proof(proof_bytes)
    .with_audit_policy_id("audit-policy-1".to_string())
    .build();

import { buildEnvelope } from '@sw4rm/js-sdk';

const envelope = buildEnvelope({
  // ...standard fields...
  effective_policy_id: 'policy-abc',
  audit_proof: proofBytes,
  audit_policy_id: 'audit-policy-1',
});

6.22.13. Voting / Aggregation Analytics¶

SDKs: Python, JS/TS, Rust

The VotingAggregator provides analytics on top of the four aggregation strategies. The spec (§17.4) defines the strategies; the analytics layer is an SDK extension. See Voting Strategies for the protocol reference.

Aggregation Strategies¶

Analytics Methods (Python)¶

from sw4rm.voting.aggregation import VotingAggregator
from sw4rm.voting.strategies import ConfidenceWeightedAggregator

aggregator = VotingAggregator(strategy=ConfidenceWeightedAggregator())
score = aggregator.aggregate(votes)
summary = aggregator.get_vote_summary(votes)

if aggregator.detect_polarization(votes):
    print("Votes are polarized — consider HITL escalation")

6.22.14. Persistence Backends¶

SDKs: Python, JS/TS, Rust

JSON file-based persistence for activity buffer, worktree bindings, and configuration. The spec does not prescribe persistence mechanisms. See Persistence quickstart for setup guidance.

Backend Interface (Python)¶

Implementations¶

from sw4rm.persistence import JSONFilePersistence
from sw4rm.activity_buffer import ActivityBuffer

persistence = JSONFilePersistence("my_agent_activity.json")
buffer = ActivityBuffer(max_items=10000)

# Save buffer state
persistence.save_records(buffer.to_dict(), buffer.order())

# Restore on restart
records, order = persistence.load_records()
buffer.restore(records, order)