Keeping the Toolchain Current

The Ekanos toolchain is five packages: @ekanos/cli, @ekanos/sdk, @ekanos/ui, @ekanos/integration-schema, and @ekanos/harness. Three independent defenses keep it in sync:

1. Schema-version skew gate

validate and publish bundle an exact @ekanos/integration-schema version. If the project resolves a newer one (checked against both a direct install and what @ekanos/sdk declares), both verbs fail fast with precondition_failed (exit 9) — before loading the definition at all.

Why this matters

$ ekanos validate
Error: The project's @ekanos/integration-schema@0.4.1 is newer than 0.4.0, the version this @ekanos/cli build validates with. Findings from "ekanos validate" are UNRELIABLE in this state: a field the newer schema added parses here as an unrecognized key, and the usual hint for that tells you to delete code that is actually correct.
Hint: Upgrade the CLI: run "ekanos upgrade" (it resolves a coherent target version set), or pin it explicitly by hand with "npm i -D @ekanos/cli@latest". Then re-run "ekanos validate" or "ekanos publish".

In that state, a field the newer schema added would parse as an unrecognized_keys issue, and the usual hint would tell you to delete correct code. So the CLI fails loudly instead.

Older project schema (warning only)

If the project’s schema is older, the verb continues and warns on stderr:

ekanos: the installed @ekanos/integration-schema@0.3.0 is older than 0.4.0, the version this CLI validates with — some fields this CLI recognizes may not be usable yet. Run "ekanos upgrade" to bring the toolchain in sync.

Validation is still correct; you just can’t use fields the older schema doesn’t know about. The JSON envelope carries data.schemaSkew in this case.

2. `ekanos upgrade`

The primary way to keep the toolchain coherent.

# Check current vs. target (read-only)
ekanos upgrade --check

# Upgrade with verification
ekanos upgrade

# Skip the post-install validate + test
ekanos upgrade --no-verify

Coherence guarantee

upgrade resolves a coherent target version set — from GET /api/partner/toolchain on your logged-in host when available, else the npm registry. @ekanos/sdk, @ekanos/ui, and @ekanos/integration-schema must share one version, and the SDK release at that version must pin exactly that schema. An incoherent set (for example, mid-way through a multi-package publish) is refused with precondition_failed (exit 9) rather than turned into an uninstallable tree:

Error: The resolved toolchain versions do not form an installable set: …
Hint: Retry in a moment — this is almost always a multi-package publish still in flight, and it self-resolves once every package finishes publishing.

Install and verify

Snapshot — package.json and the lockfile are saved
Install — Target versions of the toolchain packages that are direct dependencies are installed; transitive ones follow from whatever pins them and are listed in data.skippedTransitive
Verify — ekanos validate and your test script run
Rollback — On any failure, package.json and the lockfile are restored and a reinstall restores node_modules

In a terminal, upgrade prints the plan and asks Upgrade now? [y/N]. Outside a real TTY it requires --yes; without it, it fails with validation (exit 3) and changes nothing. If the project is already at the target, it reports so and exits 0. A failed step is reported with an error.code naming it and the step’s output in data.output:

`error.code`	Exit code
`upgrade_install_failed`	`9`
`upgrade_validate_failed`	`3`
`upgrade_test_failed`	Your test script’s

The hint confirms the project has been restored to its pre-upgrade state.

Agent-context file regeneration

After a successful upgrade, ekanos upgrade regenerates:

AGENTS.md
CLAUDE.md
.claude/skills/ekanos/SKILL.md

Each is byte-compared against what the pre-upgrade CLI’s templates would have rendered. Files you haven’t modified are refreshed; ones you’ve edited are left alone and reported as needing manual attention. docs/api-notes.md and .mcp.json are created if missing, never overwritten. A stale AGENTS.md teaches an agent yesterday’s contract, which is as harmful as a stale binary.

Flags

boolean

Read-only. Report current vs. target versions and exit 0. Changes nothing. Safe for CI and scripts.

boolean

Skip the interactive confirm. Required outside a real TTY (scripts, cron, containers).

boolean

Skip the post-install verification step. Not recommended.

string

Ekanos host to fetch the target version set from. Falls back to host resolution (see Authentication). With no stored session for the host, the npm registry is used.

string

Project directory (contains ekanos.json). Defaults to the current working directory.

3. Proactive update notice

validate, dev, publish, and status check in the background whether a newer @ekanos/cli exists.

How it works

Cached — 24-hour cache
Bounded — 1.5 second ceiling on network time
Non-fatal — never changes the command’s exit code
Silent when current — no notice if you’re up to date

Human mode prints one line to stderr:

ekanos: a newer @ekanos/cli is available (0.3.2 → 0.3.3). Run "ekanos upgrade".

JSON mode carries the notice in data.toolchain:

{
  "ok": true,
  "data": {
    "toolchain": {
      "status": "behind",
      "current": { "cli": "0.3.2" },
      "target": {
        "cli": "0.3.3",
        "sdk": "…",
        "ui": "…",
        "integrationSchema": "…",
        "harness": "…"
      },
      "upgradeCommand": "ekanos upgrade"
    }
  }
}

The same object appears on a stderr claude-code-hint line so agents can parse it without reading prose.

Unsupported version

If you’re below the host’s declared minimum CLI version, the notice’s status is unsupported and human mode prints:

ekanos: @ekanos/cli 0.2.0 is below the version this host requires (0.3.2). Run "ekanos upgrade".

publish then fails fast with precondition_failed (exit 9), because the host would refuse the submission anyway:

Error: @ekanos/cli 0.2.0 is below https://your-ekanos-host's minimum supported version (needs at least 0.3.2).
Hint: Run "ekanos upgrade" before publishing — the host will refuse this submission from an unsupported CLI regardless.

Disable update checks

export EKANOS_NO_UPDATE_CHECK=1
ekanos validate  # No update check

Workflow examples

Before you publish

ekanos upgrade --check    # See if anything needs updating
ekanos upgrade            # Install, verify, roll back on failure
ekanos publish

Team with a shared lockfile

Commit package.json and the lockfile so everyone runs the same toolchain. One person upgrades for the team:

ekanos upgrade
git add package.json pnpm-lock.yaml
git commit -m "chore: bump ekanos toolchain"

# Everyone else
git pull
pnpm install
ekanos validate

CI/CD pipeline

- name: Validate and test
  run: |
    pnpm install
    npx ekanos validate
    npx ekanos test

- name: Publish (on main)
  if: github.ref == 'refs/heads/main'
  run: |
    npx ekanos publish --source my-source
    npx ekanos status --watch

CI installs the locked versions; the team decides when to upgrade.

Agent-driven updates

ekanos upgrade --check --json   # Read data.deltas to see what would change
ekanos upgrade --yes            # Installs, verifies, rolls back on any failure

A non-zero exit from ekanos upgrade --yes means the project was restored; read error.code and data.output for the failing step.

Troubleshooting

CLI too old for the installed harness

Error: @ekanos/cli 0.1.0 is too old for @ekanos/harness 0.2.0: that harness needs shell contract 2, and this CLI generates 1.

dev refuses (exit 9) before writing anything. The hint gives the install command to upgrade the CLI. The reverse case, @ekanos/harness <version> is too old for @ekanos/cli <version>, gives the command to upgrade the harness. Fix: Run ekanos upgrade, or follow the hint.

Project schema newer than the CLI

See the schema-version skew gate section at the top of this page. Fix: Run ekanos upgrade --check to see the target, then ekanos upgrade.

Upgrade rolled back

The install, validate, or test step failed and the project was restored. error.code names the step and data.output holds its output. Fix: Fix the underlying issue (often a test failure against the new versions) and re-run ekanos upgrade.

No target available

Error: Could not resolve a toolchain target from the Ekanos host or the npm registry.

Exit 8. Neither the host nor the npm registry answered. Fix: Check connectivity and retry.

Edited agent-context files

upgrade leaves an AGENTS.md, CLAUDE.md, or skill file you’ve edited untouched and reports it as needing manual attention. Fix: Compare it against the new template and merge by hand.

​1. Schema-version skew gate

​Why this matters

​Older project schema (warning only)

​2. ekanos upgrade

​Coherence guarantee

​Install and verify

​Agent-context file regeneration

​Flags

​3. Proactive update notice

​How it works

​Unsupported version

​Disable update checks

​Workflow examples

​Before you publish

​Team with a shared lockfile

​CI/CD pipeline

​Agent-driven updates

​Troubleshooting

​CLI too old for the installed harness

​Project schema newer than the CLI

​Upgrade rolled back

​No target available

​Edited agent-context files

1. Schema-version skew gate

Why this matters

Older project schema (warning only)

2. `ekanos upgrade`

Coherence guarantee

Install and verify

Agent-context file regeneration

Flags

3. Proactive update notice

How it works

Unsupported version

Disable update checks

Workflow examples

Before you publish

Team with a shared lockfile

CI/CD pipeline

Agent-driven updates

Troubleshooting

CLI too old for the installed harness

Project schema newer than the CLI

Upgrade rolled back

No target available

Edited agent-context files