Skip to content

IPC Methods

Complete reference for all kernel IPC methods.

App Lifecycle

app.register

Register an app with the kernel.

Request:

{
  manifest: PackageManifest;
}

Response:

{
  appId: string;
  token: string;
  protocolVersion: string;
}

app.heartbeat

Health check ping.

Request:

{
  status?: Record<string, unknown>
}

Response:

{
  ok: boolean;
  serverTime: number;
}

app.ready

Signal app is ready for traffic.

Request:

{
  metadata?: Record<string, unknown>
}

Response:

{
  ok: boolean;
}

app.shutdown

Graceful shutdown notification.

Request:

{
  reason?: string;
  timeout?: number;
}

Response:

{
  ok: boolean;
}

Capability Registration

capability.register

Register a capability.

Request:

{
  type: "channel" | "tool" | "hook" | "gateway_method" | "http_route" | "provider";
  config: unknown;
}

Response:

{
  capabilityId: string;
  granted: boolean;
  reason?: string;
}

capability.unregister

Remove a capability.

Request:

{
  capabilityId: string;
}

Response:

{
  ok: boolean;
}

Hooks

hook.subscribe

Subscribe to hook events.

Request:

{
  events: string[];
}

Response:

{
  subscribed: string[];
  denied: string[];
}

hook.unsubscribe

Unsubscribe from hooks.

Request:

{
  events: string[];
}

Response:

{
  unsubscribed: string[];
}

hook.result

Return result for intercepting hook.

Request:

{
  eventId: string;
  result: unknown;
}

Response:

{
  ok: boolean;
}

Configuration

config.get

Get configuration value.

Request:

{
  path?: string;
}

Response:

{
  value: unknown;
}

config.watch

Watch for config changes (streaming).

Request:

{
  paths?: string[];
}

Stream chunks:

{
  path: string;
  oldValue: unknown;
  newValue: unknown;
}

Sessions

session.get

Get session info.

Request:

{
  key: string;
}

Response:

{
  session: {
    key: string;
    agentId: string;
    channelId?: string;
    accountId?: string;
    createdAt: number;
    lastActiveAt: number;
    messageCount: number;
  } | null;
}

session.list

List sessions.

Request:

{
  filter?: {
    agentId?: string;
    channelId?: string;
    accountId?: string;
    active?: boolean;
  };
  limit?: number;
  offset?: number;
}

Response:

{
  sessions: SessionEntry[];
  total: number;
}

Messages

message.dispatch

Dispatch a message.

Request:

{
  sessionKey: string;
  content: string;
  metadata?: Record<string, unknown>;
}

Response:

{
  dispatchId: string;
  queued: boolean;
}

Agent

agent.queue

Queue a message for agent processing.

Request:

{
  sessionKey: string;
  text: string;
  metadata?: Record<string, unknown>;
}

Response:

{
  runId: string;
  queued: boolean;
}

Error Codes

Code Description
UNKNOWN_ERROR Unspecified error
INVALID_REQUEST Malformed request
METHOD_NOT_FOUND Unknown method
INVALID_PARAMS Invalid parameters
INTERNAL_ERROR Kernel internal error
UNAUTHORIZED Auth required
FORBIDDEN Permission denied
NOT_FOUND Resource not found
CONFLICT Resource conflict
TIMEOUT Operation timeout
APP_NOT_REGISTERED Must register first
CAPABILITY_DENIED Capability not granted
HOOK_NOT_SUBSCRIBED Hook subscription needed
CONNECTION_CLOSED Connection closed

Next Steps