Poc/claw

[tomkis]

Summary

Linked Issues

Documentation

• No Docs Needed:

If this PR adds new feature or changes existing. Make sure documentation is adjusted accordingly. If the docs is not needed, please explain why.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a foundational proof-of-concept for a "Claw-like" agent within the AgentStack ecosystem. The primary goal is to demonstrate an agent capable of self-learning and self-scheduling, leveraging persistent workspace files and a heartbeat mechanism. This significantly enhances agent autonomy by allowing them to evolve their personality, accumulate knowledge, log activities, and execute recurring tasks independently, laying the groundwork for more sophisticated and adaptive AI agents.

Highlights

• New Agent Introduction: Introduced a new 'Stack Claw' agent, a proof-of-concept for a self-improving, general-purpose agent capable of self-learning and self-scheduling.
• Self-Learning Capabilities: Implemented self-learning through persistent workspace files (IDENTITY.md, MEMORY.md, DIARY.md) that allow the agent to evolve its personality and accumulate knowledge.
• Self-Scheduling (Heartbeat): Enabled self-scheduling via a 'heartbeat' mechanism, allowing the agent to perform recurring tasks at specified intervals.
• AgentStack Integration: Integrated the new agent with the AgentStack SDK for conversation history and platform context management, including new API endpoints and database schema for managing heartbeats.
• Infrastructure Support: Added necessary Dockerfile, Python project configuration, and server-side infrastructure (API routes, database migrations, job queues, and workers) to support the new agent and its heartbeat functionality.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• agents/stack-claw/.gitignore
  • Added a .gitignore file to exclude workspaces/ from version control.
• agents/stack-claw/Dockerfile
  • Added a Dockerfile to build the stack-claw agent, including Python, Node.js, uv, and the pi-coding-agent CLI.
• agents/stack-claw/plan.md
  • Added a detailed planning document outlining the architecture, current state, completed features (conversation history, persistent workspace, self-learning, self-scheduling), and next steps for the Claw-like Agent POC.
• agents/stack-claw/pyproject.toml
  • Added a pyproject.toml file to define the Python project metadata and dependencies for the stack-claw agent.
• agents/stack-claw/src/stack_claw/init.py
  • Added an empty __init__.py file to mark the stack_claw directory as a Python package.
• agents/stack-claw/src/stack_claw/agent.py
  • Added the core Python logic for the stack-claw agent, implementing conversation handling, workspace management, heartbeat scheduling, and interaction with the pi CLI.
• agents/tasks.toml
  • Updated the task configuration to include Hadolint checks for the new stack-claw agent's Dockerfile.
• apps/agentstack-sdk-py/src/agentstack_sdk/platform/context.py
  • Modified the platform context to include start_heartbeat and stop_heartbeat asynchronous methods for managing agent heartbeats.
• apps/agentstack-sdk-py/src/agentstack_sdk/server/context.py
  • Modified the server context to expose start_heartbeat and stop_heartbeat methods, delegating to the platform context.
• apps/agentstack-server/src/agentstack_server/api/routes/contexts.py
  • Modified API routes to add new endpoints for POSTing to /contexts/{context_id}/heartbeat to start a heartbeat and DELETEing from the same endpoint to stop it.
• apps/agentstack-server/src/agentstack_server/api/schema/contexts.py
  • Modified the API schema to define the HeartbeatStartRequest model for initiating agent heartbeats.
• apps/agentstack-server/src/agentstack_server/application.py
  • Modified the application startup logic to purge any stale heartbeat jobs from the Procrastinate queue and deactivate existing heartbeats in the database.
• apps/agentstack-server/src/agentstack_server/domain/models/context.py
  • Modified the domain models to introduce a ContextHeartbeat Pydantic model for representing heartbeat configurations.
• apps/agentstack-server/src/agentstack_server/domain/repositories/context.py
  • Modified the context repository interface to include methods for upsert_heartbeat, get_heartbeat, and deactivate_heartbeat.
• apps/agentstack-server/src/agentstack_server/infrastructure/persistence/migrations/alembic/versions/a8b9c0d1e2f3_.py
  • Added a new Alembic migration script to create the context_heartbeats table in the database.
• apps/agentstack-server/src/agentstack_server/infrastructure/persistence/repositories/context.py
  • Modified the SQLAlchemy context repository to implement the new heartbeat-related methods, including an upsert operation for context_heartbeats.
• apps/agentstack-server/src/agentstack_server/jobs/procrastinate.py
  • Modified the Procrastinate job configuration to register the new heartbeat_tasks blueprint.
• apps/agentstack-server/src/agentstack_server/jobs/queues.py
  • Modified the job queues enumeration to add a new HEARTBEAT queue.
• apps/agentstack-server/src/agentstack_server/jobs/tasks/heartbeat.py
  • Added a new Procrastinate task send_heartbeat responsible for processing and rescheduling agent heartbeats.
• apps/agentstack-server/src/agentstack_server/run_workers.py
  • Modified the worker configuration to include a dedicated heartbeat_worker for processing heartbeat tasks.
• apps/agentstack-server/src/agentstack_server/service_layer/services/contexts.py
  • Modified the context service to implement start_heartbeat and stop_heartbeat logic, interacting with the repository and scheduling heartbeat jobs.
• pnpm-lock.yaml
  • Updated various @types/node dependencies to version 25.5.0 and added deprecation warnings for glob and inflight packages.
• pnpm-workspace.yaml
  • Updated the workspace configuration to include the new agents/stack-claw directory.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This PR introduces a new "Claw-like" agent as a Proof of Concept, along with the necessary backend support for a "heartbeat" mechanism for scheduled tasks. The changes are extensive, adding a new agent, modifying the Python SDK, and updating the server with new APIs, database models, and background jobs. My review focuses on improving security, configurability, and dependency management. I've identified a critical issue with outdated dependencies, a high-severity security risk in how environment variables are passed to subprocesses, and several medium-severity issues related to hardcoded values and loose dependency pinning that could affect reproducibility and maintainability.

[gemini-code-assist]

The lockfile indicates the use of deprecated and vulnerable dependencies. This glob@7.1.7 is one example, which has known security vulnerabilities. Another one is inflight@1.0.6 which is also deprecated and known to leak memory. These should be updated to secure versions to avoid potential security risks and bugs. You can run pnpm audit to see the full list of vulnerabilities and then update the packages accordingly.

[gemini-code-assist]

Passing the entire os.environ to the subprocess is a security risk. It may leak sensitive environment variables from the agent server (e.g., database credentials, other service keys) to the pi subprocess that are not needed by it. It's much safer to explicitly pass only the required environment variables on a whitelist basis.

Suggested change

	env={**os.environ},
	env={"OPENAI_API_KEY": os.getenv("OPENAI_API_KEY")},

[gemini-code-assist]

The global npm package @mariozechner/pi-coding-agent is installed without a pinned version. This can lead to non-reproducible builds if a new version of the package is released with breaking changes. It's recommended to pin the version to ensure build stability.

RUN apk add --no-cache nodejs npm && npm install -g @mariozechner/pi-coding-agent@<version>

[gemini-code-assist]

The dependency python-dotenv>=1.0.0 is too broad. To ensure reproducible builds and avoid accidentally pulling in breaking changes from future major versions, it's better to pin dependencies more strictly. Consider using ~=1.0.0 to allow only patch releases, or pinning to an exact version with ==.

Suggested change

	"python-dotenv>=1.0.0",
	"python-dotenv~=1.0.0",

[gemini-code-assist]

The provider (openai) and model (openai/gpt-5-codex) are hardcoded. This makes the agent less flexible and harder to configure for different environments or models. It would be better to make these configurable, for example, through environment variables.

Suggested change

	"--provider", "openai",
	"--model", "openai/gpt-5-codex",
	"--provider", os.getenv("PI_PROVIDER", "openai"),
	"--model", os.getenv("PI_MODEL", "openai/gpt-5-codex"),

[gemini-code-assist]

The database schema public is hardcoded in the SQL query to update context_heartbeats. This reduces flexibility and can cause issues in environments where a different schema is used. This should be made configurable, similar to how procrastinate_schema is handled.

Suggested change

	await conn.execute(
	"UPDATE public.context_heartbeats SET active = false"
	)
	await conn.execute(
	f"UPDATE {configuration.persistence.db_schema}.context_heartbeats SET active = false"
	)