
package com.smartgwt.client.docs;

/**
 * The history mechanism automatically maintains a list of the last N actions taking by an AI as
 * part of
 *  executing a CoTProcess, to help the AI maintain context when it needs to execute a series of
 *   CoTTasks as part of an overall, logical task.
 *  <p>
 * This is needed to support the more predictable {@link
 * com.smartgwt.client.docs.CoTExecutionModels "AI Workflow"} execution model for
 *  enterprise AI workflows.
 *  <p>
 *  <h4>What is recorded</h4>
 * History is tracked automatically for: (a) transitions (the model emitted
 * {goTo,intent,stepAfter}),
 *  and (b) successful non?transition results that were validated and applied to
 * {@link com.smartgwt.client.util.workflow.Process#getState state} (for example via 
 * CoTTask.stateUpdates).
 *  <p>
 *  <h4>History storage</h4>
 *  The primary list is kept on the process as  history. For ease of
 *  serialization and prompt access, a bounded mirror is also maintained at
 *  <code>process.state.history</code>. Both lists are append?only during a run.
 *  <p>
 *  <h4>Including history in prompts</h4>
 *  History is typically referenced from  standard prompt template via
 *  the "${promptPart('history')}", which includes the  CoTProcess.historyPrimer and history data.
 *  <p>
 *  <h4>Manual entries</h4>
 *  Add entries programmatically via  CoTProcess.addHistory(). This appends to the process
 *  history and mirrors to <code>state.history</code> within configured limits.
 *  <pre>
 *  process.addHistory({
 *    taskID: task.ID,
 *    summary: "Added field 'orderDate'",
 *    ts: Date.now()
 *  });
 *  </pre>
 *  <p>
 *  <h4>How much history reaches the prompt</h4>
 *  History is rendered in two zones. The most recent  CoTProcess.historyDetailItems
 *  entries appear in full, with their <code>intent</code> and <code>stepAfter</code>.
 *  Every earlier entry appears as a single <code>action | result</code> line, capped at
 *   CoTProcess.historyResultMaxChars characters. Nothing is omitted: a process uses
 *  this log to know what it has already done, so an entry that disappeared would be work
 *  the process would repeat.
 *  <p>
 *  Set  CoTProcess.historyDetailItems to trade prompt size against detail, and
 *   CoTProcess.noHistory to leave history out of a prompt altogether.
 *  <p>
 *  <h4>Maximum history entries</h4>
 *   CoTProcess.historyMaxItems is a retention ceiling on the in-memory list - a
 *  guard against a runaway process, not a way to bound the prompt. The mirrored
 *  <code>state.history</code> maximum is  CoTProcess.stateHistoryMaxItems, and
 *  defaults to the in-memory ceiling if unset.
 *  <p>
 *  <h4>Truncation in Partial Prompts</h4>
 * When generating {@link com.smartgwt.client.docs.CoTPartialPrompt partial prompts}, history can
 * be truncated
 *  via  PartialPromptConfig.truncateHistory to include only the N most recent entries.
 *  This is useful when debugging recent actions without including the full history.
 */
public interface CoTHistory {
}
