Skip to content

refactor(agents): migrate Gator and generalize reusable runtime support #5723

Open
0 of 1 issue completed

Description

@purp

User Story

As an OpenShell maintainer developing and reviewing repository automation, I need agents organized consistently and reusable runtime support so new agents do not duplicate Gator's execution machinery.

Description

Cover two phases: migrate Gator to the agreed agent layout, then generalize its reusable runtime without coupling all agents to one execution backend.

1. Gator layout migration

Move Gator's bundle to .agents/agents/gator/ with a root run.sh entry point, supporting tools in bin/, and tests in tests/. Retain the existing Gator name, runtime identities, providers, workflow labels, and review policy; descriptive-noun naming applies to new agents.

Update manifests, build contexts, launch references, test tasks, code ownership, repository guidance, and launch-openshell-gator. Keep shared launcher/harness code separate from the bundle. This phase can land independently of runtime generalization.

2. Reusable agent runtime

Build on Gator's existing separation of agent payload, shared OpenShell launcher/supervisor, and harness adapters:

  • Preserve agent-owned run.* entry points and deterministic preflight. Skip model execution when the agent's own rules say no work is needed.
  • Identify the smallest useful lifecycle/result contract, including completion, waiting, blocking, failure, interruption, and bounded cleanup. Reuse existing contracts where they fit; do not impose watch semantics on one-shot agents.
  • Keep execution-specific machinery in backend adapters. OpenShell owns sandbox provisioning, immutable payloads, supervised cycles, and harness execution; CMA-backed agents use the supported SDK for remote sessions and its retry machinery.
  • Audit shared code for Gator-specific assumptions, including GATOR_* defaults and GitHub/Codex requirements, and keep workflow policy in the Gator bundle.
  • Choose and document a shared runtime location. Extract only demonstrated common behavior; do not require a universal manifest, duplicate SDK session machinery, or force the CMA labeler through Gator's sandbox launcher.

Preserve credential handling, sandbox policy, immutable payload checks, guarded tools, and the independent reviewer boundary throughout both phases.

Context

Definition of Done

  • Gator layout migration is merged, with affected references and explicit regression suites updated.
  • Shared runtime boundaries, location, and invocation/result contracts are documented.
  • Reusable execution code is separated from Gator-specific defaults and policy, with regression coverage for the extracted behavior.
  • Gator runs through the shared OpenShell backend without changing its policy or security boundaries.
  • The pattern accommodates SDK-backed, deterministic-first agents without requiring sandbox execution or a watch loop.
  • Follow-up PRs each close their own scoped issue; this tracker stays open until both phases are complete.

Activity

  1. self-assigned this
    on Nov 18, 2026
  2. purp commented on Nov 19, 2026

    @purp
    CollaboratorAuthor

    🏗️ build-plan

    Phase 1 (#5737): move the existing Gator bundle to .agents/agents/gator/, retaining its name and runtime identities. Add root run.sh delegating to the shared OpenShell launcher; keep shared runtime code in scripts/agents/. Move agent tests to tests/ and update paths, ownership, operator guidance, and explicit regression commands. Open this migration as a draft PR closing #5737, not this tracker.

    Phase 2: generalize demonstrated reusable runtime support as described above, separating lifecycle/result contracts and backend execution from Gator policy. Keep CMA SDK-backed execution independent of the OpenShell sandbox backend. No review-policy, provider-permission, credential, or sandbox-policy changes are intended.

  3. changed the title [-]refactor(agents): migrate Gator to the contributor agent layout[/-] [+]refactor(agents): migrate Gator and generalize reusable runtime support[/+] on Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions