@mxf-dev/core 3.0.0 → 3.2.0

package/src/types/TaskTypes.ts

@@ -109,7 +109,11 @@ export interface ChannelTask {
     dependsOn?: string[];               // Task IDs this task depends on
     blockedBy?: string[];               // Task IDs that block this task
     
-    // Results and outcomes
+    // Results and outcomes. `output` is whatever the caller passed to
+    // completeTask() or the REST completion route, or a TaskCompletionOutput
+    // when an agent completed the task by calling task_complete. There is no
+    // `result.summary` — use getTaskCompletionOutput() to read the summary
+    // safely regardless of which completion path produced this task.
     result?: {
         success?: boolean;
         output?: any;
@@ -117,10 +121,73 @@ export interface ChannelTask {
         completedAt?: number;
         completedBy?: string;
     };
-    
+
     assignmentStrategy: AssignmentStrategy;
 }
 
+/**
+ * What `task_complete` stores in `ChannelTask.result.output`.
+ *
+ * This is the shape TaskService.handleTaskCompletion writes when an agent
+ * completes a task through the task_complete tool. It is not the only shape
+ * `result.output` can hold: a caller can also set `result.output` directly
+ * through completeTask() or the REST completion route, so this type is a
+ * guard to check against, not a blanket narrowing of `output`.
+ */
+export interface TaskCompletionOutput {
+    agentId: string;
+    summary: string;
+    details?: Record<string, unknown>;
+    nextSteps?: string;
+    reportedSuccess: boolean;
+    requestId: string;
+}
+
+/**
+ * Checks whether a value matches the TaskCompletionOutput shape.
+ * Used to read `result.output` from a task without assuming which
+ * completion path (task_complete vs. completeTask()/REST) produced it.
+ */
+export function isTaskCompletionOutput(value: unknown): value is TaskCompletionOutput {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value as Record<string, unknown>;
+    if (typeof candidate.agentId !== 'string' || candidate.agentId.length === 0) {
+        return false;
+    }
+    if (typeof candidate.summary !== 'string') {
+        return false;
+    }
+    if (typeof candidate.reportedSuccess !== 'boolean') {
+        return false;
+    }
+    if (typeof candidate.requestId !== 'string' || candidate.requestId.length === 0) {
+        return false;
+    }
+    if (candidate.details !== undefined) {
+        if (typeof candidate.details !== 'object' || candidate.details === null || Array.isArray(candidate.details)) {
+            return false;
+        }
+    }
+    if (candidate.nextSteps !== undefined && typeof candidate.nextSteps !== 'string') {
+        return false;
+    }
+    return true;
+}
+
+/**
+ * Reads `task.result.output` as a TaskCompletionOutput, or returns undefined
+ * when the task has no result, no output, or an output that does not match
+ * (e.g. a value a caller passed directly to completeTask()/REST).
+ */
+export function getTaskCompletionOutput(
+    task: Pick<ChannelTask, 'result'> | null | undefined
+): TaskCompletionOutput | undefined {
+    const output = task?.result?.output;
+    return isTaskCompletionOutput(output) ? output : undefined;
+}
+
 /**
  * Task creation request
  */

package/src/utils/PromptTemplateReplacer.ts

@@ -31,8 +31,12 @@
  * - {{ISO_TIMESTAMP}}: Current ISO 8601 timestamp
  * - {{AGENT_ID}}: Agent ID (context-based)
  * - {{CHANNEL_ID}}: Channel ID (context-based)
+ * - {{SYSTEM_LLM_STANCE}} / {{SYSTEM_LLM_STANCE_GUIDANCE}}: the channel's SystemLLM stance and what it means for the agent
  */
 
+import { DEFAULT_SYSTEMLLM_STANCE, type SystemLlmStance } from '../types/SystemLlmStanceTypes.js';
+import { buildSystemLlmStanceGuidance } from '../prompts/SystemLlmStanceGuidance.js';
+
 /**
  * Available prompt templates as constants
  * Export these for use in prompt builders
@@ -60,6 +64,8 @@ export const PROMPT_TEMPLATES = {
     LLM_PROVIDER: '{{LLM_PROVIDER}}',
     LLM_MODEL: '{{LLM_MODEL}}',
     SYSTEM_LLM_STATUS: '{{SYSTEM_LLM_STATUS}}',
+    SYSTEM_LLM_STANCE: '{{SYSTEM_LLM_STANCE}}',
+    SYSTEM_LLM_STANCE_GUIDANCE: '{{SYSTEM_LLM_STANCE_GUIDANCE}}',
     OS_PLATFORM: '{{OS_PLATFORM}}',
     
     // Control loop state
@@ -92,6 +98,8 @@ export interface TemplateContext {
     
     // System status
     systemLlmEnabled?: boolean;
+    // SystemLLM stance of the channel; unset is treated as supportive
+    systemLlmStance?: SystemLlmStance;
     
     // Control loop state
     currentOrparPhase?: 'Observe' | 'Reason' | 'Plan' | 'Act' | 'Reflect' | null;
@@ -224,6 +232,15 @@ export class PromptTemplateReplacer {
             const statusStr = context.systemLlmEnabled ? 'Enabled' : 'Disabled';
             result = result.replace(/\{\{SYSTEM_LLM_STATUS\}\}/g, statusStr);
         }
+
+        // Replace the SystemLLM stance and its guidance. Always replaced: an
+        // agent that does not know the stance is told the supportive one, which
+        // is the stance a server that never sends one is running.
+        const stance = context.systemLlmStance ?? DEFAULT_SYSTEMLLM_STANCE;
+        const stanceGuidance = buildSystemLlmStanceGuidance(stance);
+        result = result.replace(/\{\{SYSTEM_LLM_STANCE\}\}/g, stance);
+        // Function replacer: the guidance is prose and must not be parsed for `$` patterns.
+        result = result.replace(/\{\{SYSTEM_LLM_STANCE_GUIDANCE\}\}/g, () => stanceGuidance);
         
         // Replace ORPAR phase - always replace to avoid leftover template markers
         // When phase is null, show "(Not in active cycle)" to indicate ORPAR is available but not running