pixelcrew 0.2.3 → 0.2.6

package/src/orchestrator/ui-synthesizer.js

@@ -0,0 +1,245 @@
+/**
+ * PIXEL CREW — Open-World UI Synthesizer
+ * 
+ * Compiles ViewDefinition + EntityDefinition + DesignSpec into high-fidelity,
+ * fully interactive React 18/19 Next.js App Router TSX components.
+ * 
+ * Works for ANY domain dynamically by composing universal UI primitives
+ * (Collection, Table, Form, Timeline, Inspector, Search, Filter).
+ */
+
+import { LAYOUT_PRIMITIVES } from './ontology.js';
+
+export class UISynthesizer {
+  /**
+   * Synthesize a complete TSX component file from a ViewDefinition and its target entities.
+   */
+  static synthesizeViewComponent(view, entities = [], designSpec = {}) {
+    const compName = view.componentName || 'DynamicView';
+    const targetEntityName = (view.targetEntities && view.targetEntities[0]) || (entities[0] ? entities[0].name : 'Item');
+    const entity = entities.find(e => e.name === targetEntityName) || entities[0] || {
+      name: targetEntityName,
+      title: targetEntityName,
+      fields: [
+        { name: 'id', type: 'string', label: 'ID' },
+        { name: 'name', type: 'string', label: 'Name' },
+        { name: 'status', type: 'string', label: 'Status' }
+      ],
+      seedData: []
+    };
+
+    const fields = entity.fields || [];
+    const seedData = entity.seedData || [];
+    const layoutType = (view.layout && view.layout.type) || LAYOUT_PRIMITIVES.SPLIT;
+
+    const isSplit = layoutType === LAYOUT_PRIMITIVES.SPLIT || layoutType === LAYOUT_PRIMITIVES.WORKSPACE;
+
+    return `'use client';
+
+import React, { useState } from 'react';
+import { Search, Filter, Plus, ArrowUpRight, CheckCircle2, AlertCircle, RefreshCw, Download, Database } from 'lucide-react';
+
+export interface ${entity.name}Record {
+${fields.map(f => `  ${f.name}${f.required ? '' : '?'}: ${f.type === 'number' ? 'number' : (f.type === 'boolean' ? 'boolean' : 'string')};`).join('\n')}
+}
+
+const INITIAL_RECORDS: ${entity.name}Record[] = ${JSON.stringify(seedData, null, 2)};
+
+export function ${compName}() {
+  const [records, setRecords] = useState<${entity.name}Record[]>(INITIAL_RECORDS);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [selectedStatus, setSelectedStatus] = useState<string>('ALL');
+  const [selectedRecord, setSelectedRecord] = useState<${entity.name}Record | null>(INITIAL_RECORDS[0] || null);
+  const [isCreating, setIsCreating] = useState(false);
+  const [newTitle, setNewTitle] = useState('');
+
+  const statuses = ['ALL', ...Array.from(new Set(records.map(r => r.status).filter(Boolean)))];
+
+  const filteredRecords = records.filter(record => {
+    const matchesSearch = !searchQuery || 
+      (record.name && record.name.toLowerCase().includes(searchQuery.toLowerCase())) ||
+      (record.id && record.id.toLowerCase().includes(searchQuery.toLowerCase()));
+    const matchesStatus = selectedStatus === 'ALL' || record.status === selectedStatus;
+    return matchesSearch && matchesStatus;
+  });
+
+  const handleCreate = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!newTitle.trim()) return;
+    const newEntry: ${entity.name}Record = {
+      id: '${entity.name.toLowerCase()}-' + String(records.length + 1).padStart(3, '0'),
+      name: newTitle.trim(),
+      status: 'Active',
+      createdAt: new Date().toISOString()
+    };
+    setRecords([newEntry, ...records]);
+    setSelectedRecord(newEntry);
+    setNewTitle('');
+    setIsCreating(false);
+  };
+
+  return (
+    <section id="${view.id || compName.toLowerCase()}" className="py-16 px-6 max-w-7xl mx-auto border-b border-white/10">
+      {/* Header & Controls */}
+      <div className="flex flex-col md:flex-row md:items-end justify-between mb-8 gap-4">
+        <div>
+          <div className="text-xs font-mono text-neutral-400 uppercase tracking-widest mb-2">
+            // ${entity.name.toUpperCase()} REGISTRY & WORKSPACE
+          </div>
+          <h2 className="font-display text-2xl md:text-3xl text-white font-normal">
+            ${view.title || `${entity.title || entity.name} Console`}
+          </h2>
+          <p className="text-sm text-neutral-400 mt-1 max-w-xl font-light">
+            ${view.purpose || `Manage, inspect, and track real-time telemetry across ${entity.plural || entity.name}.`}
+          </p>
+        </div>
+
+        <div className="flex items-center gap-3">
+          <button
+            onClick={() => setIsCreating(!isCreating)}
+            className="flex items-center gap-2 px-4 py-2 bg-white text-black text-xs font-mono font-medium rounded-sm hover:bg-neutral-200 transition-colors"
+          >
+            <Plus className="w-3.5 h-3.5" />
+            New ${entity.name}
+          </button>
+        </div>
+      </div>
+
+      {/* Quick Action Modal / Create Form */}
+      {isCreating && (
+        <form onSubmit={handleCreate} className="mb-8 p-4 bg-brandSurface border border-brandBorder rounded-sm flex items-center gap-4">
+          <input
+            type="text"
+            placeholder="Enter ${entity.name} identifier or name..."
+            value={newTitle}
+            onChange={(e) => setNewTitle(e.target.value)}
+            className="flex-1 bg-brandBg border border-brandBorder px-3 py-2 text-sm text-white rounded-sm focus:outline-none focus:border-white/40"
+            autoFocus
+          />
+          <button
+            type="submit"
+            className="px-4 py-2 bg-emerald-500 text-black text-xs font-mono font-medium rounded-sm hover:bg-emerald-400 transition-colors"
+          >
+            Commit Entry
+          </button>
+          <button
+            type="button"
+            onClick={() => setIsCreating(false)}
+            className="px-3 py-2 text-xs font-mono text-neutral-400 hover:text-white"
+          >
+            Cancel
+          </button>
+        </form>
+      )}
+
+      {/* Filter Bar */}
+      <div className="flex flex-col sm:flex-row items-center justify-between gap-4 mb-6 p-3 bg-brandSurface/40 border border-brandBorder rounded-sm">
+        <div className="relative w-full sm:w-72">
+          <Search className="w-4 h-4 text-neutral-500 absolute left-3 top-2.5" />
+          <input
+            type="text"
+            placeholder="Filter records..."
+            value={searchQuery}
+            onChange={(e) => setSearchQuery(e.target.value)}
+            className="w-full bg-brandBg/80 border border-brandBorder pl-9 pr-3 py-1.5 text-xs text-white rounded-sm focus:outline-none focus:border-white/30"
+          />
+        </div>
+
+        <div className="flex items-center gap-2 w-full sm:w-auto overflow-x-auto">
+          {statuses.map(st => (
+            <button
+              key={st}
+              onClick={() => setSelectedStatus(st)}
+              className={\`px-2.5 py-1 text-xs font-mono rounded-sm transition-colors border \${selectedStatus === st ? 'bg-white text-black border-white font-medium' : 'bg-brandBg text-neutral-400 border-brandBorder hover:text-white'}\`}
+            >
+              {st}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* Main Workspace / View Content */}
+      <div className="${isSplit ? 'grid grid-cols-1 lg:grid-cols-12 gap-6' : 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6'}">
+        {/* Record List / Table */}
+        <div className="${isSplit ? 'lg:col-span-7' : 'col-span-full'} space-y-3">
+          {filteredRecords.length === 0 ? (
+            <div className="p-8 text-center bg-brandSurface/20 border border-dashed border-brandBorder rounded-sm text-neutral-400 text-xs font-mono">
+              No matching ${entity.plural || entity.name} records found.
+            </div>
+          ) : (
+            filteredRecords.map(record => (
+              <div
+                key={record.id}
+                onClick={() => setSelectedRecord(record)}
+                className={\`p-4 rounded-sm border transition-all cursor-pointer \${selectedRecord?.id === record.id ? 'bg-brandSurfaceRaised border-white/40 shadow-sm' : 'bg-brandSurface border-brandBorder hover:border-brandBorderHover'}\`}
+              >
+                <div className="flex items-center justify-between mb-2">
+                  <div className="flex items-center gap-3">
+                    <span className="font-mono text-xs text-neutral-500">{record.id}</span>
+                    <h3 className="text-sm font-medium text-white">{record.name}</h3>
+                  </div>
+                  <span className="text-[10px] font-mono uppercase px-2 py-0.5 rounded-sm bg-white/5 border border-white/10 text-neutral-300">
+                    {record.status || 'Active'}
+                  </span>
+                </div>
+                
+                <div className="grid grid-cols-2 sm:grid-cols-3 gap-2 mt-3 pt-3 border-t border-white/5 text-xs text-neutral-400 font-mono">
+                  ${fields.filter(f => f.name !== 'id' && f.name !== 'name' && f.name !== 'status').slice(0, 3).map(f => `
+                  <div>
+                    <span className="text-neutral-500 block text-[10px]">${f.label}:</span>
+                    <span className="text-neutral-200">{String((record as any)['${f.name}'] || '—')}</span>
+                  </div>`).join('\n')}
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+
+        {/* Inspector Detail Panel (if split layout) */}
+        ${isSplit ? `
+        <div className="lg:col-span-5 bg-brandSurface border border-brandBorder rounded-sm p-6 flex flex-col justify-between">
+          <div>
+            <div className="flex items-center justify-between pb-4 mb-4 border-b border-white/10">
+              <span className="text-xs font-mono text-neutral-400 uppercase tracking-wider">
+                Telemetry Inspector
+              </span>
+              <span className="text-[10px] font-mono text-emerald-400 bg-emerald-500/10 px-2 py-0.5 rounded border border-emerald-500/20">
+                Live Data Link
+              </span>
+            </div>
+
+            {selectedRecord ? (
+              <div className="space-y-4">
+                <div>
+                  <h4 className="text-lg font-display text-white font-normal">{selectedRecord.name}</h4>
+                  <span className="font-mono text-xs text-neutral-500 block mt-0.5">ID: {selectedRecord.id}</span>
+                </div>
+
+                <div className="space-y-3 pt-2">
+                  ${fields.map(f => `
+                  <div className="flex items-center justify-between text-xs py-1.5 border-b border-white/5">
+                    <span className="text-neutral-400 font-mono">${f.label}</span>
+                    <span className="text-neutral-200 font-medium">{String((selectedRecord as any)['${f.name}'] ?? '—')}</span>
+                  </div>`).join('\n')}
+                </div>
+              </div>
+            ) : (
+              <div className="py-12 text-center text-neutral-500 text-xs font-mono">
+                Select a record from the registry to inspect parameters.
+              </div>
+            )}
+          </div>
+
+          <div className="pt-6 mt-6 border-t border-white/10 flex items-center justify-between text-xs font-mono text-neutral-400">
+            <span>Verified Schema: ${entity.name}</span>
+            <span>REST: /api/${entity.name.toLowerCase()}s</span>
+          </div>
+        </div>
+        ` : ''}
+      </div>
+    </section>
+  );
+}
+`;
+  }
+}

package/src/orchestrator/visual-critic.js

@@ -0,0 +1,106 @@
+/**
+ * PIXEL CREW — Visual Critic & Anti-AI Slop Auditor
+ * 
+ * Inspects generated source code, CSS tokens, and component trees against the
+ * 64-Pattern Impeccable Anti-AI Slop Catalog.
+ * Scores are calculated dynamically from verified code evidence (NO fake hardcoded scores).
+ */
+
+export class VisualCritic {
+  /**
+   * Audit generated code files for AI slop patterns and aesthetic quality.
+   */
+  static evaluateProject(files = {}) {
+    const findings = [];
+    let slopPenalty = 0;
+    const fileEntries = Object.entries(files);
+
+    for (const [filepath, content] of fileEntries) {
+      if (typeof content !== 'string') continue;
+
+      // 1. Check for decorative gridlines background
+      if (content.includes('bg-grid') || content.includes('grid-white/[0.05]') || content.includes('svg-grid')) {
+        findings.push({
+          rule: 'SLOP-001: Decorative Gridlines Background',
+          severity: 'high',
+          file: filepath,
+          evidence: 'Found decorative graph-paper gridline background classes.'
+        });
+        slopPenalty += 2.0;
+      }
+
+      // 2. Check for fake macOS terminal window
+      if (content.includes('🔴') || content.includes('arnel@arch') || content.includes('terminal-window') || content.includes('bash -c')) {
+        findings.push({
+          rule: 'SLOP-002: Fake macOS Terminal Window',
+          severity: 'high',
+          file: filepath,
+          evidence: 'Found decorative fake macOS terminal window in UI.'
+        });
+        slopPenalty += 2.5;
+      }
+
+      // 3. Check for 4-box stat strip under hero
+      if (content.includes('486h') && content.includes('4+') && content.includes('3+')) {
+        findings.push({
+          rule: 'SLOP-027: Hero Metric 4-Box Stat Strip',
+          severity: 'medium',
+          file: filepath,
+          evidence: 'Found symmetrical 4-box stat metric strip.'
+        });
+        slopPenalty += 1.5;
+      }
+
+      // 4. Check for skill percentage progress bars
+      if (content.includes('Expert') && content.includes('Proficient') && (content.includes('h-2 bg-') || content.includes('progress-bar'))) {
+        findings.push({
+          rule: 'SLOP-028: Fake Skill Progress Bars',
+          severity: 'medium',
+          file: filepath,
+          evidence: 'Found arbitrary skill proficiency progress meters.'
+        });
+        slopPenalty += 1.5;
+      }
+
+      // 5. Check for marketing buzzwords
+      const buzzwords = ['streamline', 'empower', 'supercharge', 'world-class', 'seamlessly'];
+      for (const bw of buzzwords) {
+        if (new RegExp(`\\b${bw}\\b`, 'i').test(content) && !filepath.includes('test')) {
+          findings.push({
+            rule: `SLOP-045: AI Marketing Buzzword ('${bw}')`,
+            severity: 'low',
+            file: filepath,
+            evidence: `Found generic AI cliché buzzword '${bw}'.`
+          });
+          slopPenalty += 0.5;
+        }
+      }
+
+      // 6. Check for purple/cyan gradient halo
+      if (content.includes('from-purple-500') && content.includes('to-cyan-400') && content.includes('blur-3xl')) {
+        findings.push({
+          rule: 'SLOP-020: Radial Gradient Halo Blob',
+          severity: 'high',
+          file: filepath,
+          evidence: 'Found purple/cyan radial gradient blob in background.'
+        });
+        slopPenalty += 2.0;
+      }
+    }
+
+    const baseScore = 10.0;
+    const finalScore = Math.max(1.0, Math.round((baseScore - slopPenalty) * 10) / 10);
+    const passed = findings.filter(f => f.severity === 'high').length === 0 && finalScore >= 8.5;
+
+    return {
+      passed,
+      score: finalScore,
+      slopPenalty,
+      totalFindings: findings.length,
+      findings,
+      summary: passed
+        ? `Clean, human-grade design verified (Score: ${finalScore}/10). Zero critical AI-slop anti-patterns detected.`
+        : `Visual review flagged ${findings.length} AI-slop anti-patterns (Score: ${finalScore}/10). Remediation recommended.`
+    };
+  }
+}

package/src/policies/architecture/layering.policy.js

@@ -0,0 +1,14 @@
+/**
+ * PIXEL CREW — Layering & Architectural Purity Policy
+ */
+
+export const LayeringPolicy = {
+  id: 'POL-ARCH-LAYERING',
+  name: 'Clean Architecture Boundary Policy',
+  rules: [
+    { id: 'LAYER-01', description: 'Controllers must never access the database directly; they must delegate to services.' },
+    { id: 'LAYER-02', description: 'Services contain business logic and policy enforcement; they delegate persistence to repositories.' },
+    { id: 'LAYER-03', description: 'Repositories encapsulate database queries and caching.' },
+    { id: 'LAYER-04', description: 'All errors must conform to RFC 7807 Problem Details format.' }
+  ]
+};

package/src/policies/performance/indexing.policy.js

@@ -0,0 +1,13 @@
+/**
+ * PIXEL CREW — Indexing & Performance Policy
+ */
+
+export const IndexingPolicy = {
+  id: 'POL-PERF-INDEXING',
+  name: 'Database Indexing & Query Performance Policy',
+  rules: [
+    { id: 'INDEX-01', description: 'Foreign keys must be indexed to avoid table scans on JOINs.' },
+    { id: 'INDEX-02', description: 'Tenant-scoped collections must have compound indexes: (organizationId, createdAt DESC).' },
+    { id: 'INDEX-03', description: 'Unique identifiers (email, slug) must have unique database constraints.' }
+  ]
+};

package/src/policies/reliability/resilience.policy.js

@@ -0,0 +1,13 @@
+/**
+ * PIXEL CREW — Resilience & Reliability Policy
+ */
+
+export const ResiliencePolicy = {
+  id: 'POL-REL-RESILIENCE',
+  name: 'Resilience & Fault Tolerance Policy',
+  rules: [
+    { id: 'REL-01', description: 'Mutating operations must support Idempotency-Key validation.' },
+    { id: 'REL-02', description: 'Asynchronous workers must have dead-letter queues and retry backoff.' },
+    { id: 'REL-03', description: 'Applications must handle SIGTERM/SIGINT with graceful resource cleanup.' }
+  ]
+};

package/src/policies/security/auth.policy.js

@@ -0,0 +1,31 @@
+/**
+ * PIXEL CREW — Declarative Security Policies
+ */
+
+export const AuthPolicy = {
+  id: 'POL-SEC-AUTH',
+  name: 'Authentication Guard Policy',
+  rules: [
+    { id: 'AUTH-01', description: 'Mutating endpoints (POST, PATCH, DELETE) require authenticated session context by default.' },
+    { id: 'AUTH-02', description: 'Session tokens must be transmitted in HttpOnly SameSite secure cookies.' },
+    { id: 'AUTH-03', description: 'Password hashes must use Argon2id or bcrypt.' }
+  ]
+};
+
+export const RBACPolicy = {
+  id: 'POL-SEC-RBAC',
+  name: 'Role-Based Access Control Policy',
+  rules: [
+    { id: 'RBAC-01', description: 'Deny by default: missing explicit allow rule returns 403 Forbidden.' },
+    { id: 'RBAC-02', description: 'Resource deletion restricted strictly to admin or verified owner.' }
+  ]
+};
+
+export const TenantPolicy = {
+  id: 'POL-SEC-TENANT',
+  name: 'Multi-Tenant Isolation Policy',
+  rules: [
+    { id: 'TENANT-01', description: 'Tenant context must be derived from validated session token, never trusted from request body.' },
+    { id: 'TENANT-02', description: 'All tenant-scoped database queries must include WHERE organization_id = session.orgId.' }
+  ]
+};

package/src/protocol/agent.js

@@ -0,0 +1,124 @@
+/**
+ * PIXEL CREW — Universal Agent Protocol & Roles
+ * 
+ * Standardized agent roles, states, expressions, and capability contracts.
+ */
+
+export const AGENT_STATES = {
+  IDLE: 'IDLE',
+  SPAWNING: 'SPAWNING',
+  ANALYZING: 'ANALYZING',
+  WORKING: 'WORKING',
+  BLOCKED: 'BLOCKED',
+  VERIFYING: 'VERIFYING',
+  COMPLETED: 'COMPLETED',
+  ERROR: 'ERROR'
+};
+
+export const AGENT_EXPRESSIONS = {
+  IDLE: '●_●',
+  SPAWNING: '░_░',
+  ANALYZING: '◉_⊙',
+  WORKING: '◉▂◉',
+  BLOCKED: '?_?',
+  VERIFYING: '🔍_🔍',
+  COMPLETED: '^_^',
+  ERROR: 'x_x'
+};
+
+export const ORCHESTRATOR_EXPRESSIONS = {
+  IDLE: '◉_◉',
+  COORDINATING: '◉_◉ ⚡',
+  ANALYZING: '◉_⊙',
+  COMPLETED: '★_★',
+  ERROR: 'x_x'
+};
+
+export const AGENT_ROLES = {
+  orchestrator: {
+    id: 'orchestrator',
+    name: 'Tech Lead / Master CPU',
+    title: 'Staff Swarm Architect & Project Lead',
+    color: '#ffd700',
+    icon: '👔',
+    defaultSkills: ['anti-ai/slop-guardian']
+  },
+  creativeDirector: {
+    id: 'creativeDirector',
+    name: 'Creative Director',
+    title: 'Lead Aesthetic Strategist & Brand Architect',
+    color: '#ff9900',
+    icon: '✨',
+    defaultSkills: ['design/ui-design', 'design/typography', 'anti-ai/slop-guardian']
+  },
+  frontend: {
+    id: 'frontend',
+    name: 'Frontend Builder',
+    title: 'Senior UI/UX & Component Engineer',
+    color: '#00f0ff',
+    icon: '🎨',
+    defaultSkills: ['frontend/nextjs', 'frontend/react', 'frontend/tailwind', 'frontend/accessibility']
+  },
+  backend: {
+    id: 'backend',
+    name: 'Backend Engineer',
+    title: 'Principal API & Distributed Systems Engineer',
+    color: '#ff007f',
+    icon: '⚡',
+    defaultSkills: ['backend/route-handlers', 'backend/data-models']
+  },
+  database: {
+    id: 'database',
+    name: 'Database Architect',
+    title: 'Principal DBA & Query Performance Engineer',
+    color: '#ffd700',
+    icon: '🗄️',
+    defaultSkills: ['backend/data-models']
+  },
+  security: {
+    id: 'security',
+    name: 'Security Sentinel',
+    title: 'InfoSec Lead & OWASP Auditor',
+    color: '#ff3344',
+    icon: '🛡️',
+    defaultSkills: ['frontend/accessibility']
+  },
+  performance: {
+    id: 'performance',
+    name: 'Performance Profiler',
+    title: 'Core Web Vitals & Runtime Optimizer',
+    color: '#00ff88',
+    icon: '🚀',
+    defaultSkills: ['quality/responsive-design']
+  },
+  qa: {
+    id: 'qa',
+    name: 'QA & Visual Critic',
+    title: 'Lead Verification & Anti-AI Rubric Guardian',
+    color: '#bd00ff',
+    icon: '🧪',
+    defaultSkills: ['quality/visual-review', 'quality/browser-testing', 'anti-ai/slop-guardian']
+  },
+  animationSpecialist: {
+    id: 'animationSpecialist',
+    name: 'Motion Specialist',
+    title: 'Senior Kinetic Choreographer & Micro-Interactions',
+    color: '#38bdf8',
+    icon: '🎬',
+    defaultSkills: ['motion/framer-motion', 'motion/micro-interactions']
+  }
+};
+
+/**
+ * Creates and normalizes an Agent Capabilities record
+ */
+export function normalizeCapabilities(capabilities = {}) {
+  return {
+    fileAccess: Boolean(capabilities.fileAccess ?? true),
+    terminalAccess: Boolean(capabilities.terminalAccess ?? true),
+    subagents: Boolean(capabilities.subagents ?? false),
+    backgroundTasks: Boolean(capabilities.backgroundTasks ?? true),
+    streaming: Boolean(capabilities.streaming ?? true),
+    toolCalls: Boolean(capabilities.toolCalls ?? true)
+  };
+}

package/src/protocol/event.js

@@ -0,0 +1,78 @@
+/**
+ * PIXEL CREW — Universal Event Protocol
+ * 
+ * Standardized telemetry, lifecycle, and progress events across all agent providers.
+ */
+
+export const EVENT_TYPES = {
+  AGENT_STARTED: 'agent.started',
+  AGENT_THINKING: 'agent.thinking',
+  SKILL_ACTIVATED: 'skill.activated',
+  TOOL_INVOKED: 'tool.invoked',
+  PROGRESS: 'progress',
+  TASK_COMPLETED: 'task.completed',
+  TASK_FAILED: 'task.failed',
+  ORCHESTRATION_STARTED: 'orchestration.started',
+  ORCHESTRATION_COMPLETED: 'orchestration.completed',
+  ORCHESTRATION_FAILED: 'orchestration.failed',
+  STATE_CHANGE: 'state.change'
+};
+
+/**
+ * Creates and validates a standardized AgentEvent object
+ */
+export function createEvent(options = {}) {
+  const event = {
+    id: options.id || `evt-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+    timestamp: options.timestamp || Date.now(),
+    agent: options.agent || 'orchestrator',
+    type: options.type || EVENT_TYPES.PROGRESS,
+    taskId: options.taskId || null,
+    taskName: options.taskName || null,
+    skill: options.skill || null,
+    message: String(options.message || ''),
+    provider: options.provider || 'generic',
+    data: typeof options.data === 'object' && options.data !== null ? { ...options.data } : {}
+  };
+
+  validateEvent(event);
+  return event;
+}
+
+/**
+ * Validates that an AgentEvent object satisfies contract
+ */
+export function validateEvent(event) {
+  if (!event || typeof event !== 'object') {
+    throw new Error('Event must be a non-null object');
+  }
+  if (!event.id || typeof event.id !== 'string') {
+    throw new Error('Event must have a valid string id');
+  }
+  if (typeof event.timestamp !== 'number') {
+    throw new Error('Event must have a numeric timestamp');
+  }
+  if (!event.agent || typeof event.agent !== 'string') {
+    throw new Error('Event must have a valid agent name');
+  }
+  if (!event.type || typeof event.type !== 'string') {
+    throw new Error('Event must have a valid event type');
+  }
+  return true;
+}
+
+/**
+ * Serializes event for JSONL log line
+ */
+export function serializeEvent(event) {
+  validateEvent(event);
+  return JSON.stringify(event);
+}
+
+/**
+ * Deserializes an event from JSON string or object
+ */
+export function deserializeEvent(raw) {
+  const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  return createEvent(data);
+}

package/src/protocol/index.js

@@ -0,0 +1,8 @@
+/**
+ * PIXEL CREW — Protocol Index
+ */
+
+export * from './task.js';
+export * from './agent.js';
+export * from './event.js';
+export * from './skill.js';