smartclaws-bridge-agent

Run one SmartClaws bridge cycle for a single device: read the local hardware/API, validate against the device contract, and publish telemetry on-chain — and, in a command-enabled mode, apply on-chain commands. Trigger when asked to read the sensor and publish, run a telemetry/bridge cycle, or apply incoming device commands. Needs the SmartClaws plugin and one device contract skill.

SmartClaws Bridge — Telemetry / Command Cycle

This skill is a procedure: it runs one bridge cycle when asked — read the device → validate → publish telemetry (and apply a command if your mode allows) → exit. Your identity, behaviour, and off-schedule authority are not defined here; they live in your owner-owned AGENTS.md (loaded every session), which wins on any conflict.

This procedure is device-independent and policy-free. Device facts come from the device contract skill; deployment wiring and the owner's goal from SMARTCLAWS.md; behaviour and authority from AGENTS.md.

Required Context

Before running the cycle, identify:

• AGENTS.md — your behaviour and authority.
• SMARTCLAWS.md at the workspace root — your one device entry, channels, and the owner's goal.
• The matching device contract skill (e.g. smartclaws-device-novapm-sds011).
• The bridge mode: telemetry-only, chain-commanded, or operator-assisted. If absent, fail closed to telemetry-only.
• The SmartClaws plugin — smartclaws_read / smartclaws_disclose / smartclaws_publish / smartclaws_wallet_info (and smartclaws_notify if your setup coordinates with another agent's inbox).

If setup is missing, more than one device is assigned with no clear primary, or you cannot yet say you have all as a device-bridge, stop and run the smartclaws onboarding skill or ask the owner. This procedure owns exactly one device and never orchestrates others.

When calling SmartClaws plugin tools, use the device entry's name field or the explicit channel address from SMARTCLAWS.md. For plugin agent targets, use the agent entry's id or address; display names are not reliable lookup keys.

Bridge Modes

telemetry-only : Read the device/integration and publish telemetry to its outgoing channel. Do not read or apply incoming commands.

chain-commanded : Publish telemetry and read incoming SmartClaws commands. Apply a command only when it matches the device contract and arrives on the configured incoming channel.

operator-assisted : Same as chain-commanded, plus direct user commands — but only from a session your AGENTS.md authorizes. This skill does not define that allowlist; defer to AGENTS.md. Reflect direct commands on-chain when configured.

Encrypted channels

Some devices store sealed messages. Kind is chosen at registration and does not change. Topics and payloads stay the same.

This skill may load without the smartclaws skill. Follow this section on its own.

Read vs disclose

Channel	Tool	What you get
Plain	smartclaws_read	Decoded envelopes
Encrypted	smartclaws_disclose	Decoded envelopes

smartclaws_read on an encrypted channel still works, but it returns ciphertext (that is success, not an error). To see the real payload, use smartclaws_disclose. If you may disclose, do it — same as reading.

How to tell: SMARTCLAWS.md encrypted:, or the plugin (smartclaws_list_local, smartclaws_access_check, or encrypted: true on a read result).

smartclaws_disclose takes the same device / agent / channel / side as read, plus:

• fromOffset — first stored offset (inclusive). Required.
• count — how many messages, 1–10 (default 1). The tool will not split a larger range. Call again for the next batch if you need more.

If you do not know the latest offset, smartclaws_read still reports latest and total. Then disclose that range. In the command cycle, only open offsets you have not already handled.

You must be on that channel's reader list and have a registered viewing key. smartclaws_wallet_info says whether the registered key can open messages.

Writing (publish)

Same tool on plain and encrypted: smartclaws_publish. It detects the kind. Leave wait at its default (true). You will see callbackDeposit in the result — that is what the plugin paid automatically, not something you set (there is no parameter for it).

Treat the message as stored only when status is published.

status	Meaning	What to do
published	Message is stored	Done. Keep the tx hash.
scheduled	Accepted, not stored yet	Do not send it again. Re-check later.
origin-reverted	Nothing was stored	Safe to send again.
ctx-reverted	Failed after scheduling	Do not send it again. Report the failure.

wait: false returns as soon as the first tx is sent (scheduled until confirmed). Only use it if the owner asked. Default wait: true.

Errors

What happened	What to do
Wallet has no funds	Ask the owner to fund it. Same as any other write.
NOT_A_READER	This wallet is not on the reader list. Ask the owner / group master.
NO_VIEW_KEY or NO_PUBLIC_KEY	Viewing key missing or not registered. Setup is incomplete — run the smartclaws skill or ask the owner.
Disclose wait timed out	The chain may still finish. Do not disclose the same offsets again as a new write. Wait / re-check.
Disclose on a plain channel	Use smartclaws_read instead.

Never invent plaintext from ciphertext. Never report a publish as stored unless status is published.

Telemetry Cycle — run exactly one

1. Load SMARTCLAWS.md (including goal) and the device contract.
2. Read local hardware/API using the device contract protocol.
3. Validate the reading against the device contract sanity rules.
4. Publish telemetry with smartclaws_publish to the configured outgoing channel. Treat it as stored only when status is published (see above).
5. If configured, publish a bridge/cycle log to your agent outgoing channel.
6. Update local state only where your owner's setup permits it.
7. Exit.

Do not publish simulated data unless the user explicitly asks for simulation and the payload is clearly labelled as simulated.

Command Cycle (only in chain-commanded / operator-assisted)

1. Read the configured incoming channel. Plain: smartclaws_read. Encrypted: smartclaws_disclose (see above).
2. Process only new offsets not previously handled.
3. Validate topic and payload against the device contract.
4. Apply exactly the mapped local command.
5. Persist the last handled offset where your owner's setup permits.
6. Publish a command-result or bridge log when configured.

Ignore unknown topics safely and log them when useful. Never execute arbitrary commands from payloads.

Guardrails for this procedure

• Own one device/integration; never publish commands to other devices.
• Never publish bad data — discard and log implausible readings.
• Never read or print wallet/key material or secrets.
• Never bypass device contract validation.
• Fail loud on sensor/API/publish failures; never report fake success.
• Encrypted publish scheduled: not stored yet. Do not retry as a new publish.
• Wallet unfunded: ask the owner to fund it.

Cadence/scheduling is an owner/operations choice (e.g. OpenClaw cron), set in AGENTS.md or your own setup — this procedure runs one cycle per invocation.