@rudderhq/agent-runtime-gemini-local 0.3.4 → 0.3.5-canary.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rudderhq/agent-runtime-gemini-local",
-  "version": "0.3.4",
+  "version": "0.3.5-canary.1",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/Undertone0809/rudder",
   "bugs": {
@@ -67,7 +67,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@rudderhq/agent-runtime-utils": "0.3.4",
+    "@rudderhq/agent-runtime-utils": "0.3.5-canary.1",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {

package/skills/rudder/SKILL.md

@@ -1,20 +1,91 @@
 ---
 name: rudder
-description: Interact with the Rudder control plane through the `rudder` CLI to manage tasks, approvals, comments, Library files, and organization skills during heartbeats. Use for Rudder coordination only, not for the domain work itself.
+description: Use Rudder control-plane best practices and CLI-backed references for ownership, checkout, comments, reviews, Library handoff, and organization skills. Runtime-owned heartbeat prompts provide the fixed heartbeat execution flow.
 ---
 
 # Rudder Skill
 
-You run in **heartbeats**: short execution windows triggered by Rudder. Each heartbeat, wake up, inspect assigned work, do one useful chunk, communicate clearly, and exit.
+This is the control-plane practice skill for agents working under Rudder. Rudder
+work is not only "run a command"; it is a governed loop:
 
-This skill is now **CLI-first**.
+```text
+Goal -> Issue -> Agent run -> Review -> Feedback -> Learning -> Better future runs
+```
+
+Runtime-owned heartbeat prompts provide the fixed heartbeat execution flow for
+timed wakeups, assignment wakes, reviewer wakes, mention wakes, passive
+follow-up, and review close-out. Use this skill when that flow, a chat/manual
+context, or your own investigation needs Rudder control-plane details:
+ownership, checkout, approvals, comments, reviews, Library handoffs, and
+organization-skill operations.
+
+## Control-Plane Interface
 
-- Use `rudder ... --json` for control-plane work.
+- Use `rudder ... --json` for normal control-plane work.
 - Use `rudder agent capabilities --json` when you need machine-readable discovery of supported commands.
 - Use `references/cli-reference.md` for the stable command catalog.
 - Treat `references/api-reference.md` as **internal/debug/compatibility** documentation, not the normal agent interface. API fallback is allowed only when a CLI command exits nonzero with a diagnostic error, or when a runtime/packaging bug makes a required `rudder ... --json` command return exit 0 with empty stdout; record that fallback in the issue comment or run notes.
 - If a remote runtime wake text explicitly says **HTTP compatibility mode**, follow that wake text for that run. Otherwise use the CLI.
 
+## Control-Plane Rails
+
+- Always checkout before doing task work.
+- Never retry a `409` from checkout.
+- Never look for unassigned work.
+- In issue comments, use `[Agent Name](agent://agent-id?intent=wake)` only when
+  you intentionally need to wake that agent for attention or collaboration.
+  Use `[Agent Name](agent://agent-id)` for reference-only links, and do not rely
+  on plain text agent names as wake requests.
+- Self-assign only when the wake comment explicitly transfers ownership.
+- Always communicate before exit on active work, except blocked issues with no new context.
+- Treat `issue_passive_followup` as close-out governance, not a fresh assignment.
+- Treat `issue_review_closeout_missing` as review close-out governance.
+- A reviewer does not take over implementation unless explicitly asked.
+- Do not rely on free-form accept/reject text as the durable review outcome.
+- A reviewer request for changes must use `rudder issue review --decision request_changes`, not only a reject comment.
+- If blocked, explicitly set the issue to `blocked` with a blocker comment before exit.
+- Never cancel cross-team tasks. Reassign upward with explanation.
+- Use `chainOfCommand` for escalation.
+- Above 80% spend, focus on critical work only.
+- Use `rudder-create-agent` for hiring or new-agent creation workflows.
+- If you make a git commit you MUST add `Co-Authored-By: Rudder <noreply@github.com/Undertone0809/rudder>` to the end of each commit message.
+- Git commits must use an explicit safe identity. Rudder prepares isolated Codex homes and runtime worktrees with `user.useConfigOnly=true`; if `git commit` reports missing identity, configure repo-local `user.name` and `user.email` instead of bypassing the guard. Never accept `*@*.local` author or committer metadata.
+
+## Essential Commands
+
+Use `references/cli-reference.md` for the full stable command catalog. Keep
+these high-risk command shapes in mind because the wrong command can make work
+invisible or unsafe:
+
+```bash
+rudder agent me --json
+rudder approval get "$RUDDER_APPROVAL_ID" --json
+rudder approval issues "$RUDDER_APPROVAL_ID" --json
+rudder agent inbox --json
+rudder issue context "<issue-id-or-identifier>" --json
+rudder issue context "$RUDDER_TASK_ID" --wake-comment-id "$RUDDER_WAKE_COMMENT_ID" --json
+rudder issue checkout "<issue-id-or-identifier>" --json
+rudder issue comment "<issue-id-or-identifier>" --body-file "<path>" [--image "<path>"] --json
+rudder issue done "<issue-id-or-identifier>" --comment-file "<path>" [--image "<path>"] --json
+rudder issue block "<issue-id-or-identifier>" --comment-file "<path>" [--image "<path>"] --json
+rudder issue review "<issue-id-or-identifier>" --decision approve --comment-file "<path>" --json
+rudder issue review "<issue-id-or-identifier>" --decision request_changes --comment-file "<path>" --json
+rudder issue review "<issue-id-or-identifier>" --decision needs_followup --comment-file "<path>" --json
+rudder issue review "<issue-id-or-identifier>" --decision blocked --comment-file "<path>" --json
+rudder issue create --org-id "$RUDDER_ORG_ID" ... --json
+```
+
+Issue comment and close-out commands accept comment bodies only from files or
+stdin. For multiline Markdown, command names, code spans, code blocks,
+validation summaries, or screenshot evidence, write the body to a temporary
+Markdown file and pass `--body-file <path>` or `--comment-file <path>`. Pass
+`-` to read from stdin.
+
+Add `--image "<path>"` one or more times when the close-out/progress comment
+should include local screenshots or images. Do not leave only a local `/tmp/...`
+or workspace image path in the comment, because board users may not be able to
+inspect it from Rudder.
+
 ## Authentication
 
 Rudder injects the runtime context for you. Common env vars:
@@ -70,169 +141,7 @@ rudder project create --org-id "$RUDDER_ORG_ID" --name "<name>" --json
 rudder project update "<project-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --status in_progress --json
 ```
 
-## Heartbeat Procedure
-
-Follow this order unless the wake context clearly requires a different first step.
-
-**Step 1 — Identity.** If identity is not already known, run:
-
-```bash
-rudder agent me --json
-```
-
-Use the result for your id, org, role, budget, and `chainOfCommand`.
-
-**Step 2 — Approval follow-up.** If `RUDDER_APPROVAL_ID` is set, review it first:
-
-```bash
-rudder approval get "$RUDDER_APPROVAL_ID" --json
-rudder approval issues "$RUDDER_APPROVAL_ID" --json
-```
-
-For each linked issue:
-
-- mark it done if the approval fully resolves the work
-- or add a comment explaining what remains open and what happens next
-
-**Step 3 — Get assignments.** Prefer the compact inbox:
-
-```bash
-rudder agent inbox --json
-```
-
-Inbox rows include a `relationship` field:
-
-- `assignee`: execution work you own
-- `reviewer`: review or blocker-triage work where the issue is in `in_review`
-  or `blocked`
-
-Prioritize active close-out work first: reviewer rows with `status:
-`"in_review"` or `"blocked"`, then assignee `in_progress`, then assignee
-`todo`. Skip assignee-only `blocked` work unless you can actually unblock it.
-
-If `RUDDER_TASK_ID` is set and the task is assigned to you or names you as
-reviewer, prioritize it first.
-
-**Step 4 — Mention-triggered wakes.** If `RUDDER_WAKE_COMMENT_ID` is set, read the relevant issue context before doing anything else on that task:
-
-```bash
-rudder issue context "$RUDDER_TASK_ID" --wake-comment-id "$RUDDER_WAKE_COMMENT_ID" --json
-```
-
-If the comment explicitly asks you to take ownership, you may self-assign by checkout. Otherwise respond only if useful and continue with your assigned work.
-Mention wake rules:
-
-- a board/operator issue comment can wake you by using a plain `@Name` token or an issue-composer agent mention that serializes as `agent://agent-id?intent=wake`
-- a plain structured link such as `agent://agent-id` is a reference-only link for rendering and navigation; do not infer that it woke you unless `RUDDER_WAKE_COMMENT_ID` is set
-- agent-authored issue comments do not fan out peer wakeups by default; use the reviewer, assignment, or explicit handoff workflow instead of pinging another agent into a competing run
-
-An agent mention is a request for attention or collaboration. It does not transfer issue ownership, reopen an issue, or authorize competing runs unless the comment explicitly asks for that handoff and the normal workflow permits it.
-
-**Step 5 — Checkout before work.** Never start work without checkout.
-
-```bash
-rudder issue checkout "<issue-id-or-identifier>" --json
-```
-
-Rules:
-
-- `issue checkout` defaults `--agent-id` from `RUDDER_AGENT_ID`
-- mutating CLI commands automatically attach `RUDDER_RUN_ID` when present
-- a `409` means another agent owns the task; do not retry it
-
-**Step 6 — Understand context.** Prefer the compact heartbeat context instead of replaying everything:
-
-```bash
-rudder issue context "<issue-id-or-identifier>" --json
-```
-
-Comment reading rules:
-
-- if `RUDDER_WAKE_COMMENT_ID` is set, fetch context with that wake comment first
-- if you already know the thread and only need updates, use:
-
-```bash
-rudder issue comments list "<issue-id-or-identifier>" --after "<last-comment-id>" --order asc --json
-```
-
-- use the full comment list only when cold-starting or when incremental context is not enough
-
-**Step 7 — Do the work.** Use your normal tools for the domain task itself.
-
-**Step 8 — Communicate outcome.**
-
-Before exiting an active `todo` or `in_progress` issue run, leave exactly one clear close-out signal. Use a progress comment if work remains, `issue done` if complete, `issue block` if blocked, or an explicit handoff comment when ownership changes. If the issue has a reviewer, `issue block` is also a reviewer handoff: write the blocker clearly enough for the reviewer to decide next steps. Rudder may wake you again with `RUDDER_WAKE_REASON=issue_passive_followup` when a successful run exits without that signal.
-
-When a progress, done, blocker, or handoff comment is meant to get another agent's attention, state the handoff clearly and use the normal reviewer or assignment workflow. Board/operator issue composer mentions can wake an agent, but your own agent-authored comment is treated as coordination context by default and should not be used as a peer wakeup mechanism. Writing an agent's name as plain prose is only a note and may not be rendered or routed as an agent mention.
-
-Before exiting a reviewer run or an inbox row with `relationship: "reviewer"`,
-leave exactly one structured reviewer decision. Do not rely on free-form
-comments such as "reject" or "accepted" as the durable outcome. Reviewer rows
-may be `in_review` or `blocked`; blocked reviewer work is blocker triage, not
-permission to take over implementation unless explicitly asked:
-
-- approve:
-
-```bash
-rudder issue review "<issue-id-or-identifier>" --decision approve --comment-file "<path>" --json
-```
-
-- request changes and return the issue to the assignee:
-
-```bash
-rudder issue review "<issue-id-or-identifier>" --decision request_changes --comment-file "<path>" --json
-```
-
-- keep the issue in its current review/blocker state because specific evidence
-  or follow-up is still missing:
-
-```bash
-rudder issue review "<issue-id-or-identifier>" --decision needs_followup --comment-file "<path>" --json
-```
-
-- block the issue:
-
-```bash
-rudder issue review "<issue-id-or-identifier>" --decision blocked --comment-file "<path>" --json
-```
-
-Use `blocked` to confirm a human/external blocker. The comment must name the next human action; Rudder records a human handoff and removes the issue from repeated reviewer pickup until the board changes the issue.
-
-- progress-only update:
-
-```bash
-rudder issue comment "<issue-id-or-identifier>" --body-file "<path>" [--image "<path>"] --json
-```
-
-- completion:
-
-```bash
-rudder issue done "<issue-id-or-identifier>" --comment-file "<path>" [--image "<path>"] --json
-```
-
-- blocker:
-
-```bash
-rudder issue block "<issue-id-or-identifier>" --comment-file "<path>" [--image "<path>"] --json
-```
-
-- generic patch when workflow commands are not enough:
-
-Issue comment and close-out commands accept comment bodies only from files or
-stdin. For any multiline Markdown, command names, code spans, code blocks,
-validation summaries, or screenshot evidence, write the body to a temporary
-Markdown file and pass `--body-file <path>` or `--comment-file <path>`. Pass
-`-` to read from stdin.
-
-Add `--image "<path>"` one or more times when the close-out/progress comment should include local screenshots or images. Supported local image types are PNG, JPEG, WebP, and GIF; the CLI uploads them as issue attachments and appends Markdown image links.
-
-If your comment mentions a screenshot path or uses a screenshot as validation evidence, attach that file with `--image "<path>"`. Do not leave only a local `/tmp/...` or workspace image path in the comment, because board users may not be able to inspect it from Rudder.
-
-```bash
-rudder issue update "<issue-id-or-identifier>" ... --json
-```
-
-**Step 9 — Delegate if needed.** Create subtasks with the generic create surface only when the workflow really needs a new task:
+## Delegation
 
 ```bash
 rudder issue create --org-id "$RUDDER_ORG_ID" ... [--label-id "<label-id>"] [--label "<label-name>"] --json
@@ -258,21 +167,9 @@ rudder agent skills create "$RUDDER_AGENT_ID" --name "<name>" --description "<de
 
 This creates the package under `AGENT_HOME/skills` and does not require organization skill mutation permission.
 
-When a board user or authorized agent asks you to find, import, inspect, or assign organization skills:
-
-1. Read `references/organization-skills.md`
-2. Use the CLI surfaces in this order:
-
-```bash
-rudder skill scan-local --org-id "$RUDDER_ORG_ID" --json
-rudder skill scan-projects --org-id "$RUDDER_ORG_ID" --json
-rudder skill import --org-id "$RUDDER_ORG_ID" --source "<source>" --json
-rudder skill list --org-id "$RUDDER_ORG_ID" --json
-rudder skill get "<skill-id>" --org-id "$RUDDER_ORG_ID" --json
-rudder skill file "<skill-id>" --org-id "$RUDDER_ORG_ID" --path SKILL.md --json
-rudder agent skills enable "<agent-id>" "<selection-ref>" --json
-rudder agent skills sync "<agent-id>" --desired-skills "<csv>" --json
-```
+When a board user or authorized agent asks you to find, import, inspect, or
+assign organization skills, read `references/organization-skills.md` and follow
+that workflow instead of rebuilding the command sequence here.
 
 Use `skills enable` when adding one or more skills because it preserves the
 agent's existing enabled selections. Use `skills sync` only when you intend to
@@ -322,28 +219,6 @@ Planning rules:
 - when you reference the plan in comments, use the `markdownLink` returned by `rudder library file ref ... --json`
 - `rudder issue documents ...` has been retired. Use Project Library files for durable plans/specs and cite them from issue text or comments.
 
-## Critical Rules
-
-- Always checkout before doing task work.
-- Never retry a `409` from checkout.
-- Never look for unassigned work.
-- Self-assign only on explicit @-mention handoff.
-- Always communicate before exit on active work, except blocked issues with no new context.
-- Treat `issue_passive_followup` as close-out governance, not a fresh assignment: inspect current state, then comment, finish, block, or hand off explicitly.
-- Treat `issue_review_closeout_missing` as review close-out governance: inspect
-  current state, including blocked handoffs, then record one structured review
-  decision.
-- A reviewer does not take over implementation unless explicitly asked.
-- A reviewer request for changes must use `rudder issue review --decision
-  request_changes`, not only a reject comment.
-- If blocked, explicitly set the issue to `blocked` with a blocker comment before exit.
-- Never cancel cross-team tasks. Reassign upward with explanation.
-- Use `chainOfCommand` for escalation.
-- Above 80% spend, focus on critical work only.
-- Use `rudder-create-agent` for hiring or new-agent creation workflows.
-- If you make a git commit you MUST add `Co-Authored-By: Rudder <noreply@github.com/Undertone0809/rudder>` to the end of each commit message.
-- Git commits must use an explicit safe identity. Rudder prepares isolated Codex homes and runtime worktrees with `user.useConfigOnly=true`; if `git commit` reports missing identity, configure repo-local `user.name` and `user.email` instead of bypassing the guard. Never accept `*@*.local` author or committer metadata.
-
 ## Comment Style (Required)
 
 Use concise markdown with:

package/skills/rudder/references/api-reference.md

@@ -94,10 +94,9 @@ Compact resume context for a heartbeat:
 
 Use `?wakeCommentId=<comment-id>` when the run was triggered by a specific comment.
 Mention-triggered comment wakes set `wakeComment` and `RUDDER_WAKE_COMMENT_ID`.
-Board/operator comments can request an agent wake with a plain `@Name` token or
-an issue-composer agent link whose href includes `intent=wake`. Plain
-`agent://agent-id` links are reference-only and should not be treated as wake
-requests.
+Issue comments request an agent wake with an agent link whose href includes
+`intent=wake`. Plain `agent://agent-id` links are reference-only, and plain text
+agent names should not be treated as wake requests.
 
 ### Comments
 

package/skills/rudder/references/cli-reference.md

@@ -60,6 +60,10 @@ Direct API fallback is allowed for heartbeat close-out only when a required CLI
 | `rudder automation get <automation-id>` | Read one automation detail including triggers and recent runs. | no | no | no | no |
 | `rudder automation runs <automation-id>` | List recent runs for one automation. | no | no | no | no |
 | `rudder automation triggers list <automation-id>` | List triggers configured for one automation. | no | no | no | no |
+| `rudder automation triggers create <automation-id> --kind <kind>` | Create a schedule, webhook, or API trigger through the governed automation API. | yes | no | no | attached when available |
+| `rudder automation triggers update <trigger-id>` | Update an automation trigger through the governed automation API. | yes | no | no | attached when available |
+| `rudder automation triggers delete <trigger-id>` | Delete an automation trigger through the governed automation API. | yes | no | no | attached when available |
+| `rudder automation triggers rotate-secret <trigger-id>` | Rotate an automation webhook trigger secret through the governed automation API. | yes | no | no | attached when available |
 | `rudder automation create --org-id <id> --title <title> --assignee-agent-id <id>` | Create an automation through the governed automation API. | yes | required | no | attached when available |
 | `rudder automation update <automation-id>` | Update automation fields through the governed automation API. | yes | no | no | attached when available |
 | `rudder automation enable <automation-id>` | Enable an automation by setting status to active. | yes | no | no | attached when available |
@@ -72,9 +76,10 @@ Direct API fallback is allowed for heartbeat close-out only when a required CLI
 | `rudder chat transcript <chat-id> [--limit <n>] [--cursor <cursor>] [--max-output-chars <n>]` | Read paginated chat messages with assistant transcript entries clipped in human output. | no | no | no | no |
 | `rudder chat read <chat-id> [--turn-limit <n>] [--cursor <cursor>] [--include-output]` | Read a bounded recent-message snapshot for one chat with page cursors. | no | no | no | no |
 | `rudder chat create --org-id <id>` | Create a chat conversation. | yes | required | no | attached when available |
-| `rudder chat send <chat-id> --body <text>` | Send a chat message and persist the assistant reply through the server. | yes | no | no | attached when available |
+| `rudder chat send <chat-id> --body <text>` | Send an agent-authored message directly to the operator in a chat. | yes | no | required | attached when available |
 | `rudder chat archive <chat-id>` | Archive a chat conversation without deleting it. | yes | no | no | attached when available |
-| `rudder runs list --org-id <id>` | List observed agent runs with filters for status, agent, issue, runtime, and time. | no | required | no | no |
+| `rudder runs list --org-id <id> [--used-skill <skill>] [--loaded-skill <skill>]` | List observed agent runs with filters for status, agent, issue, runtime, time, and skill evidence; used-skill means actual usage and loaded-skill is opt-in. | no | required | no | no |
+| `rudder runs by-skill <skill> --org-id <id> [--evidence <used-or-loaded>]` | Build a skill evidence packet from recent runs; defaults to actual usage and returns status counts, agents, issues, common errors, rows, and transcript/errors follow-up commands. | no | required | no | no |
 | `rudder runs get <run-id>` | Read one observed run detail. | no | no | no | no |
 | `rudder runs events <run-id>` | List persisted run events. | no | no | no | no |
 | `rudder runs log <run-id>` | Read stored run log content with clipped human output. | no | no | no | no |