Package com.tnsai.security

Class InvocationContext

java.lang.Object

com.tnsai.security.InvocationContext

public final class InvocationContext
extends Object

Trusted interaction provenance, separate from executing agent and executor principal. Root factories belong to host ingress, not model arguments or arbitrary request fields. USER denotes an interaction category, not an authenticated account. This API is not a JVM sandbox.

An invocation may carry the AgentPrincipal its dispatches are attributed to. A host that serves several agents or conversations from one executor passes it here, per call, instead of wiring it on the shared executor; a dispatch reads the invocation's principal and falls back to the executor's wired one only when the invocation carries none.

Method Summary

Modifier and Type	Method	Description
AccessSubject	actor()
List<AuthorityScope>	authorities()
static InvocationContext	autonomous(AccessSubject executingAgent, String executorId, AuthorityScope authority)	Use only for the actual agent's own initiative, never for forwarded or human work.
static InvocationContext	autonomous(AccessSubject executingAgent, String executorId, AuthorityScope authority, AgentPrincipal principal)	autonomous(AccessSubject, String, AuthorityScope) whose dispatches are attributed to principal.
String	cachePartition()
<T> T	call(Callable<T> task)
Set<ExecutionCaller>	callers()
static Optional<InvocationContext>	current()
InvocationContext	delegateTo(AccessSubject nextAgent, String nextExecutorId, AuthorityScope nextAuthority)	Trusted host transfer to the actual recipient agent.
static AgentPrincipal	dispatchPrincipal(AgentPrincipal wired)	The principal a dispatch running now is attributed to: the current invocation's, or wired when no invocation is active or it carries none.
AccessSubject	executingAgent()
String	executorId()
List<AccessSubject>	onBehalfOf()
static InvocationContext	otherAgent(AccessSubject callerAgent, AccessSubject executingAgent, String executorId, AuthorityScope authority)	Trusted peer ingress.
static InvocationContext	otherAgent(AccessSubject callerAgent, AccessSubject executingAgent, String executorId, AuthorityScope authority, AgentPrincipal principal)	otherAgent(AccessSubject, AccessSubject, String, AuthorityScope) whose dispatches are attributed to principal.
Optional<AgentPrincipal>	principal()	The executor principal this invocation's dispatches are attributed to, if the host gave one.
void	run(Runnable task)
List<AccessSubject>	subjects()
static InvocationContext	unknown(String executorId)	Carries an unclassified ingress without granting any execution category.
static InvocationContext	user(AccessSubject human, AccessSubject executingAgent, String executorId, AuthorityScope authority)	Host-owned human interaction boundary; the subject may be a stable anonymous chat identity.
static InvocationContext	user(AccessSubject human, AccessSubject executingAgent, String executorId, AuthorityScope authority, AgentPrincipal principal)	user(AccessSubject, AccessSubject, String, AuthorityScope) whose dispatches are attributed to principal.
static Runnable	wrap(Runnable task)
static <T> Callable<T>	wrap(Callable<T> task)	Captures the current provenance and restores worker state on success, failure or cancellation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

user

public static InvocationContext user(AccessSubject human,
 AccessSubject executingAgent,
 String executorId,
 AuthorityScope authority)

Host-owned human interaction boundary; the subject may be a stable anonymous chat identity. Stored @Idempotent results are shared by everyone presenting the same subjects, roles, origin, agent and executor, so a subject id must name one principal: a single anonymous id shared by many people lets them read each other's cached results.

user

public static InvocationContext user(AccessSubject human,
 AccessSubject executingAgent,
 String executorId,
 AuthorityScope authority,
 AgentPrincipal principal)

user(AccessSubject, AccessSubject, String, AuthorityScope) whose dispatches are attributed to principal.

Parameters:

principal - the executor principal for this invocation's dispatches, or null for the executor's wired one

Since:

0.18.6

autonomous

public static InvocationContext autonomous(AccessSubject executingAgent,
 String executorId,
 AuthorityScope authority)

Use only for the actual agent's own initiative, never for forwarded or human work.

autonomous

public static InvocationContext autonomous(AccessSubject executingAgent,
 String executorId,
 AuthorityScope authority,
 AgentPrincipal principal)

autonomous(AccessSubject, String, AuthorityScope) whose dispatches are attributed to principal.

Parameters:

principal - the executor principal for this invocation's dispatches, or null for the executor's wired one

Since:

0.18.6

otherAgent

public static InvocationContext otherAgent(AccessSubject callerAgent,
 AccessSubject executingAgent,
 String executorId,
 AuthorityScope authority)

Trusted peer ingress. For an existing invocation use delegateTo to preserve its origin.

otherAgent

public static InvocationContext otherAgent(AccessSubject callerAgent,
 AccessSubject executingAgent,
 String executorId,
 AuthorityScope authority,
 AgentPrincipal principal)

otherAgent(AccessSubject, AccessSubject, String, AuthorityScope) whose dispatches are attributed to principal.

Parameters:

principal - the executor principal for this invocation's dispatches, or null for the executor's wired one

Since:

0.18.6

unknown

public static InvocationContext unknown(String executorId)

Carries an unclassified ingress without granting any execution category.

cachePartition

public String cachePartition()

actor

public AccessSubject actor()

executingAgent

public AccessSubject executingAgent()

onBehalfOf

public List<AccessSubject> onBehalfOf()

executorId

public String executorId()

callers

public Set<ExecutionCaller> callers()

authorities

public List<AuthorityScope> authorities()

principal

public Optional<AgentPrincipal> principal()

The executor principal this invocation's dispatches are attributed to, if the host gave one.

Since:

0.18.6

dispatchPrincipal

public static AgentPrincipal dispatchPrincipal(AgentPrincipal wired)

The principal a dispatch running now is attributed to: the current invocation's, or wired when no invocation is active or it carries none. Every check of one dispatch reads it here.

Parameters:

wired - the executor's host-wired principal, or null

Returns:

the principal, or null when neither gives one

Since:

0.18.6

subjects

public List<AccessSubject> subjects()

current

public static Optional<InvocationContext> current()

delegateTo

public InvocationContext delegateTo(AccessSubject nextAgent,
 String nextExecutorId,
 AuthorityScope nextAuthority)

Trusted host transfer to the actual recipient agent. The departing agent is derived from this context, never supplied by the caller. Every prior authority and subject remains. A USER peer hop requires USER and OTHER_AGENT; peer work can never become SELF again. A hop to the same agent keeps this invocation's principal; a peer hop drops it, so the recipient's dispatches are attributed to the recipient executor's own wired principal.

call

public <T> T call(Callable<T> task)
           throws Exception

Throws:

Exception

run

public void run(Runnable task)

wrap

public static <T> Callable<T> wrap(Callable<T> task)

Captures the current provenance and restores worker state on success, failure or cancellation.

wrap

public static Runnable wrap(Runnable task)