Changelog

Copy Markdown View Source

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

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 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

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.