Package net.thevpc.naru.api.agent

Interface NaruSessionBuilder

public interface NaruSessionBuilder
Configures and creates one NaruSession.

A builder rather than a set of startXxx methods, because the things a session needs — where it lives, how it reaches its user, what it runs first — are independent choices, and every combination used to need its own method on the agent. 


 // a console session, blocking until the user leaves
 NaruSession s = agent.newSession()
         .interactive()
         .blocking()
         .build();

 // a headless session for a web request
 NaruSession s = agent.newSession()
         .interaction(new NaruStreamInteraction(output -> sse.send(output)))
         .task(NaruTaskSpec.of().statements(script))
         .build();

What this does not do

It does not start the session. build() returns a session that is configured but not running, so the caller decides when work begins and whether to wait for it. That separation is what lets a server hold a session open across requests.

Thread safety

A builder is not thread-safe and is meant to be used once, to make one session. Build one per session; the agent hands out a fresh builder each time.

  • Method Details

    • directory

      NaruSessionBuilder directory(NPath directory)
      Where the session keeps its state. Defaults to the agent's project directory, or the user's home directory when the agent has none.

    • interaction

      NaruSessionBuilder interaction(NaruInteraction interaction)
      How the session reaches its user: a terminal, a stream, or anything else.

      Defaults to a NaruInteraction on the process terminal, which is what every caller relied on before this seam existed. A host that will supply input itself should pass a headless interaction instead, so no thread is started and no process stdin is claimed.

    • task

      NaruSessionBuilder task(NaruTaskSpec task)
      The task the session runs when it starts. Optional; a session may be started with no work and driven later through NaruSession.newTask(net.thevpc.naru.api.task.NaruTaskSpec).

    • statements

      NaruSessionBuilder statements(String... statements)
      Shorthand for running statements as the session's first task, with input arriving line by line. Ignored if task(net.thevpc.naru.api.task.NaruTaskSpec) was already set.

    • script

      NaruSessionBuilder script(InputStream in)
      Reads the session's script from a stream, one statement per line.

      Blank lines are kept rather than skipped: the parser turns them into no-ops, except inside a /buffer on ... /buffer off block where they are meaningful parts of a multi-line prompt.

    • interactive

      NaruSessionBuilder interactive()
      The first task reads user input line by line, which is what makes a session feel interactive rather than batch.

    • banner

      NaruSessionBuilder banner(boolean banner)
      Prints the startup banner on the agent's own channel. Off by default, since a library or server host has no banner to print.

    • bannerMessage

      NaruSessionBuilder bannerMessage(NMsg bannerMessage)

    • bannerMessage

      NMsg bannerMessage()

    • richTerm

      NaruSessionBuilder richTerm(boolean richTerm)
      Enables the rich terminal: ANSI styling and command highlighting. Only meaningful for a terminal interaction, and applied to that session's terminal rather than to process-global state, so concurrent sessions do not fight over it.

    • build

      NaruSession build()
      Creates the session without starting it.
      Throws:
      IllegalStateException - if the agent has no project directory and none was set