agent-scope 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-scope contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,312 @@
+# agent-scope
+
+> **Deterministic, local, passive execution observer for AI agent workflows**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
+[![Test Coverage](https://img.shields.io/badge/coverage-98.33%25-brightgreen)](https://vitest.dev/)
+
+agent-scope is a lightweight, file-based execution observer for AI agent workflows. It provides real-time visibility into task progress, dependencies, and completion status without requiring databases, authentication, or cloud infrastructure.
+
+## Features
+
+- 🎯 **Deterministic** - Pure function state computation from files
+- 📁 **File-based** - No database, just markdown + JSONL
+- 👀 **Observer-only** - Passive monitoring, not an agent wrapper
+- 🤖 **Model-agnostic** - Works with any AI agent or framework
+- 📊 **Real-time dashboard** - Track progress, blockers, and failures
+- 🔒 **Local-first** - All data stays on your machine
+- ✅ **Type-safe** - Built with TypeScript in strict mode
+
+## Installation
+
+```bash
+npm install -g agent-scope
+```
+
+Or use directly with npx:
+
+```bash
+npx agent-scope init
+```
+
+## Quick Start
+
+### 1. Initialize in your project
+
+```bash
+npx agent-scope init
+```
+
+This creates a `.agent-scope/` directory with:
+- `queue.md` - Task definitions in markdown
+- `execution.log` - JSONL event log
+- `config.json` - Configuration
+
+### 2. Define your task queue
+
+Edit `.agent-scope/queue.md`:
+
+```markdown
+# Slice S1
+
+## S1-T1
+Area: Backend
+Depends: -
+Description: Setup database schema
+AC: Tables created and migrations run
+
+## S1-T2
+Area: Backend
+Depends: S1-T1
+Description: Implement user authentication
+AC: Login and registration endpoints working
+```
+
+### 3. Log task completion
+
+Your agent writes to `.agent-scope/execution.log`:
+
+```json
+{"task_id":"S1-T1","status":"DONE","timestamp":"2026-02-16T14:31:22Z","agent":"claude"}
+{"task_id":"S1-T2","status":"FAILED","timestamp":"2026-02-16T14:33:10Z","agent":"claude","meta":{"reason":"timeout"}}
+```
+
+### 4. Start the dashboard
+
+```bash
+npx agent-scope start
+```
+
+Opens `http://localhost:4317` with live progress visualization.
+
+## Dashboard Features
+
+### Executive Summary
+- Total tasks, done, failed, blocked, ready counts
+- Overall success rate calculation
+- Last updated timestamp
+
+### Slice Progress
+- Visual progress bars per slice
+- Percentage completion tracking
+- Task distribution breakdown
+
+### Task Table
+- Filter by status (READY, BLOCKED, DONE, FAILED)
+- View dependencies and blockers
+- Click any task for full details
+
+### Task Details
+- Acceptance criteria
+- Dependency graph
+- Reverse dependencies (who depends on this)
+- Last event information
+
+## Task Queue Format
+
+### Markdown DSL
+
+```markdown
+# Slice S1
+
+## S1-T1
+Area: <category>
+Depends: -                    # No dependencies, or comma-separated IDs
+Description: <what to do>
+AC: <acceptance criteria>
+```
+
+### Validation
+
+agent-scope validates:
+- ✅ All required fields present
+- ✅ No duplicate task IDs
+- ✅ No unknown dependencies
+- ✅ No circular dependencies (DFS detection)
+
+## Execution Log Format
+
+### JSONL Schema
+
+```typescript
+{
+  "task_id": "S1-T1",           // Required: matches task in queue
+  "status": "DONE" | "FAILED",  // Required: outcome
+  "timestamp": "ISO-8601",      // Required: when it happened
+  "agent": "string",            // Required: agent name
+  "meta": {...}                 // Optional: additional context
+}
+```
+
+### Behavior
+
+- Latest event per task wins (by timestamp)
+- Invalid lines collected as warnings
+- Malformed JSON doesn't crash the system
+
+## Architecture
+
+### Core Principles
+
+1. **Deterministic** - Same inputs always produce same output
+2. **Stateless** - Server recomputes on every request (no cache in v0.1)
+3. **Error-tolerant** - Collects errors instead of crashing
+4. **Type-safe** - Strict TypeScript throughout
+
+### Status Computation
+
+```
+For each task:
+  if lastEvent.status === FAILED → FAILED
+  else if lastEvent.status === DONE → DONE
+  else if any dependency.status !== DONE → BLOCKED
+  else → READY
+```
+
+Priority: `FAILED > DONE > BLOCKED > READY`
+
+### Tech Stack
+
+- **Language**: TypeScript (strict mode)
+- **CLI**: Commander
+- **Server**: Fastify
+- **UI**: Next.js App Router + Tailwind CSS
+- **Testing**: Vitest (98.33% coverage)
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/yourusername/agent-scope.git
+cd agent-scope
+npm install
+cd dashboard && npm install && cd ..
+```
+
+### Build
+
+```bash
+npm run build        # Builds core + dashboard
+npm run build:core   # Only TypeScript
+npm run build:dashboard  # Only Next.js UI
+```
+
+### Test
+
+```bash
+npm test                 # Run tests in watch mode
+npm run test:coverage    # Generate coverage report
+```
+
+### Project Structure
+
+```
+agent-scope/
+├─ src/
+│   ├─ core/
+│   │   ├─ types.ts           # Domain model
+│   │   ├─ queueParser.ts     # Markdown parser
+│   │   ├─ logParser.ts       # JSONL parser
+│   │   └─ stateEngine.ts     # Snapshot computation
+│   ├─ server/
+│   │   └─ server.ts          # Fastify API
+│   └─ cli.ts                 # Commander CLI
+├─ tests/core/                # Unit tests (62 tests)
+├─ dashboard/                 # Next.js UI
+│   └─ src/
+│       ├─ app/               # App Router pages
+│       └─ components/        # React components
+├─ dist/                      # Build output
+└─ .agent-scope/              # Created by init (gitignored)
+```
+
+## API Reference
+
+### `GET /snapshot`
+
+Returns current system state:
+
+```typescript
+{
+  snapshot: Snapshot | null,
+  queueErrors: string[],      // Fatal queue parse errors
+  logErrors: string[],        // Non-fatal log warnings
+  meta: {
+    generatedAt: string,      // ISO-8601
+    totalTasks: number
+  }
+}
+```
+
+### `GET /health`
+
+Health check endpoint:
+
+```json
+{"status": "ok"}
+```
+
+## Use Cases
+
+- **AI Agent Development** - Monitor multi-step agent workflows
+- **Task Automation** - Track long-running automation pipelines
+- **Project Management** - Visualize task dependencies and progress
+- **Testing** - Observe test execution flows
+- **CI/CD Monitoring** - Track deployment task completion
+
+## Non-Goals (v0.1)
+
+- ❌ Real-time streaming (manual refresh only)
+- ❌ Agent execution wrapper
+- ❌ Git integration
+- ❌ SaaS/cloud mode
+- ❌ Authentication
+- ❌ Task editing UI
+- ❌ WebSocket updates
+
+agent-scope is an **observer**, not an orchestrator. It watches your workflow, it doesn't run it.
+
+## Roadmap
+
+### v0.2 (Planned)
+- Incremental state updates
+- File watching for auto-refresh
+- Export reports (JSON, CSV)
+- Performance optimizations
+
+### v0.3 (Planned)
+- Historical snapshots
+- Time-series progress tracking
+- Multiple project support
+- Search and filters
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing`)
+3. Write tests for new functionality
+4. Ensure `npm test` passes with 95%+ coverage
+5. Submit a pull request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+## Credits
+
+Built with ❤️ by the agent-scope team
+
+Powered by:
+- [TypeScript](https://www.typescriptlang.org/)
+- [Fastify](https://www.fastify.io/)
+- [Next.js](https://nextjs.org/)
+- [Commander](https://github.com/tj/commander.js)
+- [Vitest](https://vitest.dev/)
+
+---
+
+**Note**: This is v0.1 - a minimal viable product focused on core functionality. Features are intentionally limited to ensure stability and simplicity.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { mkdirSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { exec } from 'child_process';
+import { startServer } from './server/server.js';
+const program = new Command();
+program
+    .name('agent-scope')
+    .description('Deterministic, local, passive execution observer for AI agent workflows')
+    .version('0.1.0');
+program
+    .command('init')
+    .description('Initialize agent-scope in current directory')
+    .action(() => {
+    const agentScopeDir = join(process.cwd(), '.agent-scope');
+    // Create .agent-scope/ directory
+    if (existsSync(agentScopeDir)) {
+        console.log('⚠️  .agent-scope/ already exists');
+        process.exit(1);
+    }
+    try {
+        mkdirSync(agentScopeDir);
+        console.log('✓ Created .agent-scope/ folder');
+        // Create queue.md template
+        const queueTemplate = `# Slice S1
+
+## S1-T1
+Area: Core
+Depends: -
+Description: First task
+AC: Task completed successfully
+`;
+        writeFileSync(join(agentScopeDir, 'queue.md'), queueTemplate);
+        console.log('✓ Created queue.md template');
+        // Create empty execution.log
+        writeFileSync(join(agentScopeDir, 'execution.log'), '');
+        console.log('✓ Created execution.log');
+        // Create config.json
+        const config = {
+            queueFile: 'queue.md',
+            logFile: 'execution.log',
+            port: 4317
+        };
+        writeFileSync(join(agentScopeDir, 'config.json'), JSON.stringify(config, null, 2));
+        console.log('✓ Created config.json');
+        // Generate Claude.md snippet
+        const claudeMdSnippet = `
+# Agent Scope Integration
+
+When working on tasks, log your progress to \`.agent-scope/execution.log\`:
+
+## Log Format (JSONL)
+
+Each completed task should be logged as a single line:
+
+\`\`\`json
+{"task_id":"S1-T1","status":"DONE","timestamp":"2026-02-16T14:31:22Z","agent":"claude"}
+\`\`\`
+
+Or for failures:
+
+\`\`\`json
+{"task_id":"S1-T2","status":"FAILED","timestamp":"2026-02-16T14:33:10Z","agent":"claude","meta":{"reason":"timeout"}}
+\`\`\`
+
+## Required Fields
+
+- \`task_id\`: Task identifier from queue.md (e.g., "S1-T1")
+- \`status\`: Either "DONE" or "FAILED"
+- \`timestamp\`: ISO-8601 timestamp (use \`new Date().toISOString()\`)
+- \`agent\`: Your agent name (e.g., "claude")
+- \`meta\`: (Optional) Additional context
+
+Run \`npx agent-scope start\` to view the dashboard.
+`;
+        console.log('✓ Ready to use! Add this to your Claude.md:\n');
+        console.log(claudeMdSnippet);
+    }
+    catch (error) {
+        console.error('❌ Failed to initialize:', error);
+        process.exit(1);
+    }
+});
+program
+    .command('start')
+    .description('Start the agent-scope server and dashboard')
+    .action(async () => {
+    const agentScopeDir = join(process.cwd(), '.agent-scope');
+    // Verify .agent-scope/ exists
+    if (!existsSync(agentScopeDir)) {
+        console.error('❌ .agent-scope/ not found. Run "agent-scope init" first.');
+        process.exit(1);
+    }
+    // Read config
+    const configPath = join(agentScopeDir, 'config.json');
+    if (!existsSync(configPath)) {
+        console.error('❌ config.json not found in .agent-scope/');
+        process.exit(1);
+    }
+    let config;
+    try {
+        const configContent = await import('fs').then(fs => fs.promises.readFile(configPath, 'utf-8'));
+        config = JSON.parse(configContent);
+    }
+    catch (error) {
+        console.error('❌ Failed to read config.json:', error);
+        process.exit(1);
+    }
+    const port = config.port || 4317;
+    const url = `http://localhost:${port}`;
+    try {
+        // Start server
+        await startServer(agentScopeDir, port);
+        console.log(`✓ Server running on ${url}`);
+        console.log('✓ Opening browser...');
+        // Auto-open browser
+        const platform = process.platform;
+        const openCommand = platform === 'darwin' ? 'open' :
+            platform === 'win32' ? 'start' :
+                'xdg-open';
+        exec(`${openCommand} ${url}`, (error) => {
+            if (error) {
+                console.log('Could not auto-open browser. Please visit:', url);
+            }
+        });
+    }
+    catch (error) {
+        console.error('❌ Failed to start server:', error);
+        process.exit(1);
+    }
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/core/logParser.d.ts

@@ -0,0 +1,11 @@
+import type { LogEvent } from './types.js';
+export interface LogParseResult {
+    events: LogEvent[];
+    errors: string[];
+}
+/**
+ * Parses a JSONL execution log file.
+ * Keeps only the latest event per task based on ISO-8601 timestamp comparison.
+ */
+export declare function parseLog(content: string): LogParseResult;
+//# sourceMappingURL=logParser.d.ts.map

package/dist/core/logParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logParser.d.ts","sourceRoot":"","sources":["../../src/core/logParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CA4CxD"}

package/dist/core/logParser.js

@@ -0,0 +1,103 @@
+/**
+ * Parses a JSONL execution log file.
+ * Keeps only the latest event per task based on ISO-8601 timestamp comparison.
+ */
+export function parseLog(content) {
+    const errors = [];
+    const eventsByTask = new Map();
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        const lineNumber = i + 1;
+        // Skip empty lines
+        if (!line) {
+            continue;
+        }
+        // Try to parse JSON
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            errors.push(`Line ${lineNumber}: Invalid JSON`);
+            continue;
+        }
+        // Validate schema
+        const validation = validateLogEvent(parsed, lineNumber);
+        if (validation.errors.length > 0) {
+            errors.push(...validation.errors);
+            continue;
+        }
+        const event = validation.event;
+        // Keep only latest event per task
+        const existing = eventsByTask.get(event.task_id);
+        if (!existing || event.timestamp > existing.timestamp) {
+            eventsByTask.set(event.task_id, event);
+        }
+    }
+    return {
+        events: Array.from(eventsByTask.values()),
+        errors
+    };
+}
+/**
+ * Validates that an object conforms to the LogEvent schema.
+ */
+function validateLogEvent(obj, lineNumber) {
+    const errors = [];
+    if (typeof obj !== 'object' || obj === null) {
+        errors.push(`Line ${lineNumber}: Event must be an object`);
+        return { event: null, errors };
+    }
+    const event = obj;
+    // Validate task_id
+    if (typeof event.task_id !== 'string' || !event.task_id) {
+        errors.push(`Line ${lineNumber}: Missing or invalid task_id`);
+    }
+    // Validate status
+    if (event.status !== 'DONE' && event.status !== 'FAILED') {
+        errors.push(`Line ${lineNumber}: Invalid status (must be DONE or FAILED)`);
+    }
+    // Validate timestamp
+    if (typeof event.timestamp !== 'string' || !isValidISO8601(event.timestamp)) {
+        errors.push(`Line ${lineNumber}: Missing or invalid timestamp (must be ISO-8601)`);
+    }
+    // Validate agent
+    if (typeof event.agent !== 'string' || !event.agent) {
+        errors.push(`Line ${lineNumber}: Missing or invalid agent`);
+    }
+    // Validate meta (optional)
+    if (event.meta !== undefined) {
+        if (typeof event.meta !== 'object' || event.meta === null || Array.isArray(event.meta)) {
+            errors.push(`Line ${lineNumber}: meta must be an object if provided`);
+        }
+    }
+    if (errors.length > 0) {
+        return { event: null, errors };
+    }
+    // At this point, all validations passed, so we can safely construct a LogEvent
+    const validEvent = {
+        task_id: event.task_id,
+        status: event.status,
+        timestamp: event.timestamp,
+        agent: event.agent,
+        ...(event.meta !== undefined && { meta: event.meta })
+    };
+    return {
+        event: validEvent,
+        errors: []
+    };
+}
+/**
+ * Basic ISO-8601 timestamp validation.
+ */
+function isValidISO8601(timestamp) {
+    // Check basic format and that it can be parsed as a date
+    const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z?$/;
+    if (!iso8601Regex.test(timestamp)) {
+        return false;
+    }
+    const date = new Date(timestamp);
+    return !isNaN(date.getTime());
+}
+//# sourceMappingURL=logParser.js.map

package/dist/core/logParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logParser.js","sourceRoot":"","sources":["../../src/core/logParser.ts"],"names":[],"mappings":"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"}

package/dist/core/queueParser.d.ts

@@ -0,0 +1,11 @@
+import type { Task } from './types.js';
+export interface QueueParseResult {
+    tasks: Task[];
+    errors: string[];
+}
+/**
+ * Parses a markdown queue file into structured tasks.
+ * Returns both tasks and any validation errors encountered.
+ */
+export declare function parseQueue(content: string): QueueParseResult;
+//# sourceMappingURL=queueParser.d.ts.map

package/dist/core/queueParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queueParser.d.ts","sourceRoot":"","sources":["../../src/core/queueParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAmH5D"}