@memberjunction/server 6.1.0-edge.0 → 6.1.0-edge.2

package/src/resolvers/TaskGraphFrameResolver.ts

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Live signal for durable task graphs — the dispatcher's lifecycle frames, published
+ * to anyone watching a given graph.
+ *
+ * **Why frames rather than cache invalidation.** The alternative considered was emitting
+ * invalidation events after each CAS claim so clients re-read Task rows. That works, but it makes
+ * every consumer reconstruct meaning by diffing rows, and couples the UI to claim mechanics. A
+ * frame says what happened — "this step failed, here is why" — so a viewer renders progress
+ * directly. This is §3.4's originally-promised mechanism.
+ *
+ * **Addressed by `ParentTaskID`, deliberately not by session.** A durable graph outlives the tab
+ * that submitted it, and may be started by a schedule with no session at all. Keying on the graph
+ * means "watch this workflow run" works for whoever is permitted to see it, whenever they arrive —
+ * including after a page refresh, which a session-keyed push cannot survive.
+ *
+ * @module @memberjunction/server
+ */
+import { Arg, Field, ID, ObjectType, PubSubEngine, Resolver, ResolverFilterData, Root, Subscription } from 'type-graphql';
+import { LogError } from '@memberjunction/core';
+import { UUIDsEqual } from '@memberjunction/global';
+import type { TaskGraphFrame, TaskGraphObserver } from '@memberjunction/task-graph';
+
+export const TASK_GRAPH_FRAMES_TOPIC = 'TASK_GRAPH_FRAMES';
+
+/** One lifecycle event, as it reaches a subscriber. */
+@ObjectType()
+export class TaskGraphFrameNotification {
+  @Field(() => String)
+  kind!: string;
+
+  @Field(() => ID)
+  parentTaskId!: string;
+
+  @Field(() => ID, { nullable: true })
+  taskId?: string;
+
+  @Field(() => String, { nullable: true })
+  taskName?: string;
+
+  @Field(() => String, { nullable: true })
+  status?: string;
+
+  @Field(() => String, { nullable: true })
+  errorMessage?: string;
+
+  @Field(() => ID, { nullable: true })
+  assignedUserId?: string;
+
+  @Field(() => Number, { nullable: true })
+  completedCount?: number;
+
+  @Field(() => Number, { nullable: true })
+  totalCount?: number;
+
+  @Field(() => Date)
+  date!: Date;
+}
+
+/**
+ * Wire payload. Identical to {@link TaskGraphFrame} plus the graph's owner, which exists ONLY as the
+ * server-side filter key and is never returned to a subscriber — the same discipline
+ * `PushStatusNotificationPayload` uses for `ownerUserId`.
+ */
+export interface TaskGraphFramePayload extends TaskGraphFrame {
+  /** User the graph belongs to. Filter key; never sent to the client. */
+  ownerUserId: string;
+}
+
+interface TaskGraphFrameArgs {
+  parentTaskId: string;
+}
+
+/** Minimal shape of the subscription's connection context needed by the filter. */
+export interface TaskGraphFrameFilterContext {
+  userPayload?: { userRecord?: { ID?: string } };
+}
+
+/**
+ * Delivery predicate. A frame reaches a subscriber only when BOTH hold:
+ *   1. it belongs to the graph the subscriber asked to watch, AND
+ *   2. the graph's owner matches the subscriber CONNECTION's authenticated identity.
+ *
+ * Condition 2 is load-bearing, and for the same reason `statusUpdatesFilter` needs it: a
+ * `parentTaskId` is discoverable, so without an identity check anyone holding one could watch
+ * another user's workflow — including its per-step error messages. **Fails closed** — a missing
+ * identity on either side never matches.
+ */
+export function taskGraphFrameFilter(data: {
+  payload: TaskGraphFramePayload;
+  args: TaskGraphFrameArgs;
+  context: TaskGraphFrameFilterContext | undefined;
+}): boolean {
+  const { payload, args, context } = data;
+  if (!payload.ParentTaskID || !args.parentTaskId) {
+    return false;
+  }
+  if (!UUIDsEqual(payload.ParentTaskID, args.parentTaskId)) {
+    return false;
+  }
+  const connectionUserId = context?.userPayload?.userRecord?.ID;
+  if (!connectionUserId || !payload.ownerUserId) {
+    return false; // fail closed
+  }
+  return UUIDsEqual(payload.ownerUserId, connectionUserId);
+}
+
+/**
+ * MJServer's `TaskGraphObserver` — turns dispatcher frames into a PubSub publish.
+ *
+ * `OnFrame` is synchronous and swallows everything by contract: a frame is commentary on work, never
+ * a step of it, so nothing here may stall or fail a graph. The publish itself is fire-and-forget for
+ * the same reason.
+ */
+export class TaskGraphFrameBroadcaster implements TaskGraphObserver {
+  constructor(private readonly pubSub: PubSubEngine) {}
+
+  public OnFrame(frame: TaskGraphFrame): void {
+    try {
+      if (!frame.OwnerUserID) {
+        // A graph with no recorded owner cannot be authorized to anyone, so publishing would only
+        // produce frames the filter refuses. Dropping is the same outcome, without the traffic.
+        // Reachable for graphs submitted before ownership was recorded on the parent.
+        return;
+      }
+      void this.pubSub.publish(
+        TASK_GRAPH_FRAMES_TOPIC,
+        { ...frame, ownerUserId: frame.OwnerUserID } satisfies TaskGraphFramePayload,
+      );
+    } catch (e) {
+      LogError(`[TaskGraphFrameBroadcaster] Could not publish ${frame.Kind} (ignored): ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+}
+
+@Resolver()
+export class TaskGraphFrameResolver {
+  @Subscription(() => TaskGraphFrameNotification, {
+    topics: TASK_GRAPH_FRAMES_TOPIC,
+    filter: (data: ResolverFilterData<TaskGraphFramePayload, TaskGraphFrameArgs, TaskGraphFrameFilterContext>) =>
+      taskGraphFrameFilter(data),
+  })
+  taskGraphFrames(
+    @Root() payload: TaskGraphFramePayload,
+    @Arg('parentTaskId', () => ID) parentTaskId: string
+  ): TaskGraphFrameNotification {
+    // ownerUserId is intentionally NOT returned — it is a server-side filter key only.
+    return {
+      kind: payload.Kind,
+      parentTaskId,
+      taskId: payload.TaskID,
+      taskName: payload.TaskName,
+      status: payload.Status,
+      errorMessage: payload.ErrorMessage,
+      assignedUserId: payload.AssignedUserID,
+      completedCount: payload.CompletedCount,
+      totalCount: payload.TotalCount,
+      date: new Date(),
+    };
+  }
+}

package/src/resolvers/UserFavoriteResolver.ts

@@ -14,7 +14,7 @@ import {
   Query,
   Resolver,
 } from '@memberjunction/server';
-import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import { UserCache } from '@memberjunction/generic-database-provider';
 
 import { MJUserFavorite_, MJUserFavoriteResolverBase } from '../generated/generated.js';
 import { GetReadOnlyProvider } from '../util.js';

package/src/rest/OAuthCallbackHandler.ts

@@ -15,7 +15,7 @@
 import express from 'express';
 import { LogError, LogStatus, RunView, UserInfo } from '@memberjunction/core';
 import { UUIDsEqual } from '@memberjunction/global';
-import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import { UserCache } from '@memberjunction/generic-database-provider';
 import { OAuthManager, MCPClientManager } from '@memberjunction/ai-mcp-client';
 import type { MCPServerOAuthConfig } from '@memberjunction/ai-mcp-client';
 

package/src/rest/RESTEndpointHandler.ts

@@ -189,8 +189,7 @@ export class RESTEndpointHandler {
         // Transaction operations
         this.router.post('/transactions', this.executeTransaction.bind(this));
         
-        // Reports and queries
-        this.router.get('/reports/:reportId', this.runReport.bind(this));
+        // Queries
         this.router.post('/queries/run', this.runQuery.bind(this));
         
         // Error handling
@@ -781,19 +780,6 @@ export class RESTEndpointHandler {
         }
     }
 
-    /**
-     * Run a report
-     */
-    private async runReport(req: express.Request, res: express.Response): Promise<void> {
-        try {
-            // Placeholder implementation - this would need to be implemented to run reports
-            res.status(501).json({ error: 'Not implemented' });
-        } catch (error) {
-            LogError(error);
-            res.status(500).json({ error: (error as Error)?.message || 'Unknown error' });
-        }
-    }
-
     /**
      * Run a query
      */

package/src/rest/SignatureWebhookHandler.ts

@@ -14,7 +14,7 @@
 import express from 'express';
 import BodyParser from 'body-parser';
 import { LogError, LogStatus, UserInfo } from '@memberjunction/core';
-import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import { UserCache } from '@memberjunction/generic-database-provider';
 import { SignatureEngine } from '@memberjunction/esignature/server';
 
 /**

package/src/services/DurableEntityActionTaskSubmitter.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview MJServer's implementation of the `DurableEntityActionSubmitter` seam.
+ *
+ * Turns one After* entity-action dispatch into a single-node durable task graph, which is D14's
+ * whole answer to "run this durably": not a new queue, the substrate that already has a claim
+ * protocol, restart recovery and orphan reclaim.
+ *
+ * Registered at boot beside the dispatcher, because the two are one capability — a submitter with
+ * no dispatcher writes rows nobody picks up, which is worse than staying inline.
+ *
+ * @module @memberjunction/server
+ */
+import type {
+    DurableEntityActionRequest,
+    DurableEntityActionSubmission,
+    DurableEntityActionSubmitter,
+} from '@memberjunction/actions-base';
+import { LogError } from '@memberjunction/core';
+import { TaskNode, type TaskGraphSpec } from '@memberjunction/ai-core-plus';
+import { MJEnvironmentEntityExtended } from '@memberjunction/core-entities';
+import { TaskGraphService, type ProviderFactory } from '@memberjunction/task-graph';
+
+export class DurableEntityActionTaskSubmitter implements DurableEntityActionSubmitter {
+    /**
+     * @param environmentID which environment the tasks belong to. Defaults to the platform default
+     *   because a save has no environment of its own to inherit — the record's entity is global, and
+     *   inventing a per-save environment would put a durable dispatch somewhere nobody looks.
+     */
+    constructor(
+        private readonly providerFactory: ProviderFactory,
+        private readonly environmentID: string = MJEnvironmentEntityExtended.DefaultEnvironmentID,
+    ) {}
+
+    public async Submit(request: DurableEntityActionRequest): Promise<DurableEntityActionSubmission> {
+        try {
+            const spec: TaskGraphSpec = {
+                workflowName: `${request.ActionName} — ${request.EntityName}`,
+                reasoning:
+                    `Durable dispatch of entity action binding ${request.EntityActionID} on ` +
+                    `${request.EntityName} (${request.RecordID}), fired by ${request.InvocationType}.`,
+                tasks: [
+                    TaskNode.Action(
+                        {
+                            tempId: 'action',
+                            name: request.ActionName,
+                            description: `Run ${request.ActionName} for ${request.EntityName} ${request.RecordID}.`,
+                            dependsOn: [],
+                            inputPayload: request.RedactedParams,
+                        },
+                        { actionName: request.ActionName },
+                    ),
+                ],
+                // Nothing to say to anyone: this graph exists because a record was saved, not
+                // because a person asked a question. Defaulting to 'message' would post an
+                // orphaned result into whichever conversation happened to be nearby.
+                continuation: 'none',
+                // The point of the exercise. A one-node graph constant-folds to in-run execution by
+                // default (D9), which is exactly the fire-and-forget behaviour being escaped.
+                durable: true,
+            };
+
+            const provider = await this.providerFactory.CreateProvider();
+            const result = await new TaskGraphService().Submit(spec, {
+                EnvironmentID: this.environmentID,
+                ContextUser: request.ContextUser,
+                Provider: provider,
+            });
+
+            return result.Success
+                ? { Success: true, ParentTaskID: result.ParentTaskID }
+                : { Success: false, ErrorMessage: result.ErrorMessage };
+        } catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            LogError(`[DurableEntityActionTaskSubmitter] Submission failed for binding ${request.EntityActionID}: ${message}`);
+            return { Success: false, ErrorMessage: message };
+        }
+    }
+}

package/src/services/ScheduledJobsService.ts

@@ -4,7 +4,7 @@
  */
 
 import { LogError, LogStatus, LogStatusEx, UserInfo } from '@memberjunction/core';
-import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import { UserCache } from '@memberjunction/generic-database-provider';
 import { SchedulingEngine } from '@memberjunction/scheduling-engine';
 import { ScheduledJobsConfig } from '../config.js';
 

package/src/services/StartTaskGraphDispatcher.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Boots the durable task-graph dispatcher inside MJServer.
+ *
+ * Phase 2 landed the dispatcher and the submission path but never started anything, so a submitted
+ * graph persisted correctly and then sat in `Pending` forever. Submission being durable is only
+ * half the promise — something has to *pick the work up*.
+ *
+ * The continuation deliverer is supplied here for the same reason the agent runner is: posting into
+ * a conversation is a host concern the package deliberately refuses to know about.
+ *
+ * Registration of the package's Remote Operations is a separate concern handled by the generated
+ * class-registration manifests (`ServerBootstrap` / `ServerBootstrapLite`), which import the
+ * subclasses so their `@RegisterClass` decorators run. `LoadTaskGraphOperations` is called here
+ * anyway as a cheap guard: a host that starts a dispatcher but never loaded a manifest would accept
+ * submissions that route to the CodeGen contract-only base and silently do nothing.
+ *
+ * @module @memberjunction/server
+ */
+import { UserInfo } from '@memberjunction/core';
+import { LoadTaskGraphOperations, TaskGraphDispatcher } from '@memberjunction/task-graph';
+import { TaskGraphPromptRunner } from './TaskGraphPromptRunner.js';
+import sql from 'mssql';
+import { DurableEntityActionRegistry } from '@memberjunction/actions-base';
+import { CreateTaskGraphProviderFactory } from './TaskGraphProviderFactory.js';
+import { TaskGraphActionRunner } from './TaskGraphActionRunner.js';
+import { TaskGraphAgentRunner } from './TaskGraphAgentRunner.js';
+import { DurableEntityActionTaskSubmitter } from './DurableEntityActionTaskSubmitter.js';
+import { TaskGraphContinuationDeliverer } from './TaskGraphContinuationDeliverer.js';
+import { PubSubManager } from '../generic/PubSubManager.js';
+import { TaskGraphFrameBroadcaster } from '../resolvers/TaskGraphFrameResolver.js';
+
+/**
+ * Starts one dispatcher for this process and returns it.
+ *
+ * The instance ID must be stable for the process lifetime and distinct per instance — it is what
+ * lets reconciliation tell "my own orphaned work, reclaim it" from "another live instance's work,
+ * leave it alone". `pid` plus hostname satisfies both: stable while the process lives, and never
+ * reused by a peer.
+ *
+ * The dispatcher self-registers with `ShutdownRegistry`, so the caller does not wire teardown.
+ */
+export async function StartTaskGraphDispatcher(
+    pool: sql.ConnectionPool,
+    contextUser: UserInfo,
+    instanceID?: string,
+): Promise<TaskGraphDispatcher> {
+    LoadTaskGraphOperations();
+
+    const providerFactory = CreateTaskGraphProviderFactory(pool);
+    const pubSub = PubSubManager.Instance.PubSubEngine;
+    const dispatcher = new TaskGraphDispatcher(
+        providerFactory,
+        new TaskGraphAgentRunner(),
+        contextUser,
+        { InstanceID: instanceID ?? `${process.env.HOSTNAME ?? 'mjapi'}-${process.pid}` },
+        // Without this the dispatcher had nowhere to deliver: a finished graph logged its outcome,
+        // marked itself delivered, and said nothing to the conversation that asked for it.
+        new TaskGraphContinuationDeliverer(providerFactory, contextUser),
+        // Live signal. Supplied only when a PubSub engine exists — in a worker or a test there is
+        // nobody to publish to, and the dispatcher runs identically without one.
+        pubSub ? new TaskGraphFrameBroadcaster(pubSub) : undefined,
+        // Action nodes — the third execution shape, beside agents and people. Durable After* entity
+        // actions land as these.
+        new TaskGraphActionRunner(),
+        // Prompt nodes. Without this a Flow agent with a Prompt step submits and then
+        // stalls on a task nothing can execute — which is why the shipped User Onboarding
+        // Flow Agent could not run at all before this seam existed.
+        new TaskGraphPromptRunner(),
+    );
+    await dispatcher.Start();
+
+    // Registered only AFTER the dispatcher is running, and only here. A submitter without a
+    // dispatcher writes Task rows nobody picks up — strictly worse than staying inline, because the
+    // work is now both undone and invisible in the place it used to be logged.
+    DurableEntityActionRegistry.Instance.Register(new DurableEntityActionTaskSubmitter(providerFactory));
+
+    return dispatcher;
+}

package/src/services/TaskGraphActionRunner.ts

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview MJServer's implementation of the task-graph `TaskActionRunner` seam.
+ *
+ * The counterpart to {@link TaskGraphAgentRunner}: the dispatcher knows *when* an action-assigned
+ * node should run and nothing about how an action executes, so execution is injected. Keeping it
+ * here rather than in `@memberjunction/task-graph` is not tidiness — the action engine depends on
+ * the entity layer the dispatcher also builds on, and importing it there would make every consumer
+ * of durable execution load the action engine as well.
+ *
+ * @module @memberjunction/server
+ */
+import { ActionEngineServer } from '@memberjunction/actions';
+import { ActionParam } from '@memberjunction/actions-base';
+import { LogError } from '@memberjunction/core';
+import { UUIDsEqual } from '@memberjunction/global';
+import type { TaskActionRunner, TaskActionRunParams, TaskActionRunResult } from '@memberjunction/task-graph';
+
+export class TaskGraphActionRunner implements TaskActionRunner {
+    public async RunActionForTask(params: TaskActionRunParams): Promise<TaskActionRunResult> {
+        try {
+            await ActionEngineServer.Instance.Config(false, params.ContextUser);
+            const action = ActionEngineServer.Instance.Actions.find((a) => UUIDsEqual(a.ID, params.ActionID));
+            if (!action) {
+                return { Success: false, ErrorMessage: `Action ${params.ActionID} is not in the engine's metadata.` };
+            }
+
+            const result = await ActionEngineServer.Instance.RunAction({
+                Action: action,
+                ContextUser: params.ContextUser,
+                Params: this.buildParams(params),
+                // No Filters. A durable node is work that a filter ALREADY let through — the entity
+                // action's gate ran at dispatch time, on the change context that no longer exists by
+                // the time the dispatcher picks the task up. Re-evaluating here would ask a
+                // transition question with nothing to answer it, and fail closed on every retry.
+                Filters: [],
+            });
+
+            return {
+                Success: result.Success,
+                Output: this.buildOutput(result.Params),
+                ErrorMessage: result.Success ? undefined : result.Message,
+                // The engine already wrote the log; this is the only place its id is in hand. Without
+                // carrying it out, a workflow's action step has no path back to its own execution
+                // record — the one thing anyone wants when an action misbehaves.
+                ActionLogID: result.LogEntry?.ID,
+            };
+        } catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            LogError(`[TaskGraphActionRunner] Task ${params.TaskID} failed: ${message}`);
+            return { Success: false, ErrorMessage: message };
+        }
+    }
+
+    /**
+     * Projects the action's parameters onto the flat result a workflow step is expected to produce.
+     *
+     * **Why not return `result.Params` as-is.** That is an `ActionParam[]`, and every consumer of a
+     * step's output addresses fields BY NAME: an output mapping says `{"CurrentPrice": "stockPrice"}`,
+     * and a branch condition then reads `payload.stockPrice`. Handed an array, the mapping finds no
+     * `CurrentPrice`, writes nothing, and the condition evaluates against `undefined` — which is
+     * falsy rather than erroneous, so the workflow takes the other branch and reports success. That
+     * is exactly what the Demo workflow did: step 1 completed with an output payload of `{}` and
+     * every downstream branch was skipped, with nothing anywhere reporting a problem.
+     *
+     * Only `Output` and `Both` params are included. Echoing the inputs back would let a step's own
+     * parameters masquerade as its results, so an output mapping could "succeed" by reading the
+     * value the step was given rather than the one it produced.
+     */
+    private buildOutput(actionParams: ActionParam[]): Record<string, unknown> {
+        const output: Record<string, unknown> = {};
+        for (const p of actionParams ?? []) {
+            if (p.Type === 'Output' || p.Type === 'Both') output[p.Name] = p.Value;
+        }
+        return output;
+    }
+
+    /**
+     * Rebuilds the action's parameters from the task's stored payload.
+     *
+     * **The values here have been through redaction**, because `Task.InputPayload` is persistent,
+     * user-visible storage and nothing writes a raw `ActionParam[]` there. A parameter the binding
+     * marked as not-logged therefore arrives absent rather than secret — the action sees a missing
+     * value, which is the honest consequence of choosing not to persist it, and the reason durable
+     * dispatch is opt-in per binding rather than the default.
+     *
+     * Dependency outputs are merged underneath the task's own input so a node's explicit parameters
+     * always win over an upstream node that happened to emit the same key.
+     */
+    private buildParams(params: TaskActionRunParams): ActionParam[] {
+        const merged: Record<string, unknown> = {};
+        for (const [name, value] of params.DependencyOutputs) {
+            merged[name] = value;
+        }
+        if (params.InputPayload && typeof params.InputPayload === 'object') {
+            Object.assign(merged, params.InputPayload as Record<string, unknown>);
+        }
+        return Object.entries(merged).map(([Name, Value]) => ({ Name, Value, Type: 'Input' }));
+    }
+}

package/src/services/TaskGraphAgentRunner.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview MJServer's implementation of the task-graph `TaskAgentRunner` seam.
+ *
+ * The dispatcher knows *when* a task should run and *what* it depends on, but nothing about how an
+ * agent executes. That is injected, so the package stays testable without standing up the agent
+ * framework and so a host with a different execution strategy (a queue, a remote worker) can
+ * substitute its own.
+ *
+ * This adapter is the thin translation between the two: it turns a task's input payload and its
+ * dependencies' outputs into agent messages, runs the agent, and maps the result back into the
+ * shape the dispatcher persists.
+ *
+ * @module @memberjunction/server
+ */
+import { AgentRunner } from '@memberjunction/ai-agents';
+import { ChatMessageRole } from '@memberjunction/ai';
+import { LogError } from '@memberjunction/core';
+import { MJAIAgentEntityExtended, MJAIAgentRunEntityExtended } from '@memberjunction/ai-core-plus';
+import type { TaskAgentRunner, TaskAgentRunParams, TaskAgentRunResult } from '@memberjunction/task-graph';
+
+export class TaskGraphAgentRunner implements TaskAgentRunner {
+    public async RunAgentForTask(params: TaskAgentRunParams): Promise<TaskAgentRunResult> {
+        try {
+            const agent = await params.Provider.GetEntityObject<MJAIAgentEntityExtended>('MJ: AI Agents', params.ContextUser);
+            if (!(await agent.Load(params.AgentID))) {
+                return { Success: false, ErrorMessage: `Agent ${params.AgentID} could not be loaded.` };
+            }
+
+            const result = await new AgentRunner().RunAgent({
+                agent,
+                conversationMessages: [{ role: ChatMessageRole.user, content: this.buildPrompt(params) }],
+                contextUser: params.ContextUser,
+                // Inherited from the graph, so a graph this run goes on to emit is one hop deeper
+                // rather than starting the chain over. Without it MAX_REINVOKE_DEPTH never fires.
+                continuationDepth: params.ContinuationDepth ?? 0,
+                parentRun: await this.loadSubmittingRun(params),
+            });
+
+            const success = result?.success === true;
+            return {
+                Success: success,
+                Output: this.extractOutput(result),
+                ErrorMessage: success ? undefined : (result?.agentRun?.ErrorMessage ?? 'Agent execution failed'),
+                AgentRunID: result?.agentRun?.ID,
+            };
+        } catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            LogError(`[TaskGraphAgentRunner] Task ${params.TaskID} failed: ${message}`);
+            return { Success: false, ErrorMessage: message };
+        }
+    }
+
+    /**
+     * The run that submitted this graph, as the entity `RunAgent` wants for `parentRun`.
+     *
+     * **Why this link is worth a load.** It sets `ParentRunID` on the spawned run, which turns a
+     * workflow's total cost into one indexed sum over `RootParentRunID` rather than a walk of the
+     * graph, and gives the run a "started by" trail someone can follow back. Without it every
+     * dispatched run looks like it began from nowhere.
+     *
+     * Undefined — never a throw — when there is no submitting run or it cannot be read. A graph
+     * submitted by a schedule, by MCP, or by a person genuinely has no parent run, and failing the
+     * step because its provenance is unavailable would trade real work for a bookkeeping detail.
+     */
+    private async loadSubmittingRun(params: TaskAgentRunParams): Promise<MJAIAgentRunEntityExtended | undefined> {
+        if (!params.SubmittingAgentRunID) return undefined;
+        try {
+            const run = await params.Provider.GetEntityObject<MJAIAgentRunEntityExtended>(
+                'MJ: AI Agent Runs',
+                params.ContextUser,
+            );
+            return (await run.Load(params.SubmittingAgentRunID)) ? run : undefined;
+        } catch (e) {
+            LogError(
+                `[TaskGraphAgentRunner] Task ${params.TaskID}: submitting run ` +
+                `${params.SubmittingAgentRunID} could not be loaded; the spawned run will have no ` +
+                `parent link. ${e instanceof Error ? e.message : String(e)}`,
+            );
+            return undefined;
+        }
+    }
+
+    /**
+     * Builds the agent's instruction from the task's own input plus its dependencies' outputs.
+     *
+     * Dependency outputs are included inline because a task's whole reason for depending on another
+     * is to consume what it produced. They are rendered as labelled JSON rather than prose so the
+     * agent can parse them reliably rather than inferring structure from formatting.
+     */
+    private buildPrompt(params: TaskAgentRunParams): string {
+        const sections: string[] = [];
+
+        if (params.InputPayload != null) {
+            sections.push(`## Task input\n\`\`\`json\n${JSON.stringify(params.InputPayload, null, 2)}\n\`\`\``);
+        }
+
+        if (params.DependencyOutputs.size > 0) {
+            const rendered = [...params.DependencyOutputs.entries()]
+                .map(([taskID, output]) => `### Output of task ${taskID}\n\`\`\`json\n${JSON.stringify(output, null, 2)}\n\`\`\``)
+                .join('\n\n');
+            sections.push(`## Results from prerequisite tasks\n\n${rendered}`);
+        }
+
+        return sections.length > 0
+            ? sections.join('\n\n')
+            : 'Execute this task.';
+    }
+
+    /** Prefers a structured payload over prose, so downstream tasks get data rather than text. */
+    private extractOutput(result: unknown): unknown {
+        const r = result as { payload?: unknown; agentRun?: { Message?: string } } | null;
+        if (r?.payload != null) return r.payload;
+        return r?.agentRun?.Message ?? null;
+    }
+}