agentkernel-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{agentkernel_cli-0.1.0 → agentkernel_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentkernel-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: A minimal, dependency-light kernel for a general-purpose AI agent — runs anywhere, brings its own brain.
 Project-URL: Homepage, https://github.com/sebbyrule/agentkernal
 Project-URL: Repository, https://github.com/sebbyrule/agentkernal
@@ -76,6 +76,9 @@ API keys are read **only** from the environment — never from config files or t
 ```bash
 export ANTHROPIC_API_KEY=***     # for provider = "anthropic"
 export OPENAI_API_KEY=***        # for provider = "openai" / embeddings
+export OPENROUTER_API_KEY=***    # for provider = "openrouter"
+export DEEPSEEK_API_KEY=***      # for provider = "deepseek"
+export GEMINI_API_KEY=***        # for provider = "gemini"
 # local/OpenAI-compatible endpoints (Ollama, vLLM) usually need no key
 # Credential pool: give several keys and the provider rotates on rate limits —
 # comma-separate (ANTHROPIC_API_KEY="k1,k2") or number them (ANTHROPIC_API_KEY_1, _2).
@@ -115,6 +118,11 @@ uv run agentkernel tui                        # full-screen curses terminal UI
 uv run agentkernel run "your prompt"          # single non-interactive run, prints the answer
 uv run agentkernel run --file task.md         # single run from a prompt file
 uv run agentkernel run --background "..."      # detached run; output goes to a file
+uv run agentkernel run --image diagram.png "explain this"   # attach an image (repeatable; path or URL)
+uv run agentkernel skill list                 # list discovered skills
+uv run agentkernel skill pack code-review     # package a skill into code-review.skill.zip
+uv run agentkernel skill install cr.skill.zip # install a shared skill bundle into skills/
+source <(agentkernel completion bash)         # shell completion (bash | zsh | fish)
 uv run agentkernel improve                    # reflect on the latest trace, write a rule note
 uv run agentkernel eval --suite s.toml        # run an eval suite, score answers with a judge
 uv run agentkernel eval --suite s.toml -o report.json  # ...and write a JSON report
@@ -142,13 +150,14 @@ status per turn, and writes a per-session JSONL trace. It supports slash command
 $ uv run agentkernel
 [session trace: .agentkernel/traces/<session-id>.jsonl]
 agentkernel REPL - type your message and press enter. Commands: /exit, /clear,
-/system, /profile, /skills, /skill, /tools, /trace, /cost, /memory, /improve.
+/image, /system, /profile, /skills, /skill, /tools, /trace, /cost, /memory, /improve.
 > summarize the files in this directory
 ```
 
 | Command | Effect |
 |---|---|
 | `/clear` | reset the conversation context |
+| `/image <path-or-url>` | attach an image to the next message (`/image clear` to discard) |
 | `/system [text]` | set (or clear) the system prompt for following turns |
 | `/profile [name]` | show, or load, a profile from `profile_dir` |
 | `/skills` | list discovered skills (`*` = active) |
@@ -192,9 +201,10 @@ Configuration loads from `agentkernel.toml` (see [`agentkernel.toml.example`](ag
 
 | Key | Default | Meaning |
 |---|---|---|
-| `provider` | `anthropic` | `anthropic` \| `openai` \| `local` |
+| `provider` | `anthropic` | `anthropic` \| `openai` \| `local` \| `openrouter` \| `deepseek` \| `gemini` |
 | `model` | `claude-sonnet-4-6` | model id for the selected provider |
 | `base_url` | `None` | endpoint for `provider = "local"` |
+| `local_supports_images` | `False` | opt in to sending images to a vision-capable `local` endpoint (Anthropic/OpenAI accept images automatically) |
 | `max_output_tokens` | `4096` | reply token cap |
 | `output_reserve` | `8192` | budget headroom reserved for the reply |
 | `max_iterations` | `25` | loop guard against runaway sessions |
@@ -218,6 +228,9 @@ Configuration loads from `agentkernel.toml` (see [`agentkernel.toml.example`](ag
 | `enable_memory_tools` | `False` | register `remember`/`recall`/`forget` tools |
 | `memory_auto_context` / `memory_auto_context_limit` | `False` / `3` | auto-inject recalled notes before each user message |
 | `memory_store_budget` | `None` | summarize older turns before persisting memory |
+| `memory_scope` | `None` | recall namespace: `auto` (project dir name), a literal name, or off; recall returns global + active-namespace notes |
+| `memory_recency_weight` / `memory_importance_weight` | `0.0` / `0.0` | opt-in recall re-ranking: boost notes by recency of creation and by recall frequency (`0` = relevance only) |
+| `memory_half_life_days` | `30.0` | days for a note's recency score to halve |
 | `memory_curator_model` | `None` | cheap model for `memory extract`/`consolidate` (falls back to `summarizer_model`/`model`) |
 | `semantic_search` | `False` | rank note recall with dense embeddings (SQLite only) |
 | `semantic_search_lsh_bits` | `None` | approximate vector index bits; omit for brute force |
@@ -271,12 +284,13 @@ MCP servers are declared separately as `[[mcp_servers]]` tables (see [MCP](#mcp-
 
 ### Providers ([`providers/`](agentkernel/providers))
 
-Hand-written `httpx` adapters for **Anthropic** (Messages API), **OpenAI** (Chat Completions), and **local** (OpenAI-compatible: Ollama, vLLM, LM Studio). Each adapter:
+Hand-written `httpx` adapters for **Anthropic** (Messages API), **OpenAI** (Chat Completions), and **local** (OpenAI-compatible: Ollama, vLLM, LM Studio). **OpenRouter**, **DeepSeek**, and **Gemini** ship as thin named adapters over the OpenAI shape — each just pins a default `base_url` and `*_API_KEY` env var, so `provider = "gemini"` works without hand-wiring an endpoint. Each adapter:
 
 - translates canonical messages/tools to the provider's exact wire shape and back,
 - handles the **tool-result pairing** fan-out (Anthropic: all results in one `user` message of `tool_result` blocks; OpenAI: one `role:"tool"` message per result),
 - reports cache read/write token counts where available,
-- applies cache markers on the stable prefix (Anthropic `cache_control: ephemeral`).
+- applies cache markers on the stable prefix (Anthropic `cache_control: ephemeral`),
+- translates **image input** (`Message.images`) to each wire shape (Anthropic `image` blocks, OpenAI/local `image_url` parts), gated by `Provider.supports_images` so a text-only provider drops images instead of erroring.
 
 Translation is implemented as **pure functions** separate from the HTTP call, which is what makes adapter behavior testable offline. The adapters share one `httpx` transport ([`providers/_http.py`](agentkernel/providers/_http.py)) that retries transient failures (timeouts and `429`/`5xx`), honoring a server `Retry-After` header (bounded) when present, and raises `ProviderError` only once retries are exhausted.
 
@@ -335,7 +349,7 @@ These are implemented on top of the kernel using the three primitives — a tool
 
 - **Profiles** ([`profiles.py`](agentkernel/profiles.py)) — a run parameter `(system_prompt, tool_filter, model_override, rubric)` loaded from `profiles/<name>.toml`. The loop honors `system_prompt` and `tool_filter`; CLI `--profile` sets the active profile, and a profile's `model_override` or `rubric` override the defaults.
 - **Skills** ([`skills.py`](agentkernel/skills.py)) — [Anthropic-style](https://github.com/anthropics/skills) `SKILL.md` folders (YAML frontmatter `name`/`description` + body + bundled files) discovered from `skills_dir`, with **progressive disclosure**: only a name+description catalog sits in the (stable, assembled-once) prefix; the model loads a skill's full body + file listing on demand via the `use_skill` tool. A skill can also be *pinned* (`skills = [...]`, `--skill <name>`, or `/skill <name>`) to force its body into the prefix. Loose `.md`/`.toml` skills still work.
-- **Memory** ([`memory.py`](agentkernel/memory.py), [`semantic_memory.py`](agentkernel/semantic_memory.py)) — a `MemoryStore` loaded before a run and saved after; ships with in-memory, JSONL, and SQLite/FTS5 stores. Enable with `memory_store`. The SQLite notebook supports optional `semantic_search` via an OpenAI-compatible embedding endpoint, cosine-ranked recall, and a standard-library-only approximate LSH index (`semantic_search_lsh_bits`) for large notebooks. The `reindex_memory` tool backfills embeddings when a notebook is promoted to semantic recall.
+- **Memory** ([`memory.py`](agentkernel/memory.py), [`semantic_memory.py`](agentkernel/semantic_memory.py)) — a `MemoryStore` loaded before a run and saved after; ships with in-memory, JSONL, and SQLite/FTS5 stores. Enable with `memory_store`. The SQLite notebook supports optional `semantic_search` via an OpenAI-compatible embedding endpoint, cosine-ranked recall, and a standard-library-only approximate LSH index (`semantic_search_lsh_bits`) for large notebooks. The `reindex_memory` tool backfills embeddings when a notebook is promoted to semantic recall. Recall can optionally be re-ranked by note age and recall frequency (`memory_recency_weight`/`memory_importance_weight`/`memory_half_life_days`) using the `access_count` metadata the notebook already tracks; with the default zero weights, ordering is pure relevance. A single notebook can also be partitioned into namespaces with `memory_scope` (e.g. `auto` for a per-project namespace): recall returns global notes plus the active namespace's, and new notes are stamped with it — keeping one "global brain" file while letting project-specific facts stay project-local. Within a scoped run the model can still pin a universal fact with `remember(global=true)`, which writes it to the empty scope so it's recalled everywhere.
 - **Knowledge graph** ([`knowledge.py`](agentkernel/knowledge.py)) — a file-backed triple store exposed purely as `graph_add`, `graph_query`, `graph_neighbors`, `graph_path`, and `graph_stats` tools (`enable_graph = true`). The kernel keeps no graph state.
 - **Loops** ([`loops.py`](agentkernel/loops.py)) — [loop-engineering](https://signals.forwardfuture.ai/loop-library/) workflows: `agentkernel loop` re-runs the agent on a loop's prompt until a stopping condition (a success shell-check and/or an N-in-a-row streak), following **action → check → iterate → stop**. Loops load from TOML or from a skill body (`--skill`), and the success check runs in the sandbox so a loop can verify its own work (e.g. "fix until `pytest` is green").
 - **Self-improvement** ([`improvement.py`](agentkernel/improvement.py)) — `agentkernel improve` or the REPL's `/improve` reads a session trace and asks the model for one concrete rule, written to `improvements_dir`. This is why telemetry exists from turn one.

{agentkernel_cli-0.1.0 → agentkernel_cli-0.2.0}/README.md

@@ -45,6 +45,9 @@ API keys are read **only** from the environment — never from config files or t
 ```bash
 export ANTHROPIC_API_KEY=***     # for provider = "anthropic"
 export OPENAI_API_KEY=***        # for provider = "openai" / embeddings
+export OPENROUTER_API_KEY=***    # for provider = "openrouter"
+export DEEPSEEK_API_KEY=***      # for provider = "deepseek"
+export GEMINI_API_KEY=***        # for provider = "gemini"
 # local/OpenAI-compatible endpoints (Ollama, vLLM) usually need no key
 # Credential pool: give several keys and the provider rotates on rate limits —
 # comma-separate (ANTHROPIC_API_KEY="k1,k2") or number them (ANTHROPIC_API_KEY_1, _2).
@@ -84,6 +87,11 @@ uv run agentkernel tui                        # full-screen curses terminal UI
 uv run agentkernel run "your prompt"          # single non-interactive run, prints the answer
 uv run agentkernel run --file task.md         # single run from a prompt file
 uv run agentkernel run --background "..."      # detached run; output goes to a file
+uv run agentkernel run --image diagram.png "explain this"   # attach an image (repeatable; path or URL)
+uv run agentkernel skill list                 # list discovered skills
+uv run agentkernel skill pack code-review     # package a skill into code-review.skill.zip
+uv run agentkernel skill install cr.skill.zip # install a shared skill bundle into skills/
+source <(agentkernel completion bash)         # shell completion (bash | zsh | fish)
 uv run agentkernel improve                    # reflect on the latest trace, write a rule note
 uv run agentkernel eval --suite s.toml        # run an eval suite, score answers with a judge
 uv run agentkernel eval --suite s.toml -o report.json  # ...and write a JSON report
@@ -111,13 +119,14 @@ status per turn, and writes a per-session JSONL trace. It supports slash command
 $ uv run agentkernel
 [session trace: .agentkernel/traces/<session-id>.jsonl]
 agentkernel REPL - type your message and press enter. Commands: /exit, /clear,
-/system, /profile, /skills, /skill, /tools, /trace, /cost, /memory, /improve.
+/image, /system, /profile, /skills, /skill, /tools, /trace, /cost, /memory, /improve.
 > summarize the files in this directory
 ```
 
 | Command | Effect |
 |---|---|
 | `/clear` | reset the conversation context |
+| `/image <path-or-url>` | attach an image to the next message (`/image clear` to discard) |
 | `/system [text]` | set (or clear) the system prompt for following turns |
 | `/profile [name]` | show, or load, a profile from `profile_dir` |
 | `/skills` | list discovered skills (`*` = active) |
@@ -161,9 +170,10 @@ Configuration loads from `agentkernel.toml` (see [`agentkernel.toml.example`](ag
 
 | Key | Default | Meaning |
 |---|---|---|
-| `provider` | `anthropic` | `anthropic` \| `openai` \| `local` |
+| `provider` | `anthropic` | `anthropic` \| `openai` \| `local` \| `openrouter` \| `deepseek` \| `gemini` |
 | `model` | `claude-sonnet-4-6` | model id for the selected provider |
 | `base_url` | `None` | endpoint for `provider = "local"` |
+| `local_supports_images` | `False` | opt in to sending images to a vision-capable `local` endpoint (Anthropic/OpenAI accept images automatically) |
 | `max_output_tokens` | `4096` | reply token cap |
 | `output_reserve` | `8192` | budget headroom reserved for the reply |
 | `max_iterations` | `25` | loop guard against runaway sessions |
@@ -187,6 +197,9 @@ Configuration loads from `agentkernel.toml` (see [`agentkernel.toml.example`](ag
 | `enable_memory_tools` | `False` | register `remember`/`recall`/`forget` tools |
 | `memory_auto_context` / `memory_auto_context_limit` | `False` / `3` | auto-inject recalled notes before each user message |
 | `memory_store_budget` | `None` | summarize older turns before persisting memory |
+| `memory_scope` | `None` | recall namespace: `auto` (project dir name), a literal name, or off; recall returns global + active-namespace notes |
+| `memory_recency_weight` / `memory_importance_weight` | `0.0` / `0.0` | opt-in recall re-ranking: boost notes by recency of creation and by recall frequency (`0` = relevance only) |
+| `memory_half_life_days` | `30.0` | days for a note's recency score to halve |
 | `memory_curator_model` | `None` | cheap model for `memory extract`/`consolidate` (falls back to `summarizer_model`/`model`) |
 | `semantic_search` | `False` | rank note recall with dense embeddings (SQLite only) |
 | `semantic_search_lsh_bits` | `None` | approximate vector index bits; omit for brute force |
@@ -240,12 +253,13 @@ MCP servers are declared separately as `[[mcp_servers]]` tables (see [MCP](#mcp-
 
 ### Providers ([`providers/`](agentkernel/providers))
 
-Hand-written `httpx` adapters for **Anthropic** (Messages API), **OpenAI** (Chat Completions), and **local** (OpenAI-compatible: Ollama, vLLM, LM Studio). Each adapter:
+Hand-written `httpx` adapters for **Anthropic** (Messages API), **OpenAI** (Chat Completions), and **local** (OpenAI-compatible: Ollama, vLLM, LM Studio). **OpenRouter**, **DeepSeek**, and **Gemini** ship as thin named adapters over the OpenAI shape — each just pins a default `base_url` and `*_API_KEY` env var, so `provider = "gemini"` works without hand-wiring an endpoint. Each adapter:
 
 - translates canonical messages/tools to the provider's exact wire shape and back,
 - handles the **tool-result pairing** fan-out (Anthropic: all results in one `user` message of `tool_result` blocks; OpenAI: one `role:"tool"` message per result),
 - reports cache read/write token counts where available,
-- applies cache markers on the stable prefix (Anthropic `cache_control: ephemeral`).
+- applies cache markers on the stable prefix (Anthropic `cache_control: ephemeral`),
+- translates **image input** (`Message.images`) to each wire shape (Anthropic `image` blocks, OpenAI/local `image_url` parts), gated by `Provider.supports_images` so a text-only provider drops images instead of erroring.
 
 Translation is implemented as **pure functions** separate from the HTTP call, which is what makes adapter behavior testable offline. The adapters share one `httpx` transport ([`providers/_http.py`](agentkernel/providers/_http.py)) that retries transient failures (timeouts and `429`/`5xx`), honoring a server `Retry-After` header (bounded) when present, and raises `ProviderError` only once retries are exhausted.
 
@@ -304,7 +318,7 @@ These are implemented on top of the kernel using the three primitives — a tool
 
 - **Profiles** ([`profiles.py`](agentkernel/profiles.py)) — a run parameter `(system_prompt, tool_filter, model_override, rubric)` loaded from `profiles/<name>.toml`. The loop honors `system_prompt` and `tool_filter`; CLI `--profile` sets the active profile, and a profile's `model_override` or `rubric` override the defaults.
 - **Skills** ([`skills.py`](agentkernel/skills.py)) — [Anthropic-style](https://github.com/anthropics/skills) `SKILL.md` folders (YAML frontmatter `name`/`description` + body + bundled files) discovered from `skills_dir`, with **progressive disclosure**: only a name+description catalog sits in the (stable, assembled-once) prefix; the model loads a skill's full body + file listing on demand via the `use_skill` tool. A skill can also be *pinned* (`skills = [...]`, `--skill <name>`, or `/skill <name>`) to force its body into the prefix. Loose `.md`/`.toml` skills still work.
-- **Memory** ([`memory.py`](agentkernel/memory.py), [`semantic_memory.py`](agentkernel/semantic_memory.py)) — a `MemoryStore` loaded before a run and saved after; ships with in-memory, JSONL, and SQLite/FTS5 stores. Enable with `memory_store`. The SQLite notebook supports optional `semantic_search` via an OpenAI-compatible embedding endpoint, cosine-ranked recall, and a standard-library-only approximate LSH index (`semantic_search_lsh_bits`) for large notebooks. The `reindex_memory` tool backfills embeddings when a notebook is promoted to semantic recall.
+- **Memory** ([`memory.py`](agentkernel/memory.py), [`semantic_memory.py`](agentkernel/semantic_memory.py)) — a `MemoryStore` loaded before a run and saved after; ships with in-memory, JSONL, and SQLite/FTS5 stores. Enable with `memory_store`. The SQLite notebook supports optional `semantic_search` via an OpenAI-compatible embedding endpoint, cosine-ranked recall, and a standard-library-only approximate LSH index (`semantic_search_lsh_bits`) for large notebooks. The `reindex_memory` tool backfills embeddings when a notebook is promoted to semantic recall. Recall can optionally be re-ranked by note age and recall frequency (`memory_recency_weight`/`memory_importance_weight`/`memory_half_life_days`) using the `access_count` metadata the notebook already tracks; with the default zero weights, ordering is pure relevance. A single notebook can also be partitioned into namespaces with `memory_scope` (e.g. `auto` for a per-project namespace): recall returns global notes plus the active namespace's, and new notes are stamped with it — keeping one "global brain" file while letting project-specific facts stay project-local. Within a scoped run the model can still pin a universal fact with `remember(global=true)`, which writes it to the empty scope so it's recalled everywhere.
 - **Knowledge graph** ([`knowledge.py`](agentkernel/knowledge.py)) — a file-backed triple store exposed purely as `graph_add`, `graph_query`, `graph_neighbors`, `graph_path`, and `graph_stats` tools (`enable_graph = true`). The kernel keeps no graph state.
 - **Loops** ([`loops.py`](agentkernel/loops.py)) — [loop-engineering](https://signals.forwardfuture.ai/loop-library/) workflows: `agentkernel loop` re-runs the agent on a loop's prompt until a stopping condition (a success shell-check and/or an N-in-a-row streak), following **action → check → iterate → stop**. Loops load from TOML or from a skill body (`--skill`), and the success check runs in the sandbox so a loop can verify its own work (e.g. "fix until `pytest` is green").
 - **Self-improvement** ([`improvement.py`](agentkernel/improvement.py)) — `agentkernel improve` or the REPL's `/improve` reads a session trace and asks the model for one concrete rule, written to `improvements_dir`. This is why telemetry exists from turn one.

{agentkernel_cli-0.1.0 → agentkernel_cli-0.2.0}/agent-kernel-design.md

@@ -612,13 +612,13 @@ within each group is rough priority. Nothing here is committed.
 | **Credential pools / key rotation** ✅ | provider | **Done** (`providers/credentials.py`). Keys are read from one env var (comma-separated) plus numbered siblings `<VAR>_1..N`; `post_json_pooled` rotates to the next key on a `RateLimitError` (429 after retries), marking the spent one exhausted. A single key is a pool of one, so existing setups are unchanged. Invisible to the loop. |
 | **Reasoning-effort run parameter** ✅ | run param | **Done** (`Profile.reasoning`, plumbed through `run` → `complete`). OpenAI gets `reasoning_effort`; Anthropic maps low/medium/high to an extended-thinking budget (capped under `max_tokens`); local omits it (arbitrary endpoints may reject it); others ignore it. |
 | **Model router for auxiliary work** | config | Generalize today's single `summarizer_model` into named roles (summarize / judge / classify-risk) so compaction, evals, and `smart` approval can each pick a cheap model. *(Deferred — separate `summarizer_model` / `judge_model` / `approval_judge_model` already exist; unifying them is a refactor, not new capability.)* |
-| **More first-class adapters** | provider | The OpenAI-compatible `local` adapter already covers many endpoints; add thin named adapters (Gemini, OpenRouter, DeepSeek) only where the wire shape genuinely differs. *(Deferred — `local` covers OpenAI-compatible endpoints today.)* |
+| **More first-class adapters** ✅ | provider | **Done** (`providers/compat.py`: `OpenRouterProvider`, `DeepSeekProvider`, `GeminiProvider`). All three speak the OpenAI shape, so each is a thin `OpenAIProvider` subclass pinning a default `base_url`, `*_API_KEY` env var, and capability (Gemini/OpenRouter multimodal; DeepSeek text-only) — no new wire translation. Wired into `make_provider` (`provider = "openrouter"|"deepseek"|"gemini"`), `base_url` still overridable. |
 
-### 18.6 Multimodality
+### 18.6 Multimodality — ✅ done
 
 | Idea | Seam | Notes |
 |---|---|---|
-| **Image input in canonical messages** | canonical types | Extend `Message.content` to allow typed content parts (text + image refs) and teach each adapter to translate them. The biggest single change here — it touches §4 types and every adapter — but still not the loop. Gate behind a capability flag so text-only providers are unaffected. |
+| **Image input in canonical messages** ✅ | canonical types | **Done** (`types.ImageContent`, `Message.images`). Images ride alongside `Message.content` as typed parts (rather than turning `content` into a union, so every existing `m.content` reader is untouched). Each adapter translates them: Anthropic `image` blocks (base64/url `source`), OpenAI/local `image_url` content parts (data-URI or url). Gated by `Provider.supports_images` — Anthropic/OpenAI `True`, `local` opt-in via `local_supports_images` for vision endpoints — so a text-only provider silently drops images instead of breaking. `ImageContent.from_path`/`from_url`, a flat per-image token charge in the estimator (§9.1), and `agentkernel run --image PATH_OR_URL` (repeatable; warns if the provider can't accept images). Loop untouched. |
 
 ### 18.7 Observability & DX — ✅ done (completions deferred)
 
@@ -627,7 +627,7 @@ within each group is rough priority. Nothing here is committed.
 | **`insights` command** ✅ | reads telemetry | **Done** (`insights.py`, `agentkernel insights [--days N]`). Aggregates the JSONL traces into sessions/turns/tokens/cost, a per-model breakdown, and tool-frequency with error counts — pure reading of the stable §12 schema, offline. |
 | **`doctor` command** ✅ | standalone | **Done** (`doctor.py`, `agentkernel doctor`). Network-free checks: Python version, required deps, provider credentials, sandbox (docker CLI), embedding key for semantic search, curses on Windows, writable log dir. Exits non-zero on any failure. |
 | **Plugin discovery seam** ✅ | tool registration | **Done** (`plugins.py`, `enable_plugins`/`plugins_dir`). Auto-imports `plugins/*.py` exposing `tools()` or `TOOLS`; each spec registers like a builtin. A bad plugin is reported, not fatal. Opt-in because importing executes code. |
-| **Shell completions** | CLI | Deferred — `agentkernel completion bash`/`zsh`. Trivial DX polish, low priority. |
+| **Shell completions** ✅ | CLI | **Done** (`run_completion`, `agentkernel completion bash|zsh|fish`). Emits a static completion script that completes the subcommand at the first position and defers to file completion after; the command list is read from the live argparse subparsers so it never drifts from the real commands. |
 
 ### 18.8 Bundled content & templates (assets, not engine work) — ✅ done
 
@@ -654,7 +654,7 @@ future work.
 | **A starter loops library** | external driver | Like skills and profiles, the loop runner (`loops.py`, `agentkernel loop`) is built and tested but ships only one example (`examples/loops/until-tests-pass.toml`). Add a curated `loops/` set following action → check → iterate → stop, each with a sandboxed `success_check` and/or `success_streak`: `until-tests-pass` (promote the example), `until-lint-clean`, `until-typecheck-clean`, `until-build-succeeds`, `review-and-fix` (run a review, apply fixes, repeat until clean). Pure TOML over the existing runner — no engine change. |
 | **Reusable templates** | DX / scaffolding | A `templates/` directory of annotated skeletons for the things users author repeatedly: `SKILL.md`, a profile TOML, an eval suite, a loop TOML, an `[[mcp_servers]]` block, and a builtin-style tool module. Each is a copy-paste starting point with inline comments explaining every field. |
 | **`new` scaffolding command** | CLI / DX | `agentkernel new skill <name>` / `new profile <name>` / `new eval <name>` / `new loop <name>` copies the matching template into place with the name filled in. Turns the templates above into a one-liner; pure file generation, no loop involvement. |
-| **A shareable bundle format** | packaging | Optional: a convention for packaging a skill (its `SKILL.md` + bundled files) as a single archive so skills can be shared/installed between projects, mirroring how MCP servers are declared once and reused. Only worth doing once the library above exists and people want to trade skills. |
+| **A shareable bundle format** ✅ | packaging | **Done** (`skills.pack_skill`/`install_skill`, `agentkernel skill pack/install/list`). A bundle is just a zip with `SKILL.md` (+ any resources) at the root — the same folder shape `SkillLibrary` discovers, so a packed skill installs straight back with no manifest format to learn. Install names the directory from the skill's own frontmatter `name` (robust to a renamed archive) and rejects unsafe members (absolute/`..` paths) and any zip lacking a root `SKILL.md`. |
 
 ### 18.9 Explicitly out of the kernel (separate packages)
 

{agentkernel_cli-0.1.0 → agentkernel_cli-0.2.0}/agentkernel/agent.py

@@ -67,13 +67,15 @@ class Agent:
         *,
         profile: Any | None = None,
         on_text: Any | None = None,
+        images: Any | None = None,
     ) -> str:
         """Drive the loop until a final answer or the max-iteration guard.
 
         ``profile`` (design §13, Phase 5) is accepted but, in the kernel, only
         ``tool_filter`` / ``system_prompt`` are honored if trivially present.
         ``on_text`` (when set) receives streamed text deltas; the loop contract is
-        otherwise unchanged.
+        otherwise unchanged. ``images`` (a list of ``ImageContent``) attaches to
+        the user turn; adapters that can't accept images ignore them (§18.6).
         """
         session_id = getattr(self.telemetry, "session_id", str(uuid.uuid4()))
 
@@ -84,7 +86,11 @@ class Agent:
                 self.context.add(message)
 
         self.context.add(
-            Message(role="user", content=self._prepare_user_message(user_input))
+            Message(
+                role="user",
+                content=self._prepare_user_message(user_input),
+                images=list(images) if images else [],
+            )
         )
 
         # Assemble the cacheable prefix ONCE per run and reuse the same objects