@oceanswave/openclaw-tescmd 0.3.1

package/tools/status.ts

@@ -0,0 +1,47 @@
+/**
+ * Node status tool — check if a tescmd node is connected.
+ *
+ * Lets the agent detect whether a tescmd node is currently online
+ * and connected to the Gateway before attempting to invoke commands.
+ * If no node is connected, the agent can suggest spawning one via
+ * `tescmd serve <VIN> --openclaw <url>`.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+export function registerStatusTool(api: OpenClawPluginApi): void {
+	api.registerTool(
+		{
+			name: "tescmd_node_status",
+			label: "Check Node Status",
+			description:
+				"Check whether a tescmd node is currently connected to the OpenClaw Gateway. " +
+				"Returns the node's connection status, capabilities, and last-seen timestamp. " +
+				"\n\nWhen to use: ALWAYS call this before invoking any vehicle command if you " +
+				"haven't confirmed the node is online in this conversation. If the node is " +
+				"offline, suggest the user start one with: " +
+				"`tescmd serve <VIN> --openclaw <gateway_url> --openclaw-token <token>`. " +
+				"Also useful for diagnostic checks if commands are failing. " +
+				"\n\nReturns: {connected: boolean, node_id?: string, platform: 'tesla', " +
+				"commands_available?: number, last_seen?: string}. " +
+				"If connected is false, all other vehicle tools will fail.",
+			parameters: Type.Object({}),
+			async execute(_toolCallId: string, _params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Checking tescmd node connection status...",
+						},
+					],
+					details: {
+						gatewayQuery: "node.status",
+						platform: "tesla",
+					},
+				};
+			},
+		},
+		{ name: "tescmd_node_status" },
+	);
+}

package/tools/system.ts

@@ -0,0 +1,67 @@
+/**
+ * System meta-dispatch tool.
+ *
+ * The `system.run` command is a meta-dispatch that can invoke any
+ * registered handler by name.  It accepts both OpenClaw dot-notation
+ * (e.g. "door.lock") and Tesla Fleet API snake_case names
+ * (e.g. "door_lock") via an internal alias table.
+ *
+ * This is the escape hatch for commands that don't have dedicated tools,
+ * or for programmatic dispatch when the method name is determined at runtime.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+export function registerSystemTools(api: OpenClawPluginApi): void {
+	api.registerTool(
+		{
+			name: "tescmd_run_command",
+			label: "Run Tesla Command",
+			description:
+				"Meta-dispatch: execute any registered Tesla vehicle command by name. " +
+				"Accepts both OpenClaw dot-notation (e.g. 'door.lock', 'climate.on') " +
+				"and Tesla Fleet API snake_case method names (e.g. 'door_lock', " +
+				"'auto_conditioning_start'). Cannot invoke itself (system.run). " +
+				"\n\nKnown method aliases:\n" +
+				"  door_lock → door.lock\n" +
+				"  door_unlock → door.unlock\n" +
+				"  auto_conditioning_start → climate.on\n" +
+				"  auto_conditioning_stop → climate.off\n" +
+				"  set_temps → climate.set_temp\n" +
+				"  charge_start → charge.start\n" +
+				"  charge_stop → charge.stop\n" +
+				"  set_charge_limit → charge.set_limit\n" +
+				"  actuate_trunk → trunk.open\n" +
+				"\nUse this tool when you need to run a command that doesn't have " +
+				"a dedicated tool, or when the command name is determined dynamically.",
+			parameters: Type.Object({
+				method: Type.String({
+					description: "Command method name — dot-notation (door.lock) or snake_case (door_lock)",
+				}),
+				params: Type.Optional(
+					Type.Record(Type.String(), Type.Unknown(), {
+						description: "Optional parameters to pass to the command",
+					}),
+				),
+			}),
+			async execute(_toolCallId: string, params: Record<string, unknown>) {
+				const method = params.method as string;
+				const cmdParams = (params.params as Record<string, unknown>) ?? {};
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Invoking system.run with method=${method} on tescmd node`,
+						},
+					],
+					details: {
+						nodeMethod: "system.run",
+						params: { method, params: cmdParams },
+					},
+				};
+			},
+		},
+		{ name: "tescmd_run_command" },
+	);
+}

package/tools/triggers.ts

@@ -0,0 +1,311 @@
+/**
+ * Trigger subscription tools — CRUD, polling, and convenience aliases.
+ *
+ * Triggers allow agents to subscribe to telemetry conditions and receive
+ * notifications when thresholds are crossed.  For example, alert when
+ * battery drops below 20% or when the vehicle leaves a geofence.
+ *
+ * Supported trigger operators:
+ *   lt, gt, lte, gte, eq, neq — numeric comparisons
+ *   changed — fires on any value change
+ *   enter, leave — geofence operators (for Location field)
+ *
+ * Supported telemetry fields for triggers:
+ *   Soc, BatteryLevel, InsideTemp, OutsideTemp, VehicleSpeed,
+ *   ChargeState, Locked, SentryMode, Location, Gear
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { stringEnum } from "openclaw/plugin-sdk";
+
+const TRIGGER_OPERATORS = [
+	"lt",
+	"gt",
+	"lte",
+	"gte",
+	"eq",
+	"neq",
+	"changed",
+	"enter",
+	"leave",
+] as const;
+
+const TRIGGER_FIELDS = [
+	"Soc",
+	"BatteryLevel",
+	"InsideTemp",
+	"OutsideTemp",
+	"VehicleSpeed",
+	"ChargeState",
+	"DetailedChargeState",
+	"Locked",
+	"SentryMode",
+	"Location",
+	"Gear",
+	"EstBatteryRange",
+] as const;
+
+export function registerTriggerTools(api: OpenClawPluginApi): void {
+	// -----------------------------------------------------------------
+	// tescmd_list_triggers
+	// -----------------------------------------------------------------
+	api.registerTool(
+		{
+			name: "tescmd_list_triggers",
+			label: "List Triggers",
+			description:
+				"List all active trigger subscriptions on the tescmd node. Returns " +
+				"{triggers: [{id, field, operator, value, once, cooldown_seconds}]}. " +
+				"Each trigger monitors a telemetry field and fires when the condition " +
+				"is met. Use trigger IDs from this list with tescmd_delete_trigger.",
+			parameters: Type.Object({}),
+			async execute(_toolCallId: string, _params: Record<string, unknown>) {
+				return {
+					content: [{ type: "text" as const, text: "Invoking trigger.list on tescmd node" }],
+					details: { nodeMethod: "trigger.list", params: {} },
+				};
+			},
+		},
+		{ name: "tescmd_list_triggers" },
+	);
+
+	// -----------------------------------------------------------------
+	// tescmd_poll_triggers
+	// -----------------------------------------------------------------
+	api.registerTool(
+		{
+			name: "tescmd_poll_triggers",
+			label: "Poll Trigger Notifications",
+			description:
+				"Poll for trigger notifications that have fired since the last poll. " +
+				"Returns {notifications: []} where each notification contains the " +
+				"trigger_id, field name, current value, and fired_at timestamp. " +
+				"Drains the pending notification queue — calling again immediately " +
+				"will return empty unless new triggers have fired.",
+			parameters: Type.Object({}),
+			async execute(_toolCallId: string, _params: Record<string, unknown>) {
+				return {
+					content: [{ type: "text" as const, text: "Invoking trigger.poll on tescmd node" }],
+					details: { nodeMethod: "trigger.poll", params: {} },
+				};
+			},
+		},
+		{ name: "tescmd_poll_triggers" },
+	);
+
+	// -----------------------------------------------------------------
+	// tescmd_create_trigger
+	// -----------------------------------------------------------------
+	api.registerTool(
+		{
+			name: "tescmd_create_trigger",
+			label: "Create Trigger",
+			description:
+				"Create a new telemetry trigger subscription. The trigger fires when " +
+				"the specified telemetry field meets the condition (operator + value). " +
+				"For example: field='Soc', operator='lt', value=20 fires when battery " +
+				"drops below 20%. For geofence: field='Location', operator='leave', " +
+				"with lat/lon/radius in value. Returns {id, field, operator} on success.",
+			parameters: Type.Object({
+				field: stringEnum(TRIGGER_FIELDS),
+				operator: stringEnum(TRIGGER_OPERATORS),
+				value: Type.Optional(
+					Type.Union([Type.Number(), Type.String(), Type.Boolean()], {
+						description: "Threshold value for the condition",
+					}),
+				),
+				once: Type.Optional(
+					Type.Boolean({
+						description: "If true, the trigger fires only once then auto-deletes (default: false)",
+					}),
+				),
+				cooldown_seconds: Type.Optional(
+					Type.Number({
+						description: "Minimum seconds between consecutive fires for this trigger (default: 60)",
+						minimum: 0,
+					}),
+				),
+			}),
+			async execute(_toolCallId: string, params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Creating trigger: ${params.field} ${params.operator} ${params.value ?? "(any change)"}`,
+						},
+					],
+					details: { nodeMethod: "trigger.create", params },
+				};
+			},
+		},
+		{ name: "tescmd_create_trigger" },
+	);
+
+	// -----------------------------------------------------------------
+	// tescmd_delete_trigger
+	// -----------------------------------------------------------------
+	api.registerTool(
+		{
+			name: "tescmd_delete_trigger",
+			label: "Delete Trigger",
+			description:
+				"Delete an existing trigger subscription by its ID. Get trigger IDs " +
+				"from tescmd_list_triggers. Returns {deleted: boolean, id: string}.",
+			parameters: Type.Object({
+				id: Type.String({ description: "The trigger ID to delete" }),
+			}),
+			async execute(_toolCallId: string, params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Deleting trigger ${params.id}`,
+						},
+					],
+					details: { nodeMethod: "trigger.delete", params: { id: params.id } },
+				};
+			},
+		},
+		{ name: "tescmd_delete_trigger" },
+	);
+
+	// -----------------------------------------------------------------
+	// Convenience trigger aliases
+	// -----------------------------------------------------------------
+
+	api.registerTool(
+		{
+			name: "tescmd_cabin_temp_trigger",
+			label: "Cabin Temperature Trigger",
+			description:
+				"Create a trigger on the vehicle's cabin temperature (InsideTemp). " +
+				"Shortcut for tescmd_create_trigger with field pre-set to InsideTemp. " +
+				"Example: operator='gt', value=100 fires when cabin exceeds 100°F. " +
+				"Useful for hot car alerts or climate pre-conditioning automation.",
+			parameters: Type.Object({
+				operator: stringEnum(TRIGGER_OPERATORS),
+				value: Type.Optional(Type.Number({ description: "Temperature threshold" })),
+				once: Type.Optional(Type.Boolean({ description: "Fire only once (default: false)" })),
+				cooldown_seconds: Type.Optional(
+					Type.Number({ description: "Min seconds between fires (default: 60)", minimum: 0 }),
+				),
+			}),
+			async execute(_toolCallId: string, params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Creating cabin temp trigger: InsideTemp ${params.operator} ${params.value ?? "(any)"}`,
+						},
+					],
+					details: { nodeMethod: "cabin_temp.trigger", params },
+				};
+			},
+		},
+		{ name: "tescmd_cabin_temp_trigger" },
+	);
+
+	api.registerTool(
+		{
+			name: "tescmd_outside_temp_trigger",
+			label: "Outside Temperature Trigger",
+			description:
+				"Create a trigger on the outside ambient temperature (OutsideTemp). " +
+				"Shortcut for tescmd_create_trigger with field pre-set to OutsideTemp. " +
+				"Example: operator='lt', value=32 fires when it drops below freezing.",
+			parameters: Type.Object({
+				operator: stringEnum(TRIGGER_OPERATORS),
+				value: Type.Optional(Type.Number({ description: "Temperature threshold" })),
+				once: Type.Optional(Type.Boolean({ description: "Fire only once (default: false)" })),
+				cooldown_seconds: Type.Optional(
+					Type.Number({ description: "Min seconds between fires (default: 60)", minimum: 0 }),
+				),
+			}),
+			async execute(_toolCallId: string, params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Creating outside temp trigger: OutsideTemp ${params.operator} ${params.value ?? "(any)"}`,
+						},
+					],
+					details: { nodeMethod: "outside_temp.trigger", params },
+				};
+			},
+		},
+		{ name: "tescmd_outside_temp_trigger" },
+	);
+
+	api.registerTool(
+		{
+			name: "tescmd_battery_trigger",
+			label: "Battery Level Trigger",
+			description:
+				"Create a trigger on the vehicle's battery level (BatteryLevel). " +
+				"Shortcut for tescmd_create_trigger with field pre-set to BatteryLevel. " +
+				"Example: operator='lt', value=20 fires when battery drops below 20%. " +
+				"Useful for low-battery alerts or charging automation.",
+			parameters: Type.Object({
+				operator: stringEnum(TRIGGER_OPERATORS),
+				value: Type.Optional(Type.Number({ description: "Battery level threshold (0-100)" })),
+				once: Type.Optional(Type.Boolean({ description: "Fire only once (default: false)" })),
+				cooldown_seconds: Type.Optional(
+					Type.Number({ description: "Min seconds between fires (default: 60)", minimum: 0 }),
+				),
+			}),
+			async execute(_toolCallId: string, params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Creating battery trigger: BatteryLevel ${params.operator} ${params.value ?? "(any)"}`,
+						},
+					],
+					details: { nodeMethod: "battery.trigger", params },
+				};
+			},
+		},
+		{ name: "tescmd_battery_trigger" },
+	);
+
+	api.registerTool(
+		{
+			name: "tescmd_location_trigger",
+			label: "Location/Geofence Trigger",
+			description:
+				"Create a geofence trigger on the vehicle's GPS location. " +
+				"Uses the 'enter' operator to fire when the vehicle enters a radius, " +
+				"or 'leave' to fire when it exits. Requires lat, lon, and radius " +
+				"parameters. Example: operator='leave', value={lat: 37.7749, lon: -122.4194, " +
+				"radius: 500} fires when the vehicle moves more than 500 meters from the point.",
+			parameters: Type.Object({
+				operator: stringEnum(["enter", "leave"] as const),
+				lat: Type.Optional(Type.Number({ description: "Latitude of geofence center" })),
+				lon: Type.Optional(Type.Number({ description: "Longitude of geofence center" })),
+				radius: Type.Optional(
+					Type.Number({ description: "Geofence radius in meters", minimum: 0 }),
+				),
+				value: Type.Optional(
+					Type.Unknown({ description: "Alternative: pass {lat, lon, radius} as value object" }),
+				),
+				once: Type.Optional(Type.Boolean({ description: "Fire only once (default: false)" })),
+				cooldown_seconds: Type.Optional(
+					Type.Number({ description: "Min seconds between fires (default: 60)", minimum: 0 }),
+				),
+			}),
+			async execute(_toolCallId: string, params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Creating location trigger: geofence ${params.operator}`,
+						},
+					],
+					details: { nodeMethod: "location.trigger", params },
+				};
+			},
+		},
+		{ name: "tescmd_location_trigger" },
+	);
+}

package/tools/trunk.ts

@@ -0,0 +1,67 @@
+/**
+ * Trunk and frunk tools.
+ *
+ * Control the vehicle's rear trunk and front trunk (frunk) via the
+ * tescmd node.  Both use the `actuate_trunk` Fleet API method with
+ * different `which_trunk` parameters.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+export function registerTrunkTools(api: OpenClawPluginApi): void {
+	// -----------------------------------------------------------------
+	// tescmd_open_trunk
+	// -----------------------------------------------------------------
+	api.registerTool(
+		{
+			name: "tescmd_open_trunk",
+			label: "Open/Close Trunk",
+			description:
+				"Actuate the Tesla vehicle's rear trunk. If the trunk is closed it " +
+				"will open; if open it will close (on models with a power liftgate). " +
+				"On models without power close, the trunk will open but must be " +
+				"physically closed. Auto-wakes the vehicle if asleep.",
+			parameters: Type.Object({}),
+			async execute(_toolCallId: string, _params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Invoking trunk.open on tescmd node",
+						},
+					],
+					details: { nodeMethod: "trunk.open", params: {} },
+				};
+			},
+		},
+		{ name: "tescmd_open_trunk" },
+	);
+
+	// -----------------------------------------------------------------
+	// tescmd_open_frunk
+	// -----------------------------------------------------------------
+	api.registerTool(
+		{
+			name: "tescmd_open_frunk",
+			label: "Open Frunk",
+			description:
+				"Open the Tesla vehicle's front trunk (frunk). Note: the frunk can " +
+				"only be opened remotely — it cannot be closed remotely and must be " +
+				"physically pushed down to close. Auto-wakes the vehicle if asleep.",
+			parameters: Type.Object({}),
+			async execute(_toolCallId: string, _params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Invoking frunk.open on tescmd node",
+						},
+					],
+					details: { nodeMethod: "frunk.open", params: {} },
+				};
+			},
+		},
+		{ name: "tescmd_open_frunk" },
+	);
+}

package/tools/vehicle.ts

@@ -0,0 +1,115 @@
+/**
+ * Vehicle status tools — location, battery, and speed.
+ *
+ * These read-only tools query the tescmd node for real-time vehicle
+ * telemetry data.  The node checks its in-memory telemetry store first
+ * (populated by the Fleet Telemetry stream) and falls back to the Tesla
+ * Fleet API if telemetry is unavailable.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+export function registerVehicleTools(api: OpenClawPluginApi): void {
+	// -----------------------------------------------------------------
+	// tescmd_get_location
+	// -----------------------------------------------------------------
+	api.registerTool(
+		{
+			name: "tescmd_get_location",
+			label: "Get Vehicle Location",
+			description:
+				"Get the Tesla vehicle's current GPS location, heading, and speed. " +
+				"Returns {latitude, longitude, heading, speed} — coordinates in decimal degrees, " +
+				"heading in degrees (0-360, 0=North), speed in mph. " +
+				"\n\nWhen to use: User asks 'where is my car?', needs directions to/from the vehicle, " +
+				"wants to check if the car is at a specific location, or you need proximity info " +
+				"for a geofence decision. Also useful before setting up a location trigger. " +
+				"\n\nData source: Real-time telemetry (instant) → Fleet API drive_state (may need wake). " +
+				"If response contains {pending: true}, data is being fetched — retry in a few seconds.",
+			parameters: Type.Object({}),
+			async execute(_toolCallId: string, _params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Invoking location.get on tescmd node",
+						},
+					],
+					details: {
+						nodeMethod: "location.get",
+						params: {},
+					},
+				};
+			},
+		},
+		{ name: "tescmd_get_location" },
+	);
+
+	// -----------------------------------------------------------------
+	// tescmd_get_battery
+	// -----------------------------------------------------------------
+	api.registerTool(
+		{
+			name: "tescmd_get_battery",
+			label: "Get Battery Status",
+			description:
+				"Get the Tesla vehicle's current battery level (0-100%) and estimated " +
+				"remaining range in miles. Returns {battery_level, range_miles}. " +
+				"\n\nWhen to use: User asks about charge level or range, asks 'do I need to charge?', " +
+				"is planning a trip and needs to know range, or you need to decide whether to " +
+				"suggest starting a charge. Pair with tescmd_get_charge_state to get the full " +
+				"charging picture. " +
+				"\n\nData source: Soc/BatteryLevel telemetry (instant) → Fleet API charge_state (may need wake).",
+			parameters: Type.Object({}),
+			async execute(_toolCallId: string, _params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Invoking battery.get on tescmd node",
+						},
+					],
+					details: {
+						nodeMethod: "battery.get",
+						params: {},
+					},
+				};
+			},
+		},
+		{ name: "tescmd_get_battery" },
+	);
+
+	// -----------------------------------------------------------------
+	// tescmd_get_speed
+	// -----------------------------------------------------------------
+	api.registerTool(
+		{
+			name: "tescmd_get_speed",
+			label: "Get Vehicle Speed",
+			description:
+				"Get the Tesla vehicle's current speed in miles per hour (mph). " +
+				"Returns {speed_mph}. Returns 0 or null when parked. " +
+				"\n\nWhen to use: User asks if the car is moving, you need to verify the vehicle " +
+				"is parked before sending a command (some commands should only be sent when " +
+				"stationary), or for trip monitoring. " +
+				"\n\nData source: VehicleSpeed telemetry (instant) → Fleet API drive_state (may need wake).",
+			parameters: Type.Object({}),
+			async execute(_toolCallId: string, _params: Record<string, unknown>) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Invoking speed.get on tescmd node",
+						},
+					],
+					details: {
+						nodeMethod: "speed.get",
+						params: {},
+					},
+				};
+			},
+		},
+		{ name: "tescmd_get_speed" },
+	);
+}