1# Infrastructure Patterns for Hosted Agents
2 
3This reference provides detailed implementation patterns for building hosted agent infrastructure. These patterns are derived from production systems at scale.
4 
5## Sandbox Architecture
6 
7### Modal Integration Pattern
8 
9Modal provides the sandbox infrastructure with near-instant startup and filesystem snapshots.
10 
11```python
12import modal
13 
14# Define the base image with all dependencies
15image = modal.Image.debian_slim().pip_install([
16    "opencode",
17    "gitpython",
18    "psycopg2-binary",
19])
20 
21# Create the app
22app = modal.App("coding-agent")
23 
24# Sandbox class with snapshot support
25@app.cls(image=image, timeout=3600)
26class AgentSandbox:
27    def __init__(self, repo_url: str, snapshot_id: str = None):
28        self.repo_url = repo_url
29        self.snapshot_id = snapshot_id
30    
31    @modal.enter()
32    def setup(self):
33        if self.snapshot_id:
34            # Restore from snapshot
35            modal.Sandbox.restore(self.snapshot_id)
36        else:
37            # Fresh setup from image
38            self._clone_and_setup()
39    
40    def _clone_and_setup(self):
41        """Clone repo and run initial setup."""
42        token = self._get_github_app_token()
43        os.system(f"git clone https://x-access-token:{token}@github.com/{self.repo_url}")
44        os.system("npm install")
45        os.system("npm run build")
46    
47    @modal.method()
48    def execute_prompt(self, prompt: str, user_identity: dict) -> dict:
49        """Execute a prompt in the sandbox."""
50        # Update git config for this user
51        os.system(f'git config user.name "{user_identity["name"]}"')
52        os.system(f'git config user.email "{user_identity["email"]}"')
53        
54        # Run the agent
55        result = self.agent.run(prompt)
56        
57        return {
58            "result": result,
59            "snapshot_id": modal.Sandbox.snapshot()
60        }
61```
62 
63### Image Build Pipeline
64 
65Build images on a schedule to keep them fresh:
66 
67```python
68import schedule
69import time
70from datetime import datetime
71 
72class ImageBuilder:
73    def __init__(self, repositories: list[str]):
74        self.repositories = repositories
75        self.images = {}
76    
77    def build_all_images(self):
78        """Build images for all repositories."""
79        for repo in self.repositories:
80            try:
81                image = self._build_image(repo)
82                self.images[repo] = {
83                    "image": image,
84                    "built_at": datetime.utcnow(),
85                    "commit": self._get_latest_commit(repo)
86                }
87            except Exception as e:
88                # Log but continue with other repos
89                log.error(f"Failed to build image for {repo}: {e}")
90    
91    def _build_image(self, repo: str) -> str:
92        """Build a single repository image."""
93        sandbox = modal.Sandbox.create()
94        
95        # Clone with app token
96        token = get_app_installation_token(repo)
97        sandbox.exec(f"git clone https://x-access-token:{token}@github.com/{repo} /workspace")
98        
99        # Install dependencies
100        sandbox.exec("cd /workspace && npm install")
101        
102        # Run build
103        sandbox.exec("cd /workspace && npm run build")
104        
105        # Warm caches
106        sandbox.exec("cd /workspace && npm run dev &")
107        time.sleep(5)  # Let dev server start
108        sandbox.exec("cd /workspace && npm test -- --run")
109        
110        # Create snapshot
111        return sandbox.snapshot()
112    
113    def get_latest_image(self, repo: str) -> str:
114        """Get the most recent image for a repository."""
115        if repo not in self.images:
116            raise ValueError(f"No image available for {repo}")
117        return self.images[repo]["image"]
118 
119# Schedule builds every 30 minutes
120builder = ImageBuilder(["org/frontend", "org/backend", "org/shared"])
121schedule.every(30).minutes.do(builder.build_all_images)
122```
123 
124### Warm Pool Management
125 
126Maintain pre-warmed sandboxes for instant session starts:
127 
128```python
129from collections import defaultdict
130from dataclasses import dataclass
131from datetime import datetime, timedelta
132 
133@dataclass
134class WarmSandbox:
135    sandbox_id: str
136    repo: str
137    created_at: datetime
138    image_version: str
139    is_claimed: bool = False
140 
141class WarmPoolManager:
142    def __init__(self, target_pool_size: int = 3):
143        self.target_size = target_pool_size
144        self.pools = defaultdict(list)  # repo -> [WarmSandbox]
145        self.max_age = timedelta(minutes=25)  # Expire before next image build
146    
147    def get_warm_sandbox(self, repo: str) -> WarmSandbox | None:
148        """Get a pre-warmed sandbox if available."""
149        pool = self.pools[repo]
150        
151        for sandbox in pool:
152            if not sandbox.is_claimed and self._is_valid(sandbox):
153                sandbox.is_claimed = True
154                return sandbox
155        
156        return None
157    
158    def _is_valid(self, sandbox: WarmSandbox) -> bool:
159        """Check if sandbox is still valid."""
160        age = datetime.utcnow() - sandbox.created_at
161        current_image = self.image_builder.get_latest_image(sandbox.repo)
162        
163        return (
164            age < self.max_age and
165            sandbox.image_version == current_image
166        )
167    
168    def maintain_pool(self, repo: str):
169        """Ensure pool has target number of warm sandboxes."""
170        # Remove expired sandboxes
171        self.pools[repo] = [s for s in self.pools[repo] if self._is_valid(s)]
172        
173        # Add new sandboxes to reach target
174        current_count = len([s for s in self.pools[repo] if not s.is_claimed])
175        needed = self.target_size - current_count
176        
177        for _ in range(needed):
178            sandbox = self._create_warm_sandbox(repo)
179            self.pools[repo].append(sandbox)
180    
181    def _create_warm_sandbox(self, repo: str) -> WarmSandbox:
182        """Create a new warm sandbox from latest image."""
183        image = self.image_builder.get_latest_image(repo)
184        sandbox_id = modal.Sandbox.create(image=image)
185        
186        # Sync to latest (runs in background)
187        self._sync_to_latest(sandbox_id, repo)
188        
189        return WarmSandbox(
190            sandbox_id=sandbox_id,
191            repo=repo,
192            created_at=datetime.utcnow(),
193            image_version=image
194        )
195```
196 
197## API Layer Patterns
198 
199### Cloudflare Durable Objects for Session State
200 
201Each session gets its own Durable Object with isolated SQLite:
202 
203```typescript
204// Session Durable Object
205export class SessionDO implements DurableObject {
206  private storage: DurableObjectStorage;
207  private sql: SqlStorage;
208  private connections: Map<string, WebSocket> = new Map();
209 
210  constructor(ctx: DurableObjectState) {
211    this.storage = ctx.storage;
212    this.sql = ctx.storage.sql;
213    this.initializeSchema();
214  }
215 
216  private initializeSchema() {
217    this.sql.exec(`
218      CREATE TABLE IF NOT EXISTS messages (
219        id INTEGER PRIMARY KEY,
220        role TEXT NOT NULL,
221        content TEXT NOT NULL,
222        author_id TEXT,
223        author_name TEXT,
224        created_at TEXT DEFAULT CURRENT_TIMESTAMP
225      );
226      
227      CREATE TABLE IF NOT EXISTS artifacts (
228        id INTEGER PRIMARY KEY,
229        type TEXT NOT NULL,
230        path TEXT,
231        content TEXT,
232        created_at TEXT DEFAULT CURRENT_TIMESTAMP
233      );
234      
235      CREATE TABLE IF NOT EXISTS events (
236        id INTEGER PRIMARY KEY,
237        type TEXT NOT NULL,
238        data TEXT,
239        created_at TEXT DEFAULT CURRENT_TIMESTAMP
240      );
241    `);
242  }
243 
244  async fetch(request: Request): Promise<Response> {
245    const url = new URL(request.url);
246 
247    if (request.headers.get("Upgrade") === "websocket") {
248      return this.handleWebSocket(request);
249    }
250 
251    switch (url.pathname) {
252      case "/message":
253        return this.handleMessage(request);
254      case "/status":
255        return this.getStatus();
256      default:
257        return new Response("Not found", { status: 404 });
258    }
259  }
260 
261  private handleWebSocket(request: Request): Response {
262    const pair = new WebSocketPair();
263    const [client, server] = Object.values(pair);
264 
265    const connectionId = crypto.randomUUID();
266    this.connections.set(connectionId, server);
267 
268    server.accept();
269    server.addEventListener("close", () => {
270      this.connections.delete(connectionId);
271    });
272 
273    return new Response(null, { status: 101, webSocket: client });
274  }
275 
276  private broadcast(message: object) {
277    const data = JSON.stringify(message);
278    for (const ws of this.connections.values()) {
279      ws.send(data);
280    }
281  }
282 
283  async handleMessage(request: Request): Promise<Response> {
284    const { content, author } = await request.json();
285 
286    // Store message
287    this.sql.exec(
288      `INSERT INTO messages (role, content, author_id, author_name) VALUES (?, ?, ?, ?)`,
289      ["user", content, author.id, author.name]
290    );
291 
292    // Broadcast to all connected clients
293    this.broadcast({
294      type: "message",
295      role: "user",
296      content,
297      author,
298    });
299 
300    // Forward to sandbox for processing
301    const result = await this.forwardToSandbox(content, author);
302 
303    return Response.json(result);
304  }
305}
306```
307 
308### Real-Time Event Streaming
309 
310Stream events from sandbox to all connected clients:
311 
312```typescript
313class EventStream {
314  private sessionDO: DurableObjectStub;
315 
316  async streamFromSandbox(sandboxId: string, sessionId: string) {
317    const sandbox = await modal.Sandbox.get(sandboxId);
318 
319    // Subscribe to sandbox events
320    for await (const event of sandbox.events()) {
321      // Forward to Durable Object for broadcast
322      await this.sessionDO.fetch(
323        new Request(`https://internal/event`, {
324          method: "POST",
325          body: JSON.stringify({
326            type: event.type,
327            data: event.data,
328          }),
329        })
330      );
331    }
332  }
333}
334```
335 
336## Client Integration Patterns
337 
338### Slack Bot with Repository Classification
339 
340```python
341from slack_bolt import App
342from slack_bolt.adapter.socket_mode import SocketModeHandler
343 
344app = App(token=os.environ["SLACK_BOT_TOKEN"])
345 
346# Repository descriptions for classification
347REPO_DESCRIPTIONS = [
348    {
349        "name": "frontend-monorepo",
350        "description": "React frontend application with dashboard, user portal, and admin interfaces",
351        "hints": ["dashboard", "UI", "component", "page", "frontend"]
352    },
353    {
354        "name": "backend-services",
355        "description": "Node.js API services including auth, payments, and core business logic",
356        "hints": ["API", "endpoint", "service", "backend", "database"]
357    },
358    {
359        "name": "mobile-app",
360        "description": "React Native mobile application for iOS and Android",
361        "hints": ["mobile", "app", "iOS", "Android", "native"]
362    }
363]
364 
365async def classify_repository(message: str, channel: str, thread: list[str]) -> str:
366    """Use fast model to classify which repo the message refers to."""
367    prompt = f"""Classify which repository this message is about.
368 
369Message: {message}
370Channel: #{channel}
371Thread context: {' | '.join(thread[-3:])}
372 
373Repositories:
374{json.dumps(REPO_DESCRIPTIONS, indent=2)}
375 
376Return ONLY the repository name, or "unknown" if unclear."""
377 
378    response = await openai.chat.completions.create(
379        model="gpt-4o-mini",
380        messages=[{"role": "user", "content": prompt}],
381        max_tokens=50
382    )
383    
384    return response.choices[0].message.content.strip()
385 
386@app.event("app_mention")
387async def handle_mention(event, say, client):
388    """Handle @mentions of the bot."""
389    channel = event["channel"]
390    message = event["text"]
391    thread_ts = event.get("thread_ts", event["ts"])
392    
393    # Get thread context if in a thread
394    thread_messages = []
395    if "thread_ts" in event:
396        result = await client.conversations_replies(
397            channel=channel,
398            ts=thread_ts
399        )
400        thread_messages = [m["text"] for m in result["messages"]]
401    
402    # Get channel info for context
403    channel_info = await client.conversations_info(channel=channel)
404    channel_name = channel_info["channel"]["name"]
405    
406    # Classify repository
407    repo = await classify_repository(message, channel_name, thread_messages)
408    
409    if repo == "unknown":
410        await say(
411            text="I'm not sure which repository you're referring to. Could you specify?",
412            thread_ts=thread_ts
413        )
414        return
415    
416    # Start session and process
417    session = await start_session(repo, event["user"])
418    
419    await say(
420        text=f":robot_face: Starting work in `{repo}`...",
421        thread_ts=thread_ts
422    )
423    
424    result = await session.process(message)
425    
426    # Post result with Block Kit formatting
427    await say(
428        blocks=format_result_blocks(result),
429        thread_ts=thread_ts
430    )
431```
432 
433### Chrome Extension DOM Extraction
434 
435Extract DOM structure instead of sending screenshots:
436 
437```typescript
438// content-script.ts
439interface ElementInfo {
440  tag: string;
441  classes: string[];
442  id?: string;
443  text?: string;
444  rect: DOMRect;
445  reactComponent?: string;
446}
447 
448function extractDOMInfo(element: Element): ElementInfo {
449  // Get React component name if available
450  let reactComponent: string | undefined;
451  const fiberKey = Object.keys(element).find((key) =>
452    key.startsWith("__reactFiber")
453  );
454  if (fiberKey) {
455    const fiber = (element as any)[fiberKey];
456    reactComponent = fiber?.type?.name || fiber?.type?.displayName;
457  }
458 
459  return {
460    tag: element.tagName.toLowerCase(),
461    classes: Array.from(element.classList),
462    id: element.id || undefined,
463    text: element.textContent?.slice(0, 100),
464    rect: element.getBoundingClientRect(),
465    reactComponent,
466  };
467}
468 
469function extractSelectedArea(selection: DOMRect): ElementInfo[] {
470  const elements: ElementInfo[] = [];
471 
472  // Find all elements within selection bounds
473  document.querySelectorAll("*").forEach((el) => {
474    const rect = el.getBoundingClientRect();
475    if (
476      rect.top >= selection.top &&
477      rect.left >= selection.left &&
478      rect.bottom <= selection.bottom &&
479      rect.right <= selection.right
480    ) {
481      elements.push(extractDOMInfo(el));
482    }
483  });
484 
485  return elements;
486}
487 
488// Message handler for sidebar
489chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
490  if (request.type === "EXTRACT_SELECTION") {
491    const elements = extractSelectedArea(request.selection);
492    sendResponse({ elements });
493  }
494});
495```
496 
497## Multiplayer Implementation
498 
499### Authorship Tracking
500 
501Track which user made each change:
502 
503```python
504@dataclass
505class PromptContext:
506    content: str
507    author: Author
508    session_id: str
509    timestamp: datetime
510 
511@dataclass
512class Author:
513    id: str
514    name: str
515    email: str
516    github_token: str  # For PR creation
517 
518class MultiplayerSession:
519    def __init__(self, session_id: str):
520        self.session_id = session_id
521        self.participants: dict[str, Author] = {}
522        self.prompt_queue: list[PromptContext] = []
523    
524    def add_participant(self, author: Author):
525        """Add a participant to the session."""
526        self.participants[author.id] = author
527        self.broadcast_event("participant_joined", author)
528    
529    async def process_prompt(self, prompt: PromptContext):
530        """Process prompt with author attribution."""
531        # Update git config for this author
532        await self.sandbox.exec(
533            f'git config user.name "{prompt.author.name}"'
534        )
535        await self.sandbox.exec(
536            f'git config user.email "{prompt.author.email}"'
537        )
538        
539        # Run agent
540        result = await self.agent.run(prompt.content)
541        
542        # If changes were made, create PR with author's token
543        if result.has_changes:
544            await self.create_pr(
545                branch=result.branch,
546                author=prompt.author
547            )
548        
549        return result
550    
551    async def create_pr(self, branch: str, author: Author):
552        """Create PR using the author's GitHub token."""
553        async with aiohttp.ClientSession() as session:
554            headers = {
555                "Authorization": f"Bearer {author.github_token}",
556                "Accept": "application/vnd.github.v3+json"
557            }
558            
559            await session.post(
560                f"https://api.github.com/repos/{self.repo}/pulls",
561                headers=headers,
562                json={
563                    "title": self.generate_pr_title(),
564                    "body": self.generate_pr_body(),
565                    "head": branch,
566                    "base": "main"
567                }
568            )
569```
570 
571## Metrics and Monitoring
572 
573### Key Metrics to Track
574 
575```python
576from dataclasses import dataclass
577from datetime import datetime, timedelta
578 
579@dataclass
580class SessionMetrics:
581    session_id: str
582    started_at: datetime
583    first_token_at: datetime | None
584    completed_at: datetime | None
585    pr_created: bool
586    pr_merged: bool
587    prompts_count: int
588    participants_count: int
589    
590    @property
591    def time_to_first_token(self) -> timedelta | None:
592        if self.first_token_at:
593            return self.first_token_at - self.started_at
594        return None
595 
596class MetricsAggregator:
597    def get_adoption_metrics(self, period: timedelta) -> dict:
598        """Get adoption metrics for a time period."""
599        sessions = self.get_sessions_in_period(period)
600        
601        total_prs = sum(1 for s in sessions if s.pr_created)
602        merged_prs = sum(1 for s in sessions if s.pr_merged)
603        
604        return {
605            "total_sessions": len(sessions),
606            "prs_created": total_prs,
607            "prs_merged": merged_prs,
608            "merge_rate": merged_prs / total_prs if total_prs > 0 else 0,
609            "avg_time_to_first_token": self._avg_ttft(sessions),
610            "unique_users": len(set(s.author_id for s in sessions)),
611            "multiplayer_sessions": sum(
612                1 for s in sessions if s.participants_count > 1
613            )
614        }
615    
616    def get_repository_metrics(self) -> dict[str, dict]:
617        """Get metrics broken down by repository."""
618        metrics = {}
619        
620        for repo in self.repositories:
621            repo_sessions = self.get_sessions_for_repo(repo)
622            total_prs = self.get_total_prs(repo)
623            agent_prs = sum(1 for s in repo_sessions if s.pr_merged)
624            
625            metrics[repo] = {
626                "agent_pr_percentage": agent_prs / total_prs * 100,
627                "session_count": len(repo_sessions),
628                "avg_prompts_per_session": sum(
629                    s.prompts_count for s in repo_sessions
630                ) / len(repo_sessions)
631            }
632        
633        return metrics
634```
635 
636## Security Considerations
637 
638### Sandbox Isolation
639 
640```python
641class SandboxSecurityConfig:
642    """Security configuration for sandboxes."""
643    
644    # Network restrictions
645    allowed_hosts = [
646        "github.com",
647        "api.github.com",
648        "registry.npmjs.org",
649        "pypi.org",
650    ]
651    
652    # Resource limits
653    max_memory_mb = 4096
654    max_cpu_cores = 2
655    max_disk_gb = 10
656    max_runtime_hours = 4
657    
658    # Secrets handling
659    secrets_to_inject = [
660        "GITHUB_APP_TOKEN",
661        "NPM_TOKEN",
662    ]
663    
664    # Blocked operations
665    blocked_commands = [
666        "curl",  # Use fetch tools instead
667        "wget",
668        "ssh",
669    ]
670```
671 
672### Token Handling
673 
674```python
675class TokenManager:
676    """Manage tokens for GitHub operations."""
677    
678    def get_app_installation_token(self, repo: str) -> str:
679        """Get short-lived token for repo access."""
680        # Token expires in 1 hour
681        return github_app.create_installation_token(
682            installation_id=self.get_installation_id(repo),
683            permissions={"contents": "write", "pull_requests": "write"}
684        )
685    
686    def get_user_token(self, user_id: str) -> str:
687        """Get user's OAuth token for PR creation."""
688        # Stored encrypted, decrypted at runtime
689        encrypted = self.storage.get(f"user_token:{user_id}")
690        return self.decrypt(encrypted)
691```
692 
693## References
694 
695- [Modal Documentation](https://modal.com/docs)
696- [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/)
697- [Cloudflare Agents SDK](https://developers.cloudflare.com/agents/)
698- [GitHub Apps Authentication](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app)
699- [Slack Bolt for Python](https://slack.dev/bolt-python/)
700- [Chrome Extension APIs](https://developer.chrome.com/docs/extensions/)
701