Package io.meeds.mcp.server.model

Record Class ActingIdentity

java.lang.Object
java.lang.Record
io.meeds.mcp.server.model.ActingIdentity
Record Components:
actor - the account that executes the call
onBehalfOf - the person the work is for, null when an agent acts as itself
chain - the agent name ids from the entry point to the agent making the call, never null, possibly empty
origin - what triggered the call
grantScope - what the standing-approval lookup matches against: an agent name id, or a source scope holding ":"; null for none
public record ActingIdentity(PrincipalRef actor, String onBehalfOf, List<String> chain, Origin origin, String grantScope) extends Record
Who executes a tool call, for whom, through which agents, and on which trigger. Immutable, and built only by platform code: a value an external client, a model or a tool argument sends never becomes one.

The account whose permissions apply to the call is the subject(): the person the work is for, or the agent account itself when an agent acts as itself. A call never combines two accounts' permissions. An agent account acting for a person is a combination no entry point produces yet, so it is refused at construction.

  • Field Details

    • SOURCE_SCOPE_SEPARATOR

      public static final String SOURCE_SCOPE_SEPARATOR
      What a source scope holds, and an agent name id never does.
      See Also:

    • SCHEDULE_SCOPE_PREFIX

      public static final String SCHEDULE_SCOPE_PREFIX
      The prefix of the grant scope of a scheduled agent run.
      See Also:

    • AGENT_USER_SCOPE_PREFIX

      public static final String AGENT_USER_SCOPE_PREFIX
      The prefix of the grant scope of an agent account acting as itself.
      See Also:

  • Constructor Details

    • ActingIdentity

      public ActingIdentity(PrincipalRef actor, String onBehalfOf, List<String> chain, Origin origin, String grantScope)
      Checks the identity is complete and holds a combination some entry point produces, and freezes its chain.
      Parameters:
      actor - the account that executes the call
      onBehalfOf - the person the work is for, or null
      chain - the agents from the entry point to the calling one
      origin - what triggered the call
      grantScope - the standing-approval scope, or null
      Throws:
      IllegalArgumentException - when a part is missing, a chain element is not an agent name id, a person acts for someone else, or an agent account acts for a person

  • Method Details

    • person

      public static ActingIdentity person(String username, Origin origin)
      Parameters:
      username - the person
      origin - what triggered the call
      Returns:
      the person acting for themself, with no agent in the chain and no grant scope

    • agent

      public static ActingIdentity agent(String username, String agentNameId, Origin origin)
      Parameters:
      username - the agent account's login
      agentNameId - the agent it is the account of
      origin - what triggered the call
      Returns:
      the agent account acting as itself, the agent alone in the chain, its grants matched by the scope "agent-user:" followed by its name id

    • external

      public static ActingIdentity external(String username)
      Parameters:
      username - the user the external client's token names
      Returns:
      that user acting for themself through an external MCP client

    • withHop

      public ActingIdentity withHop(String agentNameId)
      The only derivation of the chain: an agent appended at its end. The actor, the person the work is for and the origin are kept.
      Parameters:
      agentNameId - the agent that now makes the calls
      Returns:
      the identity with the agent appended, whose grant scope is that agent unless this identity carries a source scope, which is kept
      Throws:
      IllegalArgumentException - when the name id is blank or holds ":"

    • withGrantScope

      public ActingIdentity withGrantScope(String scope)
      Sets the standing-approval scope, and derives the origin from it whatever the origin was: a scope starting with "schedule:" is a scheduled run, any other scope holding ":" another unattended source, and a bare agent name id leaves the origin as it is.
      Parameters:
      scope - the grant scope, null for none
      Returns:
      the identity with that scope and the origin it implies

    • subject

      public String subject()
      Returns:
      the account whose permissions apply to the call: the person the work is for, else the actor itself

    • callingAgent

      public String callingAgent()
      Returns:
      the agent making the call, the last of the chain, or null when no agent calls

    • isSourceScope

      public boolean isSourceScope()
      Returns:
      true when the grant scope names a source rather than an agent

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • actor

      public PrincipalRef actor()
      Returns the value of the actor record component.
      Returns:
      the value of the actor record component

    • onBehalfOf

      public String onBehalfOf()
      Returns the value of the onBehalfOf record component.
      Returns:
      the value of the onBehalfOf record component

    • chain

      public List<String> chain()
      Returns the value of the chain record component.
      Returns:
      the value of the chain record component

    • origin

      public Origin origin()
      Returns the value of the origin record component.
      Returns:
      the value of the origin record component

    • grantScope

      public String grantScope()
      Returns the value of the grantScope record component.
      Returns:
      the value of the grantScope record component