Skip to content

Agent loop runtime: spec closure, panel stability, and dist plugin-check hardening - #25

Merged
bradvin merged 48 commits into
developfrom
codex/agent-loop-runtime
Feb 27, 2026
Merged

bradvin merged 48 commits into
developfrom
codex/agent-loop-runtime

Conversation

@bradvin

@bradvin bradvin commented Feb 27, 2026

Copy link
Copy Markdown
Owner

Summary

This PR merges the agen-loop-runtime workstream and follow-up fixes to make the runtime, panel polling UX, and packaging checks production-ready.

What changed

  • Implemented agent loop runtime orchestration end-to-end (sessions, runs, runner, transport abstraction, REST handoff).
  • Removed legacy duplicated loop logic and consolidated runtime paths.
  • Added/expanded runtime regression tests and spec coverage tests.
  • Implemented phased gap closures from the findings doc, then removed the findings file after closure.
  • Hardened retry/claim/pause semantics:
    • stale run recovery
    • idempotency race handling
    • paused run continuation attempt accounting
    • lock release and lease safety
  • Enforced and tuned runtime wall-time behavior and per-slice budgets.
  • Improved panel behavior for long-running jobs:
    • in-progress polling flow
    • deduped tool-call updates across polling + terminal results
    • stable progress/event cursor handling
    • suppress noisy per-round-limit tool skip errors
    • thinking/in-progress status UX updates and cadence tuning
    • clear stale in-progress banner after real assistant response
    • refocus textarea after response for faster follow-up typing
  • Fixed history/context sequencing bug where model history could start with non-user content.
  • Persisted terminal assistant result into chat history to prevent replaying prior tool-call batches on new messages.
  • Standardized plugin-check to run against dist artifact in local script and CI flow.
  • Fixed plugin metadata/readme packaging issues for plugin-check compliance.
  • Added plugin-check ignore for known trademarked_term false positive.
  • Resolved remaining PluginCheck.Security.DirectDB.UnescapedDBParameter warnings in store queries using safer prepared identifier patterns and updated wpdb test stubs accordingly.

Validation

  • npm run lint:php
  • ./bin/plugin-check (dist mode)

Latest dist plugin-check run reports no remaining warnings/errors (with trademarked_term ignored per current false-positive policy).

@greptile-apps

greptile-apps Bot commented Feb 27, 2026

Copy link
Copy Markdown

Greptile Summary

This PR implements a production-ready agent loop runtime orchestration system with significant architectural improvements.

Key Changes

  • Runtime Orchestration: Introduced Agent_Runner with Action Scheduler-backed bounded execution, run claiming/leasing, and retry backoff logic
  • Transport Abstraction: Created Agent_Transport interface with Polling_Transport and Null_Transport implementations for event delivery
  • Agent Loop Helper: New Agent_Loop_Helper consolidates loop logic with transport-agnostic turn/slice execution (1538 lines)
  • Chat Helper Refactoring: Removed 821 lines of duplicated loop logic from Chat_Helper, now delegates to runtime orchestration
  • Enhanced Stores: Added idempotency keys, resume cursors, retry tracking, lease management, and fixed all DirectDB.UnescapedDBParameter warnings using %i format specifier
  • REST API Controller: New Agent_Run_Controller handles run lifecycle (create, spawn, enqueue, status, events) with proper validation
  • Panel UX Improvements: Enhanced polling flow with event deduplication, progress messages, terminal status handling, stale banner clearing, and textarea refocus
  • Plugin-Check Hardening: Script now validates dist artifact (clawpress.zip) with trademarked_term ignored per policy
  • Test Coverage: Added comprehensive tests for Agent_Runner, Agent_Loop_Helper, and runtime wpdb stub
  • Documentation: New agent-loop.md and streaming-support.md describe architecture

Impact

The refactoring eliminates duplicated logic, standardizes runtime behavior across trigger types, and provides a stable foundation for async agent execution. DB parameter warnings resolved using safer prepared identifier patterns. Panel behavior improved for long-running jobs with proper progress tracking and stable cursor handling.

Confidence Score: 5/5

  • This PR is safe to merge with high confidence - well-architected runtime refactoring with comprehensive test coverage
  • Score reflects thorough architectural design, comprehensive test coverage for new runtime components, proper security fixes (DB parameter warnings), significant code deduplication (removed 1359 lines while adding 6851 lines of structured runtime code), and validation passing (plugin-check and lint:php). The changes follow WordPress coding standards, maintain backward compatibility through legacy parameter support, and include proper error handling with lease management and retry logic.
  • No files require special attention - all components are well-tested and follow established patterns

Important Files Changed

Filename Overview
includes/class-agent-runner.php New Action Scheduler-backed bounded run executor with proper lease management, retry backoff, and run claiming logic
includes/helpers/class-agent-loop-helper.php New transport-agnostic agent loop runtime implementing turn/slice execution with provider integration and tool calling orchestration
includes/helpers/class-chat-helper.php Major refactoring removing 821 lines of duplicated loop logic, now delegates to Agent_Loop_Helper and runtime orchestration
includes/stores/class-agent-run-store.php Enhanced with idempotency support, resume cursors, retry tracking, and fixed DB parameter warnings using %i format specifier
includes/stores/class-agent-session-store.php Added lease management fields, claim/release operations, and fixed DB parameter warnings using %i format specifier
includes/rest/class-agent-run-controller.php New REST controller for agent run lifecycle (create, spawn, enqueue, status, events) with proper validation and sanitization
src/panel/services/realClient.js Enhanced with run polling logic, event deduplication, progress messages, terminal status handling, and polling timeout
src/panel/Panel.jsx Improved ephemeral status handling, run progress event support, and better clearing of in-progress banners
bin/plugin-check Hardened to run plugin-check against dist artifact (clawpress.zip) with trademarked_term ignored per policy
tests/Unit/AgentRunnerTest.php New test coverage for Agent_Runner including queued run processing, enqueue operations, and error handling
tests/Unit/AgentLoopHelperTest.php New test coverage for Agent_Loop_Helper including turn execution, offline mode, and generator invocation

Sequence Diagram

sequenceDiagram
    participant User
    participant Panel as Panel UI
    participant ChatAPI as Chat REST API
    participant AgentRunner as Agent Runner
    participant AgentLoop as Agent Loop Helper
    participant Transport as Polling Transport
    participant EventStore as Agent Event Store
    participant RunStore as Agent Run Store
    participant SessionStore as Agent Session Store
    participant Provider as AI Provider

    User->>Panel: Send message
    Panel->>ChatAPI: POST /chat/send
    ChatAPI->>SessionStore: create_session()
    SessionStore-->>ChatAPI: session_id
    ChatAPI->>RunStore: create_run(session_id)
    RunStore-->>ChatAPI: run_id
    ChatAPI->>RunStore: claim_run(run_id, worker_id)
    RunStore-->>ChatAPI: lock_token
    ChatAPI->>SessionStore: claim_session(session_id)
    SessionStore-->>ChatAPI: lease_token
    ChatAPI->>AgentLoop: run_turn(turn_request)
    AgentLoop->>Transport: emit(agent.run.started)
    Transport->>EventStore: insert_event()
    AgentLoop->>Provider: generateText()
    Provider-->>AgentLoop: assistant_text + tool_calls
    AgentLoop->>Transport: emit(agent.tool_call)
    Transport->>EventStore: insert_event()
    AgentLoop->>Transport: emit(agent.run.finished)
    Transport->>EventStore: insert_event()
    AgentLoop-->>ChatAPI: result
    ChatAPI->>RunStore: complete_run(run_id, lock_token)
    ChatAPI->>SessionStore: update_release(session_id, lease_token)
    ChatAPI-->>Panel: response + events_cursor
    
    Note over Panel,EventStore: Polling Phase
    
    loop Poll for progress
        Panel->>ChatAPI: GET /agent/runs/{run_id}/events?after={cursor}
        ChatAPI->>EventStore: get_events(run_id, after)
        EventStore-->>ChatAPI: events[]
        ChatAPI-->>Panel: events + next_cursor
        Panel->>Panel: Update UI with tool calls
        Panel->>ChatAPI: GET /agent/runs/{run_id}
        ChatAPI->>RunStore: get_run(run_id)
        RunStore-->>ChatAPI: run status
        ChatAPI-->>Panel: run status
        alt Status is terminal
            Panel->>Panel: Stop polling, display final result
        else Status is running
            Panel->>Panel: Continue polling
        end
    end
Loading

Last reviewed commit: 66b9ce2

@bradvin
bradvin merged commit 41e39cd into develop Feb 27, 2026
4 checks passed
@bradvin
bradvin deleted the codex/agent-loop-runtime branch February 27, 2026 15:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant