Interface: PreUserMessageContext

Makaio Framework

---

Makaio Framework / hooks / PreUserMessageContext

Interface: PreUserMessageContext

Defined in: ../../../packages/hooks/src/types/hook-context.ts:121

PreUserMessage context with enriched session data.

Intercepts: AgentSubjects.sendMessage RPC via request middleware

When sessionId is present in SendMessageRequest, the context builder queries the bus to populate session, recentHistory, and project fields. Without sessionId, these fields remain undefined/empty (hooks may fire before a session is established).

Extends

• RequestHookContext<PreUserMessagePayload>.SessionHookContext

Indexable

[key: string]: unknown

Properties

bus

readonly bus: IMakaioBus

Defined in: ../../../packages/hooks/src/types/hook-context.ts:76

Bus instance for making requests

Inherited from

SessionHookContext.bus

---

contextExtensions

readonly contextExtensions: Record<string, unknown>

Defined in: ../../../packages/hooks/src/types/hook-context.ts:82

Arbitrary context extensions contributed by the host-registered SessionSubjects.enrichContext handler. Framework spreads these onto the context object at hook-call time. Empty object in OSS mode.

Inherited from

SessionHookContext.contextExtensions

---

correlationId?

readonly optional correlationId?: string

Defined in: ../../../packages/hooks/src/types/hook-context.ts:41

Correlation identifier for tracing (optional)

Inherited from

RequestHookContext.correlationId

---

hookEvent

readonly hookEvent: "PreUserMessage"

Defined in: ../../../packages/hooks/src/types/hook-context.ts:122

---

messageId?

readonly optional messageId?: string

Defined in: ../../../packages/hooks/src/types/hook-context.ts:39

Message identifier (optional - may not be present if not provided by caller)

Inherited from

RequestHookContext.messageId

---

payload

readonly payload: PreUserMessagePayload

Defined in: ../../../packages/hooks/src/types/hook-context.ts:37

The request payload (readonly via getter, mutable via replacePayload)

Inherited from

RequestHookContext.payload

---

recentHistory

readonly recentHistory: object[]

Defined in: ../../../packages/hooks/src/types/hook-context.ts:74

Recent turn history, oldest first (up to 10 turns)

completedAt?

optional completedAt?: number

Turn completion timestamp (Unix ms)

error?

optional error?: string

Error message if status is ‘error’

sessionId

sessionId: string

Session this turn belongs to

startedAt

startedAt: number

Turn start timestamp (Unix ms)

status

status: "error" | "completed" | "active" = TurnStatusSchema

Turn status

turnId

turnId: string

Unique turn identifier

turnNumber

turnNumber: number

Monotonic per-session ordinal (1-based), assigned by turn storage at creation.

usage?

optional usage?: object

Aggregated usage/cost for this turn. Populated on turn completion.

usage.byAgent?

optional byAgent?: Record<string, { cost?: number; inputTokens: number; outputTokens: number; }>

Optional per-agent breakdown (for multi-agent turns)

usage.total

total: object = UsageMetricsSchema

Total aggregated usage across all agents

usage.total.cost?

optional cost?: number

Computed cost in USD (optional, requires pricing data)

usage.total.inputTokens

inputTokens: number

Input tokens consumed

usage.total.outputTokens

outputTokens: number

Output tokens generated

Inherited from

SessionHookContext.recentHistory

---

session?

readonly optional session?: IMakaioSession

Defined in: ../../../packages/hooks/src/types/hook-context.ts:72

Session object (populated when sessionId is available)

Inherited from

SessionHookContext.session

Methods

abort()

abort(reason?): never

Defined in: ../../../packages/hooks/src/types/hook-context.ts:139

Abort message processing. Throws HookAbortError.

Parameters

reason?

string

Returns

never

---

getTurnContext()

getTurnContext(): Record<string, JsonValue>

Defined in: ../../../packages/hooks/src/types/hook-context.ts:137

Get turn context set by THIS hook instance. Returns only context set via setTurnContext() in this handler. Context from earlier hooks is merged separately after handler completes.

Returns

Record<string, JsonValue>

Turn context values set by this hook instance only

---

next()

next(): Promise<void>

Defined in: ../../../packages/hooks/src/types/hook-context.ts:54

Continue to the next handler in the middleware chain.

Returns

Promise<void>

Inherited from

RequestHookContext.next

---

replacePayload()

replacePayload(newPayload): void

Defined in: ../../../packages/hooks/src/types/hook-context.ts:50

Replace the payload with a new value. Subsequent handlers in the middleware chain will receive the new payload.

Note: Only message and sessionContext can be replaced. Routing fields (agentId, adapterId, sessionId, messageId, deliveryMode) are intentionally immutable to preserve message routing integrity.

Parameters

newPayload

Partial<P>

Returns

void

Inherited from

RequestHookContext.replacePayload

---

setTurnContext()

setTurnContext(key, value): void

Defined in: ../../../packages/hooks/src/types/hook-context.ts:130

Set turn context for downstream consumers. Uses replacePayload() to add context to sessionContext.turnContext. Value must be JSON-serializable.

Parameters

key

string

Turn context key to write (e.g. ‘guides’, ‘cwdChange’)

value

JsonValue

JSON-serializable value to store under the key

Returns

void