@kynetic-ai/spec 0.11.0 → 0.12.0

package/dist/daemon/routes/agent-dispatch.ts

@@ -19,13 +19,15 @@
  * - @agent-dispatch-engine ac-4: CLI posts state change event to daemon
  */
 
+import path from 'node:path';
 import { Elysia, t } from 'elysia';
 import { DispatchEngine } from '../../agent-runtime/dispatch.js';
 import type { TaskStateChange, TaskStatus, InvocationEvent } from '../../agent-runtime/dispatch.js';
 import { DEFAULT_KSPEC_CLI_PATH } from '../../agent-runtime/invocation.js';
-import { initContext, loadMetaContext } from '../../parser/index.js';
+import { initContext, loadMetaContext, loadAllTasks, loadAllItems, ReferenceIndex, resolveProjectRoots } from '../../parser/index.js';
 import { getCompletedSessionCountsByAgent } from '../../sessions/store.js';
 import type { PubSubManager } from '../websocket/pubsub.js';
+import type { SessionEventData } from '@kynetic-ai/shared';
 
 const VALID_TASK_STATUSES = new Set<string>([
   "pending", "in_progress", "pending_review", "needs_work", "blocked", "completed", "cancelled",
@@ -44,31 +46,33 @@ export interface AgentDispatchRouteOptions {
  * Create a new dispatch engine with optional WebSocket broadcast wiring.
  * AC: @daemon-agent-dispatch ac-3, ac-4
  */
-function createEngine(projectDir: string, pubsub?: PubSubManager): DispatchEngine {
+function createEngine(
+  projectDir: string,
+  cwd?: string,
+  pubsub?: PubSubManager,
+): DispatchEngine {
   return new DispatchEngine({
     projectDir,
+    cwd,
     kspecCliPath: DEFAULT_KSPEC_CLI_PATH,
     onInvocationEvent: pubsub
       ? (event: InvocationEvent) => {
+          // AC: @ui-api-aggregation ac-4 - Include task_title for display
           pubsub.broadcast('agents', 'agent_invocation', {
             session_id: event.session_id,
             agent_id: event.agent_id,
             task_id: event.task_id ?? null,
+            task_title: event.task_title ?? null,
             status: event.status,
             timestamp: event.timestamp,
           }, projectDir);
         }
       : undefined,
+    // AC: @session-event-broadcast ac-replaces-text-chunks
     // AC: @cli-agent-commands ac-13, @daemon-agent-dispatch ac-8
-    onTextChunk: pubsub
-      ? (sessionId: string, agentId: string, taskId: string | null, text: string) => {
-          pubsub.broadcast('agents', 'agent_text_chunk', {
-            session_id: sessionId,
-            agent_id: agentId,
-            task_id: taskId,
-            text,
-            timestamp: Date.now(),
-          }, projectDir);
+    onSessionEvent: pubsub
+      ? (event: SessionEventData) => {
+          pubsub.broadcast('agents', event.type, event, projectDir);
         }
       : undefined,
   });
@@ -117,6 +121,28 @@ function processStateChangeEvent(
   return { accepted: true };
 }
 
+export function resolveDispatchCwd(
+  projectDir: string,
+  requestedCwd: string | null,
+): string {
+  if (requestedCwd && !path.isAbsolute(requestedCwd)) {
+    throw new Error('Dispatch cwd must be an absolute path');
+  }
+  const cwd = requestedCwd ? path.resolve(requestedCwd) : projectDir;
+
+  if (cwd === projectDir) {
+    return cwd;
+  }
+
+  const projectRoots = resolveProjectRoots(projectDir);
+  const cwdRoots = resolveProjectRoots(cwd);
+  if (!projectRoots || !cwdRoots || projectRoots.mainRoot !== cwdRoots.mainRoot) {
+    throw new Error('Dispatch cwd must belong to the same git project');
+  }
+
+  return cwd;
+}
+
 export function createAgentDispatchRoutes(options: AgentDispatchRouteOptions = {}) {
   const { pubsub } = options;
 
@@ -134,16 +160,34 @@ export function createAgentDispatchRoutes(options: AgentDispatchRouteOptions = {
     }, { body: stateChangeBodySchema })
 
     // AC: @daemon-agent-dispatch ac-6 - Unified dispatch start/stop via action field
-    .post('/dispatch', async ({ body, projectContext }) => {
+    .post('/dispatch', async ({ body, projectContext, request, set }) => {
       const projectDir = projectContext.path;
 
       if (body.action === 'start') {
+        let requestedCwd: string;
+        try {
+          requestedCwd = resolveDispatchCwd(projectDir, request.headers.get('X-Kspec-Cwd'));
+        } catch (err) {
+          set.status = 400;
+          return {
+            dispatch_enabled: false,
+            error: err instanceof Error ? err.message : String(err),
+          };
+        }
+
         let engine = engines.get(projectDir);
         if (engine?.getStatus().running) {
+          if (engine.getCwd() !== requestedCwd) {
+            set.status = 409;
+            return {
+              dispatch_enabled: true,
+              error: `Dispatch engine already running for ${projectDir} with cwd ${engine.getCwd()}`,
+            };
+          }
           return { dispatch_enabled: true, reason: 'Already running' };
         }
 
-        engine = createEngine(projectDir, pubsub);
+        engine = createEngine(projectDir, requestedCwd, pubsub);
         engines.set(projectDir, engine);
         await engine.start();
 
@@ -166,16 +210,34 @@ export function createAgentDispatchRoutes(options: AgentDispatchRouteOptions = {
     })
 
     // Start dispatch engine (legacy route)
-    .post('/dispatch/start', async ({ projectContext }) => {
+    .post('/dispatch/start', async ({ projectContext, request, set }) => {
       const projectDir = projectContext.path;
+      let requestedCwd: string;
+      try {
+        requestedCwd = resolveDispatchCwd(projectDir, request.headers.get('X-Kspec-Cwd'));
+      } catch (err) {
+        set.status = 400;
+        return {
+          started: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
 
       let engine = engines.get(projectDir);
       if (engine?.getStatus().running) {
+        if (engine.getCwd() !== requestedCwd) {
+          set.status = 409;
+          return {
+            started: false,
+            error: `Dispatch engine already running for ${projectDir} with cwd ${engine.getCwd()}`,
+            status: engine.getStatus(),
+          };
+        }
         return { started: false, reason: 'Already running', status: engine.getStatus() };
       }
 
       // AC: @agent-dispatch-engine ac-10 - pass kspecCliPath so task notes work from daemon-started engine
-      engine = createEngine(projectDir, pubsub);
+      engine = createEngine(projectDir, requestedCwd, pubsub);
       engines.set(projectDir, engine);
 
       await engine.start();
@@ -215,19 +277,24 @@ export function createAgentDispatchRoutes(options: AgentDispatchRouteOptions = {
     })
 
     // AC: @daemon-agent-dispatch ac-5 - Public status endpoint
+    // AC: @ui-api-ref-resolution ac-1 - Include task_title for active invocations
     .get('/status', async ({ projectContext }) => {
       const projectDir = projectContext.path;
       const engineStatus = engines.get(projectDir)?.getStatus();
 
       let agentDefinitions: Array<{ id: string; name: string; adapter: string; completed_sessions: number }> = [];
       let completedCounts: Record<string, number> = {};
+      let refIndex: ReferenceIndex | null = null;
       try {
         const ctx = await initContext(projectDir);
-        const [meta, counts] = await Promise.all([
+        const [meta, counts, tasks, items] = await Promise.all([
           loadMetaContext(ctx),
           getCompletedSessionCountsByAgent(ctx.specDir),
+          loadAllTasks(ctx),
+          loadAllItems(ctx),
         ]);
         completedCounts = counts;
+        refIndex = new ReferenceIndex(tasks, items);
         agentDefinitions = meta.agents.map((a) => ({
           id: a.id,
           name: a.name,
@@ -240,12 +307,22 @@ export function createAgentDispatchRoutes(options: AgentDispatchRouteOptions = {
 
       return {
         dispatch_enabled: engineStatus?.running ?? false,
-        active_invocations: engineStatus?.invocations?.map((inv) => ({
-          session_id: inv.sessionId,
-          agent_id: inv.agentId,
-          task_ref: inv.taskRef ?? null,
-          elapsed_ms: inv.elapsedMs,
-        })) ?? [],
+        active_invocations: engineStatus?.invocations?.map((inv) => {
+          let task_title: string | null = null;
+          if (inv.taskRef && refIndex) {
+            const result = refIndex.resolve(inv.taskRef);
+            if (result.ok) {
+              task_title = (result.item as { title?: string }).title ?? null;
+            }
+          }
+          return {
+            session_id: inv.sessionId,
+            agent_id: inv.agentId,
+            task_ref: inv.taskRef ?? null,
+            task_title,
+            elapsed_ms: inv.elapsedMs,
+          };
+        }) ?? [],
         queue_depth: engineStatus?.queuedInvocations ?? 0,
         agent_definitions: agentDefinitions,
       };

package/dist/daemon/routes/aggregation.ts

@@ -0,0 +1,184 @@
+/**
+ * Aggregation API Routes
+ *
+ * Pre-computed server-side aggregation endpoints:
+ * - GET /api/aggregation/tasks/summary - Task status counts with dependency-aware distinctions
+ * - GET /api/aggregation/validation - Extended validation/alignment stats with entity and AC counts
+ * - GET /api/aggregation/inbox - Inbox items with inline triage status
+ *
+ * AC Coverage:
+ * - @ui-api-aggregation ac-1: Task status summary with ready vs blocked distinctions
+ * - @ui-api-aggregation ac-2: Validation/alignment stats with entity counts, AC counts, orphan counts
+ * - @ui-api-aggregation ac-3: Inbox items with inline triage status
+ */
+
+import { Elysia } from 'elysia';
+import {
+  initContext,
+  loadAllTasks,
+  loadInboxItems,
+  loadTriageRecords,
+  findTriageRecordByInboxRef,
+  buildIndexes,
+  validate,
+  AlignmentIndex,
+  areDependenciesMet,
+} from '../../parser/index.js';
+import type {
+  TaskStatusSummary,
+  ValidationAggregation,
+  InboxItemWithTriage,
+} from '@kynetic-ai/shared';
+
+interface AggregationRouteOptions {}
+
+export function createAggregationRoutes(options: AggregationRouteOptions = {}) {
+  return new Elysia({ prefix: '/api/aggregation' })
+    // AC: @ui-api-aggregation ac-1 - Task status summary with dependency-aware distinctions
+    .get('/tasks/summary', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const tasks = await loadAllTasks(ctx);
+
+      // Count tasks by status
+      const counts: Record<string, number> = {};
+      for (const task of tasks) {
+        counts[task.status] = (counts[task.status] || 0) + 1;
+      }
+
+      // Dependency-aware distinctions: ready vs blocked by incomplete dependencies
+      let ready = 0;
+      let blockedByDependencies = 0;
+      for (const task of tasks) {
+        if (task.status !== 'pending' && task.status !== 'needs_work') continue;
+        if (task.blocked_by.length > 0) {
+          blockedByDependencies++;
+        } else if (!areDependenciesMet(task, tasks)) {
+          blockedByDependencies++;
+        } else {
+          ready++;
+        }
+      }
+
+      const result: TaskStatusSummary = {
+        counts,
+        ready,
+        blocked_by_dependencies: blockedByDependencies,
+        total: tasks.length,
+      };
+
+      return result;
+    })
+
+    // AC: @ui-api-aggregation ac-2 - Extended validation/alignment stats
+    .get('/validation', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const { tasks, items, refIndex } = await buildIndexes(ctx);
+
+      // Run validation for error/warning counts and completeness data
+      const validationResult = await validate(ctx);
+
+      // Build alignment index
+      const alignIndex = new AlignmentIndex(tasks, items);
+      alignIndex.buildLinks(refIndex);
+      const alignStats = alignIndex.getStats();
+      const alignWarnings = alignIndex.findAlignmentWarnings();
+
+      // Entity counts
+      const traitCount = items.filter((item) => item.type === 'trait').length;
+
+      // AC counts from completeness warnings
+      // Count total ACs across all non-trait items
+      let totalACs = 0;
+      for (const item of items) {
+        if (item.type !== 'trait') {
+          totalACs += item.acceptance_criteria?.length || 0;
+        }
+      }
+
+      // Count uncovered ACs from completeness warnings
+      // Each warning represents one item with N uncovered ACs listed in details
+      // Details format: "Uncovered: ac-1, ac-2, ac-3"
+      const uncoveredWarnings = validationResult.completenessWarnings.filter(
+        (w) => w.type === 'missing_test_coverage' && w.subtype === 'own_ac'
+      );
+      let uncoveredCount = 0;
+      for (const warning of uncoveredWarnings) {
+        if (warning.details) {
+          // Parse "Uncovered: ac-1, ac-2, ac-3" to count individual ACs
+          const acList = warning.details.replace(/^Uncovered:\s*/, '');
+          uncoveredCount += acList.split(',').filter((s) => s.trim().length > 0).length;
+        }
+      }
+      const coveredCount = Math.max(0, totalACs - uncoveredCount);
+
+      const result: ValidationAggregation = {
+        stats: {
+          totalSpecs: alignStats.totalSpecs,
+          specsWithTasks: alignStats.specsWithTasks,
+          alignedSpecs: alignStats.alignedSpecs,
+          orphanedSpecs: alignStats.orphanedSpecs,
+        },
+        warnings: alignWarnings,
+        entity_counts: {
+          items: validationResult.stats.itemsChecked,
+          tasks: validationResult.stats.tasksChecked,
+          traits: traitCount,
+        },
+        ac_counts: {
+          total: totalACs,
+          covered: coveredCount,
+          uncovered: uncoveredCount,
+        },
+        orphan_count: validationResult.orphans.length,
+        valid: validationResult.valid,
+        error_count: validationResult.schemaErrors.length + validationResult.refErrors.length,
+        warning_count: validationResult.refWarnings.length + validationResult.completenessWarnings.length,
+      };
+
+      return result;
+    })
+
+    // AC: @ui-api-aggregation ac-3 - Inbox items with inline triage status
+    .get('/inbox', async ({ projectContext }) => {
+      const ctx = await initContext(projectContext.path);
+      const inboxItems = await loadInboxItems(ctx);
+      const triageRecords = await loadTriageRecords(ctx);
+
+      // Sort by created_at descending (newest first)
+      const sorted = [...inboxItems].sort(
+        (a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
+      );
+
+      // Merge triage status inline
+      const items: InboxItemWithTriage[] = sorted.map((item) => {
+        const triageRecord = findTriageRecordByInboxRef(triageRecords, item._ulid);
+
+        const result: InboxItemWithTriage = {
+          _ulid: item._ulid,
+          text: item.text,
+          tags: item.tags,
+          added_by: item.added_by,
+          created_at: item.created_at,
+        };
+
+        if (triageRecord) {
+          result.triage = {
+            _ulid: triageRecord._ulid,
+            status: triageRecord.status as 'pending' | 'triaged' | 'acted_on',
+            action: triageRecord.action as 'promote' | 'delete' | 'defer' | 'spec-gap' | 'duplicate' | undefined,
+            reasoning: triageRecord.reasoning,
+            decided_by: triageRecord.decided_by,
+            acted_at: triageRecord.acted_at,
+            result_ref: triageRecord.result_ref,
+          };
+        }
+
+        return result;
+      });
+
+      return {
+        items,
+        total: items.length,
+      };
+    });
+}

package/dist/daemon/routes/inbox.ts

@@ -88,9 +88,14 @@ export function createInboxRoutes(options: InboxRouteOptions) {
         await commitIfShadow(ctx.shadow, `inbox: add item ${item._ulid}`);
 
         // Broadcast update
+        // AC: @ui-api-aggregation ac-4 - Include full item data for in-place UI updates
         // AC: @multi-directory-daemon ac-18 - Broadcast scoped to request project
         pubsub.broadcast('inbox:updates', 'inbox_item_created', {
           ulid: item._ulid,
+          text: item.text,
+          tags: item.tags,
+          added_by: item.added_by,
+          created_at: item.created_at,
         }, projectContext.path);
 
         // AC: @api-contract ac-13 - Return item with generated ULID

package/dist/daemon/routes/items.ts

@@ -19,12 +19,16 @@ import {
   loadAllItems,
   loadAllTasks,
   loadPlans,
+  findItemByRef,
+  findTaskByRef,
   ReferenceIndex,
   AlignmentIndex,
   getCachedTestCoverage,
   computeACCoverage,
   type LoadedSpecItem,
+  type LoadedTask,
 } from '../../parser/index.js';
+import { getRelatedSessionsForItem } from './session-related.js';
 
 interface ItemsRouteOptions {}
 
@@ -89,6 +93,49 @@ function computeParentMap(items: LoadedSpecItem[]): Map<string, string | undefin
   return parentMap;
 }
 
+function getItemImplementationStatus(item: LoadedSpecItem): string | undefined {
+  if (typeof item.status === 'string') {
+    return item.status;
+  }
+
+  return item.status?.implementation;
+}
+
+function getItemMaturity(item: LoadedSpecItem): string | undefined {
+  if (typeof item.status === 'object') {
+    return item.status?.maturity;
+  }
+
+  return undefined;
+}
+
+function toBatchSpecItemSummary(item: LoadedSpecItem) {
+  return {
+    kind: 'item',
+    ulid: item._ulid,
+    slugs: item.slugs,
+    title: item.title,
+    type: item.type,
+    status: getItemImplementationStatus(item),
+    maturity: getItemMaturity(item),
+    traits: item.traits ?? [],
+    ac_count: item.acceptance_criteria?.length ?? 0,
+  };
+}
+
+function toBatchTaskSummary(task: LoadedTask) {
+  return {
+    kind: 'task',
+    ulid: task._ulid,
+    slugs: task.slugs,
+    title: task.title,
+    status: task.status,
+    priority: task.priority,
+    spec_ref: task.spec_ref,
+    assignee: task.assignee,
+  };
+}
+
 export function createItemsRoutes(options: ItemsRouteOptions = {}) {
   // No closure-scoped kspecDir needed - comes from middleware
 
@@ -206,6 +253,73 @@ export function createItemsRoutes(options: ItemsRouteOptions = {}) {
       }
     )
 
+    .post(
+      '/batch',
+      async ({ body, error: errorResponse, projectContext }) => {
+        const refs = body.refs;
+
+        // AC: @trait-api-endpoint ac-3 - Validate body
+        if (!Array.isArray(refs)) {
+          return errorResponse(400, {
+            error: 'validation_error',
+            details: [
+              {
+                field: 'refs',
+                message: 'Refs is required and must be an array of item references',
+              },
+            ],
+          });
+        }
+
+        // AC: @batch-item-fetch-api ac-5 - Enforce max batch size
+        if (refs.length > 100) {
+          return errorResponse(400, {
+            error: 'validation_error',
+            details: [
+              {
+                field: 'refs',
+                message: 'Maximum batch size is 100 refs',
+              },
+            ],
+          });
+        }
+
+        // AC: @multi-directory-daemon ac-1, ac-24 - Use project context from middleware
+        const ctx = await initContext(projectContext.path);
+        const items = await loadAllItems(ctx);
+        const tasks = await loadAllTasks(ctx);
+
+        const resolvedItems = [];
+        const unresolved: string[] = [];
+
+        for (const ref of refs) {
+          const task = findTaskByRef(tasks, ref);
+          if (task) {
+            resolvedItems.push(toBatchTaskSummary(task));
+            continue;
+          }
+
+          const item = findItemByRef(items, ref);
+          if (item) {
+            resolvedItems.push(toBatchSpecItemSummary(item));
+            continue;
+          }
+
+          unresolved.push(ref);
+        }
+
+        return {
+          items: resolvedItems,
+          unresolved,
+        };
+      },
+      {
+        body: t.Object({
+          refs: t.Optional(t.Array(t.String())),
+        }),
+      }
+    )
+
     // AC: @api-contract ac-10 - Get single item by ref
     .get(
       '/:ref',
@@ -340,5 +454,36 @@ export function createItemsRoutes(options: ItemsRouteOptions = {}) {
           ref: t.String(),
         }),
       }
+    )
+
+    .get(
+      '/:ref/sessions',
+      async ({ params, error: errorResponse, projectContext }) => {
+        const ctx = await initContext(projectContext.path);
+        const items = await loadAllItems(ctx);
+        const tasks = await loadAllTasks(ctx);
+        const result = await getRelatedSessionsForItem({
+          itemRef: params.ref,
+          items,
+          tasks,
+          sessionsDir: ctx.sessionsDir,
+        });
+
+        if ('error' in result) {
+          return errorResponse(404, result.error);
+        }
+
+        return {
+          items: result.sessions,
+          total: result.sessions.length,
+          offset: 0,
+          limit: result.sessions.length,
+        };
+      },
+      {
+        params: t.Object({
+          ref: t.String(),
+        }),
+      }
     );
 }

package/dist/daemon/routes/meta.ts

@@ -202,7 +202,7 @@ export function createMetaRoutes(options: MetaRouteOptions = {}) {
       return {
         project: manifest?.project ?? null,
         spec_version: manifest?.kynetic ?? null,
-        root_dir: ctx.rootDir,
+        root_dir: ctx.projectRoot,
         remote_tracking: config.shadow.remote
           ? { value: config.shadow.remote.value, type: config.shadow.remote.type }
           : null,

package/dist/daemon/routes/projects.ts

@@ -20,10 +20,14 @@ import type { ProjectContextManager } from '../project-context';
 
 interface ProjectsRouteOptions {
   projectManager: ProjectContextManager;
+  /** Called after a project is registered (e.g., to start session sync). */
+  onProjectRegistered?: (projectPath: string) => Promise<void>;
+  /** Called before a project is unregistered (e.g., to stop session sync). */
+  onProjectUnregistered?: (projectPath: string) => void;
 }
 
 export function createProjectsRoutes(options: ProjectsRouteOptions) {
-  const { projectManager } = options;
+  const { projectManager, onProjectRegistered, onProjectUnregistered } = options;
 
   return new Elysia({ prefix: '/api/projects' })
     // AC: @multi-directory-daemon ac-28 - List registered projects
@@ -91,6 +95,16 @@ export function createProjectsRoutes(options: ProjectsRouteOptions) {
             throw error;
           }
 
+          // Start session sync for the newly registered project
+          if (onProjectRegistered) {
+            try {
+              await onProjectRegistered(context.path);
+            } catch (error) {
+              // Session sync init failure does not block project registration
+              console.error(`[daemon] Failed to start session sync for ${context.path}:`, error);
+            }
+          }
+
           return {
             success: true,
             project: {
@@ -135,23 +149,31 @@ export function createProjectsRoutes(options: ProjectsRouteOptions) {
       // AC: @multi-directory-daemon ac-30 - Decode path from URL parameter
       const projectPath = decodeURIComponent(params.encodedPath);
 
-      // Validate project exists
-      if (!projectManager.hasProject(projectPath)) {
+      // Validate project exists and get normalized context
+      let context;
+      try {
+        context = projectManager.getProject(projectPath);
+      } catch {
         return errorResponse(404, {
           error: `Project not registered: ${projectPath}`,
         });
       }
 
       try {
+        // Stop session sync before unregistering (use normalized path)
+        if (onProjectUnregistered) {
+          onProjectUnregistered(context.path);
+        }
+
         // AC: @multi-directory-daemon ac-30 - Stop file watcher
-        await projectManager.stopWatcher(projectPath);
+        await projectManager.stopWatcher(context.path);
 
         // AC: @multi-directory-daemon ac-30 - Unregister project
-        projectManager.unregisterProject(projectPath);
+        projectManager.unregisterProject(context.path);
 
         return {
           success: true,
-          message: `Project unregistered: ${projectPath}`,
+          message: `Project unregistered: ${context.path}`,
         };
       } catch (error: unknown) {
         return errorResponse(500, {