amp_sdk

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.6.0] - 2026-07-13

### Added

- Added governed Amp launch support through an explicit authority object for
  command, session, and non-auth management command execution.
- Added governed launch tests proving authority-only command/cwd/env use and
  fail-closed rejection of native config, permissions, MCP OAuth, and env
  smuggling.
- Added an SDK-direct promotion fixture and provider behavior manifest for
  proving Amp-native flags, settings, management commands, and local execution
  surfaces without importing ASM.
- Added deterministic bounded scanners and error-kind normalization for
  environment keys, thread tables, management payloads, and provider errors.
- Added package-aware dependency source selection with a Hex-only publish mode
  and a release boundary test that forbids dependencies on ASM and sibling
  provider SDKs.

### Changed

- Restricted the Hex archive to consumer-facing source, guides, examples, and
  public documentation/assets, with a consistent 200px README presentation.
- Raised the minimum Elixir version to 1.19 and moved the shared runtime
  dependency to `cli_subprocess_core ~> 0.2.0`; updated Zoi to the 0.18 line.
- Command execution, sessions, process exits, transport errors, provider model
  policy, and execution surfaces now use `CliSubprocessCore` facades. The SDK
  continues to project those shared mechanics into Amp-native messages and
  error values rather than exposing raw Execution Plane modules.
- `AmpSdk.run/2`, `AmpSdk.execute/2`, management functions, public option and
  message structs, and Amp-native permission/MCP/thread APIs retain their 0.5
  entry points. The new governed authority option is additive.
- Provider behavior environment values are no longer inherited ambiently by
  runtime code. Applications must materialize OS environment values at a
  configuration boundary and pass them through `Options.env`, the `:amp_sdk`
  `:base_env` setting, or the shared provider CLI configuration.
- Error kind normalization, thread table parsing, env key validation, permission
  list parsing, and MCP list parsing now use bounded literal handling and
  deterministic scanners.
- Amp CLI native login, `AMP_*` env keys, settings files, permissions config,
  and MCP OAuth state remain standalone direct-use behavior only. Governed mode
  requires authority materialization and rejects unmanaged env, native config,
  and OAuth credential options.
- Permission actions and MCP server type/source values are validated against
  the known Amp contract. Unknown MCP status and provider error literals are
  preserved as diagnostic data while projecting to bounded `"unknown"`/`:unknown`
  values.

### Fixed

- Tightened command exit, timeout, retained-stderr, remote CLI, cwd, stream
  cleanup, and error translation behavior on the shared core 0.2 runtime.
- Preserved forward-compatible `extra` fields in typed management and message
  projections while rejecting invalid known discriminator fields.
- Removed pattern-engine examples from tests and guides in favor of fixed
  string checks.

### Removed

- Removed the SDK's residual direct dependency and test adapter for
  `external_runtime_transport`; execution transport remains owned by
  `cli_subprocess_core`.

See [Migrating to 0.6](guides/migrating-to-0.6.md) for the compatibility audit
and the required environment/dependency changes.

## [0.5.0] - 2026-04-06

### Added

- Session recovery coverage and refreshed example support for the shared
  core-backed execution/runtime model.

### Changed

- Amp discovery, command execution, and streaming now run through
  `cli_subprocess_core`, with shared execution-surface routing and core-owned
  model payload shaping.
- Release docs and package-facing notes now describe the final Phase 4 boundary
  explicitly: `cli_subprocess_core` owns Amp subprocess lifecycle and
  `built-in transport`, while `amp_sdk` stays focused on Amp-specific invocation,
  projection, and management surfaces.
- SSH and nonlocal execution flows now use the shared execution-surface
  contract instead of Amp-local transport naming.

### Fixed

- Management command wrappers, timeout cleanup, and transport error
  normalization were tightened to match current CLI behavior and reduce
  orphaned subprocesses.
- Headless transport cleanup, idle shutdown, and bounded stdout drain behavior
  now behave deterministically under unattended execution.

## [0.4.0] - 2026-02-11

### Added

- Transport `interrupt/1` callback implementation in the Built-in transport transport, allowing cooperative interruption of in-flight subprocess execution.

### Fixed

- Built-in transport line framing now handles UTF-8 text split across chunk boundaries without dropping or corrupting multibyte characters.
- Added transport regression coverage for UTF-8 chunk-boundary decoding and interrupt behavior.

## [0.3.0] - 2026-02-11

### Removed

- Legacy exception module `AmpSdk.Errors` and its specialized exception types.
- Legacy defaults/accessors tied to removed exceptions.
- Legacy transport subscription shape (`:legacy` tag + `subscribe/2`) in favor of reference-tagged transport events only.
- Raw management list APIs:
  - `AmpSdk.threads_list_raw` (arity 1)
  - `AmpSdk.permissions_list_raw` (arity 1)
  - `AmpSdk.mcp_list_raw` (arity 1)
  - `AmpSdk.Threads.list_raw` (arity 1)
  - `AmpSdk.Permissions.list_raw` (arity 1)
  - `AmpSdk.MCP.list_raw` (arity 1)
- Management struct passthrough `raw` fields:
  - `AmpSdk.Types.ThreadSummary.raw`
  - `AmpSdk.Types.PermissionRule.raw`
  - `AmpSdk.Types.MCPServer.raw`
- Legacy Node.js `require.resolve` CLI discovery fallback and probe-timeout default.

### Changed

- `AmpSdk.Config.fetch_option` (arity 3) and `read_option` (arity 3) now read atom keys only for map inputs.
- MCP constructor map/keyword inputs now expect atom keys for options; string keys in those maps are ignored.
- Permissions and MCP typed list parsing now uses direct string-key access from decoded CLI JSON.
- Docs/guides/examples now reflect strict typed APIs and legacy removals.

## [0.2.0] - 2026-02-07

### Added

- Typed management models for list-style APIs:
  - `AmpSdk.Types.ThreadSummary`
  - `AmpSdk.Types.PermissionRule`
  - `AmpSdk.Types.MCPServer`
- Raw output accessors for callers that still need plain CLI output:
  - `AmpSdk.threads_list_raw` (arity 1)
  - `AmpSdk.permissions_list_raw` (arity 1)
  - `AmpSdk.mcp_list_raw` (arity 1)

### Changed

- `threads_list/1` now returns `{:ok, [%AmpSdk.Types.ThreadSummary{}]}` instead of raw table text.
- `permissions_list/1` now requests CLI JSON and returns typed `%AmpSdk.Types.PermissionRule{}` entries.
- `mcp_list/1` now requests CLI JSON and returns typed `%AmpSdk.Types.MCPServer{}` entries.
- `threads_list/1`, `permissions_list/1`, and `mcp_list/1` now accept keyword opts, with zero-arity wrappers preserved via defaults.
- Documentation, guides, and examples now use typed list APIs as the primary path.

### Fixed

- Downstream consumers no longer need to call list functions and then parse/`length` raw CLI table strings for management data.

## [0.1.0] - 2025-02-07

### Added

- Initial public release of `amp_sdk` for Elixir with full Amp CLI coverage.
- Public facade (`AmpSdk`) exposing 37 API functions across:
  - Execution: `execute/2`, `run/2`, `create_user_message/1`, `create_permission/3`
  - Threads: `threads_new/1`, `threads_list/0`, `threads_search/2`, `threads_markdown/1`, `threads_share/2`, `threads_rename/2`, `threads_archive/1`, `threads_delete/1`, `threads_handoff/1`, `threads_replay/1`
  - Tools: `tools_list/0`, `tools_show/1`, `tools_use/2`, `tools_make/1`
  - Tasks: `tasks_list/0`, `tasks_import/1`
  - Review: `review/1`
  - Skills: `skills_add/1`, `skills_list/0`, `skills_remove/1`, `skills_info/1`
  - Permissions: `permissions_list/0`, `permissions_test/2`, `permissions_add/3`
  - MCP: `mcp_add/3`, `mcp_list/0`, `mcp_remove/1`, `mcp_doctor/0`, `mcp_approve/1`, `mcp_oauth_login/2`, `mcp_oauth_logout/1`, `mcp_oauth_status/1`
  - Usage: `usage/0`
- Streaming engine (`AmpSdk.Stream`) built on `Stream.resource/3` with typed message parsing.
- Transport layer (`AmpSdk.Transport` + `AmpSdk.Transport`) for subprocess lifecycle, I/O, and cleanup.
- Command stack with CLI discovery plus internal synchronous command execution and shared wrapper routing.
- Complete types system (`AmpSdk.Types`) including stream messages, content blocks, permission/MCP structs, and options.
- Unified error envelope (`AmpSdk.Error`) with legacy exception modules kept in `AmpSdk.Errors`.
- Settings file merge support for inline permissions and custom skills paths.
- Documentation set:
  - Root README
  - 8 guides in `guides/`
  - 28 runnable examples in `examples/` plus `examples/run_all.sh`
- Test coverage:
  - 177 tests total (including live tests tagged `:live`, excluded by default)

### Changed

- Internal process `:DOWN` waiting logic is now shared through a common helper module to reduce duplicated monitor wait code across async/command/stream paths.

### Fixed

- Stream cleanup now drains pending `{:amp_sdk_transport, ref, event}` messages for the finished stream reference, preventing mailbox residue in long-lived caller processes.
- Command collection now flushes trailing built-in transport `stdout`/`stderr`/`DOWN` messages on the normal `:DOWN` completion path (not only timeout/stop paths).
- `AmpSdk.Transport` safe-call path now runs through supervised tasks (`AmpSdk.TaskSupervisor`) instead of unsupervised per-call `spawn_monitor` helpers.
- CLI Node.js package resolution fallback (`require.resolve`) is now bounded by a probe timeout (`2_000ms`) to avoid indefinite `CLI.resolve/0` hangs.
- `AmpSdk.Transport` startup (`start` / `start_link`) now returns consistent tagged transport errors (`{:error, {:transport, reason}}`) on startup/init failures.
- Config/env normalization now drops `nil` entries for string maps, CLI env overrides, and MCP `env`/`headers` constructors instead of coercing them into empty-string values.
- `permissions add` argument order corrected to CLI format: `<action> <tool>`.
- `permissions_add/3` wrapper support added for `--to` and `--workspace`.
- `tools_use/2` no longer forces `stdin: nil` (prevents headless hangs/timeouts when no input is provided).
- `review/1` updated to support global `--dangerously-allow-all` placement before `review`.
- Delegate/signature and wrapper behavior alignment for `threads_share/2` and management command argument construction.
- Internal task spawning now relies on OTP-supervised `AmpSdk.TaskSupervisor` startup (`Application.ensure_all_started/1`) instead of ad-hoc fallback supervisor singletons.
- Internal command timeout/send-failure cleanup now uses stop-then-kill escalation with explicit DOWN confirmation to avoid orphaned subprocesses and mailbox noise.
- Transport shutdown escalation now reports force-close call-timeout errors instead of internally killing the GenServer process.
- Stream cleanup escalation now uses `:shutdown` before `:kill` for transport teardown.
- Async timeout/task-exit paths now return `%AmpSdk.Error{}` (`:task_timeout`, `:task_exit`) consistently.
- Shared defaults/messages and a shared wrapper invocation helper were added to remove duplicated timeout constants and CLI invocation glue.
- Warning cleanup and docs/examples synchronization with current CLI behavior.
- Transport `safe_call/3` now isolates `GenServer.call/3` in a monitored helper process so timeout/error handling is contained and deterministic.
- Headless `AmpSdk.Transport` instances now support idle auto-shutdown (`:headless_timeout_ms`, default `5_000`) to avoid orphaned subprocesses when no subscriber is attached.
- Exit finalization now drains stdout in bounded batches instead of unbounded single-callback loops.
- Config option reading now uses `fetch_option/3` conflict detection and raises `%AmpSdk.Error{kind: :invalid_configuration}` on atom/string key conflicts.
- Low-level transport errors can now be normalized with `AmpSdk.Transport.error_to_error/2`.
- Timeout defaults are now centralized in the internal defaults module and reused by review/stream/transport paths.

[Unreleased]: https://github.com/nshkrdotcom/amp_sdk/compare/v0.6.0...HEAD
[0.6.0]: https://github.com/nshkrdotcom/amp_sdk/compare/v0.5.0...v0.6.0
[0.5.0]: https://github.com/nshkrdotcom/amp_sdk/compare/v0.4.0...v0.5.0
[0.4.0]: https://github.com/nshkrdotcom/amp_sdk/compare/v0.3.0...v0.4.0
[0.3.0]: https://github.com/nshkrdotcom/amp_sdk/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/nshkrdotcom/amp_sdk/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/nshkrdotcom/amp_sdk/releases/tag/v0.1.0