@stephen-lord/docs 1.0.0 → 1.0.1

package/dist-docs/Agent-Skills-for-Context-Engineering/skills/filesystem-context/scripts/filesystem_context.py

@@ -0,0 +1,353 @@
+"""
+Filesystem Context Manager
+
+Demonstrates the core patterns for filesystem-based context engineering:
+1. Scratch pad for tool output offloading
+2. Plan persistence for long-horizon tasks
+3. Dynamic context discovery with file references
+
+Usage:
+    python filesystem_context.py
+
+This script demonstrates concepts without external dependencies.
+"""
+
+import os
+import json
+from datetime import datetime
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+
+
+# =============================================================================
+# Pattern 1: Scratch Pad Manager
+# =============================================================================
+
+class ScratchPadManager:
+    """
+    Manages temporary file storage for offloading large tool outputs.
+    
+    Instead of keeping 10k tokens of search results in context,
+    write them to a file and return a reference. The agent can
+    then grep or read specific sections as needed.
+    """
+    
+    def __init__(self, base_path: str = "scratch", token_threshold: int = 2000):
+        self.base_path = Path(base_path)
+        self.base_path.mkdir(parents=True, exist_ok=True)
+        self.token_threshold = token_threshold
+    
+    def estimate_tokens(self, content: str) -> int:
+        """Rough token estimate: ~4 characters per token."""
+        return len(content) // 4
+    
+    def should_offload(self, content: str) -> bool:
+        """Determine if content exceeds threshold for offloading."""
+        return self.estimate_tokens(content) > self.token_threshold
+    
+    def offload(self, content: str, source: str) -> Dict[str, Any]:
+        """
+        Write content to file, return compact reference.
+        
+        The reference includes:
+        - File path for later retrieval
+        - Summary of first few lines
+        - Token estimate for the full content
+        """
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+        filename = f"{source}_{timestamp}.txt"
+        file_path = self.base_path / filename
+        
+        file_path.write_text(content)
+        
+        # Extract summary from first meaningful lines
+        lines = content.strip().split('\n')[:5]
+        summary = '\n'.join(lines)
+        if len(summary) > 300:
+            summary = summary[:300] + "..."
+        
+        return {
+            "path": str(file_path),
+            "source": source,
+            "tokens_saved": self.estimate_tokens(content),
+            "summary": summary
+        }
+    
+    def format_reference(self, ref: Dict[str, Any]) -> str:
+        """Format reference for inclusion in context."""
+        return (
+            f"[Output from {ref['source']} saved to {ref['path']}. "
+            f"~{ref['tokens_saved']} tokens. "
+            f"Summary: {ref['summary'][:200]}]"
+        )
+
+
+# =============================================================================
+# Pattern 2: Plan Persistence
+# =============================================================================
+
+@dataclass
+class PlanStep:
+    """Individual step in an agent plan."""
+    id: int
+    description: str
+    status: str = "pending"  # pending, in_progress, completed, blocked
+    notes: Optional[str] = None
+
+
+@dataclass
+class AgentPlan:
+    """
+    Persistent plan that survives context window limitations.
+    
+    Write the plan to disk so the agent can re-read it at any point,
+    even after summarization or context window refresh.
+    """
+    objective: str
+    steps: List[PlanStep] = field(default_factory=list)
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+    
+    def to_dict(self) -> dict:
+        return {
+            "objective": self.objective,
+            "created_at": self.created_at,
+            "steps": [
+                {
+                    "id": s.id,
+                    "description": s.description,
+                    "status": s.status,
+                    "notes": s.notes
+                }
+                for s in self.steps
+            ]
+        }
+    
+    def save(self, path: str = "scratch/current_plan.json"):
+        """Persist plan to filesystem."""
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        with open(path, 'w') as f:
+            json.dump(self.to_dict(), f, indent=2)
+        print(f"Plan saved to {path}")
+    
+    @classmethod
+    def load(cls, path: str = "scratch/current_plan.json") -> "AgentPlan":
+        """Load plan from filesystem."""
+        with open(path, 'r') as f:
+            data = json.load(f)
+        
+        plan = cls(objective=data["objective"])
+        plan.created_at = data.get("created_at", "")
+        
+        for step_data in data.get("steps", []):
+            plan.steps.append(PlanStep(
+                id=step_data["id"],
+                description=step_data["description"],
+                status=step_data["status"],
+                notes=step_data.get("notes")
+            ))
+        return plan
+    
+    def current_step(self) -> Optional[PlanStep]:
+        """Get the current (first non-completed) step."""
+        for step in self.steps:
+            if step.status not in ["completed", "cancelled"]:
+                return step
+        return None
+    
+    def complete_step(self, step_id: int, notes: str = None):
+        """Mark a step as completed."""
+        for step in self.steps:
+            if step.id == step_id:
+                step.status = "completed"
+                if notes:
+                    step.notes = notes
+                return
+        raise ValueError(f"Step {step_id} not found")
+    
+    def progress_summary(self) -> str:
+        """Generate summary for context injection."""
+        completed = sum(1 for s in self.steps if s.status == "completed")
+        total = len(self.steps)
+        current = self.current_step()
+        
+        summary = f"Objective: {self.objective}\n"
+        summary += f"Progress: {completed}/{total} steps completed\n"
+        if current:
+            summary += f"Current step: [{current.id}] {current.description}"
+        else:
+            summary += "All steps completed."
+        
+        return summary
+
+
+# =============================================================================
+# Pattern 3: Tool Output Handler
+# =============================================================================
+
+class ToolOutputHandler:
+    """
+    Handles tool outputs with automatic offloading decision.
+    
+    Small outputs stay in context. Large outputs get written to files
+    with a compact reference returned instead.
+    """
+    
+    def __init__(self, scratch_pad: ScratchPadManager = None):
+        self.scratch_pad = scratch_pad or ScratchPadManager()
+    
+    def process_output(self, tool_name: str, output: str) -> str:
+        """
+        Process tool output, offloading if too large.
+        
+        Returns either:
+        - The original output (if small enough)
+        - A file reference with summary (if too large)
+        """
+        if self.scratch_pad.should_offload(output):
+            ref = self.scratch_pad.offload(output, source=tool_name)
+            return self.scratch_pad.format_reference(ref)
+        return output
+
+
+# =============================================================================
+# Demonstration
+# =============================================================================
+
+def demo_scratch_pad():
+    """Demonstrate scratch pad pattern."""
+    print("=" * 60)
+    print("DEMO: Scratch Pad for Tool Output Offloading")
+    print("=" * 60)
+    
+    scratch = ScratchPadManager(base_path="demo_scratch", token_threshold=100)
+    
+    # Small output stays in context
+    small_output = "API returned: {'status': 'ok', 'data': [1, 2, 3]}"
+    print(f"\nSmall output ({scratch.estimate_tokens(small_output)} tokens):")
+    print(f"  Should offload: {scratch.should_offload(small_output)}")
+    
+    # Large output gets offloaded
+    large_output = """
+Search Results for "context engineering":
+
+1. Context Engineering: The Art of Curating LLM Context
+   URL: https://example.com/article1
+   Snippet: Context engineering is the discipline of managing what information 
+   enters the language model's context window. Unlike prompt engineering which
+   focuses on instruction crafting, context engineering addresses the holistic
+   curation of all information...
+   
+2. Building Production Agents with Effective Context Management
+   URL: https://example.com/article2
+   Snippet: Production agent systems require sophisticated context management
+   strategies. This includes compression, caching, and strategic partitioning
+   of work across sub-agents with isolated contexts...
+   
+3. The Lost-in-Middle Problem and How to Avoid It
+   URL: https://example.com/article3
+   Snippet: Research shows that language models exhibit U-shaped attention
+   patterns, with information in the middle of long contexts receiving less
+   attention than content at the beginning or end...
+
+... (imagine 50 more results) ...
+"""
+    
+    print(f"\nLarge output ({scratch.estimate_tokens(large_output)} tokens):")
+    print(f"  Should offload: {scratch.should_offload(large_output)}")
+    
+    if scratch.should_offload(large_output):
+        ref = scratch.offload(large_output, source="web_search")
+        print(f"\nOffloaded to: {ref['path']}")
+        print(f"Tokens saved: {ref['tokens_saved']}")
+        print(f"\nReference for context:\n{scratch.format_reference(ref)}")
+
+
+def demo_plan_persistence():
+    """Demonstrate plan persistence pattern."""
+    print("\n" + "=" * 60)
+    print("DEMO: Plan Persistence for Long-Horizon Tasks")
+    print("=" * 60)
+    
+    # Create a plan
+    plan = AgentPlan(objective="Refactor authentication module")
+    plan.steps = [
+        PlanStep(id=1, description="Audit current auth endpoints"),
+        PlanStep(id=2, description="Design new token validation flow"),
+        PlanStep(id=3, description="Implement changes"),
+        PlanStep(id=4, description="Write tests"),
+        PlanStep(id=5, description="Deploy and monitor"),
+    ]
+    
+    print("\nInitial plan:")
+    print(plan.progress_summary())
+    
+    # Save to filesystem
+    plan.save("demo_scratch/current_plan.json")
+    
+    # Simulate completing first step
+    plan.complete_step(1, notes="Found 12 endpoints, 3 need updates")
+    plan.steps[1].status = "in_progress"
+    
+    print("\nAfter completing step 1:")
+    print(plan.progress_summary())
+    
+    # Save updated plan
+    plan.save("demo_scratch/current_plan.json")
+    
+    # Simulate loading from file (as if in new context)
+    print("\n--- Simulating context refresh ---")
+    loaded_plan = AgentPlan.load("demo_scratch/current_plan.json")
+    print("\nPlan loaded from file:")
+    print(loaded_plan.progress_summary())
+
+
+def demo_tool_handler():
+    """Demonstrate integrated tool output handling."""
+    print("\n" + "=" * 60)
+    print("DEMO: Integrated Tool Output Handler")
+    print("=" * 60)
+    
+    handler = ToolOutputHandler(
+        scratch_pad=ScratchPadManager(base_path="demo_scratch", token_threshold=50)
+    )
+    
+    outputs = [
+        ("calculator", "42"),
+        ("file_read", "Error: File not found"),
+        ("database_query", """
+            Results (250 rows):
+            | id | name | email | created_at | status |
+            |----|------|-------|------------|--------|
+            | 1  | John | j@e.c | 2024-01-01 | active |
+            | 2  | Jane | j@e.c | 2024-01-02 | active |
+            ... (248 more rows) ...
+        """),
+    ]
+    
+    for tool_name, output in outputs:
+        processed = handler.process_output(tool_name, output)
+        print(f"\n{tool_name}:")
+        print(f"  Original length: {len(output)} chars")
+        print(f"  Processed: {processed[:100]}...")
+
+
+def cleanup_demo():
+    """Clean up demo files."""
+    import shutil
+    demo_path = Path("demo_scratch")
+    if demo_path.exists():
+        shutil.rmtree(demo_path)
+        print("\nDemo files cleaned up.")
+
+
+if __name__ == "__main__":
+    demo_scratch_pad()
+    demo_plan_persistence()
+    demo_tool_handler()
+    
+    print("\n" + "=" * 60)
+    print("Cleanup demo files? (y/n): ", end="")
+    # Auto-cleanup for non-interactive runs
+    cleanup_demo()
+

package/dist-docs/Agent-Skills-for-Context-Engineering/skills/hosted-agents/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: hosted-agents
+description: This skill should be used when the user asks to "build background agent", "create hosted coding agent", "set up sandboxed execution", "implement multiplayer agent", or mentions background agents, sandboxed VMs, agent infrastructure, Modal sandboxes, self-spawning agents, or remote coding environments.
+---
+
+# Hosted Agent Infrastructure
+
+Hosted agents run in remote sandboxed environments rather than on local machines. When designed well, they provide unlimited concurrency, consistent execution environments, and multiplayer collaboration. The critical insight is that session speed should be limited only by model provider time-to-first-token, with all infrastructure setup completed before the user starts their session.
+
+## When to Activate
+
+Activate this skill when:
+- Building background coding agents that run independently of user devices
+- Designing sandboxed execution environments for agent workloads
+- Implementing multiplayer agent sessions with shared state
+- Creating multi-client agent interfaces (Slack, Web, Chrome extensions)
+- Scaling agent infrastructure beyond local machine constraints
+- Building systems where agents spawn sub-agents for parallel work
+
+## Core Concepts
+
+Hosted agents address the fundamental limitation of local agent execution: resource contention, environment inconsistency, and single-user constraints. By moving agent execution to remote sandboxed environments, teams gain unlimited concurrency, reproducible environments, and collaborative workflows.
+
+The architecture consists of three layers: sandbox infrastructure for isolated execution, API layer for state management and client coordination, and client interfaces for user interaction across platforms. Each layer has specific design requirements that enable the system to scale.
+
+## Detailed Topics
+
+### Sandbox Infrastructure
+
+**The Core Challenge**
+Spinning up full development environments quickly is the primary technical challenge. Users expect near-instant session starts, but development environments require cloning repositories, installing dependencies, and running build steps.
+
+**Image Registry Pattern**
+Pre-build environment images on a regular cadence (every 30 minutes works well). Each image contains:
+- Cloned repository at a known commit
+- All runtime dependencies installed
+- Initial setup and build commands completed
+- Cached files from running app and test suite once
+
+When starting a session, spin up a sandbox from the most recent image. The repository is at most 30 minutes out of date, making synchronization with the latest code much faster.
+
+**Snapshot and Restore**
+Take filesystem snapshots at key points:
+- After initial image build (base snapshot)
+- When agent finishes making changes (session snapshot)
+- Before sandbox exit for potential follow-up
+
+This enables instant restoration for follow-up prompts without re-running setup.
+
+**Git Configuration for Background Agents**
+Since git operations are not tied to a specific user during image builds:
+- Generate GitHub app installation tokens for repository access during clone
+- Update git config's `user.name` and `user.email` when committing and pushing changes
+- Use the prompting user's identity for commits, not the app identity
+
+**Warm Pool Strategy**
+Maintain a pool of pre-warmed sandboxes for high-volume repositories:
+- Sandboxes are ready before users start sessions
+- Expire and recreate pool entries as new image builds complete
+- Start warming sandbox as soon as user begins typing (predictive warm-up)
+
+### Agent Framework Selection
+
+**Server-First Architecture**
+Choose an agent framework structured as a server first, with TUI and desktop apps as clients. This enables:
+- Multiple custom clients without duplicating agent logic
+- Consistent behavior across all interaction surfaces
+- Plugin systems for extending functionality
+- Event-driven architectures for real-time updates
+
+**Code as Source of Truth**
+Select frameworks where the agent can read its own source code to understand behavior. This is underrated in AI development: having the code as source of truth prevents hallucination about the agent's own capabilities.
+
+**Plugin System Requirements**
+The framework should support plugins that:
+- Listen to tool execution events (e.g., `tool.execute.before`)
+- Block or modify tool calls conditionally
+- Inject context or state at runtime
+
+### Speed Optimizations
+
+**Predictive Warm-Up**
+Start warming the sandbox as soon as a user begins typing their prompt:
+- Clone latest changes in parallel with user typing
+- Run initial setup before user hits enter
+- For fast spin-up, sandbox can be ready before user finishes typing
+
+**Parallel File Reading**
+Allow the agent to start reading files immediately, even if sync from latest base branch is not complete:
+- In large repositories, incoming prompts rarely modify recently-changed files
+- Agent can research immediately without waiting for git sync
+- Block file edits (not reads) until synchronization completes
+
+**Maximize Build-Time Work**
+Move everything possible to the image build step:
+- Full dependency installation
+- Database schema setup
+- Initial app and test suite runs (populates caches)
+- Build-time duration is invisible to users
+
+### Self-Spawning Agents
+
+**Agent-Spawned Sessions**
+Create tools that allow agents to spawn new sessions:
+- Research tasks across different repositories
+- Parallel subtask execution for large changes
+- Multiple smaller PRs from one major task
+
+Frontier models are capable of containing themselves. The tools should:
+- Start a new session with specified parameters
+- Read status of any session (check-in capability)
+- Continue main work while sub-sessions run in parallel
+
+**Prompt Engineering for Self-Spawning**
+Engineer prompts to guide when agents spawn sub-sessions:
+- Research tasks that require cross-repository exploration
+- Breaking monolithic changes into smaller PRs
+- Parallel exploration of different approaches
+
+### API Layer
+
+**Per-Session State Isolation**
+Each session requires its own isolated state storage:
+- Dedicated database per session (SQLite per session works well)
+- No session can impact another's performance
+- Handles hundreds of concurrent sessions
+
+**Real-Time Streaming**
+Agent work involves high-frequency updates:
+- Token streaming from model providers
+- Tool execution status updates
+- File change notifications
+
+WebSocket connections with hibernation APIs reduce compute costs during idle periods while maintaining open connections.
+
+**Synchronization Across Clients**
+Build a single state system that synchronizes across:
+- Chat interfaces
+- Slack bots
+- Chrome extensions
+- Web interfaces
+- VS Code instances
+
+All changes sync to the session state, enabling seamless client switching.
+
+### Multiplayer Support
+
+**Why Multiplayer Matters**
+Multiplayer enables:
+- Teaching non-engineers to use AI effectively
+- Live QA sessions with multiple team members
+- Real-time PR review with immediate changes
+- Collaborative debugging sessions
+
+**Implementation Requirements**
+- Data model must not tie sessions to single authors
+- Pass authorship info to each prompt
+- Attribute code changes to the prompting user
+- Share session links for instant collaboration
+
+With proper synchronization architecture, multiplayer support is nearly free to add.
+
+### Authentication and Authorization
+
+**User-Based Commits**
+Use GitHub authentication to:
+- Obtain user tokens for PR creation
+- Open PRs on behalf of the user (not the app)
+- Prevent users from approving their own changes
+
+**Sandbox-to-API Flow**
+1. Sandbox pushes changes (updating git user config)
+2. Sandbox sends event to API with branch name and session ID
+3. API uses user's GitHub token to create PR
+4. GitHub webhooks notify API of PR events
+
+### Client Implementations
+
+**Slack Integration**
+The most effective distribution channel for internal adoption:
+- Creates virality loop as team members see others using it
+- No syntax required, natural chat interface
+- Classify repository from message, thread context, and channel name
+
+Build a classifier to determine which repository to work in:
+- Fast model with descriptions of available repositories
+- Include hints for common repositories
+- Allow "unknown" option for ambiguous cases
+
+**Web Interface**
+Core features:
+- Works on desktop and mobile
+- Real-time streaming of agent work
+- Hosted VS Code instance running inside sandbox
+- Streamed desktop view for visual verification
+- Before/after screenshots for PRs
+
+Statistics page showing:
+- Sessions resulting in merged PRs (primary metric)
+- Usage over time
+- Live "humans prompting" count (prompts in last 5 minutes)
+
+**Chrome Extension**
+For non-engineering users:
+- Sidebar chat interface with screenshot tool
+- DOM and React internals extraction instead of raw images
+- Reduces token usage while maintaining precision
+- Distribute via managed device policy (bypasses Chrome Web Store)
+
+## Practical Guidance
+
+### Follow-Up Message Handling
+
+Decide how to handle messages sent during execution:
+- **Queue approach**: Messages wait until current prompt completes
+- **Insert approach**: Messages are processed immediately
+
+Queueing is simpler to manage and lets users send thoughts on next steps while agent works. Build mechanism to stop agent mid-execution when needed.
+
+### Metrics That Matter
+
+Track metrics that indicate real value:
+- Sessions resulting in merged PRs (primary success metric)
+- Time from session start to first model response
+- PR approval rate and revision count
+- Agent-written code percentage across repositories
+
+### Adoption Strategy
+
+Internal adoption patterns that work:
+- Work in public spaces (Slack channels) for visibility
+- Let the product create virality loops
+- Don't force usage over existing tools
+- Build to people's needs, not hypothetical requirements
+
+## Guidelines
+
+1. Pre-build environment images on regular cadence (30 minutes is a good default)
+2. Start warming sandboxes when users begin typing, not when they submit
+3. Allow file reads before git sync completes; block only writes
+4. Structure agent framework as server-first with clients as thin wrappers
+5. Isolate state per session to prevent cross-session interference
+6. Attribute commits to the user who prompted, not the app
+7. Track merged PRs as primary success metric
+8. Build for multiplayer from the start; it is nearly free with proper sync architecture
+
+## Integration
+
+This skill builds on multi-agent-patterns for agent coordination and tool-design for agent-tool interfaces. It connects to:
+
+- multi-agent-patterns - Self-spawning agents follow supervisor patterns
+- tool-design - Building tools for agent spawning and status checking
+- context-optimization - Managing context across distributed sessions
+- filesystem-context - Using filesystem for session state and artifacts
+
+## References
+
+Internal reference:
+- [Infrastructure Patterns](./references/infrastructure-patterns.md) - Detailed implementation patterns
+
+Related skills in this collection:
+- multi-agent-patterns - Coordination patterns for self-spawning agents
+- tool-design - Designing tools for hosted environments
+- context-optimization - Managing context in distributed systems
+
+External resources:
+- [Ramp](https://builders.ramp.com/post/why-we-built-our-background-agent) - Why We Built Our Own Background Agent
+- [Modal Sandboxes](https://modal.com/docs/guide/sandbox) - Cloud sandbox infrastructure
+- [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/) - Per-session state management
+- [OpenCode](https://github.com/sst/opencode) - Server-first agent framework
+
+---
+
+## Skill Metadata
+
+**Created**: 2026-01-12
+**Last Updated**: 2026-01-12
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 1.0.0