@stackbilt/aegis-core 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbilt/aegis-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Persistent AI agent framework for Cloudflare Workers. Multi-tier memory, autonomous goals, dreaming cycles, MCP native.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -55,7 +55,11 @@
     "./routes/pages": "./src/routes/pages.ts",
     "./routes/dynamic-tools": "./src/routes/dynamic-tools.ts",
     "./adapters/voice": "./src/adapters/voice/cloudflare-agent.ts",
-    "./schema-enums": "./src/schema-enums.ts"
+    "./schema-enums": "./src/schema-enums.ts",
+    "./contracts/goal": "./src/contracts/goal.contract.ts",
+    "./contracts/agenda-item": "./src/contracts/agenda-item.contract.ts",
+    "./contracts/cc-task": "./src/contracts/cc-task.contract.ts",
+    "./contracts/memory-entry": "./src/contracts/memory-entry.contract.ts"
   },
   "scripts": {
     "dev": "wrangler dev",
@@ -70,9 +74,11 @@
   "dependencies": {
     "@cloudflare/voice": "^0.1.3",
     "@cloudflare/workers-oauth-provider": "^0.2.4",
+    "@stackbilt/contracts": "^0.2.1",
     "@stackbilt/llm-providers": "^1.6.0",
     "agents": "^0.12.3",
-    "hono": "^4.12.12"
+    "hono": "^4.12.12",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20241218.0",

package/src/contracts/agenda-item.contract.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import { defineContract } from '@stackbilt/contracts';
+
+const AgendaPriority = z.enum(['low', 'medium', 'high']);
+const AgendaStatus = z.enum(['active', 'done', 'dismissed']);
+
+export const AgendaItemContract = defineContract({
+  name: 'AgendaItem',
+  version: '1.0.0',
+  description: 'Operator agenda item — work scratchpad with priority and lifecycle tracking',
+
+  schema: z.object({
+    id: z.number().int().positive(),
+    item: z.string().min(1),
+    context: z.string().nullable(),
+    priority: AgendaPriority.default('medium'),
+    status: AgendaStatus.default('active'),
+    createdAt: z.string().datetime(),
+    resolvedAt: z.string().datetime().nullable(),
+    businessUnit: z.string().min(1).default('stackbilt'),
+  }),
+
+  operations: {
+    add: {
+      input: z.object({
+        item: z.string().min(1),
+        context: z.string().optional(),
+        priority: AgendaPriority.optional(),
+        businessUnit: z.string().min(1).optional(),
+      }),
+      output: 'self' as const,
+      emits: ['agenda_item.added'],
+    },
+
+    resolve: {
+      input: z.object({ id: z.number().int().positive() }),
+      output: 'self' as const,
+      transition: { from: 'active', to: 'done' },
+      emits: ['agenda_item.resolved'],
+    },
+
+    dismiss: {
+      input: z.object({ id: z.number().int().positive() }),
+      output: 'self' as const,
+      transition: { from: 'active', to: 'dismissed' },
+      emits: ['agenda_item.dismissed'],
+    },
+
+    escalate: {
+      input: z.object({ id: z.number().int().positive() }),
+      output: 'self' as const,
+      emits: ['agenda_item.escalated'],
+    },
+  },
+
+  states: {
+    field: 'status',
+    initial: 'active',
+    transitions: {
+      active: {
+        resolve: 'done',
+        dismiss: 'dismissed',
+      },
+      done: {},
+      dismissed: {},
+    },
+  },
+
+  surfaces: {
+    api: {
+      basePath: '/api/agenda',
+      routes: {
+        add: { method: 'POST', path: '/' },
+        resolve: { method: 'POST', path: '/:id/resolve' },
+        dismiss: { method: 'POST', path: '/:id/dismiss' },
+        escalate: { method: 'POST', path: '/:id/escalate' },
+      },
+    },
+    db: {
+      table: 'agent_agenda',
+      indexes: [
+        'idx_agenda_status(status)',
+        'idx_agenda_priority(priority)',
+        'idx_agenda_bu(business_unit, status)',
+      ],
+      columnOverrides: {
+        createdAt: { default: "datetime('now')" },
+      },
+    },
+  },
+
+  authority: {
+    add: { requires: 'role', roles: ['operator', 'system'] },
+    resolve: { requires: 'role', roles: ['operator', 'system'] },
+    dismiss: { requires: 'role', roles: ['operator', 'system'] },
+    escalate: { requires: 'role', roles: ['system'] },
+  },
+
+  invariants: [
+    {
+      name: 'resolved_has_timestamp',
+      description: 'Done items must have a resolvedAt timestamp',
+      check: (entity: unknown) => {
+        const a = entity as { status?: string; resolvedAt?: string | null };
+        if (a.status === 'done' && !a.resolvedAt) {
+          return 'Done agenda item requires resolvedAt';
+        }
+        return true;
+      },
+      appliesTo: ['resolve'],
+    },
+  ],
+});

package/src/contracts/cc-task.contract.ts

@@ -0,0 +1,204 @@
+import { z } from 'zod';
+import { defineContract } from '@stackbilt/contracts';
+
+const TaskStatus = z.enum(['pending', 'running', 'completed', 'failed', 'cancelled']);
+const TaskAuthority = z.enum(['proposed', 'auto_safe', 'operator']);
+const TaskCategory = z.enum(['docs', 'tests', 'research', 'bugfix', 'feature', 'refactor', 'deploy']);
+
+export const CCTaskContract = defineContract({
+  name: 'CCTask',
+  version: '1.0.0',
+  description: 'Claude Code autonomous task — queued, governed, and executed by the task runner',
+
+  schema: z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    repo: z.string().min(1),
+    prompt: z.string().min(1),
+    completionSignal: z.string().nullable(),
+    status: TaskStatus.default('pending'),
+    priority: z.number().int().min(0).max(100).default(50),
+    dependsOn: z.string().nullable(),
+    blockedBy: z.string().nullable(),
+    maxTurns: z.number().int().positive().default(25),
+    allowedTools: z.string().nullable(),
+    sessionId: z.string().nullable(),
+    result: z.string().nullable(),
+    error: z.string().nullable(),
+    exitCode: z.number().int().nullable(),
+    preflightJson: z.string().nullable(),
+    failureKind: z.string().nullable(),
+    retryable: z.boolean().default(false),
+    autopsyJson: z.string().nullable(),
+    createdAt: z.string().datetime(),
+    startedAt: z.string().datetime().nullable(),
+    completedAt: z.string().datetime().nullable(),
+    createdBy: z.string().min(1).default('operator'),
+    authority: TaskAuthority.default('operator'),
+    category: TaskCategory.default('feature'),
+    branch: z.string().nullable(),
+    prUrl: z.string().nullable(),
+    utilityJson: z.string().nullable(),
+    githubIssueRepo: z.string().nullable(),
+    githubIssueNumber: z.number().int().positive().nullable(),
+    businessUnit: z.string().min(1).default('stackbilt'),
+  }),
+
+  operations: {
+    create: {
+      input: z.object({
+        id: z.string().min(1),
+        title: z.string().min(1),
+        repo: z.string().min(1),
+        prompt: z.string().min(1),
+        completionSignal: z.string().optional(),
+        priority: z.number().int().min(0).max(100).optional(),
+        dependsOn: z.string().optional(),
+        blockedBy: z.string().optional(),
+        maxTurns: z.number().int().positive().optional(),
+        allowedTools: z.string().optional(),
+        authority: TaskAuthority.optional(),
+        category: TaskCategory.optional(),
+        githubIssueRepo: z.string().optional(),
+        githubIssueNumber: z.number().int().positive().optional(),
+        businessUnit: z.string().min(1).optional(),
+      }),
+      output: 'self' as const,
+      emits: ['cc_task.created'],
+    },
+
+    start: {
+      input: z.object({
+        id: z.string().min(1),
+        sessionId: z.string().min(1),
+      }),
+      output: 'self' as const,
+      transition: { from: 'pending', to: 'running' },
+      emits: ['cc_task.started'],
+    },
+
+    complete: {
+      input: z.object({
+        id: z.string().min(1),
+        result: z.string().optional(),
+        exitCode: z.number().int().optional(),
+        prUrl: z.string().optional(),
+        utilityJson: z.string().optional(),
+      }),
+      output: 'self' as const,
+      transition: { from: 'running', to: 'completed' },
+      emits: ['cc_task.completed'],
+    },
+
+    fail: {
+      input: z.object({
+        id: z.string().min(1),
+        error: z.string().min(1),
+        exitCode: z.number().int().optional(),
+        failureKind: z.string().optional(),
+        retryable: z.boolean().optional(),
+        autopsyJson: z.string().optional(),
+      }),
+      output: 'self' as const,
+      transition: { from: 'running', to: 'failed' },
+      emits: ['cc_task.failed'],
+    },
+
+    cancel: {
+      input: z.object({ id: z.string().min(1) }),
+      output: 'self' as const,
+      transition: { from: ['pending', 'running'], to: 'cancelled' },
+      emits: ['cc_task.cancelled'],
+    },
+
+    approve: {
+      input: z.object({ id: z.string().min(1) }),
+      output: 'self' as const,
+      emits: ['cc_task.approved'],
+    },
+  },
+
+  states: {
+    field: 'status',
+    initial: 'pending',
+    transitions: {
+      pending: {
+        start: 'running',
+        cancel: 'cancelled',
+      },
+      running: {
+        complete: 'completed',
+        fail: 'failed',
+        cancel: 'cancelled',
+      },
+      completed: {},
+      failed: {},
+      cancelled: {},
+    },
+  },
+
+  surfaces: {
+    api: {
+      basePath: '/api/cc-tasks',
+      routes: {
+        create: { method: 'POST', path: '/' },
+        start: { method: 'POST', path: '/:id/start' },
+        complete: { method: 'POST', path: '/:id/complete' },
+        fail: { method: 'POST', path: '/:id/fail' },
+        cancel: { method: 'POST', path: '/:id/cancel' },
+        approve: { method: 'POST', path: '/:id/approve' },
+      },
+    },
+    db: {
+      table: 'cc_tasks',
+      indexes: [
+        'idx_cc_tasks_status(status, priority)',
+        'idx_cc_tasks_depends(depends_on)',
+        'idx_cc_tasks_created(created_at)',
+        'idx_cc_tasks_bu(business_unit, status)',
+        'idx_cc_tasks_authority(authority)',
+        'idx_cc_tasks_gh_issue(github_issue_repo, github_issue_number)',
+        'idx_cc_tasks_failure_kind(failure_kind, completed_at)',
+      ],
+      columnOverrides: {
+        createdAt: { default: "datetime('now')" },
+      },
+    },
+  },
+
+  authority: {
+    create: { requires: 'role', roles: ['operator', 'system'] },
+    start: { requires: 'role', roles: ['system'] },
+    complete: { requires: 'role', roles: ['system'] },
+    fail: { requires: 'role', roles: ['system'] },
+    cancel: { requires: 'role', roles: ['operator', 'system'] },
+    approve: { requires: 'role', roles: ['operator'] },
+  },
+
+  invariants: [
+    {
+      name: 'proposed_task_needs_approval',
+      description: 'Proposed tasks must be approved before they can run',
+      check: (entity: unknown) => {
+        const t = entity as { authority?: string; status?: string };
+        if (t.authority === 'proposed' && t.status === 'running') {
+          return 'Proposed tasks require approval before execution';
+        }
+        return true;
+      },
+      appliesTo: ['start'],
+    },
+    {
+      name: 'completed_has_timestamp',
+      description: 'Completed or failed tasks must have a completedAt timestamp',
+      check: (entity: unknown) => {
+        const t = entity as { status?: string; completedAt?: string | null };
+        if ((t.status === 'completed' || t.status === 'failed') && !t.completedAt) {
+          return 'Terminal tasks require completedAt';
+        }
+        return true;
+      },
+      appliesTo: ['complete', 'fail'],
+    },
+  ],
+});

package/src/contracts/goal.contract.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { defineContract } from '@stackbilt/contracts';
+
+const GoalStatus = z.enum(['active', 'paused', 'completed', 'failed']);
+const AuthorityLevel = z.enum(['propose', 'auto_low', 'auto_high']);
+
+export const GoalContract = defineContract({
+  name: 'Goal',
+  version: '1.0.0',
+  description: 'Autonomous agent goal with scheduled execution and authority-gated autonomy',
+
+  schema: z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    description: z.string().nullable(),
+    status: GoalStatus.default('active'),
+    authorityLevel: AuthorityLevel.default('propose'),
+    scheduleHours: z.number().int().positive().default(6),
+    createdAt: z.string().datetime(),
+    lastRunAt: z.string().datetime().nullable(),
+    nextRunAt: z.string().datetime().nullable(),
+    completedAt: z.string().datetime().nullable(),
+    runCount: z.number().int().nonnegative().default(0),
+    contextJson: z.string().nullable(),
+    businessUnit: z.string().min(1).default('stackbilt'),
+  }),
+
+  operations: {
+    create: {
+      input: z.object({
+        id: z.string().min(1),
+        title: z.string().min(1),
+        description: z.string().optional(),
+        authorityLevel: AuthorityLevel.optional(),
+        scheduleHours: z.number().int().positive().optional(),
+        contextJson: z.string().optional(),
+        businessUnit: z.string().min(1).optional(),
+      }),
+      output: 'self' as const,
+      emits: ['goal.created'],
+    },
+
+    pause: {
+      input: z.object({ id: z.string().min(1) }),
+      output: 'self' as const,
+      transition: { from: 'active', to: 'paused' },
+      emits: ['goal.paused'],
+    },
+
+    resume: {
+      input: z.object({ id: z.string().min(1) }),
+      output: 'self' as const,
+      transition: { from: 'paused', to: 'active' },
+      emits: ['goal.resumed'],
+    },
+
+    complete: {
+      input: z.object({ id: z.string().min(1) }),
+      output: 'self' as const,
+      transition: { from: ['active', 'paused'], to: 'completed' },
+      emits: ['goal.completed'],
+    },
+
+    fail: {
+      input: z.object({ id: z.string().min(1) }),
+      output: 'self' as const,
+      transition: { from: ['active', 'paused'], to: 'failed' },
+      emits: ['goal.failed'],
+    },
+
+    recordRun: {
+      input: z.object({
+        id: z.string().min(1),
+        nextRunAt: z.string().datetime().optional(),
+      }),
+      output: 'self' as const,
+      emits: ['goal.ran'],
+    },
+  },
+
+  states: {
+    field: 'status',
+    initial: 'active',
+    transitions: {
+      active: {
+        pause: 'paused',
+        complete: 'completed',
+        fail: 'failed',
+      },
+      paused: {
+        resume: 'active',
+        complete: 'completed',
+        fail: 'failed',
+      },
+      completed: {},
+      failed: {},
+    },
+  },
+
+  surfaces: {
+    api: {
+      basePath: '/api/goals',
+      routes: {
+        create: { method: 'POST', path: '/' },
+        pause: { method: 'POST', path: '/:id/pause' },
+        resume: { method: 'POST', path: '/:id/resume' },
+        complete: { method: 'POST', path: '/:id/complete' },
+        fail: { method: 'POST', path: '/:id/fail' },
+      },
+    },
+    db: {
+      table: 'agent_goals',
+      indexes: [
+        'idx_goals_status(status)',
+        'idx_goals_next_run(next_run_at)',
+        'idx_goals_bu(business_unit, status)',
+      ],
+      columnOverrides: {
+        createdAt: { default: "datetime('now')" },
+      },
+    },
+  },
+
+  authority: {
+    create: { requires: 'role', roles: ['operator', 'system'] },
+    pause: { requires: 'role', roles: ['operator', 'system'] },
+    resume: { requires: 'role', roles: ['operator', 'system'] },
+    complete: { requires: 'role', roles: ['system'] },
+    fail: { requires: 'role', roles: ['system'] },
+    recordRun: { requires: 'role', roles: ['system'] },
+  },
+
+  invariants: [
+    {
+      name: 'completed_has_timestamp',
+      description: 'Completed goals must have a completedAt timestamp',
+      check: (entity: unknown) => {
+        const g = entity as { status?: string; completedAt?: string | null };
+        if (g.status === 'completed' && !g.completedAt) {
+          return 'Completed goal requires completedAt';
+        }
+        return true;
+      },
+      appliesTo: ['complete'],
+    },
+  ],
+});

package/src/contracts/memory-entry.contract.ts

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+import { defineContract } from '@stackbilt/contracts';
+
+const ValidationStage = z.enum(['candidate', 'validated', 'expert', 'canonical', 'refuted']);
+
+export const MemoryEntryContract = defineContract({
+  name: 'MemoryEntry',
+  version: '1.0.0',
+  description: 'Semantic memory entry with topic-scoped facts, CRIX validation pipeline, and decay tracking',
+
+  schema: z.object({
+    id: z.number().int().positive(),
+    topic: z.string().min(1),
+    fact: z.string().min(1),
+    factHash: z.string().default(''),
+    confidence: z.number().min(0).max(1).default(0.8),
+    source: z.string().min(1),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    expiresAt: z.string().datetime().nullable(),
+    validUntil: z.string().datetime().nullable(),
+    supersededBy: z.number().int().positive().nullable(),
+    strength: z.number().int().nonnegative().default(1),
+    lastRecalledAt: z.string().datetime().nullable(),
+    validationStage: ValidationStage.default('candidate'),
+    validators: z.string().nullable(),
+  }),
+
+  operations: {
+    record: {
+      input: z.object({
+        topic: z.string().min(1),
+        fact: z.string().min(1),
+        source: z.string().min(1),
+        confidence: z.number().min(0).max(1).optional(),
+        expiresAt: z.string().datetime().optional(),
+      }),
+      output: 'self' as const,
+      emits: ['memory_entry.recorded'],
+    },
+
+    validate: {
+      input: z.object({
+        id: z.number().int().positive(),
+        repo: z.string().min(1),
+        confirmed: z.boolean(),
+        date: z.string().datetime(),
+      }),
+      output: 'self' as const,
+      transition: { from: 'candidate', to: 'validated' },
+      emits: ['memory_entry.validated'],
+    },
+
+    promoteToExpert: {
+      input: z.object({ id: z.number().int().positive() }),
+      output: 'self' as const,
+      transition: { from: 'validated', to: 'expert' },
+      emits: ['memory_entry.promoted_expert'],
+    },
+
+    promoteToCanonical: {
+      input: z.object({ id: z.number().int().positive() }),
+      output: 'self' as const,
+      transition: { from: 'expert', to: 'canonical' },
+      emits: ['memory_entry.promoted_canonical'],
+    },
+
+    refute: {
+      input: z.object({
+        id: z.number().int().positive(),
+        supersededBy: z.number().int().positive().optional(),
+      }),
+      output: 'self' as const,
+      transition: { from: ['candidate', 'validated', 'expert'], to: 'refuted' },
+      emits: ['memory_entry.refuted'],
+    },
+
+    recall: {
+      input: z.object({ id: z.number().int().positive() }),
+      output: 'self' as const,
+      emits: ['memory_entry.recalled'],
+    },
+
+    expire: {
+      input: z.object({ id: z.number().int().positive() }),
+      output: 'self' as const,
+      emits: ['memory_entry.expired'],
+    },
+  },
+
+  states: {
+    field: 'validationStage',
+    initial: 'candidate',
+    transitions: {
+      candidate: {
+        validate: 'validated',
+        refute: 'refuted',
+      },
+      validated: {
+        promoteToExpert: 'expert',
+        refute: 'refuted',
+      },
+      expert: {
+        promoteToCanonical: 'canonical',
+        refute: 'refuted',
+      },
+      canonical: {},
+      refuted: {},
+    },
+  },
+
+  surfaces: {
+    api: {
+      basePath: '/api/memory',
+      routes: {
+        record: { method: 'POST', path: '/' },
+        validate: { method: 'POST', path: '/:id/validate' },
+        promoteToExpert: { method: 'POST', path: '/:id/promote-expert' },
+        promoteToCanonical: { method: 'POST', path: '/:id/promote-canonical' },
+        refute: { method: 'POST', path: '/:id/refute' },
+        recall: { method: 'POST', path: '/:id/recall' },
+        expire: { method: 'POST', path: '/:id/expire' },
+      },
+    },
+    db: {
+      table: 'memory_entries',
+      indexes: [
+        'idx_memory_topic(topic)',
+        'idx_memory_dedup(topic, fact_hash)',
+        'idx_memory_expires(expires_at)',
+        'idx_memory_valid(valid_until)',
+        'idx_memory_validation_stage(validation_stage)',
+      ],
+      columnOverrides: {
+        createdAt: { default: "datetime('now')" },
+        updatedAt: { default: "datetime('now')" },
+      },
+    },
+  },
+
+  authority: {
+    record: { requires: 'role', roles: ['operator', 'system'] },
+    validate: { requires: 'role', roles: ['system'] },
+    promoteToExpert: { requires: 'role', roles: ['system'] },
+    promoteToCanonical: { requires: 'role', roles: ['system'] },
+    refute: { requires: 'role', roles: ['operator', 'system'] },
+    recall: { requires: 'role', roles: ['system'] },
+    expire: { requires: 'role', roles: ['system'] },
+  },
+
+  invariants: [
+    {
+      name: 'refuted_entry_not_canonical',
+      description: 'Canonical entries cannot be refuted — they must be superseded instead',
+      check: (entity: unknown) => {
+        const m = entity as { validationStage?: string };
+        if (m.validationStage === 'canonical') {
+          return 'Canonical entries cannot transition to refuted';
+        }
+        return true;
+      },
+      appliesTo: ['refute'],
+    },
+    {
+      name: 'high_confidence_for_canonical',
+      description: 'Canonical entries should have confidence >= 0.9',
+      check: (entity: unknown) => {
+        const m = entity as { validationStage?: string; confidence?: number };
+        if (m.validationStage === 'canonical' && (m.confidence ?? 0) < 0.9) {
+          return 'Canonical memory entries require confidence >= 0.9';
+        }
+        return true;
+      },
+      appliesTo: ['promoteToCanonical'],
+    },
+  ],
+});