@yattalo/task-system-core

Shared types, config helpers, Zod validators, and context tier logic for @yattalo/task-system.

Install

npm install @yattalo/task-system-core

API

Configuration

defineConfig(config)

Type-safe configuration builder with defaults for the task system scaffold.

import { defineConfig } from "@yattalo/task-system-core";

const config = defineConfig({
  projectName: "my-project",
  agents: { claude: { label: "Claude", icon: "C", color: "#D97706" } },
  categories: ["backend", "frontend"],
  phases: [{ id: "foundation", label: "Foundation", wave: 1 }],
  taskIdPattern: "[C]\\d{1,3}",
  extensions: { commitTracking: true },
});

defineRuntimeConfig(config)

Runtime configuration for UCA features (NLM, drift detection, context tiers).

import { defineRuntimeConfig } from "@yattalo/task-system-core";

const runtime = defineRuntimeConfig({
  projectId: "my-project",
  convexUrl: "https://my-project.convex.cloud",
  nlm: { enabled: true, globalNotebookId: "abc123" },
  drift: { checkpointInterval: 50, timeOverrunMultiplier: 1.5 },
  context: { autoPromoteThreshold: 2 },
});

Context Tier Logic

canPromote(entry, targetTier, promoterAgent)

Check if a context entry can be promoted to the target tier.

import { canPromote } from "@yattalo/task-system-core";

// AI can promote draft->reviewed if confidence > 3
canPromote(entry, "reviewed", "claude");   // true if entry.confidenceScore > 3

// Only humans can promote reviewed->curated
canPromote(entry, "curated", "human");     // true
canPromote(entry, "curated", "claude");    // false

canAutoPromote(entry)

Check if an entry qualifies for automatic promotion (draft -> reviewed only). Requires 2+ validations from different agents.

import { canAutoPromote } from "@yattalo/task-system-core";

// entry.validatedBy = ["claude", "codex"]
canAutoPromote(entry); // true — 2 unique validators

getNextTier(currentTier)

Returns the next tier in the hierarchy, or null if already at top.

getNextTier("draft");    // "reviewed"
getNextTier("reviewed"); // "curated"
getNextTier("curated");  // null

createPromotionRecord(from, to, promotedBy, reason?)

Create a timestamped promotion record for tracking history.

Validators

All validators use Zod and throw on invalid input.

import {
  validateConfig,
  validateTaskDefinitions,
  validateContextEntry,
  validateKnowledgeEntry,
  validateDriftEvent,
  validateAgentRegistryEntry,
} from "@yattalo/task-system-core";

// Validates and returns typed object, or throws ZodError
const entry = validateContextEntry(rawData);

Zod schemas are also exported for custom composition:

import {
  contextEntrySchema,
  knowledgeEntrySchema,
  driftEventSchema,
  agentRegistryEntrySchema,
} from "@yattalo/task-system-core";

Config Helpers

| Function | Description | |----------|-------------| | getActiveExtensions(config) | List enabled extension keys | | hasSoftwareExtensions(config) | Check if software extensions enabled | | hasResearchExtensions(config) | Check if research extensions enabled | | getAgentKeys(config) | Array of agent key strings | | getTableName(config) | Convex table name (default: "agentTasks") |

Constants

import {
  TASK_STATUSES,         // ["backlog","todo","in_progress","blocked","review","done","archived"]
  TASK_PRIORITIES,       // ["critical","high","medium","low"]
  CONTEXT_TIERS,         // ["draft","reviewed","curated"]
  CONTEXT_ENTRY_TYPES,   // ["task_output","decision","learning","insight",...]
  DRIFT_TYPES,           // ["scope_creep","time_overrun","context_switch",...]
  DRIFT_SEVERITIES,      // ["low","medium","high"]
  DRIFT_STATUSES,        // ["open","acknowledged","resolved","dismissed"]
  KNOWLEDGE_CATEGORIES,  // ["pattern","decision","lesson_learned",...]
  AGENT_TYPES,           // ["ai","human"]
  AGENT_STATUSES,        // ["active","idle","offline"]
  JOB_STATUSES,          // ["active","paused","completed","failed"]
  RUN_STATUSES,          // ["queued","running","completed","failed","cancelled","timeout"]
} from "@yattalo/task-system-core";

Types

Task System: TaskSystemConfig, TaskDefinition, TaskStatus, TaskPriority, AgentConfig, PhaseConfig, ExtensionsConfig, GeneratorContext, ProjectDetection, CommitRecord, ScopeCreepFlag, EvidenceRecord, HandoffRecord, CheckpointEntry, AgentOpsJob, AgentOpsRun

UCA: ContextTier, ContextEntryType, ContextEntry, PromotionRecord, DriftType, DriftSeverity, DriftStatus, DriftEvent, KnowledgeCategory, KnowledgeEntry, AgentRegistryType, AgentRegistryStatus, AgentRegistryEntry, RuntimeConfig, NlmConfig, DriftConfig, ContextConfig

License

MIT