Skip to content

v0.1: Stabilize Current Runtime

Goal

Make the current owner setup boring, inspectable, and debuggable before adding new architecture.

Why It Matters

G-Agent already has valuable local-first surfaces: channels, tools, visual/image generation, Google Workspace, service mode, and workspace restriction. The next features will fail if the current runtime is hard to inspect when something breaks.

Scope

  • Keep tools.restrictToWorkspace enabled by default.
  • Keep tools.allowedPaths as the official way to trust media/project folders.
  • Document OpenAI-compatible image proxy usage, including current Codex image models.
  • Add focused tests for image proxy response formats.
  • Fix Google Workspace discovery for service environments.
  • Add easy log inspection from CLI and chat.
  • Improve troubleshooting docs for PATH, systemd user services, sandbox behavior, and trusted media folders.

Module Targets

  • backend/agent/g_agent/agent/tools/selfie.py
  • backend/agent/g_agent/providers/
  • backend/agent/g_agent/config/schema.py
  • backend/agent/g_agent/observability/
  • backend/agent/g_agent/cli/commands.py
  • docs/configuration.md
  • docs/operations.md
  • docs/troubleshooting.md

Acceptance Criteria

  • Image generation works through an OpenAI-compatible proxy.
  • Failed image generation logs provider, model, endpoint, and response shape.
  • Google Workspace errors explain missing gws, missing gcloud, or PATH issues separately.
  • CLI can show recent runtime logs without manual journal digging.
  • Docs explain how to add /home/galyarder/Documents/Keiya or similar owner media roots through tools.allowedPaths, without disabling workspace safety.

Tests

  • Proxy image response parser handles expected response variants.
  • Provider error path returns actionable text.
  • Google Workspace discovery test covers service PATH behavior.
  • Log command truncates long output safely.

References

  • Main roadmap Phase 0.
  • Existing visual/selfie implementation.
  • Current user reports around image proxy, gws, and workspace path access.

Agent Handoff

Current G-Agent State

  • agent/tools/selfie.py already supports huggingface, cloudflare, and openai-compatible image generation.
  • selfie.py has a gpt-image-* payload branch using response_format: b64_json and size: 1024x1024.
  • config/schema.py already has VisualIdentityConfig and ImageGenProviderConfig with LoRA fields.
  • agent/tools/google_workspace.py already wraps gws; config has integrations.google.gws_path, credentials_file, and tools.exec.path_append.
  • observability/metrics.py and agent/runtime.py already give metrics and task checkpoints. /logs now exposes recent bounded checkpoint output through chat and direct CLI agent mode.
  • channels/slash_commands.py has /status, /context, /tools, /cron, /memory, and /logs; extend this shared command surface before inventing a second one.

Implementation Slices

  1. Add image proxy parser tests.
  2. Cover b64_json, URL fallback, missing data, missing image keys, and non-JSON HTTP errors.
  3. Target backend/agent/tests/test_selfie_tool.py.
  4. Improve image error reporting.
  5. In SelfieTool._generate_openai_compatible, wrap HTTP errors with endpoint, provider, model, status, and a short response preview.
  6. Do not log API keys.
  7. Add gws diagnostics.
  8. Extend GwsClient helper behavior so errors distinguish:
    • binary not found
    • gcloud not found
    • auth/config missing
    • command failed
  9. Tests belong beside test_google_workspace_helpers.py and test_gws_client_env.py.
  10. Add log reader.
  11. Create observability/log_reader.py.
  12. It should read recent task checkpoints and metrics JSONL first, because those are local and portable.
  13. Optional later: journal/systemd support.
  14. Add /logs.
  15. Extend channels/slash_commands.py.
  16. Keep output short and HTML-safe for Telegram/WhatsApp.

Do Not Break

  • Keep tools.restrict_to_workspace and tools.allowed_paths behavior.
  • Keep existing SelfieTool delivery semantics: when selfie is delivered, AgentLoop suppresses duplicate follow-up text.
  • Keep gws_path override; service environments need explicit binary paths.

First PR Boundary

One PR can include:

  • image proxy tests and improved error messages
  • gws diagnostics tests
  • /logs command backed by local checkpoint/metrics summaries

Do not include SQLite session work in this PR.