@farazirfan/costar-server-executor 1.0.0

package/.env.example

@@ -0,0 +1,53 @@
+# CoStar Server Executor - Environment Configuration
+
+# ===== REQUIRED =====
+
+# Anthropic API Key (Required for agent execution)
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Supabase Configuration (Required for memory storage)
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+# ===== OPTIONAL - Agent Configuration =====
+
+# Agent Identity
+AGENT_ID=default
+USER_ID=default
+
+# Model Configuration
+ANTHROPIC_MODEL=claude-sonnet-4-20250514
+MAX_TOKENS=200000
+TEMPERATURE=1.0
+
+# Workspace Directory
+WORKSPACE_DIR=./workspace
+AUTO_GENERATE_WORKSPACE=true
+
+# ===== OPTIONAL - Tool API Keys =====
+
+# OpenAI (For image analysis and TTS)
+OPENAI_API_KEY=sk-...
+
+# Brave Search (For web search)
+BRAVE_SEARCH_API_KEY=BSA...
+
+# Google Gemini (For image/video generation)
+GEMINI_API_KEY=AI...
+
+# Google Maps (For maps, geocoding, directions)
+GOOGLE_MAPS_API_KEY=AI...
+
+# Google Service Account (For Gmail and Calendar)
+# Note: This should be a JSON string of your service account credentials
+GOOGLE_SERVICE_ACCOUNT_JSON={"type":"service_account","project_id":"..."}
+
+# ===== OPTIONAL - Skills Configuration =====
+
+# Extra skills directories (comma-separated)
+SKILLS_EXTRA_DIRS=/path/to/skills1,/path/to/skills2
+
+# ===== OPTIONAL - Tools Configuration =====
+
+# Disabled tools (comma-separated tool names)
+TOOLS_DISABLED=browser,tts

package/README.md

@@ -0,0 +1,313 @@
+# CoStar Server Executor
+
+A TypeScript implementation of autonomous AI agent patterns, cloned from [OpenClaw](https://github.com/badlogic/openclaw) and enhanced with built-in tools from ProjectX.
+
+## Overview
+
+CoStar Server Executor is a 24/7 autonomous agent framework that:
+- ✅ Executes tasks using Claude AI (Anthropic API)
+- ✅ Has access to 32 powerful tools (file operations, web, email, calendar, maps, and more)
+- ✅ Supports modular skills using the AgentSkills.io standard
+- ✅ Runs heartbeat checks for proactive monitoring
+- ✅ Stores memory and context in Supabase
+- ✅ Can be used as a CLI tool or TypeScript library
+
+## Features
+
+### Core Capabilities
+- **Agentic Execution Loop**: Multi-turn conversations with tool use
+- **32 Built-in Tools**: File ops, shell execution, web search/fetch, browser automation, memory, email, calendar, maps, image/video generation, and more
+- **Skills System**: AgentSkills.io compatible framework for modular capabilities
+- **Workspace Context**: Loads context from AGENTS.md, MEMORY.md, USER.md, PROJECTS.md
+- **Heartbeat Checks**: Proactive monitoring using HEARTBEAT.md instructions
+- **Supabase Integration**: Persistent memory and data storage
+
+### Tool Categories (32 tools)
+
+#### File Operations (5 tools)
+- `read` - Read file contents
+- `write` - Write file contents
+- `edit` - Edit file with search/replace
+- `grep` - Search file contents
+- `glob` - Find files by pattern
+
+#### Execution Tools (2 tools)
+- `exec` - Execute shell commands with PTY support
+- `process` - Manage shell command sessions
+
+#### Web Tools (3 tools)
+- `web_search` - Search the web using Brave Search API
+- `web_fetch` - Fetch and extract web page content
+- `browser` - Control headless Chromium browser
+
+#### Agent Tools (5 tools)
+- `memory` - Store and recall information in Supabase
+- `message` - Send messages to the user
+- `image` - Analyze images using GPT-4V
+- `tts` - Text-to-speech using OpenAI TTS
+- `session_status` - Get current session information
+
+#### Email Tools (4 tools)
+- `search_emails` - Search Gmail messages
+- `send_email` - Send email via Gmail
+- `read_email` - Read specific email by ID
+- `read_email_thread` - Read entire email thread
+
+#### Calendar Tools (4 tools)
+- `get_calendar_events` - List calendar events
+- `create_calendar_event` - Create new event
+- `update_calendar_event` - Update existing event
+- `delete_calendar_event` - Delete event by ID
+
+#### Google Maps Tools (3 tools)
+- `google_maps_search` - Search nearby places
+- `google_maps_directions` - Get turn-by-turn directions
+- `geocode` - Convert address to coordinates
+
+#### Utility Tools (3 tools)
+- `generate_image` - Generate images using AI (Gemini Imagen 4)
+- `generate_video` - Generate videos using AI (Google Veo 3.1)
+- `fetch_api_data` - Make HTTP requests to external APIs
+
+## Installation
+
+```bash
+# Clone the repository
+git clone <your-repo-url>
+cd costar-server-executor
+
+# Install dependencies
+npm install
+
+# Copy environment template
+cp .env.example .env
+
+# Edit .env with your API keys
+nano .env
+
+# Build the project
+npm run build
+```
+
+## Configuration
+
+### Required Environment Variables
+
+```bash
+# Anthropic API Key
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Supabase Configuration
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+### Optional Environment Variables
+
+See `.env.example` for all available configuration options including:
+- Agent configuration (model, max tokens, temperature)
+- Tool API keys (OpenAI, Brave Search, Google services)
+- Workspace directory
+- Skills directories
+- Disabled tools
+
+## Usage
+
+### CLI Usage
+
+```bash
+# Execute a task
+npm start "Search for recent news about AI"
+
+# Or after building
+node dist/index.js "Send an email to john@example.com about the meeting"
+
+# Execute heartbeat check
+npm start -- --heartbeat
+
+# Show help
+npm start -- --help
+```
+
+### Library Usage
+
+```typescript
+import { createAgent, executeTask, executeHeartbeat } from "costar-server-executor";
+
+// Execute a task
+const response = await executeTask("What's the weather in San Francisco?");
+console.log(response);
+
+// Or create and manage agent directly
+const agent = await createAgent();
+const result = await agent.executeTurn("Search for latest AI news", {
+  maxTurns: 25,
+  onToolCall: (toolName, toolCallId) => {
+    console.log(`Tool: ${toolName}`);
+  },
+  onResponse: (text) => {
+    console.log(`Response: ${text}`);
+  },
+});
+
+console.log(result.response);
+```
+
+## Workspace Files
+
+Create a `workspace/` directory with the following markdown files to provide context to the agent:
+
+- **AGENTS.md** - Autonomy grants and permissions
+- **MEMORY.md** - Agent's persistent memory
+- **USER.md** - User profile and preferences
+- **PROJECTS.md** - Active coding projects
+- **HEARTBEAT.md** - Instructions for heartbeat checks
+- **CRON.md** - Scheduled tasks
+
+Example `workspace/AGENTS.md`:
+
+```markdown
+# Autonomy Grants
+
+You are authorized to:
+- Search the web for information
+- Read and analyze files in the workspace
+- Send emails on behalf of the user
+- Create calendar events
+- Execute shell commands (non-destructive)
+
+Do NOT:
+- Delete important files without confirmation
+- Send emails to unknown recipients
+- Make financial transactions
+```
+
+## Skills
+
+The executor supports AgentSkills.io compatible skills. Bundled skills include:
+
+- **/commit** - Create git commits with proper formatting (Conventional Commits)
+- **/test** - Run tests with common frameworks (Jest, Vitest, Pytest, etc.)
+- **/review-pr** - Review GitHub pull requests
+
+### Creating Custom Skills
+
+Create a `SKILL.md` file in `workspace/skills/` or any directory specified in `SKILLS_EXTRA_DIRS`:
+
+```yaml
+---
+name: my-skill
+description: What this skill does
+metadata:
+  emoji: "🚀"
+  requires:
+    bins: ["binary-name"]
+    env: ["API_KEY"]
+  install:
+    - kind: brew
+      formula: package-name
+---
+
+# Skill Instructions
+
+Detailed markdown instructions for the agent...
+```
+
+See `SKILLS_SYSTEM.md` for complete documentation.
+
+## API Keys Required
+
+### Core Functionality
+- **ANTHROPIC_API_KEY** - For Claude AI agent execution
+- **SUPABASE_URL + SUPABASE_SERVICE_KEY** - For memory storage
+
+### Optional Tools
+- **OPENAI_API_KEY** - For image analysis (GPT-4V) and TTS
+- **BRAVE_SEARCH_API_KEY** - For web search
+- **GEMINI_API_KEY** - For image/video generation (Gemini Imagen 4, Veo 3.1)
+- **GOOGLE_MAPS_API_KEY** - For maps, geocoding, and directions
+- **GOOGLE_SERVICE_ACCOUNT_JSON** - For Gmail and Calendar access
+
+## Development
+
+```bash
+# Run in development mode with auto-reload
+npm run dev
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+
+# Format
+npm run format
+```
+
+## Architecture
+
+```
+src/
+├── agent/              # Agent execution loop
+│   ├── agent.ts        # Main Agent class
+│   ├── context-loader.ts  # Workspace file loader
+│   └── tool-executor.ts   # Tool execution handler
+├── config/             # Configuration management
+│   ├── types.ts        # Config type definitions
+│   └── config.ts       # Config loader and validator
+├── skills/             # Skills system
+│   ├── types.ts        # Skill type definitions
+│   ├── loader.ts       # SKILL.md parser
+│   ├── status.ts       # Requirement validation
+│   └── manager.ts      # SkillsManager API
+├── tools/              # Tool implementations
+│   ├── built-in-tools.ts  # Built-in tools (email, calendar, maps, etc.)
+│   ├── web-search.ts   # Web search tool
+│   ├── browser.ts      # Browser automation tool
+│   ├── memory.ts       # Memory tool
+│   └── ...             # Other tools
+├── types/              # Type definitions
+│   └── tool.ts         # Tool types
+├── utils/              # Utility functions
+│   └── tool-helpers.ts # Tool helper functions
+└── index.ts            # Main entry point
+```
+
+## Documentation
+
+- **TOOLS_IMPLEMENTATION.md** - Complete documentation of all 32 tools
+- **SKILLS_SYSTEM.md** - Skills system documentation and best practices
+- **.env.example** - Environment configuration template
+
+## Credits
+
+- **OpenClaw** - Original architecture and patterns ([@badlogic](https://github.com/badlogic/openclaw))
+- **ProjectX** - Built-in tools reference implementation (Dart/Flutter)
+- **@mariozechner/pi-coding-agent** - File operation tools
+- **AgentSkills.io** - Skills format specification
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## Support
+
+For issues and questions:
+- GitHub Issues: [Create an issue](https://github.com/your-repo/issues)
+- Documentation: See TOOLS_IMPLEMENTATION.md and SKILLS_SYSTEM.md
+
+---
+
+**CoStar Server Executor** - Autonomous AI agents in TypeScript

package/costar.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+/**
+ * CoStar Server Executor - CLI Entry
+ * Thin wrapper that loads the compiled CLI entry point.
+ */
+
+import module from "node:module";
+
+// Enable compile cache for faster startup (Node 22+)
+if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
+  try {
+    module.enableCompileCache();
+  } catch {
+    // Ignore errors on older Node versions
+  }
+}
+
+await import("./dist/cli.js");

package/dist/agent/agent-old.d.ts

@@ -0,0 +1,61 @@
+/**
+ * CoStar Server Executor - Main Agent
+ * Handles agent execution loop with Anthropic SDK
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import type { CoStarConfig } from "../config/types.js";
+import type { AnyAgentTool } from "../types/tool.js";
+/**
+ * Agent turn result
+ */
+export type AgentTurnResult = {
+    success: boolean;
+    response?: string;
+    toolCalls?: number;
+    error?: string;
+    stopReason?: string;
+    turns?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+};
+/**
+ * Agent execution options
+ */
+export type AgentExecutionOptions = {
+    maxTurns?: number;
+    stream?: boolean;
+    onToolCall?: (toolName: string, toolCallId: string) => void;
+    onResponse?: (text: string) => void;
+};
+/**
+ * Main agent class
+ */
+export declare class Agent {
+    private client;
+    private config;
+    private toolExecutor;
+    private contextLoader;
+    private conversationHistory;
+    constructor(config: CoStarConfig, tools: AnyAgentTool[], workspaceDir: string);
+    /**
+     * Reset conversation history
+     */
+    resetConversation(): void;
+    /**
+     * Execute a single agent turn
+     */
+    executeTurn(userMessage: string, options?: AgentExecutionOptions): Promise<AgentTurnResult>;
+    /**
+     * Execute heartbeat check (proactive monitoring)
+     */
+    executeHeartbeat(options?: AgentExecutionOptions): Promise<AgentTurnResult>;
+    /**
+     * Get conversation history
+     */
+    getConversationHistory(): Anthropic.Messages.MessageParam[];
+    /**
+     * Get conversation history as text
+     */
+    getConversationText(): string;
+}
+//# sourceMappingURL=agent-old.d.ts.map

package/dist/agent/agent-old.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-old.d.ts","sourceRoot":"","sources":["../../src/agent/agent-old.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC,CAAC;AAEF;;GAEG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,mBAAmB,CAAyC;gBAGlE,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,YAAY,EAAE,EACrB,YAAY,EAAE,MAAM;IAgBtB;;OAEG;IACH,iBAAiB,IAAI,IAAI;IAIzB;;OAEG;IACG,WAAW,CACf,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,eAAe,CAAC;IAgO3B;;OAEG;IACG,gBAAgB,CACpB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,eAAe,CAAC;IAyC3B;;OAEG;IACH,sBAAsB,IAAI,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE;IAI3D;;OAEG;IACH,mBAAmB,IAAI,MAAM;CAgB9B"}