@aumos/agent-sovereign 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,106 @@
+/**
+ * HTTP client for the agent-sovereign deployment management API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSovereignClient } from "@aumos/agent-sovereign";
+ *
+ * const client = createAgentSovereignClient({ baseUrl: "http://localhost:8092" });
+ *
+ * const status = await client.getSovereigntyStatus("my-edge-node");
+ *
+ * if (status.ok) {
+ *   console.log("Sovereignty level:", status.data.sovereignty_level);
+ * }
+ * ```
+ */
+import type { ApiResult, DeploymentBundle, EdgeRuntime, OfflineCapability, PackagerConfig, PerformanceEstimate, ResourceValidationResult, SovereigntyLevel, SovereigntyStatus, SyncConfig, SyncStateRequest, SyncTask } from "./types.js";
+/** Configuration options for the AgentSovereignClient. */
+export interface AgentSovereignClientConfig {
+    /** Base URL of the agent-sovereign server (e.g. "http://localhost:8092"). */
+    readonly baseUrl: string;
+    /** Optional request timeout in milliseconds (default: 30000). */
+    readonly timeoutMs?: number;
+    /** Optional extra HTTP headers sent with every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Typed HTTP client for the agent-sovereign server. */
+export interface AgentSovereignClient {
+    /**
+     * Create a signed deployment bundle for a sovereign agent.
+     *
+     * @param config - Packager configuration including sovereignty level and file sources.
+     * @returns The assembled DeploymentBundle with manifest and checksum.
+     */
+    createBundle(config: PackagerConfig): Promise<ApiResult<DeploymentBundle>>;
+    /**
+     * Deploy an agent bundle to an edge runtime.
+     *
+     * @param options - Bundle checksum, target edge node ID, and optional runtime overrides.
+     * @returns The EdgeRuntime configuration that was applied.
+     */
+    deployEdge(options: {
+        bundle_checksum: string;
+        edge_node_id: string;
+        sovereignty_level: SovereigntyLevel;
+        runtime_overrides?: Partial<EdgeRuntime>;
+    }): Promise<ApiResult<EdgeRuntime>>;
+    /**
+     * Get the current sovereignty status of an edge node.
+     *
+     * @param edgeNodeId - The edge node identifier.
+     * @returns A SovereigntyStatus with current level, connectivity, and pending tasks.
+     */
+    getSovereigntyStatus(edgeNodeId: string): Promise<ApiResult<SovereigntyStatus>>;
+    /**
+     * Queue a state synchronisation task for an edge node.
+     *
+     * @param edgeNodeId - The edge node to sync.
+     * @param request - Sync task specification.
+     * @returns The created SyncTask record.
+     */
+    syncState(edgeNodeId: string, request: SyncStateRequest): Promise<ApiResult<SyncTask>>;
+    /**
+     * Get the offline capabilities of an edge deployment.
+     *
+     * @param edgeNodeId - The edge node identifier.
+     * @returns The OfflineCapability descriptor for this deployment.
+     */
+    getOfflineCapabilities(edgeNodeId: string): Promise<ApiResult<OfflineCapability>>;
+    /**
+     * Validate resources for an edge runtime configuration.
+     *
+     * @param runtime - The EdgeRuntime configuration to validate.
+     * @returns A ResourceValidationResult with errors and warnings.
+     */
+    validateResources(runtime: EdgeRuntime): Promise<ApiResult<ResourceValidationResult>>;
+    /**
+     * Estimate inference performance for a model on an edge runtime.
+     *
+     * @param options - Edge runtime config and model size in billions of parameters.
+     * @returns A PerformanceEstimate with tokens/sec and latency projections.
+     */
+    estimatePerformance(options: {
+        runtime: EdgeRuntime;
+        model_parameter_count_billions: number;
+    }): Promise<ApiResult<PerformanceEstimate>>;
+    /**
+     * Update the synchronisation policy for an edge node.
+     *
+     * @param edgeNodeId - The edge node identifier.
+     * @param policy - The new SyncConfig to apply.
+     * @returns The updated SyncConfig.
+     */
+    updateSyncPolicy(edgeNodeId: string, policy: SyncConfig): Promise<ApiResult<SyncConfig>>;
+}
+/**
+ * Create a typed HTTP client for the agent-sovereign server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentSovereignClient instance.
+ */
+export declare function createAgentSovereignClient(config: AgentSovereignClientConfig): AgentSovereignClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAEV,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACT,MAAM,YAAY,CAAC;AAMpB,0DAA0D;AAC1D,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AA0DD,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAE3E;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE;QAClB,eAAe,EAAE,MAAM,CAAC;QACxB,YAAY,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,gBAAgB,CAAC;QACpC,iBAAiB,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;KAC1C,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAEpC;;;;;OAKG;IACH,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAEhF;;;;;;OAMG;IACH,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEhC;;;;;OAKG;IACH,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAElF;;;;;OAKG;IACH,iBAAiB,CACf,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,SAAS,CAAC,wBAAwB,CAAC,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,mBAAmB,CAAC,OAAO,EAAE;QAC3B,OAAO,EAAE,WAAW,CAAC;QACrB,8BAA8B,EAAE,MAAM,CAAC;KACxC,GAAG,OAAO,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAE5C;;;;;;OAMG;IACH,gBAAgB,CACd,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;CACnC;AAMD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,0BAA0B,GACjC,oBAAoB,CAmHtB"}

package/dist/client.js

@@ -0,0 +1,123 @@
+/**
+ * HTTP client for the agent-sovereign deployment management API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSovereignClient } from "@aumos/agent-sovereign";
+ *
+ * const client = createAgentSovereignClient({ baseUrl: "http://localhost:8092" });
+ *
+ * const status = await client.getSovereigntyStatus("my-edge-node");
+ *
+ * if (status.ok) {
+ *   console.log("Sovereignty level:", status.data.sovereignty_level);
+ * }
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function fetchJson(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeoutId);
+        const body = await response.json();
+        if (!response.ok) {
+            const errorBody = body;
+            return {
+                ok: false,
+                error: {
+                    error: errorBody.error ?? "Unknown error",
+                    detail: errorBody.detail ?? "",
+                },
+                status: response.status,
+            };
+        }
+        return { ok: true, data: body };
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: { error: "Network error", detail: message },
+            status: 0,
+        };
+    }
+}
+function buildHeaders(extraHeaders) {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...extraHeaders,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a typed HTTP client for the agent-sovereign server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentSovereignClient instance.
+ */
+export function createAgentSovereignClient(config) {
+    const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+    const baseHeaders = buildHeaders(extraHeaders);
+    return {
+        async createBundle(packagerConfig) {
+            return fetchJson(`${baseUrl}/sovereign/bundles`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(packagerConfig),
+            }, timeoutMs);
+        },
+        async deployEdge(options) {
+            return fetchJson(`${baseUrl}/sovereign/edge/deploy`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(options),
+            }, timeoutMs);
+        },
+        async getSovereigntyStatus(edgeNodeId) {
+            return fetchJson(`${baseUrl}/sovereign/edge/${encodeURIComponent(edgeNodeId)}/status`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async syncState(edgeNodeId, request) {
+            return fetchJson(`${baseUrl}/sovereign/edge/${encodeURIComponent(edgeNodeId)}/sync`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async getOfflineCapabilities(edgeNodeId) {
+            return fetchJson(`${baseUrl}/sovereign/edge/${encodeURIComponent(edgeNodeId)}/offline`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async validateResources(runtime) {
+            return fetchJson(`${baseUrl}/sovereign/edge/validate-resources`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(runtime),
+            }, timeoutMs);
+        },
+        async estimatePerformance(options) {
+            return fetchJson(`${baseUrl}/sovereign/edge/estimate-performance`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(options),
+            }, timeoutMs);
+        },
+        async updateSyncPolicy(edgeNodeId, policy) {
+            return fetchJson(`${baseUrl}/sovereign/edge/${encodeURIComponent(edgeNodeId)}/sync-policy`, {
+                method: "PUT",
+                headers: baseHeaders,
+                body: JSON.stringify(policy),
+            }, timeoutMs);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @aumos/agent-sovereign
+ *
+ * TypeScript client for the AumOS agent-sovereign deployment manager.
+ * Provides HTTP client, sovereignty level types, edge runtime configuration,
+ * offline capabilities, and state synchronisation type definitions.
+ */
+export type { AgentSovereignClient, AgentSovereignClientConfig } from "./client.js";
+export { createAgentSovereignClient } from "./client.js";
+export type { ApiError, ApiResult, DeploymentBundle, DeploymentManifest, EdgeRuntime, OfflineCapability, OfflineStatus, PackagerConfig, PerformanceEstimate, QuantizationLevel, ResourceValidationResult, SovereigntyLevel, SovereigntyLevelValue, SovereigntyStatus, SyncConfig, SyncPriority, SyncStateRequest, SyncTask, SyncTaskStatus, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAGzD,YAAY,EACV,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,QAAQ,EACR,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @aumos/agent-sovereign
+ *
+ * TypeScript client for the AumOS agent-sovereign deployment manager.
+ * Provides HTTP client, sovereignty level types, edge runtime configuration,
+ * offline capabilities, and state synchronisation type definitions.
+ */
+export { createAgentSovereignClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * TypeScript interfaces for the agent-sovereign deployment manager.
+ *
+ * Mirrors the Python dataclasses and enums defined in:
+ *   agent_sovereign.classifier.levels   (SovereigntyLevel)
+ *   agent_sovereign.edge.runtime        (QuantizationLevel, EdgeConfig, ResourceValidationResult, PerformanceEstimate)
+ *   agent_sovereign.edge.sync           (SyncPriority, SyncTaskStatus, SyncPolicy, SyncTask)
+ *   agent_sovereign.edge.offline        (OfflineStatus, OfflineCapability, CachedResponse)
+ *   agent_sovereign.deployment.packager (DeploymentManifest, DeploymentBundle)
+ *
+ * All interfaces use readonly fields to match Python frozen dataclasses.
+ */
+/**
+ * Sovereignty levels from least (cloud) to most (air-gapped) sovereign.
+ * Maps to SovereigntyLevel IntEnum in Python.
+ */
+export type SovereigntyLevel = "L1_CLOUD" | "L2_CLOUD_DEDICATED" | "L3_HYBRID" | "L4_LOCAL_AUGMENTED" | "L5_FULLY_LOCAL" | "L6_CLASSIFIED" | "L7_AIRGAPPED";
+/** Numeric value (1–7) associated with a sovereignty level. */
+export type SovereigntyLevelValue = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/**
+ * Supported model quantization levels for edge inference.
+ * Maps to QuantizationLevel enum in Python.
+ */
+export type QuantizationLevel = "none" | "int8" | "int4" | "gguf_q4_k_m" | "gguf_q5_k_m" | "gguf_q8_0";
+/** Configuration for an edge runtime environment. */
+export interface EdgeRuntime {
+    /** Maximum RAM available for model and inference (MiB). */
+    readonly max_memory_mb: number;
+    /** Maximum CPU utilisation percentage (0–100) allowed. */
+    readonly max_cpu_percent: number;
+    /** Quantization level to apply to loaded models. */
+    readonly model_quantization: QuantizationLevel;
+    /** Whether this edge node can operate without network connectivity. */
+    readonly offline_capable: boolean;
+    /** Maximum number of simultaneous inference requests. */
+    readonly max_concurrent_requests: number;
+    /** Path to the directory where model weights are cached locally. */
+    readonly model_cache_dir: string;
+    /** GPU memory available in MiB (0 if no GPU present). */
+    readonly gpu_memory_mb: number;
+    /** Whether to cache model activations across requests. */
+    readonly enable_model_caching: boolean;
+    /** How often the edge node sends a heartbeat in seconds. */
+    readonly heartbeat_interval_seconds: number;
+}
+/** Result of a resource validation check for an EdgeRuntime. */
+export interface ResourceValidationResult {
+    /** True if all resource requirements are met. */
+    readonly is_valid: boolean;
+    /** Non-fatal issues detected during validation. */
+    readonly warnings: readonly string[];
+    /** Fatal issues that prevent the runtime from operating correctly. */
+    readonly errors: readonly string[];
+    /** Detected available system memory in MiB. */
+    readonly available_memory_mb: number;
+    /** Detected logical CPU count. */
+    readonly available_cpu_count: number;
+}
+/** Estimated inference performance for an edge configuration. */
+export interface PerformanceEstimate {
+    /** Estimated token generation rate (tokens/second). */
+    readonly tokens_per_second: number;
+    /** Estimated latency to the first output token in milliseconds. */
+    readonly time_to_first_token_ms: number;
+    /** Estimated maximum context length supported given memory constraints. */
+    readonly max_context_tokens: number;
+    /** Estimated throughput multiplier from quantization (1.0 = no speedup). */
+    readonly quantization_speedup_factor: number;
+    /** Explanatory notes about the estimate. */
+    readonly notes: readonly string[];
+}
+/** Structured manifest describing a deployment package. */
+export interface DeploymentManifest {
+    /** Unique identifier for this package. */
+    readonly package_id: string;
+    /** ISO-8601 timestamp of package creation. */
+    readonly created_at: string;
+    /** The sovereignty level this package targets. */
+    readonly sovereignty_level: string;
+    /** Name of the deployment template used. */
+    readonly template_name: string;
+    /** List of relative file paths included in the bundle. */
+    readonly files: readonly string[];
+    /** Additional key/value metadata attached to this package. */
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/** A complete deployment bundle ready for transfer or installation. */
+export interface DeploymentBundle {
+    /** Structured manifest document for the package. */
+    readonly manifest: DeploymentManifest;
+    /** Resolved list of file paths included. */
+    readonly files_list: readonly string[];
+    /** SHA-256 hex digest of the serialised manifest. */
+    readonly checksum: string;
+    /** The sovereignty level this package targets. */
+    readonly sovereignty_level: SovereigntyLevel;
+    /** The raw YAML string of the manifest. */
+    readonly manifest_yaml: string;
+}
+/** Configuration for creating a deployment bundle. */
+export interface PackagerConfig {
+    /** The target sovereignty level for the deployment. */
+    readonly sovereignty_level: SovereigntyLevel;
+    /** Optional explicit package identifier. */
+    readonly package_id?: string;
+    /** Optional additional key/value pairs to embed in the manifest. */
+    readonly metadata?: Readonly<Record<string, string>>;
+    /** Optional source directory path to scan for files. */
+    readonly source_directory?: string;
+    /** Optional explicit list of file paths to include. */
+    readonly explicit_files?: readonly string[];
+}
+/**
+ * Priority level for a sync task.
+ * Maps to SyncPriority enum in Python.
+ */
+export type SyncPriority = "critical" | "high" | "normal" | "low";
+/**
+ * Lifecycle state of a sync task.
+ * Maps to SyncTaskStatus enum in Python.
+ */
+export type SyncTaskStatus = "pending" | "in_progress" | "completed" | "failed" | "skipped";
+/** Policy governing when and how synchronisation may occur. */
+export interface SyncConfig {
+    /** Whether sync tasks may run in the background. */
+    readonly allow_background_sync: boolean;
+    /** Maximum number of retry attempts for a failed sync task. */
+    readonly max_retry_attempts: number;
+    /** Base backoff interval in seconds between retry attempts. */
+    readonly retry_backoff_seconds: number;
+    /** UTC hour (0–23) at which the sync window opens. -1 means any time. */
+    readonly sync_window_start_hour: number;
+    /** UTC hour (0–23) at which the sync window closes. -1 means any time. */
+    readonly sync_window_end_hour: number;
+    /** Whether sync must only proceed over an encrypted channel. */
+    readonly require_encrypted_channel: boolean;
+    /** Maximum size of a single sync payload in MiB. */
+    readonly max_payload_size_mb: number;
+    /** If non-empty, only sync tasks with a type in this list are allowed. */
+    readonly allowed_sync_types: readonly string[];
+}
+/** A single unit of work to synchronise. */
+export interface SyncTask {
+    /** Unique identifier for this sync task. */
+    readonly task_id: string;
+    /** Category of sync (e.g. "model_update", "audit_log"). */
+    readonly sync_type: string;
+    /** Human-readable description of what this task syncs. */
+    readonly payload_description: string;
+    /** Task priority affecting processing order. */
+    readonly priority: SyncPriority;
+    /** Current lifecycle state. */
+    readonly status: SyncTaskStatus;
+    /** ISO-8601 UTC timestamp of task creation. */
+    readonly created_at: string;
+    /** ISO-8601 UTC timestamp of last status change. */
+    readonly updated_at: string;
+    /** Number of retry attempts made so far. */
+    readonly retry_count: number;
+    /** Last error message if the task failed. */
+    readonly error_message: string;
+    /** Arbitrary key/value metadata attached to this task. */
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/** Request payload for queueing a sync task. */
+export interface SyncStateRequest {
+    /** Category of the sync task. */
+    readonly sync_type: string;
+    /** Human-readable description of what will be synced. */
+    readonly payload_description: string;
+    /** Task priority. */
+    readonly priority?: SyncPriority;
+    /** Optional metadata key/value pairs. */
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/**
+ * Current connectivity status of the edge node.
+ * Maps to OfflineStatus enum in Python.
+ */
+export type OfflineStatus = "online" | "offline" | "degraded";
+/** Describes the offline operation capabilities of an edge deployment. */
+export interface OfflineCapability {
+    /** Whether the node can return cached responses when offline. */
+    readonly can_serve_cached_responses: boolean;
+    /** Whether local model inference is available without network. */
+    readonly can_run_local_inference: boolean;
+    /** Whether write operations can be queued for later sync. */
+    readonly can_queue_writes: boolean;
+    /** Maximum hours the node should operate offline. -1 = indefinite. */
+    readonly max_offline_duration_hours: number;
+    /** Time-to-live for cached responses in hours. */
+    readonly cache_ttl_hours: number;
+    /** Operation types available in degraded/offline mode. */
+    readonly supported_degraded_operations: readonly string[];
+}
+/** Current sovereignty status of an edge deployment. */
+export interface SovereigntyStatus {
+    /** The sovereignty level currently in effect. */
+    readonly sovereignty_level: SovereigntyLevel;
+    /** Current connectivity status. */
+    readonly offline_status: OfflineStatus;
+    /** Number of sync tasks currently pending. */
+    readonly pending_sync_tasks: number;
+    /** Whether resource validation has passed. */
+    readonly resources_valid: boolean;
+    /** ISO-8601 UTC timestamp of the last status check. */
+    readonly checked_at: string;
+}
+/** Standard error payload returned by the agent-sovereign API. */
+export interface ApiError {
+    readonly error: string;
+    readonly detail: string;
+}
+/** Result type for all client operations. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: ApiError;
+    readonly status: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * TypeScript interfaces for the agent-sovereign deployment manager.
+ *
+ * Mirrors the Python dataclasses and enums defined in:
+ *   agent_sovereign.classifier.levels   (SovereigntyLevel)
+ *   agent_sovereign.edge.runtime        (QuantizationLevel, EdgeConfig, ResourceValidationResult, PerformanceEstimate)
+ *   agent_sovereign.edge.sync           (SyncPriority, SyncTaskStatus, SyncPolicy, SyncTask)
+ *   agent_sovereign.edge.offline        (OfflineStatus, OfflineCapability, CachedResponse)
+ *   agent_sovereign.deployment.packager (DeploymentManifest, DeploymentBundle)
+ *
+ * All interfaces use readonly fields to match Python frozen dataclasses.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aumos/agent-sovereign",
+  "version": "0.1.0",
+  "description": "TypeScript client for the AumOS agent-sovereign deployment manager — sovereignty levels, edge runtimes, offline capabilities, and state synchronisation",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "aumos",
+    "agent-sovereign",
+    "sovereignty",
+    "edge",
+    "offline",
+    "deployment",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aumos-ai/agent-sovereign"
+  }
+}

package/src/client.ts

@@ -0,0 +1,320 @@
+/**
+ * HTTP client for the agent-sovereign deployment management API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentSovereignClient } from "@aumos/agent-sovereign";
+ *
+ * const client = createAgentSovereignClient({ baseUrl: "http://localhost:8092" });
+ *
+ * const status = await client.getSovereigntyStatus("my-edge-node");
+ *
+ * if (status.ok) {
+ *   console.log("Sovereignty level:", status.data.sovereignty_level);
+ * }
+ * ```
+ */
+
+import type {
+  ApiError,
+  ApiResult,
+  DeploymentBundle,
+  EdgeRuntime,
+  OfflineCapability,
+  PackagerConfig,
+  PerformanceEstimate,
+  ResourceValidationResult,
+  SovereigntyLevel,
+  SovereigntyStatus,
+  SyncConfig,
+  SyncStateRequest,
+  SyncTask,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration options for the AgentSovereignClient. */
+export interface AgentSovereignClientConfig {
+  /** Base URL of the agent-sovereign server (e.g. "http://localhost:8092"). */
+  readonly baseUrl: string;
+  /** Optional request timeout in milliseconds (default: 30000). */
+  readonly timeoutMs?: number;
+  /** Optional extra HTTP headers sent with every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function fetchJson<T>(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<ApiResult<T>> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    const body = await response.json() as unknown;
+
+    if (!response.ok) {
+      const errorBody = body as Partial<ApiError>;
+      return {
+        ok: false,
+        error: {
+          error: errorBody.error ?? "Unknown error",
+          detail: errorBody.detail ?? "",
+        },
+        status: response.status,
+      };
+    }
+
+    return { ok: true, data: body as T };
+  } catch (err: unknown) {
+    clearTimeout(timeoutId);
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: { error: "Network error", detail: message },
+      status: 0,
+    };
+  }
+}
+
+function buildHeaders(
+  extraHeaders: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Client interface
+// ---------------------------------------------------------------------------
+
+/** Typed HTTP client for the agent-sovereign server. */
+export interface AgentSovereignClient {
+  /**
+   * Create a signed deployment bundle for a sovereign agent.
+   *
+   * @param config - Packager configuration including sovereignty level and file sources.
+   * @returns The assembled DeploymentBundle with manifest and checksum.
+   */
+  createBundle(config: PackagerConfig): Promise<ApiResult<DeploymentBundle>>;
+
+  /**
+   * Deploy an agent bundle to an edge runtime.
+   *
+   * @param options - Bundle checksum, target edge node ID, and optional runtime overrides.
+   * @returns The EdgeRuntime configuration that was applied.
+   */
+  deployEdge(options: {
+    bundle_checksum: string;
+    edge_node_id: string;
+    sovereignty_level: SovereigntyLevel;
+    runtime_overrides?: Partial<EdgeRuntime>;
+  }): Promise<ApiResult<EdgeRuntime>>;
+
+  /**
+   * Get the current sovereignty status of an edge node.
+   *
+   * @param edgeNodeId - The edge node identifier.
+   * @returns A SovereigntyStatus with current level, connectivity, and pending tasks.
+   */
+  getSovereigntyStatus(edgeNodeId: string): Promise<ApiResult<SovereigntyStatus>>;
+
+  /**
+   * Queue a state synchronisation task for an edge node.
+   *
+   * @param edgeNodeId - The edge node to sync.
+   * @param request - Sync task specification.
+   * @returns The created SyncTask record.
+   */
+  syncState(
+    edgeNodeId: string,
+    request: SyncStateRequest,
+  ): Promise<ApiResult<SyncTask>>;
+
+  /**
+   * Get the offline capabilities of an edge deployment.
+   *
+   * @param edgeNodeId - The edge node identifier.
+   * @returns The OfflineCapability descriptor for this deployment.
+   */
+  getOfflineCapabilities(edgeNodeId: string): Promise<ApiResult<OfflineCapability>>;
+
+  /**
+   * Validate resources for an edge runtime configuration.
+   *
+   * @param runtime - The EdgeRuntime configuration to validate.
+   * @returns A ResourceValidationResult with errors and warnings.
+   */
+  validateResources(
+    runtime: EdgeRuntime,
+  ): Promise<ApiResult<ResourceValidationResult>>;
+
+  /**
+   * Estimate inference performance for a model on an edge runtime.
+   *
+   * @param options - Edge runtime config and model size in billions of parameters.
+   * @returns A PerformanceEstimate with tokens/sec and latency projections.
+   */
+  estimatePerformance(options: {
+    runtime: EdgeRuntime;
+    model_parameter_count_billions: number;
+  }): Promise<ApiResult<PerformanceEstimate>>;
+
+  /**
+   * Update the synchronisation policy for an edge node.
+   *
+   * @param edgeNodeId - The edge node identifier.
+   * @param policy - The new SyncConfig to apply.
+   * @returns The updated SyncConfig.
+   */
+  updateSyncPolicy(
+    edgeNodeId: string,
+    policy: SyncConfig,
+  ): Promise<ApiResult<SyncConfig>>;
+}
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a typed HTTP client for the agent-sovereign server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentSovereignClient instance.
+ */
+export function createAgentSovereignClient(
+  config: AgentSovereignClientConfig,
+): AgentSovereignClient {
+  const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+  const baseHeaders = buildHeaders(extraHeaders);
+
+  return {
+    async createBundle(
+      packagerConfig: PackagerConfig,
+    ): Promise<ApiResult<DeploymentBundle>> {
+      return fetchJson<DeploymentBundle>(
+        `${baseUrl}/sovereign/bundles`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(packagerConfig),
+        },
+        timeoutMs,
+      );
+    },
+
+    async deployEdge(options: {
+      bundle_checksum: string;
+      edge_node_id: string;
+      sovereignty_level: SovereigntyLevel;
+      runtime_overrides?: Partial<EdgeRuntime>;
+    }): Promise<ApiResult<EdgeRuntime>> {
+      return fetchJson<EdgeRuntime>(
+        `${baseUrl}/sovereign/edge/deploy`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(options),
+        },
+        timeoutMs,
+      );
+    },
+
+    async getSovereigntyStatus(
+      edgeNodeId: string,
+    ): Promise<ApiResult<SovereigntyStatus>> {
+      return fetchJson<SovereigntyStatus>(
+        `${baseUrl}/sovereign/edge/${encodeURIComponent(edgeNodeId)}/status`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async syncState(
+      edgeNodeId: string,
+      request: SyncStateRequest,
+    ): Promise<ApiResult<SyncTask>> {
+      return fetchJson<SyncTask>(
+        `${baseUrl}/sovereign/edge/${encodeURIComponent(edgeNodeId)}/sync`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async getOfflineCapabilities(
+      edgeNodeId: string,
+    ): Promise<ApiResult<OfflineCapability>> {
+      return fetchJson<OfflineCapability>(
+        `${baseUrl}/sovereign/edge/${encodeURIComponent(edgeNodeId)}/offline`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async validateResources(
+      runtime: EdgeRuntime,
+    ): Promise<ApiResult<ResourceValidationResult>> {
+      return fetchJson<ResourceValidationResult>(
+        `${baseUrl}/sovereign/edge/validate-resources`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(runtime),
+        },
+        timeoutMs,
+      );
+    },
+
+    async estimatePerformance(options: {
+      runtime: EdgeRuntime;
+      model_parameter_count_billions: number;
+    }): Promise<ApiResult<PerformanceEstimate>> {
+      return fetchJson<PerformanceEstimate>(
+        `${baseUrl}/sovereign/edge/estimate-performance`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(options),
+        },
+        timeoutMs,
+      );
+    },
+
+    async updateSyncPolicy(
+      edgeNodeId: string,
+      policy: SyncConfig,
+    ): Promise<ApiResult<SyncConfig>> {
+      return fetchJson<SyncConfig>(
+        `${baseUrl}/sovereign/edge/${encodeURIComponent(edgeNodeId)}/sync-policy`,
+        {
+          method: "PUT",
+          headers: baseHeaders,
+          body: JSON.stringify(policy),
+        },
+        timeoutMs,
+      );
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @aumos/agent-sovereign
+ *
+ * TypeScript client for the AumOS agent-sovereign deployment manager.
+ * Provides HTTP client, sovereignty level types, edge runtime configuration,
+ * offline capabilities, and state synchronisation type definitions.
+ */
+
+// Client and configuration
+export type { AgentSovereignClient, AgentSovereignClientConfig } from "./client.js";
+export { createAgentSovereignClient } from "./client.js";
+
+// Core types
+export type {
+  ApiError,
+  ApiResult,
+  DeploymentBundle,
+  DeploymentManifest,
+  EdgeRuntime,
+  OfflineCapability,
+  OfflineStatus,
+  PackagerConfig,
+  PerformanceEstimate,
+  QuantizationLevel,
+  ResourceValidationResult,
+  SovereigntyLevel,
+  SovereigntyLevelValue,
+  SovereigntyStatus,
+  SyncConfig,
+  SyncPriority,
+  SyncStateRequest,
+  SyncTask,
+  SyncTaskStatus,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,278 @@
+/**
+ * TypeScript interfaces for the agent-sovereign deployment manager.
+ *
+ * Mirrors the Python dataclasses and enums defined in:
+ *   agent_sovereign.classifier.levels   (SovereigntyLevel)
+ *   agent_sovereign.edge.runtime        (QuantizationLevel, EdgeConfig, ResourceValidationResult, PerformanceEstimate)
+ *   agent_sovereign.edge.sync           (SyncPriority, SyncTaskStatus, SyncPolicy, SyncTask)
+ *   agent_sovereign.edge.offline        (OfflineStatus, OfflineCapability, CachedResponse)
+ *   agent_sovereign.deployment.packager (DeploymentManifest, DeploymentBundle)
+ *
+ * All interfaces use readonly fields to match Python frozen dataclasses.
+ */
+
+// ---------------------------------------------------------------------------
+// Sovereignty level
+// ---------------------------------------------------------------------------
+
+/**
+ * Sovereignty levels from least (cloud) to most (air-gapped) sovereign.
+ * Maps to SovereigntyLevel IntEnum in Python.
+ */
+export type SovereigntyLevel =
+  | "L1_CLOUD"
+  | "L2_CLOUD_DEDICATED"
+  | "L3_HYBRID"
+  | "L4_LOCAL_AUGMENTED"
+  | "L5_FULLY_LOCAL"
+  | "L6_CLASSIFIED"
+  | "L7_AIRGAPPED";
+
+/** Numeric value (1–7) associated with a sovereignty level. */
+export type SovereigntyLevelValue = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+
+// ---------------------------------------------------------------------------
+// Edge runtime types
+// ---------------------------------------------------------------------------
+
+/**
+ * Supported model quantization levels for edge inference.
+ * Maps to QuantizationLevel enum in Python.
+ */
+export type QuantizationLevel =
+  | "none"
+  | "int8"
+  | "int4"
+  | "gguf_q4_k_m"
+  | "gguf_q5_k_m"
+  | "gguf_q8_0";
+
+/** Configuration for an edge runtime environment. */
+export interface EdgeRuntime {
+  /** Maximum RAM available for model and inference (MiB). */
+  readonly max_memory_mb: number;
+  /** Maximum CPU utilisation percentage (0–100) allowed. */
+  readonly max_cpu_percent: number;
+  /** Quantization level to apply to loaded models. */
+  readonly model_quantization: QuantizationLevel;
+  /** Whether this edge node can operate without network connectivity. */
+  readonly offline_capable: boolean;
+  /** Maximum number of simultaneous inference requests. */
+  readonly max_concurrent_requests: number;
+  /** Path to the directory where model weights are cached locally. */
+  readonly model_cache_dir: string;
+  /** GPU memory available in MiB (0 if no GPU present). */
+  readonly gpu_memory_mb: number;
+  /** Whether to cache model activations across requests. */
+  readonly enable_model_caching: boolean;
+  /** How often the edge node sends a heartbeat in seconds. */
+  readonly heartbeat_interval_seconds: number;
+}
+
+/** Result of a resource validation check for an EdgeRuntime. */
+export interface ResourceValidationResult {
+  /** True if all resource requirements are met. */
+  readonly is_valid: boolean;
+  /** Non-fatal issues detected during validation. */
+  readonly warnings: readonly string[];
+  /** Fatal issues that prevent the runtime from operating correctly. */
+  readonly errors: readonly string[];
+  /** Detected available system memory in MiB. */
+  readonly available_memory_mb: number;
+  /** Detected logical CPU count. */
+  readonly available_cpu_count: number;
+}
+
+/** Estimated inference performance for an edge configuration. */
+export interface PerformanceEstimate {
+  /** Estimated token generation rate (tokens/second). */
+  readonly tokens_per_second: number;
+  /** Estimated latency to the first output token in milliseconds. */
+  readonly time_to_first_token_ms: number;
+  /** Estimated maximum context length supported given memory constraints. */
+  readonly max_context_tokens: number;
+  /** Estimated throughput multiplier from quantization (1.0 = no speedup). */
+  readonly quantization_speedup_factor: number;
+  /** Explanatory notes about the estimate. */
+  readonly notes: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// Deployment bundle types
+// ---------------------------------------------------------------------------
+
+/** Structured manifest describing a deployment package. */
+export interface DeploymentManifest {
+  /** Unique identifier for this package. */
+  readonly package_id: string;
+  /** ISO-8601 timestamp of package creation. */
+  readonly created_at: string;
+  /** The sovereignty level this package targets. */
+  readonly sovereignty_level: string;
+  /** Name of the deployment template used. */
+  readonly template_name: string;
+  /** List of relative file paths included in the bundle. */
+  readonly files: readonly string[];
+  /** Additional key/value metadata attached to this package. */
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+/** A complete deployment bundle ready for transfer or installation. */
+export interface DeploymentBundle {
+  /** Structured manifest document for the package. */
+  readonly manifest: DeploymentManifest;
+  /** Resolved list of file paths included. */
+  readonly files_list: readonly string[];
+  /** SHA-256 hex digest of the serialised manifest. */
+  readonly checksum: string;
+  /** The sovereignty level this package targets. */
+  readonly sovereignty_level: SovereigntyLevel;
+  /** The raw YAML string of the manifest. */
+  readonly manifest_yaml: string;
+}
+
+/** Configuration for creating a deployment bundle. */
+export interface PackagerConfig {
+  /** The target sovereignty level for the deployment. */
+  readonly sovereignty_level: SovereigntyLevel;
+  /** Optional explicit package identifier. */
+  readonly package_id?: string;
+  /** Optional additional key/value pairs to embed in the manifest. */
+  readonly metadata?: Readonly<Record<string, string>>;
+  /** Optional source directory path to scan for files. */
+  readonly source_directory?: string;
+  /** Optional explicit list of file paths to include. */
+  readonly explicit_files?: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// Synchronisation types
+// ---------------------------------------------------------------------------
+
+/**
+ * Priority level for a sync task.
+ * Maps to SyncPriority enum in Python.
+ */
+export type SyncPriority = "critical" | "high" | "normal" | "low";
+
+/**
+ * Lifecycle state of a sync task.
+ * Maps to SyncTaskStatus enum in Python.
+ */
+export type SyncTaskStatus =
+  | "pending"
+  | "in_progress"
+  | "completed"
+  | "failed"
+  | "skipped";
+
+/** Policy governing when and how synchronisation may occur. */
+export interface SyncConfig {
+  /** Whether sync tasks may run in the background. */
+  readonly allow_background_sync: boolean;
+  /** Maximum number of retry attempts for a failed sync task. */
+  readonly max_retry_attempts: number;
+  /** Base backoff interval in seconds between retry attempts. */
+  readonly retry_backoff_seconds: number;
+  /** UTC hour (0–23) at which the sync window opens. -1 means any time. */
+  readonly sync_window_start_hour: number;
+  /** UTC hour (0–23) at which the sync window closes. -1 means any time. */
+  readonly sync_window_end_hour: number;
+  /** Whether sync must only proceed over an encrypted channel. */
+  readonly require_encrypted_channel: boolean;
+  /** Maximum size of a single sync payload in MiB. */
+  readonly max_payload_size_mb: number;
+  /** If non-empty, only sync tasks with a type in this list are allowed. */
+  readonly allowed_sync_types: readonly string[];
+}
+
+/** A single unit of work to synchronise. */
+export interface SyncTask {
+  /** Unique identifier for this sync task. */
+  readonly task_id: string;
+  /** Category of sync (e.g. "model_update", "audit_log"). */
+  readonly sync_type: string;
+  /** Human-readable description of what this task syncs. */
+  readonly payload_description: string;
+  /** Task priority affecting processing order. */
+  readonly priority: SyncPriority;
+  /** Current lifecycle state. */
+  readonly status: SyncTaskStatus;
+  /** ISO-8601 UTC timestamp of task creation. */
+  readonly created_at: string;
+  /** ISO-8601 UTC timestamp of last status change. */
+  readonly updated_at: string;
+  /** Number of retry attempts made so far. */
+  readonly retry_count: number;
+  /** Last error message if the task failed. */
+  readonly error_message: string;
+  /** Arbitrary key/value metadata attached to this task. */
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+/** Request payload for queueing a sync task. */
+export interface SyncStateRequest {
+  /** Category of the sync task. */
+  readonly sync_type: string;
+  /** Human-readable description of what will be synced. */
+  readonly payload_description: string;
+  /** Task priority. */
+  readonly priority?: SyncPriority;
+  /** Optional metadata key/value pairs. */
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Offline capability types
+// ---------------------------------------------------------------------------
+
+/**
+ * Current connectivity status of the edge node.
+ * Maps to OfflineStatus enum in Python.
+ */
+export type OfflineStatus = "online" | "offline" | "degraded";
+
+/** Describes the offline operation capabilities of an edge deployment. */
+export interface OfflineCapability {
+  /** Whether the node can return cached responses when offline. */
+  readonly can_serve_cached_responses: boolean;
+  /** Whether local model inference is available without network. */
+  readonly can_run_local_inference: boolean;
+  /** Whether write operations can be queued for later sync. */
+  readonly can_queue_writes: boolean;
+  /** Maximum hours the node should operate offline. -1 = indefinite. */
+  readonly max_offline_duration_hours: number;
+  /** Time-to-live for cached responses in hours. */
+  readonly cache_ttl_hours: number;
+  /** Operation types available in degraded/offline mode. */
+  readonly supported_degraded_operations: readonly string[];
+}
+
+/** Current sovereignty status of an edge deployment. */
+export interface SovereigntyStatus {
+  /** The sovereignty level currently in effect. */
+  readonly sovereignty_level: SovereigntyLevel;
+  /** Current connectivity status. */
+  readonly offline_status: OfflineStatus;
+  /** Number of sync tasks currently pending. */
+  readonly pending_sync_tasks: number;
+  /** Whether resource validation has passed. */
+  readonly resources_valid: boolean;
+  /** ISO-8601 UTC timestamp of the last status check. */
+  readonly checked_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// API result wrapper (shared pattern)
+// ---------------------------------------------------------------------------
+
+/** Standard error payload returned by the agent-sovereign API. */
+export interface ApiError {
+  readonly error: string;
+  readonly detail: string;
+}
+
+/** Result type for all client operations. */
+export type ApiResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ApiError; readonly status: number };

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}