antigravity_cli_sdk

<p align="center">
  <img src="assets/antigravity_cli_sdk.svg" alt="AntigravityCliSdk" width="200"/>
</p>

<p align="center">
  <a href="https://github.com/nshkrdotcom/antigravity_cli_sdk"><img src="https://img.shields.io/badge/GitHub-nshkrdotcom%2Fantigravity_cli_sdk-24292e?logo=github" alt="GitHub"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"/></a>
</p>

# AntigravityCliSdk

`AntigravityCliSdk` is the supported Google coding-agent SDK for the
Antigravity CLI (`agy`). It gives Elixir applications a typed streaming API,
a simple synchronous
`run/2`, governed launch checks, and the runtime module consumed by
`agent_session_manager` for the `:antigravity` SDK lane.

The retired `gemini_cli_sdk` is not supported or revived by this package.
`gemini_ex` is a distinct model API SDK and is not a coding-agent CLI runtime.

The SDK does not reimplement subprocess handling. It uses
`cli_subprocess_core`, the same core runtime that powers ASM's common
Antigravity lane.

## Installation

AntigravityCliSdk 0.2.0 requires Elixir 1.19 or later and
`cli_subprocess_core ~> 0.4.0`.

Sibling checkout during local development:

```elixir
def deps do
  [
    {:antigravity_cli_sdk, path: "../antigravity_cli_sdk"}
  ]
end
```

Hex dependency after publish:

```elixir
def deps do
  [
    {:antigravity_cli_sdk, "~> 0.2.0"}
  ]
end
```

## Quickstart

```elixir
{:ok, text} =
  AntigravityCliSdk.run("Reply with exactly: OK", %AntigravityCliSdk.Options{
    dangerously_skip_permissions: true
  })
```

For streaming:

```elixir
"Explain OTP in one sentence."
|> AntigravityCliSdk.execute(%AntigravityCliSdk.Options{})
|> Enum.each(fn
  %AntigravityCliSdk.Types.MessageEvent{content: text} -> IO.write(text)
  %AntigravityCliSdk.Types.ResultEvent{} -> :ok
  %AntigravityCliSdk.Types.ErrorEvent{} = error -> IO.inspect(error)
end)
```

## Configuration

Runtime configuration is explicit:

- `ANTIGRAVITY_CLI_PATH` is translated by `config/runtime.exs` into the app
  config key `:cli_path`.
- `ANTIGRAVITY_MODEL` becomes the app config key `:model`.
- `ANTIGRAVITY_LOG_FILE` becomes the app config key `:log_file`.
- `%AntigravityCliSdk.Options{api_key: value}` becomes
  `ANTIGRAVITY_API_KEY` in the child process environment.

Library modules read application config, not the parent OS environment.

Three independent timeout controls are available:

- `timeout_ms` is the idle wait between stream events;
- `run_deadline_ms` is a non-rearming total run ceiling;
- `transport_headless_timeout_ms` is the bounded orphan-reap window passed to
  the Core transport.

`completion_only: true` and non-nil `output_schema` are explicit common
intents, but Antigravity currently rejects both with
`AntigravityCliSdk.Error{kind: :unsupported_capability}` before resolving or
starting `agy`.

## Live Example

```bash
mix run examples/simple_stream.exs
```

The example uses the real `agy` binary through `cli_subprocess_core`.
Run the full SDK-owned suite with:

```bash
~/scripts/with_bash_secrets bash examples/run_all.sh
```

See [Examples](examples/README.md) for the full inventory. ASM provider
examples live in `agent_session_manager/examples`.

## Documentation

- [Getting Started](guides/getting-started.md)
- [Options](guides/options.md)
- [Streaming](guides/streaming.md)
- [Sessions](guides/sessions.md)
- [Authentication](guides/authentication.md)
- [Error Handling](guides/error-handling.md)
- [Testing](guides/testing.md)
- [ASM Integration](guides/asm-integration.md)
- [Provider Behavior Manifest](guides/provider-behavior-manifest.md)
- [Architecture](guides/architecture.md)
- [Examples](examples/README.md)