---

Class ::nsmcp::QuestionService

::nsmcp::QuestionService create ... \
           [ -backend:required backend:required ] \
           [ -backendErrors (default "") ] \
           [ -backends (default "") ] \
           [ -evidenceDirectory (default "") ] \
           [ -lifetime (default "3600") ] \
           [ -maxBytes:integer (default "2097152") ] \
           [ -maxConversations:integer (default "20") ] \
           [ -maxEvidenceBytes:integer (default "16777216") ] \
           [ -maxTurns:integer (default "20") ] \
           [ -mutex mutex ] \
           [ -questionLog:boolean (default "true") ] \
           [ -queue:required queue:required ] \
           [ -store:required store:required ]

Defined in /usr/local/ns/tcl/nsmcp/question-service.tcl

Class Relations

• class: ::nx::Class
• superclass: ::nsmcp::Object

Methods (to be applied on the object)

• setup (scripted, public)

   nsmcp::QuestionService setup moduleDirectory

  Configure question backends and the question service at startup. Honor enableQuestions, validate the tool registry and credentials, and establish the configured provider implementations.

  Parameters:

  moduleDirectory (required)

  Installed module directory used to resolve backend helpers.

  Returns:

  The startup setup result, or an empty result when questions are disabled.

  Testcases:

  No testcase defined.

Methods (to be applied on instances)

• cancel (scripted, public)

   <instance of nsmcp::QuestionService> cancel context handle

  Cancel the active turn of an owned conversation. Update queued or running state under the mutex so subsequent callbacks observe cancellation.

  Parameters:

  context (required)

  Authenticated request context carrying the principal, grants and selected server.

  handle (required)

  Retained job or conversation handle; ownership and expiry checks still apply.

  Returns:

  The cancellation/conversation result.

  Testcases:

  No testcase defined.

• choices (scripted, public)

   <instance of nsmcp::QuestionService> choices

  List configured question backend choices. Describe available providers and configured failures without contacting a provider.

  Returns:

  A dictionary containing the default backend and backend metadata.

  Testcases:

  No testcase defined.

• continue (scripted, public)

   <instance of nsmcp::QuestionService> continue context handle \
      turn [ peerAddress ]

  Resume an owned conversation from its retained continuation state. Derive the job and window from server-owned state and recheck ownership and turn validity before queuing work.

  Parameters:

  context (required)

  Authenticated request context carrying the principal, grants and selected server.

  handle (required)

  Retained job or conversation handle; ownership and expiry checks still apply.

  turn (required)

  Retained turn identifier, used to reject superseded callbacks.

  peerAddress (optional)

  Direct connection peer supplied by the authenticated HTTP adapter.

  Returns:

  The rooted JSON conversation status returned by send.

  Testcases:

  No testcase defined.

• describe (scripted, public)

   <instance of nsmcp::QuestionService> describe

  Describe the default backend and service evidence budgets. Merge provider metadata with this service's configured memory and evidence limits.

  Returns:

  The service metadata dictionary.

  Testcases:

  No testcase defined.

• event (scripted, public)

   <instance of nsmcp::QuestionService> event handle turn event

  Record a backend event for a specific retained turn. Serialize updates and discard events for expired or superseded turns.

  Parameters:

  handle (required)

  Retained job or conversation handle; ownership and expiry checks still apply.

  turn (required)

  Retained turn identifier, used to reject superseded callbacks.

  event (required)

  Backend event dictionary for the retained question turn.

  Returns:

  Whether the event was accepted for the active turn.

  Testcases:

  No testcase defined.

• evidence (scripted, public)

   <instance of nsmcp::QuestionService> evidence context handle id

  Retrieve retained tool evidence for an owned conversation. Validate the evidence identifier, confirm it belongs to a retained turn and read only the bounded private evidence file.

  Parameters:

  context (required)

  Authenticated request context carrying the principal, grants and selected server.

  handle (required)

  Retained job or conversation handle; ownership and expiry checks still apply.

  id (required)

  Private evidence identifier already referenced by an owned turn.

  Returns:

  A rooted JSON object containing the retained result text.

  Testcases:

  No testcase defined.

• forget (scripted, public)

   <instance of nsmcp::QuestionService> forget context handle

  Remove an owned conversation and its retained evidence. Reject active work when required and clean up private evidence with the retained conversation state.

  Parameters:

  context (required)

  Authenticated request context carrying the principal, grants and selected server.

  handle (required)

  Retained job or conversation handle; ownership and expiry checks still apply.

  Returns:

  The deletion result.

  Testcases:

  No testcase defined.

• poll (scripted, public)

   <instance of nsmcp::QuestionService> poll context handle

  Describe an owned conversation and its retained turns. Apply ownership and expiry checks before exposing bounded question, tool, evidence and usage metadata.

  Parameters:

  context (required)

  Authenticated request context carrying the principal, grants and selected server.

  handle (required)

  Retained job or conversation handle; ownership and expiry checks still apply.

  Returns:

  A rooted JSON conversation-status object.

  Testcases:

  No testcase defined.

• run (scripted, public)

   <instance of nsmcp::QuestionService> run handle turn

  Execute a queued conversation turn. Resolve retained owner/provider state, invoke the selected backend and publish completion, failure or cancellation under the mutex.

  Parameters:

  handle (required)

  Retained job or conversation handle; ownership and expiry checks still apply.

  turn (required)

  Retained turn identifier, used to reject superseded callbacks.

  Returns:

  The worker callback result; conversation state retains the outcome.

  Testcases:

  No testcase defined.

• send (scripted, public)

   <instance of nsmcp::QuestionService> send context question \
      [ handle ] [ backendName ] [ browserTimezone ] [ peerAddress ] \
      [ expectedTurn ] [ backendQuestion ] [ continuedFrom ]

  Queue a question or follow-up with optional browser timezone context. Retain authenticated ownership, backend selection and turn guards when queuing asynchronous provider work. Keep the displayed question separate from server-generated continuation instructions.

  Parameters:

  context (required)

  Authenticated request context carrying the principal, grants and selected server.

  question (required)

  Question text supplied to the selected provider.

  handle (optional)

  Existing conversation handle, or empty to create a new conversation.

  backendName (optional)

  Backend selection for a new conversation; empty retains the configured default.

  browserTimezone (optional)

  Validated browser timezone used unless the question overrides it; empty retains prior context or UTC.

  peerAddress (optional)

  Direct connection peer supplied by the authenticated HTTP adapter.

  expectedTurn (optional)

  Optional internal guard against continuing a superseded turn.

  backendQuestion (optional)

  Optional server-generated backend task, separate from the displayed question.

  continuedFrom (optional)

  Owned source-turn identifier when editing the original request.

  Returns:

  Rooted JSON triples describing the queued conversation.

  Testcases:

  No testcase defined.

• usageSummary (scripted, public)

   <instance of nsmcp::QuestionService> usageSummary

  Summarize retained finished-question token records for this server. Keep unknown usage explicit and exclude cumulative provider snapshots from summed turn usage. Apply the retained UTC-day and read bounds.

  Returns:

  A dictionary of UTC-day, backend/model and principal rollups, complete/partial counters, missing counts and read limits.

  Testcases:

  No testcase defined.

---