akm-cli 0.10.261013-beta → 0.10.261015-beta

package/STABILITY.md

@@ -33,6 +33,29 @@ spelling is in the CHANGELOG entry and the CLI reference.
 | `akm config path --all` | `akm info` |
 | `--run` / `--since` on `akm improve` | `akm improve report --run` / `--since` |
 
+**Connections and harnesses (0.10, #1244).** `engines` and `defaults` are
+replaced by `connections` and `harnesses`. A config in the old form still loads
+(converted in memory, with a warning that names `akm migrate apply`), and `akm
+migrate apply` converts it.
+
+`--engine <name>` (on `agent`, `command run`, `task add`, `proposal new` and
+`proposal extract`) and `--require-engines` (on `improve`) are hidden from
+`--help` and still run, with one warning, through 0.10. `--require-engines`
+does nothing. Change a script to `--connection <name>` or `--harness <name>`,
+and `--model <alias|name>`; how an old engine name resolves is under
+[The `engines` form](docs/reference/configuration.md#the-engines-form).
+
+`AKM_ENGINE_<NAME>_API_KEY`, `AKM_LLM_API_KEY` and `AKM_EMBED_API_KEY` are no
+longer read implicitly: put `"apiKey": "$VAR"` on the connection, or the key in
+`credentials.json`.
+
+These are unknown flags or commands (exit 2) from 0.10, with no alias:
+
+| Gone | Use |
+| --- | --- |
+| `akm setup --config <json>` and `--probe` | `akm setup --endpoint <url> --yes` and the other answer flags; `--no-probe` for an offline run (probing is the default) |
+| `akm models list`, `akm models copy-defaults` | `akm models`, `akm models set <alias> <model>` |
+
 **Version numbers (0.10 onward, #1089).** A 0.10 release is numbered
 `0.10.YYMMNN`: `YY` the UTC year, `MM` the month (`01` to `12`) and `NN` the
 release within that month (`01` to `99`), each two digits. Every release takes
@@ -84,7 +107,7 @@ enumeration of the whole `proposal` noun group.
 
 | Command | Tier | Notes |
 | --- | --- | --- |
-| `akm setup` | Stable | |
+| `akm setup` | Stable | The answer flags (`--endpoint`, `--api-key-env`, `--name`, `--harness`, `--embedding`, ...) are new in 0.10; `--config` and `--probe` are gone (see the table above). |
 | `akm index` | Stable | |
 | `akm health` | Evolving | Exit codes are Evolving; report *content* and rendered `md`/`html` layout are Experimental — do not script against report layout. |
 | `akm metrics` | Experimental | New in 0.9.28. Report content, JSON shape and the `html` dashboard may change. |
@@ -126,7 +149,7 @@ enumeration of the whole `proposal` noun group.
 | `akm log` | Evolving | |
 | `akm agent` | Evolving | |
 | `akm command run` | Evolving | Runs stored command templates through the same agent dispatch as `akm agent`. |
-| `akm models` | Evolving | `list` and `copy-defaults` for model intent aliases. |
+| `akm models` | Evolving | The alias picks of a connection, then the models its endpoint lists, and `set` to change one. |
 | `akm lint` | Evolving | |
 | `akm improve` | Evolving | Review-first by default; mutating lanes require `experimental.improveAutonomy` — see below. |
 | `akm improve report` | Evolving | Subcommand since 0.10 (was a magic `scope` value); owns `--run` and `--since`. |
@@ -314,7 +337,7 @@ CHANGELOG with a migration note.
   `list`/`remove`/`init`/`enable`/`disable`); task source v4 YAML (typed
   `inputs:`, optional `schedule:`) is the only accepted version — task v3 and
   task v2 sources are converted by `akm migrate apply`. Command tasks use
-  named engines and task history metadata is versioned. Schema additions in
+  a named connection or harness, and task history metadata is versioned. Schema additions in
   patch releases; removals only at minor. Bare `akm task` is a usage error
   naming the subcommands (`akm task doctor` reports scheduler diagnostics).
   `akm task explain <ref>` (new in 0.9.2) and `akm workflow plan <ref>` are
@@ -355,20 +378,17 @@ CHANGELOG with a migration note.
   `log.md` / `raw/` / `pages/` and its ingest flow); wiki pages are addressed
   as ordinary concepts inside their bundle. Adapter behavior and page
   conventions are still iterating.
-- **Agent dispatch** — `akm agent` and `akm command run`. Supported backends:
-  `claude`, `opencode-sdk` (the primary OpenCode interface), `codex`, and the
-  `opencode` CLI path, `copilot`, `pi`, `gemini`, `aider`, `amazonq`,
-  `openhands`. Every harness is Evolving: the harness implementation is being
-  reworked so harnesses are easy to add, remove and update (0.10). The set will
-  grow.
-  **Deprecated:** the `opencode` CLI dispatch path (an agent engine with
-  `platform: "opencode"`, which runs `opencode run` per call). It still works on
-  OpenCode 1 and 2 throughout 0.10; use an `opencode-sdk` engine instead, which
-  covers it, including a default agent (#1098). It may be removed in 0.11 or
-  later. The rest of the OpenCode integration (session-log import, config
-  import) is not deprecated.
-- **Model aliases** — `akm models list|copy-defaults` and the intent-alias
-  defaults they expose.
+- **Agent dispatch** — `akm agent` and `akm command run`. Supported
+  harnesses: `claude`, `codex`, `opencode` (through `opencode run`, for OpenCode 2
+  and for the legacy OpenCode 1, which keeps working with no removal date),
+  `copilot`, `pi`, `gemini`, `aider`, `amazonq` and `openhands`. Every harness is Evolving: a harness is a thin shell that turns a
+  request into a command, and the set is easy to add to, remove from and update.
+  The set will grow. A harness runs with your environment as it is
+  ([Configuration](docs/reference/configuration.md#how-akm-runs-a-harness)). With
+  no harness configured, agent work runs on akm's own runtime over a connection,
+  which is Evolving too.
+- **Model aliases** — `akm models` and `akm models set`, and the intent-alias
+  picks a connection holds.
 - **Proposal queue** — quality classifications (`accepted`, `pending`,
   `proposed`, `rejected`, `archived`) are stable; the JSON shape of a
   proposal record may add fields.
@@ -402,14 +422,13 @@ for scripted use.
   least settled part and are kept only in that simple form; `akm workflow list
   --children` goes with them.
 
-  Per-key status today, from the Outcome section of
-  `docs/plans/0.10-workflows.md`. It stands until the promote-or-remove
+  Per-key status today. It stands until the promote-or-remove
   decision in [#1096](https://github.com/itlackey/akm/issues/1096); every key
   is still Experimental until then.
 
   | Key | Status |
   | --- | --- |
-  | `params`, `steps`, `inputs`, `output` / `unit.output`, `defaults.engine`, `### gate` | Core: the feature set pinned by `core-feature-set.test.ts` |
+  | `params`, `steps`, `inputs`, `output` / `unit.output`, `defaults.connection` / `defaults.harness`, `### gate` | Core: the feature set pinned by `core-feature-set.test.ts` |
   | exec units (`unit.exec`), `budget`, `unit.retry`, `map`, `gate.max_loops` | Kept in the 0.10 trim |
   | child workflows (`unit.workflow`, `unit.with`) | Experimental: least settled |
 - **`akm metrics`** — new in 0.9.28. What it reports, its JSON shape and the
@@ -443,9 +462,9 @@ for scripted use.
   than `default` and `consolidate` and the proactive-maintenance lane. 0.10 measures each and keeps, folds or removes it
   (#1094). `quick`, `reflect-distill`, `thorough` and `catchup` were removed
   in 0.10 (#1130), as were `proactive-maintenance` and the high-salience lane (#1129); a user-defined strategy of the same name keeps working.
-- **Improve tuning config** — `improve.strategies.*.processes.*` (per-process
-  engines, limits, gates, and the CLS knobs) and
-  the `index.*` per-pass config. The 0.9.x series is explicitly still settling
+- **Improve tuning config** — `improve.strategies.*.processes.*` (limits,
+  gates, and the CLS knobs), `improve.processes.*` and `improve.qualityGate`
+  (where each process runs) and the `index.*` per-pass config. The 0.9.x series is explicitly still settling
   the design of the improve processes, so **keys in these two families may be
   added, renamed, or dropped in any 0.9.x or 0.10.x release**. The `akm
   improve` *command* surface is Evolving (above); its tuning config is not.
@@ -487,15 +506,15 @@ the pair pass stages a retirement when its claim checks pass and there is no
 continuity risk. `triage` with `applyMode: "promote"` can accept that staged
 retirement unattended; an unstaged retirement stays pending. Both retirement
 checks receive complete note bodies with lexical attention hints, so the selected
-engine must accommodate them. The pair judge supplies distinct-claim lists; AKM
+model must accommodate them. The pair judge supplies distinct-claim lists; AKM
 derives duplicate/subsumed/overlap outcomes and retirement direction from those
 lists. Historical queued retirement labels remain readable. Before unattended drain after an upgrade, review pending/staged
 retirements produced by older builds from notes over 12,000 body characters:
 upgrading does not revalidate their evidence (#1195).
 
 Because the gate is applied before the LLM preflight, a review-first workspace
-also needs fewer engines configured: a strategy whose only model-backed process
-is a gated lane resolves without an engine at all.
+also needs fewer connections or harnesses configured: a strategy whose only
+model-backed process is a gated lane resolves without one at all.
 
 **Three direct writes are deliberately NOT gated**, because they are additive or
 already independently controlled:
@@ -539,8 +558,6 @@ on them.
 | Variable | Purpose |
 | --- | --- |
 | `AKM_BUNDLE_DIR`, `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR` | Filesystem layout overrides |
-| `AKM_LLM_API_KEY`, `AKM_EMBED_API_KEY`, `AKM_ENGINE_<NAME>_API_KEY` | Credential provision for `$VAR` config references |
-| `AKM_LLM_ENDPOINT`, `AKM_LLM_BASE_URL` | Setup provider inference |
 | `AKM_VERBOSE`, `AKM_DEBUG` | Diagnostics |
 | `AKM_REGISTRY_URL` | akm registry mirror override |
 | `AKM_NPM_REGISTRY` | npm mirror override — redirects BOTH the trusted-tarball host allowlist and package metadata lookups (`npm view`-equivalent resolution) to the given registry base, replacing `registry.npmjs.org` wholesale rather than merging with it |
@@ -572,22 +589,6 @@ These changes are planned and will land in a known future release. They
 are not part of the current stability contract; you should plan migrations
 around them.
 
-**The 0.9.0 decision record is fully shipped.** The
-[decision record](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md) settles a set of
-breaking changes; every one of them is now in the code, and each decision
-carries its own shipped status.
-
-Shipped from that record: **D1** (`#fragment` section selection),
-**D2** (the `akm show <ref> toc|section|lines|frontmatter|full` view grammar is
-gone — `#fragment` is the only section selector), **D4** (conceptId /
-`bundle//` prefix browse), **D5** (`akm bundle` removed), **D6** (open `type`
-set at runtime), **D7** (all six `--format` values everywhere), **D8** (the
-`experimental.improveAutonomy` gate), **D9** (`--auto-accept` removed, a hard error since 0.10),
-and partially **D10** (an `akm-migrate` binary now exists, though the code still
-lives in this repo). **D3** shipped too, in the end: `akm mv` was removed in
-0.9.0 (see the Renames bullet above), with `scripts/rekey-asset-ref.ts` as the
-Internal replacement for the one capability nothing else covered.
-
 - **0.10 — `config set`/`config unset` may drop the config dump** in favor of
   a compact `{ok, shape, key}` result; `akm config list` remains the full read.
 - **0.10 — migration extraction.** The migration machinery lives in its own
@@ -595,9 +596,6 @@ Internal replacement for the one capability nothing else covered.
   `akm` (no separate npm package). The task-source migrator (`task-to-v4.ts`,
   `task-source-v3-frozen.ts`) lives with it under `scripts/akm-migrate/migrate/`,
   out of `src/`.
-- **0.11 or later — the `opencode` CLI dispatch path may be removed.**
-  Deprecated in 0.10 (see Agent dispatch under Evolving); `opencode-sdk`
-  engines replace it.
 - **0.10 — `BundleAdapter.placeNew()` is removed.** Nothing called it; writes use AKM's fixed type→directory table.
   Writable bundles in a non-akm layout would need per-adapter placement back
   ([#1163](https://github.com/itlackey/akm/issues/1163)).
@@ -624,7 +622,5 @@ worth fixing.
   (independent of the feature-stability policy above).
 - [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md) — the
   normative ref grammar.
-- [`docs/architecture/specs/0.9.0-decisions.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md)
-  — the decision record behind the 0.9.0 surface changes.
 - [`docs/reference/data-and-telemetry.md`](./docs/reference/data-and-telemetry.md) — what
   state akm reads and writes locally.

package/dist/assets/hints/cli-hints-full.md

@@ -68,7 +68,7 @@ akm show knowledge/my-doc                     # Show materialized local content
 | script | `run`, `setup`, `cwd` |
 | skill | `content` (full SKILL.md) |
 | command | `template`, `description`, `parameters` |
-| agent | `prompt`, `description`, `modelHint`, `toolPolicy` |
+| agent | `prompt`, `description`, `modelHint` |
 | knowledge | `content` (whole document, or one section via `#fragment`) |
 | workflow | `workflowTitle`, `workflowParameters`, `steps` |
 | memory | `content` (recalled context) |
@@ -297,7 +297,6 @@ akm registry add <url> --name my-team         # Add with label
 akm registry add <url> --provider skills-sh   # Specify provider type
 akm registry remove <url-or-name>             # Remove a registry
 akm search "<query>" --from registry          # Search all registries (registry search was folded into search)
-akm search "<query>" --from registry --assets # Include asset-level results
 ```
 
 ## Configuration
@@ -307,15 +306,18 @@ akm config list                               # Show current config
 akm config get <key>                          # Read a value
 akm config set <key> <value>                  # Set a value
 akm config unset <key>                        # Remove a key
+akm models                                    # Which model answers each alias, then what the endpoint lists
+akm models set <alias> <model>                # Change one (--connection <name> for another connection)
 ```
 
 ## Other Commands
 
 ```sh
 akm bundle create                                      # Initialize working bundle (scaffold only)
-akm setup                                     # Interactive wizard: bundle + LLM/embedding + agent + registry config
+akm setup                                     # Interactive wizard: agent programs, model connection, embeddings, bundle + registry config
 akm setup --dir ~/custom-bundle                # Run the wizard against a custom bundle path
 akm setup --yes                               # Non-interactive, accepts all defaults
+akm setup --endpoint <url> --yes              # Non-interactive, adds a model connection (an OpenAI-compatible endpoint)
 akm index                                     # Rebuild search index
 akm index --full                              # Full reindex
 akm bundle list                                      # List all sources
@@ -333,8 +335,8 @@ akm completions --install                     # Install completions
 ```
 
 `akm bundle create` only scaffolds the bundle directory and registers it in config;
-`akm setup` additionally walks through embedding/LLM connections, agent
-profiles, sources, and registries. Use `setup` for first-time onboarding,
+`akm setup` additionally walks through agent programs, a model connection,
+embeddings, sources, and registries. Use `setup` for first-time onboarding,
 `bundle create` when you just need a bare bundle.
 
 ## Proposals & Improvement (0.8.0+)
@@ -378,7 +380,7 @@ akm search --type task                         # Enumerate task assets
 ```
 
 Task files use task source v4 (`version: 4`). There is no `akm:` options bag
-or `on:` block — every control (`schedule`, `timeout`, `engine`, `model`,
+or `on:` block — every control (`schedule`, `timeout`, `connection`, `harness`, `model`,
 `redact`, `maxSteps`, `maxRetries`, …) is a top-level key now. Typed
 `inputs:` declarations and a bounded `output:` schema work like a
 workflow's (`output:` replaces v3's `akm.outputSchema`). Task source never
@@ -386,23 +388,24 @@ controls activation: use `akm task enable` / `disable`, which update the
 host-local config allow-list and sync. To remove one, delete the YAML and run
 `akm task sync` — the scheduler entry is unbound. Top-level
 `timeout:` may be `null` (disable the invocation timer) or a duration/number
-overriding the selected engine invocation timeout. Preview old task-v2/v3
+overriding the selected connection's or harness's timeout. Preview old task-v2/v3
 conversion with `akm migrate apply --dry-run`.
 
 ## Agent Dispatch
 
 ```sh
-akm agent --prompt "summarize open proposals"   # Dispatch the configured agent CLI
-akm agent agents/architect --prompt "..."       # Embody a bundle agent asset (system prompt, model, tool policy)
+akm agent --prompt "summarize open proposals"   # Run an agent on your default harness (else akm's own runtime over your connection)
+akm agent agents/architect --prompt "..."       # Embody a bundle agent asset (system prompt, model)
 akm command run commands/release                # Canonical reusable-command dispatch
-akm agent --model sonnet --prompt "..."         # Model override (aliases or exact IDs)
+akm agent --model reasoning --prompt "..."      # Model override (alias fast|balanced|reasoning, or an exact name)
+akm agent --harness claude --prompt "..."       # Run on a named harness (or --connection <name>)
 ```
 
 ## Health, Info, and the Event Log
 
 ```sh
-akm info                                       # Capabilities, bundle dir, index stats, semantic-search status
-akm health                                     # Runtime diagnostics; exit 0 ok / 4 warn / 1 fail
+akm info                                       # Capabilities, bundle dir, index stats, semantic-search status, connections and harnesses
+akm health                                     # Runtime diagnostics, connections and harnesses; exit 0 ok / 4 warn / 1 fail
 akm health --report                            # Adds accept-rate metrics
 akm metrics                                    # Usage, feedback, utility, LLM tokens, tasks, workflows (last 30d, read-only)
 akm metrics --since 7d                         # Narrow the window

package/dist/assets/opencode/akm-plugin.js

@@ -0,0 +1,177 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+// The OpenCode 2 plugin of akm's own agent runtime. akm writes this file to the runtime's config directory and names
+// it in the inline config's `plugins` list (src/integrations/harnesses/opencode/runtime/). It runs inside OpenCode, so
+// it imports no package: only Node's own child_process, to call back into akm.
+//
+//   - akm's three read tools, each a run of the akm that started OpenCode, with `--detail agent --format json`. akm
+//     passes the argv that runs it in `AKM_OPENCODE_CLI`, a JSON array: the executable alone for a compiled akm, the
+//     runtime and the script for one run as a script (Node and `dist/akm`, say), so no shebang or shell is needed on
+//     any platform. The run's environment is the call's, so a stamped run's reads (`AKM_EVENT_SOURCE`) are recorded as
+//     that run's.
+//   - The environment of the commands the agent runs: the variables akm set for the OpenCode process (its roots and
+//     its OpenCode settings) are put back to what akm runs in, or removed, so the agent's shell sees the environment a
+//     harness's child would.
+//   - The connection's request fields, laid over each model request in the endpoint's own field names, as the chat
+//     transport sends them. OpenCode sizes every request's output cap from the model's limit and sends it as
+//     `max_tokens` or `max_completion_tokens`; that is its own accounting, not a cap anyone asked for, so it is
+//     dropped, and the connection's fields carry a cap only when the connection writes one.
+
+import { execFile } from "node:child_process";
+
+const OUTPUT_LIMIT_BYTES = 8 * 1024 * 1024;
+
+const TOOLS = [
+  {
+    name: "akm_curate",
+    command: "curate",
+    positional: "query",
+    description:
+      "Find the akm assets (skills, knowledge, memories, workflows) that best fit a task. Read one with akm_show before relying on it.",
+    input: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "The task or question" },
+        type: { type: "string", description: "Optional asset type filter" },
+        limit: { type: "integer", minimum: 1 },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "akm_search",
+    command: "search",
+    positional: "query",
+    description: "Search akm assets by name or keyword.",
+    input: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        type: { type: "string", description: "Optional asset type filter" },
+        limit: { type: "integer", minimum: 1 },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "akm_show",
+    command: "show",
+    positional: "ref",
+    description: "Read one akm asset by its ref, as returned by akm_curate or akm_search.",
+    input: { type: "object", properties: { ref: { type: "string" } }, required: ["ref"] },
+  },
+];
+
+const text = (value) => (typeof value === "string" && value.trim() !== "" ? value.trim() : undefined);
+
+/** The arguments of one tool call for the akm CLI; throws when the required one is missing. */
+function cliArguments(tool, input) {
+  const value = text(input?.[tool.positional]);
+  if (!value) throw new Error(`"${tool.positional}" is required`);
+  const type = text(input?.type);
+  const limit = Number.isInteger(input?.limit) && input.limit > 0 ? String(input.limit) : undefined;
+  return [
+    tool.command,
+    value,
+    ...(type && tool.positional !== "ref" ? ["--type", type] : []),
+    ...(limit && tool.positional !== "ref" ? ["--limit", limit] : []),
+    "--detail",
+    "agent",
+    "--format",
+    "json",
+  ];
+}
+
+/** The argv in `AKM_OPENCODE_CLI`; throws unless it is a JSON array of strings with at least the executable. */
+function akmArgv() {
+  const raw = process.env.AKM_OPENCODE_CLI;
+  if (!raw) throw new Error("AKM_OPENCODE_CLI is not set");
+  const argv = JSON.parse(raw);
+  if (!Array.isArray(argv) || argv.length === 0 || !argv.every((part) => typeof part === "string")) {
+    throw new Error("AKM_OPENCODE_CLI is not a JSON array of strings");
+  }
+  return argv;
+}
+
+function runAkm([executable, ...prefix], args) {
+  return new Promise((resolve, reject) => {
+    execFile(
+      executable,
+      [...prefix, ...args],
+      { encoding: "utf8", maxBuffer: OUTPUT_LIMIT_BYTES, env: process.env },
+      (error, stdout, stderr) => {
+        if (error) reject(new Error((stderr || error.message).trim()));
+        else resolve(stdout);
+      },
+    );
+  });
+}
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** `over` laid over `base`; an object on both sides is merged one level deep, anything else of `over` wins. */
+function withFields(base, over) {
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(over)) {
+    merged[key] = isObject(merged[key]) && isObject(value) ? { ...merged[key], ...value } : value;
+  }
+  return merged;
+}
+
+export default {
+  id: "akm",
+  setup: async (ctx) => {
+    await ctx.tool.transform((editor) => {
+      for (const tool of TOOLS) {
+        editor.add({
+          name: tool.name,
+          description: tool.description,
+          input: tool.input,
+          options: { codemode: false },
+          execute: async (input) => {
+            try {
+              const args = cliArguments(tool, input);
+              return { content: await runAkm(akmArgv(), args) };
+            } catch (error) {
+              return { content: `${tool.name} failed: ${error instanceof Error ? error.message : String(error)}` };
+            }
+          },
+        });
+      }
+    });
+
+    const shellEnv = ctx.options?.shellEnv;
+    if (isObject(shellEnv)) {
+      await ctx.shell.hook("create.before", async (event) => {
+        for (const [name, value] of Object.entries(shellEnv)) {
+          if (typeof value === "string") event.env[name] = value;
+          else delete event.env[name];
+        }
+      });
+    }
+
+    const fields = ctx.options?.requestFields;
+    await ctx.session.hook("http.request", async (event) => {
+      const request = event.request;
+      if (request.body === null) return;
+      let body;
+      try {
+        body = JSON.parse(await request.clone().text());
+      } catch {
+        return;
+      }
+      if (!isObject(body)) return;
+      const { max_tokens: _own, max_completion_tokens: _ownCompletion, ...kept } = body;
+      const headers = new Headers(request.headers);
+      headers.delete("content-length");
+      event.request = new Request(request.url, {
+        method: request.method,
+        headers,
+        body: JSON.stringify(isObject(fields) ? withFields(kept, fields) : kept),
+        signal: request.signal,
+      });
+    });
+  },
+};

package/dist/assets/stash-skeleton/README.md

@@ -13,7 +13,7 @@ consistency and reducing repeated context-setting.
 | `knowledge/` | Knowledge | Reference documents, guides, architecture notes |
 | `memories/` | Memories | Persistent facts and preferences learned over time |
 | `commands/` | Commands | Parameterised prompt templates for common workflows |
-| `agents/` | Agents | Agent definitions with system prompts and tool policies |
+| `agents/` | Agents | Agent definitions with system prompts |
 | `workflows/` | Workflows | Multi-step orchestration sequences |
 | `tasks/` | Tasks | Scheduled or on-demand automation tasks |
 | `lessons/` | Lessons | Durable lessons extracted from past sessions |

package/dist/assets/tasks/core/improve.yml

@@ -1,4 +1,4 @@
 version: 4
-run: akm improve --require-engines
+run: akm improve
 description: Run improve pipeline nightly
 schedule: "0 2 * * *"

package/dist/assets/tasks/improve/akm-improve-consolidate.yml

@@ -1,4 +1,4 @@
 version: 4
-run: akm improve --strategy consolidate --timeout-ms 3600000 --skip-if-locked --require-engines
+run: akm improve --strategy consolidate --timeout-ms 3600000 --skip-if-locked
 description: Consolidation-only pass (every 4h at :20)
 schedule: "20 */4 * * *"

package/dist/assets/ui/config.js

@@ -34,16 +34,32 @@ function node(key, value, path, sources, depth) {
   return html`<li class="leaf"><span class="mono key">${key}</span><span class="leaf-value">${leafValue(value)}</span>${sourceBadge(source)}</li>`;
 }
 
-function enginesTable(engines) {
-  if (engines.length === 0) return emptyState("No engines are configured.");
-  const rest = (e) => {
-    const { name, kind, endpoint, model, ...others } = e;
-    return Object.keys(others).length > 0 ? JSON.stringify(others) : "";
-  };
+/** What a table shows of an entry beyond its named columns, as compact JSON. */
+function otherFields(entry, shown) {
+  const rest = Object.fromEntries(Object.entries(entry).filter(([key]) => !shown.includes(key)));
+  return Object.keys(rest).length > 0 ? JSON.stringify(rest) : "";
+}
+
+function connectionsTable(connections) {
+  if (connections.length === 0) return emptyState("No connections are configured.");
+  const aliases = (c) =>
+    Object.entries(c.models ?? {})
+      .map(([alias, entry]) => `${alias}: ${typeof entry === "string" ? entry : entry.model}`)
+      .join(", ");
+  return tableWrap(
+    html`<table><thead><tr><th>Name</th><th>Endpoint</th><th>Models</th><th>Other</th></tr></thead><tbody>${connections.map(
+      (c) =>
+        html`<tr><td class="mono">${c.name}</td><td class="mono wrap">${c.endpoint ?? ""}</td><td class="mono wrap">${aliases(c)}</td><td class="mono small wrap">${otherFields(c, ["name", "endpoint", "models"])}</td></tr>`,
+    )}</tbody></table>`,
+  );
+}
+
+function harnessesTable(harnesses) {
+  if (harnesses.length === 0) return emptyState("No harnesses are configured.");
   return tableWrap(
-    html`<table><thead><tr><th>Name</th><th>Kind</th><th>Endpoint</th><th>Model</th><th>Other</th></tr></thead><tbody>${engines.map(
-      (e) =>
-        html`<tr><td class="mono">${e.name}</td><td>${e.kind}</td><td class="mono wrap">${e.endpoint ?? ""}</td><td class="mono">${e.model ?? ""}</td><td class="mono small wrap">${rest(e)}</td></tr>`,
+    html`<table><thead><tr><th>Name</th><th>Platform</th><th>Other</th></tr></thead><tbody>${harnesses.map(
+      (h) =>
+        html`<tr><td class="mono">${h.name}</td><td class="mono">${h.platform ?? h.name}</td><td class="mono small wrap">${otherFields(h, ["name", "platform"])}</td></tr>`,
     )}</tbody></table>`,
   );
 }
@@ -58,7 +74,8 @@ export async function render() {
     ])}${data.exists ? "" : html`<p class="muted">There is no config file, so everything below is a default.</p>`}</section>
     <section><h2>Effective config</h2><p class="legend-line">Source: ${sourceBadge("default")} built-in ${sourceBadge("file")} this install's config.json ${sourceBadge("extends:ref")} a config it extends</p>
       ${keys.length === 0 ? emptyState("The effective config is empty.") : html`<ul class="tree root">${keys.map((k) => node(k, data.config[k], k, sources, 0))}</ul>`}</section>
-    <section><h2>Engines</h2>${enginesTable(data.engines)}</section>
+    <section><h2>Connections</h2>${connectionsTable(data.connections)}</section>
+    <section><h2>Harnesses</h2>${harnessesTable(data.harnesses)}</section>
     <section><h2>Environment</h2><p class="muted">AKM_* variables set for the server. They override paths and credentials.</p>${
       data.env.length === 0
         ? emptyState("No AKM_* environment variables are set.")

package/dist/assets/workflows/workflow-template.md

@@ -37,8 +37,8 @@ first step's attached artifact."
 
 A `### gate` sub-heading is the step's completion rubric: the judge
 receives this whole section byte-exact. Omit the heading or leave its text
-empty to skip validation. A non-empty rubric requires
-`workflow.judgeEngine`; verifier failures and malformed verdicts reject the
+empty to skip validation. A non-empty rubric needs a connection or a harness
+to judge it; verifier failures and malformed verdicts reject the
 gate rather than silently skipping it.
 
 - Confirm the step accomplished what it set out to do.

package/dist/cli/clack.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { cancel as realCancel, confirm as realConfirm, intro as realIntro, isCancel as realIsCancel, log as realLog, multiselect as realMultiselect, note as realNote, outro as realOutro, select as realSelect, spinner as realSpinner, text as realText, } from "@clack/prompts";
+import { cancel as realCancel, confirm as realConfirm, intro as realIntro, isCancel as realIsCancel, log as realLog, multiselect as realMultiselect, note as realNote, outro as realOutro, password as realPassword, select as realSelect, spinner as realSpinner, text as realText, } from "@clack/prompts";
 // ── Test seam ────────────────────────────────────────────────────────────────
 // Swap-and-restore override. Inert in production; only tests call the setter
 // (via tests/_helpers/seams.ts `overrideSeam`, never directly).
@@ -18,6 +18,7 @@ const realFns = {
     select: realSelect,
     multiselect: realMultiselect,
     text: realText,
+    password: realPassword,
     spinner: realSpinner,
     note: realNote,
     isCancel: realIsCancel,
@@ -42,6 +43,7 @@ export const confirm = bind("confirm");
 export const select = bind("select");
 export const multiselect = bind("multiselect");
 export const text = bind("text");
+export const password = bind("password");
 export const spinner = bind("spinner");
 export const note = bind("note");
 export const isCancel = bind("isCancel");

package/dist/cli/selection.js

@@ -0,0 +1,33 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { UsageError } from "../core/errors.js";
+import { warnOnce } from "../core/warn.js";
+import { getStringArg } from "./parse-args.js";
+export const SELECTION_ARGS = {
+    connection: { type: "string", description: "Run on this connection, by name (default: the default connection)" },
+    harness: { type: "string", description: "Run on this harness, by name or platform (default: the default harness)" },
+    model: { type: "string", description: "Model to run, by alias (fast, balanced, reasoning) or exact name" },
+};
+/** The retired `--engine`: parsed, left out of `--help` (`withoutHiddenArgs`). Spread it where the flag existed. */
+export const RETIRED_ENGINE_ARG = {
+    engine: { type: "string", hidden: true, description: "Retired: use --connection or --harness." },
+};
+export function selectionFromArgs(args) {
+    const connection = getStringArg(args, "connection");
+    const harness = getStringArg(args, "harness");
+    if (connection !== undefined && harness !== undefined) {
+        throw new UsageError("--connection and --harness are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
+    }
+    const engine = getStringArg(args, "engine");
+    if (engine !== undefined) {
+        warnOnce("retired-flag:--engine", "--engine is retired: use --connection or --harness. For now it names a connection by that name, else a harness.");
+    }
+    const model = getStringArg(args, "model");
+    return {
+        ...(connection !== undefined ? { connection } : {}),
+        ...(harness !== undefined ? { harness } : {}),
+        ...(engine !== undefined ? { engine } : {}),
+        ...(model !== undefined ? { model } : {}),
+    };
+}

package/dist/cli/shared.js

@@ -92,7 +92,7 @@ function extractHint(error) {
  * R-067: this used to call `process.exit(exitCode)` directly, which
  * terminates the process synchronously and skips every pending `finally`
  * block up the call stack — including `src/cli.ts`'s own
- * `disposeDispatchResources()` cleanup and citty's per-command `cleanup`
+ * `disposeLlmUsageSink()` cleanup and citty's per-command `cleanup`
  * hooks. `process.exitCode = exitCode; return;` is equivalent for every
  * caller here: Node/Bun exits with that code once the event loop drains
  * naturally, but cleanup on the way there still runs.
@@ -183,6 +183,19 @@ export const GLOBAL_OUTPUT_ARGS = {
         default: false,
     },
 };
+/**
+ * A command with the args marked `hidden` left out: what `--help` renders. A
+ * hidden arg parses like any other and is simply not advertised, the way
+ * `meta.hidden` keeps a command out of the COMMANDS list. It is for a retired
+ * spelling that still works, so a scheduled command written for an earlier
+ * release keeps running.
+ */
+export function withoutHiddenArgs(command) {
+    const args = command.args;
+    if (!args)
+        return command;
+    return { ...command, args: Object.fromEntries(Object.entries(args).filter(([, def]) => def.hidden !== true)) };
+}
 /**
  * Define a citty command whose `run` body is automatically wrapped in
  * `runWithJsonErrors`, so the handler emits a byte-identical JSON error