AlexandrAI AGENTS.md
agents-md

Personal Work Agent Runtime Factory Agent Guide

Project-specific AGENTS.md guidance for the Personal Work Agent runtime factory, daemon loop, worker queue, executor bundles, platform loop wiring, and tests.

AGENTS.md

Guidance for coding agents working on the Personal Work Agent runtime factory and daemon execution boundary.

Project Overview

The runtime layer builds the local daemon, configures executor bundles, wires platform sync loops, schedules ticks, starts worker processing, prepares process environment overrides, stores secrets, and coordinates periodic runtime cycles. It is the main composition root for local-first agent execution.

Use this boundary when changing daemon startup, runtime loop orchestration, queue processing, executor routing, provider selection, secret-store integration, or platform loop registration.

Project Map

  • src/workagent/runtime/factory.py builds DaemonRuntimeBundle and registers platform loops, review runtimes, pending runtimes, scheduler, worker, outbound processor, and executor bundles.
  • src/workagent/runtime/app_runtime.py coordinates one app runtime cycle across sync, review, scheduler, worker, outbound, pending, and onboarding runtimes.
  • src/workagent/runtime/loop.py and daemon_loop.py provide repeated cycle execution.
  • src/workagent/runtime/queue.py and worker.py manage local case processing.
  • src/workagent/runtime/tick.py handles daemon tick behavior and secret rotation.
  • src/workagent/runtime/process_env.py builds process environment overrides for local engines.
  • src/workagent/executors/ contains CLI and API execution engines plus routing.

Setup Commands

bashuv sync --locked --dev
uv run pytest tests/test_runtime_factory.py tests/test_app_runtime.py tests/test_runtime_loop.py -q
uv run pytest tests/test_worker_runtime.py tests/test_engine_routing.py tests/test_daemon_tick.py -q
make lint

Change Rules For Agents

  • Keep runtime wiring explicit; do not hide platform registrations behind dynamic imports without tests.
  • Preserve async session ownership. DB access should flow through async session factories.
  • Keep no-op runtimes for disabled connectors so one disabled platform does not break daemon startup.
  • Treat executor selection as a product contract. Update ExecutionEngine enum, executor implementation, routing, and tests together.
  • Keep secret values in SecretStore or environment overrides, never in logs or generated docs.
  • Preserve outbound-only sync assumptions; runtime changes should not introduce public inbound dependencies.
  • For platform loop additions, update connector client, sync service, ingest service, runtime factory registration, and tests together.

Verification

bashuv run pytest tests/test_runtime_factory.py tests/test_app_runtime_wiring.py tests/test_app_runtime_cycles.py -q
uv run pytest tests/test_runtime_loop.py tests/test_periodic_daemon_loop.py tests/test_worker_runtime.py -q
make lint

Broaden to the full suite before shipping cross-runtime changes.

Security Notes

Runtime composition touches credentials, local process environments, engine commands, and case data. Redact provider keys, pairing secrets, local roots, and token material from logs and fixtures.

PR Checklist

  • Disabled connectors still start as no-op loops.
  • New execution engines include enum, routing, executor, and tests.
  • Runtime cycle summaries remain stable.
  • Secret handling stays inside configured stores.