Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/heartbeat-automation-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,17 @@ transport-neutral goal prompt and lets the goal runtime own inner iteration;
see the host integration protocol instead of adapting this recurring
automation contract.

Antigravity App (`--runtime-profile antigravity_app` or `--antigravity_app`)
keeps a fixed resident session patrolling in place rather than relying on
Codex's `automation_update`: bind the conversation's `Conversation ID` /
`ANTIGRAVITY_CONVERSATION_ID` with `bind-agent-thread --with-agy-hooks --execute`
and `sync-global`, perform repository work and `quota should-run` in an isolated
`.worktrees/` git worktree (leaving the primary checkout clean for
`workspace_guard`), and suspend between wakes via in-session
`schedule(DurationSeconds=max(180, interval * 60), TimerCondition="any", Prompt=...)`
(`180`s minimum floor; `3 -> 6 -> 10` minute unchanged backoff; no shell `sleep`,
and no `new-conversation` `sidecar.json` unless explicitly requested).

### Native Goal bootstrap and live execution instructions

Full, compact and brief automation use the same fully qualified notification/execution rule
Expand Down
73 changes: 50 additions & 23 deletions loopx/agy_goal_mode/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
AGY_INSTALL_SURFACE = "agy"
ANTIGRAVITY_APP_INSTALL_SURFACE = "antigravity-app"
ANTIGRAVITY_APP_AGENT_TYPE = "antigravity-app"
ANTIGRAVITY_CONVERSATION_ID_ENV = "ANTIGRAVITY_CONVERSATION_ID"

# Every token normalize_agent_type and the slash-commands installer accept for
# the Antigravity CLI surface.
Expand Down Expand Up @@ -59,17 +60,22 @@
"`IsDaemon`, `ExactTiming`) that delivers its `Prompt` as a high-priority "
"wakeup notification when it fires; `manage_task` lists or kills active "
"schedules.",
"When a LoopX turn enters `waiting_external` (for example CI checks or PR "
"review waits), call `schedule(DurationSeconds=<poll_after_seconds>, "
"Prompt=...)` and end the turn immediately so the host wakes the session "
"reactively instead of running shell sleep polling loops.",
"In an Antigravity App fixed resident session (`antigravity-app`), arm "
"`schedule(DurationSeconds=max(180, recommended_interval_minutes * 60), "
"TimerCondition=\"any\", Prompt=...)` (3-minute / 180s minimum floor; "
"unchanged-wait backoff `3 -> 6 -> 10` minutes) before ending every patrol "
"turn (including `waiting_external`, CI/PR waits, settled turns, or quiet "
"no-ops) unless `scheduler_hint.action=stop_until_explicit_resume`, so the "
"host wakes the same conversation reactively instead of running shell sleep "
"polling loops or spawning `new-conversation` sidecars.",
"Background `run_command` tasks and `invoke_subagent` runs also resume the "
"session reactively on completion or message arrival, so the agent does "
"not need a polling loop inside a turn.",
"All native wakes live inside the running Antigravity process; for "
"background periodic heartbeats in Antigravity 2.0 (`antigravity-app`), "
"configure `sidecar.json` and optional `hooks.json` bound Stop recovery in "
"`~/.gemini/config`.",
"For fixed in-session patrols, bind the current `<user_information>` "
"`Conversation ID` (or `$ANTIGRAVITY_CONVERSATION_ID`) via `bind-agent-thread` "
"+ `sync-global` and configure bound `hooks.json` `Stop` recovery in "
"`~/.gemini/config` without creating a `new-conversation` `sidecar.json`; "
"use `sidecar.json` only when explicitly requesting detached fresh-conversation ticks.",
)

# Native goal primitive (built into the agy binary; live-verified on 1.1.18 in
Expand Down Expand Up @@ -97,8 +103,8 @@
ANTIGRAVITY_APP_AGENT_TYPE_CATALOG_ENTRY: dict[str, Any] = {
"display_name": "Antigravity App",
"host_loop": (
"Antigravity App native schedule timer closed loop + optional background "
"sidecar.json heartbeat and hooks.json bound Stop recovery"
"Antigravity App fixed-session in-place schedule timer closed loop + "
"hooks.json bound Stop recovery (or optional detached sidecar.json)"
),
"entry": (
f"the LoopX skill installed in {ANTIGRAVITY_SKILLS_ROOT_LABEL} "
Expand Down Expand Up @@ -262,7 +268,7 @@ def build_antigravity_hooks_template(
resolve_local_executable: bool = True,
) -> dict[str, Any]:
"""Native Stop hook; installation alone never binds an arbitrary chat."""
conversation_id = conversation_id or os.environ.get("ANTIGRAVITY_CONVERSATION_ID")
conversation_id = conversation_id or os.environ.get(ANTIGRAVITY_CONVERSATION_ID_ENV)
args = _antigravity_provider_args(
"stop-hook",
cli_bin=cli_bin,
Expand Down Expand Up @@ -392,30 +398,51 @@ def antigravity_app_activation_extras(
"Prompt": wake_prompt,
"TimerCondition": "any",
},
"min_duration_seconds": 180,
"backoff_progression_minutes": [3, 6, 10],
"when_to_use": (
"Call `schedule(DurationSeconds=..., Prompt=...)` and end the turn "
"whenever `waiting_external`, CI checks, or PR review gates block "
"immediate completion; never use shell sleep loops."
"Before ending every fixed-session patrol turn (after settlement, "
"on `waiting_external`/CI/PR review waits, or when idle/no-op) "
"unless `scheduler_hint.action=stop_until_explicit_resume`, call "
"`schedule(DurationSeconds=max(180, recommended_interval_minutes * 60), "
"TimerCondition=\"any\", Prompt=...)` (`3 -> 6 -> 10` minute "
"unchanged backoff) and end the turn; never use shell sleep loops."
),
},
"fixed_session_patrol_contract": {
"mode": "in_place_resident_session",
"conversation_id_sources": [
"<user_information> Conversation ID",
ANTIGRAVITY_CONVERSATION_ID_ENV,
],
"bind_and_hooks_sync_supported": True,
"detached_sidecar_required": False,
"isolated_worktree_root": ".worktrees/",
"min_duration_seconds": 180,
"backoff_progression_minutes": [3, 6, 10],
},
"sidecar_template": sidecar_template,
"hooks_template": hooks_template,
"missing_host_tool_gate": (
"Antigravity App in-session `schedule(DurationSeconds=...)` timers fire "
"while the app session is active; for unattended background ticks, "
f"configure `sidecar.json` in `{ANTIGRAVITY_SIDECAR_CONFIG_LABEL}` "
f"and optional `hooks.json` in `{ANTIGRAVITY_HOOKS_CONFIG_LABEL}`."
"Antigravity App in-session `schedule(DurationSeconds>=180, "
"TimerCondition=\"any\", Prompt=...)` wakes this exact resident "
"conversation while the app session is active (with bound "
f"`{ANTIGRAVITY_HOOKS_CONFIG_LABEL}` `Stop` recovery for network EOFs); "
"only configure detached `sidecar.json` in "
f"`{ANTIGRAVITY_SIDECAR_CONFIG_LABEL}` when explicitly asked for "
"new-conversation background ticks."
),
},
"extra_activation_steps": [
f"Install or refresh the Antigravity skill and optional MCP/hooks surface (`{cli_bin} slash-commands --install --surface antigravity-app --with-agy-mcp --with-agy-hooks` and `{cli_bin} workflow-skills --install --host-surface antigravity-app`).",
"When a turn enters `waiting_external` or waits on CI/review checks, suspend directly with the native `schedule(DurationSeconds=<poll_after_seconds>, Prompt=...)` tool and end the turn instead of polling in a shell loop.",
f"For background periodic heartbeats, write only `sidecar_template.sidecar_json` to `{ANTIGRAVITY_SIDECAR_CONFIG_LABEL}`. Preserve its existing id, model, permissions and host enable choice. Each fresh native heartbeat loads Core admission before work; do not persist an expanded execution body. Apply the bound `hooks_template` at the top level of hooks.json for bounded transport-error recovery; never wrap it in a `hooks` object.",
"For a fixed resident session, read `<user_information>` `Conversation ID` (or `$ANTIGRAVITY_CONVERSATION_ID`), bind it via `bind-agent-thread --with-agy-hooks --execute` (plus `sync-global`) so `~/.gemini/config/hooks.json` carries the active `loopx` CLI and `--conversation-id`, run peer edits and `quota should-run` inside an isolated `.worktrees/` git worktree, and before ending every turn call `schedule(DurationSeconds=max(180, recommended_interval_minutes * 60), TimerCondition=\"any\", Prompt=...)` (`3 -> 6 -> 10`m backoff; no shell sleep or `new-conversation` sidecar).",
f"Only when explicitly requesting detached new-conversation ticks instead of fixed in-session patrol, write `sidecar_template.sidecar_json` to `{ANTIGRAVITY_SIDECAR_CONFIG_LABEL}` preserving its existing id, model, permissions and host enable choice. Apply bound `hooks_template` at the top level of hooks.json; never wrap it in a `hooks` object.",
],
"host_scheduler_note": (
"use the native `schedule(DurationSeconds=..., Prompt=...)` tool to suspend "
"and wake on `waiting_external` / CI waits, or configure `sidecar.json` for "
"background periodic heartbeats."
"for fixed in-session patrol, call `schedule(DurationSeconds>=180, "
"TimerCondition=\"any\", Prompt=...)` (`3 -> 6 -> 10`m backoff) before "
"ending every turn unless stopped; use `sidecar.json` only for explicit "
"detached new-conversation heartbeats."
),
}

Expand Down
5 changes: 4 additions & 1 deletion loopx/agy_goal_mode/host_runtime.py
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,10 @@ def bootstrap_prompt(args: argparse.Namespace) -> str:
+ "\nFollow task_body only when ok=true, including current scope, stop, "
"settlement and scheduler backoff. Do not replay the failed user request, "
"create another Goal/Agent, or reuse an old Turn receipt. Remain quiet "
"when the fresh user_channel requests no notification."
"when the fresh user_channel requests no notification. Before ending the "
"recovered turn (unless stopped), re-arm in-session "
"schedule(DurationSeconds>=180, TimerCondition='any', Prompt=...) with "
"the current backoff cadence instead of starting a new conversation."
)


Expand Down
1 change: 1 addition & 0 deletions loopx/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -365,6 +365,7 @@ def _main(argv: list[str] | None = None) -> int:
args,
registry_path=registry_path,
allow_missing_registry=not user_supplied_registry(raw_argv),
registry_was_configured=registry_was_configured,
)
if common_command_result is not None:
return common_command_result
Expand Down
3 changes: 3 additions & 0 deletions loopx/cli_commands/_host_thread.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
import argparse
import os

from ..agy_goal_mode import ANTIGRAVITY_CONVERSATION_ID_ENV
from ..kiro_cli_goal_mode import KIRO_CLI_AGENT_TYPE, KIRO_CLI_SESSION_ID_ENV

# Host surface -> the environment variable that host exports for its own
Expand All @@ -17,6 +18,8 @@
"codex-cli-tui": "CODEX_THREAD_ID",
"trae_app": "TRAECLI_THREAD_ID",
"traex-cli": "TRAECLI_THREAD_ID",
"antigravity-app": ANTIGRAVITY_CONVERSATION_ID_ENV,
"agy": ANTIGRAVITY_CONVERSATION_ID_ENV,
KIRO_CLI_AGENT_TYPE: KIRO_CLI_SESSION_ID_ENV,
}

Expand Down
45 changes: 45 additions & 0 deletions loopx/cli_commands/registry_admin.py
Original file line number Diff line number Diff line change
Expand Up @@ -383,6 +383,19 @@ def register_registry_admin_commands(subparsers: argparse._SubParsersAction) ->
bind_thread_parser.add_argument("--host-surface", required=True, help="Host surface such as codex-app.")
bind_thread_parser.add_argument("--agent-id", required=True, help="Already registered public-safe agent id.")
bind_thread_parser.add_argument("--execute", action="store_true", help="Write the binding; otherwise preview only.")
bind_thread_parser.add_argument(
"--with-agy-hooks",
action="store_true",
help="Also preview or atomically write the bound Antigravity Stop recovery hook in hooks.json.",
)
bind_thread_parser.add_argument(
"--agy-home",
help="Antigravity config home for --with-agy-hooks (defaults to AGY_HOME or ~/.gemini/config).",
)
bind_thread_parser.add_argument(
"--cli-bin",
help="LoopX CLI executable path/name recorded in hooks.json when using --with-agy-hooks.",
)

unbind_thread_parser = subparsers.add_parser(
"unbind-agent-thread",
Expand Down Expand Up @@ -631,6 +644,14 @@ def handle_registry_admin_command(

if args.command in {"bind-agent-thread", "unbind-agent-thread"}:
try:
with_agy_hooks = bool(
args.command == "bind-agent-thread"
and getattr(args, "with_agy_hooks", False)
)
if with_agy_hooks and args.host_surface not in {"agy", "antigravity-app"}:
raise ValueError(
"--with-agy-hooks requires --host-surface agy or antigravity-app"
)
global_path = explicit_global_registry(args.runtime_root)
global_goal = _registry_goal(global_path, args.goal_id)
source_registry = global_goal.get("source_registry")
Expand Down Expand Up @@ -691,11 +712,13 @@ def handle_registry_admin_command(
_registry_goal(source_path, args.goal_id),
host_surface=args.host_surface,
thread_id=args.thread_id,
exact_surface=True,
)
global_binding = resolve_thread_agent_binding(
_registry_goal(global_path, args.goal_id),
host_surface=args.host_surface,
thread_id=args.thread_id,
exact_surface=True,
)
if args.command == "bind-agent-thread":
readback_verified = all(
Expand Down Expand Up @@ -724,6 +747,28 @@ def handle_registry_admin_command(
payload["error_kind"] = "thread_agent_binding_readback_failed"
else:
payload["global_sync"] = {"enabled": bool(args.execute), "wrote": False}
if with_agy_hooks:
from ..slash_command_install import sync_antigravity_hooks

cli_bin = (
getattr(args, "cli_bin", None)
or getattr(args, "control_cli_bin", None)
or "loopx"
)
hooks_result = sync_antigravity_hooks(
cli_bin=cli_bin,
agy_home=getattr(args, "agy_home", None),
execute=bool(args.execute and payload.get("ok")),
goal_id=args.goal_id,
agent_id=args.agent_id,
runtime_root=str(global_path.parent),
conversation_id=args.thread_id,
registry=str(source_path),
)
payload["antigravity_hooks"] = hooks_result
if hooks_result["status"].startswith(("blocked_", "skipped_")):
payload["ok"] = False
payload["error_kind"] = hooks_result["status"]
except Exception as exc:
payload = {
"ok": False,
Expand Down
55 changes: 53 additions & 2 deletions loopx/cli_commands/slash_commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

import argparse
from collections.abc import Callable
import os
from pathlib import Path

from ..pi_goal_mode.installation import inspect_pi_installations, render_pi_installation_markdown
from ..slash_command_install import install_slash_commands, render_slash_command_install_markdown
Expand Down Expand Up @@ -132,7 +134,19 @@ def register_slash_commands_command(
parser.add_argument(
"--with-agy-hooks",
action="store_true",
help="Optionally install a disabled Antigravity Stop recovery hook; bind a Goal, Agent and native conversation before enabling it.",
help="Optionally install an Antigravity Stop recovery hook; pass --goal-id, --agent-id, and --conversation-id (or bind via bind-agent-thread --with-agy-hooks) to enable it.",
)
parser.add_argument(
"--goal-id",
help="Optional Goal id bound into the Antigravity Stop recovery hook when using --with-agy-hooks.",
)
parser.add_argument(
"--agent-id",
help="Optional Agent id bound into the Antigravity Stop recovery hook when using --with-agy-hooks.",
)
parser.add_argument(
"--conversation-id",
help="Optional Antigravity Conversation ID bound into the Stop recovery hook when using --with-agy-hooks.",
)
parser.add_argument(
"--opencode-home",
Expand Down Expand Up @@ -161,6 +175,8 @@ def handle_slash_commands_command(
*,
output_format: FormatSelector,
print_payload: PrintPayload,
registry_path: Path | None = None,
registry_was_configured: bool | None = None,
) -> int | None:
if args.command != "slash-commands":
return None
Expand All @@ -173,14 +189,44 @@ def handle_slash_commands_command(
print_payload(payload, output_format(args), render_pi_installation_markdown)
return 0 if payload["ok"] else 1
if args.install or args.uninstall or args.dry_run:
effective_cli_bin = (
args.cli_bin
if args.cli_bin != "loopx"
else (getattr(args, "control_cli_bin", None) or args.cli_bin)
)
agy_goal_id = getattr(args, "goal_id", None)
if registry_was_configured is None:
from ..paths import default_registry_path

raw_reg = getattr(args, "registry", None)
configured_registry = bool(os.environ.get("LOOPX_REGISTRY")) or (
bool(raw_reg) and str(raw_reg) != str(default_registry_path())
)
else:
configured_registry = registry_was_configured
resolved_registry = (
registry_path
if registry_path is not None
else (Path(args.registry).expanduser() if getattr(args, "registry", None) else None)
)
agy_registry = (
str(resolved_registry.resolve())
if agy_goal_id and configured_registry and resolved_registry is not None
else None
)
agy_runtime_root = (
str(Path(args.runtime_root).expanduser().resolve())
if agy_goal_id and getattr(args, "runtime_root", None)
else None
)
payload = install_slash_commands(
execute=bool((args.install or args.uninstall) and not args.dry_run),
uninstall=bool(args.uninstall),
with_goal_bridge=bool(args.with_goal_bridge),
with_agy_mcp=bool(getattr(args, "with_agy_mcp", False)),
with_agy_hooks=bool(getattr(args, "with_agy_hooks", False)),
surfaces=args.surface,
cli_bin=args.cli_bin,
cli_bin=effective_cli_bin,
include_legacy_aliases=not bool(args.no_legacy_aliases),
codex_home=args.codex_home,
claude_home=args.claude_home,
Expand All @@ -189,6 +235,11 @@ def handle_slash_commands_command(
cursor_home=args.cursor_home,
zcode_home=getattr(args, "zcode_home", None),
agy_home=getattr(args, "agy_home", None),
agy_goal_id=agy_goal_id,
agy_agent_id=getattr(args, "agent_id", None),
agy_conversation_id=getattr(args, "conversation_id", None),
agy_runtime_root=agy_runtime_root,
agy_registry=agy_registry,
pi_project=args.pi_project,
pi_scope=args.pi_scope,
)
Expand Down
5 changes: 3 additions & 2 deletions loopx/cli_commands/start_goal.py
Original file line number Diff line number Diff line change
Expand Up @@ -209,8 +209,9 @@ def register_start_goal_command(subparsers: argparse._SubParsersAction) -> None:
"--thread-id",
help=(
"Stable opaque host thread id used to reuse the bound agent lane. "
"Codex App defaults to CODEX_THREAD_ID and Trae App to "
"TRAECLI_THREAD_ID when available."
"Codex App defaults to CODEX_THREAD_ID, Trae App to "
"TRAECLI_THREAD_ID, and Antigravity to ANTIGRAVITY_CONVERSATION_ID "
"(or <user_information> Conversation ID) when available."
),
)
start_goal_parser.add_argument(
Expand Down
Loading
Loading