[integration] big-agents

.agents/skills/agenta-package-practices/SKILL.md

@@ -134,6 +134,8 @@ via `ModalFooter`, theme integration.
 
 ## Style utilities and presentational components
 
+When adding or changing UI elements, implement appearance and interaction states for both light and dark themes, and verify both before considering the work complete.
+
 ```typescript
 import {cn, textColors, bgColors} from "@agenta/ui"
 

.agents/skills/sync-model-catalog/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: sync-model-catalog
+description: Regenerate and refresh the curated agent model catalog (the label/description/pricing/ratings behind the agent model picker). Use when the pinned @earendil-works/pi-ai version bumps, when a Claude Code build changes its accepted alias set, or before a release when the curated Claude/Pi facts (lineup, pricing, ratings) need refreshing from current public sources. Owns the data files under sdks/python/agenta/sdk/agents/data/; never edits capabilities.py logic.
+allowed-tools: Read, Edit, Write, Grep, Glob, Bash, WebSearch, WebFetch
+user-invocable: true
+---
+
+# Sync model catalog
+
+Keeps the agent model catalog honest. The catalog is the curated decoration over each harness's
+accepted model set: clean labels, one-sentence descriptions, real pricing, and 1-5 ratings, keyed
+by the id the harness accepts. It is published additively next to the ids-only `models` map on the
+harness capability record (`capabilities.py`).
+
+Design and rationale:
+`docs/design/agent-workflows/projects/model-catalog-schema/{design.md,plan.md}`.
+
+## What it owns
+
+Three JSON data files under `sdks/python/agenta/sdk/agents/data/`, loaded by
+`sdks/python/agenta/sdk/agents/model_catalog.py`:
+
+- `pi_models.generated.json` — machine-generated from pi-ai. Objective facts only (name / pricing /
+  context_window / modalities), `source: "pi_generated"`. **Never hand-edit.**
+- `pi_models.curated.json` — human overlay for the generated file (id -> `{label?, description?,
+  ratings?}`), merged onto the generated facts at load. Survives regeneration.
+- `claude_models.curated.json` — hand-curated Claude alias entries (facts + judgments),
+  `source: "curated"`.
+
+It never edits `capabilities.py` logic — only these data files.
+
+## The three jobs
+
+### 1. Regenerate the Pi file (on a pi-ai version bump)
+
+The generator reads the pinned pi-ai `models.generated` for the providers Agenta reaches (the
+vault-mapped providers plus `openai-codex`) and emits one entry per model. pi-ai provider names are
+mapped to Agenta's vocabulary (`google`->`gemini`, `together`->`together_ai`); ids are
+`<agenta-provider>/<pi-model-id>`.
+
+```bash
+# From repo root. Point at the pinned pi-ai in the runner's node_modules (the .pnpm path includes
+# the version — resolve it with the glob).
+MODELS=$(ls services/runner/node_modules/.pnpm/@earendil-works+pi-ai@*/node_modules/@earendil-works/pi-ai/dist/models.generated.js | head -1)
+node .agents/skills/sync-model-catalog/generate_pi_models.mjs "$MODELS" \
+  sdks/python/agenta/sdk/agents/data/pi_models.generated.json
+```
+
+Detect the bump from a lockfile diff on `@earendil-works+pi-ai@<version>`. The `_generator` field
+in the output records the exact pi-ai version. The curated overlay is untouched — only the
+`.generated.json` is rewritten, so the merge on load re-applies the human judgments.
+
+### 2. Sync Claude to the live accepted set (needs a running runner)
+
+`claude_models.curated.json` must cover exactly the aliases the Claude harness accepts. Probe the
+live set: start a Claude session on a running runner and read the model config options (the same
+`getConfigOptions` call `allowedModels` uses in `services/runner/src/engines/sandbox_agent/model.ts`).
+Reconcile in two directions only: add a curated entry for any accepted alias the file lacks (seed its
+facts from pi-ai's `anthropic` block), and remove any entry the harness no longer accepts. This is how
+a new alias (e.g. a `fable` alias, if a Claude Code build starts accepting it) enters the catalog.
+Requires an authenticated Claude session, so it is a manual/periodic step, not a CI gate.
+
+Note: today the accepted set is `default/sonnet/opus/haiku` plus their `[1m]` variants
+(`CLAUDE_MODEL_ALIASES` in `capabilities.py`). There is no `fable` alias yet; Fable reaches the
+picker through the Pi `anthropic` block. Do not add a `fable` Claude entry until the live probe
+confirms the harness accepts it.
+
+### 3. Refresh curated metadata from current public sources (before a release / on demand)
+
+Labels, descriptions, and ratings state a model's *current* standing, which a language model's
+training data gets wrong (the Anthropic frontier is Fable 5, above Opus, as of mid-2026). Look up the
+current lineup, pricing, and relative standing from the vendor's pages and announcements (WebSearch +
+WebFetch), then propose updated descriptions and ratings for a human to confirm. Never write a rating
+from memory. Validate the 1-5 range and flag any entry whose facts you could not verify. Ratings:
+higher is better on every axis; `cost` is cost-efficiency (5 = cheapest).
+
+## Validate
+
+The pydantic loader enforces the schema (including the 1-5 rating range) on load, and the unit test
+locks coverage and the overlay merge:
+
+```bash
+cd sdks/python && uv run --no-sync python -m pytest \
+  oss/tests/pytest/unit/agents/connections/test_model_catalog.py -q
+```
+
+A malformed data file fails loud there (and at import in `capabilities.py`, which then publishes an
+empty catalog rather than crashing `/inspect`).
+
+## When to run
+
+- Job 1 on a pi-ai bump (automatable from a lockfile diff).
+- Jobs 2 and 3 before a release or on demand (need a live session and a web lookup).
+
+The skill writes files and a proposal; a human reviews the curated changes and commits.

.agents/skills/sync-model-catalog/generate_pi_models.mjs

@@ -0,0 +1,119 @@
+// Generate the Pi model-catalog data file from the pinned `@earendil-works/pi-ai`
+// `models.generated` catalog. This is job 1 of the `sync-model-catalog` skill.
+//
+// It reads the pi-ai model definitions for the providers Agenta reaches (the vault-mapped
+// providers plus the `openai-codex` subscription) and emits one `ModelCatalogEntry` per model
+// with `source: "pi_generated"` and the objective facts filled from pi-ai (name / pricing /
+// context_window / modalities). The curated fields (label / description / ratings) are left
+// absent — a human adds those in the sibling `pi_models.curated.json` overlay, which the SDK
+// loader merges on top of this file. Regeneration only ever rewrites this generated file, so the
+// overlay survives a bump.
+//
+// Run from the runner package (so `@earendil-works/pi-ai` resolves):
+//   node .agents/skills/sync-model-catalog/generate_pi_models.mjs \
+//     services/runner/node_modules/@earendil-works/pi-ai/dist/models.generated.js \
+//     sdks/python/agenta/sdk/agents/data/pi_models.generated.json
+//
+// The output JSON carries no inline comments (JSON forbids them); the "generated, do not
+// hand-edit" notice lives in the `_generator` envelope field and in the skill README.
+
+import {readFileSync, writeFileSync} from "node:fs";
+import {pathToFileURL} from "node:url";
+
+// pi-ai provider name -> Agenta vault provider vocabulary. Agenta's capability table, vault, and
+// FE reachability filter speak `gemini`/`together_ai`; pi-ai's catalog keys them `google`/
+// `together`. The catalog entry's `provider` (and the `provider/` prefix on its `id`) uses the
+// Agenta vocabulary so it lines up with the rest of the system. The exact `provider/id` string the
+// live Pi harness accepts is verified by the skill's live-probe job, not asserted here.
+const PROVIDER_MAP = {
+  openai: "openai",
+  anthropic: "anthropic",
+  google: "gemini",
+  mistral: "mistral",
+  groq: "groq",
+  minimax: "minimax",
+  together: "together_ai",
+  openrouter: "openrouter",
+  "openai-codex": "openai-codex",
+};
+
+// The pi-ai provider blocks Agenta reaches: the vault-mapped providers plus the codex subscription.
+const PI_PROVIDERS = Object.keys(PROVIDER_MAP);
+
+function piVersion(modelsPath) {
+  // dist/models.generated.js -> ../package.json (the pi-ai package root).
+  try {
+    const pkgUrl = new URL("../package.json", pathToFileURL(modelsPath));
+    const pkg = JSON.parse(readFileSync(pkgUrl, "utf8"));
+    return `@earendil-works/pi-ai@${pkg.version}`;
+  } catch {
+    return "@earendil-works/pi-ai@unknown";
+  }
+}
+
+function pricing(cost) {
+  if (!cost) return null;
+  const out = {
+    input_per_mtok: cost.input ?? null,
+    output_per_mtok: cost.output ?? null,
+    currency: "USD",
+  };
+  if (cost.cacheRead != null) out.cache_read_per_mtok = cost.cacheRead;
+  if (cost.cacheWrite != null) out.cache_write_per_mtok = cost.cacheWrite;
+  return out;
+}
+
+function entryFor(agentaProvider, model) {
+  return {
+    id: `${agentaProvider}/${model.id}`,
+    provider: agentaProvider,
+    source: "pi_generated",
+    name: model.name ?? null,
+    pricing: pricing(model.cost),
+    context_window: model.contextWindow ?? null,
+    modalities: Array.isArray(model.input) ? model.input : null,
+    label: null,
+    description: null,
+    ratings: null,
+  };
+}
+
+async function main() {
+  const modelsPath = process.argv[2];
+  const outPath = process.argv[3];
+  if (!modelsPath || !outPath) {
+    console.error("usage: generate_pi_models.mjs <models.generated.js> <out.json>");
+    process.exit(2);
+  }
+
+  const {MODELS} = await import(pathToFileURL(modelsPath).href);
+
+  const models = [];
+  for (const piProvider of PI_PROVIDERS) {
+    const block = MODELS[piProvider];
+    if (!block) continue;
+    const agentaProvider = PROVIDER_MAP[piProvider];
+    for (const model of Object.values(block)) {
+      models.push(entryFor(agentaProvider, model));
+    }
+  }
+
+  const doc = {
+    schema_version: "1",
+    _generator: {
+      source: piVersion(modelsPath),
+      generated_by: ".agents/skills/sync-model-catalog/generate_pi_models.mjs",
+      generated_at: new Date().toISOString(),
+      note: "Generated file. Do not hand-edit. Curated fields live in pi_models.curated.json.",
+    },
+    models,
+  };
+
+  writeFileSync(outPath, JSON.stringify(doc, null, 2) + "\n");
+  console.error(`wrote ${models.length} models to ${outPath} from ${doc._generator.source}`);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

.agents/skills/write-template-playbooks/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: write-template-playbooks
+description: >-
+  Write a template playbook for the build-an-agent skill: a 1-2 KB per-use-case file that
+  teaches the builder agent to configure one kind of Agenta agent (changelog writer, issue
+  triager, support router, and so on). Use when the ask is "write a template playbook", "add
+  an agent template", "author a playbook for the build-an-agent skill", or "write the <X>
+  playbook". Encodes the file format, the prompting checklist, and the platform facts authors
+  get wrong.
+allowed-tools: Read, Edit, Write, Grep, Glob, Bash
+user-invocable: true
+---
+
+# Write a template playbook
+
+A playbook is one markdown file under `references/agent-templates/<key>.md` in the
+build-an-agent skill. The builder agent reads the one that matches the user's ask, then follows
+it to configure that specific agent. Your job: encode the use-case thinking so a Sonnet-class
+model can execute it. You get one inventory row as input (name, one-line pitch, integrations,
+trigger). Turn it into a spec-conforming playbook.
+
+Keep each playbook **1 to 2 KB**. An over-comprehensive playbook hurts: the agent cannot
+extract what is relevant. Write a coherent, moderately detailed unit with a working
+instructions template.
+
+## The skeleton
+
+Fill this in. Omit any section the use case does not need (a no-tool template drops Explore and
+Connections; a no-trigger template drops the trigger half of Verify).
+
+```markdown
+# <Template name> playbook
+
+## Match
+One line: when this playbook applies. The card key plus the shape of the ask, including
+free-text asks that match no card.
+
+## Required context (ask via one request_input form)
+- <field>: why the agent cannot proceed without it. When the agent can propose a value, set
+  it as the field's `default` (prefilled, one-click acceptable); no default otherwise. [required]
+Only fields the agent genuinely cannot proceed without. One to four. Secrets never go here.
+
+## Researchable context (ask, defaulting to "figure it out")
+- <field>: the agent can discover this. Enum with a "Use your best judgment" or "Figure it
+  out from what's connected" option set as the `default`; the built-in Other… covers custom
+  values. Note the speed trade-off in the description.
+
+## Explore first (read before proposing)
+- Which read tools to discover_tools and wire.
+- One test_run passing the uncommitted tools in delta.set.parameters.agent.tools (the FULL
+  tools list), to see the real repo or workspace. Show the user a concrete example before
+  committing the full setup.
+
+## Defaults / priors table (situation to proposed setup)
+| Situation | Trigger | Tools | Behavior default |
+|---|---|---|---|
+| <situation> | <trigger> | <reads> + <write> | <what it does> |
+
+## Connections
+Which integrations must be ready. If missing, request_connection and stop. List the
+tool-agnostic alternatives (Notion OR Confluence OR Google Drive).
+
+## Instructions template (what to commit)
+The numbered per-run procedure for instructions.agents_md: exact tools in order, pinned ids,
+ending on the terminal action. Include the output-format shape.
+
+## Verify
+1. test_run with a blunt test message; read the verdict and the tools line, not a 200.
+2. If a trigger: fire an artificial test message first; then ask the user to run the real
+   trigger test (Lightning "Test event" for a subscription, Play "Run" for a schedule).
+
+## Closing report
+What the agent became, what is connected, what is scheduled, what you verified, what still
+needs the user.
+```
+
+Every section maps to the build loop: Match to step one, Required and Researchable to
+`request_input`, Explore to `discover_tools` plus `test_run`, Defaults to the proposal,
+Connections to `request_connection`, Instructions to `commit_revision`, Verify to `test_run`
+and the trigger test, Report to the final step.
+
+## Three platform facts authors get wrong
+
+These are counterintuitive and every first draft gets them backwards. State them correctly.
+
+1. **`request_input` HAS a real `default` field (#5190, shipped) — use it.** A field's
+   `default` prefills the form so the user can accept every proposal in one click; set one
+   whenever the agent can propose a value. Rules: the default must match the field type
+   (array of strings on a multi-select); an empty default (`""`/`[]`) means "no proposal" and
+   is stripped; **date/date-time fields ignore defaults** — do not set them there. For a
+   researchable choice, include a "Figure it out, use your best judgment" enum option and set
+   it as the `default`. Enum options are SUGGESTIONS: every enum renders a built-in "Other…"
+   free-text escape hatch, so keep lists short and likely, not exhaustive. Multi-pick
+   questions use `{type: "array", items: {type: "string", enum: [...]}}`; options needing a
+   sentence of explanation use `oneOf: [{const, title, description}]`, which renders as
+   selectable choice cards. Forms with several questions can set `"x-ag-stepper": true` on
+   requestedSchema (one question at a time + review) — the tool description teaches this;
+   playbooks do not re-state it.
+2. **`test_run` exercises uncommitted tools** through its in-memory delta
+   (`delta.set.parameters.agent.tools` carries the FULL tools list, lists replace wholesale).
+   So exploration does NOT require commit-and-stop-turn. Explore the real repo or workspace
+   with new tools before committing anything. Commit-and-stop is only a fallback for when the
+   flow cannot carry the delta.
+3. **The trigger-test affordance is Lightning "Test event"** (event subscriptions) or Play
+   "Run" (schedules). It is never a flask icon. The flask is for Evaluations. Write the correct
+   copy in every Verify section.
+
+## What a playbook NEVER contains
+
+Add what the model lacks for this use case; omit what it already knows. Do not put in a
+playbook:
+
+- The generic build loop (discover, commit, test). It lives in the build-an-agent skill body.
+- The config schema (tool entries, the fixed `llm`/`harness`/`runner` block). It lives in
+  the skill body and `references/config-schema.md`.
+- Tool wire shapes or cron rules. Those live in the skill body and its other references.
+
+A playbook that re-teaches these wastes the 1-2 KB budget and drifts from the source of truth.
+
+## Read a reference when
+
+| To do this | Read |
+|---|---|
+| Get the prompting rules for procedure, priors, forms, and verification | `references/prompting-checklist.md` |
+| Copy from a complete, spec-conforming example | `references/worked-example.md` |
+
+The canonical file format and the index.md match-table format are in the project spec at
+`docs/design/agent-workflows/projects/agent-templates/playbook-spec.md`. Read it if the
+skeleton above is not enough.