@ekanos/cli 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "private": false,
   "description": "The Ekanos partner toolchain CLI: scaffold, validate, and test an Ekanos integration against the published @ekanos packages. Agent-native — every verb speaks JSON with a stable exit-code taxonomy.",
   "keywords": [
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@clack/prompts": "1.7.0",
-    "@ekanos/integration-schema": "0.9.0",
+    "@ekanos/integration-schema": "0.10.0",
     "esbuild": "0.28.1",
     "picocolors": "1.1.1"
   },

package/templates/agents-claude.md.tmpl

@@ -0,0 +1,14 @@
+# Ekanos agents
+
+This folder is where we design and change our Ekanos managed agents with the
+`ekanos` CLI (`npx @ekanos/cli agents …`). The agents themselves live in Ekanos;
+`agents/<key>/` holds a copy for review (`agent.json` + `AGENT.md`).
+
+- To create or change an agent, use the `build-agent` skill: it checks what
+  the Source already has (`npx @ekanos/cli catalog`), interviews the user, then
+  drafts, applies and — only on the user's yes — publishes.
+- For how Sources, team accounts, seats, integrations and connections fit
+  together, use the `ekanos-platform` skill.
+- Ekanos docs are in the `ekanos-sdk-docs` MCP server (https://sdk.ekanos.dev).
+  Look things up there rather than guessing.
+- Never ask for or write a secret; teams enter those in the Ekanos app.

package/templates/claude-skill.md.tmpl

@@ -34,14 +34,10 @@ already does what the user wants, propose setting it up (walk its
 
 ## Managed agents live in Ekanos
 
-An agent is not code in this repo: `npx ekanos agents list --json` shows the
-source's agents, `pull <key>` writes one as `agent.json` + `AGENT.md`,
-`apply <dir>` stores a change as a new draft version, and only a source admin
-`publish`es it to every team. Name tools and products exactly as the catalog
-lists them. Decide with the user, per product and MCP server, whether each
-team connects its own (`required` or `optional`), and what teams may add
-(`teamCustomization`, all off unless turned on). Show the user the applied draft and wait for their yes before
-`publish --yes`; never `--overwrite` a version conflict you have not read.
+An agent is not code in this repo. To create or change one — or decide who
+gets it — use the `build-agent` skill; for how Sources, team accounts, seats
+and connections fit together, the `ekanos-platform` skill. A folder that only
+manages agents (no integration) is set up with `npx ekanos agents init`.
 
 ## The loop
 

package/templates/package.json.tmpl

@@ -12,12 +12,12 @@
     "prepare": "node scripts/setup-hooks.mjs"
   },
   "dependencies": {
-    "@ekanos/sdk": "^0.9.0",
-    "@ekanos/ui": "^0.9.0"
+    "@ekanos/sdk": "^0.10.0",
+    "@ekanos/ui": "^0.10.0"
   },
   "devDependencies": {
-    "@ekanos/cli": "^0.5.1",
-    "@ekanos/harness": "^0.7.0",
+    "@ekanos/cli": "^0.7.0",
+    "@ekanos/harness": "^0.7.1",
     "@hookform/resolvers": "^5.2.2",
     "@tailwindcss/postcss": "^4.3.3",
     "@tanstack/react-query": "^5.101.4",

package/templates/skills/build-agent/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: build-agent
+description: Interview-driven workflow for creating, changing and rolling out an Ekanos managed agent with `ekanos agents` — e.g. "create a customer support agent that uses Linear and Zendesk", "an agent that triages tickets", "update our support agent's instructions", "roll this agent out to every team", "roll back the agent". Use for any request to build or change an agent, its tools, approvals, connections or rollout. Not for building an integration (that is build-integration).
+---
+
+# Build an Ekanos managed agent
+
+The user describes what they want in a sentence ("a customer support agent
+that uses Linear, Zendesk and our Mintlify docs as the source of truth"). Turn
+that into an agent Ekanos runs, by interviewing them — one topic at a time,
+in plain words, with a recommendation each time — then drafting, applying and
+(on their yes) publishing it. Read the `ekanos-platform` skill first if you
+have not: Sources vs teams, seats and connections underlie every question
+here.
+
+Run the CLI as `npx @ekanos/cli … --json` and read the envelope
+(`{ ok, data }` / `{ ok: false, error: { code, message, hint } }`); follow
+every `hint`. Look things up in the `ekanos-sdk-docs` MCP server
+(https://sdk.ekanos.dev) rather than guessing.
+
+## Hard rules
+
+- Never ask for, accept or write a secret (API key, client secret, webhook
+  signing secret). Teams enter those in the Ekanos app.
+- Never `publish` or `rollback` without the user's explicit yes to that
+  version, after they have seen it. `--yes` records that consent; it is never
+  a way past a question.
+- Never `--overwrite` a version conflict (exit 7) you have not shown the user:
+  someone else changed the agent; pull it and reconcile.
+- Use product and tool names exactly as the catalog lists them.
+
+## 1. Ground yourself (before asking anything)
+
+1. `npx @ekanos/cli sources --json` — which Sources, which seats. More than one?
+   Ask which Source this is for and pass `--source <slug>` on every command
+   after. A `developer` seat can apply drafts but not publish; say so early.
+2. `npx @ekanos/cli catalog --source <slug> --json` — every product the Source
+   has, its tools, its **agent events** (what can start an agent) and its
+   `setupSteps`.
+3. `npx @ekanos/cli agents list --source <slug> --json` — an agent that already
+   does this should be changed, not duplicated.
+4. Map the request onto the catalog. For each thing the user named, say
+   which of these it is:
+   - **Ready** — the product is `enabled` and has the tools/events needed.
+   - **Not set up yet** — offered but not enabled, or a setup step left
+     (`setupSteps` says who: `ekanos` = an Ekanos super admin, `source_admin`
+     = the user if they hold that seat, `team` = each team). The common one a
+     Source admin can clear: an integration's **app for the Source** is not
+     set up, so no team can connect. Run
+     `npx @ekanos/cli apps show <product> --source <slug> --json` for the
+     callback URL to register in the provider, then ask the user to run
+     `npx @ekanos/cli apps set <product> --source <slug>` **in their own
+     terminal** — it asks for the secret there; never ask for it in chat.
+     The agent can be drafted while that is pending.
+   - **Missing** — no product does it. Say so plainly. Options: build the
+     integration (the `build-integration` skill), use a remote MCP server
+     instead if the service offers one (common for docs and knowledge bases:
+     a Mintlify docs site serves one at `https://<docs-host>/mcp`), or ship
+     the agent without it and add it in a later version.
+
+Tell the user this map in a few lines before the interview. Don't hide a gap
+behind a plan that assumes it away.
+
+## 2. The interview
+
+One topic per message. Summarize what you heard before moving on. Defaults
+in parentheses are the recommendation when the user has no preference.
+
+1. **The job.** What should it do, for whom, and what does a good outcome
+   look like? What must it never do? Ask for one or two real examples (a
+   ticket, an issue) — they make the instructions concrete.
+2. **Who gets it** — see `references/rollout.md`. Every team, or one team's
+   own? (Every team, when more than one team does this work the same way.)
+   Explain what a team sees and does, how updates reach teams, pinning and
+   rollback.
+3. **What it can touch.** Which products and tools; reads vs changes.
+   (Reads only to start; add writes once it has earned trust.)
+4. **What waits for a person.** Reads run on their own, changes wait for
+   approval — and any per-tool exceptions (a public reply to a customer
+   almost always waits). See `references/agent-json.md` → `policy`.
+5. **Whose connections.** For each product and MCP server: each team
+   connects its own — `required` (the agent waits at "needs setup" until the
+   team connects it) or `optional` (its tools appear once connected). One
+   connection shared by every team is not available yet.
+6. **What teams may add** — their own MCP servers, their own skills, more of
+   their own integrations, or narrowing (removing tools, more approvals). All
+   off unless there is a reason. Give one concrete example per knob.
+7. **What starts it** — see `references/triggers.md`. Triggers belong to each
+   team and are set after turning the agent on; say what each team will have
+   to set up (an @mention, a label, a new ticket, a schedule) and what it
+   needs connected first.
+
+## 3. Draft, apply, publish
+
+1. Write `agents/<key>/agent.json` (the body; field guide in
+   `references/agent-json.md`) and `agents/<key>/AGENT.md` (the
+   instructions). `<key>` is lowercase-hyphenated, e.g. `support-triage`.
+   The instructions say: the job, the sources of truth and when to consult
+   each, what to do when unsure (ask, or hand to a person), tone, and what
+   never to do. Show the user both files and walk through them.
+2. On their go: `npx @ekanos/cli agents apply agents/<key> --source <slug> --json`.
+   A refusal (exit 3) lists each problem with its path in the body — explain
+   and fix them together. The stored version is a **draft**: no team sees it.
+3. `npx @ekanos/cli agents show <key> --source <slug>` — review the stored draft
+   with the user.
+4. Ask: publish this version to every team now? Only on yes:
+   `npx @ekanos/cli agents publish <key> --source <slug> --to <n> --yes`.
+5. Hand over the team-side checklist (`references/triggers.md` has the
+   per-integration parts): find it under Agents → "Provided for your team",
+   Turn on, connect what it needs, confirm access, add triggers. Suggest one
+   team pilots it first, and plan a first test run with them.
+
+## Changing it later
+
+`npx @ekanos/cli agents pull <key> --source <slug>` writes the latest version to
+`agents/<key>/`; edit, `apply` (a new draft), `show`, then `publish` on the
+user's yes. `rollback <key> --to <n> --yes` republishes an earlier version.
+Teams that pinned a version stay on it and are told a newer one exists.

package/templates/skills/build-agent/references/agent-json.md

@@ -0,0 +1,85 @@
+# `agent.json` — the agent's body
+
+`agents/<key>/agent.json` plus `agents/<key>/AGENT.md` (the instructions, used
+when `agent.json` has no `instructions`). `ekanos agents pull` writes this
+layout and records `baseVersion`; `apply` reads it back and refuses a
+conflicting change unless `--overwrite`. Unknown fields are refused.
+
+```json
+{
+  "name": "Support triage",
+  "description": "Triages new support tickets and drafts replies.",
+  "model": null,
+  "maxTurns": 50,
+  "tools": { "mode": "custom", "products": ["zendesk"], "tools": ["linear_list_team_issues"] },
+  "policy": {
+    "reads": "auto",
+    "writes": "approve",
+    "overrides": { "zendesk_add_internal_note": "auto" }
+  },
+  "skills": [],
+  "connections": {
+    "zendesk": { "owner": "team", "team": "required" },
+    "linear": { "owner": "team", "team": "optional" }
+  },
+  "mcpServers": [
+    {
+      "key": "docs",
+      "name": "Product docs",
+      "url": "https://docs.example.com/mcp",
+      "auth": "none",
+      "owner": "team",
+      "team": "required",
+      "toolEffects": { "search": "read" }
+    }
+  ],
+  "teamCustomization": { "mcpServers": false, "skills": false, "integrations": false, "narrow": false }
+}
+```
+
+The tool names above are illustrations. Take real ones from
+`ekanos catalog --json`.
+
+## Fields
+
+- **`name`** (≤80), **`description`** (≤500, or null).
+- **`instructions`** — or `AGENT.md`. Up to 20,000 characters.
+- **`model`** — a model id, or `null` for the house default (recommended
+  unless the user has a reason).
+- **`maxTurns`** — 1–100, default 50: the most tool-use steps in one run.
+- **`tools`** — what it may call at all:
+  - `read_only`: every read tool the team has connected.
+  - `all`: every tool, reads and changes.
+  - `custom`: whole `products` (slugs) plus single `tools` (names).
+  A tool it must never call is simply not granted — there is no deny list.
+  Extra team integrations (`teamCustomization.integrations`) need `custom`.
+- **`policy`** — for each granted tool, `auto` (runs on its own) or
+  `approve` (waits for a person in the app). `reads`/`writes` set the
+  defaults by the tool's effect; `overrides` set single tools by name. An
+  undeclared tool effect counts as a write. MCP tools are named
+  `mcp__<server key>__<tool>` in `overrides`.
+- **`skills`** — skill slugs the Source or the platform already has.
+- **`connections`** — by product slug: `{ "owner": "team", "team": "required" | "optional" }`.
+  A product with no entry is `team`/`optional`. `owner: "source"` (one
+  connection for every team) is refused today.
+- **`mcpServers`** — remote MCP servers (streamable HTTP, `https` only, up to
+  10): `key` (lowercase, ≤31), `name`, `url`, `auth` (`none` | `bearer` |
+  `oauth`, default `oauth`), `owner`/`team` as for connections, and
+  `toolEffects` (which tools only read; the rest count as writes). Turning
+  the agent on adds a team-owned server to the team; `auth: "none"` needs no
+  sign-in, others ask the team to sign in.
+- **`teamCustomization`** — what teams may add, all `false` by default:
+  - `mcpServers` — attach their own MCP servers (their tools ask first until
+    the team marks one as read-only),
+  - `skills` — attach their own skills,
+  - `integrations` — grant more of their own connected products/tools
+    (needs `tools.mode: "custom"`),
+  - `narrow` — remove tools or make more of them wait for approval. Never
+    loosens.
+
+## What the host checks on `apply`
+
+Every product and tool must be in the Source's catalog, every skill must
+exist for the Source, the model must be known, connection keys must be
+catalog products. Each refusal comes back with a `path` into the body
+(`tools.tools.0`, `skills.2`) — fix that field.

package/templates/skills/build-agent/references/rollout.md

@@ -0,0 +1,53 @@
+# Who gets the agent: rollout options
+
+Two shapes. Recommend one, and say why in terms of the user's teams.
+
+## Provided for every team (an agent template)
+
+Built with `ekanos agents` by a Source admin.
+
+- **Defined once.** Instructions, model, tools, approvals, skills, which
+  connections it uses, and what teams may add.
+- **Drafts are private.** `apply` stores a numbered version; no team sees it
+  until it is published.
+- **Publishing reaches every team in the Source.** Each sees it under Agents →
+  "Provided for your team". There is no list of chosen teams: every team can
+  see it, and each decides whether to turn it on.
+- **Turning it on** makes the team's own copy. The person who turns it on
+  becomes its owner; the agent uses that person's and that team's
+  connections, so a team that has not connected a `required` product sees
+  "needs setup" instead of a working agent.
+- **Updates.** Each publish updates every team that follows the latest
+  version. A team can **pin** a version instead; it stays there and is told
+  when a newer one is published.
+- **Rollback.** `ekanos agents rollback <key> --to <n> --yes` publishes an
+  earlier version to every team that follows it.
+- **What stays the team's:** whether it is on, its triggers, its own
+  connections, its run history, and whatever `teamCustomization` lets it add.
+- **When a new version needs more access** than a team confirmed (a new
+  product, a tool that now runs without approval), the team's owner is asked
+  to confirm again; until then the agent keeps only what needs no new
+  confirmation.
+
+Good for: the same job done by several teams; a central owner who improves
+it over time; consistent behaviour and approvals.
+
+Piloting: publish, then have one team turn it on first. Teams that never
+turn it on are unaffected. Or keep it as an applied draft until the pilot
+plan is ready.
+
+## A team's own agent
+
+Built by a team in the app (Agents → New). Only that team has it; the Source
+cannot update or roll it back, and nothing about it is visible to other teams.
+
+Good for: one team's own process; experiments a team owns.
+
+## Questions that decide it
+
+- How many teams do this work? The same way?
+- Who should own improvements — one central person, or each team?
+- Must every team follow the same approval rules (e.g. customer-facing
+  replies always reviewed)?
+- Do teams need to add their own tools or knowledge, and should they be
+  allowed to? (`teamCustomization`, all off by default.)

package/templates/skills/build-agent/references/triggers.md

@@ -0,0 +1,47 @@
+# What starts the agent: triggers
+
+Triggers belong to each team. They are not part of the agent template: a team
+adds them on its copy (Agents → the agent → Triggers) after turning it on.
+Your job in the interview is to say which triggers each team will want, and
+what it must connect first, so the team-side checklist is complete.
+
+## Kinds a team can add
+
+- **An integration's event** — any event a connected integration declares
+  (the catalog lists them per product as `agentEvents`). The team picks the
+  event and fills in its filter (the fields the event declares — e.g. labels,
+  a team, a group, tags). When the integration also has a **channel**, the
+  agent answers where the event happened (on the issue, on the ticket), and
+  that reply tool runs on its own by default.
+- **Schedule** — a cron and time zone, with "what to do each time".
+- **Webhook** — a URL any system can call, with "what to do with each
+  request".
+- **Slack** — chosen channels and/or direct messages in a connected Slack.
+
+## Integrations with agent events
+
+Check `ekanos catalog <product> --source <slug> --json` for what is actually
+there; these are the known shapes.
+
+**Linear** (`linear.mentioned`, `linear.assigned`, `linear.issue_labeled`) —
+the agent becomes a teammate in Linear: @mention it, assign it an issue, or
+apply a label. Each team needs two things in the app: each person's own
+Linear connection (for the tools), and the team's own Linear app for the
+agent (client id, secret and webhook signing secret, entered in Ekanos).
+Guide: https://sdk.ekanos.dev/guides/linear-agent
+
+**Zendesk** (`zendesk.ticket_created`, `zendesk.comment_added`; filters such
+as brand, group, tags, organization) — when present in the catalog, each team
+connects its own Zendesk (subdomain plus an OAuth client it creates in
+Zendesk) and adds a Zendesk webhook pointing at its Ekanos endpoint. The agent
+answers on the ticket as a public reply or an internal note — recommend
+internal notes, or approval on public replies, until the team trusts it.
+
+## Checklist to hand each team
+
+1. Agents → "Provided for your team" → Turn on.
+2. Connect every `required` product and sign in to any MCP server that needs
+   it (the agent shows what is missing).
+3. Do each integration's own setup (team app, webhook) from its guide.
+4. Confirm access if asked.
+5. Add the triggers above, then run one real example and review it.

package/templates/skills/ekanos-platform/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: ekanos-platform
+description: How Ekanos is organized — Sources, team accounts, seats and roles, products (integrations and experiences), connections, and managed agents — and which of those the ekanos CLI can change. Use whenever a request involves who gets something (one team or every team), who can set it up, whether something is "connected" or "enabled", or explaining Ekanos to the user before building an integration or an agent.
+---
+
+# How Ekanos is organized
+
+Explain these in plain words when a decision depends on them. Docs:
+https://sdk.ekanos.dev/concepts/sources-and-teams (or search the
+`ekanos-sdk-docs` MCP server). Never guess a rule that is not here or in the
+docs — ask, or check the CLI.
+
+## Sources and team accounts
+
+- A **Source** is one Ekanos customer's whole deployment: its brand, domain,
+  users and catalog. Ekanos is white-label, so the people inside a Source see
+  only their own brand.
+- A Source holds many **team accounts**. A team is where the work happens:
+  its members, its data, its connections, its agents. Teams in the same Source
+  do not see each other's data.
+- Team members have one of three team roles — **owner**, **admin**,
+  **member** — which govern that team only. Being a team owner gives no
+  authority over the Source.
+- **"Source" is admin vocabulary.** Team members never see the word. When you
+  describe what a team will see, say "provided for your team", never "the
+  Source's agent". Use "Source" freely with the person you are helping only
+  if they are a Source admin or developer (they are, if the CLI works for
+  them).
+
+## Seats: who can use the CLI on a Source
+
+`npx @ekanos/cli sources --json` lists the user's seats.
+
+| Seat | Can |
+|---|---|
+| `developer` | Submit integrations; read the catalog; apply agent **drafts** |
+| `source_admin` | Everything a developer can, plus **publish** agents to every team, set up the Source's **provider apps** (`ekanos apps`), and manage the Source's roster |
+
+Only an Ekanos super admin grants seats. If the user lacks the seat a step
+needs, say which and stop — there is no way around it from the CLI.
+
+## Products: integrations and experiences
+
+Everything in the catalog (`npx @ekanos/cli catalog --source <slug> --json`) is a
+**product** of one of two kinds:
+
+- **Integration** — a connection to a third party (Linear, Zendesk, Slack…).
+  Brings tools an agent can call, and may declare **agent events** that start
+  agents (`linear.mentioned`, `zendesk.ticket_created`…).
+- **Experience** — an Ekanos-native capability (Agents, Workflows, Home…).
+  Never "connected"; it is simply on or off for the Source.
+
+## Is it usable? Four separate facts
+
+Ask them in this order; each catalog product reports where it stands
+(`availability` and `setupSteps`).
+
+1. **Given to the Source** — `availability` is `enabled` (on), `turned-off`
+   (given, but a Source setting or plan has it off) or `available` (Ekanos
+   offers it; this Source has not been given it). A product missing from the
+   catalog altogether is not offered to this Source. Giving a Source a product
+   is an Ekanos super admin's step (`setupSteps` names it with actor
+   `ekanos`) — not something a Source admin or the CLI can do.
+2. **Connected by a team** — a team (or a person, for per-person
+   integrations) signed in to the third party. Connections belong to a team,
+   never to the Source: two teams using Linear each connect their own.
+3. **Set up by the team** where needed — some integrations have each team
+   bring its own app (a team-provided app: client id, secret, webhook signing
+   secret entered in Ekanos). Those secrets are typed into the app, never
+   into a chat or a file.
+4. **Used by an agent** — granted in the agent's tools.
+
+Some integrations sign every team in through **one app for the whole Source**
+(Linear's OAuth app, say): until the Source has its credentials, no team can
+connect (`setupSteps` step `provider-app`). A Source admin sets it up —
+`ekanos apps show <product>` gives the callback URL to register with the
+provider, and `ekanos apps set <product>`, run by the admin at their own
+terminal, takes the client ID and secret. Integrations whose teams each bring
+their own app (Zendesk) have no Source app.
+
+A product that is "enabled" is not therefore "connected". Say which one you
+mean.
+
+## Managed agents
+
+An agent is **data held by Ekanos**, not code: instructions, a model, the
+tools it may use, which calls wait for a person's approval, and skills. It is
+changed through the CLI or the app, with no deploy.
+
+- **Provided for every team** — a Source admin defines it once with
+  `ekanos agents` (a template). Each team sees it under Agents → "Provided for
+  your team" and turns it on; it then runs on that team's own connections.
+  Publishing a new version updates every team that follows it.
+- **A team's own** — built by a team in the app (Agents → New). Only that team
+  has it, and the Source cannot update it.
+
+The `build-agent` skill walks through choosing between these and building one.
+
+## Where each thing is done
+
+| Done by | Where |
+|---|---|
+| Making a product available to a Source; granting seats | Ekanos super admin, in Ekanos's admin |
+| Building or updating an integration | A developer, with `ekanos validate` / `ekanos publish` |
+| Agents provided for every team | A Source admin, with `ekanos agents` |
+| An integration's app for the whole Source (client ID and secret) | A Source admin, with `ekanos apps set` at their own terminal |
+| Connecting an integration; turning on a provided agent; its triggers | Each team, in the app |