antigravity

Syncs with Python SDK v0.1.18.

Behavior changes

• Default tools. list_directory, search_directory, and find_file are now deprecated and off unless you list them in enabledTools. They are no longer in defaultTools(), readOnly(), nondestructive(), or minimal(). minimal() is now run_command, view_file, create_file, and edit_file.
• schedule is on by default. The new BuiltinTools.schedule tool is part of defaultTools(), readOnly(), and nondestructive(). To turn it off, add it to disabledTools.
• manage_task follows run_command and schedule. The harness enables manage_task whenever either tool is active, for the main agent and for subagents.
• The harness evaluates policies. Local configs now send policies to the harness as policy_config. LocalConnection answers the harness's policy_decision_request for dynamic rules (rules with a when predicate or an askUser decision). Agent no longer registers the client-side enforce() hook for these configs, so each rule is evaluated, and each askUser handler prompts, once per tool call. enforce() still runs when the agent starts, so invalid policies fail early.
• run_command is denied by default. When policies is omitted, LocalAgentConfig, LocalOpenAIAgentConfig, and LiteRTAgentConfig now default to confirmRunCommand(), which denies run_command and allows everything else, as upstream does. Previously the default allowed every tool, including run_command. Pass policies: [allowAll()] to keep the old behavior. An explicit policies: [] stays empty, so the missing-safety-policy check applies again.
• No automatic workspace policy. Local configs no longer add a workspace() rule for each workspace. That rule was a wildcard allow that never denied anything, and on the wire it cost a round trip to the SDK on every tool call. The harness already restricts file tools to the configured workspaces, as upstream does. workspace() is deprecated; use workspaces or workspaceOnly().
• Safer terminal prompts. ToolConfirmationHook and askUserHandler strip ANSI escape sequences and control characters from tool names, arguments, and reasons before printing them.

Added

• eval() preset on LocalAgentConfig, LocalOpenAIAgentConfig, and LiteRTAgentConfig, for benchmark and evaluation runs. It:

  • disables generate_image and subagents;
  • enables daemon commands (RunCommandConfig(enableDaemons: true));
  • applies allowAll() if you set no policies, and RetryConfig.benchmark() if you set no retry config;
  • on LocalAgentConfig, sets text Gemini and Vertex targets to ThinkingLevel.high. Pass thinkingLevel: null to leave thinking levels unchanged.

  It raises AntigravityValidationException if a text target already sets thinkingLevel, or if a thinking level is requested on LiteRTAgentConfig or LocalOpenAIAgentConfig. Your own enabledTools or disabledTools list replaces the generate_image denylist. Dart can't tell an explicit enableSubagents: true from the default, so subagents are always disabled. The default confirmRunCommand() rules don't count as policies you set, so eval() replaces them.

• Auto policy mode. auto({name, handler, model}) returns an AutoPolicy, sent to the harness as policy_config.auto_config. The harness's safety assessor checks risky tool calls. Without a handler, flagged calls are denied; with one, you're asked to confirm. Only one auto() rule is allowed. runInteractiveLoop gives an auto() rule without a handler the terminal askUserHandler.

• Policy reasons. deny() and askUser() accept reason. It's sent as the rule's deny_reason, and it's the denial message and the reason passed to handlers.

• Reasons for ask-user handlers. Handlers can take an optional reason, either positional ((tc, [String? reason])) or named ((tc, {String reason = ''})), to get the runtime's explanation, such as an auto-mode safety assessment. One-argument handlers still work. executeAskUser is exported for custom integrations.

• SubagentConfig.model. A model name for one subagent, sent as custom_subagents[].model.name. Subagents still use the agent-level endpoint.

• AgentConfig.evaluatesPoliciesInHarness. True for the local configs. Custom AgentConfig subclasses default to false and keep client-side enforce().

• BuiltinTools.deprecated() returns the three directory tools.

Changed

• safeDefaults() and the write-tool safety check treat the deprecated directory tools as read-only, as upstream does.
• HarnessDownloader.defaultVersion is 0.1.18.
• Raised minimum dependency versions: dart_mappable ^4.10.0, mcp_dart ^2.4.2, and meta ^1.19.0. Dev dependencies: test ^1.32.0, build_runner ^2.16.1, and dart_mappable_builder ^4.10.0.

Not ported

• The v0.1.18 release notes also list JSON schema normalization, ToolRunner coercion changes, the removal of modified_arguments_json, and a service-tier ingestion fix. None of those files changed between v0.1.17 and v0.1.18. Dart already parses unknown service tiers as ServiceTier.standard.
• SpeechAnnotation, Environment.StorageQuota, the ExternalClientEvent rename, and the SystemInstructionTemplate restructure are proto-only and don't change SDK behavior.
• Upstream LiteRTAgentConfig applies the lightweight preset automatically, and has since v0.1.17. The Dart config doesn't; call lightweight() yourself.

• Sync with Python SDK v0.1.17:
  • Simplified CompactionConfig to the validated tokenThreshold field, retaining the deprecated checkpointIntervalTokens getter for source compatibility.
  • Added ToolOutputTruncationConfig, SandboxStatus, UsageMetadata scalar multiplication, and BuiltinTools.defaultTools().
  • Updated generated mappers, harness serialization, documentation, and compatibility tests for the new wire shapes.

• Sync with Python SDK v0.1.16:
  • Context Compaction Policy (CompactionConfig):
    • Added CompactionConfig in types/compaction.dart, exposing checkpointIntervalTokens (tokens of history per compaction checkpoint) and maxContextTokens (hard context-window ceiling), with validation that both are positive and that checkpointIntervalTokens <= maxContextTokens.
    • Retained the deprecated compactionThreshold alias, which maps to checkpoint_interval_tokens on the wire and raises on conflicting values.
    • Added AgentConfig.compactionConfig and AgentConfig.effectiveCompactionConfig, which resolves the legacy CapabilitiesConfig.compactionThreshold when no CompactionConfig is set.
    • Emitted compaction_config over the wire (alongside the legacy compaction_threshold) and deprecated CapabilitiesConfig.compactionThreshold, which now also rejects non-positive values (matching the upstream gt=0 constraint).
  • Lightweight Configuration Preset (lightweight()):
    • Added AgentConfig.lightweight(), implemented on LocalAgentConfig, LocalOpenAIAgentConfig, and LiteRTAgentConfig with covariant return types. It returns a copy restricted to BuiltinTools.minimal(), with AgentBehavior.minimal, subagents disabled, and a 64 Ki-token compaction checkpoint interval (AgentConfig.lightweightCheckpointIntervalTokens).
    • The presets act as defaults rather than a wholesale replacement, mirroring upstream: a caller-provided enabledTools allowlist wins, a caller-provided disabledTools list is subtracted from BuiltinTools.minimal(), and runCommandConfig, finishToolSchemaJson, and compactionConfig are carried over. Resolution lives in the shared AgentConfig.lightweightCapabilities() and AgentConfig.lightweightCompactionConfig() helpers.
    • Divergence from Python: agentBehavior and enableSubagents always take the preset, because Dart cannot distinguish an explicitly-set value from a default on a non-nullable field (Pydantic's model_fields_set has no equivalent). Subagent scoping (maxSubagentDepth, allowedSubagents) is intentionally dropped, since CapabilitiesConfig rejects both once subagents are disabled.
    • Added BuiltinTools.minimal() (run_command, view_file, create_file, edit_file, list_directory, search_directory) and the AgentBehavior.minimal variant (AGENT_BEHAVIOR_MINIMAL on the wire).
  • Budget Scope (BudgetScope):
    • Added the BudgetScope enum (LIFETIME, FORWARD_LOOKING) and BudgetConfig.scope (defaults to BudgetScope.lifetime), letting a resumed session budget only the calls and tokens made from that point onwards.
    • budget_config is now emitted only when at least one limit is set, and always carries an explicit scope.
  • Terminal Command Sandbox on the Wire:
    • enable_sandbox is now emitted in the harness_side_tools.run_command proto, so RunCommandConfig.enableSandbox reaches the harness.
  • LiteRT Context Ceiling Consolidation:
    • Deprecated LiteRTAgentConfig.maxContextTokens in favour of compactionConfig.maxContextTokens, mirroring upstream's removal of the standalone field. LiteRTAgentConfig.effectiveCompactionConfig folds the legacy value into the shared compaction policy and effectiveMaxContextTokens exposes the resolved ceiling, so the LiteRT runner and the harness now read one source of truth. Dart keeps the field deprecated rather than removing it outright, matching how compactionThreshold is handled.
    • All three local configs now hand effectiveCompactionConfig to their strategy, matching upstream; the strategy retains its own capability fallback for directly-constructed strategies.
  • Conversation History Seeding:
    • Conversation (and Conversation.create) now accept history to pre-seed steps and maxHistorySize as a constructor parameter; compaction indices and cumulative usage are computed over the combined history. (history already existed upstream in v0.1.15 and was only documented in v0.1.16; it was previously missing in Dart.)
  • Step Usage Metadata Deprecation:
    • Deprecated Step.usageMetadata in favour of ChatResponse.usageMetadata for per-turn usage and Conversation.cumulativeUsage for the session total. The field remains on the wire and is still read internally.
  • Default Model:
    • Updated defaultModel to gemini-3.8-flash.
  • Harness Downloader Default Version:
    • Updated default upstream localharness binary download version in HarnessDownloader to 0.1.16.
  • Not ported (no Dart counterpart):
    • Upstream's ToolRunner support for callable-class and dataclass tools relies on Python reflection (typing.get_type_hints over __call__); Dart tools are explicit Tool(name:, schema:, handler:) values with nothing to introspect.
    • Upstream's new struct_converter and the dependent event_processor branch convert genai.Content and proto-message tool results into google.protobuf.Struct. Dart has no genai dependency and tool results are plain Dart values, so the existing media extraction path already covers this.
    • Vertex AI Express Mode (vertex: true with apiKey) already shipped in Dart 0.10.0.
  • Examples:
    • Added example/getting_started/compaction.dart, example/getting_started/sandboxing.dart, and example/getting_started/vertex.dart (Express and Standard Vertex AI modes, configured via Platform.environment rather than an argument parser, matching existing Dart examples).
    • Added a BudgetScope.forwardLooking session-resume demo to example/getting_started/budget_limits.dart.
    • example/getting_started/subagents.dart now relies on subagents being enabled by default and exposes example/resources/ as the workspace for all three demos, replacing the temporary directories and synthetic target_code.dart / design.md / perf_data.txt fixtures. The static reviewer audits the bundled mcp_server.dart, and the nested hierarchy fact-checks mcp_server.dart and sample_doc.txt.

• Sync with Python SDK v0.1.15:
  • Stop Lifecycle Hook (StopHook):
    • Added StopHook, StopDecision, StopHookResult, and StopArgs for intercepting turn completion when the agent reaches idle.
    • Enables inspecting the assistant's final response and deciding whether to allow the turn to finish (StopDecision.allowStop) or continue execution (StopDecision.continueTurn) with an injected feedback system prompt.
    • Added HookRunner.dispatchStop and wired LIFECYCLE_HOOK_STOP through HookRouter, preserving turn context across continuation cycles.
    • Followed Dart language heuristics: mapped Python StopDecision.CONTINUE to StopDecision.continueTurn (since continue is a reserved control flow keyword in Dart) while maintaining exact wire compatibility (CONTINUE on the wire, supporting both prefixed and bare values).
  • Terminal Command Sandbox Configuration (enableSandbox):
    • Added enableSandbox property to RunCommandConfig (defaults to false).
    • Propagated enable_sandbox into localharness harness_side_tools.run_command configuration over the wire, allowing opt-in execution within OS-level sandboxing (exebox).
  • Universal JSON Schema Normalization (normalizeSchema):
    • Added normalizeSchema in schema_utils.dart to canonicalize custom tool input schemas before wire transmission.
    • Recursively normalizes uppercase type names (STRING, OBJECT, etc.) to standard lowercase OpenAPI/JSON Schema strings (string, object), converts snake_case combiners and attributes (any_of, additional_properties, etc.) to camelCase (anyOf, additionalProperties), and preserves literal constraints (enum, const, default).
    • Eliminates HTTP 400 Bad Request schema validation errors when targeting local OpenAI-compatible inference endpoints (Ollama, LM Studio, vLLM).
  • Tool Execution Metadata Preservation:
    • Added serverName to ToolResult and preserved id, callId, stepId, and serverName across all ToolResult executions, error handlers, and internal SDK fallback responses.
  • Interactive CLI Execution Behavior:
    • Updated runInteractiveLoop in interactive.dart to ensure capabilities.agentBehavior is explicitly set to AgentBehavior.interactive.
  • Harness Downloader Default Version:
    • Updated default upstream localharness binary download version in HarnessDownloader to 0.1.15.

Release v0.9.2 - Fix RetryConfig proto serialization, subagent tool n…

• Critical Bug Fixes for Local Harness Execution:
  • Trajectory Idle State Recognition: Added support for STATE_FULLY_IDLE (and FULLY_IDLE) in LocalConnection trajectory state updates, properly emitting the idle_sentinel step and preventing agent.chat() / response.text() from hanging at turn completion.
  • Tool Authorization Handshake: Added handler for LIFECYCLE_HOOK_PRE_TOOL / PRE_TOOL in HookRouter, returning valid pre_tool_result decisions (ALLOW / DENY) to the harness and resolving tool execution deadlocks.
  • Wire Path Normalization: Added wire-format URI normalization (file:///, cns://) for tool call arguments in HookRouter to support path-based safety policies and canonical workspace containment.

Release v0.9.0 - Sync Python SDK v0.1.11 features, budget limits, sub…

• Sync with Python SDK v0.1.10 & Dart-Idiomatic Enhancements:
  • Breaking API Change: Conversation.lastTurnUsage signature updated to UsageMetadata? (matching Python SDK v0.1.10) to return null when no token usage was recorded during a turn.
  • Gemini Prioritized Inference (ServiceTier): Introduced ServiceTier enum (standard, priority, flex) and support in GeminiModelOptions and UsageMetadata to configure high-priority model execution with automated fallback.
  • Live Token Usage Updates: Added support for live UsageUpdate event streaming over WebSockets, accumulating per-trajectory token usage live during execution. Added subtraction (-) operator support to UsageMetadata.
  • Agent Execution Modes (AgentMode): Introduced AgentMode enum (autonomous, interactive) in CapabilitiesConfig and SubagentCapabilities with interactive tool validation warnings (BuiltinTools.askQuestion).
  • Interactive CLI Spinner: Updated interactive CLI step spinner formatting (formatStepSpinnerMessage) to display all active tool names during concurrent tool calls (e.g. Running tools 'tool_a', 'tool_b'...).
  • Tool Call Correlation ID: Added callId correlation support across ToolCall, ToolResult, ToolExecutionException, and lifecycle hook payloads.
  • Flexible Context-Aware Lifecycle Hooks: Added .stateless() factory constructors to FunctionInspectHook, FunctionDecideHook, and FunctionTransformHook to seamlessly support both (data) and (context, data) callback signatures.
  • ActionCompaction Handling: Emits context window compaction events over WebSockets and dispatches registered OnCompactionHook handlers.
  • Standardized System Instructions Strategy: Plain string instructions default to an appended system instruction strategy, while CustomSystemInstructions completely replaces built-in instructions.
  • LiteRT Token Output Limit: Increased LiteRT default maxOutputTokens from 8192 to 16,384 tokens to prevent truncation during complex generation.

Release v0.7.0 - Sync Python SDK v0.1.9 updates and Dart-idiomatic SD…

Release v0.6.0: Sync Python SDK v0.1.8 updates

• Sync with Python SDK v0.1.7:
  • Hierarchical Thread-Safe State Management: Introduced the StateStore class for hierarchical context state sharing and lock/reentrancy support. Retargeted HookContext and ToolContext to inherit from StateStore.
  • Session Continuation Modes: Implemented SessionContinuationMode to specify continuation behavior (RESUME, CREATE_OR_RESUME, CREATE_ONLY, SESSION_CONTINUATION_MODE_UNSPECIFIED) with validation checks on AgentConfig.
  • Dynamic Environment Hydration: Hydrates Vertex project and location parameters automatically from standard GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION environment variables when not explicitly passed, and enables Vertex mode automatically when GOOGLE_GENAI_USE_VERTEXAI or GOOGLE_GENAI_USE_ENTERPRISE is set.
  • Websocket Retry Backoff & DNS Resolution: Refactored websocket connections in LocalConnectionStrategy to retry on both localhost and 127.0.0.1 to ensure reliable connections in containerized sandboxes.
  • Spinner Pause/Resume: Enhanced CLI Spinner with pause and resume behaviors, and integrated them into user confirmation/question hooks to prevent prompt clobbering.
  • Custom Tool Execution Support: Added custom_tool parsing support in Step.fromMap and filtered out tool calls from StepUpdate if they are local custom tools to prevent client duplicate events.
  • Addition Operator for Token Usage: Implemented + addition operator on UsageMetadata for clean accumulation of token usage.
  • Updated default image generation model to 'gemini-3.1-flash-lite-image'.
  • Added ThinkingLevel.extraHigh ('extra_high') level support.

chore: bump version to 0.4.1 and apply post-release bug fixes & docum…

feat: sync Python SDK 0.1.6 updates & add localharness auto-upgrades

chore: bump version to 0.3.1 and update CHANGELOG.md

• Synchronize updates from Python SDK (v0.1.5):
  • Added new read_url_content builtin tool and its ReadUrlContentResult structured output.
  • Added StepType.thinking to enum representation for telemetry tracking.
  • Implemented the HookRouter to process WebSocket-based CallHookRequest turn and tool lifecycle hooks delegated by the harness.
  • Added support for telemetry PreStepHook and PostStepHook inside HookRunner and connection parser.
  • Implemented _StepTracker to prevent duplicate step hooks or non-linear state transitions.
  • Supported error and cancelled propagation in trajectory_state_update events.
  • Historical Step Absorption: Aligned startup handshake to await and parse pre-existing conversation history and usage metadata from initialize_conversation_response, populating them immediately in Conversation on start.

• Reintroduce generated files in package

• Model Configuration Overhaul: Replaced the monolithic GeminiConfig with a more flexible ModelTarget and polymorphic ModelEndpoint class hierarchy (GeminiAPIEndpoint, VertexEndpoint).
• Subagents Feature: Introduced SubagentConfig and SubagentCapabilities allowing definition and inclusion of subagents in the main agent's configuration.
• New Builtin Tools: Added SearchWeb tool and related SearchWebResult structured output.
• Enhanced Configuration: Support for environment variables (env) in McpStdioServer. Removed imageModel from CapabilitiesConfig to favor the new generic model targeting features.