my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

my-project-public — gitlawb

#1	/**
#2	* CLAWD Convex Client
#3	*
#4	* Lightweight HTTP client for the automaton to communicate with
#5	* the CLAWD Convex backend for agent tracking, heartbeats, and
#6	* key-value data storage.
#7	*
#8	* Uses the Convex HTTP actions defined in convex/clawd/http.ts.
#9	* No external dependencies needed — just uses fetch.
#10	*/
#11
#12	export interface ConvexClientOptions {
#13	/** Base URL of the Convex deployment (e.g. https://giddy-dragon-7.convex.site) */
#14	siteUrl: string;
#15	/** Optional agent identifier */
#16	agentId?: string;
#17	}
#18
#19	/**
#20	* Result of registering an agent.
#21	*/
#22	export interface RegisterResult {
#23	registered: boolean;
#24	agentId: string;
#25	firstSeen: number;
#26	}
#27
#28	/**
#29	* Result of recording a heartbeat.
#30	*/
#31	export interface HeartbeatResult {
#32	recorded: boolean;
#33	timestamp: number;
#34	}
#35
#36	/**
#37	* Result of storing data.
#38	*/
#39	export interface DataResult {
#40	stored: boolean;
#41	key: string;
#42	updatedAt: number;
#43	}
#44
#45	/**
#46	* Agent data entry returned from Convex.
#47	*/
#48	export interface AgentDataEntry {
#49	_id: string;
#50	agentId: string;
#51	key: string;
#52	value: string;
#53	contentType?: string;
#54	tags?: string[];
#55	updatedAt: number;
#56	_creationTime: number;
#57	}
#58
#59	/**
#60	* Agent info returned from Convex.
#61	*/
#62	export interface AgentInfo {
#63	_id: string;
#64	agentId: string;
#65	name: string;
#66	installMethod: string;
#67	active: boolean;
#68	firstSeen: number;
#69	lastSeen: number;
#70	metadata?: string;
#71	address?: string;
#72	source?: string;
#73	tags?: string[];
#74	latestHeartbeat?: {
#75	state?: string;
#76	creditsCents?: number;
#77	uptimeSeconds?: number;
#78	timestamp?: number;
#79	tier?: string;
#80	};
#81	}
#82
#83	/**
#84	* Creates a CLAWD Convex client for the automaton.
#85	*/
#86	export function createConvexClient(
#87	options: ConvexClientOptions,
#88	) {
#89	const baseUrl = options.siteUrl.replace(/\/$/, '');
#90	const defaultAgentId = options.agentId;
#91
#92	/**
#93	* Make an HTTP request to a CLAWD endpoint.
#94	*/
#95	async function request<T>(
#96	method: string,
#97	path: string,
#98	body?: Record<string, any>,
#99	): Promise<T> {
#100	const url = `${baseUrl}${path}`;
#101	const headers: Record<string, string> = {
#102	'Content-Type': 'application/json',
#103	};
#104
#105	if (defaultAgentId) {
#106	headers['X-Agent-Id'] = defaultAgentId;
#107	}
#108
#109	const resp = await fetch(url, {
#110	method,
#111	headers,
#112	body: body ? JSON.stringify(body) : undefined,
#113	});
#114
#115	if (!resp.ok) {
#116	const text = await resp.text();
#117	throw new Error(
#118	`Convex API error: ${method} ${path} -> ${resp.status}: ${text}`,
#119	);
#120	}
#121
#122	return resp.json() as Promise<T>;
#123	}
#124
#125	/**
#126	* Register / install an agent.
#127	*/
#128	async function registerAgent(params: {
#129	agentId: string;
#130	name: string;
#131	installMethod?: string;
#132	source?: string;
#133	metadata?: string;
#134	address?: string;
#135	tags?: string[];
#136	}): Promise<RegisterResult> {
#137	return request<RegisterResult>('POST', '/clawd/register', {
#138	agentId: params.agentId,
#139	name: params.name,
#140	installMethod: params.installMethod \|\| 'automaton',
#141	source: params.source,
#142	metadata: params.metadata,
#143	address: params.address,
#144	tags: params.tags,
#145	});
#146	}
#147
#148	/**
#149	* Push a heartbeat.
#150	*/
#151	async function sendHeartbeat(params: {
#152	agentId: string;
#153	state?: string;
#154	creditsCents?: number;
#155	usdcBalance?: number;
#156	uptimeSeconds?: number;
#157	version?: string;
#158	sandboxId?: string;
#159	turnCount?: number;
#160	skillCount?: number;
#161	tier?: string;
#162	statusPayload?: Record<string, any>;
#163	}): Promise<HeartbeatResult> {
#164	return request<HeartbeatResult>('POST', '/clawd/heartbeat', {
#165	agentId: params.agentId,
#166	state: params.state,
#167	creditsCents: params.creditsCents,
#168	usdcBalance: params.usdcBalance,
#169	uptimeSeconds: params.uptimeSeconds,
#170	version: params.version,
#171	sandboxId: params.sandboxId,
#172	turnCount: params.turnCount,
#173	skillCount: params.skillCount,
#174	tier: params.tier,
#175	statusPayload: params.statusPayload,
#176	});
#177	}
#178
#179	/**
#180	* Store key-value data for an agent.
#181	*/
#182	async function setData(params: {
#183	agentId: string;
#184	key: string;
#185	value: string;
#186	contentType?: string;
#187	tags?: string[];
#188	}): Promise<DataResult> {
#189	return request<DataResult>('POST', '/clawd/data', {
#190	agentId: params.agentId,
#191	key: params.key,
#192	value: params.value,
#193	contentType: params.contentType,
#194	tags: params.tags,
#195	});
#196	}
#197
#198	/**
#199	* Retrieve data for an agent by key.
#200	*/
#201	async function getData(params: {
#202	agentId: string;
#203	key: string;
#204	}): Promise<AgentDataEntry \| null> {
#205	return request<AgentDataEntry \| null>(
#206	'GET',
#207	`/clawd/data?agentId=${encodeURIComponent(params.agentId)}&key=${encodeURIComponent(params.key)}`,
#208	);
#209	}
#210
#211	/**
#212	* List all data keys for an agent.
#213	*/
#214	async function listData(params: {
#215	agentId: string;
#216	}): Promise<Array<{
#217	key: string;
#218	contentType?: string;
#219	tags?: string[];
#220	updatedAt: number;
#221	valuePreview: string;
#222	}>> {
#223	return request('GET', `/clawd/data/list?agentId=${encodeURIComponent(params.agentId)}`);
#224	}
#225
#226	/**
#227	* Get agent info + latest heartbeat.
#228	*/
#229	async function getAgent(params: {
#230	agentId: string;
#231	}): Promise<AgentInfo \| null> {
#232	return request<AgentInfo>(
#233	'GET',
#234	`/clawd/agent?agentId=${encodeURIComponent(params.agentId)}`,
#235	);
#236	}
#237
#238	/**
#239	* List all agents (optionally only active ones).
#240	*/
#241	async function listAgents(params?: {
#242	activeOnly?: boolean;
#243	}): Promise<AgentInfo[]> {
#244	const activeParam = params?.activeOnly ? '?active=true' : '';
#245	return request<AgentInfo[]>('GET', `/clawd/agents${activeParam}`);
#246	}
#247
#248	return {
#249	registerAgent,
#250	sendHeartbeat,
#251	setData,
#252	getData,
#253	listData,
#254	getAgent,
#255	listAgents,
#256	};
#257	}
#258
#259	export type ConvexAgentClient = ReturnType<typeof createConvexClient>;
#260
#261

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public