@rudderhq/agent-runtime-gemini-local 0.2.4-canary.0 → 0.2.5-canary.0

package/package.json

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

package/skills/rudder/SKILL.md

@@ -12,7 +12,7 @@ This skill is now **CLI-first**.
 - Use `rudder ... --json` for 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.
+- 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.
 
 ## Authentication
@@ -109,6 +109,7 @@ rudder issue context "$RUDDER_TASK_ID" --wake-comment-id "$RUDDER_WAKE_COMMENT_I
 ```
 
 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.
+An `@Name` 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.
 
@@ -218,6 +219,14 @@ Always set `parentId`. Set `goalId` unless you are intentionally creating top-le
 
 ## Organization Skills Workflow
 
+When you need to create a skill for yourself, prefer an agent-private skill:
+
+```bash
+rudder agent skills create "$RUDDER_AGENT_ID" --name "<name>" --description "<description>" --enable --json
+```
+
+This creates the package under `AGENT_HOME/skills` and does not require organization skill mutation permission.
+
 When a board user, CEO, or manager asks you to find, import, inspect, or assign organization skills:
 
 1. Read `references/organization-skills.md`

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

@@ -181,7 +181,7 @@ When `RUDDER_APPROVAL_ID` is set, read the approval and its linked issues first.
 
 - `GET /llms/agent-configuration.txt`
 - `GET /llms/agent-configuration/:agentRuntimeType.txt`
-- `GET /llms/agent-icons.txt`
+- `GET /llms/agent-icons.txt` (legacy named icons for compatibility/debugging; normal hires should omit `icon`)
 - `GET /api/orgs/:orgId/agent-configurations`
 - `GET /api/agents/:agentId/configuration`
 - `GET /api/agents/:agentId/config-revisions`

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

@@ -9,6 +9,12 @@ Stable CLI contract for agents using the bundled `rudder` skill. Prefer these co
 - `--run-id` defaults to `RUDDER_RUN_ID` and is attached to mutating requests when available.
 - `issue checkout` defaults `--agent-id` from `RUDDER_AGENT_ID`.
 
+## JSON Output Contract
+
+`rudder ... --json` commands must write valid JSON to stdout on success. If a command cannot produce the requested JSON, it must exit nonzero and write a diagnostic error to stderr. An exit-0 command with empty stdout is a CLI/runtime defect, not a valid empty result.
+
+Direct API fallback is allowed for heartbeat close-out only when a required CLI command fails diagnostically or returns exit 0 with empty stdout. When using fallback, note the affected command and reason in the issue comment or run notes so the CLI path can be fixed.
+
 ## Agent V1 Commands
 
 | Command | Description | Mutating | Org | Agent | Run ID |
@@ -16,6 +22,7 @@ Stable CLI contract for agents using the bundled `rudder` skill. Prefer these co
 | `rudder agent me` | Show the authenticated agent identity, budget, and chain of command. | no | no | no | no |
 | `rudder agent inbox` | List the compact assignee and reviewer work inbox for the authenticated agent. | no | no | no | no |
 | `rudder agent capabilities` | List the stable Rudder agent command contract. | no | no | no | no |
+| `rudder agent skills create [agent-id] --name <name> [--enable]` | Create an agent-private skill package under AGENT_HOME/skills. | yes | no | no | attached when available |
 | `rudder agent skills enable <agent-id> <selection-ref...>` | Add skill selections to an agent without replacing existing enabled skills. | yes | no | no | attached when available |
 | `rudder agent skills sync <agent-id>` | Sync the desired enabled skill set for an agent. | yes | no | no | attached when available |
 | `rudder issue get <issue>` | Read a full issue by UUID or identifier. | no | no | no | no |
@@ -86,7 +93,7 @@ Do not rely on a free-form reject or accept comment as the review outcome. The s
 - `rudder agent config doc <agent-runtime-type>` — Read adapter-specific configuration guidance for one runtime.
 - `rudder agent config list --org-id <id>` — List redacted agent configuration snapshots for an organization.
 - `rudder agent config get <agent-id-or-shortname>` — Read one redacted agent configuration snapshot by id or shortname.
-- `rudder agent icons` — List allowed agent icon names for create and hire payloads.
+- `rudder agent icons` — List legacy named agent icons for compatibility/debugging; normal create and hire payloads should omit icon.
 - `rudder issue create --org-id <id> ...` — Create a new issue or subtask with the generic issue surface; agent-created issues default to the creating agent when no assignee is supplied.
 - `rudder approval create --org-id <id> --type <type> --payload <json>` — Create a new approval request.
 - `rudder approval resubmit <approval-id> [--payload <json>]` — Resubmit a revision-requested approval, optionally with updated payload.

package/skills/rudder/references/organization-skills.md

@@ -4,6 +4,14 @@ Use this reference when a board user, CEO, or manager asks you to discover, impo
 
 This workflow is now **CLI-first** for the bundled `rudder` skill.
 
+For a skill that belongs only to the running agent, do not use organization import or scan commands. Use:
+
+```bash
+rudder agent skills create "$RUDDER_AGENT_ID" --name "<name>" --description "<description>" --enable --json
+```
+
+Agent-private skill creation writes under `AGENT_HOME/skills` and does not require organization skill mutation permission.
+
 ## Canonical Model
 
 1. import or scan the skill into the organization library

package/skills/rudder-create-agent/SKILL.md

@@ -59,13 +59,7 @@ rudder agent config list --org-id "$RUDDER_ORG_ID" --json
 rudder agent config get "<agent-id>" --json
 ```
 
-5. Discover allowed agent icons and pick one that matches the role.
-
-```sh
-rudder agent icons
-```
-
-6. If the role needs organization skills on day one, inspect or import them before hiring.
+5. If the role needs organization skills on day one, inspect or import them before hiring.
 
 ```sh
 rudder skill list --org-id "$RUDDER_ORG_ID" --json
@@ -76,13 +70,14 @@ rudder skill scan-local --org-id "$RUDDER_ORG_ID" --roots "<csv>" --json
 rudder skill scan-projects --org-id "$RUDDER_ORG_ID" --project-ids "<csv>" --workspace-ids "<csv>" --json
 ```
 
-7. Draft the hire payload.
+6. Draft the hire payload.
 
 Required thinking:
 
 - role / title / optional `name`
 - `name` is optional; if omitted, Rudder assigns a distinct personal name automatically
-- `icon` from `rudder agent icons`
+- omit `icon` for normal hires; Rudder assigns a DiceBear Notionists avatar automatically
+- only set `icon` when preserving an explicit DiceBear avatar reference or an uploaded `asset:<uuid>` image avatar reference provided by the board/UI
 - reporting line (`reportsTo`)
 - adapter type
 - optional `desiredSkills` from the organization skill library
@@ -108,13 +103,12 @@ Draft `promptTemplate` as a durable SOUL document, not a one-line command. Use t
 - Voice: how the agent should communicate
 - Continuity: what should become memory or explicit instruction updates over time
 
-8. Submit the canonical hire request.
+7. Submit the canonical hire request.
 
 ```sh
 rudder agent hire --org-id "$RUDDER_ORG_ID" --payload '{
   "role": "cto",
   "title": "Chief Technology Officer",
-  "icon": "crown",
   "reportsTo": "<ceo-agent-id>",
   "capabilities": "Owns technical roadmap, architecture, staffing, execution",
   "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
@@ -136,7 +130,7 @@ rudder agent hire --org-id "$RUDDER_ORG_ID" --payload '{
 
 Do **not** substitute `rudder approval create --type hire_agent` for this step unless you are doing low-level debugging. That bypasses the canonical direct-create vs pending-approval behavior.
 
-9. Handle governance state.
+8. Handle governance state.
 
 If the hire response includes `approval`, monitor and discuss on the approval thread:
 
@@ -171,7 +165,7 @@ Before sending a hire request:
 
 - if the role needs skills, make sure they already exist in the org library or import them first using the Rudder org-skills workflow
 - reuse proven config patterns from related agents where possible
-- set a concrete `icon` from `rudder agent icons` so the new hire is identifiable in org and task views
+- omit `icon` for normal hires so the server generates the default DiceBear Notionists avatar
 - avoid secrets in plain text unless required by adapter behavior
 - ensure the reporting line is correct and in-org
 - ensure the prompt is role-specific, operationally scoped, and structured enough to become the agent's durable `SOUL.md`

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

@@ -12,7 +12,6 @@ Internal/debug reference for the bundled `rudder-create-agent` skill.
 | --- | --- |
 | `rudder agent config index` | `GET /llms/agent-configuration.txt` |
 | `rudder agent config doc <agentRuntimeType>` | `GET /llms/agent-configuration/:agentRuntimeType.txt` |
-| `rudder agent icons` | `GET /llms/agent-icons.txt` |
 | `rudder agent config list --org-id <orgId>` | `GET /api/orgs/:orgId/agent-configurations` |
 | `rudder agent config get <agentId>` | `GET /api/agents/:agentId/configuration` |
 | `rudder agent hire --org-id <orgId> --payload <json>` | `POST /api/orgs/:orgId/agent-hires` |
@@ -25,7 +24,6 @@ Internal/debug reference for the bundled `rudder-create-agent` skill.
 
 - `GET /llms/agent-configuration.txt`
 - `GET /llms/agent-configuration/:agentRuntimeType.txt`
-- `GET /llms/agent-icons.txt`
 
 Auth:
 
@@ -82,7 +80,6 @@ Request body:
 {
   "role": "cto",
   "title": "Chief Technology Officer",
-  "icon": "crown",
   "reportsTo": "uuid-or-null",
   "capabilities": "Owns architecture and engineering execution",
   "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
@@ -143,6 +140,8 @@ Response when approval is not required:
 Important notes:
 
 - `name` is optional; if omitted or blank, Rudder assigns a distinct first name automatically
+- `icon` is optional; omit it for normal hires so Rudder generates a DiceBear Notionists avatar automatically
+- only pass `icon` when the board/UI supplied an explicit DiceBear Notionists reference or uploaded `asset:<uuid>` image avatar reference
 - `desiredSkills` accepts organization skill ids, canonical keys, or a unique slug; the server resolves and stores canonical organization skill keys
 - `agentRuntimeConfig.promptTemplate`, when present for local runtimes during hire, is role/persona content that Rudder materializes as managed `SOUL.md`
 - write hire-time `promptTemplate` as a durable SOUL document with mission, responsibilities, boundaries, decision principles, voice, and continuity when the role has ongoing authority

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

@@ -7,7 +7,7 @@ Canonical CLI contract for the bundled `rudder-create-agent` skill. Prefer these
 - All commands support `--json`.
 - `--org-id` defaults to `RUDDER_ORG_ID` when relevant.
 - Mutating commands attach `RUDDER_RUN_ID` automatically when available.
-- `agent config index`, `agent config doc`, and `agent icons` print plain text by default. With `--json`, they emit that text as a JSON string.
+- `agent config index` and `agent config doc` print plain text by default. With `--json`, they emit that text as a JSON string.
 
 ## Core CLI Surface
 
@@ -21,7 +21,6 @@ rudder agent config index
 rudder agent config doc "<agent-runtime-type>"
 rudder agent config list --org-id "$RUDDER_ORG_ID" --json
 rudder agent config get "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
-rudder agent icons
 ```
 
 Use these in order:
@@ -30,7 +29,6 @@ Use these in order:
 2. `agent config index` to discover installed runtimes
 3. `agent config doc` to read one runtime's required fields and examples
 4. `agent list` plus `agent config list/get` to reuse proven patterns from related agents
-5. `agent icons` to choose an allowed `icon`
 
 ### Organization skills
 
@@ -57,7 +55,6 @@ Use these before hiring when the new role needs `desiredSkills`.
 rudder agent hire --org-id "$RUDDER_ORG_ID" --payload '{
   "role": "cto",
   "title": "Chief Technology Officer",
-  "icon": "crown",
   "reportsTo": "<ceo-agent-id>",
   "capabilities": "Owns technical roadmap, architecture, staffing, execution",
   "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
@@ -104,7 +101,7 @@ The `agent hire` payload accepts the same shape as the hire API, including:
 - `name` optional; blank or omitted means Rudder assigns a distinct first name
 - `role`: one of `ceo`, `cto`, `cmo`, `cfo`, `engineer`, `designer`, `pm`, `qa`, `devops`, `researcher`, `general`
 - `title`
-- `icon`
+- `icon` optional; omit it for normal hires so Rudder generates a DiceBear Notionists avatar automatically. Only provide an explicit DiceBear reference or uploaded `asset:<uuid>` image avatar reference when the board/UI supplied one.
 - `reportsTo`
 - `capabilities`
 - `desiredSkills`