Class PlanningDesignerAgent

Applies auto-alignment rules to includeResponseTypeDefinition based on other flags.

When a documentation flag (e.g., includeForEachDocs) is explicitly set to false, the corresponding response type section (e.g., forEach) should also be excluded unless explicitly set otherwise.

Auto-alignment mappings:

• includePayloadInPrompt → includeResponseTypeDefinition.payload
• includeResponseFormDocs → includeResponseTypeDefinition.responseForms
• includeCommandDocs → includeResponseTypeDefinition.commands
• includeForEachDocs → includeResponseTypeDefinition.forEach
• includeWhileDocs → includeResponseTypeDefinition.while

Applies runtime SubAgentChanges to a base sub-agent set — the sub-agent counterpart of applyActionChanges. Returns a NEW array (never mutates the cached base set).

Attempts to recover from a context length exceeded error using multiple strategies. Uses escalating strategies: remove old results → compact old results → compact all → trim user message. This approach preserves the user's original request while removing stale tool results.

Builds the agent-invariant AgentBaseCatalog — the resolved sub-agents + actions and their formatted markdown, plus the base agent-type prompt params. Computed once per agent and cached on AIEngine (see gatherPromptTemplateData); does NOT apply any runtime overrides.

Builds merged agent type prompt params from schema defaults, agent config, and runtime overrides.

Merge precedence (lowest to highest):

1. Schema defaults (from AgentType.PromptParamsSchema)
2. Agent config (from AIAgent.AgentTypePromptParams)
3. Runtime overrides (from ExecuteAgentParams.data.__agentTypePromptParams)

Builds the summarizeRange recursive-sub-call host: resolves the seeded 'Summarize Conversation Range' prompt (priority-ordered cheap models — the RLM "strong root model, cheap sub-call model" split) and runs it via the standard prompt runner so the AIPromptRun records itself.

Builds hierarchical step string from parent and current step counts.

Examples:

• Root agent step 2: buildHierarchicalStep(2, []) => "2"
• Sub-agent step 1 under root step 2: buildHierarchicalStep(1, [2]) => "2.1"
• Nested sub-agent step 3: buildHierarchicalStep(3, [2, 1]) => "2.1.3"
• Deep nesting: buildHierarchicalStep(5, [1, 2, 3, 4]) => "1.2.3.4.5"

Exposed as protected so driver sub-classes can emit step labels that match the framework's 2.1.3 nesting convention.

Builds a per-run PipelineToolRegistry that unifies the three pipeline-able substrates behind one namespace: built-in transforms, the agent's effective Actions, and the run's artifact tools. Transforms register first so their reserved names win; a source whose name collides with a transform is skipped for pipeline use (still callable normally) and logged, rather than aborting the whole pipeline.

Builds the editable plan-approval AgentResponseForm: the Markdown-rendered plan (with an Edit toggle so the human can amend it before approving), an optional feedback field that travels back to the agent with the decision (most useful on Reject — it steers the re-plan), and an Approve/Reject button group. Override to change the card's layout (e.g. split the plan into per-step checkboxes instead of one field).

Approval is a HIGHER-ORDER signal, not just a form reply: conversation hosts detect decision === 'approve' on this form and switch the conversation out of Plan Mode (see ng-conversations' plan-decision handling), so the follow-up run executes the approved plan instead of planning again. Rejection keeps Plan Mode on — the agent re-plans with the feedback in context.

Builds the message appended to conversationMessages when skill(s) activate — this is what actually puts each skill's Instructions into effect for the rest of the run. Override to change formatting (e.g. a more compact representation for a high skill-activation-count agent).

Builds the AgentSkillInvocation observability record for a skill activation — capturing WHO pulled the trigger and the provenance-of-authority gate values in effect at activation time, so auditors can see exactly which configuration admitted the skill even if that configuration later changes.

Bound a standalone tool result to maxStandaloneToolResultChars: return a head slice plus a redirect that teaches the agent to page (get_rows) or reduce (pipeline) instead of reading a whole large artifact. Mirrors how read/search tools cap output at the tool boundary.

Checks execution guardrails and modifies next step if limits are exceeded. This method is called after validation but before execution of non-terminal steps.

Pre-turn fallback: compacts synchronously when the assembled window is already over the trigger budget BEFORE the first prompt of this run, then splices the fresh summary into the live message array. Only runs with an EXPLICIT configured budget (agent or type ContextWindowMaxTokens) — before the first prompt the model is unknown, and compacting against the conservative default would over-trigger on large-context models. The post-turn hook (real model known) covers those.

Best-effort deep clone for sub-agent payloads. We need this so two parallel sub-agents can each receive their own working copy — without it, mutations by one in-flight sub-agent would race the others' reads.

Uses structuredClone (Node 17+) where available; falls back to a JSON round-trip for environments without it. Returns the original value on non-cloneable inputs.

JSON fallback caveats — the round-trip is not shape-preserving:

• Date → ISO string
• Map, Set, RegExp, typed arrays → {}
• undefined values and function-valued properties → dropped
• BigInt → throws (caught by the outer try/catch, returns original)
• circular refs → throws (returns original) If payloads ever carry those shapes, behavior diverges between the structuredClone path (Node 17+) and the JSON path. Keep sub-agent payloads to plain JSON-safe shapes to avoid this skew.

Exposed as protected so driver sub-classes performing their own parallel dispatch get the same payload-isolation guarantee.

Compacts a message using configured compaction mode.

Converts ChatMessageContent to a string representation. Handles both simple strings and content block arrays.

Creates an AIAgentRunStep for message compaction operations. Records the compaction attempt with context about the message being compacted.

Creates a step entity for tracking.

Exposed as protected so driver sub-classes (e.g. Skip) can author custom AIAgentRunStep records with the same setup correctness — StepNumber, hierarchy breadcrumb, UUID validation, payload serialization, and the queueStepSave coupling that keeps INSERT-then-UPDATE ordering safe.

Creates a chat message containing sub-agent execution results.

Determines if an action change scope applies to the current agent.

Emits message lifecycle event if callback is registered.

Enables a skill's bundled Actions and sub-agents by pushing specific-scoped add entries (targeted at exactly the activating agent's ID) onto params.actionChanges / params.subAgentChanges. specific/[agent.ID] is the correct scope for "apply to THIS agent, at whatever depth it runs, and never leak to its sub-agents":

• doesChangeScopeApply returns true only when the running agent's ID is in the list, so it applies to the activating agent regardless of depth (a sub-agent that activates a skill still gets its tools — which a root-scoped change would NOT do, since root means "the depth-0 agent," not "the current agent").
• filterActionChangesForSubAgent / filterSubAgentChangesForSubAgent propagate specific as-is, and each downstream agent checks includes(itsOwnID) → false, so the grant never cascades to sub-agents the activating agent later delegates to. Because params is the same object reference used for the rest of this run, every subsequent turn's gatherPromptTemplateData() call picks up the change automatically — no extra plumbing.

Override to change propagation scope (e.g. a subclass that wants skill-granted capabilities to cascade to sub-agents could push scope: 'all-subagents' instead).

Estimates total token count across all conversation messages.

Executes the agent's internal logic.

This method contains the core execution logic that drives agent behavior. By default, it implements a sequential execution loop, but subclasses can override this to implement different execution patterns such as:

• Parallel execution of multiple steps
• Event-driven or reactive execution
• State machine implementations
• Custom termination conditions
• Alternative flow control mechanisms

Executes a batch of artifact tool calls, recording each as its own Tool AIAgentRunStep (a sibling of the Prompt step that requested them) with full inputs/outputs captured in InputData/OutputData. Returns the stored results so the caller can render them into a single recall-friendly message for the next prompt turn.

Step naming convention: Artifact Tool: {toolName} for log/UI clarity.

Executes conversation-history retrieval tool calls, wrapping each invocation in its own AIAgentRunStep (StepType='Tool', "Conversation Tool: {tool}") — the same per-call observability shape as artifact tools. Reads are served from the ConversationEngine cache; per-call failures are contained in the result.

At most MAX_CONVERSATION_TOOL_CALLS_PER_TURN calls execute per response; the excess come back as skipped failure-shaped results (no run steps recorded) telling the model to re-request them next turn.

Expands a previously compacted message to its original content.

Executes a batch of in-flight memory writes, recording each as its own Tool AIAgentRunStep (a sibling of the Prompt step that requested them) with full inputs/outcomes captured in InputData/OutputData.

Writes run SEQUENTIALLY (not Promise.all like artifact tools) by design: each persisted note is embedded and synced into the in-memory vector service on Save, so write N must be visible to write N+1's near-duplicate check (this is also what makes same-run supersede-own work). The per-run cap bounds the cost of the serialization.

Step naming convention: Memory Write for log/UI clarity.

Executes the next step based on the current state.

This method can be overridden by subclasses to customize step execution behavior. It handles the execution of different step types (prompt, actions, sub-agent, chat) based on the previous decision.

Runs a tool pipeline as a single Tool step in the run tree (sibling of the prompt step that requested it, matching artifact-tool steps). ALL pipeline observability lives in this step's OutputData — the per-stage breakdown, totals, bytes saved, and the tool chain — so there are no dedicated pipeline entities and no extra SQL I/O; the run tree alone carries everything a debug UI needs.

Executes a 'Plan' next step (Plan Mode): records a Plan run-step, raises the standard MJ: AI Agent Requests HITL request with an editable plan-approval AgentResponseForm, and terminates this run awaiting the human's response — reusing the exact same pause/resume infrastructure executeChatStep uses (createFeedbackRequest + the existing MJAIAgentRequestEntityServer.Save() auto-resume-on-status-change hook). A rejected or edited-and-resubmitted plan resumes as a new linked run via the normal run-chain mechanism; resolvePlanModeGate re-checks approval on that new run so a rejection sends the agent back to present a revised plan rather than through to execution.

Important: the RETURNED BaseAgentNextStep.step is 'Chat', not 'Plan' — 'Plan' is only ever an intermediate classification (used for the AIAgentRunStep.StepType audit record, which the UI reads to render a plan-approval card instead of a generic chat bubble). The step returned to the framework must stay within AIAgentRun.FinalStep's DB-CHECK- constrained, terminal-only vocabulary — 'Plan' is deliberately not part of it (see the BaseAgentNextStep.step doc comment) — so a plan-approval pause is represented as the same terminal shape executeChatStep already uses.

Executes the configured prompt. Always uses the attemptJSONRepair option to try to fix LLM JSON syntax issues if they arise.

Executes a 'Skill' next step: activates one or more skills the LLM requested by name. Activating a skill (1) appends its full Instructions to the conversation so they take effect for the remainder of the run, and (2) enables its bundled Actions/sub-agents by pushing root-scoped add entries onto params.actionChanges/params.subAgentChanges — the same runtime tool-surface-extension mechanism ExecuteAgentParams already exposes to external callers. This is NOT a nested agent run; it never terminates the loop itself.

Already-activated skills (tracked in _activatedSkillIDs) are skipped — re-requesting an active skill is a harmless no-op rather than re-appending duplicate instructions.

Decomposed into resolveSkillActivations, buildSkillActivationMessage, enableSkillCapabilities, and recordSkillActivationStep — override any of those for fine-grained control (e.g. custom instruction formatting, additional side effects on activation) without re-implementing the whole step.

Extracts default values from a JSON Schema definition.

Filters and transforms action changes for propagation to a sub-agent.

This method applies the following propagation rules:

• 'global': Propagated as-is to all sub-agents
• 'root': Not propagated (only applies to root agent)
• 'all-subagents': Propagated as 'global' (since sub-agent is now in scope)
• 'specific': Propagated as-is (sub-agent checks if it's in agentIds)

Filters/transforms sub-agent changes for propagation to a sub-agent — the sub-agent counterpart of filterActionChangesForSubAgent (same propagation rules).

Finalizes a step entity with completion status. Pairs with createStepEntity — drivers that create custom steps should also finalize them through this method so Status/CompletedAt/Success/ErrorMessage/OutputData are populated consistently and the UPDATE is sequenced behind the INSERT via queueStepSave.

Formats a message with agent hierarchy for streaming/progress updates.

Exposed as protected so driver sub-classes emit progress events whose breadcrumbs line up with the framework's own — keeps the Explorer tree view consistent across custom and built-in dispatch.

Gets the effective actions for validation, using runtime changes if available. Falls back to database-configured actions if _effectiveActions is empty.

Gets the effective sub-agents for validation, using runtime subAgentChanges if available. Falls back to the database-configured relationship set if _effectiveSubAgents is empty. Mirrors getEffectiveActionsForValidation.

Gets the execution count for an item (action or sub-agent).

Gets the context limit for the current model. Uses model selection info from the prompt result to determine the actual model's MaxInputTokens.

Resolves which activated skill(s), if any, granted the given action to this agent — the attribution recorded on the Actions step's Skills column. Returns undefined (no linkage) when the action is one of the agent's NATIVE grants (an Active MJ: AI Agent Actions row), even if an activated skill also bundles it: native authority takes precedence, and Skills = NULL is the contract for "the agent had this tool anyway".

Resolves which activated skill(s), if any, granted the given sub-agent to this agent — the attribution recorded on the Sub-Agent step's Skills column. Returns undefined when the sub-agent is a NATIVE relationship (a ParentID child of this agent, or an Active MJ: AI Agent Relationships referenced-sub-agent row), even if an activated skill also bundles it — same native-precedence contract as getSkillAttributionForAction.

Returns the system default prompt ID for message compaction. Looks up the "Compact Agent Message" prompt by name.

Handles validation of the starting payload if configured.

This method validates the input payload against the agent's StartingPayloadValidation schema before execution begins. It respects the agent's PayloadScope if configured.

Checks if any agent run guardrails have been exceeded. Override this method to implement custom guardrail logic.

Increments the execution count for an item (action or sub-agent).

Exposed as protected so driver sub-classes performing custom dispatch bump the same per-item counter the framework checks against execution guardrails — without this, custom dispatch silently bypasses limits.

Initializes the AI and Action engines. Subclasses can override this to add any additional engine/metadata loading initialization they want to do and this method will be called at the right time in the agent execution process.

Pushes a single user-role message containing rendered artifact-tool results into the conversation. This mirrors the action-result "inject once, then expire" pattern — the LLM sees the results on its next turn, and older messages are pruned/compacted by pruneAndCompactExpiredMessages instead of being re-rendered into every system-prompt turn.

Pushes a single user-role message containing rendered conversation-tool results into the conversation — the same inject-once-then-expire lifecycle as artifact tool results.

Pushes a single user-role message containing memory-write outcomes into the conversation, mirroring injectArtifactToolResultsMessage's inject-once-then-expire pattern. Closing the loop here is what stops the LLM from re-emitting the same memory on subsequent turns.

Pushes the pipeline's final output (or its failure message) into the conversation for the LLM's next turn, mirroring the artifact-tool "inject once, then expire" pattern. Only the final output is surfaced — intermediate step outputs never enter the context window.

Carries the PREVIOUS turn's tool results forward into this run's context.

Inline tool results (artifact + conversation tools) are injected into the run's in-memory messages only — the next turn rebuilds messages from the conversation window, so a result paged in on turn N is gone on turn N+1 and the agent must re-call the tool. The results already persist in each Tool step's OutputData; this re-injects the immediately previous completed run's successful results as one transient message. One-turn memory by construction: each run carries only its direct predecessor's results, so context never compounds.

Gated on conversationId + root depth — programmatic runs and sub-agents skip it.

Determines if an error is a configuration error that cannot be resolved by retrying. Configuration errors indicate issues with agent setup that need manual intervention.

This method provides detailed diagnostic information to help identify what configuration is missing or incorrect.

Determines if a prompt execution error is fatal and should stop agent execution. Fatal errors are those that won't be resolved by retrying, such as context length exceeded (when no larger model is available), authentication failures, or invalid request format.

Returns true if the message is a turn-generated result (action, tool, client tool, sub-agent, or loop). These are the volatile, expirable messages that accumulate over turns. Everything else — system/RAG context, injected memory, the original user request — anchors the cache-stable prompt prefix and is protected from routine pruning.

Loads all required configuration for agent execution.