Package net.thevpc.naru.api.agent

Interface NaruInteraction

public interface NaruInteraction
How a session reaches its user.

This is the seam that keeps the engine free of any assumption about a human being at a terminal. The core never reads a stream, never prints, and never blocks waiting for someone to type: it calls requestInput(net.thevpc.naru.api.agent.NaruInputRequest) and carries on, and it reports progress through write(net.thevpc.naru.api.agent.NaruLogMode, net.thevpc.nuts.text.NMsg). What a terminal, a browser, or a test harness does with those two calls is somebody else's problem.

Threading

write(net.thevpc.naru.api.agent.NaruLogMode, net.thevpc.nuts.text.NMsg) may be called from any worker thread, including several at once, and must not block. requestInput(net.thevpc.naru.api.agent.NaruInputRequest) may also arrive on a worker thread and must not block either — the answer comes later, through NaruInputRequest.deliver(String), not through a return value.

Lifecycle

open(NaruSession) is called once when the session starts and close() when it stops. An implementation that owns a thread starts and stops it there, which is why a headless session has no input thread at all.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    NAME_STREAM
    Headless: no thread, output forwarded to a listener.
    static final String
    NAME_TERMINAL
    Interactive console session: blocks a thread on a real terminal.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Called once when the session stops.
    default String
    name()
    The name this interaction is registered under, for diagnostics and for hosts that look one up by name.
    void
    open(NaruSession session)
    Called once when the session starts, before any task runs.
    void
    requestInput(NaruInputRequest request)
    Asks the user a question on behalf of a blocked task.
    void
    write(NaruLogMode mode, NMsg message)
    Reports a piece of session output.
    void
    writeStream(NaruLogMode mode, NMsg fragment, boolean end)
    Reports a fragment of output that is still being produced, and that the user is meant to see as it arrives rather than after the work finishes.

  • Field Details

    • NAME_TERMINAL

      static final String NAME_TERMINAL
      Interactive console session: blocks a thread on a real terminal.
      See Also:

    • NAME_STREAM

      static final String NAME_STREAM
      Headless: no thread, output forwarded to a listener.
      See Also:

  • Method Details

    • name

      default String name()
      The name this interaction is registered under, for diagnostics and for hosts that look one up by name.

    • open

      void open(NaruSession session)
      Called once when the session starts, before any task runs.

    • requestInput

      void requestInput(NaruInputRequest request)
      Asks the user a question on behalf of a blocked task. Must return promptly: the task stays blocked until the returned request is delivered or cancelled.

    • write

      void write(NaruLogMode mode, NMsg message)
      Reports a piece of session output. Called for every NaruLogMode, on whichever thread produced it. A consumer that throws is ignored — output is a side channel and must never fail the work that produced it.

    • writeStream

      void writeStream(NaruLogMode mode, NMsg fragment, boolean end)
      Reports a fragment of output that is still being produced, and that the user is meant to see as it arrives rather than after the work finishes.

      Fragments of the same mode concatenate: the caller sends end=false for each piece and a final end=true for that mode, and what the user reads is the fragments joined in the order they arrived. A write(net.thevpc.naru.api.agent.NaruLogMode, net.thevpc.nuts.text.NMsg) of any mode in between closes the open fragment first, so an unrelated log line can never land in the middle of a half-drawn sentence.

      An implementation may show fragments the moment they arrive, or it may hold them and emit the joined text once at end: both are correct, and a headless host or a test harness has no reason to bother with the first. Neither may drop them -- a model turn that is streamed but never shown is a turn the user paid for and did not get.

    • close

      void close()
      Called once when the session stops. Must not block.