client

client

Field	Value
Prefix	client
Namespace constant	ClientNamespace
Subjects constant	ClientSubjects
Kind	bus
Schema record	ClientSchemas
Tier	framework
Package	@makaio/contracts
Defined in	packages/contracts/src/client/namespace.ts

Subjects

Key	Wire	Type	Schema
account.observe	client.account.observe	rpc	account-identity.ts
install	client.install	rpc	binary-management.ts
installJob.completed	client.installJob.completed	event	binary-management.ts
installJob.progress	client.installJob.progress	event	binary-management.ts
list	client.list	rpc	binary-management.ts
resolveBinary	client.resolveBinary	rpc	binary-resolution.ts
runtime.observe	client.runtime.observe	rpc	runtime-observation.ts
runtime.started	client.runtime.started	event	runtime-observation.ts
scan	client.scan	rpc	schemas.ts
session.account.observe	client.session.account.observe	rpc	account-identity.ts
session.started	client.session.started	event	session-observed.ts
session.tool.post	client.session.tool.post	event	session-observed.ts
session.tool.pre	client.session.tool.pre	event	session-observed.ts
session.turn.completed	client.session.turn.completed	event	session-observed.ts
session.turn.started	client.session.turn.started	event	session-observed.ts
session.userPrompt.submitted	client.session.userPrompt.submitted	event	session-observed.ts
setActive	client.setActive	rpc	binary-management.ts
uninstall	client.uninstall	rpc	binary-management.ts
update	client.update	rpc	binary-management.ts
usage.ingest	client.usage.ingest	rpc	account-identity.ts
usage.snapshot	client.usage.snapshot	event	account-identity.ts
version.changed	client.version.changed	event	binary-management.ts
wiring.list	client.wiring.list	rpc	schemas.ts

Subject Details

client.account.observe (rpc)

Request and response schemas for client.account.observe.

Subject: client.account.observe Type: Request (RPC)

Request:

Field	Type	Required
clientId	string	yes
displayLabel	string | undefined	no
identifiers	{ scheme: string; value: string; strength: "strong" | "alias"; }[]	yes
metadata	Record<string, unknown> | undefined	no
observedAt	number | undefined	no

Response:

Field	Type	Required
clientAccountId	string	yes
displayLabel	string | undefined	no

client.install (rpc)

Request and response schemas for client.install.

Enqueues a background install job for a managed client binary. Callers can track progress via client.installJob.progress and client.installJob.completed events using the returned jobId.

Subject: client.install Type: Request (RPC)

Request:

Field	Type	Required
clientId	string	yes
version	string | undefined	no

Response:

Field	Type	Required
jobId	string	yes
requestedVersion	string | null	yes
resolvedVersion	string | null	yes

client.installJob.completed (event)

Event payload for client.installJob.completed.

Emitted once by the install job runner when the pipeline finishes, regardless of outcome. Listeners should check status before acting.

Subject: client.installJob.completed Type: Event

Field	Type	Required
activeVersion	string | null	yes
clientId	string	yes
error	{ message: string; code?: string | undefined; } | undefined	no
installPath	string | undefined	no
jobId	string	yes
metadata	Record<string, unknown> | undefined	no
status	"success" | "error"	yes
strategy	"manifest-bucket" | "npm" | "github-release"	yes
version	string | undefined	no

client.installJob.progress (event)

Event payload for client.installJob.progress.

Emitted by the install job runner at each pipeline stage transition and whenever the download progress percentage changes materially.

Subject: client.installJob.progress Type: Event

Field	Type	Required
activeAfterCompletion	boolean | undefined	no
clientId	string	yes
installPath	string | undefined	no
jobId	string	yes
metadata	Record<string, unknown> | undefined	no
progress	number | null	yes
stage	"downloading" | "resolving" | "verifying" | "extracting" | "installing" | "post-install" | "activating"	yes
strategy	"manifest-bucket" | "npm" | "github-release"	yes
version	string | undefined	no

client.list (rpc)

Request and response schemas for client.list.

Returns the local installation inventory for all managed clients, enriched with the latest-available-version from the upstream index.

Subject: client.list Type: Request (RPC)

Request:

Field	Type	Required
forceRefresh	boolean | undefined	no

Response:

Field	Type	Required
clients	{ clientId: string; installedVersions: { version: string; installPath: string; installedAt: number; isActive: boolean; }[]; activeVersion: string | null; latestAvailableVersion: string | null; latestVersionLastCheckedAt: number | null; latestVersionSourceStatus: "error" | "fresh" | "cached"; updateAvailable: boolean; }[]	yes

client.resolveBinary (rpc)

Request and response schemas for client.resolveBinary.

Resolves the binary path, environment overrides, and config directory for a given client. The response is everything a caller needs to spawn the binary.

Phase 2 optional fields (sessionId, projectDir, preferSource, harnessId) are declared now as seams so the handler contract is stable before the implementations land.

Subject: client.resolveBinary Type: Request (RPC)

Request:

Field	Type	Required
clientId	string	yes
harnessId	string | undefined	no
preferSource	"global" | "managed" | undefined	no
projectDir	string | undefined	no
sessionId	string | undefined	no

Response:

Field	Type	Required
binaryPath	string | null	yes
configDir	string | null	yes
env	Record<string, string>	yes
source	"global" | "managed"	yes
version	string | null	yes

client.runtime.observe (rpc)

Request and response schemas for client.runtime.observe.

Callers send this request when they detect that a client runtime has started. The handler upserts a ClientRuntime record and returns a stable clientRuntimeId together with flags indicating whether the record was created or promoted to a richer state.

Hard-evidence invariant: at least one of supervisorSessionId, pid, or adapterSessionId must be present. Enforced via .refine() on the request schema (not on the shared evidence base, which stays composable).

Subject: client.runtime.observe Type: Request (RPC)

Request:

Field	Type	Required
adapterSessionId	string | undefined	no
argv	string[] | undefined	no
clientId	string	yes
cwd	string | undefined	no
metadata	Record<string, unknown> | undefined	no
observedAt	number	yes
parentPid	number | undefined	no
pid	number | undefined	no
sessionId	string | undefined	no
source	{ layer: "adapter" | "supervisor" | "client-hook" | "statusline" | "cli-wrapper"; producer: string; }	yes
supervisorSessionId	string | undefined	no

Response:

Field	Type	Required
clientRuntimeId	string	yes
created	boolean	yes
promoted	boolean	yes

client.runtime.started (event)

Payload for client.runtime.started.

Emitted by the runtime-observe service after a client.runtime.observe request has been handled and a runtime record has been created or confirmed. Listeners can react to this event without coupling to the observe handler.

Hard-evidence invariant: at least one of supervisorSessionId, pid, or adapterSessionId is present (guaranteed by the observe handler before emit).

Subject: client.runtime.started Type: Event

Field	Type	Required
adapterSessionId	string | undefined	no
argv	string[] | undefined	no
clientId	string	yes
clientRuntimeId	string	yes
cwd	string | undefined	no
metadata	Record<string, unknown> | undefined	no
observedAt	number	yes
parentPid	number | undefined	no
pid	number | undefined	no
sessionId	string | undefined	no
source	{ layer: "adapter" | "supervisor" | "client-hook" | "statusline" | "cli-wrapper"; producer: string; }	yes
status	"started" | "observed"	yes
supervisorSessionId	string | undefined	no

client.scan (rpc)

Subject: client.scan Type: Request (RPC)

Request:

Field	Type	Required
targets	{ clientId: string; binaryName: string; minimumVersion?: string | undefined; }[] | undefined	no

Response:

Field	Type	Required
results	{ clientId: string; found: boolean; version?: string | undefined; warningMessage?: string | undefined; }[]	yes

client.session.account.observe (rpc)

Request and response schemas for client.session.account.observe.

Subject: client.session.account.observe Type: Request (RPC)

Request:

Field	Type	Required
clientId	string	yes
kind	string	yes
locator	{ kind: "session"; sessionId: string; } | { kind: "adapter-session"; adapterSessionId: string; } | { kind: "both"; sessionId: string; adapterSessionId: string; }	yes
observedAt	number	yes
payload	Record<string, unknown>	yes
source	string	yes

Response:

Field	Type	Required
changed	boolean	yes
clientAccountId	string | null	yes
handled	boolean	yes
sessionId	string | null	yes

client.session.started (event)

Payload for client.session.started.

Emitted when an adapter observes that a new client session has begun. This is a normalized observed signal — not a command. The session may not yet be linked to a framework session at emission time.

Subject: client.session.started Type: Event

Field	Type	Required
adapterSessionId	string | undefined	no
clientId	string	yes
metadata	Record<string, unknown> | undefined	no
observedAt	number	yes
sessionId	string | undefined	no
source	string	yes

client.session.tool.post (event)

Payload for client.session.tool.post.

Emitted when an adapter observes that a tool call has completed inside the client runtime. The success field reflects the outcome when the adapter can determine it.

Subject: client.session.tool.post Type: Event

Field	Type	Required
adapterSessionId	string | undefined	no
clientId	string	yes
metadata	Record<string, unknown> | undefined	no
observedAt	number	yes
sessionId	string | undefined	no
source	string	yes
success	boolean | undefined	no
toolCallId	string | undefined	no
toolName	string | undefined	no

client.session.tool.pre (event)

Payload for client.session.tool.pre.

Emitted when an adapter observes that a tool call is about to be executed by the client runtime. The toolName and toolCallId fields identify the specific invocation when the adapter has access to them.

Subject: client.session.tool.pre Type: Event

Field	Type	Required
adapterSessionId	string | undefined	no
clientId	string	yes
metadata	Record<string, unknown> | undefined	no
observedAt	number	yes
sessionId	string | undefined	no
source	string	yes
toolCallId	string | undefined	no
toolName	string | undefined	no

client.session.turn.completed (event)

Payload for client.session.turn.completed.

Emitted when an adapter observes that an assistant turn has finished inside an ongoing client session.

Subject: client.session.turn.completed Type: Event

Field	Type	Required
adapterSessionId	string | undefined	no
clientId	string	yes
metadata	Record<string, unknown> | undefined	no
observedAt	number	yes
sessionId	string | undefined	no
source	string	yes

client.session.turn.started (event)

Payload for client.session.turn.started.

Emitted when an adapter observes the beginning of an assistant turn inside an ongoing client session.

Subject: client.session.turn.started Type: Event

Field	Type	Required
adapterSessionId	string | undefined	no
clientId	string	yes
metadata	Record<string, unknown> | undefined	no
observedAt	number	yes
sessionId	string | undefined	no
source	string	yes

client.session.userPrompt.submitted (event)

Payload for client.session.userPrompt.submitted.

Emitted when an adapter observes that the user has submitted a prompt to the client runtime. The prompt field carries the raw prompt text when the adapter has access to it.

Subject: client.session.userPrompt.submitted Type: Event

Field	Type	Required
adapterSessionId	string | undefined	no
clientId	string	yes
metadata	Record<string, unknown> | undefined	no
observedAt	number	yes
prompt	string | undefined	no
sessionId	string | undefined	no
source	string	yes

client.setActive (rpc)

Request and response schemas for client.setActive.

Switches the active binary pointer to an already-installed version. The requested version must be present on disk; the handler will reject requests for versions that have not been installed.

Subject: client.setActive Type: Request (RPC)

Request:

Field	Type	Required
clientId	string	yes
version	string	yes

Response:

Field	Type	Required
activeVersion	string	yes
clientId	string	yes

client.uninstall (rpc)

Request and response schemas for client.uninstall.

Removes a specific installed version of a managed client binary. If the removed version was active, the active pointer is cleared to null — no automatic replacement is made. Callers must explicitly call client.setActive to promote another installed version.

Subject: client.uninstall Type: Request (RPC)

Request:

Field	Type	Required
clientId	string	yes
version	string	yes

Response:

Field	Type	Required
activeVersion	string | null	yes
clientId	string	yes
removedVersion	string	yes

client.update (rpc)

Request and response schemas for client.update.

Enqueues an update job that installs the latest available version and activates it. Callers can track progress via client.installJob.progress and client.installJob.completed events using the returned jobId.

Subject: client.update Type: Request (RPC)

Request:

Field	Type	Required
clientId	string	yes

Response:

Field	Type	Required
jobId	string	yes
resolvedVersion	string | null	yes

client.usage.ingest (rpc)

Request and response schemas for client.usage.ingest.

Subject: client.usage.ingest Type: Request (RPC)

Request:

Field	Type	Required
account	{ identifiers: { scheme: string; value: string; strength: "strong" | "alias"; }[]; displayLabel?: string | undefined; }	yes
clientId	string	yes
metadata	Record<string, unknown> | undefined	no
observedAt	number	yes
source	string	yes
usage	{ windows: { key: string; label: string; usedPercentage: number; resetsAt?: number | undefined; }[]; }	yes

Response:

Field	Type	Required
clientAccountId	string	yes
snapshot	{ clientAccountId: string; clientId: string; observedAt: number; source: string; usage: { windows: { key: string; label: string; usedPercentage: number; resetsAt?: number | undefined; }[]; }; displayLabel?: string | undefined; metadata?: Record<string, unknown> | undefined; }	yes

client.usage.snapshot (event)

Canonical usage snapshot emitted after stitching identity and usage.

Subject: client.usage.snapshot Type: Event

Field	Type	Required
clientAccountId	string	yes
clientId	string	yes
displayLabel	string | undefined	no
metadata	Record<string, unknown> | undefined	no
observedAt	number	yes
source	string	yes
usage	{ windows: { key: string; label: string; usedPercentage: number; resetsAt?: number | undefined; }[]; }	yes

client.version.changed (event)

Event payload for client.version.changed.

Emitted whenever the active-version pointer for a managed client changes, regardless of the operation that caused the change.

Subject: client.version.changed Type: Event

Field	Type	Required
activeVersion	string | null	yes
clientId	string	yes
previousActiveVersion	string | null	yes
reason	"update" | "install" | "uninstall" | "set-active"	yes

client.wiring.list (rpc)

Subject: client.wiring.list Type: Request (RPC)

Request:

Field	Type	Required
clientId	string | undefined	no
makaioCommand	string	yes
projectDir	string | undefined	no

Response:

Field	Type	Required
results	{ clientId: string; entries: { group: string; name: string; installed: boolean; command: string; }[]; }[]	yes

---

Auto-generated by yarn docs:bus. Do not edit manually.