{"_id":"@agenticros/find","name":"@agenticros/find","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@agenticros/find","version":"0.2.0","type":"module","description":"Find Object skill for AgenticROS — the robot rotates in place until YOLOv8 sees a target object in the camera, then stops and returns the bounding box.","keywords":["agenticros","ros2","robotics","vision","yolo","object-detection","search"],"homepage":"https://github.com/agenticros/agenticros-skill-find#readme","bugs":{"url":"https://github.com/agenticros/agenticros-skill-find/issues"},"repository":{"type":"git","url":"git+https://github.com/agenticros/agenticros-skill-find.git"},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","typecheck":"tsc --noEmit"},"agenticros":{"id":"find","displayName":"Find Object","description":"Rotate the robot in place and stop the moment YOLOv8 sees the target — any of 80 COCO classes plus a small alias table (phone, tv, sofa just work). Returns the bounding box, confidence, and horizontal offset from image center.","categories":["vision","search","navigation"],"capabilities":[{"id":"find_object","verb":"find","description":"Rotate the robot in place until YOLOv8 sees the target object in the camera, then stop and return the bounding box.","inputs":{"target":"string"},"outputs":{"found":"boolean","bbox":"object","confidence":"number"},"interruptible":true,"blocks_base":true}]},"dependencies":{"@agenticros/core":"^0.8.0","@sinclair/typebox":"^0.34.0","onnxruntime-node":"^1.20.0","sharp":"^0.33.0"},"devDependencies":{"@types/node":"^20.17.0","typescript":"^5.7.0"},"author":{"name":"PlaiPin"},"license":"Apache-2.0","publishConfig":{"access":"public"},"_id":"@agenticros/find@0.2.0","gitHead":"f002a550fb0edb2c7d928cddb346e39ab2fbecdd","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-g7LTO20D1HkCcgogBufiJiyfUGR6sJFumP/b9RaHO5vD+JqA7A5RN8yiU0EsEER2bh3cKFUlcyLXnVmvestaDg==","shasum":"271e6a38ea04d44d3d881c2fe695f4ffd716b6f2","tarball":"https://registry.npmjs.org/@agenticros/find/-/find-0.2.0.tgz","fileCount":31,"unpackedSize":76085,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFT3t/+kAtqAz3CUQtZjMX4kygRzmtgjqs2wLT5FsLGKAiBb5R4fhlQvfDj27iXJXh7BJjMOIw+RWOpwNxxfc/p0SA=="}]},"_npmUser":{"name":"chrismatthieu","email":"chris@matthieu.us"},"directories":{},"maintainers":[{"name":"chrismatthieu","email":"chris@matthieu.us"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/find_0.2.0_1783638140356_0.3856330726525681"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-09T23:02:20.188Z","0.2.0":"2026-07-09T23:02:20.542Z","modified":"2026-07-09T23:02:20.790Z"},"maintainers":[{"name":"chrismatthieu","email":"chris@matthieu.us"}],"description":"Find Object skill for AgenticROS — the robot rotates in place until YOLOv8 sees a target object in the camera, then stops and returns the bounding box.","homepage":"https://github.com/agenticros/agenticros-skill-find#readme","keywords":["agenticros","ros2","robotics","vision","yolo","object-detection","search"],"repository":{"type":"git","url":"git+https://github.com/agenticros/agenticros-skill-find.git"},"author":{"name":"PlaiPin"},"bugs":{"url":"https://github.com/agenticros/agenticros-skill-find/issues"},"license":"Apache-2.0","readme":"# agenticros-skill-find\n\nFind Object skill for [AgenticROS](https://github.com/agenticros/agenticros): the robot rotates in place until it sees a target object in the camera feed, then stops.\n\n## What it does\n\n- **Behavior**: One-shot search. The skill rotates the robot in place (clockwise by default) and runs **YOLOv8n** on each captured camera frame. As soon as it detects an instance of the requested COCO class above a confidence threshold, it stops the robot and returns the bounding box plus the horizontal offset of the object from image center.\n- **Targets**: Any of the 80 COCO classes — e.g. `bottle`, `cup`, `vase`, `chair`, `cell phone`, `laptop`, `bowl`, `book`, `tv`, `couch`. Common aliases (`phone`, `tv`/`television`, `sofa`, `plant`, `bike`) are accepted.\n- **No ROS2 node required**: Detection runs entirely inside the OpenClaw gateway process. The skill subscribes to the camera topic via the AgenticROS transport and publishes `geometry_msgs/Twist` to `cmd_vel`.\n- **Stops on success or timeout**: If the timeout elapses without detection, the skill stops the robot and returns `found: false` with the elapsed time.\n- **Tools**:\n  - **`find_object`** — Rotate and search for a target object. Returns whether it was found, confidence, bounding box, and horizontal offset (`-1` left edge, `0` center, `+1` right edge).\n- **Config**: All options live under **`config.skills.find`** (see [Config options](#config-options-configskillsfind)).\n\n## Install and run\n\n1. **Install the skill** where the OpenClaw gateway can load it:\n   - **Option A (recommended)**: Add to AgenticROS config as a package name:\n     - In OpenClaw config, under `plugins.entries.agenticros.config`, set:\n       - `skillPackages`: `[\"agenticros-skill-find\"]`\n     - Install the package in the same environment as the gateway (e.g. `pnpm add agenticros-skill-find` in the gateway app).\n   - **Option B**: Clone this repo into a directory and add that directory to `skillPaths`:\n     - `skillPaths`: `[\"/path/to/agenticros-skill-find\"]`\n     - Run `pnpm install` and `pnpm build` in this repo.\n2. **Configure** the skill in the same config under `skills.find` (see [Config options](#config-options-configskillsfind)).\n3. **Restart the OpenClaw gateway** so the plugin loads the skill.\n4. In chat, use natural language: e.g. _\"find the bottle\"_, _\"look for a chair\"_, _\"locate my phone\"_. The agent will call `find_object` with the appropriate target.\n\n## First-run model download\n\nOn its first call, the skill downloads `yolov8n.onnx` (~6 MB) from the public Ultralytics mirror to `~/.agenticros/models/yolov8n.onnx`. Subsequent calls reuse the cached file.\n\nTo override:\n- `AGENTICROS_YOLOV8_MODEL` — absolute path to a local `.onnx` file.\n- `AGENTICROS_YOLOV8_URL` — alternative download URL.\n\n## Project structure\n\n| Path | Purpose |\n|------|---------|\n| `src/index.ts` | Entry point; exports `registerSkill(api, config, context)`. |\n| `src/config.ts` | Find skill config slice: reads `config.skills.find` and applies defaults. |\n| `src/types.ts` | Local skill API types (matches what the AgenticROS plugin passes at runtime). |\n| `src/coco-classes.ts` | COCO 80-class names + common aliases. |\n| `src/detector.ts` | YOLOv8n ONNX wrapper (CPU). |\n| `src/find-object.ts` | Rotate-and-detect loop: publishes `cmd_vel`, samples frames, stops on hit/timeout. |\n| `src/tools/find-object.ts` | Registers the `find_object` tool. |\n\nThe skill gets **transport** from the plugin via **context**:\n\n- `context.getTransport()` — ROS2 transport (subscribe/publish).\n- `context.logger` — Plugin logger.\n\nConfig is the full AgenticROS config; the skill only uses `config.skills.find`, plus `config.robot.namespace` / `config.teleop.cmdVelTopic` / `config.safety.maxAngularVelocity` for topic resolution and safety clamping.\n\n## Config options (config.skills.find)\n\n| Option | Description |\n|--------|-------------|\n| `cameraTopic` | Camera image topic (default `/camera/camera/color/image_raw/compressed`). Resolved against the robot namespace. |\n| `cameraMessageType` | `\"CompressedImage\"` (default) or `\"Image\"`. |\n| `cmdVelTopic` | Override `cmd_vel` topic (default: from teleop or robot namespace). |\n| `defaultAngularSpeed` | Default rotation speed in rad/s when the caller omits it (default `0.3`). Clamped to `safety.maxAngularVelocity`. |\n| `defaultTimeoutSeconds` | Default timeout in seconds when the caller omits it (default `30`). |\n| `defaultMinConfidence` | Default minimum YOLO confidence to accept a detection (default `0.5`). |\n| `pollIntervalMs` | Time between camera frame samples (default `500`). |\n| `snapshotTimeoutMs` | Per-frame camera subscribe timeout (default `3000`). |\n\n## Tool: `find_object`\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `target` | string (required) | COCO class name (e.g. `\"bottle\"`, `\"cup\"`, `\"vase\"`, `\"chair\"`, `\"cell phone\"`). Aliases accepted. |\n| `angular_speed` | number | Rotation speed in rad/s (default from config). Clamped to `safety.maxAngularVelocity`. |\n| `clockwise` | boolean | Rotate clockwise (default `true`). Set `false` for counterclockwise. |\n| `timeout_seconds` | number | Give up after this many seconds (default from config). |\n| `min_confidence` | number | Minimum detection confidence to accept (default from config). |\n\n**Returns** an object with `found`, `target`, `classId`, `elapsedSeconds`, `rotationDirection`, `angularSpeed`, and (when found) a `detection` block: `confidence`, `cx`, `cy`, `width`, `height`, `imageWidth`, `imageHeight`, `horizontalOffset`.\n\n## Contract summary\n\n- **Package**: `package.json` has `\"agenticrosSkill\": true` and a `main` entry that exports **`registerSkill(api, config, context)`**.\n- **Config**: Skill-specific options live under **`config.skills.find`**. The skill validates and defaults its own slice.\n- **Context**: Use **`context.getTransport()`** for ROS2 and **`context.logger`** for logging.\n- **Registration**: Call **`api.registerTool(...)`** inside `registerSkill`. Depend only on the public skill API and types exported by `@agenticros/core`.\n\nFor the full contract and how to create a third-party skill, see [docs/skills.md](https://github.com/agenticros/agenticros/blob/main/docs/skills.md) in the AgenticROS repo, and use [agenticros-skill-followme](https://github.com/agenticros/agenticros-skill-followme) as the reference template.\n\n## Acknowledgements\n\nYOLOv8n model from [Ultralytics](https://github.com/ultralytics/ultralytics).\n","readmeFilename":"README.md","_rev":"1-9aa79ebbc6f177734a5c8db5330477a6"}