aos-mcp: caller unavailable for

Error message

aos-mcp: caller unavailable for {expected_host} hook: {error}

What it means

After parsing a host hook request, `handle` asks the runtime for the caller identity. If runtime::caller() fails, the hook is rejected as `caller_unavailable`, a warning is logged, and processing stops with Ok(()). The capsule cannot authenticate the hook without a caller, so it refuses rather than guess.

Solutions

Invoke the hook through the host bridge so the runtime can supply a caller identity.
Check the runtime/binding version supports caller metadata for hook ingress.
Read the logged error for the underlying cause (e.g. missing context) and fix the invocation environment.

Example fix

// before (tooling)
direct_call(capsule, "hook_ingress", payload)
// after
via_host_bridge(capsule, host, payload) // host supplies caller identity

Defensive patterns

Strategy: try-catch

Try / catch

match runtime::caller() {
    Ok(caller) => proceed(caller),
    Err(e) => { reject(host, event, "caller_unavailable"); log::warn!("caller unavailable: {e}"); }
}

Prevention

Always invoke hooks via the host bridge, never direct entry-point calls from tooling.
Pin runtime and bridge versions that propagate caller metadata.
Alert on caller_unavailable rejections — they usually indicate an out-of-band invocation.

When it happens

Trigger: runtime::caller() returns Err while handling a host hook — e.g. the hook was invoked outside a proper host-initiated call context or the runtime lacks caller metadata.

Common situations: Invoking the hook entry point directly from tooling instead of through the host, running on a runtime version that does not populate caller info, or a misconfigured host binding.

Related errors

AI-assisted analysis of unicity-aos/aos-ce@f6f22024fb (2026-09-13). Data as JSON: /api/errors/f8bb71c184f32d2d. Report an issue: GitHub.

Appendix: source

Thrown at capsules/capsule-mcp/src/host_hooks.rs:84

        Ok(request) => request,
        Err(error) => {
            reject(expected_host, "unknown", "malformed_payload");
            log::warn(format!(
                "aos-mcp: malformed {expected_host} hook ingress: {error}"
            ));
            return Ok(());
        }
    };
    if let Err(reason) = validate_request(expected_host, &request) {
        reject(expected_host, &request.event, reason);
        return Ok(());
    }

    let caller = match runtime::caller() {
        Ok(caller) => caller,
        Err(error) => {
            reject(expected_host, &request.event, "caller_unavailable");
            log::warn(format!(
                "aos-mcp: caller unavailable for {expected_host} hook: {error}"
            ));
            return Ok(());
        }
    };
    if caller.principal.as_deref() != Some(request.principal_id.as_str()) {
        reject(expected_host, &request.event, "principal_mismatch");
        return Ok(());
    }

    let token_key = token_key(expected_host, &request.session_id);
    if !authenticate_token(&token_key, &request)? {
        reject(expected_host, &request.event, "token_mismatch");
        return Ok(());
    }

    ipc::publish_json(
        &format!("oracle.v1.hook.validated.{expected_host}"),

View on GitHub (pinned to f6f22024fb)