zigrix 0.1.1 → 0.2.1

package/dist/orchestration/prompt-compose.js

@@ -0,0 +1,172 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { inferStandardAgentRole, normalizeAgentRole, } from '../agents/roles.js';
+const ROLE_RULE_FILE = {
+    orchestrator: 'orchestrator-agent.md',
+    qa: 'qa-agent.md',
+    security: 'security-agent.md',
+    frontend: 'frontend-agent.md',
+    backend: 'backend-agent.md',
+    system: 'system-agent.md',
+};
+const WORKER_COMMON_RULE_FILE = 'worker-common.md';
+function bundledRulesDir() {
+    return path.resolve(fileURLToPath(new URL('../../rules/defaults', import.meta.url)));
+}
+function firstReadableRulePath(paths, fileName) {
+    const candidates = [
+        path.join(paths.rulesDir, fileName),
+        path.join(bundledRulesDir(), fileName),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function loadRuleText(paths, fileName) {
+    const resolved = firstReadableRulePath(paths, fileName);
+    if (!resolved) {
+        throw new Error(`required Zigrix rule file not found: ${fileName}`);
+    }
+    return fs.readFileSync(resolved, 'utf8').trim();
+}
+function compactBlock(text) {
+    return text.replace(/\r\n/g, '\n').trim();
+}
+function joinPromptBlocks(...blocks) {
+    return blocks
+        .map((block) => (typeof block === 'string' ? compactBlock(block) : ''))
+        .filter((block) => block.length > 0)
+        .join('\n\n---\n\n');
+}
+function renderRoleMap(task) {
+    const entries = Object.entries(task.roleAgentMap ?? {}).filter(([, ids]) => Array.isArray(ids) && ids.length > 0);
+    if (entries.length === 0)
+        return '- (none)';
+    return entries.map(([role, ids]) => `- ${role}: ${ids.join(', ')}`).join('\n');
+}
+function resolveTaskRole(task, agentId) {
+    if (typeof task.orchestratorId === 'string' && task.orchestratorId === agentId)
+        return 'orchestrator';
+    if (typeof task.qaAgentId === 'string' && task.qaAgentId === agentId)
+        return 'qa';
+    const roleMap = task.roleAgentMap;
+    if (roleMap && typeof roleMap === 'object') {
+        for (const [role, agentIds] of Object.entries(roleMap)) {
+            if (!Array.isArray(agentIds))
+                continue;
+            if (agentIds.includes(agentId)) {
+                const normalized = normalizeAgentRole(role);
+                if (normalized)
+                    return normalized;
+            }
+        }
+    }
+    return null;
+}
+export function resolveAgentRole(config, task, agentId) {
+    const fromTask = resolveTaskRole(task, agentId);
+    if (fromTask)
+        return fromTask;
+    const fromRegistry = config.agents.registry[agentId]?.role;
+    if (typeof fromRegistry === 'string') {
+        const normalized = normalizeAgentRole(fromRegistry);
+        if (normalized)
+            return normalized;
+    }
+    return inferStandardAgentRole({ agentId, theme: null });
+}
+export function buildSpawnLabel(taskId, agentId) {
+    return `[${agentId}] ${taskId}`;
+}
+export function composeOrchestratorPrompt(params) {
+    const roleRule = loadRuleText(params.paths, ROLE_RULE_FILE.orchestrator);
+    const overlay = [
+        `## Runtime Task Overlay: ${params.task.taskId}`,
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        `| taskId | ${params.task.taskId} |`,
+        `| title | ${params.task.title} |`,
+        `| scale | ${params.task.scale} |`,
+        `| orchestratorId | ${params.orchestratorId} |`,
+        `| qaAgentId | ${params.qaAgentId} |`,
+        `| specPath | ${params.specPath} |`,
+        `| metaPath | ${params.metaPath} |`,
+        `| promptPath | ${params.promptPath} |`,
+        ...(params.projectDir ? [`| projectDir | ${params.projectDir} |`] : []),
+        '',
+        '### Authority Boundary',
+        '- 이 prompt는 Zigrix orchestrator role rule + task overlay를 합성한 canonical instruction이다.',
+        '- 메인 전용 skill (`zigrix-main-agent-guide`)이나 일반 OpenClaw skill discovery를 근거 규칙으로 삼지 않는다.',
+        '- 실제 runtime agentId는 아래 role mapping과 task metadata를 따른다.',
+        '',
+        '### Original Request',
+        params.task.description,
+        params.constraints ? `\n### Constraints\n${params.constraints}` : '',
+        '',
+        '### Runtime Role Mapping',
+        renderRoleMap(params.task),
+        '',
+        '### Required CLI Chain',
+        '1. `zigrix task start <taskId> --json`',
+        '2. `zigrix task status <taskId> --json`',
+        '3. 필요 워커마다 `zigrix worker prepare → sessions_spawn → zigrix worker register → zigrix worker complete`',
+        '4. evidence 수집/머지 확인',
+        '5. `zigrix task finalize <taskId> --json`',
+        '',
+        '### Worker Dispatch Contract',
+        '- worker spawn 전에 반드시 `zigrix worker prepare --task-id <taskId> --agent-id <workerId> --description "..." --json` 를 호출해 worker prompt / projectDir / spawnLabel을 확보한다.',
+        '- worker spawn 시 `agentId`, `label`, `cwd`, `task` 를 모두 명시한다.',
+        '- spawn 후에는 prepare 응답의 `spawnLabel` / `projectDir` 와 실제 `sessionKey` / `sessionId` 를 함께 `zigrix worker register` 에 전달한다.',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return joinPromptBlocks(roleRule, overlay);
+}
+export function composeWorkerPrompt(params) {
+    const role = resolveAgentRole(params.config, params.task, params.agentId);
+    const roleRule = loadRuleText(params.paths, ROLE_RULE_FILE[role]);
+    const baseRule = role === 'orchestrator' ? '' : loadRuleText(params.paths, WORKER_COMMON_RULE_FILE);
+    const overlay = [
+        `## Runtime Worker Overlay: ${params.task.taskId}`,
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        `| taskId | ${params.task.taskId} |`,
+        `| title | ${params.task.title} |`,
+        `| scale | ${params.task.scale} |`,
+        `| agentId | ${params.agentId} |`,
+        `| role | ${role} |`,
+        `| specPath | ${params.specPath} |`,
+        `| metaPath | ${params.metaPath} |`,
+        `| promptPath | ${params.promptPath} |`,
+        ...(params.projectDir ? [`| projectDir | ${params.projectDir} |`] : []),
+        '',
+        '### Authority Boundary',
+        '- 이 prompt는 Zigrix role rule + task overlay를 합성한 canonical worker instruction이다.',
+        '- 메인 전용 skill (`zigrix-main-agent-guide`)이나 일반 OpenClaw skill discovery를 근거 규칙으로 삼지 않는다.',
+        '- role rule 안의 예시 agent 이름보다 현재 overlay의 `agentId` / `role` / `projectDir` 를 우선 적용한다.',
+        '',
+        '### Assignment',
+        params.description,
+        params.constraints ? `\n### Constraints\n${params.constraints}` : '',
+        params.dod ? `\n### Definition of Done\n${params.dod}` : '',
+        params.unitId || params.workPackage
+            ? `\n### Execution Context\n- unitId: ${params.unitId ?? 'N/A'}\n- workPackage: ${params.workPackage ?? 'N/A'}`
+            : '',
+        '',
+        '### Completion Chain',
+        `- evidence collect: \`zigrix evidence collect --task-id ${params.task.taskId} --agent-id ${params.agentId} --summary "<result summary>"\``,
+        '- 결과 보고에는 taskId / sessionKey / runId / evidence / risks 를 포함한다.',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return {
+        role,
+        prompt: joinPromptBlocks(baseRule, roleRule, overlay),
+    };
+}

package/dist/orchestration/worker.d.ts

@@ -1,8 +1,9 @@
+import type { ZigrixConfig } from '../config/schema.js';
 import { type ZigrixPaths } from '../state/paths.js';
 import { type ZigrixTask } from '../state/tasks.js';
 export declare const DEFAULT_REQUIRED_ROLES: readonly ["orchestrator", "qa"];
 export declare function resolveRequiredAgents(task: Partial<ZigrixTask> & Record<string, unknown>): string[];
-export declare function prepareWorker(paths: ZigrixPaths, params: {
+export declare function prepareWorker(paths: ZigrixPaths, config: ZigrixConfig, params: {
     taskId: string;
     agentId: string;
     description: string;
@@ -21,6 +22,8 @@ export declare function registerWorker(paths: ZigrixPaths, params: {
     unitId?: string;
     workPackage?: string;
     reason?: string;
+    label?: string;
+    projectDir?: string;
 }): Record<string, unknown> | null;
 export declare function completeWorker(paths: ZigrixPaths, params: {
     taskId: string;

package/dist/orchestration/worker.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { appendEvent } from '../state/events.js';
 import { ensureBaseState } from '../state/paths.js';
 import { loadTask, resolveTaskPaths, saveTask } from '../state/tasks.js';
+import { buildSpawnLabel, composeWorkerPrompt } from './prompt-compose.js';
 export const DEFAULT_REQUIRED_ROLES = ['orchestrator', 'qa'];
 function firstNonEmpty(...values) {
     for (const value of values) {
@@ -47,45 +48,51 @@ export function resolveRequiredAgents(task) {
     }
     return resolveDefaultRequiredAgents(task);
 }
-function renderPrompt(params) {
-    const sections = [
-        `## Worker Assignment: ${params.task.taskId}`,
-        '',
-        '| Field | Value |',
-        '|---|---|',
-        `| taskId | ${params.task.taskId} |`,
-        `| title | ${params.task.title} |`,
-        `| scale | ${params.task.scale} |`,
-        `| role | ${params.agentId} |`,
-        ...(params.projectDir ? [`| projectDir | ${params.projectDir} |`] : []),
-        '',
-        '### Assignment',
-        params.description,
-    ];
-    if (params.constraints)
-        sections.push('', '### Constraints', params.constraints);
-    if (params.dod)
-        sections.push('', '### Definition of Done', params.dod);
-    if (params.unitId || params.workPackage) {
-        sections.push('', '### Execution Context', `- unitId: ${params.unitId ?? 'N/A'}`, `- workPackage: ${params.workPackage ?? 'N/A'}`);
-    }
-    sections.push('', '### Completion', '작업 완료 후 다음 순서를 반드시 따르라:', '', '1. **증적(evidence) 수집** — 작업 결과 증적을 먼저 기록한다:', '   ```bash', `   zigrix evidence collect --task-id ${params.task.taskId} --agent-id ${params.agentId} --summary "<작업 결과 요약>"`, '   ```', '2. **결과 보고** — 증적 수집 완료 후 결과와 근거를 명확히 보고하라.', '', '⚠️ 증적 없이 완료하면 finalize에서 incomplete 판정된다.');
-    return sections.join('\n');
+function normalizePathValue(value) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        return null;
+    return path.resolve(value.trim());
+}
+function parseSessionKey(sessionKey) {
+    const matched = sessionKey.match(/^agent:([^:]+):subagent:([^:\s]+)$/);
+    if (!matched)
+        return null;
+    return { agentId: matched[1], sessionId: matched[2] };
 }
-export function prepareWorker(paths, params) {
+export function prepareWorker(paths, config, params) {
     ensureBaseState(paths);
     const task = loadTask(paths, params.taskId);
     if (!task)
         return null;
-    const projectDir = params.projectDir ?? task.projectDir;
-    const prompt = renderPrompt({ task, ...params, projectDir });
+    const taskPaths = resolveTaskPaths(paths, params.taskId);
     const promptPath = path.join(paths.promptsDir, `${params.taskId}-${params.agentId}.md`);
-    fs.writeFileSync(promptPath, `${prompt}\n`, 'utf8');
+    const projectDir = normalizePathValue(params.projectDir ?? task.projectDir ?? null);
+    const spawnLabel = buildSpawnLabel(params.taskId, params.agentId);
+    const composed = composeWorkerPrompt({
+        paths,
+        config,
+        task,
+        agentId: params.agentId,
+        description: params.description,
+        constraints: params.constraints,
+        unitId: params.unitId,
+        workPackage: params.workPackage,
+        dod: params.dod,
+        projectDir,
+        promptPath,
+        specPath: taskPaths.specPath,
+        metaPath: taskPaths.metaPath,
+    });
+    fs.writeFileSync(promptPath, `${composed.prompt}\n`, 'utf8');
     task.workerSessions[params.agentId] = {
+        ...(task.workerSessions[params.agentId] ?? {}),
         status: 'prepared',
+        role: composed.role,
         unitId: params.unitId,
         workPackage: params.workPackage,
         promptPath,
+        expectedLabel: spawnLabel,
+        projectDir,
     };
     const required = task.requiredAgents.length > 0 ? task.requiredAgents : resolveRequiredAgents(task);
     if (!required.includes(params.agentId))
@@ -101,36 +108,60 @@ export function prepareWorker(paths, params) {
         status: 'IN_PROGRESS',
         unitId: params.unitId,
         workPackage: params.workPackage,
-        payload: { agentId: params.agentId, description: params.description, constraints: params.constraints ?? '', dod: params.dod ?? '', promptPath },
+        payload: {
+            agentId: params.agentId,
+            role: composed.role,
+            description: params.description,
+            constraints: params.constraints ?? '',
+            dod: params.dod ?? '',
+            promptPath,
+            spawnLabel,
+            projectDir,
+        },
     });
     return {
         ok: true,
         taskId: params.taskId,
         agentId: params.agentId,
+        role: composed.role,
         promptPath,
-        prompt,
+        prompt: composed.prompt,
         unitId: params.unitId,
         workPackage: params.workPackage,
-        projectDir: projectDir ?? null,
-        ...resolveTaskPaths(paths, params.taskId),
+        projectDir,
+        spawnLabel,
+        ...taskPaths,
     };
 }
-/**
- * Extract sessionId from a sessionKey of the form `agent:<agentId>:subagent:<sessionId>`.
- * Returns null if the sessionKey does not match the expected pattern.
- */
-function parseSessionIdFromKey(sessionKey) {
-    const matched = sessionKey.match(/^agent:[^:]+:subagent:([^:\s]+)$/);
-    return matched?.[1] ?? null;
-}
 export function registerWorker(paths, params) {
     const task = loadTask(paths, params.taskId);
     if (!task)
         return null;
-    // Resolve sessionId: use provided value, or fall back to parsing it from sessionKey
-    const resolvedSessionId = params.sessionId || parseSessionIdFromKey(params.sessionKey) || null;
+    const parsedKey = parseSessionKey(params.sessionKey);
+    if (parsedKey && parsedKey.agentId !== params.agentId) {
+        throw new Error(`worker register validation failed: sessionKey belongs to '${parsedKey.agentId}', expected '${params.agentId}'`);
+    }
+    const previous = task.workerSessions[params.agentId] ?? {};
+    const expectedLabel = firstNonEmpty(previous.expectedLabel) ?? buildSpawnLabel(params.taskId, params.agentId);
+    const providedLabel = firstNonEmpty(params.label);
+    if (!providedLabel) {
+        throw new Error('worker register validation failed: label is required (use spawnLabel from worker prepare).');
+    }
+    if (providedLabel !== expectedLabel) {
+        throw new Error(`worker register validation failed: label mismatch (expected '${expectedLabel}', got '${providedLabel}')`);
+    }
+    const expectedProjectDir = normalizePathValue(firstNonEmpty(previous.projectDir, task.projectDir));
+    const providedProjectDir = normalizePathValue(params.projectDir);
+    if (expectedProjectDir && !providedProjectDir) {
+        throw new Error('worker register validation failed: projectDir is required for this task.');
+    }
+    if (expectedProjectDir && providedProjectDir && expectedProjectDir !== providedProjectDir) {
+        throw new Error(`worker register validation failed: projectDir mismatch (expected '${expectedProjectDir}', got '${providedProjectDir}')`);
+    }
+    const resolvedSessionId = params.sessionId || parsedKey?.sessionId || null;
+    const resolvedProjectDir = providedProjectDir ?? expectedProjectDir;
     task.workerSessions[params.agentId] = {
-        ...(task.workerSessions[params.agentId] ?? {}),
+        ...previous,
         status: 'dispatched',
         sessionKey: params.sessionKey,
         runId: params.runId ?? '',
@@ -138,6 +169,9 @@ export function registerWorker(paths, params) {
         unitId: params.unitId,
         workPackage: params.workPackage,
         reason: params.reason ?? '',
+        label: providedLabel,
+        expectedLabel,
+        projectDir: resolvedProjectDir,
     };
     const required = task.requiredAgents.length > 0 ? task.requiredAgents : resolveRequiredAgents(task);
     if (!required.includes(params.agentId))
@@ -145,11 +179,37 @@ export function registerWorker(paths, params) {
     task.requiredAgents = required;
     saveTask(paths, task);
     appendEvent(paths.eventsFile, {
-        event: 'worker_dispatched', taskId: params.taskId, phase: 'execution', actor: 'zigrix', targetAgent: params.agentId, status: 'IN_PROGRESS',
-        sessionKey: params.sessionKey, sessionId: resolvedSessionId, unitId: params.unitId, workPackage: params.workPackage,
-        payload: { agentId: params.agentId, runId: params.runId ?? '', reason: params.reason ?? '' },
+        event: 'worker_dispatched',
+        taskId: params.taskId,
+        phase: 'execution',
+        actor: 'zigrix',
+        targetAgent: params.agentId,
+        status: 'IN_PROGRESS',
+        sessionKey: params.sessionKey,
+        sessionId: resolvedSessionId,
+        unitId: params.unitId,
+        workPackage: params.workPackage,
+        payload: {
+            agentId: params.agentId,
+            runId: params.runId ?? '',
+            reason: params.reason ?? '',
+            label: providedLabel,
+            projectDir: resolvedProjectDir,
+        },
     });
-    return { ok: true, taskId: params.taskId, agentId: params.agentId, sessionKey: params.sessionKey, runId: params.runId ?? '', sessionId: resolvedSessionId, unitId: params.unitId, workPackage: params.workPackage, status: 'dispatched' };
+    return {
+        ok: true,
+        taskId: params.taskId,
+        agentId: params.agentId,
+        sessionKey: params.sessionKey,
+        runId: params.runId ?? '',
+        sessionId: resolvedSessionId,
+        unitId: params.unitId,
+        workPackage: params.workPackage,
+        label: providedLabel,
+        projectDir: resolvedProjectDir,
+        status: 'dispatched',
+    };
 }
 export function completeWorker(paths, params) {
     const task = loadTask(paths, params.taskId);
@@ -167,16 +227,36 @@ export function completeWorker(paths, params) {
     };
     saveTask(paths, task);
     appendEvent(paths.eventsFile, {
-        event: 'worker_done', taskId: params.taskId, phase: 'execution', actor: params.agentId, targetAgent: params.agentId,
-        status: (params.result ?? 'done') === 'blocked' ? 'BLOCKED' : 'IN_PROGRESS', sessionKey: params.sessionKey, sessionId: params.sessionId ?? null,
-        unitId: params.unitId ?? prev.unitId, workPackage: params.workPackage ?? prev.workPackage,
+        event: 'worker_done',
+        taskId: params.taskId,
+        phase: 'execution',
+        actor: params.agentId,
+        targetAgent: params.agentId,
+        status: (params.result ?? 'done') === 'blocked' ? 'BLOCKED' : 'IN_PROGRESS',
+        sessionKey: params.sessionKey,
+        sessionId: params.sessionId ?? null,
+        unitId: params.unitId ?? prev.unitId,
+        workPackage: params.workPackage ?? prev.workPackage,
         payload: { result: params.result ?? 'done', runId: params.runId },
     });
     const evidenceDir = path.join(paths.evidenceDir, params.taskId);
     const presentAgents = fs.existsSync(evidenceDir)
-        ? fs.readdirSync(evidenceDir).filter((file) => file.endsWith('.json') && file !== '_merged.json').map((file) => path.basename(file, '.json')).sort()
+        ? fs
+            .readdirSync(evidenceDir)
+            .filter((file) => file.endsWith('.json') && file !== '_merged.json')
+            .map((file) => path.basename(file, '.json'))
+            .sort()
         : [];
     const required = resolveRequiredAgents(task);
     const missingAgents = required.filter((agentId) => !presentAgents.includes(agentId));
-    return { ok: true, taskId: params.taskId, agentId: params.agentId, result: params.result ?? 'done', requiredAgents: required, presentEvidenceAgents: presentAgents, missingEvidenceAgents: missingAgents, allEvidenceCollected: missingAgents.length === 0 };
+    return {
+        ok: true,
+        taskId: params.taskId,
+        agentId: params.agentId,
+        result: params.result ?? 'done',
+        requiredAgents: required,
+        presentEvidenceAgents: presentAgents,
+        missingEvidenceAgents: missingAgents,
+        allEvidenceCollected: missingAgents.length === 0,
+    };
 }

package/dist/state/tasks.d.ts

@@ -40,6 +40,36 @@ export type ZigrixTask = {
     qaAgentId?: string;
     orchestratorSessionKey?: string;
     orchestratorSessionId?: string;
+    nextAction?: string;
+    resumeHint?: string;
+    staleReason?: string;
+    staleReasons?: string[];
+};
+export type StaleReasonCode = 'stale_timeout' | 'session_dead' | 'missing_session_mapping';
+export type SessionDiagnosis = {
+    scope: 'orchestrator' | 'worker';
+    agentId: string;
+    sessionKey: string;
+    sessionId: string | null;
+    mappingSource: 'explicit' | 'parsed' | 'sessions_json' | 'none';
+    state: 'active' | 'deleted' | 'missing';
+    reason: 'session_dead' | 'missing_session_mapping' | null;
+    activePath: string | null;
+    deletedPath: string | null;
+};
+export type StaleTaskSummary = {
+    taskId: string;
+    title: string;
+    updatedAt: string;
+    hoursThreshold: number;
+    timedOut: boolean;
+    reason: string;
+    reasonCode: StaleReasonCode;
+    reasons: StaleReasonCode[];
+    nextAction: string;
+    resumeHint: string;
+    reportLine: string;
+    sessions: SessionDiagnosis[];
 };
 export declare function resolveTaskPaths(paths: ZigrixPaths, taskId: string): {
     specPath: string;
@@ -61,6 +91,12 @@ export declare function createTask(paths: ZigrixPaths, params: {
     prefix?: string;
 }): ZigrixTask;
 export declare function updateTaskStatus(paths: ZigrixPaths, taskId: string, status: string): ZigrixTask | null;
+export declare function bindOrchestratorSession(paths: ZigrixPaths, params: {
+    taskId: string;
+    agentId: string;
+    sessionKey: string;
+    sessionId?: string;
+}): Record<string, unknown> | null;
 export declare function recordTaskProgress(paths: ZigrixPaths, params: {
     taskId: string;
     actor: string;
@@ -68,6 +104,11 @@ export declare function recordTaskProgress(paths: ZigrixPaths, params: {
     unitId?: string;
     workPackage?: string;
 }): Record<string, unknown> | null;
-export declare function findStaleTasks(paths: ZigrixPaths, hours?: number): ZigrixTask[];
-export declare function applyStalePolicy(paths: ZigrixPaths, hours?: number, reason?: string): Record<string, unknown>;
+type StalePolicyOptions = {
+    agentsStateDir?: string | null;
+    fallbackReason?: string;
+};
+export declare function findStaleTasks(paths: ZigrixPaths, hours?: number, options?: StalePolicyOptions): StaleTaskSummary[];
+export declare function applyStalePolicy(paths: ZigrixPaths, hours?: number, reason?: string, options?: StalePolicyOptions): Record<string, unknown>;
 export declare function rebuildIndex(paths: ZigrixPaths): Record<string, unknown>;
+export {};