Agent

Functions
void	nus_agent_reset (void)
	Clear the in-flight ask id and the accumulator; no init, no locking, no return.
void	nus_agent_note_ask (const char *id)
	Record the in-flight ask id; a NULL or empty id resets the agent. No caller anywhere.
int	nus_agent_handle_token (const char *json, const jsmntok_t *toks, int n_toks)
	Append a "delta" to the accumulator; -1 on id mismatch (silently dropped).
int	nus_agent_handle_done (const char *json, const jsmntok_t *toks, int n_toks)
	Forward the final text to the CM55 page over IPC and reset; "text" is authoritative.
int	nus_agent_handle_tool_call (const char *json, const jsmntok_t *toks, int n_toks)
	Observability only — a short hint-text IPC so the CM55 marquee shows which tool runs.
size_t	nus_agent_buffer_len (void)
	Bytes buffered for the in-flight ask; a telemetry probe, not a synchronisation primitive.

Detailed Description

Six functions: the nus_agent_* stream handlers. Compiled only with ENABLE_PAGE_BENTO_BUDDY=1 (default 0, proj_cm33_ns/Makefile:64, :305); rebuild after make getlibs — Flag gate (read first).

Declarations: nus_agent.h (includes vendor/jsmn.h, absent from the dist include set — Header packaging note). Implementation nus_agent.c is archived in libbento_secure.a. Module state is a single in-flight ask owned by one NUS RX task (nus_agent.c:44): token frames whose id does not match the latest ask are silently dropped; the accumulator is bounded at 256 chars and overflow truncates.

Variant

mtb-mpy and mtb-only

Function Documentation

nus_agent_reset()

void nus_agent_reset

(

void

)

Clear the in-flight ask id and the accumulator; no init, no locking, no return.

Contract

No init, no locking, no return — clears the id and the accumulator (nus_agent.c:115-120). Called on .done (:203), on an empty final (:192) and on a NULL/empty ask id (:125). Safe from any task in the single-reader/single-writer sense the header states. Template call sites: 0 (archived: 3).

Variant

mtb-mpy and mtb-only

Origin

Lifted from BENTO-TESAIoT-libraries/claw/common/ble_nus/nus_agent.c:115-133 (compiled into the prebuilt archive; not shipped as source).

nus_agent_note_ask()

void nus_agent_note_ask

(

const char *

id

)

Record the in-flight ask id; a NULL or empty id resets the agent. No caller anywhere.

Contract

Records the in-flight ask id so later token/done frames can be matched; ids longer than the internal buffer are truncated. A NULL or empty id resets the agent (nus_agent.c:122-133 — cited as the definition, not a call). No caller anywhere; the definition rendered under nus_agent_reset() shows the id-copy semantics.

Variant

mtb-mpy and mtb-only

Example (authored — no shipped call site)

__attribute__((used))
static void bento_ex_nus_agent_note_ask(void)
{
    /* Arm for the ask we are about to emit: */
    nus_agent_note_ask("ask-42");
    /* ...emit the bento.agent.ask event with the same id; token/done
     * frames carrying any other id are now silently dropped. */
 
    /* Leaving the ASK submode? NULL (or "") resets the accumulator: */
    nus_agent_note_ask(NULL);
}

nus_agent_handle_token()

int nus_agent_handle_token	(	const char *	json,
		const jsmntok_t *	toks,
		int	n_toks )

Append a "delta" to the accumulator; -1 on id mismatch (silently dropped).

Contract

Appends the "delta" string to the accumulator; 0 if accepted, -1 if the id does not match the current ask (silently dropped) or "delta" is missing. Dispatcher-only entry point; the shipped caller (void)-casts it. Template call sites: 0; archived call site nus_commands.c:1760 ((void)nus_agent_handle_token(json, toks, n_toks); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_agent_handle_done()

int nus_agent_handle_done	(	const char *	json,
		const jsmntok_t *	toks,
		int	n_toks )

Forward the final text to the CM55 page over IPC and reset; "text" is authoritative.

Contract

Forwards the final text to the CM55 page via ipc_bento_buddy_send(IPC_CMD_BUDDY_AGENT_RESPONSE, ...) and resets the accumulator; returns 0. The "text" field is authoritative; if missing, the accumulated deltas are forwarded. An empty final still resets state. Its tail is the exemplar rendered under ipc_bento_buddy_send. Template call sites: 0; archived call site nus_commands.c:1764 ((void)nus_agent_handle_done(json, toks, n_toks); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_agent_handle_tool_call()

int nus_agent_handle_tool_call	(	const char *	json,
		const jsmntok_t *	toks,
		int	n_toks )

Observability only — a short hint-text IPC so the CM55 marquee shows which tool runs.

Contract

Observability only — tool execution happens desktop-side; the device emits a short hint-text IPC so the CM55 marquee shows which tool runs. Returns 0. Template call sites: 0; archived call site nus_commands.c:1768 ((void)nus_agent_handle_tool_call(json, toks, n_toks); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_agent_buffer_len()

size_t nus_agent_buffer_len

(

void

)

Bytes buffered for the in-flight ask; a telemetry probe, not a synchronisation primitive.

Contract

Bytes currently buffered for the in-flight ask; 0 when idle. Telemetry/host-test probe, not a synchronisation primitive (bounded at 256; a value stuck at the bound is complete-or-truncated). No caller anywhere.

Variant

mtb-mpy and mtb-only

Example (authored — no shipped call site)

__attribute__((used))
static void bento_ex_nus_agent_buffer_len(void)
{
    size_t buffered = nus_agent_buffer_len();
    if (buffered == 0u) {
        return;                        /* idle — no ask streaming          */
    }
    /* Streaming in progress: e.g. surface a token-count spinner on the
     * ASK submode while the desktop LLM streams deltas. */
}