Skip to content

Boot-prompt pointers

A boot-prompt pointer names the compiled boot prompt that an Agent, an installed Agent or a worker should be started from. You set it with one mutation, clear it with the same mutation, and read it back on the object it belongs to. For the boot briefing a worker is started with, see Teams, workers, and sessions.

Status: the setters and the two read fields are built on hadron-server from #2219 (issue #2045). This page is written from that merged code and the GraphQL schema, not from a run. Nothing is served from a pointer yet. Serving, the refusals that come with it and the retirement of the old prompt fields wait for a later server slice, so setting a pointer today changes what is stored and read back, not what an agent is started with. Compiling a boot prompt is not built yet either, so there is no compiled prompt for a pointer to name until it is.

Who may set one

Only a manager, acting as themselves.

Pointer Who may set it
Agent the Agent's manager
Installed Agent (one App) the App's manager
Worker the App's manager. Holding the worker grants nothing.

These callers are refused:

  • A request bound to a worker session, including the manager's own, is refused with BOOT_PROMPT_POINTER_SESSION_REFUSED. So is a request with an ambiguous multi-session binding, or a named session that failed to validate. A worker never sets a pointer; its manager does it without a session.
  • An App key, an impersonation, a run, or a caller who does not manage the object is refused with FORBIDDEN.

The order of the checks. The owner is resolved first, through its own read gate. Then the caller's authority over it is checked, and only after that is the target node looked at, so a refused caller learns nothing about the target. An owner you cannot read, or that is gone, answers its usual not-found before any FORBIDDEN (table below).

There is no MCP tool that sets a pointer. Use GraphQL.

The three setters

Each takes the owner and nodeRef, a node id or a fully-qualified node URN, and returns the updated owner.

setAgentBootPrompt(agentRef: String!, nodeRef: String): Agent!
setAppAgentBootPrompt(appRef: String!, agentRef: String!, nodeRef: String): AppAgent!
setWorkerBootPrompt(workerRef: ID!, nodeRef: String): Worker!
  • nodeRef: null clears the pointer. Leaving nodeRef out is refused with BAD_USER_INPUT, so a clear is always deliberate.
  • The node must be a compiled boot prompt. It does not have to be approved to be pointed at; approval is checked when a prompt is served.
  • Where the node must live:
Pointer The compiled prompt must be in
Agent that Agent's own system memory (not a base Agent's, not another's)
Installed Agent, worker the App's install memory for that Agent

workerRef is the worker's id or URN. A worker pointer is for customised workers.

Refusals

Code Meaning
BOOT_PROMPT_POINTER_SESSION_REFUSED The request is bound to a worker session.
BOOT_PROMPT_POINTER_NOT_FOUND About the target node, not the owner. No compiled boot prompt you can read has that ref. A missing, a deleted and an unreadable node all answer this, so it never says whether a hidden node exists.
BOOT_PROMPT_POINTER_NOT_COMPILED The node is not a compiled boot prompt (for example, its source).
BOOT_PROMPT_POINTER_WRONG_ROLE The node does not have the boot-prompt role.
BOOT_PROMPT_POINTER_WRONG_MEMORY The node is in the wrong memory for this kind of pointer (table above).
AGENT_NOT_FOUND setAgentBootPrompt: no such Agent, or one you cannot read. setAppAgentBootPrompt: the Agent is missing or not installed in that App.
APP_NOT_FOUND setAppAgentBootPrompt: an App you do not participate in, or one that is deleted or uninstalled.
WORKER_NOT_FOUND setWorkerBootPrompt: no such worker, or one you cannot read.
FORBIDDEN The owner is readable, but the caller is not a manager acting as themselves.
BAD_USER_INPUT nodeRef was omitted, or does not parse as a node id or URN.

Reading a pointer

Each of Agent, AppAgent and Worker has two read fields.

Field Value
bootPromptRef The canonical URN of the compiled prompt the pointer names now. A node that was moved shows its new URN; one that was hard-deleted shows the URN it had when the pointer was set.
bootPromptTargetDeleted true if the target is deleted (soft or hard) or its memory is deleted, false if it is live.

null means "not shown", not "no prompt". Both fields are null when no pointer is set and when you are not allowed to see it, so a null is never proof that no pointer exists. Who may see each:

On Visible to
Agent a caller who may read that Agent's system memory
AppAgent the App's participants
Worker callers behind the worker read gate (it is working state)