Class Session

java.lang.Object
uno.anahata.asi.agi.tool.ToolContext
uno.anahata.asi.agi.tool.AnahataToolkit
uno.anahata.asi.toolkit.Session
All Implemented Interfaces:
ContextProvider, PropertyChangeSource, Rebindable
public class Session extends AnahataToolkit
The definitive toolkit for managing the current agi session's metadata, tool capabilities, and context pruning policies.

This toolkit provides high-level control over the session environment, allowing the model to optimize its own context window, toggle available toolkits, and manage the lifecycle of stateful resources.

Author:
anahata-ai

  • Field Details

    • sessionStart

      private Date sessionStart
      The time when the session started.

    • sessionRestored

      private Date sessionRestored
      The last time the session got deserialized.

  • Constructor Details

    • Session

      public Session()

  • Method Details

    • postActivate

      public void postActivate()
      Captures the sessionRestored time during deserialization;
      Overrides:
      postActivate in class AnahataToolkit

    • getSystemInstructions

      public List<String> getSystemInstructions() throws Exception
      Description copied from interface: ContextProvider
      Gets a list of system instruction strings provided by this context provider. These are typically prepended to the conversation as high-level guidance.
      Returns:
      A list of system instruction strings.
      Throws:
      Exception - if an error occurs during instruction generation.

    • updateSessionNickname

      public String updateSessionNickname(String nickName)
      Updates the AGIs nickname.
      Parameters:
      nickName - the new nickname
      Returns:
      a confirmation message

    • updateSessionSummary

      public String updateSessionSummary(String summary)
      Updates the human-readable summary of the current session.

      STRICT USAGE RULE: This tool MUST ONLY be called if there are other "task-related" tool calls (e.g., file manipulation, shell commands, pruning) being made in the same turn. It should NEVER be called as the sole tool in a turn.

      The summary is visible to the user in the container dashboard and the parent agi if spawned by another agi.

      Parameters:
      summary - A concise summary of the conversation's current state or topic.
      Returns:
      A confirmation message.

    • setContextProviderProviding

      public void setContextProviderProviding(boolean providing, List<String> providerIds)
      Enables or disables specific context providers within the session hierarchy.

      This tool allows the model to surgically control which providers contribute to the RAG message, helping to reduce noise and optimize token usage.

      Parameters:
      providing - Whether to enable or disable the providers.
      providerIds - The fully qualified IDs of the context providers to update.

    • setToolkitEnabled

      public void setToolkitEnabled(boolean enabled, List<String> toolkitNames)
      Enables or disables multiple toolkits by their names.

      Disabling a toolkit makes its tools invisible to the model and can reduce complexity when certain capabilities are no longer needed.

      Parameters:
      enabled - Whether to enable or disable the toolkits.
      toolkitNames - The names (IDs) of the toolkits to update (e.g., 'Audio', 'Chrome').

    • killRunningTools

      public String killRunningTools(List<Long> toolCallIds)
      Signals one or more currently executing background tools to stop.

      This is useful for cancelling long-running tasks like large file reads, complex shell commands, or audio recording.

      Parameters:
      toolCallIds - The unique IDs of the tool calls to stop.
      Returns:
      A detailed report of the stopping operations.

    • enableHostedTools

      public String enableHostedTools()
      Switches the session to server-side tool mode.

      CRITICAL: After calling this, local Java tools are disabled until manually re-enabled by the user. Use this only when a capability provided by the model host (e.g., Google Search) is explicitly required.

      Returns:
      Confirmation message describing the impact.

    • populateMessage

      public void populateMessage(RagMessage ragMessage) throws Exception
      Populates the RAG message with comprehensive session metadata.

      Provides a Markdown summary of session identity, model configuration, context window usage, and the status of executing tools.

      Parameters:
      ragMessage - The target RAG message.
      Throws:
      Exception - if metadata extraction fails.