refactor: centralize TAP helper ownership

packages/app-scheduling/src/handler.ts

@@ -7,9 +7,11 @@ import type {
 	TimeSlot,
 } from "trusted-agents-core";
 import {
+	createGrantSet,
 	findApplicableSchedulingGrants,
 	findSchedulableSchedulingSlots,
 	mapSchedulingDecisionToResult,
+	parseSchedulingActionPayload,
 } from "trusted-agents-core";
 
 export async function handleSchedulingRequest(ctx: TapActionContext): Promise<TapActionResult> {
@@ -50,7 +52,7 @@ function handleGrantOnlyEvaluation(
 ): TapActionResult {
 	// Check if grants cover this scheduling request
 	const matchingGrants = findApplicableSchedulingGrants(
-		{ version: "tap-grants/v1", updatedAt: "", grants: ctx.peer.grantsToPeer },
+		createGrantSet(ctx.peer.grantsToPeer, ""),
 		proposal,
 	);
 
@@ -132,61 +134,10 @@ function handleGrantOnlyEvaluation(
 }
 
 function validatePayload(payload: Record<string, unknown>): SchedulingProposal | null {
-	if (payload.type !== "scheduling/propose" && payload.type !== "scheduling/counter") {
-		return null;
-	}
-
-	if (typeof payload.title !== "string" || payload.title.length === 0) {
-		return null;
-	}
-
-	if (typeof payload.duration !== "number" || payload.duration <= 0) {
-		return null;
-	}
-
-	if (!Array.isArray(payload.slots) || payload.slots.length === 0) {
-		return null;
-	}
-
-	const slots: TimeSlot[] = [];
-	for (const slot of payload.slots) {
-		if (
-			typeof slot !== "object" ||
-			slot === null ||
-			typeof (slot as Record<string, unknown>).start !== "string" ||
-			typeof (slot as Record<string, unknown>).end !== "string"
-		) {
-			return null;
-		}
-		const s = slot as { start: string; end: string };
-		const startDate = new Date(s.start);
-		const endDate = new Date(s.end);
-		if (Number.isNaN(startDate.getTime()) || Number.isNaN(endDate.getTime())) {
-			return null;
-		}
-		if (startDate >= endDate) {
-			return null;
-		}
-		slots.push({ start: s.start, end: s.end });
-	}
-
-	const schedulingId =
-		typeof payload.schedulingId === "string" && payload.schedulingId.length > 0
-			? payload.schedulingId
-			: `sch_${Date.now()}`;
-
-	const originTimezone =
-		typeof payload.originTimezone === "string" && payload.originTimezone.length > 0
-			? payload.originTimezone
-			: "UTC";
-
-	return {
-		type: payload.type as "scheduling/propose" | "scheduling/counter",
-		schedulingId,
-		title: payload.title,
-		duration: payload.duration as number,
-		slots,
-		originTimezone,
-		...(typeof payload.note === "string" && payload.note.length > 0 ? { note: payload.note } : {}),
-	};
+	return parseSchedulingActionPayload(payload, {
+		defaultSchedulingId: () => `sch_${Date.now()}`,
+		defaultOriginTimezone: "UTC",
+		copySlots: true,
+		includeLocation: false,
+	});
 }

packages/app-scheduling/src/index.ts

@@ -1,4 +1,4 @@
-import { defineTapApp } from "trusted-agents-core";
+import { defineTapApp, generateActionId } from "trusted-agents-core";
 import { handleSchedulingRequest } from "./handler.js";
 
 export { handleSchedulingRequest } from "./handler.js";
@@ -48,8 +48,7 @@ export function buildSchedulingPayload(params: {
 }): Record<string, unknown> {
 	return {
 		type: "scheduling/propose",
-		schedulingId:
-			params.schedulingId ?? `sch_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,
+		schedulingId: params.schedulingId ?? generateActionId("sch"),
 		title: params.title,
 		duration: params.durationMinutes,
 		slots: params.proposedSlots,

packages/app-scheduling/test/handler.test.ts

@@ -4,6 +4,7 @@ import type {
 	SchedulingHandler,
 	TapActionContext,
 } from "trusted-agents-core";
+import { createGrantSet } from "trusted-agents-core";
 import { describe, expect, it, vi } from "vitest";
 import { handleSchedulingRequest } from "../src/handler.js";
 
@@ -54,16 +55,8 @@ function buildMockContext(
 				status: "active",
 				createdAt: new Date().toISOString(),
 				permissions: {
-					grantedByMe: {
-						version: "tap-grants/v1",
-						updatedAt: new Date().toISOString(),
-						grants: overrides.grantsToPeer ?? [],
-					},
-					grantedByPeer: {
-						version: "tap-grants/v1",
-						updatedAt: new Date().toISOString(),
-						grants: [],
-					},
+					grantedByMe: createGrantSet(overrides.grantsToPeer ?? []),
+					grantedByPeer: createGrantSet([]),
 				},
 			},
 			grantsFromPeer: [],
@@ -121,16 +114,8 @@ function buildMockContact(): Contact {
 		status: "active",
 		createdAt: new Date().toISOString(),
 		permissions: {
-			grantedByMe: {
-				version: "tap-grants/v1",
-				updatedAt: new Date().toISOString(),
-				grants: [makeGrant()],
-			},
-			grantedByPeer: {
-				version: "tap-grants/v1",
-				updatedAt: new Date().toISOString(),
-				grants: [],
-			},
+			grantedByMe: createGrantSet([makeGrant()]),
+			grantedByPeer: createGrantSet([]),
 		},
 	};
 }

packages/app-transfer/src/handler.ts

@@ -1,12 +1,8 @@
-import type {
-	TapActionContext,
-	TapActionResult,
-	TransferActionRequest,
-	TransferAsset,
-} from "trusted-agents-core";
+import type { TapActionContext, TapActionResult, TransferActionRequest } from "trusted-agents-core";
 import {
+	createGrantSet,
 	findApplicableTransferGrants,
-	isEthereumAddress,
+	parseTransferActionPayload,
 	toErrorMessage,
 } from "trusted-agents-core";
 
@@ -25,7 +21,7 @@ export async function handleTransferRequest(ctx: TapActionContext): Promise<TapA
 
 	// Check if grants cover this transfer
 	const matchingGrants = findApplicableTransferGrants(
-		{ version: "tap-grants/v1", updatedAt: "", grants: ctx.peer.grantsToPeer },
+		createGrantSet(ctx.peer.grantsToPeer, ""),
 		request,
 	);
 
@@ -123,37 +119,5 @@ export async function handleTransferRequest(ctx: TapActionContext): Promise<TapA
 }
 
 function validatePayload(payload: Record<string, unknown>): TransferActionRequest | null {
-	if (payload.type !== "transfer/request") {
-		return null;
-	}
-
-	if (typeof payload.actionId !== "string" || payload.actionId.length === 0) {
-		return null;
-	}
-
-	if (payload.asset !== "native" && payload.asset !== "usdc") {
-		return null;
-	}
-
-	if (typeof payload.amount !== "string" || payload.amount.length === 0) {
-		return null;
-	}
-
-	if (typeof payload.chain !== "string" || payload.chain.length === 0) {
-		return null;
-	}
-
-	if (typeof payload.toAddress !== "string" || !isEthereumAddress(payload.toAddress)) {
-		return null;
-	}
-
-	return {
-		type: "transfer/request",
-		actionId: payload.actionId,
-		asset: payload.asset as TransferAsset,
-		amount: payload.amount,
-		chain: payload.chain,
-		toAddress: payload.toAddress as `0x${string}`,
-		note: typeof payload.note === "string" && payload.note.length > 0 ? payload.note : undefined,
-	};
+	return parseTransferActionPayload(payload);
 }

packages/app-transfer/src/index.ts

@@ -1,4 +1,4 @@
-import { defineTapApp } from "trusted-agents-core";
+import { defineTapApp, generateActionId } from "trusted-agents-core";
 import { handleTransferRequest } from "./handler.js";
 
 export { handleTransferRequest } from "./handler.js";
@@ -28,7 +28,7 @@ export function buildTransferPayload(params: {
 }): Record<string, unknown> {
 	return {
 		type: "transfer/request",
-		actionId: params.actionId ?? `txn_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,
+		actionId: params.actionId ?? generateActionId("txn"),
 		...params,
 	};
 }

packages/app-transfer/test/handler.test.ts

@@ -1,4 +1,4 @@
-import type { TapActionContext } from "trusted-agents-core";
+import { type TapActionContext, createGrantSet } from "trusted-agents-core";
 import { describe, expect, it, vi } from "vitest";
 import { handleTransferRequest } from "../src/handler.js";
 
@@ -54,16 +54,8 @@ function buildMockContext(
 				status: "active",
 				createdAt: new Date().toISOString(),
 				permissions: {
-					grantedByMe: {
-						version: "tap-grants/v1",
-						updatedAt: new Date().toISOString(),
-						grants: overrides.grantsToPeer ?? [],
-					},
-					grantedByPeer: {
-						version: "tap-grants/v1",
-						updatedAt: new Date().toISOString(),
-						grants: [],
-					},
+					grantedByMe: createGrantSet(overrides.grantsToPeer ?? []),
+					grantedByPeer: createGrantSet([]),
 				},
 			},
 			grantsFromPeer: [],

packages/cli/assets/hermes/plugin/client.py

@@ -73,6 +73,14 @@ def _hermes_config_path() -> Path:
     return _hermes_home() / "plugins" / "trusted-agents-tap" / "config.json"
 
 
+def _tapd_socket_path(data_dir: Path) -> Path:
+    return data_dir / SOCKET_NAME
+
+
+def _tapd_token_path(socket_path: Path) -> Path:
+    return socket_path.parent / TOKEN_FILE_NAME
+
+
 def _load_hermes_identities() -> list[dict[str, Any]]:
     """Read the Hermes plugin config and return the list of identities.
 
@@ -183,7 +191,7 @@ def _load_auth_token(socket_path: Path) -> tuple[str | None, str | None]:
     is mode 0o600, so a same-uid process that cannot read it cannot call
     the daemon — this is the security boundary the unix-socket auth relies
     on. Parent dir of the socket is the tapd dataDir."""
-    token_path = socket_path.parent / TOKEN_FILE_NAME
+    token_path = _tapd_token_path(socket_path)
     try:
         raw = token_path.read_text(encoding="utf-8").strip()
     except FileNotFoundError:
@@ -392,7 +400,7 @@ def send_request(action: str, params: dict | None = None) -> Any:
 
     # Strip the identity key so it doesn't leak into tapd request bodies.
     dispatch_params = {k: v for k, v in params.items() if k != "identity"}
-    socket_path = data_dir / SOCKET_NAME
+    socket_path = _tapd_socket_path(data_dir)
     return _dispatch(action, dispatch_params, socket_path)
 
 
@@ -472,7 +480,7 @@ def drain_all_identities() -> list[dict]:
 
     if len(identities) == 0:
         data_dir = _legacy_data_dir()
-        socket_path = data_dir / SOCKET_NAME
+        socket_path = _tapd_socket_path(data_dir)
         drained, err = _drain_one(socket_path)
         if err is not None:
             return [_meta_error_notification("default", err)]
@@ -481,7 +489,7 @@ def drain_all_identities() -> list[dict]:
     merged: list[dict] = []
     for entry in identities:
         name = entry["name"]
-        socket_path = Path(entry["dataDir"]) / SOCKET_NAME
+        socket_path = _tapd_socket_path(Path(entry["dataDir"]))
         drained, err = _drain_one(socket_path)
         if err is not None:
             merged.append(_meta_error_notification(name, err))

packages/cli/src/commands/app.ts

@@ -1,4 +1,4 @@
-import type { TapApp } from "trusted-agents-core";
+import { type TapApp, isObject } from "trusted-agents-core";
 import { loadConfig } from "../lib/config-loader.js";
 import { handleCommandError } from "../lib/errors.js";
 import { error } from "../lib/output.js";
@@ -23,12 +23,11 @@ export async function appInstallCommand(name: string, opts: GlobalOptions): Prom
 			const mod = await import(packageName);
 			const exported = mod.default ?? mod.app ?? mod;
 			if (
-				!exported ||
-				typeof exported !== "object" ||
-				typeof (exported as Record<string, unknown>).id !== "string" ||
-				typeof (exported as Record<string, unknown>).name !== "string" ||
-				typeof (exported as Record<string, unknown>).version !== "string" ||
-				typeof (exported as Record<string, unknown>).actions !== "object"
+				!isObject(exported) ||
+				typeof exported.id !== "string" ||
+				typeof exported.name !== "string" ||
+				typeof exported.version !== "string" ||
+				typeof exported.actions !== "object"
 			) {
 				error(
 					"VALIDATION_ERROR",
@@ -38,7 +37,7 @@ export async function appInstallCommand(name: string, opts: GlobalOptions): Prom
 				process.exitCode = 1;
 				return;
 			}
-			tapApp = exported as TapApp;
+			tapApp = exported as unknown as TapApp;
 		} catch (_importErr) {
 			error(
 				"NOT_FOUND",

packages/cli/src/commands/config-set.ts

@@ -1,7 +1,6 @@
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import YAML from "yaml";
-import { writeFileAtomic } from "../lib/atomic-write.js";
+import { isObject } from "trusted-agents-core";
+import { readYamlFile, writeYamlFileAtomic } from "../lib/atomic-write.js";
 import { resolveChainAlias } from "../lib/chains.js";
 import {
 	resolveConfigPath,
@@ -61,18 +60,21 @@ export async function configSetCommand(
 			throw new Error(`Config file not found at ${configPath}. Run 'tap init' first.`);
 		}
 
-		const content = await readFile(configPath, "utf-8");
-		const yaml = (YAML.parse(content) as Record<string, unknown>) ?? {};
+		const yaml = (await readYamlFile<Record<string, unknown> | null>(configPath)) ?? {};
 
 		// Handle nested keys like xmtp.db_encryption_key
 		const parts = normalizeConfigPath(key);
 		let target: Record<string, unknown> = yaml;
 		for (let i = 0; i < parts.length - 1; i++) {
 			const part = parts[i]!;
-			if (typeof target[part] !== "object" || target[part] === null) {
-				target[part] = {};
+			const next = target[part];
+			if (isObject(next)) {
+				target = next;
+			} else {
+				const child: Record<string, unknown> = {};
+				target[part] = child;
+				target = child;
 			}
-			target = target[part] as Record<string, unknown>;
 		}
 
 		const leafKey = parts[parts.length - 1]!;
@@ -81,7 +83,7 @@ export async function configSetCommand(
 		const resolvedValue = leafKey === "chain" ? resolveChainAlias(value) : value;
 		target[leafKey] = parseConfigValue(parts, resolvedValue);
 
-		await writeFileAtomic(configPath, YAML.stringify(yaml));
+		await writeYamlFileAtomic(configPath, yaml);
 
 		success({ key, value: target[leafKey], path: configPath }, opts, startTime);
 	} catch (err) {