@rudderhq/agent-runtime-cursor-local 0.4.6-canary.11 → 0.4.6-canary.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rudderhq/agent-runtime-cursor-local",
-  "version": "0.4.6-canary.11",
+  "version": "0.4.6-canary.12",
   "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.4.6-canary.11",
+    "@rudderhq/agent-runtime-utils": "0.4.6-canary.12",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {

package/skills/visualize/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: visualize
+description: "Create safe inline visual explanations in Rudder Chat. Use when asked for a chart, plot, diagram, timeline, comparison, static map, simulator, scenario view, or compact visual that materially improves understanding. Prefer Mermaid for static node-and-edge structures; use Rudder's HTML/SVG/CSS artifact path only when thread-scoped output is available. Rudder visuals are declarative and scriptless: convert simulator requests to static scenarios or disclosure-based comparisons and never rely on JavaScript, network access, or external assets."
+compatibility: "Rudder Chat inline visual capture. HTML artifacts require a thread-scoped visualization directory exposed by the current runtime."
+---
+
+# Visualize
+
+Create a visual only when it materially improves what the user can understand,
+compare, or decide. The Rudder inline runtime is scriptless and has no network
+access, so design for a useful first render with declarative HTML, SVG, and CSS.
+
+## Choose The Output
+
+1. Use a normal fenced Mermaid block when labeled nodes and edges fully explain
+   a static structure or flow. Do not create an HTML artifact for that case.
+2. Use an inline visual for charts, timelines, comparisons, spatial layouts,
+   static scenario views, or compact reports that benefit from custom geometry.
+3. Create an HTML artifact only when the current run exposes a writable,
+   thread-scoped visualization directory ending in
+   `visualizations/YYYY/MM/DD/<thread-id>`. Use the exact directory from the
+   runtime's writable roots. Never infer, scan for, or create another thread's
+   directory.
+4. If that directory is unavailable, fall back to Mermaid, Markdown tables, or
+   concise prose. Do not emit a directive that Rudder cannot resolve.
+
+## File And Directive
+
+- Choose a concise ASCII lowercase-hyphenated title and write
+  `<title>.html` inside the current thread-scoped visualization directory.
+- Write only an HTML fragment. Do not include a doctype or `html`, `head`, or
+  `body` elements.
+- Keep every fragment under 2 MiB and emit at most three visuals in one
+  assistant message.
+- Give the fragment one top-level markup root, `<div id="widget">`. Bounded
+  `<style>` blocks may precede that root.
+- Put any custom CSS in bounded `<style>` elements. Inline `style` attributes
+  are removed.
+- Read the file back before replying. Fix escaped markup such as literal `\"`
+  or `\n`, missing labels, clipped content, and malformed SVG.
+- Add this exact directive on its own line where the visual should render:
+
+```text
+::codex-inline-vis{file="<title>.html"}
+```
+
+Use only the `file` attribute. The value must be a basename ending in `.html`;
+paths, separators, traversal, extra attributes, and alternate quoting are
+rejected. Keep any necessary explanation outside the fragment and do not add a
+second Markdown link to the file.
+
+## Rudder Safety Boundary
+
+Rudder sanitizes the fragment before rendering, but generate valid input rather
+than relying on sanitization:
+
+- Do not write scripts, event handlers, JavaScript URLs, forms, links, images,
+  media, nested frames, embedded objects, canvas, or external resources.
+- Do not use `fetch`, XHR, WebSocket, module imports, CDN libraries, web fonts,
+  or URL-bearing CSS. The artifact has no network access.
+- Do not use active controls such as buttons, inputs, selects, or textareas.
+  They are removed because the scriptless runtime cannot preserve their state
+  or behavior safely.
+- Do not implement a parent bridge, follow-up prompt action, filesystem access,
+  or access to Rudder state, credentials, cookies, storage, or APIs.
+- Use `<details>` and `<summary>` for the only stateful native disclosure.
+  Use `data-tooltip` on `<summary>` for short supplementary hover/focus text.
+  A tooltip on any other preserved element is hover-only and must not contain
+  essential information.
+- Keep all data needed for the visual inside the fragment. Use inline SVG for
+  charts and supplied geometry; never fetch a basemap or invent geography.
+
+Read [references/runtime-contract.md](references/runtime-contract.md) before
+writing custom markup or CSS. Use
+[assets/example-chart.html](assets/example-chart.html) as a structure example,
+not as data or copy to repeat.
+
+## Composition
+
+- Start with the visual itself. Do not add decorative KPI rows, repeated
+  legends, permanent toolbars, or explanatory paragraphs inside the fragment.
+- Use one dominant chart, diagram, or comparison. Add up to three compact
+  summary cards only when their values are central to reading the visual.
+- For a requested simulator or adjustable explorer, show representative static
+  scenarios or a disclosure-based comparison and state the limitation in the
+  surrounding response. Do not pretend controls survived when they cannot.
+- For maps, use only user-supplied or locally available geometry that can be
+  embedded as safe SVG. Otherwise choose a table, ranked plot, or schematic.
+- Keep the outer surface transparent and unframed. Use `.card` only for a real
+  bounded summary or detail; never nest cards.
+
+## Layout And Accessibility
+
+- Design for the full Chat width around 736px and reflow cleanly down to 320px.
+- Avoid fixed outer widths, viewport-height layouts, horizontal scrolling,
+  fixed positioning, and clipped labels.
+- Use semantic headings sparingly. Do not restate the user prompt or render a
+  title inside the fragment when the surrounding Markdown already names it.
+- Give each meaningful SVG `role="img"` plus an accessible name or description.
+  Include `<title>` and `<desc>` when they improve screen-reader output.
+- Label important values directly. Add a legend only when multiple series
+  cannot be labeled on the marks.
+- Pair color with text, shape, or line style so meaning never depends on color
+  alone.
+
+## Theme And Utilities
+
+- Use Rudder theme variables for every color. Start with `--foreground`,
+  `--muted-foreground`, `--border`, and `--viz-series-1`; use
+  `--viz-series-2` through `--viz-series-6` only for stable categories.
+- Use host utilities such as `.viz-grid`, `.viz-row`, `.viz-stat`,
+  `.viz-stat-value`, `.viz-badge`, `.card`, `.text-small`, `.text-muted`,
+  `.text-destructive`, and `.sr-only` before adding custom CSS.
+- Keep custom selectors scoped below `#widget`. Use only theme variables already
+  provided by Rudder; custom CSS variables are removed.
+- Use normal text by default and weights 400 or 500. Reserve compact secondary
+  text for annotations, never essential labels.
+
+## Verification
+
+Before replying:
+
+1. Confirm the file is in the exact current-thread visualization directory,
+   uses an allowed basename, is below 2 MiB, and the message has no more than
+   three directives.
+2. Confirm the fragment contains no scripts, handlers, URLs, external assets,
+   active controls, document-level elements, or unsupported embeds.
+3. Confirm SVG view boxes, labels, referenced IDs, table semantics, and CSS
+   selectors are valid.
+4. Check both narrow and wide layout when a preview path is available. If not,
+   keep the geometry responsive and the composition conservative.
+5. Emit the directive only after the file is complete and readable.

package/skills/visualize/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Visualize"
+  short_description: "Create safe inline visuals in Rudder Chat"
+  default_prompt: "Use $visualize to create a clear Rudder-native chart, diagram, comparison, or other inline visual when it improves understanding."
+
+policy:
+  allow_implicit_invocation: true

package/skills/visualize/assets/example-chart.html

@@ -0,0 +1,89 @@
+<style>
+#widget .example-chart {
+  display: grid;
+  gap: 12px;
+}
+
+#widget .example-chart-bars {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  align-items: end;
+  gap: 10px;
+  min-height: 180px;
+  padding-block: 8px;
+  border-bottom: 1px solid var(--border);
+}
+
+#widget .example-chart-bar {
+  display: grid;
+  grid-template-rows: 1fr auto;
+  align-items: end;
+  gap: 6px;
+  min-width: 0;
+  color: var(--foreground);
+  text-align: center;
+}
+
+#widget .example-chart-bar-mark {
+  width: 100%;
+  min-height: 12px;
+  border-radius: var(--radius) var(--radius) 0 0;
+  background: var(--viz-series-1);
+}
+
+#widget .example-chart-bar:nth-child(1) .example-chart-bar-mark {
+  height: 52px;
+}
+
+#widget .example-chart-bar:nth-child(2) .example-chart-bar-mark {
+  height: 72px;
+}
+
+#widget .example-chart-bar:nth-child(3) .example-chart-bar-mark {
+  height: 98px;
+}
+
+#widget .example-chart-bar:nth-child(4) .example-chart-bar-mark {
+  height: 118px;
+}
+
+@media (max-width: 420px) {
+  #widget .example-chart-bars {
+    gap: 5px;
+  }
+}
+</style>
+<div id="widget">
+  <figure class="example-chart" aria-labelledby="example-chart-caption">
+    <figcaption id="example-chart-caption">
+      Completed loops by week
+    </figcaption>
+    <div class="example-chart-bars" role="img" aria-label="Completed loops rose from 8 to 18 over four weeks">
+      <div class="example-chart-bar">
+        <div class="example-chart-bar-mark"></div>
+        <span class="text-small">8</span>
+      </div>
+      <div class="example-chart-bar">
+        <div class="example-chart-bar-mark"></div>
+        <span class="text-small">11</span>
+      </div>
+      <div class="example-chart-bar">
+        <div class="example-chart-bar-mark"></div>
+        <span class="text-small">15</span>
+      </div>
+      <div class="example-chart-bar">
+        <div class="example-chart-bar-mark"></div>
+        <span class="text-small">18</span>
+      </div>
+    </div>
+  </figure>
+  <details class="card">
+    <summary data-tooltip="Show how the sample values are defined">Method</summary>
+    <p class="text-small text-muted">Illustrative weekly counts for validating the Rudder fragment contract.</p>
+  </details>
+  <svg role="img" aria-label="Upward trend marker" viewBox="0 0 120 24">
+    <title>Upward trend</title>
+    <desc>A line rises from left to right across four points.</desc>
+    <polyline points="4,20 40,16 78,9 116,4" fill="none" stroke="var(--viz-series-1)" stroke-width="2" vector-effect="non-scaling-stroke" />
+  </svg>
+</div>

package/skills/visualize/references/runtime-contract.md

@@ -0,0 +1,114 @@
+# Rudder Inline Visual Runtime Contract
+
+Read this reference when producing a Rudder inline visual. The runtime is
+scriptless, sanitized, isolated from Rudder state, and has no network access.
+Every fragment must be under 2 MiB, and one assistant message may reference at
+most three fragments.
+
+## Output Envelope
+
+Write a fragment with one top-level markup root, `<div id="widget">`. Bounded
+`<style>` elements may precede that root. Do not write a doctype or `html`,
+`head`, or `body`; Rudder extracts and sanitizes the CSS before it sanitizes the
+markup.
+
+The assistant message must place this exact directive on its own line:
+
+```text
+::codex-inline-vis{file="<title>.html"}
+```
+
+Only a current-run file from the exact thread-scoped visualization directory is
+eligible for capture. Rudder rejects absolute paths, separators, traversal,
+symlink escapes, missing files, stale files, oversized files, malformed
+directives, unknown attributes, and duplicate attributes.
+
+## Preserved Markup
+
+Use these common HTML elements:
+
+- Structure: `article`, `aside`, `div`, `section`, `main`, `header`, `footer`,
+  `figure`, `figcaption`, `blockquote`, `hr`, `br`.
+- Text: `h1` through `h6`, `p`, `span`, `small`, `strong`, `em`, `b`, `i`,
+  `mark`, `s`, `u`, `code`, `pre`.
+- Lists and data: `ul`, `ol`, `li`, `dl`, `dt`, `dd`, `table`, `caption`,
+  `colgroup`, `col`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`, `meter`,
+  `progress`.
+- Native disclosure: `<details>` and `<summary>`. This is the only supported
+  stateful interaction.
+
+Use inline `<svg>` for charts and diagrams. Supported primitives include
+`svg`, `g`, `defs`, `title`, `desc`, `path`, `line`, `rect`, `circle`, `ellipse`,
+`polygon`, `polyline`, `text`, `tspan`, `linearGradient`, `radialGradient`, and
+`stop`. Do not use clipping paths; the runtime does not preserve a safe
+`clip-path` reference.
+
+Common preserved attributes include:
+
+- Accessibility and structure: `role`, `aria-label`, `aria-labelledby`,
+  `aria-describedby`, `aria-hidden`, `id`, `class`, `scope`, `colspan`,
+  `rowspan`, `open`, `value`, `min`, and `max`.
+- Tooltip: `data-tooltip`, limited to concise plain text.
+- SVG geometry and paint: `viewBox`, `preserveAspectRatio`, `x`, `y`, `x1`,
+  `x2`, `y1`, `y2`, `cx`, `cy`, `r`, `rx`, `ry`, `width`, `height`, `d`,
+  `points`, `transform`, `fill`, `stroke`, opacity, line, gradient, text-anchor,
+  and vector-effect attributes.
+
+IDs and class tokens must start with a letter and contain only letters, digits,
+underscores, and hyphens. Keep each token at most 64 characters. A class list is
+limited to 24 safe tokens. Use `url(#safe-id)` only for an inline SVG paint
+reference such as a gradient; all external URL values are removed.
+
+## Removed Markup
+
+Do not generate `<script>`, `a`, `button`, `input`, `select`, `textarea`,
+`form`, `img`, `image`, `audio`, `video`, `canvas`, `iframe`, `object`, `embed`,
+`foreignObject`, `use`, SVG animation, document metadata, or external resource
+elements. The runtime removes those elements and every URL-bearing or event
+handler attribute.
+
+There is no JavaScript, Lucide runtime, CDN library, parent bridge,
+`window.openai`, API access, storage, cookies, or authenticated context. A
+visual that depends on any of them is not a Rudder inline visual.
+
+## CSS
+
+Use host classes first:
+
+- Layout: `.viz-grid` and `.viz-row`. `.viz-controls` is also available as a
+  wrapping layout class, but it does not make removed buttons, inputs, selects,
+  or other active controls usable.
+- Summaries: `.card`, `.viz-stat`, `.viz-stat-value`, `.viz-badge`.
+- Text: `.text-small`, `.text-muted`, `.text-destructive`, `.sr-only`.
+- Tooltip: add `data-tooltip="Concise detail"` to `<summary>` for hover and
+  keyboard-focus behavior. On another preserved element it is hover-only, so
+  keep essential information visible elsewhere.
+
+The host provides theme variables including `--background`, `--foreground`,
+`--card`, `--card-foreground`, `--popover`, `--popover-foreground`, `--primary`,
+`--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`,
+`--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`,
+`--border`, `--input`, `--ring`, `--font-size-base`, `--radius`, and
+`--viz-series-1` through `--viz-series-6`.
+
+Custom `<style>` content is bounded to eight style blocks and 32 KiB total.
+Use ordinary rules and responsive `@media` rules only. The sanitizer removes
+custom properties, URL values, imports, fonts, namespaces, keyframes, property
+registrations, malformed CSS, unknown functions, and unsupported declarations.
+Inline `style` attributes are always removed.
+
+Safe custom CSS commonly uses grid or flex layout, spacing, borders, text,
+theme colors, dimensions, responsive media queries, and static transforms. Keep
+selectors scoped beneath `#widget` and keep the result useful without animation.
+
+## Responsive And Accessible Output
+
+- Support widths from 736px down to 320px without horizontal overflow.
+- Use responsive SVG view boxes and `max-width: 100%` behavior.
+- Reserve enough space for the longest labels and values.
+- Give charts and diagrams a screen-reader name and, when useful, description.
+- Use tables when exact values matter more than spatial comparison.
+- Pair every color encoding with text, shape, or another non-color cue.
+
+See `../assets/example-chart.html` for a minimal contract-valid fragment. Its
+data is illustrative; reuse the structure, not the values.