@rudderhq/agent-runtime-codex-local 0.3.5-canary.9 → 0.3.5

package/skills/para-memory-files/evals/conversation-capture.md

@@ -0,0 +1,128 @@
+# Conversation and Agent Work Capture Evals
+
+Use these lightweight cases when changing the `para-memory-files` skill's
+Rudder chat and agent work capture behavior. They are written for human or
+agent review, not a dedicated automated harness.
+
+### Case: User Corrects Memory Behavior
+
+Input:
+
+A user says: "No, do not just leave this in your personal MEMORY.md. This
+should become an org skill rule so other agents stop missing chat context."
+
+Expected behavior:
+
+- Write a concise daily-note chat capture with context, user intent,
+  conclusion/action, reusable lesson, and follow-up/risk.
+- Route the stable behavior change toward the relevant skill package or skill
+  patch proposal.
+- Update personal MEMORY.md only if there is also a personal operating
+  preference for this agent.
+
+Must not:
+
+- Copy the full transcript into memory.
+- Treat the correction as only a personal preference.
+- Hide the organization-wide fix in one agent's private memory.
+
+### Case: Issue Close-Out Without New Signal
+
+Input:
+
+An issue comment says: "Done, tests passed, commit abc123." It repeats the
+same evidence already present in the issue and contains no new preference,
+decision, correction, or reusable lesson.
+
+Expected behavior:
+
+- No daily-note capture is required.
+- If the agent needs an audit trail, rely on the issue itself as the source of
+  truth.
+
+Must not:
+
+- Record low-signal close-out chatter just because it happened in chat.
+- Promote repeated issue status into personal memory.
+
+### Case: Automation Work Produces Reusable Lesson
+
+Input:
+
+During a scheduled CI patrol automation, the agent discovers that a recurring
+workflow failure should be repaired directly when credentials and local
+reproduction are available, and only escalated when the platform is down or a
+non-substitutable secret is missing.
+
+Expected behavior:
+
+- Write a concise daily-note memory capture that names the automation context,
+  durable escalation rule, action taken, reusable lesson, and follow-up risk.
+- Promote the shared operating rule to the relevant project know-how, skill, or
+  agent instruction when it affects future agents or recurring automations.
+- Keep raw logs, credentials, and noisy command output out of memory.
+
+Must not:
+
+- Ignore the event because it came from automation instead of chat.
+- Store the complete automation transcript or secrets in a personal memory file.
+- Hide an organization-wide automation rule only in one agent's private memory.
+
+### Case: Low-Signal Chat
+
+Input:
+
+A chat contains greetings, thanks, and "I'll check later" with no task
+definition or durable preference.
+
+Expected behavior:
+
+- Do not write a memory entry.
+- Continue the conversation normally.
+
+Must not:
+
+- Create a daily note from politeness or temporary scheduling chatter.
+
+### Case: Project-Level Decision
+
+Input:
+
+A user explains that future Rudder proposals for non-trivial architecture work
+must live in the project Library first, receive two critique rounds, and only
+then be implemented.
+
+Expected behavior:
+
+- Capture the chat signal in the daily note.
+- Promote the project-level policy to shared project knowledge under the
+  project Library or organization workspace.
+- If it changes agent behavior generally, propose or update the relevant skill.
+
+Must not:
+
+- Store the policy only in `$AGENT_HOME/instructions/MEMORY.md`.
+- Skip the shared knowledge artifact when the rule affects multiple agents.
+
+### Case: Attachment Changes Task Interpretation
+
+Input:
+
+A user attaches a screenshot and says the real problem is not the visible
+button style but the workflow confusion shown by the screenshot.
+
+Expected behavior:
+
+- Capture the daily-note context, including the conversation or issue reference
+  and a short description of how the attachment changed the task.
+- Route any reusable product or execution lesson to shared project knowledge
+  when it affects future project work.
+- Keep the attachment details summarized and avoid sensitive visual content
+  that is not needed for future behavior.
+
+Must not:
+
+- Preserve the entire image transcript or private visual details in personal
+  memory.
+- Ignore the attachment-driven reinterpretation when forming future task
+  context.

package/skills/para-memory-files/references/schemas.md

@@ -17,6 +17,37 @@
   access_count: 0
 ```
 
+## Daily Note Conversation and Agent Work Capture Entry
+
+Daily notes are lightweight chronological logs. Use this structure when a
+Rudder chat, issue run, automation, review, close-out, or other agent execution
+event contains durable signal worth retaining.
+
+```md
+## HH:MM - Memory capture
+
+- Context: conversation, issue, automation, run, or evidence reference; project;
+  and why this mattered.
+- User intent: durable correction, preference, constraint, decision, or task
+  interpretation.
+- Conclusion/action: what changed, what was done, or where it was routed.
+- Reusable lesson: future behavior, command, validation signal, or routing rule.
+- Follow-up/risk: unresolved uncertainty, owner, promotion target, or none.
+```
+
+Keep entries summarized and redacted:
+
+- Do not copy full private transcripts.
+- Do not copy raw automation logs, command output, or routine close-out text
+  when they add no durable signal beyond the source artifact.
+- Do not store secrets, tokens, credentials, private keys, session cookies, or
+  auth headers.
+- Do not turn one-off sensitive context into durable memory unless the future
+  behavioral lesson can be safely stated without the sensitive detail.
+- If the information belongs in shared project knowledge, note the routing
+  decision in the daily note and promote it to the project Library or
+  organization workspace.
+
 ## Memory Decay
 
 Facts decay in retrieval priority over time so stale info does not crowd out recent context.

package/skills/rudder/SKILL.md

@@ -21,7 +21,7 @@ organization-skill operations.
 
 ## Control-Plane Interface
 
-- Use `rudder ... --json` for normal control-plane work.
+- Use `rudder ... --json` for normal control-plane work. CLI output renders IDs as short IDs by default; `rudder runs ...` commands accept short run IDs. Add `--full-ids` only for debugging or compatibility checks that need raw UUIDs.
 - 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.
@@ -77,6 +77,7 @@ rudder issue review "<issue-id-or-identifier>" --decision request_changes --comm
 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
+rudder user activity --user me --since today --json
 ```
 
 Issue comment and close-out commands accept comment bodies only from files or
@@ -90,6 +91,23 @@ 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.
 
+## User Activity Context
+
+Use `rudder user activity --user me --since today --json` when you need a
+user-centered view of recent Rudder behavior before claiming context is missing,
+before answering questions like "what did I do today?", "which agents did I
+talk to?", or "what feedback did I give?", and before turning broad recent
+activity into daily notes, handoff context, or preference candidates.
+
+The ledger returns safe excerpts plus source/provenance pointers across
+user-authored chat messages, issue comments, approval comments, and user actor
+activity events. Treat summaries and excerpts as pointers, not ground truth
+when exact wording matters. Inspect the cited source before writing durable
+memory, taste/profile updates, or conclusions about stable user preference. Do
+not use the ledger to bypass organization or project permissions, and do not
+store private content in long-term memory unless it is an explicit durable
+preference or operating lesson.
+
 ## Authentication
 
 Rudder injects the runtime context for you. Common env vars:
@@ -120,7 +138,9 @@ Rules:
 
 Each organization has one system-managed shared workspace root at:
 
-- `~/.rudder/instances/<instance>/organizations/<org-id>/workspaces`
+- `~/.rudder/instances/<instance>/organizations/<org-storage-key>/workspaces`
+
+`<org-storage-key>` is the filesystem-safe storage key for the organization. For UUID-backed organizations it is the Rudder short ID form: the first 12 lowercase hex characters of the UUID with dashes removed. The API and database still use the full organization id.
 
 Important files and conventions:
 
@@ -191,9 +211,11 @@ If asked to make or revise durable project work files, use the Library as a loca
 
 When you need to cite a Library file in a chat reply, issue comment, review, blocker, or done comment, use the `markdownLink` returned by `rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>" --json`. Do not hand-write `library-entry://...` URLs.
 
-Strong Library links look like normal Markdown, but the target contains only
-the stable Library entry id. Title and path are display or lookup details
-returned by Rudder, not URL metadata agents should encode:
+Strong Library links look like normal Markdown. The stable Library entry id is
+the identity; Rudder may add a `p` query parameter as a synchronous path hint so
+the UI can navigate immediately before entry metadata finishes loading. Agents
+must not hand-write that query parameter; copy the `mentionHref` or
+`markdownLink` returned by Rudder:
 
 ```md
 [Project work file](library-entry://<entry-id>)
@@ -210,7 +232,8 @@ rudder issue comment "<issue-id-or-identifier>" --body-file "<path>" --json
 The `ref`, `put`, and `get` JSON responses include:
 
 - `libraryEntryId`: stable Library file identity
-- `mentionHref`: the raw `library-entry://<entry-id>` target
+- `mentionHref`: the raw `library-entry://<entry-id>` target, optionally with
+  Rudder-generated `?p=<url-encoded-path-hint>`
 - `markdownLink`: the Markdown link to paste into the comment body
 
 For close-out comments, copy `markdownLink` from the JSON response into your temporary Markdown comment file and post that link as the Rudder-visible handoff checkpoint. Direct filesystem writes are not complete handoff evidence until the file is cited with the returned `markdownLink`. The `ref` argument is a Library-relative path such as `$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>`, not the absolute `$RUDDER_PROJECT_LIBRARY_ROOT/...` filesystem path. If `$RUDDER_PROJECT_LIBRARY_ROOT` is unset or inaccessible, use `rudder library file get/put "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>"` as the remote or restricted runtime fallback. Use older `library-file://...` links only when you are preserving or reading legacy content that has no `libraryEntryId`.

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

@@ -139,6 +139,7 @@ Use the incremental `after` form when you already know the thread.
 - `GET /api/orgs/:orgId/goals`
 - `POST /api/orgs/:orgId/goals`
 - `GET /api/orgs/:orgId/activity`
+- `GET /api/orgs/:orgId/users/:userId/activity-ledger`
 - `GET /api/orgs/:orgId/costs/summary`
 - `GET /api/orgs/:orgId/costs/by-agent`
 - `GET /api/orgs/:orgId/costs/by-project`
@@ -197,8 +198,8 @@ Workspace file detail responses include renderable reference fields:
 {
   "filePath": "projects/rudder/RUD-123.md",
   "libraryEntryId": "entry-uuid",
-  "mentionHref": "library-entry://entry-uuid",
-  "markdownLink": "[RUD-123.md](library-entry://entry-uuid)"
+  "mentionHref": "library-entry://entry-uuid?p=projects%2Frudder%2FRUD-123.md",
+  "markdownLink": "[RUD-123.md](library-entry://entry-uuid?p=projects%2Frudder%2FRUD-123.md)"
 }
 ```
 
@@ -214,6 +215,11 @@ the remote or restricted runtime fallback. `library-file://...` is legacy weak
 path syntax and should not be used for new durable Library references when
 `libraryEntryId` is available.
 
+The `libraryEntryId` remains the strong identity. The optional `p` query value
+is a Rudder-generated synchronous path hint for fast UI navigation before entry
+metadata is available; agents should copy returned links instead of constructing
+or editing that URL by hand.
+
 ## Approval Workflows
 
 - `GET /api/approvals/:approvalId`

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

@@ -5,13 +5,14 @@ Stable CLI contract for agents using the bundled `rudder` skill. Prefer these co
 ## Defaults
 
 - All commands support `--json`.
+- CLI output renders IDs as short IDs by default; `rudder runs ...` commands accept short run IDs. Add `--full-ids` only when a debugging or compatibility workflow needs raw UUIDs.
 - `--org-id` defaults to `RUDDER_ORG_ID` when relevant.
 - `--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.
+`rudder ... --json` commands must write valid JSON to stdout on success. ID fields in CLI JSON use short display IDs by default; pass `--full-ids` to preserve raw UUIDs. Short run IDs returned by CLI output can be passed back into `rudder runs get`, `events`, `log`, `transcript`, `errors`, `cancel`, and `retry`. 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.
 
@@ -42,6 +43,7 @@ Direct API fallback is allowed for heartbeat close-out only when a required CLI
 | `rudder project get <project-id-or-shortname> [--org-id <id>]` | Read one project by ID or shortname. | no | no | no | no |
 | `rudder project create --org-id <id> --name <name>` | Create a project in the organization. | yes | required | no | attached when available |
 | `rudder project update <project-id-or-shortname> [--org-id <id>]` | Update mutable project fields such as name, description, status, goals, lead agent, target date, color, or archivedAt. | yes | no | no | attached when available |
+| `rudder user activity --user me --since today --json` | Read a user-centered activity ledger with safe excerpts and provenance across chats, issue comments, approval comments, and user actor activity. | no | required | no | no |
 | `rudder library file list [directory]` | List Library files and folders; file rows include `libraryEntryId` when a strong reference can be generated. | no | required | no | no |
 | `rudder library file get <path>` | Fallback read when local filesystem access is unavailable; JSON includes `mentionHref` and `markdownLink`. | no | required | no | no |
 | `rudder library file ref <path>` | Return the stable Markdown reference for one Library file without printing file content. | no | required | no | no |
@@ -132,9 +134,12 @@ printf '%s\n' "$result" | jq -r .markdownLink
 The relevant JSON fields are:
 
 - `libraryEntryId`: stable identity for the Library file.
-- `mentionHref`: raw `library-entry://<id>` target.
+- `mentionHref`: raw `library-entry://<id>` target, optionally with a
+  Rudder-generated `p` query parameter as a path hint for the current Library
+  path.
 - `markdownLink`: complete Markdown link that the renderer turns into a Library
-  chip and that continues resolving after Rudder-managed rename or move.
+  chip. Its identity remains the entry id; any `p` query value is only a
+  synchronous navigation hint and agents should not hand-write it.
 
 Use `rudder library file get/put` only when local filesystem access to the
 Library is unavailable, such as remote or restricted runtimes. `rudder library

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

@@ -98,7 +98,8 @@ rudder skill scan-projects \
 
 Notes:
 
-- Rudder now uses one fixed org workspace root at `~/.rudder/instances/<instance>/organizations/<org-id>/workspaces`.
+- Rudder now uses one fixed org workspace root at `~/.rudder/instances/<instance>/organizations/<org-storage-key>/workspaces`.
+- `<org-storage-key>` is the filesystem storage key. For UUID-backed organizations, use the short ID form: the first 12 lowercase hex characters of the UUID with dashes removed. API calls still use the full organization id.
 - `scan-projects` should be treated as a compatibility command that scans the shared org workspace plus any legacy project workspace records that still exist.
 - The org `Resources` catalog is the canonical place to register shared repos, docs, URLs, and connector objects for agents.
 - Workspaces remains the disk-backed shared file surface. In local trusted runs, durable project work should be written directly under `$RUDDER_PROJECT_LIBRARY_ROOT`; use `$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>` when asking Rudder for a renderable reference. When a run creates or updates a durable Library file, its final chat reply or issue comment should include a user-visible Markdown link to that file.